Appendix B: IBMPKCS11Impl Provider's KeyStore Requirement

The existing objects stored on a PKCS11 token should match to KeyStore entries.

1. Certificate objects

   We consider all certificate objects, no matter the CKA_TRUSTED attribute is set to true or not, are trusted. Each of the certificate objects has a KeyStore.TrustedCertificateEntry type of entry in the keystore.

   The alias for the entry is the value of CKA_LABEL attribute of the certificate object. It is possible that different objects may have the same CKA_LABEL value, then the alias may already exist in the keystore. In such case, the new alias will be derived from the label plus "cert" plus a number. The number starts at 0 and increments by 1 every time we derive a new alias. For example, if alias "aliceCA" exists, the new alias for the certificate object with same label will be "aliceCAcert0".

2. Private key objects

   All private key objects have a KeyStore.PrivateKeyEntry type of entry in the keystore. On the hardware token, the certificate object for a private key object should share the same unique CKA_ID value as the private key object. For each matching pair of private key and certificate, the certificate chain is built by following the issuer->subject path. If more than one certificate is found, the first one will be used. Once the certificate chain is built and validated, it is added to the keystore as part of the private key entry. If the private key object has no CKA_ID, or for any reason the certificate chain can not be built, then the private key entry will not have a certificate chain with it.

   The alias of the private key is the value of CKA_LABEL attribute of the private key object. If the same alias exists in the keystore, the new one will be the label plus "key" plus a number. The number starts at 0 and increments by 1 every time we derive a new alias. For example, if alias "alicePriv" exists, the new one will be "alicePrivkey0". If the key's CKA_LABEL attribute is empty, we create an alias for the private key entry using "privatekey" plus a number.

3. Secret key object

   For each secret key object, we create a KeyStore.SecretKeyEntry type entry, with the CKA_LABEL value as the keystore alias. If the alias already exists, then we derive an alias using "secretkey" plus a number. The number increases by 1 every time we create such new alias.

Adding new entry to the keystore would create new object to the PKCS11 token.

1. Trusted certificate entry

   The alias string parameter is converted into byte array and use as the value for CKA_ID. The alias is also used as CKA_LABEL value. The certificate object will be created on the token as a token object. Because PKCS11 specification does not allow regular applications to set CKA_TRUSTED attribute to be true, the certificate object will not have this flag set.

2. Key entry

   When you try to add a new private key entry, if there is a private key entry with the same alias in the keystore, the old private key token will be deleted as well as its associated certificate. If the rest of the certificates in the chain are not used by other entries, they will be removed also.

The private key or secret key entry may wrap the PKCS11 private key or secret key object that the IBMPKCS11Impl provider recognizes. If not, or if the key is actually a software key, IBMPKCS11Impl provider will convert the key using the KeyFactory or SecretKeyFactory facility. The default is to convert it to an extractable, non-sensitive PKCS11 session key object. Users can change the default by customizing the key attributes with "import" operation in the configuration file.