Verify message integrity with DKIM

To generate the comparison values in a DKIM-Signature, the sending email server standardizes both headers and body content. This process is called canonicalization. DKIM follows the Internet Message Format format. Given this standard format, an email message can still undergo some mild modifications in transit. You can choose the level of tolerance you have for these changes as they get authenticated.

• If you want to accept common modifications, choose relaxed.
• If you don't want to tolerate any changes, choose simple.
• You can set this value for both the header and body independently, with the header listed first, then a forward slash (/), then the body.
• This value defaults to simple/simple.

This results in accepted combinations of simple/simple, simple/relaxed, relaxed/simple, and relaxed/relaxed. If you only provide one value, like relaxed, that value applies to the header. The body gets set to simple and the complete value becomes relaxed/simple.

The service that generates your DKIM signatures sets the method, or algorithm, applied to the header and body content.

• On email servers that you manage, you set the canonicalization value in the DKIM configuration file.
• Most large-scale email servers set their value to relaxed/relaxed.
• Twilio SendGrid sets this value to relaxed/simple.

To learn how canonicalization changes email message formatting, see Canonicalization.

Comparing two versions of a large value has inherent difficulties. No method can compare an entire single object, like an email message, at two points in time: when one party sent it and when the intended party received it. To compare a single file from two points in time, computer systems use a digital fingerprint of the object called a hash. To create a hash, you use an algorithm that runs mathematical calculations on the data and returns a 256 alphanumeric string. Hashing describes the calculation that creates the hash.

With DKIM, the header and the body content get hashed and the recipient email server compares hashes of the original objects, not the objects themselves.

To protect the data on disk or in transit requires encryption. The data gets transformed into a format that only certain parties can decode. Public key encryption involves a pair of keys: a public key and a private key. The private key transforms, or encodes or encrypts, the data. The party that encrypts the data keeps this key a secret. The public key decodes or decrypts the encrypted data back into its original form. The public key can be widely distributed and used to decrypt data.

With DKIM, the sending email server encrypts the hashed value with its private key. The DKIM DNS TXT resource record includes the public key, which can decrypt the DKIM-Signature and prove message data integrity.

To convert binary data into text characters, email servers use Base64 encoding. This converts 8-bit (2^8) representations of data into 6-bit (2^6) representations of data. With this encoding, you only need 64 characters to represent any data, hence the name Base64. In practice, this means that every three bytes, or 24 bits, of data gets converted into four characters. This encoding allows sending of any type of data including images and attachments.

To ensure transmission of all types of data and not just text, DKIM encodes the data with Base64.

DKIM implementation requires creating the instructions and public key stored on the sender's domain and configuring any DKIM settings on the email server.

With DKIM, receiving email servers check the integrity of incoming email messages in the following process:

1. Identify or install a DKIM processor on your sending email server.
2. Configure the basic settings for the DKIM processor, like the canonical algorithm.
3. Generate a DKIM key pair on your sending email server. If prompted, use the following parameters:
   • selector: A unique identifier for the key, like a subdomain or a hostname for a server.
   • key size: The cryptographic strength or size of the key in bits, either 1024 or 2048.
4. Copy the public key.
5. Create a TXT DNS record.
   • Set the record label to <selector>._domainkey.<domain>.
   • Set the record value to the signature, outlined in the DKIM record format.
6. When sending an email message, your sending message transfer agent (MTA) creates your DKIM-Signature and adds it to the message.

To implement DKIM for your account on Twilio SendGrid, see the Domain Authentication guide.

An DKIM record resides as the value of a DNS TXT labeled <selector>._domainkey.<domain> with a value that resembles the following:

k=rsa;t=s;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDmzRmJRQxLEuyYiyMg4suA2SyMwR5MGHpP9dNT1hRiwUd/mZp1ro7kIDTKS8ttkI6z6eTRW9e9dDOxzSxNuXmume60Cjbu08gOyhPG3GfWdg7QkdN6kR4V75MFlw624VY35DaXBvnlTJTgRg/EW72O1DiYVThkyCgpSYS8nmEQIDAQAB

