Chapter 21. Managing attribute encryption

Directory Server offers a number of mechanisms to secure access to sensitive data in the directory. However, by default, the server stores data unencrypted in the database. For highly sensitive information, the potential risk that an attacker could gain access to the database, can be a significant risk.

The attribute encryption feature enables administrators to store specific attributes with sensitive data, such as government identification numbers, encrypted in the database. When enabled for a suffix, every instance of these attributes, even the index data, is encrypted for every entry stored in this attribute in the database. Note that you can enable attribute encryption for suffixes. To enable this feature for the whole server, you must enable attribute encryption for each suffix on the server. Attribute encryption is fully compatible with eq and pres indexing.

Important

Any attribute you use within the entry distinguished name (DN) cannot be efficiently encrypted. For example, if you have configured to encrypt the uid attribute, the value is encrypted in the entry, but not in the DN: 

dn: uid=demo_user,ou=People,dc=example,dc=com
...
uid::Sf04P9nJWGU1qiW9JJCGRg==

21.1. Keys Directory Server uses for attribute encryption

To use attribute encryption, you must configure encrypted connections using TLS. Directory Server uses the server’s TLS encryption key and the same PIN input methods for attribute encryption.

The server uses randomly generated symmetric cipher keys to encrypt and decrypt attribute data. The server wraps these keys using the public key from the server’s TLS certificate. As a consequence, the effective strength of the attribute encryption cannot be higher than the strength of the server’s TLS key.

Warning

Without access to the server’s private key, it is not possible to recover the symmetric keys from the wrapped copies. Therefore, back up the server’s certificate database regularly. If you lose the key, you will no longer be able to decrypt and encrypt data stored in the database.

21.2. Enabling attribute encryption using the command line

This procedure demonstrates how to enable attribute encryption for the telephoneNumber attribute in the userRoot database using the command line. After you perform the procedure, the server stores existing and new values of this attribute AES-encrypted.

Prerequisites

  • You have enabled TLS encryption in Directory Server.

Procedure

  1. Export the userRoot database: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend export -E userRoot

    The server stores the export in an LDIF file in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory. The -E option decrypts attributes that are already encrypted during the export.

  2. Enable AES encryption for the telephoneNumber attribute: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend attr-encrypt --add-attr telephoneNumber dc=example,dc=com

  3. Stop the instance: 

    # dsctl instance_name stop

  4. Import the LDIF file: 

    # dsctl instance_name ldif2db --encrypted userRoot /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2022_01_24_10_28_27.ldif

    The --encrypted parameter enables the script to encrypt attributes configured for encryption during the import.

  5. Start the instance: 

    # dsctl instance_name start

Additional resources

21.3. Enabling attribute encryption using the web console

This procedure demonstrates how to enable attribute encryption for the telephoneNumber attribute in the userRoot database using the web console. After you perform the procedure, the server stores existing and new values of this attribute AES-encrypted.

Note that the export and import features in the web console do not support encrypted attributes. Therefore, you must perform these steps on the command line.

Prerequisites

  • You have enabled TLS encryption in Directory Server.
  • You are logged in to the instance in the web console.

Procedure

  1. Export the userRoot database: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend export -E userRoot

    The server stores the export in an LDIF file in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory. The -E option decrypts attributes that are already encrypted during the export.

  2. In the web console, navigate to Database → Suffixes → suffix_entry → Encrypted Attributes.
  3. Enter the attribute to encrypt, and click Add Attribute.
  4. In the Actions menu, select Stop Instance.

  5. On the command line, import the LDIF file: 

    # dsctl instance_name ldif2db --encrypted userRoot /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2022_01_24_10_28_27.ldif

    The --encrypted parameter enables the script to encrypt attributes configured for encryption during the import.

  6. In the web console, open the Actions menu, and select Start Instance.

Additional resources

21.4. General considerations after enabling attribute encryption

