We have just released version 6.0.8 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository.

Note that this is the last release for which the LDAP SDK source code will be maintained in both the GitHub and SourceForge repositories. The LDAP SDK was originally hosted in a subversion repository at SourceForge, but we switched to GitHub as the primary repository a few years ago. We have been relying on GitHub’s support for accessing git repositories via subversion to synchronize changes to the legacy SourceForge repository, but that support is being discontinued. The SourceForge project will continue to remain available for the discussion forum, mailing lists, and release downloads, but up-to-date source code will only be available on GitHub.

You can find the release notes for the 6.0.8 release (and all previous versions) at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes:

• We added a DN.getDNRelativeToBaseDN method that can be used to retrieve the portion of DN that is relative to a given base DN (that is, the portion of a DN with the base DN stripped off). For example, if you provide it with a DN of “uid=test.user,ou=People,dc=example,dc=com” and a base DN of “dc=example,dc=com”, then the method will return “uid=test.user,ou=People”.

• We added LDAPConnectionPool.getServerSet and LDAPThreadLocalConnectionPool.getServerSet methods that can be used to retrieve the server set that the connection pool uses to establish new connections for the pool.

• We updated the Filter class to alternative methods with shorter names for constructing search filters from their individual components. For example, as an alternative to calling the Filter.createANDFilter method for constructing an AND search filter, you can now use Filter.and, and as an alternative to calling Filter.createEqualityFilter, you can now use Filter.equals. The older versions with longer method names will remain available for backward compatibility.

• We added support for encrypted PKCS #8 private keys, which require a password to access the private key. The PKCS8PrivateKey class now provides methods for creating the encrypted PEM representation of the key, and the PKCS8PEMFileReader class now has the ability to read encrypted PEM files. We also updated the manage-certificates tool so that the export-private-key and import-certificate subcommands now support encrypted private keys.

• We updated PassphraseEncryptedOutputStream to use a higher key factory iteration count by default. When using the strongest available 256-bit AES encryption, it now follows the latest OWASP recommendation of 600,000 PBKDF2 iterations. You can still programmatically explicitly specify the iteration count when creating a new output stream if desired, and we have also added system properties that can override the default iteration count without any code change.

• We added a PassphraseEncryptedOutputStream constructor that allows you to provide a PassphraseEncryptedStreamHeader when creating a new instance of the output stream. This will reuse the secret key that was already derived for the provided stream header (although with newly generated initialization vector), which can be significantly faster than deriving a new secret key from the same passphrase.

• We added a new ObjectTrio utility class that can be useful in cases where you need to reference three typed objects as a single object (for example, if you want a method to be able to return three objects without needing to define a new class that encapsulates those objects). This complements the existing ObjectPair class that supports two typed objects.

• We updated the documentation to include RFC 9371 in the set of LDAP-related specifications. This RFC formalizes the process for requesting a private enterprise number (PEN) to use as the base object identifier (OID) for your own definitions (e.g., for use in defining custom attribute types or object classes). The OID-related documentation has also been updated to provide a link to the IANA site that you can use to request an official base OID for yourself or your organization.

• We updated the documentation to include the latest revisions of draft-howard-gssapi-aead, draft-ietf-kitten-scram-2fa, draft-melnikov-scram-bis, and draft-reitzenstein-kitten-opaque in the set of LDAP-related specifications.

We have just released version 6.0.7 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

• We fixed a bug in the SearchResultEntry.equals method that could prevent a SearchResultEntry from matching other types of Entry objects.

• We fixed a bug in the Entry.applyModifications method that could cause it to fail with a NOT_ALLOWED_ON_RDN result if the provided entry was missing one or more of the attribute values used in its RDN.

• We fixed a bug in the argument parser’s support for mutually dependent arguments with a set containing more than two arguments. Previously, the constraint would have been satisfied if at least two of the arguments were provided, rather than requiring all of them to be provided.