The TXT record value must adhere to the following standards:

• It must follow RFC 1035 3.3.14 format for DNS records.
• It can't exceed 512 bytes.

The DKIM DNS TXT record is a string limited to 512 bytes. This text consists of a series of semi-colon-separated properties called tags. These tags include the public key and the settings to generate a signature that matches the encrypted one in your email messages. DKIM requires only one tag: for the public key. The remaining tags provide instructions to recreate a match to your DKIM-Signature. The tags include the following string values:

To improve your email deliverability, Twilio turns on DKIM for all email messages. This provides you with a custom DKIM record. When you configuring an authenticated domain, choose automated or manual security.

These differ in who updates to DNS records and the DKIM signature after making changes that impact deliverability. This could include adding another dedicated sending IP address or granting a subdomain permission to send email messages.

• Automated security grants Twilio permission to make updates on your behalf.
• Manual security leaves updates to your best efforts.

To verify the authenticity of a message's signature, receiving mail servers parse the DKIM-Signature email header.

With DKIM turned on, the sending email server adds an DKIM-Signature metadata header to each email message. This header resembles the following example:

The properties in a DKIM-Signature email header also use tags. DKIM requires email messages to include seven of these tags.

With DKIM, receiving email servers check the integrity of incoming email messages in the following process:

1. The receiving server checks the format of the DKIM-Signature header. If the DKIM-Signature meets any of the following conditions, the check fails.
   • Signature misses one of the required tags: v=, a=, b=, bh=, d=, h=, and s=.
   • The domain in the i= tag doesn't match the complete or parent domain in the d= tag.
   • The h= tag doesn't include the From header.
2. The receiving server sends a request to the sending domain's DNS server, based on the s= and d= tags of the signature, following the method in the q= tag. The q= tag only accepts a value of dns/txt, which translates to check the TXT record in the DNS server.
   • If the query fails to respond, the recipient can try again later.
   • If the query responds that the DKIM record doesn't exist, the check fails.
3. This domain's DNS server returns the DKIM record to the receiving server. If the DKIM record meets any of the following conditions, the check fails.
   • The DKIM record doesn't follow the DKIM specification.
   • The h= tag in the DKIM record doesn't include the value in the a= tag of the signature.
   • The DKIM record doesn't include a public key in the p= tag.
   • The k= tag in the DKIM record doesn't match the a= tag of the signature.
4. The receiving server prepares comparison values using the tags from the signature.
   1. Creates a standard version of the message body using the canonicalization algorithm from the c= tag.
   2. Truncates the message body length to the value of the l= tag.
   3. Applies the hash algorithm from the a= tag on the truncated, canonicalized message body. The hash algorithm defaults to SHA256.
   4. Converts the 256-character body hash using Base64.
   5. Compares the resulting value to the bh= tag value. If the values don't match, the check fails.
   6. Applies hash algorithm from the a= tag on the headers from the h= tag and their values, using the canonicalization algorithm from the c= tag, and the DKIM-Signature header itself without its b= tag. As the DKIM-Signature header includes the bh= tag, the body hash gets included.
   7. Applies the encryption algorithm from the a= tag to the combination of the headers and their values and the DKIM-Signature header. The encryption algorithm defaults to RSA, but could be Ed25519.
   8. Converts the 256-character encrypted header hash using Base64.
   9. Compares the resulting value to the b= tag. If the values don't match, the check fails.
5. The next step depends on the check result which only have one of two outcomes:
   • The check passes. The receiving email server delivers the message to the specified recipient.
   • The check fails. The receiving email server rejects the message and processes it according to the DMARC policy or the inbox provider's filtering rules.

• Sender Identity
• Domain Authentication
• Single Sender Verification
• How to set up link branding
• How to set up reverse DNS
• Troubleshooting Sender Authentication