This chapter discusses how to manage the data entries in your directory. It also describes how to set referrals and to encrypt attribute values.
When planning a directory deployment, you need to characterize the types of data that the directory will contain. Read the relevant chapters in the Sun Java System Directory Server Enterprise Edition 6.3 Deployment Planning Guide before creating entries and modifying the default schema.
You cannot modify your directory unless the appropriate access control instructions (ACIs) have been defined. For further information, see Chapter 7, Directory Server Access Control.
This chapter covers the following topics:
The best way to manage entries depends on the context:
If you mostly use DSCC for administration and you want to search or modify just a few entries, use DSCC. For more information about DSCC, see Directory Service Control Center Interface.
If you do not perform any administrative tasks on Directory Server and you want to search or modify just a few entries, use Directory Editor. For information about Directory Editor, see the Sun Java System Directory Editor 1 2005Q1 Installation and Configuration Guide.
If you want to search or modify a large number of entries, use the command-line utilities ldapmodify and ldapdelete.
DSCC enables you to view all readable unencrypted attributes of an entry and to edit its writable attributes. It also enables you to add and remove attributes, set multi-valued attributes, and manage the object classes of the entry. For more information about how to use DSCC to manage entries, see the DSCC online help. For more information about DSCC in general, see Directory Service Control Center Interface.
Directory Editor is an easy-to-use directory editing tool that enables administrators and end-users to search, create and edit data. This data is in the form of users, groups, and containers.
The ldapmodify and ldapdelete command-line utilities provide full functionality for adding, editing, and deleting your directory contents. You can use these utilities to manage both the configuration entries of the server and the data in the user entries. The utilities can also be used to write scripts to perform bulk management of one or more directories.
The ldapmodify and ldapdelete commands are used in procedures throughout this book. The following sections describe the basic operations that you will need to perform procedures. For more information about the ldapmodify and ldapdelete commands, see Sun Java System Directory Server Enterprise Edition 6.3 Reference.
Input to the command-line utilities is always in LDIF, and it can be provided either directly from the command-line or through an input file. The following section provides information about LDIF input, and subsequent sections describe the LDIF input for each type of modification.
For information about formatting LDIF input correctly, see the Guidelines for Providing LDIF Input in Sun Java System Directory Server Enterprise Edition 6.3 Reference.
The following sections describe these basic operations:
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
You can add one or more entries to the directory by using the -a option of ldapmodify. The following example creates a structural entry to contain users and then creates a user entry:
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: ou=People,dc=example,dc=com objectclass: top objectclass: organizationalUnit ou: People description: Container for user entries dn: uid=bjensen,ou=People,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetorgPerson uid: bjensen givenName: Barbara sn: Jensen cn: Babs Jensen telephoneNumber: (408) 555-3922 facsimileTelephoneNumber: (408) 555-4000 mail: bjensen@example.com userPassword: secret |
The -D and -w options give the bind DN and password, respectively, of a user with permissions to create these entries. The -a option indicates that all entries in the LDIF will be added. Then each entry is listed by its DN and its attribute values, with a blank line between each entry. The ldapmodify utility creates each entry after it is entered, and the utility reports any errors.
By convention, the LDIF of an entry lists the following attributes:
The DN of the entry.
The list of object classes.
The naming attribute (or attributes). This is the attribute used in the DN, and it is not necessarily one of the required attributes.
The list of required attributes for all object classes.
Any allowed attributes that you want to include.
When typing a value for the userPassword attribute, provide the clear text version of the password. The server will encrypt this value and store only the encrypted value. Be sure to limit read permissions to protect clear passwords that appear in LDIF files.
You can also use an alternate form of the LDIF that does not require the -a option on the command line. The advantage of this form is that you can combine entry addition statements and entry modification statements, as shown in the following example.
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: ou=People,dc=example,dc=com changetype: add objectclass: top objectclass: organizationalUnit ou: People description: Container for user entries dn: uid=bjensen,ou=People,dc=example,dc=com changetype: add objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetorgPerson uid: bjensen givenName: Barbara sn: Jensen cn: Barbara Jensen telephoneNumber: (408) 555-3922 facsimileTelephoneNumber: (408) 555-4000 mail: bjensen@example.com userPassword: secret |
The changetype: add keyword indicates that the entry with the given DN should be created with all of the subsequent attributes. All other options and LDIF conventions are the same as explained earlier in this section.
In both examples, you can use the -f filename option to read the LDIF from a file instead of from the terminal input. The LDIF file must contain the same format as used for the terminal input, depending upon your use of the -a option.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Use the changetype: modify keyword to add, replace, or remove attributes and their values in an existing entry. When you specify changetype: modify, you must also provide one or more change operations to indicate how the entry is to be modified. The three possible LDIF change operations are shown in the following example:
dn: entryDN changetype: modify add: attribute attribute: value... - replace: attribute attribute: newValue... - delete: attribute [attribute: value] ... |
Use a hyphen (-) on a line to separate operations on the same entry, and use a blank line to separate groups of operations on different entries. You can also give several attribute: value pairs for each operation.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
The following example shows how you can use the same add LDIF syntax to add values to existing multi-valued attribute and to attributes that do not yet exist:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify add: cn cn: Babs Jensen - add: mobile mobile: (408) 555-7844 |
This operation might fail and the server will return an error if any of the following are true:
The given value already exists for an attribute.
The value does not follow the syntax defined for the attribute.
The attribute type is not required or allowed by the entry’s object classes.
The attribute type is not multi-valued and a value already exists for it.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
The attribute;binary subtype indicates that attribute values must be transported over LDAP as binary data, regardless of their actual syntax. This subtype is designed for complex syntax that does not have LDAP string representations, such as userCertificate. The binary subtype should not be used outside of this purpose.
When used with the ldapmodify command, appropriate subtypes can be added to attribute names in any of the LDIF statements.
To enter a binary value, you may type it directly in the LDIF text or read it from another file. The LDIF syntax for reading it from a file is shown in the following example:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: version: 1 dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify add: userCertificate;binary userCertificate;binary:< file:///local/cert-file |
To use the :< syntax to specify a file name, you must begin the LDIF statement with the line version: 1. When ldapmodify processes this statement, it will set the attribute to the value that is read from the entire contents of the given file.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Language and pronunciation subtypes of attributes designate localized values. When you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:
attribute;lang-CC |
where attribute is an existing attribute type, and cc is the two-letter country code to designate the language. You may optionally add a pronunciation subtype to a language subtype to designate a phonetic equivalent for the localized value. In this case the attribute name is as follows:
attribute;lang-CC;phonetic |
To perform an operation on an attribute with a subtype, you must explicitly match its subtype. For example, if you want to modify an attribute value that has the lang-fr language subtype, you must include lang-fr in the modify operation as follows:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify add: homePostalAddress;lang-fr homePostalAddress;lang-fr: 34, rue de la Paix |
If the attribute value contains non-ASCII characters, they must be UTF-8 encoded.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
The following example shows how to change the value of an attribute by using the replace syntax in LDIF:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify replace: sn sn: Morris - replace: cn cn: Barbara Morris cn: Babs Morris |
All current values of the specified attributes are removed, and all given values are added.
After changing an attribute value, you can use the ldapsearch command to verify the change.
When you modify an attribute value, do not unintentionally include trailing spaces at the end of the value. Trailing spaces might result in the value appearing in base-64 encoding (such as 34xy57eg).
If the attribute value ends with a trailing space, the trailing space is encoded as part of the attribute value. When you verify the change using DSCC or the ldapsearch command, the value you see might be plain text, but it might also appear as base-64 encoded text. This depends on which Directory Server client you use.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
The following example shows how to delete an attribute entirely and to delete only one value of a multi valued attribute:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify delete: facsimileTelephoneNumber - delete: cn cn: Babs Morris |
When using the delete syntax without specifying an attribute: value pair, all values of the attribute are removed. If you specify an attribute: value pair, only that value is removed.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
To modify one value of a multi valued attribute with the ldapmodify command, you must perform two operations as shown in the following example:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify delete: mobile mobile: (408) 555-7845 - add: mobile mobile: (408) 555-5487 |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Use the ldapdelete command-line utility to delete entries from the directory. This utility binds to the directory server and deletes one or more entries based on their DN. You must provide a bind DN that has permission to delete the specified entries.
You cannot delete an entry that has children. The LDAP protocol forbids the situation where child entries would no longer have a parent. For example, you cannot delete an organizational unit entry unless you have first deleted all entries that belong to the organizational unit.
The following example shows only one entry in the organizational unit. This entry and then its parent entry can be deleted.
$ ldapdelete -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: uid=bjensen,ou=People,dc=example,dc=com ou=People,dc=example,dc=com |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
When using the ldapmodify utility, you can also use the changetype: delete keywords to delete entries. All of the same limitations apply as when using ldapdelete, as described in the previous section. The advantage of using LDIF syntax for deleting entries is that you can perform a mix of operations in a single LDIF file.
The following example performs the same delete operations as the previous example:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - dn: uid=bjensen,ou=People,dc=example,dc=com changetype: delete dn: ou=People,dc=example,dc=com changetype: delete |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.
For more information about using ldapsearch, common ldapsearch options, accepted formats, and examples, refer to Sun Java System Directory Server Enterprise Edition 6.3 Reference.
This procedure uses the modify DN operation. Before starting this operation, ensure that you are familiar with the section Guidelines and Limitations for Using the Modify DN Operation.
For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.
When modifying the DNs of entries that are a uniquemember of a group, you must have the referential integrity plug-in enabled. Referential integrity ensures that the group members get adjusted when the entry is moved. For information about how to enable and configure the referential integrity plug-in, see To Configure the Referential Integrity Plug-In.
If you are moving an entry from one parent to another, extend ACI rights on the parent entries.
On the current parent entry of the entry to be moved, ensure that the ACI allows the export operations by using the syntax allow (export ...)
On the future parent entry of the entry to be moved, ensure that the ACI allows the import operations. by using the syntax allow (import ...)
For information about using ACIs, see Chapter 7, Directory Server Access Control.
Ensure that the modify DN operation is enabled globally, or at least for the suffix or suffixes that will be affected by the move operation.
To ensure compatibility with previous releases of Directory Server, the modify DN operation is not enabled by default.
If you have already enabled the modify DN operation previously, go to the next step.
To enable the modify DN operation globally for a server, use this command:
$ dsconf set-server-prop -h host -p port moddn-enabled:on |
Run the ldapmodify command.
This step uses the modify DN operation. Do one of the following:
Move the entry.
For example, the following command moves the entry uid=bjensen from the subtree for contractors, ou=Contractors,dc=example,dc=com to the subtree for employees, ou=People,dc=example,dc=com:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=Contractors,dc=example,dc=com changetype: modrdn newrdn: uid=bjensen deleteoldrdn: 0 newsuperior: ou=People,dc=example,dc=com |
Rename the entry.
For example, the following command renames the entry uid=bbjensen to uid=bjensen:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bbjensen,ou=People,dc=example,dc=com changetype: modrdn newrdn: uid=bjensen deleteoldrdn: 1 |
Pay attention to the following attributes when writing the LDIF statement:
dn - Specifies the entry to rename or move.
changetype: modrdn - Specifies that a modify DN operation is to be used.
newrdn - Gives the new naming attribute.
deleteoldrdn - Indicates whether the previous naming attribute should be removed from the entry (1 is yes, 0 is no).
Note that you cannot remove a naming attribute from the entry if that attribute is obligatory in the entry definition.
newsuperior - Specifies the new superior attribute of the entry.
For information about the ldapmodify command and its options, see the ldapmodify(1) man page.
If you encounter resource limit errors when moving or renaming subtrees that contain a large number of entries, increase the number of locks that can be used by the database.
$ dsconf set-server-prop -h host -p port db-lock-count:value |
If you modify this property, you must restart the server for the change to take effect.
When you use the modify DN operation, as described in the previous section, use the guidelines described in the following sections.
Do not use the modify DN operation to move an entry from one suffix to another suffix, or to rename or move the root suffix.
Ensure that you are running Directory Server 5.2 2005Q1 or later. The modify DN operation cannot be used on versions of Directory Server prior to Directory Server 5.2 2005Q1.
Do not use the entryid operational attribute in your application because it is reserved for internal use only. The entryid attribute of an entry can change when an entry is moved.
Enable the modify DN operation globally for all suffixes on a server, or individually on each suffix where you wish to run the operation. By default the modify DN operation is disabled.
Extend the ACI rights on each suffix where you wish to run the modify DN operation. The Import access right allows an entry to be imported to the specified DN. The Export access right allows an entry to be exported from the specified DN.
Before performing a modify DN operation, ensure that the operation would not break client authentication. If you move an entry that refers to a client certificate, client authentication will break. After moving an entry, validate your certificates.
Before performing a modify DN operation, ensure that the operation would not break your application. The rename or move of an entry can affect several suffixes, or can change the following characteristics of the entry:
The scope of a filtered role of an entry.
The nested role of an entry, where the nested role contains a filtered role.
The dynamic group membership of an entry.
Using the modify DN operation without complying with the following requirements can break replication and bring down your directory service.
Ensure that all servers in your replication topology are running at least Directory Server 5.2. You cannot use the modify DN operation on versions of Directory Server prior to Directory Server 5.2.
Enable the modify DN operation on all servers in your replication topology. If the modify DN operation is supported on the master server but not on the consumer server, replication will fail. A message similar to the following will be written to the error log on the supplier server:
Unable to start a replication session with MODDN enabled
To restart replication, reconfigure the replication topology to enable the modify DN operation on all servers. and then start a replication session in one of the following ways:
By following the instructions in To Force Replication Updates.
By changing an entry on the supplier server. The change is replicated to the consumer servers.
Enable and configure the referential integrity plug-in on all master replicas in the topology. This action ensures that the server maintains referential integrity for groups and roles. For information about how to enable and configure the referential integrity plug-in, see To Configure the Referential Integrity Plug-In.
After performing a modify DN operation, allow time for the referential integrity plug-in to replicate its changes.
You can use referrals to tell client applications which server to contact if the information is not available locally. Referrals are pointers to a remote suffix or entry that Directory Server returns to the client, in place of a result. The client must then perform the operation again on the remote server named in the referral.
Redirection occurs in three cases:
When a client application requests an entry that does not exist on the local server, and the server has been configured to return the default referral.
When an entire suffix has been disabled for maintenance or security reasons.
The server will return the referrals defined by that suffix. The suffix-level referrals are described in Setting Referrals and Making a Suffix Read-Only. Read-only replicas of a suffix also return referrals to the master servers when a client requests a write operation.
When a client specifically accesses a smart referral.
A smart referral is an entry that you create. The server will return the referral that the smart referral defines.
In all cases, a referral is an LDAP URL that contains the host name, port number, and optionally a DN on another server. For example, ldap://east.example.com:389.
For conceptual information about how you can use referrals in your directory deployment, see the Sun Java System Directory Server Enterprise Edition 6.3 Deployment Planning Guide.
The following sections describe the procedures for setting your directory’s default referrals and for creating and defining smart referrals.
Default referrals are returned to client applications that submit operations on a DN that is not contained on a suffix maintained by your Directory Server. The server will return all referrals that are defined, but the order in which they are returned is not defined.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Use the dsconf command-line utility to set one or more default referrals.
$ dsconf set-server-prop -h host -p port suffix-DN referral-url:referral-URL |
For example:
$ dsconf set-server-prop -h host1 -p 1389 dc=example,dc=com \ referral-url:ldap://east.example.com:1389 |
Smart referrals allow you to map a directory entry or a directory tree to a specific LDAP URL. Using smart referrals, you can refer client applications to a specific server or to a specific entry on a specific server.
Often, a smart referral points to an actual entry with the same DN on another server. However, you may define the smart referral to any entry on the same server or on a different server. For example, you can define the entry with the following DN to be a smart referral:
uid=bjensen,ou=People,dc=example,dc=com |
The smart referral points to another entry on the server east.example.com:
cn=Babs Jensen,ou=Sales,o=east,dc=example,dc=com |
The way the directory uses smart referrals conforms to the standard specified in section 4.1.10 of RFC 4511 (http://www.ietf.org/rfc/rfc4511.txt).
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
To create a smart referral, create an entry with referral and extensibleObject object classes.
The referral object class allows the ref attribute that is expected to contain an LDAP URL. The extensibleObject object class allows you to use any schema attribute as the naming attribute, in order to match the target entry.
For example, to define the following entry to return a smart referral instead of the entry uid=bjensen, use this command:
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: referral uid: bjensen ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Sales,o=east,dc=example,dc=com |
Any information after a space in an LDAP URL is ignored by the server. Thus, you must use %20 instead of spaces in any LDAP URL that you intend to use as a referral. Other special characters must be escaped.
After you have defined the smart referral, modifications to the uid=bjensen entry will actually be performed on the cn=Babs Jensen entry on the other server. The ldapmodify command will automatically follow the referral, for example:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: replace replace: telephoneNumber telephoneNumber: (408) 555-1234 |
(Optional) To modify the smart referral entry, use the -M option of ldapmodify:
$ ldapmodify -M -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: uid=bjensen,ou=People,dc=example,dc=com changetype: replace replace: ref ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Marketing,o=east,dc=example,dc=com |
Directory Server allows you to check the integrity of your attributes whenever you perform the following operations:
Importing data using dsadm import or dsconf import.
Using LDAP or DSML to add entries, modify entries, or modify the DN of an entry.
The checks ensure that the attribute values conform to IETF recommendations. All nonconforming attributes are rejected and logged in the errors log. The log messages include the connection and operation ID, if applicable.
By default, the server does not automatically check the syntax of the previously mentioned operations. If you want to turn syntax checking on, use the following procedure.
Syntax checking is not the same as schema checking. For information about schema checking, see Managing Schema Checking.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
To turn on automatic syntax checking, use this command:
$ dsconf set-server-prop -h host -p port check-syntax-enabled:on |
By default, the server maintains special attributes for newly created or modified entries, as specified in the LDAP v3 specification. These special attributes are stored on the entry in the suffix and include the following:
creatorsName — the DN of the user who initially created the entry.
createTimestamp — the timestamp for when the entry was created, in GMT format.
modifiersName — the DN of the user who last modified the entry.
modifyTimestamp — the timestamp for when the entry was modified, in GMT format.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Turning off entry modification tracking results in non-compliant data. As many applications rely on these attributes and as disabling this feature results in only minimal performance gains, we recommend that you do not turn off entry modification tracking.
Turn off entry modification tracking for the server.
$ dsconf set-server-prop -h host -p port suffix-DN mod-tracking-enabled:off |
Attribute encryption protects sensitive data while it is stored in the directory. Attribute encryption allows you to specify that certain attributes of an entry are stored in an encrypted format. This prevents data from being readable while stored in database files, backup files, and exported LDIF files.
With this feature, attribute values are encrypted before they are stored in the Directory Server database, and decrypted back to their original value before being returned to the client. You must use access controls to prevent clients from accessing such attributes without permission, and SSL to encrypt the attribute values when in transit between the client and Directory Server. For an architectural overview of data security in general and attribute encryption in particular, see Sun Java System Directory Server Enterprise Edition 6.3 Reference.
Attribute encryption is active only when SSL is configured and enabled on the server. However, no attributes are encrypted by default. Attribute encryption is configured at the suffix level, which means that an attribute is encrypted in every entry in which it appears in the suffix. If you want to encrypt an attribute in an entire directory, you must enable encryption for that attribute in every suffix.
Attribute encryption affects all data and index files associated with a suffix. If you modify the encryption configuration of an existing suffix, you must first export its contents, make the configuration change, and then re-import the contents. DSCC can help you perform these steps. For more information about using DSCC, see Directory Service Control Center Interface.
For additional security, when turning on encryption for any attribute, you should manually delete the database cache files and database log file that might still contain unencrypted values. The procedure for deleting these files is described in To Configure Attribute Encryption.
You should enable any encrypted attributes before loading or creating data in a new suffix.
If you choose to encrypt an attribute that some entries use as a naming attribute, values that appear in the DN will not be encrypted. Values that are stored in the entry will be encrypted.
Even though you can select the userPassword attribute for encryption, no real security benefit is realized unless the password needs to be stored in the clear. Such is the case for DIGEST-MD5 SASL authentication. If the password already has an encryption mechanism defined in the password policy, further encryption provides little additional security, but, it will impact the performance of every bind operation.
When in storage, encrypted attributes are prefaced with a cipher tag that indicates the encryption algorithm used. An encrypted attribute using the DES encryption algorithm would appear as follows:
{CKM_DES_CBC}3hakc&jla+=snda% |
When importing data online with a view to encrypting it, you will already have provided the key database password to authenticate to the server and will not be prompted a second time. If you are importing data offline, Directory Server will prompt you for the password before it allows you to encrypt the data you are importing. When decrypting data (a more security-sensitive operation), Directory Server automatically prompts you for the key database password, regardless of whether the export operation is online or offline. This provides an additional security layer.
As long as the certificate or private key does not change, the server will continue to generate the same key. Thus, data can be transported (exported then imported) from one server instance to another, provided both server instances have used the same certificate.
While attribute encryption offers increased data security, it does impact system performance. Think carefully about which attributes require encryption, and encrypt only those attributes that you consider to be particularly sensitive.
Because sensitive data can be accessed directly through index files, the index keys that correspond to the encrypted attributes must be encrypted to ensure that the attributes are fully protected. Given that indexing already has an impact on Directory Server performance (without the added cost of encrypting index keys), configure attribute encryption before data is imported or added to the database for the first time. This procedure will ensure that encrypted attributes are indexed as such from the outset.
Consider the following when implementing the attribute encryption feature:
As a general best practice when modifying attribute encryption configuration, you should export your data, make the configuration changes, and then import the newly configured data.
This will ensure that all configuration changes are taken into account in their entirety, without any loss in functionality. Failing to do so could result in some functionality loss and thus compromise the security of your data.
Modifying attribute encryption configuration on an existing database can have a significant impact on system performance.
For example, imagine that you have a database instance with existing data. The database contains previously stored entries with an attribute called mySensitiveAttribute. The value of this attribute is stored in the database and in the index files in clear text, . If you later decide to encrypt the mySensitiveAttribute attribute, all the data in the database instance must be exported and re-imported into the database to ensure that the server updates the database and index files with the attribute encryption configuration. The resulting performance impact could have been avoided had the attribute been encrypted from the beginning.
When exporting data in decrypted format, the export is refused if an incorrect password is used.
As a security measure, the server prompts users for passwords if they want to export data in decrypted format. Should users provide an incorrect password, the server refuses the decrypted export operation. Passwords can be entered directly or by providing the path to a file that contains the password. Note that this file has the same syntax as the SSL password file. See Configuring the Certificate Database Password.
To be able to use the dsconf command with the -–decrypt-attr option, set password prompt must be set to on and you must have chosen a certificate database password as described in Configuring the Certificate Database Password.
Algorithm changes are supported, but the result can be lost indexing functionality if they are not made correctly.
To change the algorithm used to encrypt data, export the data, modify the attribute encryption configuration, and then import the data. If you do not follow this procedure, the indexes that were created on the basis of the initial encryption algorithm will no longer function.
Because the encrypted attributes are prefaced with a cipher tag that indicates the encryption algorithm used, the internal server operations take care of importing the data. Directory Server therefore enables you to export data in encrypted form before making the algorithm change.
Changing the server’s SSL certificate results in your not being able to decrypt encrypted data.
The server’s SSL certificate is used by the attribute encryption feature to generate its own key, which is then used to perform the encryption and decryption operations. Thus, the SSL certificate is required to decrypt encrypted data. If you change the certificate without decrypting the data beforehand, you cannot decrypt the data. To avoid this, export your data in decrypted format, change the certificate, and then re-import the data.
To transport data in encrypted format, that is, to export and import it from one server instance to another, both server instances must use the same certificate.
For information, see “Encrypting Attribute Values” in the Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
If the suffix on which you want to configure attribute encryption contains any entries whatsoever, you must first export the contents of that suffix to an LDIF file.
If the suffix contains encrypted attributes and you plan to re-initialize the suffix using the exported LDIF file, you can leave the attributes encrypted in the exported LDIF .
To enable encryption for an attribute, use this command:
$ dsconf create-encrypted-attr -h host -p port suffix-DN attr-name cipher-name |
where cipher-name is one of the following:
des - DES block cipher
des3 - Triple-DES block cipher
rc2 - RC2 block cipher
rc4 - RC4 stream cipher
For example:
$ dsconf create-encrypted-attr -h host1 -p 1389 dc=example,dc=com uid rc4 |
To return an encrypted attribute to its original state, use this command:
$ dsconf delete-encrypted-attr -h host -p port suffix-DN attr-name |
If you have changed the configuration to encrypt one or more attributes, and these attributes had values before the import operation, clear the database cache and remove the log.
Any unencrypted values will not be visible in the database cache and database log.
If you delete these files, you will lose some tracking information. In addition, after you delete these files, the server will be in recovery mode, and might take a long time to restart.
To clear the database cache and remove the log:
Stop Directory Server as described in Starting, Stopping, and Restarting a Directory Server Instance.
As root or a user with administrator privileges, delete the database cache files from your file system.
# rm instance-path/db/__db.* |
Delete the database log file from your file system.
# rm instance-path/db/log.0000000001 |
Restart Directory Server.
The server will automatically create new database cache files. Performance of operations in this suffix might be slightly impacted until the cache is filled again.
Initialize the suffix with an LDIF file as described in Initializing a Suffix.
As the file is loaded and the corresponding indexes are created, all values of the specified attributes will be encrypted.