Configure Secret Store Back-end¶
The Key Manager service has a plugin architecture that allows the deployer to store secrets in one or more secret stores. Secret stores can be software-based such as a software-only encryption mechanism, or hardware devices such as a hardware security module (HSM).
Secret Stores implement both the encryption mechanisms as well as the storage of the encrypted secrets.
This section compares all the plugins that are currently available and the security tradeoffs that need to be considered when deciding which pluings to use.
Simple Crypto Plugin¶
This back end plugin implements encryption using only software. The encrypted secrets are stored in the Barbican database.
This crypto plugin is configured by default in /etc/barbican/barbican.conf.
This plugin uses single symmetric key (kek - or ‘key encryption key’)
- which is stored in plain text in the /etc/barbican/barbican.conf file to encrypt
and decrypt all secrets.
Security |
⚠ Master Key (KEK) stored in the configuration file |
Maturity |
✅ Tested on every patch |
Ease of Use |
✅ Simple to deploy
❌ Key rotation is disruptive
(all secrets must be re-encrypted)
|
Scalability |
✅ Storage can be scaled in SQL DB
✅ Failover/HA is simple, just run more barbican-api
instances
✅ High performance - Software crypto is fast
|
Cost |
✅ Free (as in beer) |
Warning
This plugin stores its KEK in plain text in the configuration file, which will be present in any node running the barbican-api or barbican-worker services. Extreme care should be taken to prevent unauthrized access to these nodes. When using this plugin the KEK is the only thing protecting the secrets stored in the database.
The configuration for this plugin in /etc/barbican/barbican.conf is as follows:
# ================= Secret Store Plugin =================== [secretstore] .. enabled_secretstore_plugins = store_crypto # ================= Crypto plugin =================== [crypto] .. enabled_crypto_plugins = simple_crypto [simple_crypto_plugin] # the kek should be a 32-byte value which is base64 encoded kek = 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY='
PKCS#11 Crypto Plugin¶
This crypto plugin can be used to interface with a Hardware Security Module (HSM) using the PKCS#11 protocol.
Secrets are encrypted (and decrypted on retrieval) by a project specific Key Encryption Key (KEK), which resides in the HSM.
The configuration for this plugin in /etc/barbican/barbican.conf.
Settings for some different HSMs are provided below:
Safenet¶
The PKCS#11 plugin configuration looks like:
# ================= Secret Store Plugin =================== [secretstore] .. enabled_secretstore_plugins = store_crypto [p11_crypto_plugin] # Path to vendor PKCS11 library library_path = '/usr/lib/libCryptoki2_64.so' # Token serial number used to identify the token to be used. Required # when the device has multiple tokens with the same label. (string # value) token_serial_number = 12345678 # Token label used to identify the token to be used. Required when # token_serial_number is not specified. (string value) #token_label = <None> # Password to login to PKCS11 session login = 'mypassword' # Label to identify master KEK in the HSM (must not be the same as HMAC label) mkek_label = 'an_mkek' # Length in bytes of master KEK mkek_length = 32 # Label to identify HMAC key in the HSM (must not be the same as MKEK label) hmac_label = 'my_hmac_label' # (Optional) HSM Slot ID that contains the token device to be used. # (integer value) #slot_id = 1 # Enable Read/Write session with the HSM? # rw_session = True # Length of Project KEKs to create # pkek_length = 32 # How long to cache unwrapped Project KEKs # pkek_cache_ttl = 900 # Max number of items in pkek cache # pkek_cache_limit = 100
Thales¶
For a Thales NetHSM, the plugin configuration looks like:
# ================= Secret Store Plugin =================== [secretstore] .. enabled_secretstore_plugins = store_crypto [p11_crypto_plugin] # Path to vendor PKCS11 library library_path = '/opt/nfast/toolkits/pkcs11/libcknfast.so' # Token serial number used to identify the token to be used. Required # when the device has multiple tokens with the same label. (string # value) token_serial_number = 12345678 # Token label used to identify the token to be used. Required when # token_serial_number is not specified. (string value) #token_label = <None> # Password to login to PKCS11 session login = 'XXX' # Label to identify master KEK in the HSM (must not be the same as HMAC label) mkek_label = 'thales_mkek_0' # Length in bytes of master KEK mkek_length = 32 # Label to identify HMAC key in the HSM (must not be the same as MKEK label) hmac_label = 'thales_hmac_0' # (Optional) HSM Slot ID that contains the token device to be used. # (integer value) # slot_id = 1 # Enable Read/Write session with the HSM? # rw_session = True # Length of Project KEKs to create # pkek_length = 32 # How long to cache unwrapped Project KEKs # pkek_cache_ttl = 900 # Max number of items in pkek cache # pkek_cache_limit = 100 # Secret encryption mechanism (string value) # Deprecated group/name - [p11_crypto_plugin]/algorithm encryption_mechanism = CKM_AES_CBC # HMAC Key Type (string value) hmac_key_type=CKK_SHA256_HMAC # HMAC Key Generation Mechanism (string value) hmac_keygen_mechanism = CKM_NC_SHA256_HMAC_KEY_GEN # Generate IVs for CKM_AES_GCM mechanism. (boolean value) # Deprecated group/name - [p11_crypto_plugin]/generate_iv aes_gcm_generate_iv=True # Always set CKA_SENSITIVE=CK_TRUE including # CKA_EXTRACTABLE=CK_TRUE keys. # default true always_set_cka_sensitive=false
The HMAC and MKEK keys can be generated as follows:
barbican-manage hsm gen_hmac \ --library-path /opt/nfast/toolkits/pkcs11/libcknfast.so \ --passphrase XXX --slot-id 1 --label thales_hmac_0 \ --key-type CKK_SHA256_HMAC \ --mechanism CKM_NC_SHA256_HMAC_KEY_GENbarbican-manage hsm gen_mkek \ --library-path /opt/nfast/toolkits/pkcs11/libcknfast.so \ --passphrase XXX --slot-id 1 --label thales_mkek_0
ATOS Bull¶
For an ATOS Bull HSM, the plugin configuration looks like:
# ================= Secret Store Plugin =================== [secretstore] .. enabled_secretstore_plugins = store_crypto [p11_crypto_plugin] # Path to vendor PKCS11 library library_path = '/usr/lib64/libnethsm.so' # Token serial number used to identify the token to be used. Required # when the device has multiple tokens with the same label. (string # value) token_serial_number = 12345678 # Token label used to identify the token to be used. Required when # token_serial_number is not specified. (string value) #token_label = <None> # Password to login to PKCS11 session login = 'XXX' # Label to identify master KEK in the HSM (must not be the same as HMAC label) mkek_label = 'atos_mkek_0' # Length in bytes of master KEK mkek_length = 32 # Label to identify HMAC key in the HSM (must not be the same as MKEK label) hmac_label = 'atos_hmac_0' # (Optional) HSM Slot ID that contains the token device to be used. # (integer value) # slot_id = 1 # Enable Read/Write session with the HSM? # rw_session = True # Length of Project KEKs to create # pkek_length = 32 # How long to cache unwrapped Project KEKs # pkek_cache_ttl = 900 # Max number of items in pkek cache # pkek_cache_limit = 100 # Secret encryption mechanism (string value) # Deprecated group/name - [p11_crypto_plugin]/algorithm encryption_mechanism = CKM_AES_CBC # HMAC Key Type (string value) hmac_key_type = CKK_GENERIC_SECRET # HMAC Key Generation Mechanism (string value) hmac_keygen_mechanism = CKM_GENERIC_SECRET_KEY_GEN # Always set CKA_SENSITIVE=CK_TRUE including # CKA_EXTRACTABLE=CK_TRUE keys. # default true always_set_cka_sensitive=false
The HMAC and MKEK keys can be generated as follows:
barbican-manage hsm gen_hmac --library-path /usr/lib64/libnethsm.so \ --passphrase XXX --slot-id 1 --label atos_hmac_0 \ --key-type CKK_GENERIC_SECRET \ --mechanism CKM_GENERIC_SECRET_KEY_GENbarbican-manage hsm gen_mkek --library-path /usr/lib64/libnethsm.so \ --passphrase XXX --slot-id 1 --label atos_mkek_0
Utimaco¶
The PKCS#11 plugin configuration looks like:
# ================= Secret Store Plugin =================== [secretstore] .. enabled_secretstore_plugins = store_crypto [p11_crypto_plugin] # Path to vendor PKCS11 library (string value) library_path = '/opt/utimaco/lib/libcs_pkcs11_R2.so' # Token serial number used to identify the token to be used. Required # when the device has multiple tokens with the same label. (string # value) token_serial_number = 12345678 # Token label used to identify the token to be used. Required when # token_serial_number is not specified. (string value) #token_label = <None> # Password to login to PKCS11 session (string value) login = '$up3r$e<retP4ssw0rd' # Master KEK label (as stored in the HSM) (string value) mkek_label = 'my_mkek' # Master KEK length in bytes. (integer value) #mkek_length = <None> # Master HMAC Key label (as stored in the HSM) (string value) hmac_label = 'my_hmac_key' # (Optional) HSM Slot ID that contains the token device to be used. # (integer value) # slot_id = 1 # Flag for Read/Write Sessions (boolean value) #rw_session = true # Project KEK length in bytes. (integer value) #pkek_length = 32 # Project KEK Cache Time To Live, in seconds (integer value) #pkek_cache_ttl = 900 # Project KEK Cache Item Limit (integer value) #pkek_cache_limit = 100 # Secret encryption mechanism (string value) # Deprecated group/name - [p11_crypto_plugin]/algorithm encryption_mechanism = CKM_AES_CBC # HMAC Key Type (string value) #hmac_key_type = CKK_AES # HMAC Key Generation Algorithm (string value) #hmac_keygen_mechanism = CKM_AES_KEY_GEN # File to pull entropy for seeding RNG (string value) #seed_file = # Amount of data to read from file for seed (integer value) #seed_length = 32 # User friendly plugin name (string value) #plugin_name = PKCS11 HSM # Generate IVs for CKM_AES_GCM mechanism. (boolean value) # Deprecated group/name - [p11_crypto_plugin]/generate_iv #aes_gcm_generate_iv = true # HMAC key wrap mechanism hmac_keywrap_mechanism = CKM_AES_MAC
The HMAC and MKEK keys can be generated as follows:
barbican-manage hsm gen_mkek --library-path \ /opt/utimaco/lib/libcs_pkcs11_R2.so --passphrase XXX \ --slot-id 0 --label 'my_mkek'barbican-manage hsm gen_hmac --library-path \ /opt/utimaco/lib/libcs_pkcs11_R2.so --passphrase XXX \ --slot-id 0 --label 'my_hmac_key'
KMIP Plugin¶
This secret store plugin is used to communicate with a KMIP device. The secret is securely stored in the KMIP device directly, rather than in the Barbican database. The Barbican database maintains a reference to the secret’s location for later retrieval.
The plugin can be configured to authenticate to the KMIP device using either a username and password, or using a client certificate.
The configuration for this plugin in /etc/barbican/barbican.conf is as follows:
[secretstore] .. enabled_secretstore_plugins = kmip_crypto [kmip_plugin] username = 'admin' password = 'password' host = localhost port = 5696 keyfile = '/path/to/certs/cert.key' certfile = '/path/to/certs/cert.crt' ca_certs = '/path/to/certs/LocalCA.crt'
Dogtag Plugin¶
Dogtag is the upstream project corresponding to the Red Hat Certificate System, a robust, full-featured PKI solution that contains a Certificate Manager (CA) and a Key Recovery Authority (KRA) which is used to securely store secrets.
The KRA stores secrets as encrypted blobs in its internal database, with the master encryption keys being stored either in a software-based NSS security database, or in a Hardware Security Module (HSM).
Note that the software-based NSS database configuration provides a secure option for those deployments that do not require or cannot afford an HSM. This is the only current plugin to provide this option.
The KRA communicates with HSMs using PKCS#11. For a list of certified HSMs, see the latest release notes. Dogtag and the KRA meet all the relevant Common Criteria and FIPS specifications.
The KRA is a component of FreeIPA. Therefore, it is possible to configure the plugin with a FreeIPA server. More detailed instructions on how to set up Barbican with FreeIPA are provided here.
The plugin communicates with the KRA using a client certificate for a trusted KRA agent. That certificate is stored in an NSS database as well as a PEM file as seen in the configuration below.
The configuration for this plugin in /etc/barbican/barbican.conf is as follows:
[secretstore] .. enabled_secretstore_plugins = dogtag_crypto [dogtag_plugin] pem_path = '/etc/barbican/kra_admin_cert.pem' dogtag_host = localhost dogtag_port = 8443 nss_db_path = '/etc/barbican/alias' nss_password = 'password123'
