KeyStoreSecretStore

Manages a secret store for cryptographic keys and certificates, based on a standard Java KeyStore.

The KeyStore is typically file-based PKCS12 KeyStore. Legacy proprietary formats such as JKS and JCEKS are supported, but implement weak encryption and integrity protection mechanisms. Consider not using them for new functionality.

The secrets provider queries the KeyStoreSecretStore for a named secret, identified by a secret ID and a stable ID, corresponding to the secret-id/aliases mapping. The KeyStoreSecretStore returns a secret that exactly matches the name, and whose purpose matches the secret ID and any purpose contraints.

The secrets provider builds the secret, checking that the secret’s constraints are met, and returns a unique secret. If the secret’s constraints are not met, the secrets provider cannot build the secret and the secret query fails.

For a description of how secrets are managed, see Secrets.

Usage

{
  "name": string,
  "type": "KeyStoreSecretStore",
  "config": {
    "file": configuration expression<string>,
    "storeType": configuration expression<string>,
    "storePassword": configuration expression<string>,
    "keyEntryPassword": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "mappings": [ object, ... ],
    "leaseExpiry": configuration expression<duration>
   }
}

Properties

"file": configuration expression<string>, required

The path to the KeyStore file.

"storeType": configuration expression<string>, optional

The secret store type.

"storePassword": configuration expression<secret-id>, required

The secret ID of the password to access the KeyStore.

IG searches for the value of the password until it finds it, first locally, then in parent routes, then in config.json.

To create a store password, add a file containing the password. The filename must corresponds to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns.

"keyEntryPassword": configuration expression<secret-id>, optional

The secret ID of the password to access entries in the KeyStore.

To create an entry password, add a file containing the password. The filename must corresponds to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns.

When this property is used, the password must be the same for all entries in the KeyStore. If JKS uses different password for entries, keyEntryPassword doesn’t work.

Default: The value of storePassword

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the keystore password and key entry password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default secrets object.

"mappings": array of objects, required

One or more mappings of one secret ID to one or more aliases. The secret store uses the mappings as follows:

When the secret is used to create signatures or encrypt values, the secret store uses the active secret, the first alias in the list.
When the secret is used to verify signatures or decrypt data, the secret store tries all of the mapped aliases in the list, starting with the first, and stopping when it finds a secret that can successfully verify signature or decrypt the data.
```
"mappings": [
  {
    "secretId": "id.key.for.signing.jwt",
    "aliases": [ "SigningKeyAlias", "AnotherSigningKeyAlias" ]
  },
  {
    "secretId": "id.key.for.encrypting.jwt",
    "aliases": ["EncryptionKeyAlias"]
  }
]
```

secretId: configuration expression<secret-id>, required: The ID of the secret used in your configuration.
aliases: array of configuration expression<strings>, required: One or more aliases for the secret ID.

"leaseExpiry": configuration expression<duration>, optional: The amount of time that secrets produced by this store can be cached before they must be refreshed.

If the duration is zero or unlimited, IG issues a warning, and uses the default value.

Default: 5 minutes

Log level

To facilitate debugging secrets for the KeyStoreSecretStore, in logback.xml add a logger defined by the fully qualified package name of the KeyStoreSecretStore. The following line in logback.xml sets the log level to ALL:

<logger name="org.forgerock.secrets.keystore" level="ALL">

Example

For examples of routes that use KeyStoreSecretStore, see the examples in JwtBuilderFilter.

More information

org.forgerock.secrets.keystore.KeyStoreSecretStore

org.forgerock.openig.secrets.KeyStoreSecretStoreHeaplet