One of the biggest changes that we’ve made in this release is that we’ve deprecated support for the TLSv1 and TLSv1.1 protocol versions in accordance with RFC 8996. By default, the LDAP SDK will prefer using TLSv1.3, but it can fall back to using TLSv1.2 if the newer protocol is not supported by the client JVM or by the directory server. The older TLSv1 and TLSv1.1 protocol versions can still be enabled if necessary (either programmatically or by setting system properties), but given that they are no longer considered secure, and given that TLSv1.2 became an official standard over twelve years ago, the far better option would be to use a directory server release from sometime in the last decade.
We have also updated the set of TLS cipher suites that the LDAP SDK will use by default. The default set of enabled cipher suites no longer includes those that rely on the SHA-1 message digest algorithm (which is no longer considered secure) or those that rely on RSA key exchange (which doesn’t support forward secrecy and could allow an observer to decrypt the communication if the server certificate’s private key becomes compromised; note that deprecating RSA key exchange doesn’t affect the ability to interact with servers that use certificates with RSA key pairs). If necessary, you can override the set of cipher suites that the LDAP SDK uses by default, either programmatically or with system properties.
You can find the complete release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html. Other notable changes in this release include:
- We fixed an issue that could cause the LDAP SDK to use the set of TLS cipher suites enabled in the JVM by default rather than a recommended set identified by the LDAP SDK itself. This could potentially result in using weaker encryption for secure connections.
- We updated the logic that the LDAP SDK uses when deciding which characters to escape when generating the string representation of a DN or RDN. Previously, it would always escape all non-ASCII characters. Now, the LDAP SDK will no longer escape non-ASCII characters that it believes are displayable (including the Unicode letter, number, punctuation, and symbol character types). If desired, you can override this behavior either programmatically or with a system property.
- We updated the logic that the LDAP SDK uses when deciding which data should be base64-encoded when generating the LDIF representation of an entry. Previously, it would not always base64-encode data with ASCII control characters (other than NUL, LF, and CR, which must always be base64-encoded). Now, it will always base64-encode values with ASCII control characters by default. It can also be configured to optionally not base64-encode values with non-ASCII characters (which technically violates the LDIF specification but may be useful when displaying to an end user). You can override the LDAP SDK’s base64-encoding strategy either programmatically or with a system property.
- We updated the LDIF reader to make it possible to disable support for parsing LDAP controls. By default, the LDAP SDK supports LDIF change records that include LDAP controls as described in RFC 2849. However, this can cause a problem in a rare corner case if a record represents an entry rather than a change record and the first attribute in the LDIF representation of that entry is named “control”. If you attempt to read that record as a generic LDIF record or as a change record with defaultAdd set to true (rather than reading it specifically as an entry), then the LDIF reader will attempt to parse that attribute as an LDIF control. If you have LDIF records that represent entries in which the first attribute may be named “control”, if you are reading them as generic LDIF records or as LDIF change records with defaultAdd set to true, and if you don’t have any LDIF change records that legitimately do include LDAP controls, then you can update the LDIF reader to disable support for controls so that it will interpret a leading “control” element as an attribute rather than a change record with a control.
- We updated PKCS11KeyManager to make it easier to use certificate chains stored in PKCS #11 tokens without needing to alter the JVM configuration. Previously, if you wanted to use PKCS #11, you either had to modify a configuration file within the JVM installation (which may not always be feasible), or you had to write your own code to load the provider before trying to use the key manager. You can now supply a provider configuration file when creating a PKCS #11 key manager, and it will ensure that the necessary provider is loaded and registered with the JVM.
- We updated the manage-certificates tool to support interacting with PKCS #11 tokens. Previously, the tool only supported certificates in JKS, PKCS #12, and BCFKS key stores. When using a PKCS #11 token, you must use the --keyStore argument with a value that is the path to the provider configuration file and the --keyStoreFormat argument with a value of PKCS11.
- We updated the manage-certificates tool to add a new copy-keystore subcommand with support for copying some or all of the information in one key store to another key store of the same or a different type. This can allow you to merge key stores or convert a key store from one type to another (for example, JKS to PKCS #12).
- We updated the manage-certificates tool to add optional --output-file and --output-format arguments to the generate-self-signed-certificate subcommand. This allows you to generate and export a self-signed certificate in one step rather than requiring a separate command to export a certificate after generating it.
- We updated the manage-certificates tool to allow interacting with BCFKS key stores even when the LDAP SDK is not operating in FIPS 140-2-compliant mode. Note that the necessary FIPS-compliant Bouncy Castle libraries must already be in the classpath.
- We updated the manage-certificates tool to display the key store type when using the list-certificates subcommand.
- We updated the in-memory-directory-server command-line tool to add a new --doNotGenerateOperationalAttributes argument that will prevent the server from maintaining operational attributes like entryDN, entryUUID, subschemaSubentry, creatorsName, createTimestamp, modifiersName, and modifyTimestamp.
- We updated the FileArgument class to provide better support for interacting with files that are potentially encrypted or compressed. The getFileLines, getNonBlankFileLines, and getFileBytesMethods have been updated so that they can transparently handle reading from gzip-compressed files. Further, for tools that are running as part of a Ping Identity Directory Server installation, they can transparently handle reading from files that are encrypted with a key from the server’s encryption settings database. Also, a new getFileInputStream method has been provided that can retrieve an input stream to use when reading from the target file, including cases in which the file is compressed or encrypted.
- We added a new ThreadLocalSecureRandom class that can be used to maintain a set of per-thread SecureRandom instances that can be used without concerns around synchronization or contention.
- We updated the documentation to include the latest revisions of the draft-coretta-x660-ldap, draft-ietf-kitten-password-storage, and draft-melnikov-scram-2fa drafts in the set of LDAP-related specifications.
Changes specific to running in FIPS 140-2-compliant mode include:
- We have updated the LDAP SDK so that it will use the Bouncy Castle FIPS-compliant SecureRandom instance in hybrid mode, which helps reduce the chance that it will encounter severe performance issues as a result of depleted entropy on the underlying system. However, in some cases, it may still be necessary to either use a hardware random number generator or a software entropy supplementing daemon (like rngd) to prevent blocking due to a lack of entropy.
- We have updated the LDAP SDK to make it possible to customize the set of providers that will be allowed when running in FIPS 140-2-compliant mode. You can perform this customization programmatically or with a system property.
- We have updated the command-line tool framework to check whether the LDAP SDK is running in FIPS 140-2-compliant mode upon invoking the tool constructor. This can help prevent cases in which the tool may inadvertently perform operations with a non-FIPS-compliant provider.
Changes specific to using the LDAP SDK in conjunction with the Ping Identity Directory Server include:
- We updated the collect-support-data tool to allow using the --keyStoreFormat and --trustStoreFormat arguments when invoking the server-side version of the tool. Previously, you could only use these arguments in conjunction with the --useRemoteServer argument. This change only applies when using the 126.96.36.199 or later release of the Ping Identity Directory Server.
- We added client-side support for a new administrative task that can be used to safely remove an object class definition from the server schema. The task will ensure that the object class is not in use before attempting to remove it, and it will clean up any references to the object class that may no longer be necessary (for example, in a backend’s entry compaction dictionary).