How to improve email security with a DKIM record

e>

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

• You can manage the domain name concerned in the OVHcloud Control Panel, or via your DNS service provider if it is registered outside of OVHcloud.
• You have access to the OVHcloud Control Panel.
• You have signed up to one of these email offers:
  • OVHcloud MX Plan Email, available with a web hosting plan
  • Exchange
  • An email solution outside of OVHcloud with DKIM support

Instructions

Overview

• How does DKIM work?
  • Hashing
  • Asymmetric encryption
  • How are hashing and asymmetric encryption used for DKIM?
  • Why do we need to configure DNS servers?
  • Example of an email sent using DKIM
  • What is a DKIM selector?
• Automatically configure DKIM for an OVHcloud email offer
• Configure DKIM via API for an OVHcloud email offer
  • API - Full DKIM configuration
    • For MX Plan)
    • For Exchange
  • API - The different states of DKIM
  • API - Activate or change a DKIM selector
  • API - Disable and delete DKIM
• Configuring DKIM for an email solution outside of your OVHcloud account
  • DKIM record
  • TXT record
  • CNAME record
• Test your DKIM
• Use cases
  • How do I change my DKIM key pair?
  • Why does the DKIM icon appear in red in the Control Panel?
  • From the OVHcloud API interface, how do I understand the state of the DKIM that is not working?

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.

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

Automatically configure DKIM for an OVHcloud email offer

Automatic DKIM configuration is available for all our email offers:

• MX Plan included with a Cloud Web Hosting, a free 100M hosting or ordered separately
• Exchange

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.

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.

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 DKIM, you will first need to retrieve the internal reference of your Exchange service.

1. Log in to your OVHcloud Control Panel.
2. Open the Web Cloud section.
3. In the MICROSOFT section, click Exchange.
4. Select the service concerned.
5. Finally, go to the Associated domains tab.

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).

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

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.

Go to the API section /email/domain/ (MX Plan offer) or /email/exchange (Exchange 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:

For MX Plan

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

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

{
 "activeSelector": null,
 "autoconfig": true,
 "selectors": [
   {
     "selectorName": "ovhmo3456789-selector2",
     "status": "set",
     "cname": "ovhmo3456789-selector2._domainkey.mydomain.ovh CNAME ovhmo3456789-selector2._domainkey.123402.aj.dkim.mail.ovh.net."
   },
   {
     "selectorName": "ovhmo3456789-selector1",
     "cname": "ovhmo3456789-selector1._domainkey.mydomain.ovh CNAME ovhmo3456789-selector1._domainkey.123403.aj.dkim.mail.ovh.net.",
     "status": "set"
   }
 ],
 "status": "modifying"
}

{
 "activeSelector": null,
 "status": "disabled",
 "autoconfig": false,
 "selectors": [
   {
     "cname": "ovhmo3456789-selector1._domainkey.mydomain.ovh CNAME ovhmo3456789-selector1._domainkey.123403.aj.dkim.mail.ovh.net."
     "status": "toSet",
     "selectorName": "ovhmo4287928-selector1"
   },
   {
     "selectorName": "ovhmo4287928-selector2",
     "cname": "ovhmo3456789-selector2._domainkey.mydomain.ovh CNAME ovhmo3456789-selector2._domainkey.123402.aj.dkim.mail.ovh.net.",
     "status": "toSet"
   }
 ]
}

ovhmo3456789-selector1._domainkey IN CNAME ovhmo3456789-selector1._domainkey.123403.aj.dkim.mail.ovh.net.

{
 "selectors": [
   {
     "selectorName": "ovhmo3465680-selector2",
     "cname": "ovhmo3456789-selector2._domainkey.mydomain.ovh CNAME ovhmo3456789-selector2._domainkey.123402.aj.dkim.mail.ovh.net.",
     "status": "set"
   },
   {
     "status": "set",
     "cname": "ovhmo3456789-selector1._domainkey.mydomain.ovh CNAME ovhmo3456789-selector1._domainkey.123403.aj.dkim.mail.ovh.net."
     "selectorName": "ovhmo3465680-selector1"
   }
 ],
 "activeSelector": "ovhmo3465680-selector1",
 "autoconfig": true,
 "status": "enabled"
}

For Exchange

Follow the 5 steps below by clicking on each tab.

"ovhex123456-selector1"
"ovhex123456-selector2"

{
   "autoEnableDKIM": false,
   "configureDkim": false,
   "selectorName": "ovhex123456-selector1"
}

status: "todo",
function: "addExchangeDomainDKIM",
id : 107924143,
"finishDate": null,
"todoDate": "2023-05-05T11:32:07+02:00"

targetRecord: "ovhex123456-selector1._domainkey.1675.ac.dkim.mail.ovh.net"
recordType: "CNAME"
header: "from;to;subject;date"
taskPendingId: 108712689
status: "waitingRecord"
cnameIsValid: false
lastUpdate: "1970-01-01T00:00:00+01:00"
customerRecord: "ovhex123456-selector1._domainkey.mydomain.ovh"
selectorName: "ovhex1234565-selector1"

ovhex123456-selector1._domainkey IN CNAME ovhex123456-selector1._domainkey.1500.ab.dkim.mail.ovh.net.

id: 108716876
todoDate: "2023-05-05T11:30:11+02:00"
finishDate: null
status: "todo"
function: "enableExchangeDKIM"

API - The different states of DKIM

Select the email solution concerned in the following tabs:

Not Found (404)
{ `message`: `The requested object (selectorName = ovhemp123456-selector1) does not exist` }

API - Enable or change the DKIM selector

Select the email solution concerned in the following tabs:

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

API - Disable and delete DKIM

Select the email solution concerned in the following tabs:

{
 "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.

Log in to the OVHcloud Control Panel. In the Web Cloud section, click on Domain names in the left column and select the domain name concerned.

Click on the DNS Zone 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.

• 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?

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.

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

• 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".
• exchangeService: Enter the name of your Exchange service, which is in the form of "hosted-zz111111-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?

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.

1. Log in to your OVHcloud Control Panel.
2. Open the Web Cloud section.
3. In the MICROSOFT section, click Exchange.
4. Select the service concerned.

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

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.

Go further

Join our community of users.