KMS ACL Classes

ACLs are implemented in the upstream Hadoop KMS and apply to any variant of the service, whether it is through Key Trustee Server (KTS), the Java Keystore (JKS), or the HSM KMS. Understanding how these ACLs are defined and work enables you to more accurately create ACLs that meet both your needs and the needs of your customers.

The KMS ACL classes provide fine-grain control of key access at different decision points (for example, preventing a user from accessing the KMS altogether), and are applied either KMS-wide or key-specific:

  • KMS-wide
    You can use KMS-wide ACLs to specify the types of operations a user can perform. Configure KMS-wide operations using the classes:
    • hadoop.kms.acl.<OPERATION>
    • hadoop.kms.blacklist.<OPERATION>

    KMS-wide ACLs precede key-specific ACLs. In other words, the permission check on a key-specific ACL only occurs if permission is already granted at the KMS-wide level; if it is, then the permission check against key-specific ACLs can proceed.

    Users accessing a KMS-wide ACL are first checked for inclusion in the ACL for the requested operation, and then checked for exclusion in the blacklist before the operation is performed or access is granted.

  • Key-specific
    You can use key-specific ACLs, set on a per-encryption zone key basis, to specify the types of operations a user can perform. Configure key-specific operations using the classes:
    • default.key.acl.<OPERATION>
    • whitelist.key.acl.<OPERATION>
    • key.acl.<key_name>.<OPERATION>

There are five distinct classes of ACLs, each defined by the operations defined within.

The hadoop.kms.acl.<OPERATION> Class

This class controls permissions to perform KMS-wide operations. The only ACLs that fall back to a value of '*' when the values are empty are those within the hadoop.kms.acl definition.

You can define fine-grain access for the following operations in this ACL class:

Table 1. hadoop.kms.acl.<OPERATION> Class
hadoop.kms.acl.<OPERATION> <OPERATION> Name Description
CREATE

Create Key

Creates an encryption zone key.

DELETE

Delete Key

Deletes an encryption zone key.

ROLLOVER

Rollover Key

Rolls an encryption zone key to the new version, using different material.

The encrypted encryption keys (also known as EEKs or EDEKs) are always generated using the latest version of the encryption key.
Invalidate Key Cache Invalidates all cached EEKs.
GET

Get Current Key

Gets the latest version of the encryption zone key, including its material.

Get Key Version Gets a specified version of the encryption zone key, including its material.
Get Key Versions Gets all versions of the encryption zone key, including their materials.
GET_KEYS Get Key Names Lists all the encryption zone key names on the Key Trustee KMS. No additional key material is returned.
GET_METADATA Get Key Metadata Gets the metadata of an encryption zone key, including the cipher, key length, description, time created, and number of versions and other attributes.
Get Keys Metadata Gets the metadata for a collection of encryption zone keys.
SET_KEY_MATERIAL For ROLLOVER and/or CREATE encryption key operations, determines whether or not the user can provide key material.

If encryption zone key material is not provided, then the Key Trustee KMS randomly generates the material.

GENERATE_EEK Generate Encrypted Key for Current KeyVersion Generates an encrypted encryption zone key from a given encrypted key name, using its current key version.
Re-encrypt Encrypted Key With The Latest KeyVersion Takes a previously generated EEK, and re-encrypts it using the latest KeyVersion of the same encrypted key. If the latest KeyVersion is the same as the one used to generate the EEK, then the same EEK is returned.
Batch Re-encrypt Encrypted Keys With The Latest KeyVersion Takes a batch of previously generated EEKs, and re-encrypts them using the latest KeyVersion of the same encrypted key. If the latest KeyVersion is the same as the one used to generate the EEK, then the same EEK is returned.
DECRYPT_EEK Decrypt Encrypted Key Decrypts an EEK and returns the decrypted encryption zone key.

The hadoop.kms.blacklist.<OPERATION> Class

This class controls permissions to perform KMS-wide operations. Users and groups listed here will be prevented from performing any other listed OPERATION on any encryption keys.

You can define fine-grain access for the following operations in this ACL category:

Table 2. hadoop.kms.blacklist.<OPERATION> Class
hadoop.kms.blacklist.<OPERATION> <OPERATION> Name Description
CREATE

Create Key

Creates an encryption zone key.

DELETE

Delete Key

Deletes an encryption zone key.

ROLLOVER

Rollover Key

Rolls an encryption zone key to the new version, using different material.

The encrypted encryption keys (EEKs) are always generated using the latest version of the encryption key.
Invalidate Key Cache Invalidates all cached EEKs.
GET

Get Current Key

Gets the latest version of the encryption zone key, including its material.

