Configuring KMS Access Control Lists (ACLs)

An Access Control List (ACL) is a list of specific permissions or controls that allow individual users, groups, a host, or applications to perform specific actions upon specific objects. The Hadoop KMS supports a range of ACLs that control access to encryption keys and key operations on a granular basis.

KMS ACLs indirectly impact data access by controlling key access, and are decoupled from HDFS file permissions and ACLs. KMS ACLs alone do not directly control data access. Instead, KMS ACLs control whether or not an authorized client can perform a specific operation on a named encryption key.

While KMS ACLs play a primary role in controlling encryption key security, it is important to understand that they are not the only mechanism by which access is controlled. A user’s role also factors into the level of access.

Proper configuration of KMS ACLs depends on a variety of variables such as workload, CDP components in use, and how your clusters are configured. This documentation does not take into consideration or describe these outside variables. For details about your specific component’s ACL behavior and requirements, refer to the product documentation for the CDP components in your configuration.

KMS ACLs and Roles

Cloudera’s framework for key management is based on enforcing a secure-by-default configuration based upon the KMS ACLs and roles described here.

Table 1. KMS ACLs and Roles
Role Description Allowed To: Not Allowed To:
Key Administrators

The sole purpose of a Key Administrator is to create and manage keys. This user is whitelisted in a number of areas so that they can handle defined and undefined keys within the context of the KMS.

  • Create and manage encryption zone keys
  • Add, update, or otherwise modify ACLs that protect all encryption zone keys
HDFS Superusers

Responsible for HDFS administration, HDFS Superusers are not granted rights to decrypt data within encryption zones. Rather, they are authorized to only create zones and attach keys to those zones for the data sets that they manage. HDFS Superusers are usually also HDFS Superusers.

  • Create encryption zones
  • Manage, create, or read keys
  • Add, update, or otherwise modify ACLs that protect all keys
  • Decrypt EEKs
HDFS Service User

There is only one HDFS Service User; this is the user the HDFS service runs as within the Hadoop framework. HDFS Service Users are granted special permissions to generate keys (EEKs) that populate per encryption zone key caches.

  • Generate keys that are made available for use through the per encryption zone key caches
End Users

Producers and consumers of data who store or retrieve information within specific encryption zones.

  • Read and write in encrypted data spaces

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) or the Java Keystore (JKS). 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:

    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 denylist 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:

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 2. 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 3. 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 4. 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 5. 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 6. 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

KMS ACL Evaluation Flow

Before diving into the details of how KMS ACLs are evaluated, it is critical that you understand the key rules that the KMS uses in performing this evaluation.

KMS ACL Flow Rules:
  • The whitelist class bypasses key.acl and default.key.acl controls.
  • The key.acl definitions override all default definitions.

The better you understand these rules, the more likely it is that you will be successful creating and managing KMS ACL sets to achieve your desired goals.

The KMS evaluates hadoop.kms.acl.<OPERATION> and hadoop.kms.blacklist.<OPERATION> classes to determine whether or not access to a specific KMS feature or function is authorized.

In other words, a user must be allowed by hadoop.kms.acl.<OPERATION>, and not be disallowed by hadoop.kms.blacklist.<OPERATION>.

If a user is disallowed or otherwise not allowed access to a KMS-wide operation, then the flow halts and returns the result "Denied".

If a user is allowed access to a KMS-wide operation, then the evaluation flow proceeds.

The KMS evaluates whitelist.key.acl class.

The KMS ACL workflow evaluates the whitelist.key.acl.<OPERATION>, and if the user is allowed access, then it is granted ("Allowed") . If not, then the flow continues with the evaluation.

The KMS evaluates default.key.acl.<OPERATION>, and key.acl.<OPERATION> classes.

The KMS evaluates whether or not there is a key.acl.KEY.<OPERATION> that matches the action the user is attempting to perform. If there is, it then evaluates that value to determine whether or not the user can perform the requested operation.

Depending on the result of the KMS ACL evaluation, controls are applied to the key and results (Allowed or Denied).

KMS ACL Syntax and Tips

Blacklist and Whitelist Syntax

