• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main content
  • Documentation
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault

  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary

    • Overview
    • Replication
      • Overview
      • AWS KMS XKS
      • Oracle TDE
    • Automated Integrated Storage Snapshots
    • Automated Upgrades
    • Redundancy Zones
    • Lease Count Quotas
    • Entropy Augmentation
    • Seal Wrap
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
    • HCP Vault

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Vault Enterprise
  5. PKCS11 Provider
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

»PKCS#11 Provider

PKCS#11 is an open standard C API that provides a means to access cryptographic capabilities on a device. For example, it is often used to access a Hardware Security Module (HSM) (like a Yubikey) from a local program (such as GPG).

Vault provides a PKCS#11 library (or provider) so that Vault can be used as an SSM (Software Security Module). This allows a user to treat Vault like any other PKCS#11 device to manage keys, objects, and perform encryption and decryption in Vault using PKCS#11 calls. The PKCS#11 library connects to Vault's KMIP Secrets Engine to provide cryptographic operations and object storage.

Platform Support

This library works with Vault Enterprise 1.11+ with the advanced data protection module in the license with the KMIP Secrets Engine.

Operating SystemArchitectureDistributionglibc
Linuxx86-64RHEL 7 compatible2.17
Linuxx86-64RHEL 8 compatible2.28
Linuxx86-64RHEL 9 compatible2.34
macOSx86-64——

The provider comes in the form of a shared C library, libvault-pkcs11.so (for Linux) or libvault-pkcs11.dylib (for macOS). It can be downloaded from releases.hashicorp.com.

Quick Start

  1. To use the provider, you will need access to a Vault Enterprise instance with the KMIP Secrets Engine.

    For example, you can start one locally (if you have a license in the VAULT_LICENSE environment variable) with:

    docker pull hashicorp/vault-enterprise &&
    docker run --name vault \
      -p 5696:5696 \
      -p 8200:8200 \
      --cap-add=IPC_LOCK \
      -e VAULT_LICENSE=$(printenv VAULT_LICENSE) \
      -e VAULT_ADDR=http://127.0.0.1:8200 \
      -e VAULT_TOKEN=root \
      hashicorp/vault-enterprise \
      server -dev -dev-root-token-id root -dev-listen-address 0.0.0.0:8200
    
  2. Configure the KMIP Secrets Engine and a KMIP scope. The scope is used to hold keys and objects.

    Note: These commands will output the credentials in plaintext.

    vault secrets enable kmip
    vault write kmip/config listen_addrs=0.0.0.0:5696
    vault write -f kmip/scope/my-service
    vault write kmip/scope/my-service/role/admin operation_all=true
    vault write -f -format=json kmip/scope/my-service/role/admin/credential/generate | tee kmip.json
    

    Important: When configuring KMIP in production, you will probably need to set the server_hostnames and server_ips configuration parameters, otherwise the TLS connection to the KMIP Secrets Engine will fail due to certification validation errors.

    This last line will generate a JSON file with the certificate, key, and CA certificate chain to connect to the KMIP server. You'll need to save these to files so that the PKCS#11 provider can use them.

    jq --raw-output --exit-status '.data.ca_chain[]' kmip.json > ca.pem
    jq --raw-output --exit-status '.data.certificate' kmip.json > cert.pem
    

    The certificate file from the KMIP Secrets Engine also contains the key.

  3. Create a configuration file called vault-pkcs11.hcl:

    slot {
      server = "127.0.0.1:5696"
      tls_cert_path = "cert.pem"
      ca_path = "ca.pem"
      scope = "my-service"
    }
    

    See below for all available parameters.

  4. Copy the certificates from the KMIP credentials into the files specified in the configuration file (e.g., cert.pem, and ca.pem).

  5. You should now be able to use the libvault-pkcs11.so (or .dylib) library to access the KMIP Secrets Engine in Vault using any PKCS#11-compatible tool, like OpenSC's pkcs11-tool, e.g.:

    $ VAULT_LOG_FILE=/dev/null pkcs11-tool --module ./libvault-pkcs11.so -L
    Available slots:
    Slot 0 (0x0): Vault slot 0
    token label        : Token 0
    token manufacturer : HashiCorp
    token model        : Vault Enterprise
    token flags        : token initialized, PIN initialized, other flags=0x60
    hardware version   : 1.12
    firmware version   : 1.12
    serial num         : 1234
    pin min/max        : 0/255
    
    $ VAULT_LOG_FILE=/dev/null pkcs11-tool --module ./libvault-pkcs11.so --keygen -a abc123 --key-type AES:32 \
    --extractable --allow-sw 2>/dev/null
    Key generated:
    Secret Key Object; AES length 32
    VALUE:
    label:      abc123
    Usage:      encrypt, decrypt, wrap, unwrap
    Access:     none
    

    The VAULT_LOG_FILE=/dev/null setting is to prevent the Vault PKCS#11 driver logs from appearing in stdout (the default if no file is specified). In production, it's good to set VAULT_LOG_FILE to point to somewhere more permanent, like /var/log/vault.log.

