14 Understanding Data Encryption in Oracle Unified Directory

Understand about data encryption in Oracle Unified Directory from the following topics. Get an insight into basic encryption concepts, supported features, and basic configuration tasks.

• What is Attribute Encryption?

• Understanding Attribute Encryption

• Understanding Encryption Algorithms

• Understanding Encryption in Index Keys

• Understanding Encryption in Replication Topology

• Considerations for Attribute Encryption Usage

• Configuring Attribute Encryption

• Configuring Attribute Encryption in Replication Enabled Topology

• Encryption or Re-encryption of Existing Data
• Use Case Scenarios

14.1 What is Attribute Encryption?

Encryption is a mechanism that converts plaintext data into something unreadable, called ciphertext, to prevent unauthorized access to sensitive data. Decryption is the process in which the ciphertext is converted back to plaintext.

Oracle Unified Directory is a next-generation unified directory solution that integrates storage, synchronization, and proxy functionality to help you manage the critical identity information that drives your business applications. This data might contain sensitive information that should be available only to the intended recipient. Oracle Unified Directory offers mechanisms; such as access control rules, password authentication, and SSL to secure access to your data. Your data might also contain some extremely sensitive information, such as credit card numbers and SSN numbers. For this type of data, standard measures alone are not sufficient to prevent unauthorized access because the information is stored as human readable plaintext within the database. If an invader gains access to your server storage files and uses this information to their advantage, then the loss could present a high security risk.

Oracle Unified Directory provides an attribute encryption feature that enables you to store certain sensitive attributes as ciphertext, which prevents data from being readable while it is stored in underlying database files, backup files, and exported LDIF files. Attribute encryption enables you to encrypt important data before it is written to the disk and to decrypt data when it is read from the disk.

Note:

The attribute encryption feature does not encrypt data that is retrieved over the LDAP protocol. Only data saved on the disk is encrypted.

If an LDAP client reads (searches for) an entry with some encrypted attributes on the disk, then that client receives a decrypted entry and the values of the originally encrypted attributes are immediately readable without any decryption.

Attributes are not encrypted by default. You configure attribute encryption at the suffix level, which means that an attribute is encrypted at every entry in which it appears in the suffix. Thus, after an attribute is encrypted, every instance of that attribute is encrypted before it is stored in the database files. This in turn implies that all of the on-disk data for that specific attribute is encrypted.

Encryption is always reversible. Encrypted attributes are decrypted when returned through search requests. If you want to encrypt an attribute in an entire directory, then you must enable encryption for that attribute in every suffix or leave the suffix list empty.

Note:

Attribute encryption affects all data and index files associated with a suffix. These attributes are not changed (encrypted) until attribute encryption is activated. Existing attributes will remain unchanged.

To apply encryption to all of the data, you must first make the configuration change, export the contents, and then re-import the contents.

Attribute encryption also enables you to export data to another database in an encrypted format. The purpose of attribute encryption is to protect sensitive data only when the data is being stored or exported.

Related Topics

Masking Attributes in the Audit Log

14.2 Understanding Attribute Encryption

Attributes are not encrypted by default. You need to configure attribute encryption at the suffix level. This indicates that an attribute is encrypted at every entry in which it appears in the suffix.

Oracle Unified Directory allows you to encrypt:

• Specific attribute types defined in a mandatory attribute types list.

  Note:

  You cannot encrypt some operational or internal attributes, such as entryuuid, createTimestamp, virtual attributes, or password attributes. For more information about attributes that are not supported for encryption, see Considerations for Attribute Encryption Usage.

• Only DB Local Backend (user back end).

• Attributes in all suffixes of all available DB Local Backends or, if listed, in some specific suffixes. For example:

  If suffixes are specified, then it should be root suffixes of a DB Local Backend, not a sub suffix. For example, if DB Local Backend has root suffix dc=example,dc=com then you cannot encrypt some attributes only in ou=people,dc=example,dc=com.

14.3 Understanding Encryption Algorithms

Oracle Unified Directory enables you to prevent unauthorized access to attributes of an entry stored on a disk using encryption algorithms.

An encryption algorithm is a set of mathematical rules or functions used for encrypting and decrypting data. These algorithms work in combination with a key to encrypt and decrypt data.

The attribute encryption feature supports a wide range of standard encryption algorithms.

You can configure the server to encrypt attributes using several encrypting schemes. The supported encryption schemes include:

• AES128

• AES256

  Note:

  Download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" if applicable. The download page is https://www.oracle.com/in/java/technologies/javase-jce-all-downloads.html

