How to improve email security with a DKIM record

View as Markdown

Find out how to configure a DKIM record on your OVHcloud domain name and email service

Objective

The DKIM (DomainKeys Identified Mail) record allows you to sign emails to prevent identity fraud. This signature works on the principle of hashing combined with asymmetric cryptography.

This guide explains how DKIM works, and how to set it up for your email service.

Requirements

OVHcloud Control Panel Access

  • Lien direct :
  • Pour accéder à vos services : Web Cloud > Zones DNS > Sélectionnez votre nom de domaine
Warning

Si votre nom de domaine n'utilise pas les serveurs DNS d'OVHcloud, vous devez réaliser la modification du DKIM depuis l'interface du prestataire gérant la configuration de votre nom de domaine.

Si votre nom de domaine est déposé chez OVHcloud, vous pouvez vérifier si ce dernier utilise notre configuration OVHcloud dans votre depuis l'onglet Zone DNS, une fois le domaine concerné sélectionné.

If your domain name is registered with OVHcloud, you can check if it is using the OVHcloud configuration in your . To do this, go to the DNS zones tab, and select the domain concerned.

Instructions

Overview

How does DKIM work?

To understand why DKIM helps secure your email exchanges, it is necessary to understand how it works. DKIM uses hashing and asymmetric encryption to create a secure signature. The email platform and the DNS zone of your domain name will help transmit the DKIM information to your recipients.

Hashing

The principle of a hash function is to generate a signature (also called a fingerprint) from input data. Its purpose is to create a fixed sequence of characters at the output, regardless of the amount of input data.

On the following diagram, you can see that the output will always be 32 characters using a MD5 (Message Digest 5) hash algorithm, while the input text may vary in size. The slightest character variation in input data completely changes the output hash, making the output signature unpredictable and tamper-proof. In the example below, the input value is passed into the MD5 hash algorithm and the output is its hash value.

hash

The hash function is useful when you want to check the integrity of a message. Different but similar looking input data will produce a completely different hash value with an equal length of characters in output, regardless of the input length.

Asymmetric encryption

The purpose of encryption, as its name suggests, is to encrypt the data it is given. It is asymmetric because the encryption key is not the same as the decryption, unlike symmetric encryption, which uses the same key to encrypt and decrypt.

Asymmetric encryption uses a public key and a private key. The public key is visible and usable by everyone. The private key is only used by the holder and is not visible to all.

There are two uses for asymmetric encryption:

  • The input data is encrypted with the public key and decrypted by the holder of the private key. For example, you want a third party to send you data securely. You transmit your public key without worrying about someone getting it. This third party will encrypt their data with your public key. Encrypted data can only be decrypted by the private key holder.
hash
  • The input data is encrypted by the private key holder and decrypted by the public key. This use applies to authenticate a data exchange. For example, your recipients want to ensure that you are the author of the message you send them. In this case, you will encrypt your message with your private key. This message can only be decrypted by the public key that you have transmitted to everyone, which guarantees your recipients the authenticity of your message. A message decrypted by the public key can only come from the holder of the private key.
hash
How are hashing and asymmetric encryption used for DKIM?

From the email platform, DKIM will use hashing to create a signature from certain elements of the email header and email body (email content).

The signature is then encrypted with the private key using asymmetric encryption.

Why do we need to configure DNS servers?

In order for a recipient to verify the sender's DKIM signature, they will need the DKIM parameters and especially the public key to decrypt it. A domain name’s DNS zone is public, which is why a DNS record is added to transmit the public key and DKIM settings to the recipient.

What is a DKIM selector?

When you enable DKIM, it works with a public/private key pair. You can assign several pairs of keys to your domain name, for example, as part of a rotation. Indeed, when you change the key pair, the old pair must remain active until all emails you sent with the old key fail to pass the DKIM check on the incoming server.

For this rotation principle to work, we're going to use something called DKIM selectors. A DKIM selector includes a private/public key pair. It is visible as a character string in the DKIM signature of an email after the argument s=. This signature is visible in the email header.

Example of a DKIM signature part

DKIM-Signature: v=1; a=rsa-sha256; d=mydomain.ovh; s=ovhex123456-selector1; c=relaxed/relaxed; t=1681877341;

The value of this selector is s=ovhex123456-selector1.

Example of an email sent using DKIM

When you send an email from contact@mydomain.ovh, a signature encrypted with a private key is added to the email header.