Configuration

The PKCS#11 Provider can be configured through an HCL file and through envionment variables.

The HCL file contains directives to map PKCS#11 device slots (logical devices) to Vault instances and KMIP scopes and configures how the library will authenticate to KMIP (with a client TLS certificate). The PKCS#11 library will look for this file in vault-pkcs11.hcl and /etc/vault-pkcs11.hcl by default, or you can override this by setting the VAULT_KMIP_CONFIG environment variable.

For example,

slot {
    server = "127.0.0.1:5696"
    tls_cert_path = "cert.pem"
    ca_path = "ca.pem"
    scope = "my-service"
}

The slot block configures the first PKCS#11 slot to point to Vault. Most programs will use only one slot.

  • server (required): the Vault server's IP or DNS name and port number (5696 is the default).
  • tls_cert_path (required): the location of the client TLS certificate used to authenticate to the KMIP engine.
  • tls_key_path (optional, defaults to the value of tls_cert_path): the location of the encrypted or unencrypted TLS key used to authenticate to the KMIP engine.
  • ca_path (required): the location of the CA bundle that will be used to verify the server's certificate.
  • scope (required): the KMIP scope to authenticate against and where the TDE master keys and associated metadata will be stored.
  • cache (optional, default true): if the provider uses a cache to improve the performance of C_GetAttributeValue (KMIP: GetAttributes) calls.
  • emulate_hardware (optional, default false): specifies if the provider should report that it is connected to a hardware device.

The default location the PKCS#11 library will look for the configuration file is the current directory (vault-pkcs11.hcl) and /etc/vault-pkcs11.hcl, but you can override this by setting the VAULT_KMIP_CONFIG environment variable to any file.

Environment variables can be also used to configure these parameters and more.

  • VAULT_KMIP_CONFIG: location of the HCL configuration file. By default, the provider will check ./vault-pkcs11.hcl and /etc/vault-pkcs11.hcl.
  • VAULT_KMIP_CERT_FILE: location of the TLS certificate used for authentication to the KMIP engine.
  • VAULT_KMIP_KEY_FILE: location of the TLS key used for authentication to the KMIP engine.
  • VAULT_KMIP_KEY_PASSWORD: password for the TLS key file, if it is encrypted to the KMIP engine.
  • VAULT_KMIP_CA_FILE: location of the TLS CA bundle used to authenticate the connection to the KMIP engine.
  • VAULT_KMIP_SERVER: address and port of the KMIP engine to use for encryption and storage.
  • VAULT_KMIP_SCOPE: KMIP scope to use for encryption and storage
  • VAULT_KMIP_CACHE: whether or not to cache C_GetAttributeValue (KMIP: GetAttributes) calls.
  • VAULT_LOG_LEVEL: the log level that the provider will use. Defaults to WARN. Valid values include TRACE, DEBUG, INFO, WARN, ERROR, and OFF.
  • VAULT_LOG_FILE: the location of the file the provider will use for logging. Defaults to standard out.
  • VAULT_EMULATE_HARDWARE: whether or not the provider will report that it is backed by a hardware device.

Encrypted TLS Key Support

The TLS key returned by the KMIP engine is unencrypted by default. However, the PKCS#11 provider does support (limited) encryption options for the key using RFC 1423. We would only recommend using AES-256-CBC out of the available algorithms.

The keys from KMIP should be ECDSA keys, and can be encrypted with a password with OpenSSL, e.g.,:

openssl ec -in cert.key -out encrypted.key -aes-256-cbc

The PKCS#11 provider will need access to the password to decrypt the TLS key. The password can be supplied to the provider in two ways:

  • The VAULT_KMIP_KEY_PASSWORD environment variable, or
  • the "PIN" parameter to the C_Login PKCS#11 function will be used to try to decrypt an encrypted TLS key.

Note that only a single password can be supplied via the VAULT_KMIP_KEY_PASSWORD, so if multiple slots in the HCL file use encrypted TLS keys, they will need to be encrypted with the same password, or use the C_Login method to specify the password.