• Blowfish (128-bit key)

• Triple DES (168-bit key)

• RC4 (128-bit key)

This content applies only to OUD Bundle Patch 12.2.1.4.211008 and later releases.

The newly supported encryption schemes include:

• AES-128-GCM
• AES-192-GCM
• AES-256-GCM (Default from 12.2.1.4.211030 BP release)

  Note:

  Oracle recommends you to use a GCM based stronger encryption algorithm from the above list. Weaker algorithms are used for backward compatibility. When a weaker encryption algorithm is detected by OUD server, a warning message gets logged in the server logs.

14.3.1 Attribute Encryption Key

Oracle Unified Directory uses symmetric key for attribute encryption and decryption. It generates the required symmetric key whenever it is needed. Symmetric key is encrypted and securely stored in cn=admin data backend. This encryption is done using the server's public key. Hence, the stored encrypted symmetric key can only be decrypted using the server's private key.

14.4 Understanding Encryption in Index Keys

An attacker can also access sensitive data directly through index files. Therefore, it is imperative to encrypt the index keys corresponding to the encrypted attributes, to ensure that the attributes are fully protected.

Database encryption is partially compatible with indexing. The content of the index files that are normally derived from attribute values are also encrypted to prevent an attacker from recovering part or all of the encrypted data from an analysis of the indexes.

The server pre-encrypts all index keys before looking up an index for an encrypted attribute. This action has some effect on server performance for searches that use an encrypted index. However, limited performance impact should not prevent you from using an index.

Oracle Unified Directory enables you to use the following index types for an associated encrypted attribute:

• Equality

• Substring

• Approximate

• Presence

Note:

You must bear in mind that encryption techniques do not preserve the order of an index. Therefore, ordering indexes are not supported when attributes are encrypted.

Encryption is supported for DB Local Backend indexes only. Keys of the indexes are encrypted for an encrypted attribute.

14.5 Understanding Encryption in Replication Topology

Encryption in replication topology refers to encrypting data that is stored in replication server databases.

Learn about how encryption is supported in a replication topology from the following topics:

• Understanding Encryption in a Replication Server Database (or changelog)

• Understanding Attribute Encryption Key in Replication Topology

• Updating Servers from 11.1.2.2.0

• Using an ODSEE Gateway

14.5.1 Understanding Encryption in a Replication Server Database (or changelog)

Oracle Unified Directory supports encryption in a replication server database (also known as the changelog) and for cn=changelog (also known as the external changelog or the retro-changelog). Oracle Unified Directory encrypts data on a replication server database the same way it does for a server database. No additional configuration is necessary. Enabling and disabling encryption, defining attributes for encryption, and defining suffixes for encryption is the same for either database.

If you perform an operation on a server that is part of a replicated topology, and if that change is associated with an encrypted attribute, then Oracle Unified Directory encrypts the data in the replication server's database (the changelog, which is readable from cn=changelog) using the same algorithm that is used for encryption in the server.

When Oracle Unified Directory accesses the retro-changelog (cn=changelog), which accesses the changelog, the retro-changelog always returns clear values. Encryption only occurs at rest; that is, on stable storage (hard disk).

14.5.2 Understanding Attribute Encryption Key in Replication Topology

The keys used for encryption are created, stored, and retrieved from cn=admin data. This suffix is replicated on any other server in the topology.

So, any server in the topology can decrypt any encrypted attribute and send it to its LDAP clients. Therefore, keys used for encryption or decryption algorithm are replicated throughout the entire topology because cn=admin data is replicated.

A stored symmetric key used in encryption can only be decrypted by the server using its private key. Hence, while renewing ads-truststore certificate, you must retain the same keys.

Note:

If you are using a gateway from Oracle Directory Server Enterprise Edition, see Using an ODSEE Gateway.

14.5.3 Updating Servers from 11.1.2.2.0

When updating version 11.1.2.2.0 replicated topology of servers to version 11.1.2.3.0, encryption does not occur in every replication server database until after all servers have been updated.

In addition, you must wait for the purge delay to expire to ensure there are no more sensible values in the changelog.

14.5.4 Using an ODSEE Gateway

Learn about using an ODSEE gateway in this topic. Oracle Directory Server Enterprise Edition allows some attributes to be encrypted in the back end, but not in the changelog.

Starting with Oracle Unified Directory version 11.1.2.3.0, if you are using a gateway from Oracle Directory Server Enterprise Edition, then you can configure that gateway like other servers in the Oracle Unified Directory topology.