The recipient recipient@otherdomain.ovh can decrypt this signature with the public key visible in the DNS zone of mydomain.ovh. The signature is created from the content of the email sent. This means that if the email is modified during transit, the signature will not match with the content and this will cause the DKIM check on the destination server to fail.

Automatically configure DKIM for an OVHcloud email offer

Automatic DKIM configuration is available for all our email offers:

When you configure your domain name on an OVHcloud email solution, automatic DKIM configuration is proposed and performed by default if you do not disable it.

If DKIM was not enabled when you added a domain name to your email platform, you will need to launch the automatic configuration process via the Control Panel.

Click on the tab below corresponding to your offer.

MX Plan
Exchange
E-mail Pro
Zimbra
  1. Connectez-vous à votre .
  2. Rendez-vous dans la partie Web Cloud.
  3. Cliquez sur MX Plan.
  4. Sélectionnez le domaine concerné.
  5. Enfin, allez dans l'onglet Informations générales.

In the General informations box, DKIM is displayed in red in the column Diagnostic.

email

To enable DKIM, simply click on the red DKIM badge and then click on Validate from the activation window that appears.

email

If your domain name is not managed in the same OVHcloud Control Panel as your email platform or is registered outside OVHcloud, you will see the window below:

email

This window asks you to enter two CNAME values in the DNS zone of the domain name, which links this domain name to the DKIM selectors of your email service. You need to enter these values and ensure they are propagated before clicking on Enable.

Automatic DKIM activation takes between 30 minutes and a maximum of 24 hours. To check that your DKIM is working, simply return to the domain management section mentioned in the tabs above and check that the DKIM badge is green, or for a Zimbra offer, that the DKIM tab no longer displays the warning icon.

email

If after 24 hours your DKIM badge is still red, refer to the section "Why is DKIM not working and appears red in the Control Panel?" of this guide.

Configure DKIM via API for an OVHcloud email offer

To configure Exchange or Email Pro DKIM, you will first need to retrieve the internal reference of your Exchange or Email Pro service.

Click on the tab below corresponding to your solution.

Exchange
E-mail Pro
  1. Connectez-vous à votre .
  2. Rendez-vous dans la partie Web Cloud.
  3. Dans la rubrique MICROSOFT, cliquez sur Exchange.
  4. Sélectionnez la plateforme concernée.

By default, your platform name will match its reference number, or it will be visible under the name you have given it (see image below).

email

Also, make sure that the domain name you want to use for your emails is active in the Associated domains section.

email

API - Full DKIM configuration

To configure DKIM, go to the OVHcloud API page and log in:

  1. Click on Authentication in the top left.
  2. Then click on Login with OVHcloud SSO.
  3. Enter your OVHcloud credentials.
  4. Click on the Authorize button to authorise API calls from this site.
Info

Refer to our guide "Getting started with OVHcloud APIs" if you have never used APIs before.

Go to the API section /email/domain/ (MX Plan and Zimbra offers), /email/exchange (Exchange offer) or /email/pro (E-mail Pro offer) and enter "dkim" in the Filter field to display only the API functions related to DKIM.

Click on the tab corresponding to your offer:

MX Plan and Zimbra
Exchange
Email Pro
email
For MX Plan and Zimbra

Follow the 5 steps by clicking on each of the 5 tabs below:

1. Enable DKIM on your domain name
2. Check the status of the DKIM operation
3. Retrieve the DNS record
4. Configurer l'enregistrement DNS
5. DKIM activation

To enable DKIM on your domain name, use the following API call:

PUT/email/domain/{domain}/dkim/enable
  • domain: Enter the domain name attached to the email service on which you want to enable DKIM.

Click EXECUTE to activate.

Sample result:

{
 "domain": "mydomain.ovh",
 "id": 123455789,
 "function": "domain/enableDKIM",
 "status": "todo"
}

You should get the same result as in the example above, with "status": "todo" indicating that DKIM will be activated.

For Exchange

Follow the 5 steps below by clicking on each tab.

1. List of selectors
2. Create a selector
3. Retrieve the DNS record
4. Configurer l'enregistrement DNS
5. Activating DKIM

Before you create one of the selectors for your domain name, you will need to retrieve the name automatically assigned to them by Exchange.


To do this, use the following API call:

GET/email/exchange/{organizationName}/service/{exchangeService}/domain/{domainName}/dkimSelector

  • domainName: Enter the domain name attached to your Exchange service on which you want to enable DKIM.
  • exchangeService: Type the name of your Exchange service in the form "hosted-zz1111111-1" or "private-zz111111-1".
  • organisationName: Type the name of your Exchange service in the form "hosted-zz1111111-1" or "private-zz111111-1".

