LDAP certificate lookup

The gateway can automatically retrieve S/MIME recipient certificates from an external LDAP directory when it does not already have a valid certificate for the recipient. When enabled, the gateway queries the configured LDAP server during delivery, imports the certificate it finds, and uses it for encryption. The certificate is then available for future messages to the same recipient.

To use LDAP certificate lookup, you must supply additional Ansible configuration at deployment time via command-line variables. This is typically done by passing the LDAP connection details and lookup settings when you run your Ansible playbook.

Before you begin, make sure you have:

• Network connectivity from the gateway to the LDAP server, including any required firewall openings.

• The LDAP server URI, Base DN, and an appropriate search scope and filter that locate user certificates (commonly stored in the userCertificate attribute).

• A Bind DN and password if anonymous binds are not allowed.

• Transport security configured on the LDAP server (StartTLS or LDAPS) if your security policy requires it.

High-level steps:

1. Collect LDAP connection details (server address, port, Base DN), authentication credentials, and the search filter you want to use for matching recipient email addresses.

2. Run your Ansible deployment and provide these values on the command line as extra variables so the gateway is configured to perform LDAP certificate lookups.

3. After deployment, send a test message to a recipient whose certificate is in the directory to confirm that the gateway retrieves and uses the certificate.

4. Optionally refine your configuration to include or exclude certain recipient patterns and ensure lookups use secure LDAP transport.

Configuration

To configure LDAP lookup, you need to create an ansible override file /etc/ciphermail/ansible/group_vars/all/ldap-smime-lookup.yml which overrides the Ansible ciphermail_backend__smime_ldap_servers variable.

Example:

---
ciphermail_backend__smime_ldap_servers:
  - {
      uri: 'ldaps://ldap.example.com:1389',
      base_dn: 'ou=People,dc=example,dc=com',
      scope: 'sub',
      alias_dereferencing: 'never',
      search_filter_template: '(&(objectclass=inetOrgPerson)(mail=#{email}))',
      exclude_recipients_regex: '.*@gmail\.com .*@outlook\.com',
      include_recipients_regex: '.*@example\.com',
      bind_dn: 'cn=admin,cn=config',
      password: 'admin',
      timeout: 30000
  }

The following fields can be configured:

uri

The LDAP URL. This is a required setting.

base_dn

The base distinguished name (DN) that serves as the starting point for LDAP searches. This is a required setting.

scope

The search scope:

• base searches only the base object

• one searches its immediate children

• sub searches the entire subtree

• children searches the children of the base object and their descendants, excluding the base itself

Default: sub

alias_dereferencing

Specify how aliases dereferencing is done. Should be one of never, always, search, or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or dereferenced only when locating the base object for the search.

Default: never

search_filter_template

The filter should conform to the string representation for search filters as defined in RFC 4515.

In the search filter, include the token #{email}. This token will be replaced with the email address you want to look up.

Default: (&(objectclass=inetOrgPerson)(mail=#{email}))

exclude_recipients_regex

A comma-separated list of regular expressions. If a recipient’s email address matches any of these patterns, the certificate check is skipped. Use this to exclude recipients for whom a certificate should never be looked up.

include_recipients_regex

A comma-separated list of regular expressions. If a recipient’s email address matches any pattern in this list, the certificate check is performed and not skipped. Use this to explicitly include recipients whose domains would otherwise be excluded because they match a pattern in the exclude_recipients_regex list.

bind_dn

If your LDAP server requires authentication, set bind_dn to the distinguished name (DN) of the user account that will authenticate.

password

Password for the LDAP bind account; required only when bind_dn is specified.

timeout

Maximum execution time for the LDAP script, in milliseconds. If this limit is exceeded, the script is terminated.

Default: 30000

Setup

To enable the LDAP lookup, follow these steps:

1. Create the file using the Cockpit File Browser (or use an SSH client)

   /etc/ciphermail/ansible/group_vars/all/ldap-smime-lookup.yml

   Paste the ciphermail_backend__smime_ldap_servers configration.

   ---
   ciphermail_backend__smime_ldap_servers:
     - {
         uri: '<replace>',
         base_dn: '<replace>',
         scope: '<replace>',
         alias_dereferencing: '<replace>',
         search_filter_template: '<replace>',
         exclude_recipients_regex: '<replace>',
         include_recipients_regex: '<replace>',
         bind_dn: '<replace>',
         password: '<replace>',
         timeout: <replace>
     }
   

   where <replace> should be replaced by the correct value

2. Login the shell using Cockpit Terminal (or use an SSH client)

3. Run the ansible playbook

   sudo cm-run-playbook
   

   Hint

   the sudo command might ask for your Unix account password.

Test

To confirm that your current settings allow certificate retrieval from the LDAP server, run the lookup script manually with the appropriate parameters.

echo "test@example.com" | /opt/ciphermail/scripts/cm-ldap-retrieve-certificates.sh --uri <replace> --base-dn <replace> ...

Usage: cm-ldap-retrieve-certificates.sh ...

    [-h]                        show usage
    [--help]                    show usage
    --uri                       uri of ldap server
    --base-dn                   base-dn
    --scope                     search scope (one of base, one, sub [default], or children)
    --alias-dereferencing       specify how aliases dereferencing is done (one of never [default], always, search, or find)
    --search-filter-template    ldap search filter
    --exclude-recipients-regex  space-separated list of regular expressions that will exclude an email address if it matches any of the provided patterns
    --include-recipients-regex  space-separated list of regular expressions that will include an email address if it matches any of the provided patterns
    --bind-dn                   the DN to bind to the LDAP directory
    --password                  the password for simple authentication
    --debug                     if set, debug output will be produced

Note: Replace test@example.com with a real email address that has an associated certificate in your LDAP directory.

When a certificate exists in the LDAP directory for the specified email address, the script returns the certificate encoded in Base64.

Example:

MIIFvzCCBKegAwIBAgIQSeTtMHIdW8+....

If the LDAP server does not have a certificate for the email address, no results are returned.

Finsh

If LDAP lookup is enabled, the gateway performs an LDAP search for each external recipient whenever an email is sent.