This guide provides instructions for setting up OpenSSL to use a Cloud HSM
key on Debian 11 (Bullseye). These instructions are generally applicable even if
you're using another OS or environment, but be aware that there may be slight
differences.

## Requirements

Download a [release](https://github.com/GoogleCloudPlatform/kms-integrations/releases?q=pkcs%2311&expanded=true) of the library
to get started. For additional details about the PKCS #11 library, see the [user guide](https://github.com/GoogleCloudPlatform/kms-integrations/tree/master/kmsp11/docs/user_guide.md).

Before starting, install the `libengine-pkcs11-openssl` package.

```bash
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
```

## Configuration

### Setting the PKCS11_MODULE_PATH environment variable.

In order for `openssl` to use our PKCS #11 library, set the `PKCS11_MODULE_PATH`
environment variable:

```bash
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
```

To permanently set the environment variable, add
`export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"` to `/etc/profile`
by running the following command:

```bash
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile
```

### PKCS #11 library configuration

The PKCS #11 library requires a YAML configuration file to locate Cloud KMS
resources. The YAML must at a minimum configure a single PKCS #11 token.

If you are using OpenSSL with another process that may end up forking (for
example, Apache or Nginx), you must also ensure that the
`refresh_interval_secs` field remains unset, or is set to 0.

Sample configuration file:

```yaml
---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
```

With this configuration, all asymmetric signing and decryption keys in
`my-keyring` will be available in the library.

You must set the permissions on the configuration file so that it is writable
only by the file owner. Point `KMS_PKCS11_CONFIG` to your config file:

    export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

Again, you can make this setting permanent by adding it to `/etc/profile`.

```bash
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
```

## Running OpenSSL commands

With the engine and library properly configured, you may now use the engine in
OpenSSL commands.

When creating asymmetric signatures, keep in mind that Cloud KMS
keys are constrained to use a single digest. As an example, a CryptoKeyVersion
with the algorithm `EC_SIGN_P256_SHA256` must always be used in conjunction with
a SHA-256 digest. That corresponds to the `-sha256` flag in OpenSSL. Keys
that require SHA-384 or SHA-512 digests should be used with the `-sha384` or
`-sha512` flags.

> [!NOTE]
> **Note:** When creating asymmetric signatures using Cloud KMS keys with an algorithm starting with `RSA_PSS`, additional options are typically required by OpenSSL: `-sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest`.

### Create a new signature

Assuming there's a key named `foo` in your configured key ring, use the
following command to create a signature over `bar.txt`:

```bash
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt
```

The output of this command is unformatted binary.

That command assumes you are using a key that takes a SHA-256 digest, so the
`-sha256` argument was used. The `-sha384` or `-sha512` options would be
appropriate for Cloud HSM keys that use those digest types.

For an RSA-PSS key, remember to use the `-sigopt` options discussed previously.

### Create a new certificate signing request

You may also generate a certificate signing request (CSR) for a Cloud HSM
signing key. This is useful if your certificate authority requires a CSR in
order to generate a new certificate for code signing, or to protect TLS web
sessions.

    openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
      -keyform engine -key pkcs11:object=foo > my-request.csr

> [!NOTE]
> **Note:** Only create CSRs for Cloud KMS CryptoKeys with the `ASYMMETRIC_SIGN` purpose. In addition, take care to use the correct digest algorithm and `-sigopt` options for the key type.

### Generate a new self-signed certificate

For local development and testing, you can use a self-signed certificate for a
Cloud HSM signing key. Self-signed certificates are also useful for SAML
token signing.

    openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
      -keyform engine -key pkcs11:object=foo > my-request.crt

> [!NOTE]
> **Note:** Self-signed certificates for Cloud KMS CryptoKeys are only used for the `ASYMMETRIC_SIGN` purpose. In addition, take care to use the correct digest algorithm and `-sigopt` options for the key type.

## Troubleshooting with PKCS #11 Spy

PKCS #11 Spy is an open source tool that logs the contents of interactions over
the a PKCS #11 interface. It does this by sitting between the application and
the PKCS #11 library, and logging all the calls that are made. This can be
helpful for troubleshooting.

> [!CAUTION]
> **Caution:** Don't use PKCS #11 Spy with sensitive workloads. When configured, PKCS #11 Spy can observe all interactions with the HSM.

To use PKCS #11 Spy, you must have the `opensc` package installed. The
`opensc` package contains PKCS #11 Spy. To ensure that `opensc` is installed,
run the following command:

```bash
sudo apt-get install opensc
```

Then, set the `PKCS11_MODULE_PATH` environment variable to point OpenSSL at the
PKCS #11 Spy library by running the following command:

```bash
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
```

Finally, point PKCS #11 Spy to the Cloud HSM PKCS #11 library by setting the
`PKCS11SPY` and `PKCS11SPY_OUTPUT` environment variables. To set these environment
variables, run the following commands:

```bash
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"
```