Example result:

"ovhex123456-selector1"
"ovhex123456-selector2"
For Email Pro

Follow the 5 steps below by clicking on each tab.

1. List of selectors
2. Create a selector
3. Retrieve the DNS record
4. Configurer l'enregistrement DNS
5. Activating DKIM

Before you create one of the selectors for your domain name, you will need to retrieve the name automatically attributed to them by Email Pro.


To do this, use the following API call:

GET/email/pro/{service}/domain/{domainName}/dkim

  • service: Enter the name of your Email Pro service, in the format "emailpro-zz1111111-1".
  • domainName: Enter the domain name attached to your Email Pro service on which you want to enable DKIM.

Example result:

"ovhemp123456-selector1"
"ovhemp123456-selector2"

API - The different states of DKIM

Select the email solution concerned in the following tabs:

MX Plan and Zimbra
Exchange
Email Pro

When performing operations on your E-mail platform's DKIM, use the API call below to check the current DKIM status.

GET/email/domain/{domain}/dkim
  • domain: Enter the domain name attached to your email service on which DKIM must be present.

Then look at the general status: value in the result:

  • disabled: DKIM is disabled, has not yet been configured or has been disabled by API.
  • modifying: DKIM configuration is in progress, it is necessary to wait for the process to complete.
  • toConfigure: DKIM configuration is pending domain name DNS settings. You must manually enter the DNS records in the domain name zone. To do this, go to Step 4 of the “Complete DKIM Configuration” for MX Plan and Zimbra.
  • enabled - The DKIM is configured and functional.
  • error: The installation process encountered an error. Please open a support ticket with the domain name concerned.

At the level of the selectors you also have 3 possible states:

API - Enable or change the DKIM selector

Warning

The DKIM selector must be in ready status before it can be enabled.

Select the email solution concerned in the following tabs:

MX Plan and Zimbra
Exchange
Email Pro

To enable DKIM, use the following API call:

PUT/email/domain/{domain}/dkim/enable

  • domain: Enter the domain name attached to your email service on which the DKIM must be present.

Example result:

{
 "function": "domain/enableDKIM",
 "id": 123456789,
 "domain": "guidesteam.ovh",
 "status": "todo"
}
Info

During a DKIM selector rotation, you can directly activate the second selector you have created to switch over to it, while keeping the first selector active until all emails delivered with it are properly scanned by their recipient.

API - Disable and delete DKIM

Warning

For Exchange and Email Pro solutions

The DKIM selector must be in inProduction or ready status before it can be disabled.

Select the email solution concerned in the following tabs:

MX Plan and Zimbra
Exchange
Email Pro

If you want to disable the DKIM without removing the selectors and their key pair, use the following API call:

PUT/email/domain/{domain}/dkim/disable

  • domain : enter the domain name attached to your email service on which the DKIM must be present.

Example result:

{
 "domain": "guidesteam.ovh",
 "id": 174219594,
 "function": "domain/disableDKIM",
 "status": "todo"
}

Configuring DKIM for an email solution outside of your OVHcloud account

If you would like to configure your DNS zone to add a DKIM record to it for your solution, follow the instructions below.

Depuis , cliquez sur l'onglet Web Cloud puis sur Noms de domaine dans la colonne de gauche et sélectionnez le nom de domaine concerné.

Click on the DNS zones tab, then Add an entry. There are 3 ways to add a record to set the DKIM in your DNS zone:

  • DKIM record: A configuration that allows you to view all settings for a DKIM record.
  • TXT record: The record to use when all DKIM parameters have been provided to you.
  • CNAME record: A record used for an OVHcloud email solution or a Microsoft email server.

DKIM record

This record is named DKIM on the interface but it is actually a TXT record in the zone. The purpose of the DKIM record is to make it easier to read the various parameters of the DKIM by presenting them as independent fields.

email
  • Sub-domain: Enter the DKIM selector name and add ._domainkey as a suffix. Your domain name will be added automatically at the end.

