Configuring Apache HDFS Encryption
Also available as:
loading table of contents...

Ranger KMS Properties

This topic describes configuration properties for the Ranger Key Management Service (KMS).

Table 1. Properties in Advanced dbks-site Menu (dbks-site.xml)
Property Name Default Value Description
ranger.ks.masterkey.credential.alias ranger.ks.masterkey.password Credential alias used for masterkey.
ranger.ks.jpa.jdbc.user rangerkms Database username used for operation.
ranger.ks.jpa.jdbc.url jdbc:log4jdbc:mysql://localhost:3306/rangerkms JDBC connection URL for database.
ranger.ks.jpa.jdbc.password _ (default it’s encrypted) Database user's password.
ranger.ks.jpa.jdbc.driver net.sf.log4jdbc.DriverSpy Driver used for database.
ranger.ks.jpa.jdbc.dialect org.eclipse.persistence.platform. database.MySQLPlatform Dialect used for database.
ranger.ks.jpa.jdbc.credential. provider.path /etc/ranger/kms/rangerkms.jceks Credential provider path.
ranger.ks.jpa.jdbc.credential.alias ranger.ks.jdbc.password Credential alias used for password.
ranger.ks.jdbc.sqlconnectorjar /usr/share/java/mysql-connector-java.jar Driver jar used for database.
ranger.db.encrypt.key.password _ (Default; it’s encrypted) Password used for encrypting the Master Key.
hadoop.kms.blacklist.DECRYPT_EEK hdfs Blacklist for decrypt EncryptedKey CryptoExtension operations. This can have multiple user IDs in a comma separated list. e.g. stormuser,yarn,hdfs.
Table 2. Properties in Advanced kms-env
Property Name Default Value Description
Kms User kms Ranger KMS process will be started using this user.
Kms Group kms Ranger KMS process will be started using this group.
LD library path LD library path (basically used when the db flavor is SQLA). Example: /opt/sqlanywhere17/lib64
kms_port 9292 Port used by Ranger KMS.
kms_log_dir /var/log/ranger/kms Directory where the Ranger KMS log will be generated.
Table 3. Properties in Advanced kms-properties (
Property Name Default Value Description
db_user rangerkms Database username used for the operation.
db_root_user Database root username. Default is blank. Specify the root user.
db_root_password Database root user’s password. Default is blank. Specify the root user password.
db_password Database user’s password for the operation. Default is blank. Specify the Ranger KMS database password.
db_name rangerkms Database name for Ranger KMS.
db_host <FQDN of instance where the Ranger KMS is installed> Hostname where the database is installed. Note: Check the hostname for DB and change it accordingly.
SQL_CONNECTOR_JAR /usr/share/java/mysql-connector.jar Location of DB client library.
REPOSITORY_CONFIG_USERNAME keyadmin User used in default repo for Ranger KMS.
REPOSITORY_CONFIG_PASSWORD keyadmin Password for user used in default repo for Ranger KMS.
KMS_MASTER_KEY_PASSWD Password used for encrypting the Master Key. Default value is blank. Set the master key to any string.
DB_FLAVOR MYSQL Database flavor used for Ranger KMS. Supported values: MYSQL, SQLA, ORACLE, POSTGRES, MSSQL
Table 4. Properties in Advanced kms-site (kms-site.xml)
Property Name Default Value Description JavaKeyStoreProvider.password none If using the JavaKeyStoreProvide, the password for the keystore file. authorization.manager org.apache.ranger. authorization.kms. authorizer.RangerKmsAuthorizer Ranger KMS security authorizer.
hadoop.kms.key.provider.uri dbks://http@localhost:9292/kms URI of the backing KeyProvider for the KMS.
hadoop.kms.current.key. 30000 Expiry time for the KMS current key cache, in milliseconds. This affects getCurrentKey operations. 600000 Expiry time for the KMS key version and key metadata cache, in milliseconds. This affects getKeyVersion and getMetadata.
hadoop.kms.cache.enable true

Whether the KMS will act as a cache for the backing KeyProvider. When the cache is enabled, operations like getKeyVersion, getMetadata, and getCurrentKey will sometimes return cached data without consulting the backing KeyProvider. Cached values are flushed when keys are deleted or modified.

Note: This setting is beneficial if Single KMS and single mode are used. If this is set to true when multiple KMSs are used, or when the key operations are from different modes (Ranger UI, CURL, or hadoop command), it might cause inconsistency.

hadoop.kms.authentication.type simple Authentication type for the Ranger KMS. Can be either “simple” or “kerberos”.
hadoop.kms.authentication.signer. secret.provider.zookeeper.path /hadoop-kms/hadoop-auth-signature-secret The ZooKeeper ZNode path where the Ranger KMS instances will store and retrieve the secret from.
hadoop.kms.authentication. signer.secret.provider. zookeeper.kerberos.principal kms/#HOSTNAME# The Kerberos service principal used to connect to ZooKeeper
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.connection.string #HOSTNAME#:#PORT#,...

The ZooKeeper connection string, a list of hostnames and port comma separated. For example:

<FQDN for first instance>:2181,<FQDN for second instance>:2181

hadoop.kms.authentication. signer.secret.provider. zookeeper.auth.type kerberos

ZooKeeper authentication type: 'none' or 'sasl' (Kerberos)

The value "none" means the default authentication will be used (not, "no authentication is used.") Using "none" means:
  • In a non-kerberized unsecure cluster: no security on the Zookeeper connection
  • In a kerberized secure cluster: Kerberos/SASL is used to connect to Zookeeper with the Ranger KMS's "_Client_" Login Context

The value "sasl" means that KMS would use an independent "ZKSignerSecretProviderClient" Login Context, but this is not yet supported on HDP.

hadoop.kms.authentication. signer. secret.provider random Indicates how the secret to sign authentication cookies will be stored. Options are 'random' (default), 'string', and zookeeper'. If you have multiple Ranger KMS instances, specify 'zookeeper'.
hadoop.kms.authentication. kerberos.principal HTTP/localhost The Kerberos principal to use for the HTTP endpoint. The principal must start with 'HTTP/' as per the Kerberos HTTP SPNEGO specification.
hadoop.kms.authentication. DEFAULT Rules used to resolve Kerberos principal names.
hadoop.kms.authentication. kerberos.keytab ${user.home}/kms.keytab Path to the keytab with credentials for the configured Kerberos principal.
hadoop.kms.audit. 10000 Specified in ms. Duplicate audit log events within this aggregation window are quashed to reduce log traffic. A single message for aggregated events is printed at the end of the window, along with a count of the number of aggregated events.
Table 5. Properties in Advanced ranger-kms-audit (ranger-kms-audit.xml)
Property Name Default Value Description
Audit provider summary enabled Enable audit provider summary. true Enable audit.
xasecure.audit.destination. solr.zookeepers none Specify solr zookeeper string.
xasecure.audit.destination.solr.urls {{ranger_audit_solr_urls}}

Specify solr URL.

Note: In Ambari this value is populated from the Ranger Admin by default.

xasecure.audit.destination. solr.batch.filespool.dir /var/log/ranger/kms/audit/solr/spool Directory for solr audit spool.
Audit to SOLR Enable audit to solr.
xasecure.audit.destination.hdfs.dir hdfs://NAMENODE_HOST:8020/ranger/audit

HDFS directory to write audit.

Note: Make sure the service user has required permissions.

xasecure.audit.destination. hdfs.batch.filespool.dir /var/log/ranger/kms/audit/hdfs/spool Directory for HDFS audit spool.
Audit to HDFS Enable hdfs audit.
xasecure.audit.destination.db.user {{xa_audit_db_user}}

xa audit db user

Note: In Ambari this value is populated from the Ranger Admin by default.

xasecure.audit.destination. db.password encrypted (it’s in encrypted format)

xa audit db user password

Note: In Ambari this value is populated from the Ranger Admin by default.

xasecure.audit.destination.db.jdbc.url {{audit_jdbc_url}}

Database JDBC URL for xa audit.

Note: In Ambari the value for this is populated from the Ranger Admin by default.

xasecure.audit.destination. db.jdbc.driver {{jdbc_driver}}

Database JDBC driver.

Note: In Ambari this value is populated from the Ranger Admin by default.

xasecure.audit.destination. db.batch.filespool.dir /var/log/ranger/kms/audit/db/spool Directory for database audit spool.
Audit to DB Enable audit to database.
xasecure.audit.credential.provider.file jceks://file{{credential_file}} Credential provider file.
Table 6. Properties in Advanced ranger-kms-policymgr-ssl
Property Name Default Value Description
xasecure.policymgr.clientssl. truststore.password changeit Password for the truststore.
xasecure.policymgr.clientssl. truststore /usr/hdp/current/ranger-kms/conf/ranger-plugin-truststore.jks jks file for truststore
xasecure.policymgr.clientssl. keystore.password myKeyFilePassword Password for keystore.
xasecure.policymgr.clientssl. keystore.credential.file jceks://file{{credential_file}} Java keystore credential file.
xasecure.policymgr.clientssl. keystore /usr/hdp/current/ranger-kms/conf/ranger-plugin-keystore.jks Java keystore file.
xasecure.policymgr.clientssl. truststore.credential.file jceks://file{{credential_file}} Java truststore file.
Table 7. Properties in Advanced ranger-kms-security
Property Name Default Value Description <default name for Ranger KMS Repo> Name of the Ranger service containing policies for the KMS instance. Note: In Ambari the default value is <clusterName>_kms.
ranger.plugin.kms.policy.source.impl org.apache.ranger.admin.client. RangerAdminRESTClient Class to reterive policies from the source. {{policymgr_mgr_url}} URL for Ranger Admin. ssl.config.file /etc/ranger/kms/conf/ranger-policymgr-ssl.xml Path to the file containing SSL details for contacting the Ranger Admin.
ranger.plugin.kms.policy. pollIntervalMs 30000 Time interval to poll for changes in policies.
ranger.plugin.kms.policy.cache.dir /etc/ranger/{{repo_name}}/policycache Directory where Ranger policies are cached after successful retrieval from the source.