FIPS 140-3 compliance under development

This release of Security Toolkit 9.0 for Java has not yet been validated according to the Federal Information Processing Standards (FIPS). When the toolkit cryptographic module is certified for FIPS 140-3, Entrust will release an updated version of the Security Toolkit for Java.

Limitations writing certificate objects to Safenet eToken 5110+ FIPS

Certificate objects are only allowed to be written in the public area of the token. Please ensure that the end user policy of the policy setting on your Entrust Certificate Authority (ECA) has the following setting enabled for the certificates to be stored in the token public memory.

Secured key transport with the nShield HSM at FIPS Level 3

The protected key transfer in nShield uses CKM_AES_KEY_WRAP_KWP mechanism for key wrapping at FIPS Level 3 and is only supported in nShield firmware version 13.02 and up. Older firmware versions and FIPS Level 2 use the CKM_AES_CBC_PAD mechanism for key wrapping in the protected key transfer.

Elliptic curve keys not supported with CardMS APIs

The toolkit throws the following error when creating, recovering, or retrieving elliptic curve-based keys using the CMPForCardMS APIs.

Problems running the awk Linux command

In most Linux systems awk is located in /bin however, in some systems, it is located in /usr/bin. The Toolkit throws the following error when it does not find awk in the /bin directory.

If this issue applies to your Linux system, a simple workaround is to add a symbolic link to /usr/bin/awk in the /bin directory and then rebind. Rebinding corrects a problem with the data that was collected for the machine fingerprint. Using this feature without rebinding may cause the user login to fail.

Limitations to writing elliptic curve-based EPFs to nShield and Luna SA hardware devices

There are some limitations to writing elliptic curve based EPFs to nShield and Luna SA hardware devices.

The transfer of private keys from software to hardware did not work properly using Luna SA. SafeNet indicates that Luna SA devices should be updated to the latest firmware (4.6.8 or higher) to fix this problem. Luna SA supports only protected key transfers.

• The protected key transfer in nShield uses the CKM_AES_KEY_WRAP_KWP mechanism in nShield Security World 13.2.2 and up.

• Older firmware versions use the CKM_AES_CBC_PAD mechanism for its protected key transfer.

If you are working with nShield, the plaintext EC key transfer works with the following setting in cknfastrc.

ECDSA elliptic curve algorithm renamed as EC

Since the 7.2 SP2 release, the algorithm name associated with an EC public or private key was changed from "ECDSA" to EC". This change was made to comply with the JCA/JCE algorithm naming conventions.

http://download.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html

When EC support was first added to the Toolkit, only the ECDSA signature algorithm was supported; hence, the decision was made to assign these keys the "ECDSA" algorithm name. However, these were actually generic EC keys that could be used with any EC-based algorithm (for example, ECPV, ECDH, ECMQV, ECIES), not only ECDSA. Now that Sun (now Oracle) has defined standard algorithm naming conventions and Entrust is planning on broadening EC algorithm support beyond just ECDSA, we felt it was necessary to change the algorithm name associated with EC keys from "ECDSA" to "EC".

This change is not backward compatible. Customers whose code identifies EC keys by examining the algorithm should update that code to use the new name. See the Java Toolkit ECDSA sample for an example.

Named Elliptic Curve parameters not supported

The Toolkit will not support custom-named Elliptic Curve (EC) parameters. The existing ECDSAExample.java included with the Java Toolkit does not support registering named curves. Instead, ANSI X9.62 curves are registered through the EcParameterFactory class.

System property required in systems without non-UTF-8 encoded INI files

Some JVMs cause Java to fail to recognize the byte order mark (BOM) that may mark the beginning of a UTF-8 encoded file. The issue is detailed at:

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4508058.

While working around the problem, the Toolkit sets the default character set to "UTF-8".

For existing systems with Microsoft INI Files that are not encoded in UTF-8 (or subsets of UTF-8), the com.entrust.toolkit.util.IniFile.encoding system property should be set to specify the encoding to use for INI files. For example, z/OS systems should use:

This setting overrides the default "UTF-8" value.

XML stack overflow due to small call stack

The Xerces parser uses recursion to parse XML messages. This can cause a StackOverflowException if the XML message being processed is large enough to exhaust the Java System call stack. The error is more prominent on JVMs where the call stack size has been reduced. The call stack size may be increased by using the Java -Xss<size> command line option. See java.sun.com for information on how to increase the call stack size.

Limitations when using LDAPS with Active Directory referrals

When using an Active Directory environment to enable LDAP over SSL connections, the SSL certificate used to protect the Active Directory must follow the rules defined by section 3.6 of RFC 2830. The server's domain name must be in the Subject Alternative Name extension (as a DNS type) in the SSL certificate used to authenticate the SSL connection.