Then, if changes sent from an Oracle Directory Server Enterprise Edition server through the replication gateway are associated with an encrypted attribute (defined by the configuration as with regular Oracle Unified Directory servers), then Oracle Unified Directory can encrypt that data and store it in the replication server database.

14.6 Considerations for Attribute Encryption Usage

Learn about the usage of Attribute Encryption, what happens when the attribute encryption configuration is modified and what needs to be done for encrypted attributes that are indexed.

Consider the following points below while implementing the attribute encryption feature:

• Attribute encryption provides increased data security, but it does have an impact on system performance. Consider using encryption only for the most sensitive attributes.

• When modifying the attribute encryption configuration, you must export your data, make the configuration changes, and then import the newly configured data to ensure that all configuration changes are taken into account without any information loss. If you fail to do so, then data that is already present in the back end on which no change occurred after the data encryption configuration change remains in clear or encrypted format as configured with the initial algorithm.

• Algorithm changes are supported. Modifying encryption on an indexed attribute requires that you rebuild the index associated with the encrypted attribute. This in turn impacts the performance. For more information about rebuilding indexes, see rebuild-index.

• For encrypted attributes that are indexed, it is required to maintain the consistency between indexes and the data encryption configuration. If you modify or update the configuration for encrypted attributes, then you must rebuild the indexes associated with the encrypted attribute. Failing to do so will log an error message in the error log file, which prompts you to rebuild the indexes because the configuration has changed. For more information about how to rebuild indexes, see rebuild-index.

• If you configure an attribute of RDN to be encrypted, then the values that appear in the DN will not be encrypted. Only values that are stored in the entry are encrypted.

  For example, consider the following entry:

  dn: uid=foo,dc=example,dc=com
  objectclass: inetorgperson
  objectclass: organizationalperson
  objectclass: person
  objectclass: top
  uid=foo
  cn=bar
  sn=joe
  

  Here, uid is an attribute that is:

  • Part of the DN of the entry and is its RDN.

  • Also part of the attributes of the entry. You must keep in mind that this is always the case, because RDN is always present as an attribute in the entry.

  However, uid is a multi-valued attribute, therefore you can add a value to uid in the entry as follows:

  dn: uid=foo,dc=example,dc=com
  objectclass: inetorgperson
  objectclass: organizationalperson
  objectclass: person
  objectclass: top
  uid=foo
  uid=secondValue
  cn=bar
  sn=joe
  

  Now, if you encrypt uid, then the new value that you have added is encrypted and not the initial value, foo. The value that is in the RDN is not encrypted.

• You cannot configure encryption for the following attributes because they are used internally by the server:

  Operational Attributes

  • objectclass

  • entryUUID

  • creatorsName

  • createTimestamp

  • modifiersName

  • modifyTimestamp

  Virtual Attributes

  You cannot configure a virtual attribute for encryption.

  Password Attributes

  Because passwords are already hashed or encrypted, you cannot use the attribute encryption feature to modify the existing behavior of, or configure encryption for, any password attributes that are defined in a password policy. For example, the userPassword attribute, which is defined in the default password policy is not supported.

  Password encryption or hashing is handled differently. For information about password policies and the password storage scheme, see Managing Password Policies.

14.7 Configuring Attribute Encryption

You must configure different parameters to enable attribute encryption.

The following sections describe the configuration parameters to enable attribute encryption and the different methods to configure attribute encryption.

• Attribute Encryption Configuration Parameters

• Attribute Encryption Advanced Configuration Parameters

• Configuring Attribute Encryption Using the dsconfig Command

• Configuring Attribute Encryption Using the dsconfig Interactive Mode

• Managing Attribute Encryption

14.7.1 Attribute Encryption Configuration Parameters

Learn about the various attribute encryption configuration parameters, their names, descriptions, allowable values and formats, and rules to perform an action based on the values provided, from the tabular column below.

Table 14-1 describes the configuration parameters to enable attribute encryption.

Table 14-1 Configuration Parameters for Attribute Encryption