• We added JSONObject methods for retrieving fields by name using case-insensitive matching (by default, JSON field names are treated in a case-sensitive manner). Because it is possible that a JSON object will have multiple fields with the same name when using case-insensitive matching, there are a few options for indicating how such conflicts should be handled, including only returning the first match, returning a map with all matching fields, or throwing an exception if there are multiple matches.

• We updated the set of LDAP-related specifications to include the latest version of the draft-schmaus-kitten-sasl-ht proposal.

We have just released version 6.0.6 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

General Updates

• We fixed an issue that could cause request failures when closing a connection operating in asynchronous mode with outstanding operations.

• We fixed an issue that could interfere with the ability to get a default SSLContext on Java 17 when running in FIPS 140-2-compliant mode.

• We updated LDAPConnectionOptions to add support for a new system property that can enable certificate hostname verification by default without any code changes.

• We updated the LDAP command-line tool framework to add a new --verifyCertificateHostnames argument to enable hostname verification when performing TLS negotiation.

• We improved the class-level Javadoc documentation for the SSLUtil class to provide a better overview of TLS protocol versions, TLS cipher suites, key managers, trust managers, and certificate hostname verification, and to provide better examples that illustrate best practices for establishing secure connections.

• We fixed an issue in the JNDI compatibility support for controls, as well as extended requests and responses. Even though the implementation was based on the JNDI documentation, it appears that at least OpenJDK implementations do not abide by that documentation. The LDAP SDK is now compatible with the observed behavior rather than the documentation, although a system property can be used to revert to the former behavior.

• We updated the SearchRequest class to add constructors that allow you to provide the search base DN with a DN object (as an alternative to existing constructors that allow you to specify it as a String).

• We fixed an issue in the command-line tool framework in which an Error (for example, OutOfMemoryError) could cause the tool to report a NullPointerException rather than information about the underlying error.

• We fixed an issue in the IA5 argument value validator that could allow it to accept argument values with non-ASCII characters.

• We fixed an issue in the DNS hostname argument value validator that could prevent it from properly validating the last component of a fully qualified domain name, or the only component of an unqualified name.

• We updated the identify-references-to-missing-entries tool to provide an option to generate an LDIF file with changes that can be used to remove identified references.

• We updated the SelfSignedCertificateGenerator class to perform better validation for the subject alternative DNS names that it includes in a certificate.

• We updated the manage-certificates generate-self-signed-certificate command to rename the --replace-existing-certificate argument to be --use-existing-key-pair. The former argument name still works, but it is hidden from the usage.

• We included a native-image/resource-config.json file in the LDAP SDK jar file manifest, which can be used by the GraalVM native-image tool to ensure that appropriate resource files are included in the resulting image.

Updates Specific to Use With the Ping Identity Directory Server

• * We updated the summarize-access-log tool to report on many more things, including the most common IP addresses for failed bind attempts, the most consecutive failed binds, information about work queue wait times, information about request and response controls, the number of components in search filters, and search filters that may indicate injection attempts.

• We updated support for the audit data security administrative task to make it possible to specify the number and/or age of previous reports to retain.

• We fixed issues that prevented specifying the criticality of the administrative operation and join request controls.

We have just released version 6.0.5 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

General Updates:

• We fixed an issue that could occasionally cause the LDAP SDK to hide the actual cause of a StartTLS failure by using information from a second, less useful exception.

• We fixed an issue that could cause the ldifsearch tool to display a malformed message when the first unnamed trailing argument was expected to be a search filter but could not be parsed as a valid filter.

• We improved support for validating and comparing values using the telephone number syntax. Previously, we used a loose interpretation of the specification, which would consider any printable string (including strings without any digits) to be valid, and would only ignore spaces and hyphens when comparing values. You can now configure varying levels of strictness (either programmatically or using system properties), including requiring at least one digit or strict conformance to the X.520 specification. You can also configure it to ignore all non-digit characters when comparing values, and this is now the default behavior.

