S/MIME Certificate Discovery (SCD)

S/MIME Certificate Discovery (SCD) lets the gateway find the S/MIME certificates of external recipients by itself. A domain that takes part announces it with a DNS record and publishes its users’ certificates, and optionally a certificate for the whole domain, in a directory on its web server. When the gateway has no certificate for a recipient, it asks that directory, checks what it finds, and imports the certificates that pass the checks. The next email to the recipient is encrypted without anybody having exchanged certificates by hand.

S/MIME Certificate Discovery (SCD)

Tip

Looking for the short route? Looking up the certificates of your correspondents only takes the steps under Enabling. To publish the certificates of your own domain, follow one of the step-by-step guides at the end of this chapter: Step by step: enterprise edition or Step by step: community edition.

Design goals

  1. Federated. Every domain publishes for itself. There is no registry, no central operator, no enrolment, and no bilateral agreement.

  2. Trivial to publish. A conforming directory is a tree of static files on any HTTPS server, including object storage or a static site host, announced by one DNS TXT record. No dynamic code, no database and no new server software are required.

  3. Trivial to consume, and cheap to decline. One DNS query and one HTTPS GET per address — two GETs, once per domain, for a domain certificate — using only primitives already present in every mail gateway and MUA. Crucially, a domain that does not support SCD is identified by the DNS query alone, with no HTTP request at all.

  4. DNSSEC optional. DNSSEC hardens availability, but the protocol MUST be usable and meaningfully secure without it.

  5. Discovery is not trust. The retrieved certificate is a candidate. The relying party decides whether it is acceptable, using the same path validation it applies to a certificate from any other source.

  6. Per-address and per-domain. Both end-user certificates and domain-to-domain (gateway-to-gateway) certificates are supported, the latter with one requirement no CA can supply.

The full S/MIME Certificate Discovery (SCD) specification can be downloaded from https://www.ciphermail.com/downloads/smime-certificate-discovery.pdf

Discovery only makes certificates available. A discovered certificate is checked as any certificate the gateway uses: it must have a valid path to one of the gateway’s trusted roots, must not be revoked, must be usable for encryption, and must name the recipient’s address. A certificate that fails a check is never stored.

The gateway can also publish the certificates of your own users, so that other gateways find them (see Publishing the certificates of your own domains).

Discovery never stops an email. When a lookup fails or finds nothing, the email goes on with the certificates the gateway already holds, and the usual rules apply (for example PDF encryption, or sending without encryption).

Note

Discovery looks up external recipients only. It is off by default.

How it works

A domain that takes part publishes a TXT record:

_smimecertdir.example.org. IN TXT "v=SCD1"

and serves a directory over HTTPS, by default on the host smimecert.<domain>:

https://smimecert.example.org/.well-known/smimecert/example.org/hu/<hash>
https://smimecert.example.org/.well-known/smimecert/example.org/domain
https://smimecert.example.org/.well-known/smimecert/example.org/domain.sig

hu/<hash> holds the certificates of one address; <hash> is derived from the part of the address before the @. domain holds the domain certificate, the certificate a gateway of that domain decrypts with on behalf of all its users, and domain.sig its signature. A domain certificate is only accepted when it is signed with a key the domain publishes in its TXT record (the k= field), and when it also passes the checks above.

For a recipient the gateway has no certificate for, a lookup:

  1. asks the DNS for the _smimecertdir record of the recipient’s domain. No record means the domain does not take part, and the gateway remembers that for up to a day;

  2. fetches the recipient’s file and, when the domain certificate is allowed (see Mailbox and domain certificates), the domain file and its signature;

  3. checks every certificate it received and imports those that pass.

Answers are cached. A directory answer is reused for at least an hour and at most seven days (a day when the directory gives no lifetime), and after that the gateway asks the directory whether anything changed. A failure, such as a directory that cannot be reached, is remembered for an hour, so that a failing directory is not asked for every email. The scd lookup command asks again at once.

A domain may set the flag flags=domain-only on its record to say that it publishes a domain certificate only. When the domain certificate is allowed, the gateway then skips the per-address lookup.