Name	Description	Single/ Multi Valued	Format	Presence Rules
enabled	Allows you to enable or disable encryption.	S	String representing a boolean, true or false	If set to true, then you must at least define attribute-encryption-include.
attribute-encryption- include	Encrypts every attribute defined here. Encrypt attributes of all the entries of all suffixes or only in the suffixes defined with encrypted-suffix if defined.	M	String representing a single attribute name or OID	Defined if enabled is set to true
encrypted-suffix	Controls how encryption is applied for suffixes. If not present, encryption is applied on suffixes stored in DB Local Backend. If present, defines the list of user DB Local Backend suffixes on which the encryption is applied. Other suffixes are not encrypted. WARNING: The suffix must be a root suffix defined in the back end, not a descendant. For example, if back end has dc=example,dc=com defined as a supported suffix, you cannot use ou=people,dc=example,dc=com here.	M	String representing a single suffix	Meaningful if enabled is set to true
attribute-encryption- algorithm	Defines the algorithm to use for encryption.	S	String representing an encryption algorithm. Possible values are: triple-des-168 aes-128 aes-256 blowfish-128 rc4-128 aes-128-gcm aes-192-gcm aes-256-gcm Note: The following algorithms: aes-128-gcm, aes-192-gcm, and aes-256-gcm are applicable for October 21 Bundle Patch and later releases.	Meaningful if enabled is set to true

14.7.2 Attribute Encryption Advanced Configuration Parameters

In this release, the following configuration parameters, except offline-reencryption, is applicable for attribute encryption using scheduled tasks.

This content applies only to OUD Bundle Patch 12.2.1.4.211008 and later releases.

Table 14-2 Attribute Encryption Table

Name	Description	Single/ Multi Valued	Format	Presence Rules
encryption-properties	Optional encryption properties that you can use to configure custom values for initialization vector length in bits (iv-length-bits=128) and GCM tag length (gcm-tag-length=12). When you do not specify any value, OUD uses 96 bit iv and a tag length of 16 for GCM if chosen.	M	String represents a single property with name and value. For example, iv-length-bits=96	Meaningful for encryption algorithm (like GCM) that supports iv and tag length
use-defined-enc-algo-in-replication	Controls the encryption algorithm that will be used to generate replication changelogs. In a cross-version topology with new OUD instances and old OUD instances, this value set to false (default setting) if older instances of OUD do not understand a newer algorithm. True specifies that if all instances of OUD are running the same version, a changelog is generated and published to other OUD instances using the defined encryption scheme.	S	String represents a boolean value, true or false.

14.7.3 Configuring Attribute Encryption Using the dsconfig Command

You use the dsconfig command to configure attribute encryption.

Consider the scenario, where you plan to encrypt every attribute, postalAddress and mail, with AES-128 algorithm in entries of user DB Local Backend root suffixes, dc=customers,dc=com and dc=partners,dc=com.

To configure attribute encryption using the dsconfig command:

1. Run the following commands sequentially.

   To configure attribute encryption for postalAddress attribute with AES-128 algorithm in the dc=customers,dc=com suffix, run the following command:

   dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
   -j /local/password set-data-encryption-prop --set enabled:true \
   --set attribute-encryption-include:postalAddress \
   --set encryption-algorithm:aes-128 \
   --set encrypted-suffix:dc=customers,dc=com
   

   Note:

   If you do not specify the encryption algorithm as aes-128 and if you are using the bundle patch release 12.2.1.4.211030 or higher, then the default encryption algorithm is aes-256-gcm. The aes-256-gcm algorithm applies only to the bundle patch 12.2.1.4.211030 or higher.

   To add attribute encryption for mail attribute and to add encryption in the dc=partners,dc=com suffix, run the following command:

   dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
   -j /local/password \
   set-data-encryption-prop --add attribute-encryption-include:mail \
   --add encrypted-suffix:dc=partners,dc=com \
   

14.7.4 Configuring Attribute Encryption Using the dsconfig Interactive Mode

You can configure attribute encryption using the dsconfig command-line interactive mode.

Introduction of a Data Encryption subsection, located under the main Security menu, allows you to modify all of the configuration attributes described in Table 14-1.

Consider the following example to configure attribute encryption using the dsconfig command in interactive mode.

Oracle Unified Directory Configuration Console Main Menu
What do you want to configure?

    1)  General Configuration            7)   Virtualization
    2)  Authentication and authorization 8)   Load Balancing
    3)  Schema                           9)   Distribution
    4)  Replication                      10)  Integration
    5)  Local Data Source                11)  Http
    6)  Remote Data Source
 
    q)  quit
 
Enter choice: 2
Authentication and authorization Management Menu

What would you like to do?

    1)  Access Control Group Plugin  8)  Password Policy Import
    2)  Access Control Handler       9)  Password Storage Scheme
    3)  Crypto Manager              10)  Password Validator
    4)  Data Encryption             11)  Root DN
    5)  Key Manager Provider        12)  SASL Mechanism Handler
    6)  Password Generator          13)  Trust Manager Provider
    7)  Password Policy
         
    b)  back
    q)  quit
 
