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.
↓Parent Component
↓Properties
↓dsconfig Usage
The PKCS11 Cipher Stream Provider component inherits from the Cipher Stream Provider
The properties supported by this managed object are as follows:
| Basic Properties: | Advanced Properties: |
|---|---|
| ↓ description | None |
| ↓ enabled | |
| ↓ pkcs11-provider-class | |
| ↓ pkcs11-provider-configuration-file | |
| ↓ key-store-pin | |
| ↓ key-store-pin-file | |
| ↓ key-store-pin-environment-variable | |
| ↓ pkcs11-key-store-type | |
| ↓ ssl-cert-nickname | |
| ↓ encryption-metadata-file |
| Description | A description for this Cipher Stream Provider |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether this Cipher Stream Provider is enabled for use in the PingAuthorize Server. |
| Default Value | None |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The fully-qualified name of the Java security provider class that implements support for interacting with PKCS #11 tokens. If this is not provided, then the server will attempt to automatically determine the appropriate provider class. |
| Default Value | The server will attempt to automatically determine the appropriate provider class. |
| Allowed Values | The fully-qualified name of a Java class that extends or implements java.security.Provider |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
pkcs11-provider-configuration-file
| Description | The path to the file to use to configure the security provider that implements support for interacting with PKCS #11 tokens. If this is not provided, then it will be assumed that either the provider does not require any configuration, or that the appropriate settings have already been specified in the JVM configuration. |
| Default Value | No provider configuration file will be used. |
| Allowed Values | A filesystem path |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The clear-text user PIN needed to interact with the PKCS #11 token. Exactly one of the key-store-pin, key-store-pin-file, and key-store-pin-environment-variable properties must be provided. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The path to a file containing the user PIN needed to interact with the PKCS #11 token. The file must exist and must contain exactly one line with a clear-text representation of the PIN. Exactly one of the key-store-pin, key-store-pin-file, and key-store-pin-environment-variable properties must be provided. |
| Default Value | None |
| Allowed Values | A filesystem path |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
key-store-pin-environment-variable
| Description | The name of an environment variable whose value is the user PIN needed to interact with the PKCS #11 token. The environment variable must be defined and must contain a clear-text representation of the PIN. Exactly one of the key-store-pin, key-store-pin-file, and key-store-pin-environment-variable properties must be provided. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The key store type to use when obtaining an instance of a key store for interacting with a PKCS #11 token. If this is not provided, then a default key store type of "PKCS11" will be used. |
| Default Value | PKCS11 |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The alias for the certificate in the PKCS #11 token that will be used to wrap the encryption key. The target certificate must exist in the PKCS #11 token, and it must have an RSA key pair because the JVM does not currently provide adequate key wrapping support for elliptic curve key pairs. If you have also configured the server to use a PKCS #11 token for accessing listener certificates, we strongly recommend that you use a different certificate to protect the contents of the encryption settings database than you use for negotiating TLS sessions with clients. It is imperative that the certificate used by this PKCS11 Cipher Stream Provider remain constant for the life of the provider because if the certificate were to be replaced, then the contents of the encryption settings database could become inaccessible. Unlike with listener certificates used for TLS negotiation that need to be replaced on a regular basis, this PKCS11 Cipher Stream Provider does not consider the validity period for the associated certificate, and it will continue to function even after the certificate has expired. If you need to rotate the certificate used to protect the server's encryption settings database, you should first install the desired new certificate in the PKCS #11 token under a different alias. Then, you should create a new instance of this PKCS11 Cipher Stream Provider that is configured to use that certificate, and that also uses a different value for the encryption-metadata-file because the information in that file is tied to the certificate used to generate it. Finally, you will need to update the global configuration so that the encryption-settings-cipher-stream-provider property references the new cipher stream provider rather than this one. The update to the global configuration must be done with the server online so that it can properly re-encrypt the contents of the encryption settings database with the correct key tied to the new certificate. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
encryption-metadata-file (Read-Only)
| Description | The path to a file that will hold metadata about the encryption performed by this PKCS11 Cipher Stream Provider. When initially configuring this cipher stream provider, the metadata file should not exist (although its parent directory must exist). The first time the provider is initialized and the secret key is successfully retrieved from Vault, a new metadata file will be generated with an appropriate set of properties for generating the cipher to use to interact with the encryption settings database. On subsequent uses, the existing metadata file will be read to determine these settings so that the existing encryption settings database can be opened. |
| Default Value | config/pkcs11-cipher-stream-provider-encryption-metadata.json |
| Allowed Values | A filesystem path |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
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}