Get Key Version Gets a specified version of the encryption zone key, including its material.
Get Key Versions Gets all versions of the encryption zone key, including their materials.
GET_KEYS Get Key Names Lists all the encryption zone key names on the Key Trustee KMS. No additional key material is returned.
GET_METADATA Get Key Metadata Gets the metadata of an encryption zone key, including the cipher, key length, description, time created, and number of versions and other attributes.
Get Keys Metadata Gets the metadata for a collection of encryption zone keys.
SET_KEY_MATERIAL For ROLLOVER and/or CREATE encryption key operations, determines whether or not the user can provide key material.

If encryption zone key material is not provided, then the Key Trustee KMS randomly generates the material.

GENERATE_EEK Generate Encrypted Key for Current KeyVersion Generates an encrypted encryption zone key (EEK) from a given encrypted key name, using its current key version.
Re-encrypt Encrypted Key With The Latest KeyVersion Takes a previously generated EEK, and re-encrypts it using the latest KeyVersion of the same encrypted key. If the latest KeyVersion is the same as the one used to generate the EEK, then the same EEK is returned.
Batch Re-encrypt Encrypted Keys With The Latest KeyVersion Takes a batch of previously generated EEKs, and re-encrypts them using the latest KeyVersion of the same encrypted key. If the latest KeyVersion is the same as the one used to generate the EEK, then the same EEK is returned.
DECRYPT_EEK Decrypt Encrypted Key Decrypts an EEK and returns the decrypted encryption zone key.

The key.acl.<key-name>.<OPERATION> Class

This class controls permissions to perform operations for a specific key, and applies to key-specific ACLs.

You can define fine-grain access for the following operations in this ACL class:

Table 3. key.acl<key-name>.<OPERATION> Class
key.acl.key-name. <OPERATION> <OPERATION> Name Description
MANAGEMENT

createKey, deleteKey, rolloverNewVersion

Use for the following operations:

  • createKey
  • deleteKey
  • rolloverNewKeyVersion
GENERATE_EEK Generate Encryption Key Use for the following operations:
  • generateEncryptedKey
  • reencryptEncryptedKey
  • reencryptEncryptedKeys
  • warmUpEncryptedKeys
DECRYPT_EEK

Decrypt Encrypted Key

Use for the decryptEncryptedKey operation.

READ

Read

Use for the following operations:

  • getKeyVersion
  • getKeyVersions
  • getMetadata
  • getKeysMetadata
  • getCurrentKey
ALL All Use to specify all operations in this class.

The default.key.acl.<OPERATION> Class

This class controls permission to perform operations for keys that are not otherwise specified by key.acl.<key-name>.<OPERATION>, and applies to key-specific ACLs.

The default.key.acl.<OPERATION> applies to all keys for which an ACL has not been explicitly configured. Be aware that if all of the following conditions exist, key access is denied:

  • There is no key-specific ACL configured
  • There is no KMS ACL configured for the requested operation
  • There is no whitelist key ACL configured for the requested operation

Also note that the default.key.acl does not fall back to a value of '*' when you use empty values. All default.key.acls are (by default) empty, which means that you must create the required key definition entries for each key you wish to use.

Table 4. default.key.acl.<OPERATION> Class
default.key.acl. <OPERATION> <OPERATION> Name Description
MANAGEMENT

Manage the Zone Key

Use for the following operations:

  • createKey
  • deleteKey
  • rolloverNewKeyVersion
GENERATE_EEK

Create Encryption Key

Use for the decryptEncryptedKey operation.

DECRYPT_EEK

Decrypt Encryption Key

Use for the following operations:

  • getKeyVersion
  • getKeyVersions
  • getMetadata
  • getKeysMetadata
  • getCurrentKey
READ Read

Use for the following operations:

  • getKeyVersion
  • getKeyVersions
  • getMetadata
  • getKeysMetadata
  • getCurrentKey

The whitelist.key.acl Class

This class controls permissions to perform key operations across all keys, and applies to key-specific ACLs.

Table 5. whitelist.key.acl.<OPERATION> Class
whitelist.key.acl.<OPERATION> <OPERATION> Name Description
MANAGEMENT

Manage the Zone Key

Use for the following operations:

  • createKey
  • deleteKey
  • rolloverNewKeyVersion
GENERATE_EEK

Create Encryption Key

Use for the decryptEncryptedKey operation.

DECRYPT_EEK

Decrypt Encryption Key

Use for the following operations:

  • getKeyVersion
  • getKeyVersions
  • getMetadata
  • getKeysMetadata
  • getCurrentKey
READ Read

Use for the following operations:

  • getKeyVersion
  • getKeyVersions
  • getMetadata
  • getKeysMetadata
  • getCurrentKey