Enter choice [b]: 4

Configure the Properties of Data Encryption

Property                           Value(s)
------------------------------------------------------------------
1)  attribute-encryption-include   description, givenname, mobile
2)  enabled                        true
3)  encrypted-suffix               "dc=example,dc=com"
4)  encryption-algorithm           aes-128

?)  help
f)  finish - apply any changes to the Data Encryption
c)  cancel
q)  quit
 
Enter choice [f]: ?

Component name: Data Encryption

Data Encryption allows to configure attribute encryption.

Option Types:
 
 r -- Property value(s) are readable
 w -- Property value(s) are writable
 m -- The property is mandatory
 s -- The property is single-valued
 a -- Administrative action is required for changes to take effect

Property                      Options  Syntax
--------------------------------------------------
attribute-encryption-include  rw---    OID
enabled                       rw-s-    BOOLEAN
encrypted-suffix              rw---    DN
encryption-algorithm          rw-s-    ALGORITHM
---------------------------------------------------

14.7.5 Managing Attribute Encryption

You can enable and disable attribute encryption, and modify and fetch attributes using dsconfig command.

The following topics describe how to enable and disable attribute encryption:

• Enabling Encryption for Attributes of Specific Suffixes

• Disabling Encryption

• Enabling Encryption for a Specific Attribute Using an Algorithm

• Modifying Attributes

• Fetching Attributes

14.7.5.1 Enabling Encryption for Attributes of Specific Suffixes

This section describes a scenario to encrypt every attribute, postalAddress and mail, with 3DES-168 algorithm in entries of user DB Local Backend root suffixes, dc=customers,dc=com and dc=partners,dc=com.

To configure attribute encryption for postalAddress use the following command:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
-j /local/password \
set-data-encryption-prop --set enabled:true \
--set encryptedsuffix:dc=customers,dc=com \
--set attribute-encryption-include:postalAddress \
--set encryption-algorithm:triple-des-168 \

To configure attribute encryption for mail use the following command:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
-j /local/password \
set-data-encryption-prop --add attribute-encryption-include:mail \
--add encrypted-suffix:dc=partners,dc=com \

You can configure attributes using the set-data-encryption-prop option of dsconfig command. For more information about the encryption parameters, see dsconfig.

In this example, configure encryption using the preceding two dsconfig commands sequentially. For more information, see Configuring Attribute Encryption Using the dsconfig Command.

14.7.5.2 Disabling Encryption

Use the following dsconfig command to disable encryption:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
-j /local/password \
set-data-encryption-prop --set enabled:false \

14.7.5.3 Enabling Encryption for a Specific Attribute Using an Algorithm

Use the following command to encrypt the mobile attribute with the AES-128 algorithm:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" \
-j /local/password set-data-encryption-prop --set enabled:true \
--set attribute-encryption-include:mobile \
--set encryption-algorithm:aes-128 \

14.7.5.4 Modifying Attributes

You can modify the attributes through the dsconfig command with the set-data-encryption-prop subcommand as follows:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" /
-j /local/password set-data-encryption-prop --set "enabled:true"

Note:

Run the dsconfig set-data-encryption-prop --help command to explore the set-data-encryption-prop command option. For more information, see dsconfig.

14.7.5.5 Fetching Attributes

You can read the attributes through the dsconfig command with the get-data-encryption-prop subcommand as follows:

dsconfig -n -X -h localhost -p 1444 -D "cn=Directory Manager" /
-j /local/password get-data-encryption-prop

Property                     : Value(s)
-----------------------------:-------------------------------
attribute-encryption-include : description, givenname, mobile
enabled                      : true
encrypted-suffix             : "dc=example,dc=com"
encryption-algorithm         : aes-128

14.8 Configuring Attribute Encryption in Replication Enabled Topology

You can initialize OUD topology with attribute encryption. The keys used for encryption are not stored in the keystore instead in cn=admin data suffix. This suffix is replicated across all the servers of the topology. Therefore, any OUD instance can decrypt encrypted attribute prior to sending it back to client application.

Note:

Consider a Replication Enabled Topology with attribute encryption already configured and the attribute data of all entries stored in an encrypted state in the topology. To renew or regenerate Self-Signed Certificates (for example, when the Certificates are about to expire), see Regenerating Certificates Using dsreplication regenerate-cert.

To renew or reset Custom or CA Signed Certificates, see Providing Certificates Using dsreplication set-cert. The commands (dsreplication regenerate-cert and dsreplication set-cert) automate the process of resetting the Certificates in the replication topology.