The ACL syntax for both allowed and disallowed entries is as follows:
  • Users only: user1,user2,userN

    There are no spaces following the commas separating the users in the list.

  • Groups only: nobody group1,group2,groupN

    There is a space between nobody and the comma-separated group list. The nobody user, if it exists, must not have privileges to log in to or interact with the system. If you are uncertain about its access privileges, specify a different nonexistent user in its place.

  • Users and Groups: user1,user2,userN group1,group2,groupN

    The comma-separated user list is separated from the comma-separated group list by a space.

Blocking User Access

If you wish to block access to an operation entirely, use the value of an empty space, or some non-existent values (for example,'NOUSERS NOGROUPS'). By doing this, you ensure that no user maps to a particular operation by default. Alternatively, you can restrict those features to Key Administrators only by setting the value to Keyadmin users and/or groups.

Group Membership in KMS ACLs

The group membership used by ACL entries depends upon the configured group mapping mechanism for HDFS. By default, group membership is determined on the local Linux system running the KMS service. If you have configured HDFS to use LDAP for group mapping, then group membership for the ACL entries is determined using the configured LDAP settings.

Configuring KMS ACLs Using Cloudera Manager

Minimum Required Role: Key Administrator (also provided by Full Administrator)

The KMS installation wizard includes an option to generate the recommended ACLs. To view or edit the ACLs:
  1. Go to the KMS service.
  2. Click Configuration.
  3. In the Search field, type acl to show the Key Management Server Advanced Configuration Snippet (Safety Valve) for kms-acls.xml (in the Key Management Server Default Group category).
  4. Add or edit the ACL properties according to your cluster configuration. See "Recommended KMS Access Control List” for example ACL entries.
  5. Click Save Changes.
  6. Return to the Home page by clicking the Cloudera Manager logo, and return to the KMS service.
  7. Click ( Refresh Needed) . Then click Refresh Cluster.
  8. Click Finish.

Recommended KMS ACL

Cloudera recommends the following ACL definition for secure production settings. Replace keyadmin and keyadmingroup with the user and group responsible for maintaining encryption keys.

<configuration>

<!--
KMS ACLs control which users can perform various actions on the KMS,and which
users and groups have access to which keys.

This file includes the following sections:
  * ACLs for KMS operations
  ** Access to specific KMS operations
  ** Blacklists for specific operations
  * ACLs for keys
  ** Default ACLs for keys
  ** Whitelist ACLs for keys
  ** Key-specific ACLs
-->

<!--
KMS ACLs that govern access to specific key operations. If access is not granted
for an operation here, then the operation is forbidden, even if a key ACL allows it.

The ACL value should be either a username or a username and groupname separated
by whitespace.

A value of "*" (for the username or groupname) indicates that all users are
granted access to that operation. Any operation for which there is no ACL or an
empty (zero-length) ACL is treated as having an ACL with a value of "*".
To disallow all users, add an ACL with a value of " " (a single space).

Note: This convention applies only to the KMS-wide ACLs beginning with 'hadoop.kms.acl'.
-->
<property>
  <name>hadoop.kms.acl.CREATE</name>
  <value>keyadmin keyadmingroup</value>
  <description>
    ACL for create-key operations.
    If the user is not in the GET ACL, the key material is not returned
    as part of the response.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.DELETE</name>
  <value>keyadmin keyadmingroup</value>
  <description>
   ACL for delete-key operations.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.ROLLOVER</name>
  <value>keyadmin keyadmingroup</value>
  <description>
    ACL for rollover-key operations.
    If the user does is not in the GET ACL, the key material is not returned as part of the response.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.GET</name>
  <value></value>
  <description>
    ACL for get-key-version and get-current-key operations.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.GET_KEYS</name>
  <value>keyadmin keyadmingroup</value>
  <description>
    ACL for get-keys operations.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.SET_KEY_MATERIAL</name>
  <value></value>
  <description>
    Complementary ACL for CREATE and ROLLOVER operations to allow the client to provide the
    key material when creating or rolling a key.
  </description>
</property>