Example:

  selector-name._domainkey.mydomain.ovh.

  • Version (v=): It is used to specify the DKIM version. It is recommended that you use it and its default value is "DKIM1".
    If specified, this tag must be placed first in the record and must be equal to "DKIM1" (without quotes). Records that begin with a "v=" tag with another value should be ignored.

  • Granularity (g=): Allows you to specify the "local" part of an email address, i.e. the part before the "@".
    It allows you to specify the email address or email addresses that are authorised to sign an email message with the selector's DKIM key.
    The default value for "g=" is "*", which means that all email addresses are allowed to use the DKIM signature key.
    By specifying a value for "g=", you can limit the use of the key to a specific local portion of an email address or a range of email addresses by using wildcards (for example: "*-group").

  • Algorithm (hash) (h=): Directive to specify the hash algorithms used to sign email headers. Use this tag to define a list of hash algorithms that will be used to generate a DKIM signature for a given message.

  • Key type (k=): Specifies the signature algorithm used to sign outgoing email messages. It allows recipients to know how the message was signed and what method is used to verify its authenticity.
    Possible values for the tag "k=" include "rsa" for the RSA signature algorithm and "ed25519" for the ed25519 signature algorithm. The choice of algorithm depends on the sender's security policy and the recipient's support.

  • Notes (n=): It is used to include notes of interest for administrators who manage the DKIM key system.
    These notes may be useful for documentation purposes or to help administrators understand or manage how DKIM works. The notes in "n=" are not interpreted by software and do not affect the operation of DKIM.

  • Public key (base64) (p=): It is used to populate DKIM public key data, which is encoded in base64.
    This tag is mandatory in the DKIM signature, and allows signature recipients to retrieve the public key needed to verify the authenticity of the signed message.

  • Revoke public key: If a DKIM public key has been revoked (for example, if the private key is compromised), an empty value must be used for the "p=" tag, indicating that this public key is no longer valid. Recipients must then return an error for any DKIM signature that references a revoked key.

  • Type of service (s=): The "s=" tag is optional and is not present by default. It allows you to specify the type or types of services to which this DKIM record applies.
    Service types are defined using a colon-separated list of keywords.
    The recipient should ignore this record if the appropriate service type is not listed.
    The "s=" tag is intended to restrict the use of keys for other purposes, in case the use of DKIM is defined for other services in the future.
    The service types currently defined are "email" and "*" (all service types).

  • Test mode (t=y): Allows domain name holders to test a DKIM setup without the risk of having messages rejected or marked as spam if DKIM signature verification fails.
    When the "t=y" flag is used, the recipient should not treat test signed messages differently than unsigned messages. However, the recipient can follow the test result to help the signatories.

  • Sub-domains (t=s): Allows the use of the DKIM signature to be restricted to the domain name only (for example: @mydomain.ovh) or allow sending from the domain name and its subdomains (e.g.: @mydomain.ovh, @test.mydomain.ovh, @other.mydomain.ovh, etc.).

TXT record

This is the type of native record used to set the DKIM in your domain name’s DNS zone. You need to have a good understanding of its syntax to complete it.

This type of DKIM setting is recommended when the information to be entered has been communicated to you by the email service provider.

For a complete understanding of the composition of the DKIM record, see the previous part of this guide called "DKIM Record ".

Example of a DKIM record

  • Subdomain:
selector-name._domainkey.mydomain.ovh.
  • Target:
v=DKIM1;t=s;p= MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA77VDAIfyhjtoF0DIE5V7 rev1EKk4L0nxdBpD5O/jPrM4KP0kukeuB6IMpVplkkq52MSDeRcjoO50h0DmwZOr RUkyGjQwOnAh0VhY3fqkuwBYftEX7vWo8C2E1ylzimABkwPpSL62jZ1DheoXcil9 1M35wWBKtlYdXVedKjCQKOEnwTo+0hdNe38rU9NMgq6nbTIMjDntvxoVI+yF3kcx q/VpAY8BIYbcAXkVFvUyfUBABnnKpf0SfblsfcLW0Koy/FRxPDFOvnjNxXeOxMFR UI6K6PaW2WvtbJG2v+gHLY5M4tB0+/FNJU9emZfkPOk3DmRhZ8ENi7+oZa2ivUDj OQIDAQAB

CNAME record

The CNAME record is an alias. This means that the target value points to a URL that will itself provide the DKIM record to the server that will query the CNAME record. This type of CNAME record for setting the DKIM is common when using a Microsoft email server.

This record type is used to enable DKIM on a domain name declared for an OVHcloud Exchange solution. This way, your email solution provider can manage security and update the DKIM for you.

Test your DKIM

We recommend sending an email from an account on your Exchange platform to an email address that verifies the DKIM signature on receipt.