• We fixed a bug in which the ldapcompare tool did not properly close its output file if one was configured. The output file does get automatically closed when the tool exits so it’s not an issue when running ldapcompare from the command line, but this can cause problems if the tool is invoked programmatically from another application.

• We fixed an issue with the tool properties file created using the --generatePropertiesFile argument in command-line tools that support it. The generated properties file did not properly escape backslash, carriage return, line feed, or form feed characters.

Updates Specific to Use With the Ping Identity Directory Server:

• We added support for encoding controls to JSON objects, and for decoding JSON objects as controls. There is a generic JSON representation that will work for any type of control (in which the value is provided as the base64-encoded representation of the raw value used in the LDAP representation of the control), but most controls provided as part of the LDAP SDK also support a more user-friendly representation in which the components of the value are represented in a nested JSON object.

• We added client-side support for a new JSON-formatted request control that can be used to send request controls to a Ping Identity Directory Server with the controls encoded as JSON objects rather than a raw LDAP representation. We also added support for a JSON-formatted response control that can be used to receive JSON-encoded response controls from the server.

• We updated the ldapsearch and ldapmodify command-line tools to add a --useJSONFormattedRequestControls argument that will cause any request controls to be sent using a JSON-formatted request control, and it will cause any response controls returned by the server to be embedded in a JSON-formatted response control.

• We fixed an issue with the way that the parallel-update tool created assured replication request controls when an explicit local or remote assurance level was specified. Previously, it would only specify a minimum assurance level without specifying a maximum level, which could cause the server to use a higher assurance level than requested by the client.

• We updated the topology registry trust manager to allow trusting a certificate chain if either the peer certificate or any of its issuers is found in the server’s topology registry. Previously, it would only trust a certificate chain if the peer certificate itself was found in the topology registry, and having an issuer certificate was not sufficient. The former behavior is still available with a configuration option.

• We updated the topology registry trust manager to make it possible to ignore the certificate validity window for peer and issuer certificates. The validity window is still respected by default, but if the trust manager is configured to ignore it, then a certificate chain may be trusted even if the peer or an issuer certificate is expired or not yet valid.

We have just released version 6.0.4 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

General Updates:

• We fixed an issue with the Filter.matchesEntry method that could cause it to throw an exception rather than returning an appropriate Boolean result when evaluating an AND or an OR filter in which one of the nested elements used inappropriate matching (for example, if the assertion value did not conform to the syntax for the associated attribute type).

• We fixed an issue with the way that decodeable controls are registered with the LDAP SDK. Under some circumstances, a thread could become blocked while attempting to create a new control.

• We updated the JVM-default trust manager to properly check for the existence of a “jssecacerts” trust store file in accordance with the JSSE specification. It had previously only looked for a file named “cacerts”.

• We updated the logic used to select the default set of supported cipher suites so that it will no longer exclude suites with names starting with “SSL_” by default on JVMs with a vendor string that includes “IBM”. IBM JVMs appear to use the “SSL_” prefix for some or all cipher suites, including those that are not associated with TLS protocols rather than a legacy SSL protocol. We also added a TLSCipherSuiteSelector.setAllowSSLPrefixedSuites method that can be used to override the default behavior.

• We updated the LDIF reader to support reading modifications with attribute values read from a file referenced by URL. This was previously supported when reading LDIF entries or add change records, but it had been overlooked for LDIF modify change records.

• We updated the LDIF reader so that it no longer generates comments attempting to clarify the contents of base64-encoded values if the value is longer than 1,000 bytes.

• We updated the documentation to include the latest versions of the draft-behera-ldap-password-policy, draft-coretta-x660-ldap, and draft-ietf-kitten-scram-2fa specifications.

Updates Specific to Use With the Ping Identity Directory Server:

• We added a new API for parsing access log messages generated by the server. The new API supports both text-formatted and JSON-formatted log messages, whereas the previous version only supported messages in the default text (“name=value”) format.