<property>
  <name>hadoop.kms.acl.GENERATE_EEK</name>
  <value>hdfs supergroup</value>
  <description>
    ACL for generateEncryptedKey CryptoExtension operations.
  </description>
</property>

<!--
  KMS blacklists to prevent access to operations. These settings override the permissions granted by the KMS ACLs listed above.

  The blacklist value should be either a username or a username and groupname separated by whitespace.

  A blank value indicates that no user is blacklisted from the operation. A value of "*" (for either the username or
  groupname) indicates that all users are blacklisted from the operation. Any operation for which there is no blacklist
  will be treated as having a blacklist with an empty value.
-->

<!--
  In this template the hdfs user is blacklisted for everything except GET_METADATA, GET_KEYS, and GENERATE_EEK. The
  GET and SET_KEY_MATERIAL operations are blacklisted for all users because Hadoop users should not need to perform
  those operations, and access to the key material should be as restricted as possible.
-->

<property>
  <name>hadoop.kms.blacklist.CREATE</name>
  <value>hdfs supergroup</value>
</property>

<property>
  <name>hadoop.kms.blacklist.DELETE</name>
  <value>hdfs supergroup</value>
</property>

<property>
  <name>hadoop.kms.blacklist.ROLLOVER</name>
  <value>hdfs supergroup</value>
</property>

<property>
  <name>hadoop.kms.blacklist.GET</name>
  <value>*</value>
</property>

<property>
  <name>hadoop.kms.blacklist.GET_KEYS</name>
  <value></value>
</property>

<property>
  <name>hadoop.kms.blacklist.SET_KEY_MATERIAL</name>
  <value>*</value>
</property>

<property>
  <name>hadoop.kms.blacklist.DECRYPT_EEK</name>
  <value>hdfs supergroup</value>
</property>

<property>
  <name>keytrustee.kms.acl.UNDELETE</name>
  <value></value>
  <description>
    ACL that grants access to the UNDELETE operation on all keys.
    Only used by Key Trustee KMS.
  </description>
</property>

<property>
  <name>keytrustee.kms.acl.PURGE</name>
  <value></value>
  <description>
    ACL that grants access to the PURGE operation on all keys.
    Only used by Key Trustee KMS.
  </description>
</property>

<!--
  Default key ACLs that govern access to key operations for key-operation pairs that do not have a
  key-specific ACL already. Key-specific ACLs override the default key ACLs.

  The ACL value should be either a username or a username and group name separated by whitespace.

  An empty value for an ACL indicates that no user is granted access to that operation. A value
  of "*" (for the username or groupname) indicates that all users are granted access to that operation.
  Any operation for which there is no ACL will be treated as having an ACL with an empty value.
-->

<property>
  <name>default.key.acl.MANAGEMENT</name>
  <value></value>
  <description>
    Default ACL that grants access to the MANAGEMENT operation on all keys.
  </description>
</property>

<property>
  <name>default.key.acl.GENERATE_EEK</name>
  <value></value>
  <description>
    Default ACL that grants access to the GENERATE_EEK operation on all keys.
  </description>
</property>

<property>
  <name>default.key.acl.DECRYPT_EEK</name>
  <value></value>
  <description>
    Default ACL that grants access to the DECRYPT_EEK operation on all keys.
  </description>
</property>

<property>
  <name>default.key.acl.READ</name>
  <value></value>
  <description>
    Default ACL that grants access to the READ operation on all keys.
  </description>
</property>

<!--
  Whitelist key ACLs that grant access to key-specific operations. Any permissions granted here
  will be added to whatever permissions are granted by the specific key ACL or the default key ACL.
  Note that these whitelist ACLs grant access to operations on specific keys. If the operations
  are not allowed because of the KMS ACLs/blacklists, then the they will not be permitted,
  regardless of the whitelist settings.

  The ACL value should be either a username or a username and group name separated by whitespace.

  An empty value for an ACL indicates that no user is granted access to that operation. A value
  of "*" (for the username or groupname) indicates that all users are granted access to that
  operation. Any operation for which there is no ACL will
  be treated as having an ACL with an empty value.
-->

