Message Signing setup and usage

Setup overview

How to use the Message Signing feature

There are 3 complementary layers to control the Message Signing feature:

1. the default configuration set at the Transactional Email Technical Account with which your source Application is authenticated to;

2. use the signing flag into the JobRequest you sent to that Technical Account, working with REST APIs or SMTP Header;

3. the S/MIME certificate uploaded into the Message Signing PKI (Public Key Infrastructure), you have 2 options:

   1. using our User Synchronisation Encryption (USE) tool and uploading your certificate by yourself;

   2. or contact our Support Team to request your S/MIME certificate to be uploaded by us.

Technical Account configuration

First of all, the Message Signing feature must have been booked, enabled and configured at the Technical Account level by our Implementation team. Thus to allow JobRequest to use this feature. 2 parameters must be set:

• active: define if the feature is authorized to be used with the Technical Account or not, means that if the Technical Account allows to route the JobRequest to the built-in signing component;

• defaultActive: define the default behaviour expected if nothing is explictly set into the JobRequest sent to the Technical Account (see the paragraph below).

Please review all the potential configuration scenarios and related results later below.

It is recommended to implement one dedicated Technical Account for all your business applications requiring the sent signed emails and force the signing mechanism for all JobRequests sent to this Technical Account. To do so, ask to set the defaultActive parameter to true, therefore you don’t even need to explictly set the signing flag into any JobRequest.

JobRequest

Just as the vast majority of Transactional Email features, Message Signing can be controled at the JobRequest level. Thus to provide you sufficient flexibility to choose which email must be sent out signed or not.

If the signing flag is explicitly defined at the JobRequest level (true or false), it overwrittes the Technical Account defaultActive configuration.

REST APIs

With Message Signing you have the possibility to flag which email within a REST JobRequest should sent out signed using your S/MIME certificate, example:

{ 
  "mail": ...
  "job": {
    ...
    "features": {
      "messageSigning": {
        "active": true
      }
    }
  }
}

Find more information about this Message Signing REST parameter here or on the Transactional Email API developer portal.

SMTP Adapter

With Message Signing you have the possibility to flag which email within a SMTP JobRequest should sent out signed using your S/MIME certificate, example:

X-RETARUS-M4A-MESSAGE-SIGNING-ACTIVE: true

Find more information about this Message Signing SMTP Header here.

Public Key Infrastructure

Each S/MIME certificate that have been imported into the Message Signing PKI (Public Key Infrastructure) is related to one specific sender address:

• to sign an email the EnvelopeFrom address set into the JobRequest must match at least one S/MIME signing key uploaded into the Message Signing PKI;

• If a JobRequest asks to digitally sign an email with a sender address not matching a S/MIME certificate uploaded into the PKI, the JobRequest will be considered as “PROCESSING_FAILED”.

Several S/MIME certificates can be uploaded into the Message Signing PKI. The sender address set into these certifcates is the key identifier to know which signing key to apply to the JobRequest.

Wrap up

To trigger the Message Signing feature and send signed emails you must:

1. Sent a JobRequest with an EnvelopeFrom matching a S/MIME certificate uploaded into the PKI

2. AND

   1. Set explicitly the signing flag to active: true into that JobRequest

   2. OR set the default Technical Account configuration to defaultActive: true

Tracking Points for administrators

myEAS Live Search

Email successfully signed

Push Notification samples

SMIME_SIGNING (intermediate)

Phase:             PROCESS
Type:               SMIME_SIGNING
State:               INTERMEDIATE
Subtype:          OK

{
  "meta":{
    "event": {
    "description": "The mail was signed successfully.",
    "phase": "PROCESS",
    "state": "INTERMEDIATE",
    "subType": "OK",
    "ts": "2024-11-08T07:38:42.224Z",
    "type": "SMIME_SIGNING"
},

SMIME_SIGNING FAILED

Phase:             PROCESS
Type:               DROPPED
State:               FINISHED
Subtype:          PROCESSING_FAILED

{
  "meta":{
    "event": {
    "description": "signature with given key identifier (sender.address@your-domain) failed",
    "phase": "PROCESS",
    "state": "FINISHED",
    "subType": "PROCESSING_FAILED",
    "ts": "2024-11-12T08:46:45.680Z",
    "type": "DROPPED"
},