14.8.1 Configuring Attribute Encryption in a New Replicated Topology Setup

This content applies only to OUD Bundle Patch 12.2.1.4.211008 and later releases.

You can configure the attribute encryption in an entirely new replicated topology setup.

Follow these steps:

1. Configure attribute encryption for all instances using dsconfig. See Configuring Attribute Encryption Using the dsconfig Command and Configuring Attribute Encryption Using the dsconfig Interactive Mode.
2. Enable Replication for all instances. See Enabling Replication Between Two Servers With dsreplication.

   Note:

   Scheduled re-encrypt task is not applicable for this new replication topology setup assuming no data present.

14.8.2 Configuring Attribute Encryption in the Existing Replicated Topology Setup

Consider an OUD instance running in a replicated topology. To secure value of attributes while storing the attributes on the disk, you need to define attribute encryption. The attribute data of the newly created entries is encrypted in the replicated topology, whereas the attribute data of the existing entries are not be stored securely.

To apply encryption to all entries or the attribute data, you need to perform following steps.

Follow these steps:

1. Configure attribute encryption for all instances using dsconfig. See Configuring Attribute Encryption Using the dsconfig Command and Configuring Attribute Encryption Using the dsconfig Interactive Mode.
2. Perform encryption of the existing data as described in the section Encryption or Re-encryption of Existing Data.

14.9 Encryption or Re-encryption of Existing Data

In the existing environment, when attribute encryption is newly enabled or any existing attribute encryption related configuration such as the encryption algorithm changes, then encryption of the existing data present in the backend as per new encryption configuration needs to be performed.

You can perform the attribute encryption in different ways as follows:

• Encryption or Re-encryption of Existing Data Using Scheduled Task
• Encryption or Re-encryption of Existing Data Using Replication or Import
• Encryption or Re-encryption of Existing Data on Single Instance Using Export or Import

14.9.1 Encryption or Re-encryption of Existing Data Using Scheduled Task

This content applies only to OUD Bundle Patch 12.2.1.4.211008 and later releases.

You can perform the encryption of the existing data present in the backend by configuring a re-encrypt scheduled task on an OUD server instance. The scheduled task encrypts the required data on the given OUD server instance where it is run.

In case of a replicated topology, it also publishes necessary attribute encryption modify operations to other nodes over replication so that data on the other nodes get encrypted.

Follow these steps

1. Ensure that necessary attribute encryption configurations are present on all OUD instances in case of a replicated topology.
2. Take backup of all OUD instances.
3. Configure the scheduled task for re-encryption using command, dsconfig create-task --type reencrypt.

   
   Recurring Task ./dsconfig create-task -h <OUD_INSTANCE> -p <ADMIN_PORT> -D "cn=Directory Manager" -j /local/password -X --type reencrypt --backendID userRoot --recurringTask "* * * * *" --batch-size 10
   Schedule Task ./dsconfig create-task -h <OUD_INSTANCE> -p <ADMIN_PORT> -D "cn=Directory Manager" -j /local/password -X --type reencrypt --backendID userRoot --start 0
   

In this approach the existing data is encrypted without the downtime of OUD instances.

Consider that the backend has huge number of entries, then you can schedule a ReEncrypt Recurring Task. The reencryption is preferred to be performed in batches at the configured intervals as per the schedule. Consider that the backend has fewer entries, then you can schedule a single time Scheduled Task. All entries are intended to be reencrypted at once as part of a single task.

Oracle recommends that you configure the task on the OUD instance such that no LDAP queries from any clients are processed until the re-encryption is finished. This instance should be included in the replication topology but not in the load balancer. This can be accomplished in one of following ways:

1. When you remove one node from the existing load balancer.
2. When you build a new instance specifically for this purpose.

14.9.1.1 Scheduled Task for Re-encryption

The scheduled task for re-encryption takes care of re-encrypting all entries based on parameters passed. On successful completion of the task, the status is marked as "Completed Successfully and stopped Recurring Task" for a Recurring Task or "Completed successfully" for a Scheduled Task.

Usage

dsconfig create-task {options}

For global options, see dsconfig --help.

Note:

Interactive mode for dsconfig create-task is not supported now. Hence use complete command as listed below.

Subcommand Options

Table 14-3 Create Task Options

