Amazon Key Management Service 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 Amazon Key Management Service Cipher Stream Provider is used to create a cipher stream provider using a secret key that is decrypted using the Amazon Key Management Service.

When starting up, this cipher stream provider will check for the existence of the file specified by the encrypted-password-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 send that password, along with additional encryption metadata, to the Key Management Service, and that encrypted result will be written to the encrypted password file.
The next time the cipher stream provider is started, that encrypted password file will be read and its contents sent to the Key Management Service to be decrypted. The decrypted 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.
Once it is created, this Amazon Key Management Service Cipher Stream Provider should not be altered in any way. If you would like to change the cipher stream provider that the server uses, even to use a different key in the Amazon Key Management Service, you will need to create a new cipher stream provider configuration object and update the global configuration to activate that new provider. If this is done with the server online, then the encryption settings database will automatically be re-encrypted with the new cipher stream provider. However, as a safeguard against unexpected failures, it is still recommended that you export the encryption settings definitions before switching the active cipher stream provider.

Parent Component Relations from This Component Properties dsconfig Usage

Parent Component

The Amazon Key Management Service Cipher Stream Provider component inherits from the Cipher Stream Provider

Relations from This Component

The following components have a direct aggregation relation from Amazon Key Management Service Cipher Stream Providers:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  None
 enabled
 encrypted-passphrase-file
 aws-external-server
 aws-access-key-id
 aws-secret-access-key
 aws-region-name
 kms-encryption-key-arn
 iteration-count

Basic Properties

description

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

enabled

Description
Indicates whether this Cipher Stream Provider is enabled for use in the Directory Server.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

encrypted-passphrase-file (Read-Only)

Description
The path to a file that will hold the encrypted passphrase used by this cipher stream provider. When initially configuring this cipher stream provider, the passphrase file should not exist (although its parent directory must exist). The first time the provider is initialized, a new passphrase will be generated and encrypted with the specified key in the Amazon Key Management Service. On subsequent uses, the existing passphrase file will be read and decrypted using the same key. This key will be cached in memory so that the server will not need to interact with the Amazon Key Management Service for subsequent accesses to the encryption settings database.
Default Value
config/encryption-settings-passphrase.kms-encrypted
Allowed Values
A filesystem path
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

aws-external-server

Description
The external server with information to use when interacting with the Amazon Key Management Service. If an external server is specified, then none of the aws-access-key-id ,aws-secret-access-key, or aws-region-name properties may be specified.
Default Value
None
Allowed Values
The DN of any Amazon Aws External Server.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

aws-access-key-id

Description
The access key ID that will be used if this cipher stream provider will authenticate to the Amazon Key Management Service using an access key rather than an IAM role associated with an EC2 instance. If an access key ID is provided, then a secret access key must also be given. In this case, the specified key will be used to authenticate to the Amazon Key Management Service. The configured key must have permission to encrypt and decrypt data with the key specified by the kms-encryption-key-arn configuration property.
If no access key ID is provided, then no secret access key may be configured. In this case, the server must be running in an Amazon EC2 instance, and that EC2 instance must be configured with an IAM role that has permission to encrypt and decrypt data with the key specified by the kms-encryption-key-arn configuration property.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

aws-secret-access-key

Description
The secret access key that will be used if this cipher stream provider will authenticate to the Amazon Key Management Service using an access key rather than an IAM role associated with an EC2 instance. If a secret access key is provided, then an access key ID must also be given. In this case, the specified key will be used to authenticate to the Amazon Key Management Service. The configured key must have permission to encrypt and decrypt data with the key specified by the kms-encryption-key-arn configuration property.
If no secret access key is provided, then no access key ID may be configured. In this case, the server must be running in an Amazon EC2 instance, and that EC2 instance must be configured with an IAM role that has permission to encrypt and decrypt data with the key specified by the kms-encryption-key-arn configuration property.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

aws-region-name

Description
The name of the Amazon Web Services region that holds the encryption key. This is optional, and if it is not provided, then the server will attempt to determine the region from the key ARN. This property must not be provided if an aws-external-server value is configured.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

kms-encryption-key-arn (Read-Only)

Description
The Amazon resource name (ARN) for the KMS key that will be used to encrypt the contents of the passphrase file. This key must exist, and the AWS client must have access to encrypt and decrypt data using this key.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

iteration-count (Read-Only)

Description
The PBKDF2 iteration count that will be used when deriving the encryption key used to protect the encryption settings database.
Default Value
600000
Allowed Values
An integer value. Lower limit is 1000.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


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 Amazon Key Management Service Cipher Stream Provider:

dsconfig create-cipher-stream-provider
     --provider-name {name}
     --type amazon-key-management-service
     --set enabled:{propertyValue}
     --set kms-encryption-key-arn:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Cipher Stream Provider:

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