Error Handling

If an error occurs, the first place to check will be the VAULT_LOG_FILE for any relevant error messages.

If the PKCS#11 provider returns an error code of 0x30 (CKR_DEVICE_ERROR), then an additional device error code may be available from the C_SessionInfo call. Here are the known device error codes the provider will return:

CodeMeaning
400Invalid input was provided in the configuration or PKCS#11 call.
401Invalid credentials were provided.
404The object, attribute, or key was not found.
600An unknown I/O error occurred.
601A KMIP engine error occured.

Capabilities

The Vault PKCS#11 provider implements the following PKCS#11 provider profiles:

  • Baseline
  • Extended

The following mechanisms are currently supported, as of Vault 1.12:

NameMechanism Number
AES key generation0x1080
AES-CBC0x1082
AES-CBC Pad0x1085
AES-CTR0x1086
AES-GCM0x1087

Here is the list of supported and unsupported PKCS#11 functions:

  • Encryption and decryption
    • C_EncryptInit
    • C_Encrypt
    • C_EncryptUpdate
    • C_EncryptFinal
    • C_DecryptInit
    • C_Decrypt
    • C_DecryptUpdate
    • C_DecryptFinal
  • Key management
    • C_GenerateKey
    • C_GenerateKeyPair
    • C_WrapKey
    • C_UnwrapKey
    • C_DeriveKey
  • Objects
    • C_CreateObject
    • C_DestroyObject
    • C_GetAttributeValue
    • C_FindObjectsInit
    • C_FindObjects
    • C_FindObjectsFinal
    • C_SetAttributeValue
    • C_CopyObject
    • C_GetObjectSize
  • Management
    • C_Initialize
    • C_Finalize
    • C_Login (PIN is used as a passphrase for the TLS encryption key, if provided)
    • C_Logout
    • C_GetInfo
    • C_GetSlotList
    • C_GetSlotInfo
    • C_GetTokenInfo
    • C_GetMechanismList
    • C_GetMechanismInfo
    • C_OpenSession
    • C_CloseSession
    • C_CloseAllSessions
    • C_GetSessionInfo
    • C_InitToken
    • C_InitPIN
    • C_SetPIN
    • C_GetOperationState
    • C_SetOperationState
    • C_GetFunctionStatus
    • C_CancelFunction
    • C_WaitForSlotEvent
  • Signing
    • C_SignInit
    • C_Sign
    • C_SignUpdate
    • C_SignFinal
    • C_SignRecoverInit
    • C_SignRecover
    • C_VerifyInit
    • C_Verify
    • C_VerifyUpdate
    • C_VerifyFinal
    • C_VerifyRecoverInit
    • C_VerifyRecover
  • Digests
    • C_DigestInit
    • C_Digest
    • C_DigestUpdate
    • C_DigestKey
    • C_DigestFinal
    • C_DigestEncryptUpdate
    • C_DecryptDigestUpdate
    • C_SignEncryptUpdate
    • C_DecryptVerifyUpdate
  • Random Number Generation (see note below)
    • C_SeedRandom
    • C_GenerateRandom

Limitations and Notes

Due to the nature of Vault, the KMIP Secrets Engine, and PKCS#11, there are some other limitations to be aware of:

  • The key and object IDs returned by C_FindObjects, etc., are randomized for each session, and cannot be shared between sessions; they have no meaning after a session is closed. This is because KMIP objects, which are used to store the PKCS#11 objects, have long random strings as IDs, but the PKCS#11 object ID is limited to a 32-bit integer. Also, the PKCS#11 provider does not have any local storage.
  • The PKCS#11 provider's performance is heavily dependent on the latency to the Vault server and its performance. This is because nearly all PKCS#11 API calls are translated 1-1 to KMIP calls, aside from some object attribute calls (which can be locally cached). Multiple sessions can be safely used simultaneously though, and a single Vault server node has been tested as supporting thousands of ongoing sessions.
  • The object attribute cache is valid only for a single object per session, and will be cleared when another object's attributes are queried.
  • The random number generator function, C_GenerateRandom, is currently implemented in software in the library by calling out to Go's crypto/rand package, and does not call Vault.
Edit this page on GitHub

On this page

  1. PKCS#11 Provider
  2. Platform Support
  3. Quick Start
  4. Configuration
  5. Encrypted TLS Key Support
  6. Error Handling
  7. Capabilities
  8. Limitations and Notes
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)