Enabling

  1. Make sure the gateway can reach the directories it will look up: DNS queries for TXT records, and outgoing HTTPS to smimecert.<domain> of the recipients’ domains. The requests go through the back-end proxy when one is configured (see Proxy ). Behind a proxy, the gateway still refuses a directory whose name resolves to an internal address, where it can resolve the name itself. The proxy resolves the name again, so configure the proxy to refuse connections to internal addresses as well: only the proxy can stop a name that answers the gateway and the proxy differently.

  2. Make sure the roots of the CAs that issue your correspondents’ certificates are trusted by the gateway. Discovered certificates are checked against the same roots as every other certificate. A correspondent with a private CA gives you its root; check its fingerprint with them over a trusted channel before you import it.

  3. Turn on Certificate Discovery Enabled. Discovery runs when it is enabled for both the sender and the recipient, so enabling it globally covers all mail. To limit it to a few correspondents, enable it on your own domain (the senders) and on the domains of those correspondents (the recipients), and leave it off globally.

  4. Optionally set Domain Certificate to ALLOWED, globally or for the domains you want to accept a domain certificate from (see Mailbox and domain certificates).

  5. Test with a recipient whose domain publishes certificates:

    ciphermail-cli scd lookup --email <recipient>
    

From the CLI, enabling discovery globally and allowing domain certificates looks like this:

ciphermail-cli property global set --name scd-enabled --value true
ciphermail-cli property global set --name scd-domain-certificate --value ALLOWED

The settings are described under S/MIME Certificate Discovery (SCD).

Mailbox and domain certificates

Mailbox certificates, the certificates of one address, are imported into the certificate store. They are used through Auto Select Encryption Certificates, as any imported certificate is. When auto-select is off for a recipient, a discovered certificate is imported but only used after an administrator selects it for the recipient. In that case the mail flow only looks up a recipient when a domain certificate is allowed and the recipient has no certificate at all; to import a recipient’s own certificate for manual selection, use scd lookup.

A domain certificate is accepted only when Domain Certificate is ALLOWED for the recipient. It is imported and selected on the domain’s S/MIME encryption page, as for manual domain to domain encryption (see Domain to domain encryption). When the gateway has no domain entry for the recipient’s domain yet, discovery creates one. Email to the domain is then encrypted for the domain certificate and, when the gateway holds one, for the recipient’s own certificate as well, so both the receiving gateway and the recipient’s own mail client can decrypt it.

When the recipient’s own lookup fails but the domain certificate is available, the domain certificate is used, and a line is logged (see What is logged).

Discovery never removes anything. A certificate that a directory no longer publishes stays in the store until it expires or an administrator deletes it; a publisher that wants its certificate to stop being used revokes it.

Tip

A domain certificate is a strong assertion: it lets the receiving gateway read all email to the domain. Allow it for the domains you exchange encrypted email with, rather than globally, when you want to keep control over which domains can receive email that way.

Waiting for a lookup

An email waits for the lookups of its recipients at most Maximum Wait (ms) (default 5000, the largest value among the recipients counts). A lookup that takes longer goes on in the background: the email is sent with what the gateway already holds, and the certificate is there for the next email. With 0, an email never waits, and the first email to a new recipient is never encrypted with a discovered certificate.

To protect the gateway, one email starts at most 50 lookups, and at most 1000 lookups wait in all, 50 of them for one domain. Recipients beyond those limits are skipped for that email and logged.

The refresh job

Certificates expire. A publisher puts the successor of a certificate in its directory beside the current one, ahead of the expiry. Once a day, on one node of a cluster, the refresh job looks up the addresses of the certificates that expire within 30 days, so that their successors are imported before they are needed. It looks only at certificates without a private key, for external recipients with discovery enabled, at domains that publish a record.

Each run ends with a summary line in the log, for example:

S/MIME Certificate Discovery refresh: 12 certificate(s) expiring within 30 day(s), 9 address(es) and 2
domain(s) to look at; skipped 3 at a domain without a record, 1 internal or with discovery off, 0 over the
limit of 10000 per run; 7 lookup(s): 2 found, 5 unchanged, 0 failed, 0 still running; 0 state(s) purged; 4120 ms

The job gives way to the mail flow: when the lookups of the mail flow keep the discovery service busy, the run stops, logs a warning, and tries again an hour later.