• We updated the summarize-access-log tool (which can be used to perform basic analysis of server access log files) to add support for JSON-formatted log files.

• We added support for retrieving and parsing X.509 certificate monitor entries.

• We added client-side support for an administrative task that can cause the server to immediately refresh any cached certificate monitor data. The server will automatically refresh the cache every minute, but the task can be used to cause an immediate refresh.

We have just released version 6.0.3 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

General Updates:

• We fixed an issue with the round-robin server set that could cause it to select some servers with a higher frequency than others in the event that one or more of the servers become unavailable.

• We fixed a potential race condition that could leave a background Timer thread running if a connection was closed while waiting for a response to a request issued via the asynchronous API.

• We fixed an issue in which the in-memory directory server could incorrectly include a matched DN in certain bind response messages.

• We improved support for SSL/TLS debugging for SSLUtil operations when used in conjunction with the javax.net.debug system property.

• We added methods to the JSONLDAPResultWriter class that can be used to encode entries, search result references, and LDAP results to JSON objects.

• We added a CryptoHelper.inferKeyStoreType method that attempts to determine the key store type for a specified file that is expected to represent a JKS, PKCS #12, or BCFKS key store.

• We added StaticUtils convenience methods for generating random bytes, integers, and strings, optionally using cryptographically secure random number generators.

• We updated the documentation to add draft-melnikov-scram-bis and to update draft-melnikov-scram-sha-512 and draft-melnikov-scram-sha3-512 in the set of LDAP-related specifications.

Updates Specific to Use With the Ping Identity Directory Server:

• We fixed an issue that could cause the manage-account tool to fail if it receives a response with an unrecognized password policy state operation type. This is most likely to occur when the tool is communicating with a version of the Ping Identity Directory Server that does not correspond to the version of the manage-account tool.

• We added client-side support for new extended operations that can allow for remote management of certificates in Ping Identity Directory Server instances.

• We updated the AuthenticationFailureReason class to add additional failure reason values related to pass-through authentication.

• We updated the TaskManager class to add methods for using LDAPInterface objects (including connection pools or Server SDK internal connections) as an alternative to LDAPConnection objects when interacting with administrative tasks.

We have just released version 6.0.2 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

• We fixed an issue in the JVM-default trust manager that could prevent it from properly trusting a certificate chain that should be considered valid through a cross-signed relationship, which may include certificates signed by the Let’s Encrypt service in some cases. Although the trust manager provided support for cross-signed certificates, that support would previously only be used if one or more of the certificates in the presented chain were outside of their current validity window.

• We added the ability to use the tls-server-end-point channel binding type when authenticating with the GSSAPI SASL mechanism. This feature depends on the underlying JVM providing support for this channel binding type and will likely require Java 13 or later.

• We fixed an issue in the in-memory directory server that could prevent it from returning search result references for smart referral entries within the scope of the search. It would previously only return references for smart referral entries that matched the search filter, but will now return references for any smart referral entry within the scope.

• We updated the LDAP command-line tool framework to add a --defaultTrust argument that can be used to indicate that the tool should use a default set of non-interactive logic for determining whether to trust a presented certificate chain. This includes at least the JVM’s default trust store, but in tools that are part of a Ping Identity server installation, it may also include the server’s default trust store and the topology registry. This is the same logic that tools would previously use when invoked without any trust-related arguments, with the exception that it will not interactively prompt about whether to trust the presented chain if it cannot be trusted through any of the default mechanisms. As such, it is more suitable for use in scripts that are intended to run in non-interactive settings.

• We updated the documentation to include the latest revision of draft-ietf-kitten-password-storage in the set of LDAP-related specifications.

We have just released version 6.0.1 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository. You can find the release notes at https://docs.ldap.com/ldap-sdk/docs/release-notes.html, but here’s a summary of the changes included in this version:

