[Cryptech Tech] Java PKCS11 provider restrictions on the underlying native PKCS#11 library

[Oleg Muravskiy]

As promised at the Berlin's workshop, here's an excerpt from Java's PKCS11 provider documentation (http://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html#KeyStoreRestrictions) that describes how it interacts with the PKCS11 implementations.

Cheers,
Oleg

Sun PKCS#11 provider's KeyStore Requirements
The following describes the requirements placed by the Sun PKCS#11 Provider's KeyStore implementation on the underlying native PKCS#11 library. Note that changes may be made in future releases to maximize interoperability with as many existing PKCS#11 libraries as possible.

Read-Only Access

To map existing objects stored on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.

A search for all private key objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:
CKA_TOKEN = true
CKA_CLASS = CKO_PRIVATE_KEY
A search for all certificate objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:
CKA_TOKEN = true
CKA_CLASS = CKO_CERTIFICATE
Each private key object is matched with its corresponding certificate by retrieving their respective CKA_ID attributes. A matching pair must share the same unique CKA_ID.
For each matching pair, the certificate chain is built by following the issuer->subject path. From the end entity certificate, a call fo C_FindObjects[Init|Final] is made with a search template that includes the following attributes:

CKA_TOKEN = true
CKA_CLASS = CKO_CERTIFICATE
CKA_SUBJECT = [DN of certificate issuer]
This search is continued until either no certificate for the issuer is found, or until a self-signed certificate is found. If more than one certificate is found the first one is used.

Once a private key and certificate have been matched (and its certificate chain built), the information is stored in a private key entry with the CKA_LABEL value from end entity certificate as the KeyStore alias.

If the end entity certificate has no CKA_LABEL, then the alias is derived from the CKA_ID. If the CKA_ID can be determined to consist exclusively of printable characters, then a String alias is created by decoding the CKA_ID bytes using the UTF-8 charset. Otherwise, a hex String alias is created from the CKA_ID bytes ("0xFFFF...", for example).

If multiple certificates share the same CKA_LABEL, then the alias is derived from the CKA_LABEL plus the end entity certificate issuer and serial number ("MyCert/CN=foobar/1234", for example).

Each certificate not part of a private key entry (as the end entity certificate) is checked whether it is trusted. If the CKA_TRUSTED attribute is true, then a KeyStore trusted certificate entry is created with the CKA_LABEL value as the KeyStore alias. If the certificate has no CKA_LABEL, or if multiple certificates share the same CKA_LABEL, then the alias is derived as described above.
If the CKA_TRUSTED attribute is not supported then no trusted certificate entries are created.

Any private key or certificate object not part of a private key entry or trusted certificate entry is ignored.
A search for all secret key objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:
CKA_TOKEN = true
CKA_CLASS = CKO_SECRET_KEY
A KeyStore secret key entry is created for each secret key object, with the CKA_LABEL value as the KeyStore alias. Each secret key object must have a unique CKA_LABEL.

Write Access

To create new KeyStore entries on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.

When creating a KeyStore entry (during KeyStore.setEntry, for example), C_CreateObject is called with CKA_TOKEN=true to create token objects for the respective entry contents.
Private key objects are stored with CKA_PRIVATE=true. The KeyStore alias (UTF8-encoded) is set as the CKA_ID for both the private key and the corresponding end entity certificate. The KeyStore alias is also set as the CKA_LABEL for the end entity certificate object.

Each certificate in a private key entry's chain is also stored. The CKA_LABEL is not set for CA certificates. If a CA certificate is already in the token, a duplicate is not stored.

Secret key objects are stored with CKA_PRIVATE=true. The KeyStore alias is set as the CKA_LABEL.

If an attempt is made to convert a session object to a token object (for example, if KeyStore.setEntry is called and the private key object in the specified entry is a session ojbect), then C_CopyObject is called with CKA_TOKEN=true.
If multiple certificates in the token are found to share the same CKA_LABEL, then the write capabilities to the token are disabled.
Since the PKCS#11 specification does not allow regular applications to set CKA_TRUSTED=true (only token initialization applications may do so), trusted certificate entries can not be created.
Miscellaneous

In addition to the searches listed above, the following searches may be used by the Sun PKCS#11 provider's KeyStore implementation to perform internal functions. Specifically, C_FindObjects[Init|Final] may be called with any of the following attribute templates:

    CKA_TOKEN    true
    CKA_CLASS    CKO_CERTIFICATE
    CKA_SUBJECT  [subject DN]
    
    CKA_TOKEN    true
    CKA_CLASS    CKO_SECRET_KEY
    CKA_LABEL    [label]
    
    CKA_TOKEN    true
    CKA_CLASS    CKO_CERTIFICATE or CKO_PRIVATE_KEY
    CKA_ID       [cka_id] 




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.cryptech.is/archives/tech/attachments/20160719/0c045f96/attachment-0001.html>