<property>
  <name>whitelist.key.acl.MANAGEMENT</name>
  <value>keyadmin keyadmingroup</value>
  <description>
    Whitelist ACL for MANAGEMENT operations for all keys.
  </description>
</property>

<property>
  <name>whitelist.key.acl.READ</name>
  <value>hdfs supergroup</value>
  <description>
    Whitelist ACL for READ operations for all keys.
  </description>
</property>

<property>
  <name>whitelist.key.acl.GENERATE_EEK</name>
  <value>hdfs supergroup</value>
  <description>
    Whitelist ACL for GENERATE_EEK operations for all keys.
  </description>
</property>

<property>
  <name>whitelist.key.acl.DECRYPT_EEK</name>
  <value>keyadmin keyadmingroup</value>
  <description>
    Whitelist ACL for DECRYPT_EEK operations for all keys.
  </description>
</property>

<!--
  Key ACLs that grant access to specific key operations. Any permissions granted here are added
  to whatever permissions are granted by the whitelists.
  The key ACL name should be key.acl.<keyname>.<OPERATION>.

  The ACL value should be either a username or a username and group name separated by whitespace.

  An empty value for an ACL indicates that no user is granted access to that operation. A value
  of "*" (for the username or group name) indicates that all users are granted access to that operation.
  Any key operation for which there is no ACL will default to the default ACL for the operation.

  Normally adding users or groups for a specific key and DECRYPT_EEK is sufficient to allow access
  to data protected with HDFS data at rest encryption.
-->

<!--
  The following ACLs are required for proper functioning of services. Cloudera Manager does not create keys or
  encryption zones; however, our best practices recommend encryption zones on certain directories.
  An assumption in these ACLs is that the user has followed the recommended naming scheme and named the keys
  according to documented best practices: "hive-key" for the Hive service,
  "hbase-key" for the Hbase service, etc. If the key names are different, then none of this will work
  out of the box, and you will need to edit these ACLs to match your key names.
-->

<property>
  <name>key.acl.hive-key.DECRYPT_EEK</name>
  <value>hive hive</value>
  <description>
    Gives the Hive user and the Hive group access to the key named "hive-key".
    This allows the Hive service to read and write files in /user/hive/.
    Also note that the Impala user ought to be a member of the Hive group to enjoy this same access.
  </description>
</property>

<property>
  <name>key.acl.hive-key.READ</name>
  <value>hive hive</value>
  <description>
    Required because Hive compares key strengths when joining tables.
  </description>
</property>

<property>
  <name>key.acl.hbase-key.DECRYPT_EEK</name>
  <value>hbase hbase</value>
  <description>
    Gives the hbase user and hbase group access to the key named "hbase-key".
    This allows the hbase service to read and write files in /hbase.
  </description>
</property>

<property>
  <name>key.acl.solr-key.DECRYPT_EEK</name>
  <value>solr solr</value>
  <description>
    Gives the solr user and solr group access to the key named "solr-key".
    This allows the solr service to read and write files in /solr.
  </description>
</property>

<property>
  <name>key.acl.mapred-key.DECRYPT_EEK</name>
  <value>mapred,yarn hadoop</value>
  <description>
    Gives the mapred user and mapred group access to the key named "mapred-key".
    This allows mapreduce to read and write files in /user/history.
    This is required by YARN.
  </description>
</property>

<property>
  <name>key.acl.hue-key.DECRYPT_EEK</name>
  <value>oozie,hue oozie,hue</value>
  <description>
    Gives the appropriate users and groups access to the key named "hue-key".
    This allows Hue and Oozie to read and write files in /user/hue.
    Oozie is required here because it will attempt to access workflows in /user/hue/oozie/workspaces.
  </description>
</property>



<!-- This example is required if there are encryption zones on user’s home directories. -->
<!--
<property>
  <name>key.acl.username-key.DECRYPT_EEK</name>
  <value>username username,hive,hbase,solr,oozie,hue,yarn</value>
  <description>
    Designed to be placed on a key that protects the EZ /user/username, and assumes that
    the key name is also "username-key"; this shows that a number of services can reach in
    to access data. Remove those that are not needed for your use case.
  </description>
</property>
-->

</configuration>