Failure to follow these guidelines may result in an error preventing a successful secure LDAP connection to the Active Directory.

FPKI and PKIX compliance not enforced

The Toolkit does not enforce Federal Public Key Infrastructure (FPKI) and Public Key Infrastructure X.509 (PKIX) certificate compliance.

Key agreement not supported by the S/MIME version 3 API

The S/MIME version 3 API contained in this release of the Toolkit does not support Key agreement, particularly the Ephemeral-Static variant of the Diffie-Helman key agreement algorithm.

Limitations when signing and verifying XML documents that do not specify attributes

This note describes an issue that might become apparent when you work with enveloping XML digital signatures whose <Signature> elements contain signed XML content.

A valid XML document identifies the XML schema (*.xsd file) or document type definition (DTD) to which it conforms. DTDs and XML schemas can declare two types of attributes that need not be present in the XML document instance:

• Fixed attributes are constants that apply to their associated elements whether or not they appear in an XML document instance. XML document instances do not usually contain fixed attributes. If they do, the fixed attribute must have the value specified in the corresponding DTD or schema. When an XML document instance is processed, an XML parser automatically supplies the values of these attributes if they are not present in the parsed document.

• Attributes with default values specified in the DTD or schema can be overridden.

When you use the Toolkit to sign XML document instances that do not explicitly contain fixed or default attributes, the validation step fails when the signed documents are verified. The org.w3c.dom.Document.importNode method imports attribute nodes into a DOM document only if the original XML document contains attributes—it does not import fixed or default attributes not included in an XML document instance.

You can overcome this issue by following these steps to ensure that the signed XML document is correctly constructed:

1. Parse the XML document instance you want to sign.

2. Serialize the parsed document (for example, using the iaik.ixsil.util.DOMUtilsImpl.serializeDocument method.

3. Parse the serialized document.

After this step, the serialized document specifies the fixed attributes explicitly. Create an XML digital signature object from the parsed serialized document.

Limitations on XML decryption with hardware tokens

In the Toolkit's XML Encryption classes, the default algorithm used to encrypt the key in an <EncryptedKey> element is RSA with PKCS #1 v2.0 Optimal Asymmetric Encryption Padding (OAEP). The use of OAEP encoding with the RSA algorithm is not yet common among PKCS #11 devices, so this release of the Toolkit does not support RSA OAEP for PKCS #11 token users. If you want to work with XML encryption and token users, set the <EncryptedKey> algorithm to RSA with PKCS #1 v1.5 padding before performing encryption operations using the setEncryptedKeyAlgorithm method in the Encryptor class as follows:

This step prevents the decryption operation from failing. Refer to the Javadoc reference documentation for more information on the following classes.

• com.entrust.toolkit.xencrypt.core.Encryptor

• com.entrust.toolkit.xencrypt.init.XMLEConstants

Unable to use a server login credentials file in several web applications

To use a server login credentials file (*.ual) with more than one web application, ensure the classes that load native libraries are loaded by a class loader used across all web applications. In general, do not put Toolkit JAR files into a WEB-INF\lib directory if you are using a feature of the Toolkit, such as server Login, that requires native libraries across multiple web applications.

KeyStore limitations with CAPI

The Entrust KeyStore implementation returned by the KeyStore.getInstance() methods cannot be used to read credentials from CAPI (Cryptographic API). To use CAPI credentials with a KeyStore

1. Log in to a User object using credentials from CAPI.

2. Use this object to create an EntrustKeyStore.

Forced CA key update

During a call to User.login(), the toolkit writes the new CA certificate to the user's credential store (for example, an .epf file) if a CA key has been updated and a CredentialWriter has been set. The next time the user logs in, the toolkit will require a Directory connection or a cache file containing the link certificates. Otherwise, the toolkit cannot find a path from the root certificate to the user certificates.

Although this behavior is consistent with other Entrust Toolkit products, it can be overridden by calling the User.setWriteCaUpdates(boolean) method so that new CA keys are written only when the user receives new keys.

Server login limitations on password change

After a Server Login with UALCredentialReader , users can change their password as if they were logged in using any other reader type. However, after changing their password, they must use the UALCreator class to re-bind the new password to the computer. Otherwise, subsequent logins will fail.

Limited support for 1-key-pair V1 users

The toolkit provides read-only support for 1-key-pair V1 users that are EPF-based. However, digital identity management is not supported for 1-key-pair V1 users. This includes:

• Create user

• Recover user

• Force key-update

• Change DN

• All other key update operations

• All digital identity writing operations

The outcome in each case is undefined. For 1-key-pair users with digital identity management support, please migrate to V2 users, who fully support 1 to 4 key pairs.