Here is what you will find in the header of the received email:

ARC-Authentication-Results: i=1; mx.example.com;
       dkim=pass header.i=@mydomain.ovh header.s=ovhex123456-selector1 header.b=KUdGjiMs;
       spf=pass (example.com: domain of test-dkim@mydomain.ovh designates 54.36.141.6 as permitted sender) smtp.mailfrom=test-dkim@mydomain.ovh
Return-Path: <test-dkim@mydomain.ovh>

To retrieve the header of an email, please read our guide on Retrieving email headers.

Use cases

How and why change the DKIM key pair on my solution?

Warning

This question only applies to Exchange and Email Pro solutions.

When you enable DKIM for the first time on your email service, you can create 2 selectors, each containing a pair of keys. The second selector acts as a successor to the one that is currently in use.

To avoid attempts to decrypt the DKIM key, it is recommended that you change the key pair periodically. To do this, make sure that you have configured your 2 selectors by checking that the first one is in inProduction status and the second one is in ready status. You can check this status by referring to the section API - The different states of DKIM.

Click on the tab below corresponding to your solution.

Exchange
Email Pro

To switch to the second selector, use the following API call:

POST/email/exchange/{organizationName}/service/{exchangeService}/domain/{domainName}/dkim/{selectorName}/enable
  • domainName: Enter the domain name attached to your Exchange service.
  • selectorName: Enter the name of the selector you want to switch to.
  • organizationName: Enter the name of your Exchange service, which is in the form of "hosted-zz111111-1" or "private-zz11111-1".
  • exchangeService: Enter the name of your Exchange service, which is in the form of "hosted-zz111111-1" or "private-zz11111-1".

After switching to the new selector, keep the old one for 7 days before deleting it and creating a new one.

Why is the DKIM not functional and appears in red in the Control Panel?

Warning

This question only applies to Exchange and Email Pro solutions.

If you notice that your emails have not been signed by the DKIM, despite its activation or configuration, log in to your Control Panel to check the status of the DKIM.

Click on the tab below corresponding to your solution to check the status of the DKIM on your email service.

Exchange
E-mail Pro
  1. Connectez-vous à votre .
  2. Rendez-vous dans la partie Web Cloud.
  3. Dans la rubrique MICROSOFT, cliquez sur Exchange.
  4. Sélectionnez la plateforme concernée.
  5. Enfin, allez dans l'onglet Domaines associés.

In the Associated domains section, check the colour of the DKIM icon to the right of the domain name concerned (see the image below).

email

Here are the 4 states that result in a red DKIM icon in your Control Panel. Click on the tab corresponding to your error code:

501
502
503
504

“Only one DKIM selector has been initialized”

Only a DKIM selector is present in your configuration. To allow us to switch to a new key when necessary, we are asked to configure the 2 selectors provided by the service.

To fix this error:

  • Check the status of the DKIM selectors to determine which one needs to be configured. Use the section “API - The different states of DKIM” of this guide.
  • Once you have identified the selector you want to configure, follow the steps in the section “API - Full DKIM configuration” of this guide, depending on your solution (Exchange or Email Pro), and apply it only to the selector concerned. Wait a maximum of 24 hours after configuring the selector.

From the OVHcloud API interface, how do I understand the status when DKIM is not working?

If you are using the OVHcloud API to configure your DKIM and it is not functional, please use the section “API - The different states of DKIM” of this guide to identify the status of your selectors.

Below, you will find the states that may block your DKIM from working, and the appropriate solution for each situation.

Exchange and Email Pro
MX Plan and Zimbra
  • WaitingRecord: The DNS records are pending configuration or being validated in the DNS zone. A regular automatic check is carried out to see if the DNS record is present and correctly entered. Depending on your solution, follow step 5 in the section “API - Full DKIM configuration” to configure the DNS zone correctly for the domain name concerned.
  • ready: DNS records are present in the zone. DKIM can now be enabled. Simply activate the selector by going to the section API - Activate or change a DKIM selector.
  • deleting: DKIM configuration is being deleted. Once you have deleted it, you will need to follow the section “API - Full DKIM configuration”.
  • disabling: DKIM is being disabled. Once you have done this, you can activate the selector by going to API - Activate or change a DKIM selector.
  • todo: The task has been initialised, it must be launched. After 24 hours, if your selector is still in this state, please open a support ticket, specifying the number of the selector concerned.

Go further

Join our community of users.

Was this page helpful?