• We added a new ldap-diff command-line tool that can be used to compare the contents of two LDAPv3 servers. Any differences identified will be written to a specified file as LDIF change records that may be used to update the source server to match the target server. The tool attempts to minimize the memory required to perform the comparison, and it can use multiple passes to avoid potential false positives that result from delays in replication or changes made while the tool is running.

• We updated the ldifsearch tool to provide support for presenting the results in alternative output formats. It now supports the same formats as ldapsearch, including LDIF, JSON, CSV (single-valued and multi-valued), tab-delimited text (single-valued and multi-valued), DNs only, and values only.

• We updated the LDIF reader to make it possible to customize the size limit that it imposes for values read from a file referenced by URL. This limit is a safety feature that prevents consuming too much memory when encountering a reference to a very large file, but the size limit was previously hard-coded to be 10 megabytes. That is still the default, but it’s now possible to use the com.unboundid.ldif.LDIFReader.maxURLFileSizeBytes system property to set an alternative limit.

• We augmented the LDAP SDK’s debugging support to make it possible to automatically have debug messages written to a file specified by the com.unboundid.ldap.sdk.debug.file system property. This is intended to be used in conjunction with other debugging-related system properties to enable support for debugging in existing applications without the need for a code change.

• We lowered the debug level for exception messages that may be logged as a result of a SocketTimeoutException that is caught internally in the course of trying to determine whether a connection in a connection pool is still valid. This is a completely normal condition that was previously inadvertently logged at a WARNING level. This could potentially mislead people into thinking that it’s a problem, or at the very least make it harder to find debug messages that are actually important. It is now logged at the FINEST level, so it will only be visible at the highest level of verbosity.

• We updated support for the Ping Identity Directory Server’s matching entry count control to make it possible to request extended response data, including whether the search is fully indexed, whether identified candidate entries are known to be included in the scope of the search, and any remaining portion of the filter that was not used in the course of building the set of candidate entries.

• We updated support for the Ping Identity Directory Server’s generate profile administrative task to clarify that all included paths must be relative rather than absolute. Those paths will be treated as relative to the server root, and relative paths that reference portions of the filesystem outside the server root will not be allowed.

• We updated the documentation to include the latest revision of draft-coretta-x660-ldap in the set of LDAP-related specifications.

We have just released version 5.1.3 of the UnboundID LDAP SDK for Java. It is available for download from GitHub and SourceForge, and it is available in the Maven Central Repository.

The biggest change in this release addresses an issue in the LDAP listener framework (including the in-memory directory server). The listener did not adequately protect against the case in which a malicious or errant client could send an LDAP request encoded as an ASN.1 BER sequence with a very large value length, which could result in the listener attempting to allocate up to two gigabytes of memory. The LDAP listener framework will now impose a maximum request size of 20 megabytes by default, which is the same as the default maximum size that the LDAP SDK will impose for responses read from a directory server. The maximum request size can be configured using the InMemoryDirectoryServerConfig.setMaxMessageSizeBytes method when using the in-memory directory server, or using the LDAPListenerConfig.setMaxMessageSizeBytes method when using the more general LDAP listener framework. If you’re using the LDAP listener framework (or the in-memory directory server) to accept requests from potentially untrusted clients, then we recommend upgrading to the 5.1.3 release.

Other changes since the 5.1.2 release include:

• We have updated OID support to add methods for interacting with object identifiers in a hierarchical manner. It is now possible to create a new OID that is a child of a provided OID with a given subordinate component value. You can also get the parent for a provided OID and determine whether one OID is an ancestor or descendant of another.

• We have updated the oid-lookup tool to add a new --exact-match argument that will cause it to only return items in which the OID, name, type, origin, or URL exactly matches the provided search string. The tool continues to use substring matching by default.

• We have updated the ldap-result-code tool to add a new --output-format argument that allows you to customize whether the output should be formatted as a human-readable table, comma-separated values, tab-delimited text, or JSON objects. It will continue to format result codes in a table by default.