> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test PKI operations

> Guided walkthrough demonstrating PKI operations using Vault and KMES, including CA creation and signing.

This section shows several PKI operations to demonstrate how to create Root and Intermediate CAs, which can then issue leaf certificates under them.

## Initialize Vault

Before performing the test PKI operations, perform the following steps to initialize, unseal (if required), and log in to Vault:

<Steps>
  <Step>
    In a different terminal window from where Vault is running, run the following commands to set the `VAULT_ADDR` and `PIN` environment variables.

    ```shell expandable lines wrap title="Shell" theme={null}
    export VAULT_ADDR='http://127.0.0.1:8200'
    export PIN= <HSM_PIN>
    ```
  </Step>

  <Step>
    Run the following command to check the Vault status.

    ```shell expandable lines wrap title="Shell" theme={null}
    vault status
    ```

    <Check>
      If the operation succeeds, the output should be similar to the following example:

      ```shell expandable lines wrap title="Shell" theme={null}
      Key                      Value
      ---                      -----
      Recovery Seal Type       pkcs11
      Initialized              false
      Sealed                   true
      Total Recovery Shares    0
      Threshold                0
      Unseal Progress          0/0
      Unseal Nonce             n/a
      Version                  n/a
      HA Enabled               false
      ```
    </Check>
  </Step>

  <Step>
    Run the following command to initialize Vault:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault operator init -key-shares=1 -key-threshold=1
    ```

    <Warning>
      We do not recommend using `1` for both the key shares and the key threshold in production.
    </Warning>

    <Check>
      If the operation succeeds, the output should be similar to the following example:

      ```shell expandable lines wrap title="Shell" theme={null}
      Unseal Key 1: qK4pHBY46Zxg2nt/cMgeLGh01Kh9SQ1ChOIDHPe/kmg=

      Initial Root Token: hvs.iYjhzPiwz00bpqX6rmzSe7yj

      Success! Vault is initialized

      Recovery key initialized with 1 key shares and a key threshold of 1. Please
      securely distribute the key shares printed above.
      ```
    </Check>
  </Step>

  <Step>
    If the HSM auto unseal is not configured, run the following command to unseal Vault manually:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault operator unseal <Unseal Key 1 provided from above>
    ```
  </Step>

  <Step>
    Run the following command to log in to Vault:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault login <Initial Root Token provided from above>
    ```
  </Step>
</Steps>

## Generate managed keys

Perform the following steps to generate managed keys on the KMES Series 3 for the Root and intermediate CA:

<Steps>
  <Step>
    Run the following command to generate a managed key on the KMES Series 3 for the Root CA:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write /sys/managed-keys/pkcs11/hsm-key-root library=hsm1 token_label=Futurex pin=$PIN key_label="hsm-key-root" allow_generate_key=true allow_store_key=true mechanism=0x0001 key_bits=2048 any_mount=false 
    ```

    The value specified in the **library** field in the preceding command must match the value set in the **name** field of the **kms\_library** stanza in the Vault configuration file (shown in the following example). The value specified in the **token\_label** field in the preceding command must be **Futurex**.

    ```none expandable lines wrap title="None" theme={null}
    # Provide your Futurex HSM connection information
    kms_library "pkcs11" {
      name="hsm1"
      library = "/usr/local/bin/fxpkcs11/libfxpkcs11-Debug.so"
    }
    ```
  </Step>

  <Step>
    Run the following command to generate a managed key on the KMES for the intermediate CA:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write /sys/managed-keys/pkcs11/hsm-key-int library=hsm1 token_label=Futurex pin=$PIN key_label="hsm-key-int" allow_generate_key=true allow_store_key=true mechanism=0x0001 key_bits=2048 any_mount=false
    ```
  </Step>

  <Step>
    Run the following command to verify that the key configurations have been written to Vault:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault list /sys/managed-keys/pkcs11
    ```
  </Step>

  <Step>
    Run the following commands to verify that the key configurations are valid by test signing some data:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write -f /sys/managed-keys/pkcs11/hsm-key-root/test/sign
    vault write -f /sys/managed-keys/pkcs11/hsm-key-int/test/sign
    ```
  </Step>
</Steps>

## Enable the PKI Secrets Engine

Perform the following steps to enable the PKI Secrets Engine for the Root and intermediate CA:

<Steps>
  <Step>
    Run the following command to enable the PKI secrets engine for the Root CA:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault secrets enable -path=pki -allowed-managed-keys=hsm-key-root pki
    ```
  </Step>

  <Step>
    Run the following command to enable the PKI secrets engine for the Intermediate CA:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault secrets enable -path=pki_int -allowed-managed-keys=hsm-key-int pki 
    ```
  </Step>
</Steps>

## Create a Root CA certificate

Perform the following steps to create a Root CA certificate with the corresponding managed key that you generated and stored on the KMES Series 3:

<Steps>
  <Step>
    Run the following command to create a Root CA certificate with its corresponding managed key and output it to a file:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write -field=certificate pki/root/generate/kms managed_key_name=hsm-key-root common_name=example.com ttl=8760h > /tmp/CA_cert.crt
    ```
  </Step>

  <Step>
    Run the following command to verify that the certificate looks correct:

    ```none expandable lines wrap title="None" theme={null}
    cat /tmp/CA_cert.crt
    ```
  </Step>
</Steps>

## Create a CSR

Perform the following steps to create a CSR for the intermediate CA with the managed key that you generated and stored on the KMES Series 3

<Steps>
  <Step>
    Run the following command to create an Intermediate CA certificate with its corresponding managed key and output it to a file:

    <Note>
      The following command requires you to install the `jq` package on your system. This package processes JSON output.
    </Note>

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write -format=json pki_int/intermediate/generate/kms managed_key_name=hsm-key-int common_name="example.com" | jq -r '.data.csr' > /tmp/pki_intermediate.csr
    ```
  </Step>

  <Step>
    Run the following command to verify that the certificate looks correct:

    ```shell expandable lines wrap title="Shell" theme={null}
    cat /tmp/pki_intermediate.csr
    ```
  </Step>
</Steps>

## Sign the CA certificate

Perform the following steps to sign the intermediate CA certificate with the managed Root CA:

<Steps>
  <Step>
    Run the following command to sign the intermediate CA certificate with the managed Root CA and output it to a file:

    <Note>
      The following command requires you to install the `jq` package on your system. This package processes JSON output.
    </Note>

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write -format=json pki/root/sign-intermediate csr=@/tmp/pki_intermediate.csr format=pem_bundle ttl="43800h" | jq -r '.data.certificate' > /tmp/intermediate.cert.pem
    ```
  </Step>

  <Step>
    Run the following command to write the signed Intermediate CA certificate to Vault:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write pki_int/intermediate/set-signed certificate=@/tmp/intermediate.cert.pem
    ```
  </Step>
</Steps>

## Issue a leaf certificate

Perform the following steps to issue a leaf certificate from the intermediate CA:

<Steps>
  <Step>
    Run the following command to create a new role:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write pki_int/roles/example-dot-com allowed_domains="example.com" allow_subdomains=true max_ttl="720h"
    ```
  </Step>

  <Step>
    Run the following command to issue a leaf certificate:

    ```shell expandable lines wrap title="Shell" theme={null}
    vault write -format=json pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"
    ```
  </Step>
</Steps>