Consider the following points after you have enabled encryption for data that is already in the database:

  • Unencrypted data can persist in the server’s database page pool backing file. To remove this data:

    1. Stop the instance: 

      # dsctl instance_name stop

    2. Remove the /var/lib/dirsrv/slapd-instance_name/db/guardian file: 

      # **rm /var/lib/dirsrv/slapd-instance_name/db/guardian``

    3. Start the instance: 

      # dsctl instance_name start
  • After you enabled have encryption and successfully imported the data, delete the LDIF file with the unencrypted data.
  • Directory Server does not encrypt the replication log file. To protect this data, store the replication log on an encrypted disk.
  • Data in the server’s memory (RAM) is unencrypted and can be temporarily stored in swap partitions. To protect this data, configure encrypted swap space.
Important

Even if you delete files that contain unencrypted data, this data can be restored under certain circumstances.

21.5. Updating the TLS certificates used for attribute encryption

Attribute encryption is based on the TLS certificate of the server. Follow this procedure to prevent that attribute encryption fails after renewing or replacing the TLS certificate.

Prerequisites

  • You configured attribute encryption.
  • The TLS certificate will expire in the near future.

Procedure

  1. Export the userRoot database: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend export -E userRoot

    The server stores the export in an LDIF file in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory. The -E option decrypts attributes that are already encrypted during the export.

  2. Create a private key and a certificate signing request (CSR). Skip this step if you want to create them using an external utility.

    • If your host is reachable only by one name, enter: 

      # dsctl instance_name tls generate-server-cert-csr -s "CN=server.example.com,O=example_organization"

    • If your host is reachable by multiple names: 

      # dsctl instance_name tls generate-server-cert-csr -s "CN=server.example.com,O=example_organization" server.example.com server.example.net

      If you specify the host names as the last parameter, the command adds the Subject Alternative Name (SAN) extension with the DNS:server.example.com, DNS:server.example.net entries to the CSR.

    The string specified in the -s subject parameter must be a valid subject name according to RFC 1485. The CN field in the subject is required, and you must set it to one of the fully-qualified domain names (FQDN) of the server. The command stores the CSR in the /etc/dirsrv/slapd-instance_name/Server-Cert.csr file.

  3. Submit the CSR to the certificate authority (CA) to get a certificate issued. For further details, see your CA’s documentation.

  4. Import the server certificate issued by the CA to the NSS database:

    • If you created the private key using the dsctl tls generate-server-cert-csr command, enter: 

      # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate add --file /root/instance_name.crt --name "server-cert" --primary-cert

      Remember the name of the certificate you set in the --name _certificate_nickname parameter. You require it in a later step.

    • If you created the private key using an external utility, import the server certificate and the private key: 

      # dsctl instance_name tls import-server-key-cert /root/server.crt /root/server.key

      Note that the command requires you to specify the path to the server certificate first and then the path to the private key. This method always sets the nickname of the certificate to Server-Cert.

  5. Import the CA certificate to the NSS database: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate add --file /root/ca.crt --name "Example CA"

  6. Set the trust flags of the CA certificate: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags "Example CA" --flags "CT,,"

    This configures Directory Server to trust the CA for TLS encryption and certificate-based authentication.

  7. Stop the instance: 

    # dsctl instance_name stop

  8. Edit the /etc/dirsrv/slapd-instance_name/dse.ldif file, and remove the following entries including their attributes:

    • cn=AES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    • cn=3DES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    Important

    Remove the entries for all databases. If any entry that contains the nsSymmetricKey attribute is left in the `/etc/dirsrv/slapd-instance_name/dse.ldif file, Directory Server will fail to start.

  9. Import the LDIF file: 

    # dsctl instance_name ldif2db --encrypted userRoot /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2022_01_24_10_28_27.ldif

    The --encrypted parameter enables the script to encrypt attributes configured for encryption during the import.

  10. Start the instance: 

    # dsctl instance_name start