Administration commands

Two CLI commands help with setting up and diagnosing discovery (see CLI Commands).

scd lookup --email <address>

Looks the address up at once, ignoring cached answers and remembered failures, and imports what it finds, as the mail flow would. It waits at most 30 seconds. The answer shows whether the domain publishes a record, the flags of the record, the status of the address and of the domain certificate, the certificates accepted, and every event of the lookup, such as a certificate that was rejected and why. The command needs the permission scd:lookup-now.

scd state --domain <domain>

Shows what the gateway remembers of a domain: until when, the record it last read, the certificates discovery accepted for addresses at the domain and for the domain itself, with when and from where, and whether discovery created the domain entry. The command needs the permission scd:get-domain-state.

The outcome of a lookup is one of:

FINISHED

The lookup finished; the rest of the answer describes it.

STILL_RUNNING

The lookup took longer than 30 seconds. It goes on in the background; what it finds is imported, and its events are logged.

BUSY

The discovery service is busy with the lookups of the mail flow. Try again later.

addressStatus and domainStatus are one of:

FOUND

Certificates were accepted and imported.

NONE

Nothing is published for the address, or no domain certificate.

HELD

A valid certificate is already held; the lookup found nothing new.

UNCHANGED

The directory’s answer did not change since the last lookup.

ERROR

The directory could not be read, or what it returned was not usable; the events say why.

NOT_SUPPORTED, NO_DOMAIN, RESOLVER_FAILURE (address only)

The domain publishes no record; the address has no domain; the record could not be queried.

NOT_ALLOWED (domain only)

Domain Certificate is OFF for the recipient, so the domain certificate was not looked for.

Example:

$ ciphermail-cli scd lookup --email carol@example.org
{
  "outcome": "FINISHED",
  "address": "carol@example.org",
  "domain": "example.org",
  "recordFound": true,
  "recordFlags": [],
  "addressStatus": "NONE",
  "domainStatus": "FOUND",
  "addressCertificates": [],
  "domainCertificates": [
    {
      "subject": "CN=gateway@example.org",
      "issuer": "O=Example, CN=Example Root CA",
      ...
    }
  ],
  "events": []
}

Back-end settings

The following settings tune discovery and publishing. Each is given as its Ansible variable and, in brackets, the back-end property the variable sets. Unset, a setting keeps the default given here.

With Ansible Pro/Ent only, set the variables in an Ansible override file, for example /etc/ciphermail/ansible/group_vars/all/override.yml, and run the playbook. A variable is written to the back-end’s configuration only when it is set.

sudo cm-run-playbook

Without Ansible, set the properties in a YAML file in a subdirectory of /etc/ciphermail/spring.config.d, for example /etc/ciphermail/spring.config.d/custom/application.yml, and restart the back-end. Do not use spring.config.d/backend/application.yml, which the installation may generate. For example, to publish every hour through a name server of your own:

ciphermail:
  scd:
    publish-interval: 3600000
    dns-server: 192.0.2.53
sudo systemctl restart ciphermail-backend
ciphermail_backend__scd_enabled_in_flow

Whether the mail flow contains the discovery step at all. Default true; with the step in place, discovery still only runs where it is enabled. Not a property: without Ansible the step is always in the flow.

ciphermail_backend__scd_threads (ciphermail.scd.threads)

The threads that run lookups. Default 4.

ciphermail_backend__scd_queue_size (ciphermail.scd.queue-size)

The lookups that may wait besides the running ones. Default 1000.

ciphermail_backend__scd_max_lookups_per_message (ciphermail.scd.max-lookups-per-message)

The most lookups one email starts. Default 50.

ciphermail_backend__scd_max_pending_per_domain (ciphermail.scd.max-pending-per-domain)

The most lookups waiting for one domain. Default 50.

ciphermail_backend__scd_dns_timeout (ciphermail.scd.dns-timeout)

Milliseconds before the TXT query is given up. Default 5000.

ciphermail_backend__scd_connect_timeout (ciphermail.scd.connect-timeout)

Milliseconds before a connection to a directory is given up. Default 5000.