Option	Description
--type {type}	Specifies the type of task to be created. Note: Currently only reencrypt type is supported.
-t, --start {startTime}	Indicates the date and time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.
--recurringTask {schedulePattern}	Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time and date pattern.
--batch-size {batchsize}	Represents the batch size to be used for re-encryption.
--backendID {backendName}	Represents the backend ID for the backend to re-encrypt.
--completionNotify {emailAddress}	Represents the email address of a recipient to be notified when the task completes. You may specify this option more than once.
--errorNotify {emailAddress}	Represents the email address of a recipient to be notified if an error occurs when this task executes. You may specify this option more than once.
--dependency {taskID}	Represents the ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.
--failedDependencyAction {action}	Represents the action this task will take should one if its dependent tasks fail. The value must be one of PROCESS, CANCEL, DISABLE. If not specified defaults to CANCEL.

Examples

The examples of creating a recurring task and a scheduled task is as follows:

Creating a Recurring Task

./dsconfig create-task -h <OUD_INSTANCE> -p <ADMIN_PORT> -D "cn=Directory Manager" -j /local/password -X --type reencrypt --backendID userRoot --recurringTask "* * * * *" --batch-size 10

Creating a Scheduled Task

./dsconfig create-task -h <OUD_INSTANCE> -p <ADMIN_PORT> -D  "cn=Directory Manager" -j /local/password -X --type reencrypt --backendID  userRoot --start 20210830121500

14.9.1.2 Managing Scheduled Tasks

You can view all re-encryption tasks using manage-tasks command:

./manage-tasks -h <OUD_INSTANCE> -p <ADMIN_PORT> -D "cn=Directory Manager" -j /local/password -n -s

Output

20210830043148359 ReEncrypt Completed successfully
ReEncryptTask-5f73a72c-7725-473f-89e8-3bc05f847d64 ReEncrypt Completed Successfully and stopped Recurring Task
ReEncryptTask-5f73a72c-7725-473f-89e8-3bc05f847d64-20210830043300000 ReEncrypt Completed successfully
ReEncryptTask-5f73a72c-7725-473f-89e8-3bc05f847d64-20210830043600000 ReEncrypt Completed successfully

Troubleshooting Using Manage-Tasks

You can troubleshoot by using the manage-tasks command. Use the manage-tasks command to check if the scheduled Re-encrypt Tasks had any errors during re-encryption. The status of the tasks would either be in "Completed with errors and stopped Recurring Task" for a Recurring Task or in "Completed with errors" for a Scheduled Task.

Example

You can view all re-encryption tasks by using the manage-tasks command:

./manage-tasks -h <OUD_INSTANCE> -p <ADMIN_PORT> -D "cn=Directory Manager" -j /local/password -n -s

Output

ReEncryptTask-7ec1bab7-d971-44bb-b780-ea5c803dcd4f ReEncrypt Completed with errors and stopped Recurring Task
ReEncryptTask-7ec1bab7-d971-44bb-b780-ea5c803dcd4f-20210830032400000 ReEncrypt Completed with errors
ReEncryptTask-7ec1bab7-d971-44bb-b780-ea5c803dcd4f-20210830032500000 ReEncrypt Completed with errors

You can view more information using the following command:

./manage-tasks -h <OUD_INSTANCE> -p <ADMIN_PORT> -D  "cn=Directory Manager" -j /local/password -n -i "ReEncryptTask-7ec1bab7-d971-44bb-b780-ea5c803dcd4f-20210830032400000"

The above command displays the log messages for the task and the entries that have failed during the run:

ReEncrypt Options
-----------------------------------------------------------------------
ds-task-reencrypt-failed-dn uid=user.1,ou=People,dc=example,dc=com
uid=user.5,ou=People,dc=example,dc=com
dc=example,dc=com:3,6,9
ds-task-reencrypt-backend-id userRoot
objectclass ds-recurring-task
ds-tasktopds-task-reencrypt
ds-task-reencrypt-creation-time 20210830032400Z
ds-task-reencrypt-batch-size 10

Last Log Message
------------------------------------------------------------------------------
[30/Aug/2021:03:24:00 +0000] severity="NOTICE" msgCount=11 msgID=9896350 message="ReEncrypt task
ReEncryptTask-7ec1bab7-d971-44bb-b780-ea5c803dcd4f-20210830032400000 finished execution"

In case of errors, it is recommended to look at the logs for root cause of the errors and re-schedule a new re-encryption task so that the failed entries are retried again for re-encryption.

If Reencryption (via Reencrypt Tasks) has been scheduled partially covering only few suffixes, a warning message gets logged in the server logs during server startup.

14.9.2 Encryption or Re-encryption of Existing Data Using Replication or Import

This approach requires OUD instance downtime to encrypt the existing data in a replicated topology. To apply encryption to all entries or the attribute data using replication, you need to perform the following steps.

