PKCS11 Cipher Stream Provider

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

The PKCS11 Cipher Stream Provider uses an RSA certificate stored in a PKCS #11 token to wrap or unwrap an encryption key needed to access the contents of the encryption settings database.

Note that at present, only RSA certificates are supported. Java does not currently support any key wrapping algorithms that may be used for certificates with an elliptic curve key pair, especially for certificates in PKCS #11 tokens.

Also note that this PKCS11 Cipher Stream Provider will only interact with the PKCS #11 token once when the server is started or when launching a tool that needs to access the encryption settings database. Once the key is obtained, it will be cached in memory so that it will not be necessary to interact with the token while the server or tool remains running.
When starting up, this cipher stream provider will check for the existence of the file specified by the encryption-metadata-file configuration property. If that file does not exist, then the provider will securely generate a very long password that it will use to generate a local encryption key to encrypt the contents of the encryption settings database. It will then use the certificate in the PKCS #11 token to wrap that password, along with additional encryption metadata, and that wrapped result will be written to the encryption metadata file.
The next time the cipher stream provider is started, that encryption metadata file will be read and unwrapped with the certificate from the PKCS #11 token. The unwrapped password and encryption metadata will be used to derive the secret key that will be used to decrypt the contents of the encryption settings database.

dsconfig Usage

To list the configured Cipher Stream Providers:

dsconfig list-cipher-stream-providers
     [--property {propertyName}] ...

To view the configuration for an existing Cipher Stream Provider:

dsconfig get-cipher-stream-provider-prop
     --provider-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Cipher Stream Provider:

dsconfig set-cipher-stream-provider-prop
     --provider-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new PKCS11 Cipher Stream Provider:

dsconfig create-cipher-stream-provider
     --provider-name {name}
     --type pkcs11
     --set enabled:{propertyValue}
     --set ssl-cert-nickname:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Cipher Stream Provider:

dsconfig delete-cipher-stream-provider
     --provider-name {name}