ciphermail_backend__scd_response_timeout (ciphermail.scd.response-timeout)

Milliseconds a directory may take to answer. Default 10000.

ciphermail_backend__scd_refresh_interval (ciphermail.scd.refresh-interval)

Milliseconds between runs of the refresh job; 0 turns the job off. Default 86400000 (a day).

ciphermail_backend__scd_refresh_window_days (ciphermail.scd.refresh-window-days)

Days before expiry the refresh job looks at a certificate. Values below 7 days plus the refresh interval, in whole days, are raised to that: 8 at the default interval of a day. Default 30.

ciphermail_backend__scd_refresh_concurrency (ciphermail.scd.refresh-concurrency)

The most refresh job lookups at a time, at most one per domain. Default 2.

ciphermail_backend__scd_refresh_max_lookups (ciphermail.scd.refresh-max-lookups)

The most lookups in one run of the refresh job. Default 10000.

ciphermail_backend__scd_refresh_startup_delay (ciphermail.scd.refresh-startup-delay)

Milliseconds before the first run after a start, plus a random part of up to the same. Default 300000 (five minutes).

ciphermail_backend__scd_publish_interval (ciphermail.scd.publish-interval)

Milliseconds between generations of the published directory on every node. Empty or 0, the default, generates nothing; 3600000 (an hour) to publish. See Publishing the certificates of your own domains.

ciphermail_backend__scd_dns_server (ciphermail.scd.dns-server)

The name server the discovery TXT queries go to instead of the system’s, as an IP address with an optional port, for example 192.0.2.53 or 192.0.2.53:5353. Only these queries go there. Default: the system’s name servers.

ciphermail_backend__scd_additional_trust_anchors_path (ciphermail.scd.additional-trust-anchors-path)

A PEM or DER file of CA certificates that the TLS certificates of directories may chain to, besides the roots Java trusts. Use it for a directory with a TLS certificate from a private CA. The file must be readable by the back-end; /tmp is not, since the back-end has a private one. Default: none.

The additional trust anchors configure the TLS connection to the directory only. Whether a discovered S/MIME certificate is trusted is decided by the gateway’s own roots.

What is logged

Every lookup that imports something logs it:

Discovered certificate for alice@example.org imported: CN=alice@example.org, from https://...
Discovered domain certificate of example.org assigned: CN=gateway@example.org, from https://...
Domain example.org created for its discovered domain certificate

Lines that start with S/MIME Certificate Discovery: report what a lookup met. Those marked once are logged once a day per address or domain.

A discovered certificate was rejected (warning)

A certificate in a directory did not pass the checks; the reason follows, for example no path to a trusted root. If the correspondent uses a private CA, obtain its root from them, check the fingerprint, and import it.

The signature of a discovered domain certificate does not verify (warning)

The domain file is not signed with a key from the domain’s record. The domain certificate is not used. Tell the correspondent.

A certificate directory file holds too many certificates (warning)

A file holds more than 32 certificates, and is not used.

A certificate directory could not be read

The directory could not be reached, or answered with an error; the reason follows. The gateway tries again after an hour. Check that the gateway can reach the host, through the proxy if one is configured.

The certificate discovery record could not be queried

The DNS query failed. Check the gateway’s name servers, or name server of ciphermail.scd.dns-server (Back-end settings).

A certificate directory answer held nothing usable

The directory answered, but with nothing that could be used, for example an empty file.

The domain certificate is used because the recipient’s own lookup failed

The recipient’s file could not be read, and the email is encrypted for the domain certificate alone.

More than one certificate discovery record (warning, once)

The domain publishes several _smimecertdir records. Discovery goes on; the correspondent should remove the extra ones.

The domain-only flag appeared on a certificate discovery record (warning, once)

A domain whose certificates were looked up per address now says it publishes a domain certificate only.

The certificate discovery record of a domain that provided certificates is gone (warning, once)

The domain stopped taking part. The certificates already imported are kept until they expire.

A discovered certificate is no longer published (warning, once)

A certificate that discovery imported for an address is gone from the directory. It is kept until it expires or is revoked.

A discovered domain certificate is no longer published (warning, once)

As above, for the domain certificate.

Other lines:

Discovered certificate for <address> could NOT be imported (error)

The certificate passed the checks but could not be stored, for example because the database was not available. It is fetched again while no valid certificate for the address is held; scd lookup fetches it at once.

S/MIME Certificate Discovery for <n> recipients of one mail skipped (warning)

One email had more recipients to look up than allowed, or too many lookups were waiting already. Those recipients are looked up with a later email.

S/MIME Certificate Discovery refresh stopped after <n> lookup(s) (warning)

The refresh job gave way to the mail flow and tries again later.

Continuity alerts

The gateway remembers which domain certificates a domain published. It logs a warning when that changes in a way a routine renewal does not:

  • a domain certificate from an issuer the domain did not use before appears;

  • a domain certificate disappears long before its renewal window, that is with more than a third of its validity, or more than ninety days, left;

  • the first domain certificate appears for a domain the gateway already exchanged certificates with.

The first two are also emailed to the notification recipients Pro/Ent only (see Notifications ).

A change of CA or an early replacement can be legitimate, but it is also what a compromise of the correspondent’s directory would look like. Confirm the new certificate with the correspondent, for example by comparing its thumbprint over the phone.

How long the gateway remembers a domain is set by Memory (days) (default 30), counted from the last certificate accepted from the domain. The domain certificates of a domain are remembered for the continuity checks until they expire. scd state shows what the gateway remembers.

Publishing the certificates of your own domains

The gateway can also publish the certificates of its own users, and a domain certificate, so that other gateways find them in the same way. It writes the directory as files, which Apache on the gateway serves, or which you copy to another web server.

For a walk through every step, see Step by step: enterprise edition and Step by step: community edition.

Publishing is off by default. It takes two steps: the publish interval (ciphermail.scd.publish-interval, see Back-end settings) makes every node generate the directory, for example every hour (3600000), and the settings below decide what is in it. Without the interval nothing is generated, whatever the settings say. Publication is a disclosure: anyone who knows or guesses an address of yours can fetch its certificate, which shows the name in it and sometimes more, and so learns that the address exists. The directory cannot be listed, since a file is named after a hash of the address.

What is published

For an address, the gateway publishes the certificates for which all of these hold:

  • the address is internal: the Locality setting, read for the address itself, so a user can be internal in a domain that is not, and the other way round;

  • Publish Certificates is on for the address (at the user, domain or global level);

  • the gateway holds the private key, and it can be loaded;

  • the address is in the certificate’s subject alternative name;

  • the certificate is valid, can be used for encryption, and the gateway trusts it itself.

All certificates that qualify are published, at most 32 per address, each with its chain up to and including the root, so that a correspondent with a private CA can import the root after checking its fingerprint. A certificate that names several addresses discloses all of them when it is published for one.

As the domain certificate of an internal domain, the gateway publishes the certificates selected on that domain’s S/MIME encryption page, when Publish Domain Certificate is on for the domain. They must have an address at the domain in their subject alternative name, for example gateway@example.com, a private key at the gateway, and pass the same checks. The users of the domain inherit this selection, which is also what lets the gateway decrypt mail encrypted for the domain certificate in strict mode. A selected certificate that does not qualify is skipped, with a warning in the log at every generation.

Give the domain certificate an address no user has. The successor selection below takes any later certificate for that address with its key at the gateway, so a personal certificate issued for a user’s address would be published as a domain certificate too.

The certificate must be selected on the domain’s own entry. A certificate selected on a wildcard domain, such as *.example.com, is not published, and a domain that has no entry of its own publishes no domain certificate, also when a wildcard domain covers it. Publish Domain Certificate itself may be set on the wildcard domain or globally: the domain’s entry inherits it, as it inherits its other settings.

Once a day, the gateway selects the successor of a domain certificate by itself: a certificate with a later start of validity for the same address, with its key at the gateway, that passes the checks. It is added beside the current one, which stays selected until it expires, so both are published during the overlap. A successor from another CA is added too, with a warning: your correspondents will see a “new issuer” alert. Obtaining the successor, by import or from the CA, stays your task. To have a successor you just imported selected and published at once, run scd publish now.