1. Perform a pre-external-initialization on any one of the instances. See dsreplication.
2. Perform an off-line import either on all instances or on one instance, and then perform Binary copy to the other instances or dsreplication initialize. See import-ldif.
3. Perform a post-external-initialization on any one of the instances. See dsreplication.

14.9.3 Encryption or Re-encryption of Existing Data on Single Instance Using Export or Import

You can perform the encryption or re-encryption of existing data on single instance using export or import in a non-replicated topology.

1. Do one of the following:
   • If you want the existing data present in the back end to be configured for encryption, export the data using the LDIF script:

     export-ldif -n userRoot -l /data/export.ldif

     For more information about exporting to LDIF, see export-ldif
   • If you only want future modifications to consider the new encryption configuration, go to Step 4.
2. Perform the following steps to re-import data, and stop.
   1. Stop the server.

      stop-ds

   2. Import data.

      import-ldif -n userRoot -l /data/export.ldif

      For more information about importing from command line, see import-ldif.

      Note:

      Irrespective of the fact whether data is encrypted or not in the imported LDIF file, the import-ldif command saves the data in the back end as stated by the current server configuration. So, the import process allows you to encrypt or decrypt data as needed. For example, importing encrypted data in a server configured with no encryption allows you to store data unencrypted. In addition, if you import a clear LDIF file into a server configured for encryption, then it allows you to store data encrypted.

      The algorithm of the current configuration is always used. If you import an AES128 encrypted data set into the server with RC4 encryption configured, then data is re-encrypted and stored with RC4 configuration.

   3. Start the server.

      start-ds

      When you import data, then it also builds the indexes. Therefore, there is no need to perform step 4.
3. Rebuild indexes.

   If the suffix on which you want to configure encryption contains indexes for the impacted attributes, then rebuild those indexes. Run the following commands:

   For example, if there are some indexes associated with the postalAddress attribute, then rebuild index using the following command:

   rebuild-index -b dc=customers,dc=com -i postalAddress

   Similarly, if there are some indexes associated with the mail attribute, then rebuild index using the following command:

   rebuild-index -b dc=customers,dc=com -i mail

   For more information about rebuilding indexes, see rebuild-index.

14.10 Use Case Scenarios

This content applies only to OUD Bundle Patch 12.2.1.4.211008 and later releases.

You may have some replicated topology which may impact if attribute encryption is used, especially when certain releases of OUD contain newer encryption schemes. Consider the use case scenarios as follows:

• Mixed Replicated Topology Containing Multiple Versions of OUD Instances
• Replicated Topology with all OUD Instances Support Configured Encryption Scheme

.

14.10.1 Mixed Replicated Topology Containing Multiple Versions of OUD Instances

A mixed version topology consists of the latest version of OUD, which may contain newer encryption schemes which are not available in older version of OUD. In such a mixed version topology containing multiple versions of OUD, it is recommended that newer encryption schemes that are released in the latest product should be configured after all OUD instances are moved to the latest version. However, you can choose a combination of newer and older encryption schemes in such a mixed version topology.

This requires the value of the configuration property, use-defined-enc-algo-in-replication to be set to false. With this configuration, latest release of OUD server instance will generate changelog or modify events using AES-128 encryption algorithm which is understood by all older versions of OUD server.

For example, consider a scenario where OUD1 instance is created using an older version with data encryption algorithm AES-256 and OUD2 instance is created using a newer version of OUD with data encryption algorithm AES-256-GCM. In this topology OUD2 understands newly introduced encryption algorithm whereas OUD1 fails to decipher the newer encryption algorithms. Now, any change in OUD2 will generate the change-log events using AES-256-GCM algorithm and same is replicated to OUD1. OUD1 fail to decrypt the change-log that is encrypted using AES-256-GCM.

To avoid such compatibility issues in mixed mode change-log is encrypted using the default AES-128 algorithm provided the configuration property, use-defined-enc-algo-in-replication is set to false. Once all instances are moved to the latest version, the configuration property, use-defined-enc-algo-in-replication is set to true so that replication will use the latest configured encryption algorithm.

14.10.2 Replicated Topology with all OUD Instances Support Configured Encryption Scheme

The replicated topology may contain different versions of OUD. However, in this topology, all OUD instances support the configured encryption scheme. Administrator can set the value of the configuration property, use-defined-enc-algo-in-replication to true so that any change in encrypted attribute values will generate the modify or change-log that is encrypted using configured encryption algorithm. This change-log is interpreted by other OUD node in the replication topology and replay the same change.

.