luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

docs: Add docs for PKCS#11 provider (#17312) 

docs: Add docs for PKCS#11 provider

The PKCS#11 provider is being released shortly.
This moves over the preliminary docs and cleans them up.

I added them as a new section under "Vault Enterprise" ->
"PKCS#11 Provider", but I am open to suggestion on if there is a
better place for them, e.g., "Platforms", or somehow merging
with "Vault Enterprise" -> "HSM"?

Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
This commit is contained in:
Christopher Swenson 2022-10-03 11:11:46 -07:00 committed by GitHub
parent 9cc2f52bc1
commit ff8d8338cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 448 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

306
website/content/docs/enterprise/pkcs11-provider/index.mdx Normal file
View File

@ -0,0 +1,306 @@
---
layout: docs
page_title: PKCS#11 Provider - Vault Enterprise
description: |-
The Vault PKCS#11 Provider allows Vault KMIP Secrets Engine to be used via PKCS#11 calls.
The provider supports a subset of key generation, encryption, decryption and key storage operations.
This requires the Enterprise ADP-KM license.
---
# PKCS#11 Provider
[PKCS#11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html)
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](https://www.yubico.com/)) from a local program (such as [GPG](https://gnupg.org/)).
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](/docs/secrets/kmip) 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 System | Architecture | Distribution | glibc |
| ---------------- | -------------| ----------------- | ------- |
| Linux | x86-64 | RHEL 7 compatible | 2.17 |
| Linux | x86-64 | RHEL 8 compatible | 2.28 |
| Linux | x86-64 | RHEL 9 compatible | 2.34 |
| macOS | x86-64 | &mdash; | &mdash; |
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](https://releases.hashicorp.com/vault-pkcs11-provider).
## 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:
```sh
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
```
1. Configure the [KMIP Secrets Engine](/docs/secrets/kmip) and a KMIP *scope*. The scope is used to hold keys and objects.
```sh
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](/api-docs/secret/kmip#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.
```sh
jq -r '.data.ca_chain[]' kmip.json > ca.pem
jq -r '.data.certificate' kmip.json > cert.pem
```
The certificate file from the KMIP Secrets Engine also contains the key.
1. Create a configuration file called `vault-pkcs11.hcl`:
```hcl
slot {
server = "127.0.0.1:5696"
tls_cert_path = "cert.pem"
ca_path = "ca.pem"
scope = "my-service"
}
```
See [below](#configuration) for all available parameters.
1. Copy the certificates from the KMIP credentials into the files specified in the configuration file (e.g., `cert.pem`, and `ca.pem`).
1. 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.:
```sh
$ 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](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc416959678) (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,
```hcl
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](/docs/secrets/kmip#scopes-and-roles) 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](https://www.rfc-editor.org/rfc/rfc1423).
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.,:
```sh
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:
| Code | Meaning |
| ---- | ---------------------------------------------------------------- |
| 400 | Invalid input was provided in the configuration or PKCS#11 call. |
| 401 | Invalid credentials were provided. |
| 404 | The object, attribute, or key was not found. |
| 600 | An unknown I/O error occurred. |
| 601 | A KMIP engine error occured. |
## Capabilities
The Vault PKCS#11 provider implements the following PKCS#11 provider profiles:
- [Baseline](http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/os/pkcs11-profiles-v2.40-os.html#_Toc416960548)
- [Extended](http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/os/pkcs11-profiles-v2.40-os.html#_Toc416960554)
The following mechanisms are currently supported, as of Vault 1.12:
| Name | Mechanism Number |
| ------------------ | ---------------- |
| AES key generation | `0x1080` |
| AES-CBC | `0x1082` |
| AES-CBC Pad | `0x1085` |
| AES-CTR | `0x1086` |
| AES-GCM | `0x1087` |
Here is the list of supported and unsupported PKCS#11 functions:
- Encryption and decryption
- [x] `C_EncryptInit`
- [x] `C_Encrypt`
- [ ] `C_EncryptUpdate`
- [ ] `C_EncryptFinal`
- [x] `C_DecryptInit`
- [x] `C_Decrypt`
- [ ] `C_DecryptUpdate`
- [ ] `C_DecryptFinal`
- Key management
- [x] `C_GenerateKey`
- [ ] `C_GenerateKeyPair`
- [ ] `C_WrapKey`
- [ ] `C_UnwrapKey`
- [ ] `C_DeriveKey`
- Objects
- [x] `C_CreateObject`
- [x] `C_DestroyObject`
- [x] `C_GetAttributeValue`
- [x] `C_FindObjectsInit`
- [x] `C_FindObjects`
- [x] `C_FindObjectsFinal`
- [ ] `C_SetAttributeValue`
- [ ] `C_CopyObject`
- [ ] `C_GetObjectSize`
- Management
- [x] `C_Initialize`
- [x] `C_Finalize`
- [x] `C_Login` (PIN is used as a passphrase for the TLS encryption key, if provided)
- [x] `C_Logout`
- [x] `C_GetInfo`
- [x] `C_GetSlotList`
- [x] `C_GetSlotInfo`
- [x] `C_GetTokenInfo`
- [x] `C_GetMechanismList`
- [x] `C_GetMechanismInfo`
- [x] `C_OpenSession`
- [x] `C_CloseSession`
- [x] `C_CloseAllSessions`
- [x] `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
- [ ] `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.

129
website/content/docs/enterprise/pkcs11-provider/oracle-tde.mdx Normal file
View File

@ -0,0 +1,129 @@
---
layout: docs
page_title: Oracle TDE - PKCS#11 Provider - Vault Enterprise
description: |-
The Vault PKCS#11 Provider can be used to enable Oracle TDE.
---
# Oracle TDE
[Oracle Transparent Data Encryption](https://docs.oracle.com/database/121/ASOAG/introduction-to-transparent-data-encryption.htm#ASOAG10270) (TDE)
is supported with the [Vault PKCS#11 provider](/docs/enterprise/pkcs11-provider).
In this setup, Vault's KMIP engine generates and store the "TDE Master Encryption Key" that the Oracle Database uses to encrypt and decrypt the "TDE Table Keys".
Oracle will not have access to the TDE Master Encryption Key itself.
## Requirements
To setup Oracle TDE backed by Vault, the following are required:
- A database running Oracle 19 Enterprise Edition
- A Vault Enterprise 1.11+ server with Advanced Data Protection for KMIP support.
- Vault has TCP port 5696 accessible to the Oracle database.
- `libvault-pkcs11.so` downloaded from [releases.hashicorp.com](https://releases.hashicorp.com/vault-pkcs11-provider) for the operating system running the Oracle database (the RHEL 7 x86-64 version for Oracle Enterprise Linux 7).
## Vault Setup
On the Vault server, we need to [setup the KMIP Secrets Engine](/docs/secrets/kmip), e.g.:
1. Start the KMIP Secrets Engine and listener:
```sh
vault secrets enable kmip
vault write kmip/config listen_addrs=0.0.0.0:5696
```
~> **Important**: When configuring KMIP for Oracle, you will probably need to set the
`server_hostnames` and `server_ips` [configuration parameters](/api-docs/secret/kmip#parameters),
otherwise the TLS connection to the KMIP Secrets Engine will fail due to certification validation errors.
When configuring Oracle TDE, this error can manifest as the `sqlplus` session silently hanging.
1. Create a KMIP scope to contain the TDE keys and objects.
The KMIP scope is essentially an isolated namespace.
For example, you can create a scope called `my-service`:
```sh
vault write -f kmip/scope/my-service
```
1. Create a KMIP role that has access to the scope:
```sh
vault write kmip/scope/my-service/role/admin operation_all=true
```
1. Create TLS credentials (a certificate, key, and CA bundle) for the KMIP role:
```sh
vault write -f -format=json kmip/scope/my-service/role/admin/credential/generate | tee kmip.json
```
The response from the `credential/generate` endpoint is JSON.
The `.data.certificate` entry contains a bundle of the TLS client key and certificate we will use to connect to KMIP with from Oracle.
The `.data.ca_chain[]` entries contain the CA bundle to verify the KMIP server's certificate.
Save these to, e.g., `cert.pem` and `ca.pem`:
```sh
jq -r '.data.ca_chain[]' kmip.json > ca.pem
jq -r '.data.certificate' kmip.json > cert.pem
```
## Oracle TDE Preparation
The rest of the steps take place on the Oracle server.
We need to configure the Vault PKCS#11 provider.
1. Copy the `libvault-pkcs11.so` binary into `$ORACLE_BASE/extapi/64/hsm/vault/0.0.1/`, and ensure there are no other PKCS#11 libraries in `$ORACLE_BASE/extapi/64/hsm`.
1. Copy the TLS certificate and key bundle (e.g., `/etc/cert.pem`) and CA bundle (e.g., `/etc/ca.pem`) for the KMIP role (configured as above) to the Oracle server.
The exact location does not matter as long as the Oracle process has access to it.
1. Create a configuration file, for example `/etc/vault-pkcs11.hcl`, with the following contents:
```hcl
slot {
server = "VAULT_ADDRESS:5696"
tls_cert_path = "/etc/cert.pem"
ca_path = "/etc/ca.pem"
scope = "my-service"
}
```
This file is used by `libvault-pkcs11.so` to know how to find and communicate with the KMIP engine in Vault.
In particular:
- The `slot` block configures the first PKCS#11 slot to point to Vault. Oracle will use this first slot.
- `server` should point to the Vault server's IP (or DNS name) and port number (5696 is the default).
- `tls_cert_path` should be the location on the Oracle database of the client TLS certificate and key bundle used to connect to Vault server.
- `ca_path` should be the location of the CA bundle on the Oracle database.
- `scope` is the KMIP scope to authenticate against and where the TDE master keys and associated metadata will be stored.
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.
1. If you want to view the Vault logs (helpful when trying to find error messages), you can specify the `VAULT_LOG_FILE` (default is stdout) and `VAULT_LOG_LEVEL` (default is `INFO`). We'd recommend setting `VAULT_LOG_FILE` to something like `/tmp/vault.log` or `/var/log/vault.log`. Other useful log levels are `WARN` (quieter) and `TRACE` (very verbose, could possibly contain sensitive information, like raw network packets).
## Enable TDE
The only remaining step is to setup Oracle TDE for an external HSM using shared library, `libvault-pkcs11.so`.
These steps are not specific to Vault, other than requiring the shared library, HCL configuration, and certificates be present.
TDE is complex, but an example way to enable it is:
1. Create or update the `sqlnet.ora` (usually in `$ORACLE_BASE/oradata/dbconfig/$SID/sqlnet.ora`) configuration file to use an HSM encryption wallet by adding the following line:
```
encryption_wallet_location=(source=(method=hsm))
```
1. Restart the Oracle database so that it picks up the `sqlnet.ora` changes.
1. Open a `sqlplus` session into the root container (or switch into it with `ALTER SESSION SET CONTAINER = CDB$ROOT;`)
1. Open the HSM wallet: `ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "1234" CONTAINER = ALL;`.
The password `1234` here is used as the password for decyrpting the TLS key, if it is stored encrypted on disk.
If the TLS key is not encrypted, this password is ignored.
1. Create the TDE master key: `ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY USING TAG 'default' IDENTIFIED BY "1234" CONTAINER = ALL;`, again specifying the TLS key password if necessary.
1. Finally, use TDE in a PDB, e.g., `CREATE TABLE test_tde (something CHAR(32) ENCRYPT);`.
More extensive information on the details and procedures for Oracle TDE can be found in [Oracle's documentation](https://docs.oracle.com/database/121/ASOAG/asopart1.htm#ASOAG600).

13
website/data/docs-nav-data.json
View File

@ -2072,6 +2072,19 @@
}
]
},
{
"title": "PKCS11 Provider",
"routes": [
{
"title": "Overview",
"path": "enterprise/pkcs11-provider"
},
{
"title": "Oracle TDE",
"path": "enterprise/pkcs11-provider/oracle-tde"
}
]
},
{
"title": "Automated Integrated Storage Snapshots",
"path": "enterprise/automated-integrated-storage-snapshots"