A domain certificate is published signed. Each domain has its own Ed25519 signing key, kept in the gateway’s database, also on a gateway with an HSM. The key is created by scd publish record (below); without it no domain certificate is published.

Serving the directory

Every node writes the directory under /var/www/scd-publish at the publish interval, and at once after scd publish now. Only files that changed are rewritten, and the new generation replaces the old one in one step, so a reader never sees half a tree. The nodes of a cluster each write their own copy; the copies are identical.

Served by the gateway. With Ansible Pro/Ent only, set the variable ciphermail_ui__scd_publish_serve: true and run the playbook.

Apache then serves the directory as /.well-known/smimecert on every virtual host. In addition:

Note

Without Ansible, the CipherMail Apache configuration that comes with the gateway already contains the block below, so there is nothing to add. Only an Apache configuration from before S/MIME Certificate Discovery was introduced, or one that was written by hand, lacks it. To find out, look for smimecert in the configuration: /etc/apache2/conf-enabled/ciphermail.conf on Debian, /etc/httpd/conf/httpd.conf on AlmaLinux. If it is missing, add the block outside the virtual hosts and reload Apache (sudo systemctl reload apache2 or sudo systemctl reload httpd).

Alias /.well-known/smimecert /var/www/scd-publish/current/.well-known/smimecert

<Directory /var/www/scd-publish>
    Options FollowSymLinks
    AllowOverride None
    Require all granted
    ForceType application/pem-certificate-chain
    <Files "domain.sig">
        ForceType text/plain
    </Files>
    FileETag MTime Size
</Directory>

<Location /.well-known/smimecert>
    # a missing file must stay a 404, not the portal page of ErrorDocument 404 /
    ErrorDocument 404 default
    Header always set Cache-Control "max-age=86400" "expr=%{REQUEST_STATUS} == 200"
    Header always set Cache-Control "max-age=3600" "expr=%{REQUEST_STATUS} == 404"
</Location>
  • smimecert.<domain> must resolve to the portal address of the gateway;

  • the gateway’s TLS certificate must contain smimecert.<domain>. With ACME, place a new order with that name added to the existing ones;

  • the TXT record of scd publish record must be published.

Served by another web server. A gateway is usually not reachable from the internet. Copy the current generation to a web server that is, for example every hour:

rsync -a --delete-after --delay-updates /var/www/scd-publish/current/.well-known/smimecert/ \
    web.example.com:/var/www/html/.well-known/smimecert/

--delay-updates puts the new files in place at the end, so the web server never serves a domain file beside the signature of another. Point smimecert.<domain> at that web server, which needs a TLS certificate for the name, and serve the files over HTTPS on port 443 with the content type application/pem-certificate-chain.

In split mode, the front-end nodes run no main back-end and write no directory; serve it from a back-end node or copy it to the front-end nodes or another web server.

Publishing commands

scd publish record --domain <domain>

Shows the TXT record to publish for _smimecertdir.<domain>, the host name smimecert.<domain>, and what is published: the addresses, the domain certificates, and every certificate that was skipped, with the reason. When the domain publishes its domain certificate and has no signing key, the key is created, and the record then contains it (k=). Permission scd:publish-record.

scd publish check --domain <domain> [--base-url <url>] [--all] [--address <ip>]

Fetches the directory from outside, as another gateway would, and compares it with what this node serves: the record in the DNS, the domain certificate and its signature, and 20 addresses (--all for every address). The files are fetched exactly as the gateway’s own discovery fetches: through the same proxy, with the same trusted roots, and with the same rules, so a redirect, a content coding other than gzip or a file over the size limit is reported, as another gateway would fail on it. Other gateways follow no redirect, so the web server must serve the files at the paths themselves. Unlike another gateway, the check also connects to a private address, so that it works where the gateway resolves smimecert.<domain> to an internal address (split-horizon DNS). --base-url checks another web server, for example https://web.example.com/.well-known/smimecert; it must be an https URL. --address connects every fetch to the given IP address instead of the addresses the host resolves to, to check each node of several behind one name in turn; a plain check connects to whichever address the resolver hands it first. The TLS name check is against the host name as always, and a pinned fetch connects directly, never through a proxy. After two failures in a row to reach the host, the check stops and reports how many files it did not check. The answer contains "consistent": true or false and the differences. Permission scd:publish-check.

