#set ( $H3 = '###' ) #set ( $H4 = '####' ) #set ( $H5 = '#####' ) Hadoop Key Management Server (KMS) - Documentation Sets ======================================================= Hadoop KMS is a cryptographic key management server based on Hadoop's **KeyProvider** API. It provides a client and a server components which communicate over HTTP using a REST API. The client is a KeyProvider implementation interacts with the KMS using the KMS HTTP REST API. KMS and its client have built-in security and they support HTTP SPNEGO Kerberos authentication and HTTPS secure transport. KMS is a Java web-application and it runs using a pre-configured Tomcat bundled with the Hadoop distribution. KMS Client Configuration ------------------------ The KMS client `KeyProvider` uses the **kms** scheme, and the embedded URL must be the URL of the KMS. For example, for a KMS running on `http://localhost:16000/kms`, the KeyProvider URI is `kms://http@localhost:16000/kms`. And, for a KMS running on `https://localhost:16000/kms`, the KeyProvider URI is `kms://https@localhost:16000/kms` KMS --- $H3 KMS Configuration Configure the KMS backing KeyProvider properties in the `etc/hadoop/kms-site.xml` configuration file: ```xml hadoop.kms.key.provider.uri jceks://file@/${user.home}/kms.keystore hadoop.security.keystore.java-keystore-provider.password-file kms.keystore.password ``` The password file is looked up in the Hadoop's configuration directory via the classpath. NOTE: You need to restart the KMS for the configuration changes to take effect. $H3 KMS Cache KMS has two kinds of caching: a CachingKeyProvider for caching the encryption keys, and a KeyProvider for caching the EEKs. $H4 CachingKeyProvider KMS caches encryption keys for a short period of time to avoid excessive hits to the underlying KeyProvider. This Cache is enabled by default (can be disabled by setting the `hadoop.kms.cache.enable` boolean property to false) This cache is used with the following 3 methods only, `getCurrentKey()` and `getKeyVersion()` and `getMetadata()`. For the `getCurrentKey()` method, cached entries are kept for a maximum of 30000 milliseconds regardless the number of times the key is being accessed (to avoid stale keys to be considered current). For the `getKeyVersion()` method, cached entries are kept with a default inactivity timeout of 600000 milliseconds (10 mins). These configurations can be changed via the following properties in the `etc/hadoop/kms-site.xml` configuration file: ```xml hadoop.kms.cache.enable true hadoop.kms.cache.timeout.ms 600000 hadoop.kms.current.key.cache.timeout.ms 30000 ``` $H4 KeyProvider Architecturally, both server-side (e.g. KMS) and client-side (e.g. NameNode) have a cache for EEKs. The following are configurable on the cache: * The size of the cache. This is the maximum number of EEKs that can be cached under each key name. * A low watermark on the cache. For each key name, if after a get call, the number of cached EEKs are less than (size * low watermark), then the cache under this key name will be filled asynchronously. For each key name, only 1 thread could be running for the asynchronous filling. * The maximum number of asynchronous threads overall, across key names, allowed to fill the queue in a cache. * The cache expiry time, in milliseconds. Internally Guava cache is used as the cache implementation. The expiry approach is [expireAfterAccess](https://code.google.com/p/guava-libraries/wiki/CachesExplained). Note that due to the asynchronous filling mechanism, it is possible that after rollNewVersion(), the caller still gets the old EEKs. In the worst case, the caller may get up to (server-side cache size + client-side cache size) number of old EEKs, or until both caches expire. This behavior is a trade off to avoid locking on the cache, and is acceptable since the old version EEKs can still be used to decrypt. Below are the configurations and their default values: Server-side can be changed via the following properties in the `etc/hadoop/kms-site.xml` configuration file: ```xml hadoop.security.kms.encrypted.key.cache.size 500 hadoop.security.kms.encrypted.key.cache.low.watermark 0.3 hadoop.security.kms.encrypted.key.cache.num.fill.threads 2 hadoop.security.kms.encrypted.key.cache.expiry 43200000 ``` Client-side can be changed via the following properties in the `etc/hadoop/core-site.xml` configuration file: ```xml hadoop.security.kms.client.encrypted.key.cache.size 500 hadoop.security.kms.client.encrypted.key.cache.low-watermark 0.3 hadoop.security.kms.client.encrypted.key.cache.num.refill.threads 2 hadoop.security.kms.client.encrypted.key.cache.expiry 43200000 ``` $H3 KMS Aggregated Audit logs Audit logs are aggregated for API accesses to the GET\_KEY\_VERSION, GET\_CURRENT\_KEY, DECRYPT\_EEK, GENERATE\_EEK operations. Entries are grouped by the (user,key,operation) combined key for a configurable aggregation interval after which the number of accesses to the specified end-point by the user for a given key is flushed to the audit log. The Aggregation interval is configured via the property : hadoop.kms.aggregation.delay.ms 10000 $H3 Start/Stop the KMS To start/stop KMS use KMS's sbin/kms.sh script. For example: hadoop-${project.version} $ sbin/kms.sh start NOTE: Invoking the script without any parameters list all possible parameters (start, stop, run, etc.). The `kms.sh` script is a wrapper for Tomcat's `catalina.sh` script that sets the environment variables and Java System properties required to run KMS. $H3 Embedded Tomcat Configuration To configure the embedded Tomcat go to the `share/hadoop/kms/tomcat/conf`. KMS pre-configures the HTTP and Admin ports in Tomcat's `server.xml` to 16000 and 16001. Tomcat logs are also preconfigured to go to Hadoop's `logs/` directory. The following environment variables (which can be set in KMS's `etc/hadoop/kms-env.sh` script) can be used to alter those values: * KMS_HTTP_PORT * KMS_ADMIN_PORT * KMS_MAX_THREADS * KMS_MAX_HTTP_HEADER_SIZE * KMS_LOGNOTE: You need to restart the KMS for the configuration changes to take effect. $H3 Loading native libraries The following environment variable (which can be set in KMS's `etc/hadoop/kms-env.sh` script) can be used to specify the location of any required native libraries. For eg. Tomact native Apache Portable Runtime (APR) libraries: * JAVA_LIBRARY_PATH $H3 KMS Security Configuration $H4 Enabling Kerberos HTTP SPNEGO Authentication Configure the Kerberos `etc/krb5.conf` file with the information of your KDC server. Create a service principal and its keytab for the KMS, it must be an `HTTP` service principal. Configure KMS `etc/hadoop/kms-site.xml` with the correct security values, for example: ```xml hadoop.kms.authentication.type kerberos hadoop.kms.authentication.kerberos.keytab ${user.home}/kms.keytab hadoop.kms.authentication.kerberos.principal HTTP/localhost hadoop.kms.authentication.kerberos.name.rules DEFAULT ``` NOTE: You need to restart the KMS for the configuration changes to take effect. $H4 KMS Proxyuser Configuration Each proxyuser must be configured in `etc/hadoop/kms-site.xml` using the following properties: ```xml hadoop.kms.proxyuser.#USER#.users * hadoop.kms.proxyuser.#USER#.groups * hadoop.kms.proxyuser.#USER#.hosts * ``` `#USER#` is the username of the proxyuser to configure. The `users` property indicates the users that can be impersonated. The `groups` property indicates the groups users being impersonated must belong to. At least one of the `users` or `groups` properties must be defined. If both are specified, then the configured proxyuser will be able to impersonate and user in the `users` list and any user belonging to one of the groups in the `groups` list. The `hosts` property indicates from which host the proxyuser can make impersonation requests. If `users`, `groups` or `hosts` has a `*`, it means there are no restrictions for the proxyuser regarding users, groups or hosts. $H4 KMS over HTTPS (SSL) To configure KMS to work over HTTPS the following 2 properties must be set in the `etc/hadoop/kms_env.sh` script (shown with default values): * KMS_SSL_KEYSTORE_FILE=$HOME/.keystore * KMS_SSL_KEYSTORE_PASS=password In the KMS `tomcat/conf` directory, replace the `server.xml` file with the provided `ssl-server.xml` file. You need to create an SSL certificate for the KMS. As the `kms` Unix user, using the Java `keytool` command to create the SSL certificate: $ keytool -genkey -alias tomcat -keyalg RSA You will be asked a series of questions in an interactive prompt. It will create the keystore file, which will be named **.keystore** and located in the `kms` user home directory. The password you enter for "keystore password" must match the value of the `KMS_SSL_KEYSTORE_PASS` environment variable set in the `kms-env.sh` script in the configuration directory. The answer to "What is your first and last name?" (i.e. "CN") must be the hostname of the machine where the KMS will be running. NOTE: You need to restart the KMS for the configuration changes to take effect. $H4 KMS Access Control KMS ACLs configuration are defined in the KMS `etc/hadoop/kms-acls.xml` configuration file. This file is hot-reloaded when it changes. KMS supports both fine grained access control as well as blacklist for kms operations via a set ACL configuration properties. A user accessing KMS is first checked for inclusion in the Access Control List for the requested operation and then checked for exclusion in the Black list for the operation before access is granted. ```xml hadoop.kms.acl.CREATE * 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. hadoop.kms.blacklist.CREATE hdfs,foo Blacklist for create-key operations. If the user is in the Blacklist, the key material is not returned as part of the response. hadoop.kms.acl.DELETE * ACL for delete-key operations. hadoop.kms.blacklist.DELETE hdfs,foo Blacklist for delete-key operations. hadoop.kms.acl.ROLLOVER * ACL for rollover-key operations. If the user is not in the GET ACL, the key material is not returned as part of the response. hadoop.kms.blacklist.ROLLOVER hdfs,foo Blacklist for rollover-key operations. hadoop.kms.acl.GET * ACL for get-key-version and get-current-key operations. hadoop.kms.blacklist.GET hdfs,foo ACL for get-key-version and get-current-key operations. hadoop.kms.acl.GET_KEYS * ACL for get-keys operation. hadoop.kms.blacklist.GET_KEYS hdfs,foo Blacklist for get-keys operation. hadoop.kms.acl.GET_METADATA * ACL for get-key-metadata and get-keys-metadata operations. hadoop.kms.blacklist.GET_METADATA hdfs,foo Blacklist for get-key-metadata and get-keys-metadata operations. hadoop.kms.acl.SET_KEY_MATERIAL * Complimentary ACL for CREATE and ROLLOVER operation to allow the client to provide the key material when creating or rolling a key. hadoop.kms.blacklist.SET_KEY_MATERIAL hdfs,foo Complimentary Blacklist for CREATE and ROLLOVER operation to allow the client to provide the key material when creating or rolling a key. hadoop.kms.acl.GENERATE_EEK * ACL for generateEncryptedKey CryptoExtension operations hadoop.kms.blacklist.GENERATE_EEK hdfs,foo Blacklist for generateEncryptedKey CryptoExtension operations hadoop.kms.acl.DECRYPT_EEK * ACL for decrypt EncryptedKey CryptoExtension operations hadoop.kms.blacklist.DECRYPT_EEK hdfs,foo Blacklist for decrypt EncryptedKey CryptoExtension operations ``` $H4 Key Access Control KMS supports access control for all non-read operations at the Key level. All Key Access operations are classified as : * MANAGEMENT - createKey, deleteKey, rolloverNewVersion * GENERATE_EEK - generateEncryptedKey, warmUpEncryptedKeys * DECRYPT_EEK - decryptEncryptedKey * READ - getKeyVersion, getKeyVersions, getMetadata, getKeysMetadata, getCurrentKey * ALL - all of the above These can be defined in the KMS `etc/hadoop/kms-acls.xml` as follows For all keys for which a key access has not been explicitly configured, It is possible to configure a default key access control for a subset of the operation types. It is also possible to configure a "whitelist" key ACL for a subset of the operation types. The whitelist key ACL is a whitelist in addition to the explicit or default per-key ACL. That is, if no per-key ACL is explicitly set, a user will be granted access if they are present in the default per-key ACL or the whitelist key ACL. If a per-key ACL is explicitly set, a user will be granted access if they are present in the per-key ACL or the whitelist key ACL. If no ACL is configured for a specific key AND no default ACL is configured AND no root key ACL is configured for the requested operation, then access will be DENIED. **NOTE:** The default and whitelist key ACL does not support `ALL` operation qualifier. ```xml key.acl.testKey1.MANAGEMENT * ACL for create-key, deleteKey and rolloverNewVersion operations. key.acl.testKey2.GENERATE_EEK * ACL for generateEncryptedKey operations. key.acl.testKey3.DECRYPT_EEK admink3 ACL for decryptEncryptedKey operations. key.acl.testKey4.READ * ACL for getKeyVersion, getKeyVersions, getMetadata, getKeysMetadata, getCurrentKey operations key.acl.testKey5.ALL * ACL for ALL operations. whitelist.key.acl.MANAGEMENT admin1 whitelist ACL for MANAGEMENT operations for all keys. whitelist.key.acl.DECRYPT_EEK admin1 whitelist ACL for DECRYPT_EEK operations for all keys. default.key.acl.MANAGEMENT user1,user2 default ACL for MANAGEMENT operations for all keys that are not explicitly defined. default.key.acl.GENERATE_EEK user1,user2 default ACL for GENERATE_EEK operations for all keys that are not explicitly defined. default.key.acl.DECRYPT_EEK user1,user2 default ACL for DECRYPT_EEK operations for all keys that are not explicitly defined. default.key.acl.READ user1,user2 default ACL for READ operations for all keys that are not explicitly defined. ``` $H3 KMS Delegation Token Configuration KMS delegation token secret manager can be configured with the following properties: ```xml hadoop.kms.authentication.delegation-token.update-interval.sec 86400 How often the master key is rotated, in seconds. Default value 1 day. hadoop.kms.authentication.delegation-token.max-lifetime.sec 604800 Maximum lifetime of a delagation token, in seconds. Default value 7 days. hadoop.kms.authentication.delegation-token.renew-interval.sec 86400 Renewal interval of a delagation token, in seconds. Default value 1 day. hadoop.kms.authentication.delegation-token.removal-scan-interval.sec 3600 Scan interval to remove expired delegation tokens. ``` $H3 Using Multiple Instances of KMS Behind a Load-Balancer or VIP KMS supports multiple KMS instances behind a load-balancer or VIP for scalability and for HA purposes. When using multiple KMS instances behind a load-balancer or VIP, requests from the same user may be handled by different KMS instances. KMS instances behind a load-balancer or VIP must be specially configured to work properly as a single logical service. $H4 HTTP Kerberos Principals Configuration When KMS instances are behind a load-balancer or VIP, clients will use the hostname of the VIP. For Kerberos SPNEGO authentication, the hostname of the URL is used to construct the Kerberos service name of the server, `HTTP/#HOSTNAME#`. This means that all KMS instances must have a Kerberos service name with the load-balancer or VIP hostname. In order to be able to access directly a specific KMS instance, the KMS instance must also have Keberos service name with its own hostname. This is required for monitoring and admin purposes. Both Kerberos service principal credentials (for the load-balancer/VIP hostname and for the actual KMS instance hostname) must be in the keytab file configured for authentication. And the principal name specified in the configuration must be '\*'. For example: ```xml hadoop.kms.authentication.kerberos.principal * ``` **NOTE:** If using HTTPS, the SSL certificate used by the KMS instance must be configured to support multiple hostnames (see Java 7 `keytool` SAN extension support for details on how to do this). $H4 HTTP Authentication Signature KMS uses Hadoop Authentication for HTTP authentication. Hadoop Authentication issues a signed HTTP Cookie once the client has authenticated successfully. This HTTP Cookie has an expiration time, after which it will trigger a new authentication sequence. This is done to avoid triggering the authentication on every HTTP request of a client. A KMS instance must verify the HTTP Cookie signatures signed by other KMS instances. To do this all KMS instances must share the signing secret. This secret sharing can be done using a Zookeeper service which is configured in KMS with the following properties in the `kms-site.xml`: ```xml hadoop.kms.authentication.signer.secret.provider zookeeper Indicates how the secret to sign the authentication cookies will be stored. Options are 'random' (default), 'string' and 'zookeeper'. If using a setup with multiple KMS instances, 'zookeeper' should be used. hadoop.kms.authentication.signer.secret.provider.zookeeper.path /hadoop-kms/hadoop-auth-signature-secret The Zookeeper ZNode path where the KMS instances will store and retrieve the secret from. hadoop.kms.authentication.signer.secret.provider.zookeeper.connection.string #HOSTNAME#:#PORT#,... The Zookeeper connection string, a list of hostnames and port comma separated. hadoop.kms.authentication.signer.secret.provider.zookeeper.auth.type kerberos The Zookeeper authentication type, 'none' or 'sasl' (Kerberos). hadoop.kms.authentication.signer.secret.provider.zookeeper.kerberos.keytab /etc/hadoop/conf/kms.keytab The absolute path for the Kerberos keytab with the credentials to connect to Zookeeper. hadoop.kms.authentication.signer.secret.provider.zookeeper.kerberos.principal kms/#HOSTNAME# The Kerberos service principal used to connect to Zookeeper. ``` $H4 Delegation Tokens TBD $H3 KMS HTTP REST API $H4 Create a Key *REQUEST:* POST http://HOST:PORT/kms/v1/keys Content-Type: application/json { "name" : "", "cipher" : "", "length" : , //int "material" : "", //base64 "description" : "" } *RESPONSE:* 201 CREATED LOCATION: http://HOST:PORT/kms/v1/key/ Content-Type: application/json { "name" : "versionName", "material" : "", //base64, not present without GET ACL } $H4 Rollover Key *REQUEST:* POST http://HOST:PORT/kms/v1/key/ Content-Type: application/json { "material" : "", } *RESPONSE:* 200 OK Content-Type: application/json { "name" : "versionName", "material" : "", //base64, not present without GET ACL } $H4 Delete Key *REQUEST:* DELETE http://HOST:PORT/kms/v1/key/ *RESPONSE:* 200 OK $H4 Get Key Metadata *REQUEST:* GET http://HOST:PORT/kms/v1/key//_metadata *RESPONSE:* 200 OK Content-Type: application/json { "name" : "", "cipher" : "", "length" : , //int "description" : "", "created" : , //long "versions" : //int } $H4 Get Current Key *REQUEST:* GET http://HOST:PORT/kms/v1/key//_currentversion *RESPONSE:* 200 OK Content-Type: application/json { "name" : "versionName", "material" : "", //base64 } $H4 Generate Encrypted Key for Current KeyVersion *REQUEST:* GET http://HOST:PORT/kms/v1/key//_eek?eek_op=generate&num_keys= *RESPONSE:* 200 OK Content-Type: application/json [ { "versionName" : "encryptionVersionName", "iv" : "", //base64 "encryptedKeyVersion" : { "versionName" : "EEK", "material" : "", //base64 } }, { "versionName" : "encryptionVersionName", "iv" : "", //base64 "encryptedKeyVersion" : { "versionName" : "EEK", "material" : "", //base64 } }, ... ] $H4 Decrypt Encrypted Key *REQUEST:* POST http://HOST:PORT/kms/v1/keyversion//_eek?ee_op=decrypt Content-Type: application/json { "name" : "", "iv" : "", //base64 "material" : "", //base64 } *RESPONSE:* 200 OK Content-Type: application/json { "name" : "EK", "material" : "", //base64 } $H4 Get Key Version *REQUEST:* GET http://HOST:PORT/kms/v1/keyversion/ *RESPONSE:* 200 OK Content-Type: application/json { "name" : "versionName", "material" : "", //base64 } $H4 Get Key Versions *REQUEST:* GET http://HOST:PORT/kms/v1/key//_versions *RESPONSE:* 200 OK Content-Type: application/json [ { "name" : "versionName", "material" : "", //base64 }, { "name" : "versionName", "material" : "", //base64 }, ... ] $H4 Get Key Names *REQUEST:* GET http://HOST:PORT/kms/v1/keys/names *RESPONSE:* 200 OK Content-Type: application/json [ "", "", ... ] $H4 Get Keys Metadata GET http://HOST:PORT/kms/v1/keys/metadata?key=&key=,... *RESPONSE:* 200 OK Content-Type: application/json [ { "name" : "", "cipher" : "", "length" : , //int "description" : "", "created" : , //long "versions" : //int }, { "name" : "", "cipher" : "", "length" : , //int "description" : "", "created" : , //long "versions" : //int }, ... ]