scd publish now

Selects the successors of the domain certificates at once, instead of waiting for the daily selection, and makes every node generate the directory within a minute, when the publish interval is set. Permission scd:publish-now.

scd publish key next|switch|remove-previous --domain <domain>

Replaces the signing key of a domain (permission scd:publish-key):

  1. next creates a new key. Publish the record it shows, which lists both keys, and wait until the old record has expired from caches (its TTL).

  2. switch signs with the new key from then on.

  3. After 7 days, the longest another gateway keeps the domain file, remove-previous removes the old key. Publish the record it shows.

The signing keys are kept in the key store scd, under the alias SCD:<domain>, with SCD:<domain>:next or SCD:<domain>:previous during a rotation; keystore aliases --keystore-name scd lists them. A domain that no longer publishes keeps its key until you remove it with keystore delete --keystore-name scd --alias SCD:<domain>. keystore export pkcs12 and keystore import pkcs12 move a domain’s key to another installation, so that its record stays the same. Do not delete or rename the key of a domain that publishes: scd publish record would create a new key, and other gateways reject the domain certificate until the new record is published.

The check is not run automatically. To run it daily and be mailed when the directory is not what the gateway serves, use a systemd timer, for example /etc/systemd/system/scd-publish-check.service:

[Unit]
Description=Check the published S/MIME Certificate Discovery directory

[Service]
Type=oneshot
ExecStart=/bin/sh -c 'ciphermail-cli scd publish check --domain example.com > /tmp/scd-check.json; \
    jq -e .consistent /tmp/scd-check.json > /dev/null || mail -s "SCD check failed" admin@example.com < /tmp/scd-check.json'

and /etc/systemd/system/scd-publish-check.timer:

[Unit]
Description=Check the published S/MIME Certificate Discovery directory daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Enable it with systemctl enable --now scd-publish-check.timer.

Step by step: enterprise edition Pro/Ent only

Publishing the certificates of example.com from the gateway itself, with Apache on the gateway serving the directory. Replace example.com by your domain.

  1. Make the domain internal. Add it if the gateway has no entry for it yet:

    ciphermail-cli domain add --domain example.com
    ciphermail-cli property domain set --domain example.com --name locality --value INTERNAL
    

    The users to publish need S/MIME certificates with their private keys on the gateway, issued by a CA whose root the gateway trusts.

  2. Choose what to publish. The certificates of the users of the domain:

    ciphermail-cli property domain set --domain example.com --name scd-publish-certificates --value true
    

    Optionally a domain certificate, a certificate with its private key for an address no user has, such as gateway@example.com. Look up its thumbprint, select it for the domain and switch it on. Select it on the domain itself, not on a wildcard domain such as *.example.com: a selection on a wildcard domain is not published. set explicit replaces the selection, so list any certificate that is selected already as well:

    ciphermail-cli certificate search email --email gateway@example.com
    ciphermail-cli certificate selection domain set explicit --domain example.com --thumbprints <thumbprint>
    ciphermail-cli property domain set --domain example.com --name scd-publish-domain-certificate --value true
    
  3. Switch on generating and serving. Add to an Ansible override file, for example /etc/ciphermail/ansible/group_vars/all/override.yml:

    ciphermail_backend__scd_publish_interval: 3600000
    ciphermail_ui__scd_publish_serve: true
    

    and run the playbook:

    sudo cm-run-playbook
    
  4. Point the host name at the gateway. In the DNS of example.com, let smimecert.example.com resolve to the portal address of the gateway (an A record, or a CNAME to the portal’s host name), or to the load balancer in front of a cluster.

  5. Add the host name to the TLS certificate. With ACME, order a certificate for every name the gateway already serves plus the new one:

    ciphermail-cli acme order new --domains portal.example.com smimecert.example.com
    

    With a certificate of your own, it must name smimecert.example.com as well.

  6. Publish the record. This creates the domain’s signing key when it publishes a domain certificate:

    ciphermail-cli scd publish record --domain example.com
    

    Publish txtRecord from the answer as a TXT record for _smimecertdir.example.com. When txtRecord is empty, nothing is published, and skipped says why.

  7. Generate now, instead of waiting for the next hour, and look at the files:

    ciphermail-cli scd publish now
    ls /var/www/scd-publish/current/.well-known/smimecert/example.com
    
  8. Check from outside, once the DNS changes are visible:

    ciphermail-cli scd publish check --domain example.com
    

    "consistent": true means that what the world sees is what the gateway publishes; otherwise differences says what is wrong. To keep checking, add the systemd timer of Publishing the certificates of your own domains.

Step by step: community edition

Publishing the certificates of example.com from the gateway itself, with Apache on the gateway serving the directory. Replace example.com by your domain.

  1. Make the domain internal. Add it if the gateway has no entry for it yet:

    ciphermail-cli domain add --domain example.com
    ciphermail-cli property domain set --domain example.com --name locality --value INTERNAL
    

    The users to publish need S/MIME certificates with their private keys on the gateway, issued by a CA whose root the gateway trusts.

  2. Choose what to publish. The certificates of the users of the domain:

    ciphermail-cli property domain set --domain example.com --name scd-publish-certificates --value true
    

    Optionally a domain certificate, a certificate with its private key for an address no user has, such as gateway@example.com. Look up its thumbprint, select it for the domain and switch it on. Select it on the domain itself, not on a wildcard domain such as *.example.com: a selection on a wildcard domain is not published. set explicit replaces the selection, so list any certificate that is selected already as well:

    ciphermail-cli certificate search email --email gateway@example.com
    ciphermail-cli certificate selection domain set explicit --domain example.com --thumbprints <thumbprint>
    ciphermail-cli property domain set --domain example.com --name scd-publish-domain-certificate --value true
    
  3. Switch on generating. Create /etc/ciphermail/spring.config.d/custom/application.yml with:

    ciphermail:
      scd:
        publish-interval: 3600000
    

    and restart the back-end, which also creates /var/www/scd-publish:

    sudo systemctl restart ciphermail-backend
    
  4. Check that Apache serves the directory. The CipherMail Apache configuration that comes with the gateway already does. Look for smimecert in /etc/apache2/conf-enabled/ciphermail.conf on Debian or /etc/httpd/conf/httpd.conf on AlmaLinux:

    grep smimecert /etc/apache2/conf-enabled/ciphermail.conf
    

    If nothing is found, the configuration is from before S/MIME Certificate Discovery was introduced, or was written by hand. Add the Apache block of Publishing the certificates of your own domains (“Served by the gateway”) outside the virtual hosts, then check the configuration and reload Apache:

    sudo apachectl configtest
    sudo systemctl reload apache2
    

    (httpd instead of apache2 on AlmaLinux.)

  5. Point the host name at the gateway. In the DNS of example.com, let smimecert.example.com resolve to the address of the gateway’s portal (an A record, or a CNAME to the portal’s host name).

  6. Add the host name to the TLS certificate. The certificate Apache presents, SSLCertificateFile in the CipherMail Apache configuration, must name smimecert.example.com as well. Replace it by one that does, and reload Apache.

  7. Publish the record. This creates the domain’s signing key when it publishes a domain certificate:

    ciphermail-cli scd publish record --domain example.com
    

    Publish txtRecord from the answer as a TXT record for _smimecertdir.example.com. When txtRecord is empty, nothing is published, and skipped says why.

  8. Generate now, instead of waiting for the next hour, and look at the files:

    ciphermail-cli scd publish now
    ls /var/www/scd-publish/current/.well-known/smimecert/example.com
    
  9. Check from outside, once the DNS changes are visible:

    ciphermail-cli scd publish check --domain example.com
    

    "consistent": true means that what the world sees is what the gateway publishes; otherwise differences says what is wrong. To keep checking, add the systemd timer of Publishing the certificates of your own domains.

What publishing logs

A generation that changed files logs, per domain, the number of addresses and domain certificates and the record, for example:

S/MIME Certificate Discovery publishes for example.com: 120 address(es), 1 domain certificate(s), 123 file(s);
record v=SCD1; k=...

A generation that changed nothing logs nothing at the default level. A selected domain certificate that is not published logs a warning at every generation, naming the reason, until it is fixed.