> ## 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 OpenSSL Engine

> Instructions and sample commands for testing OpenSSL Engine functionality.

This section walks through creating a key pair in CryptoHub and running several OpenSSL commands that use it through the OpenSSL pkcs11 engine you configured in the previous section.

Run these commands with `cryptohub.json` in the environment, matching the wiring from the previous section:

```
export CHLIBS_CONFIG=/etc/cryptohub.json
export OPENSSL_CONF=/etc/ssl/openssl-cryptohub-engine.cnf
```

`CHLIBS_CONFIG` must be present in the environment of any process that loads the module. The engine uses the module set through `MODULE_PATH` in `openssl.cnf`, so you do not set a separate module environment variable.

## Confirm the CryptoHub token label

The token label your `pkcs11:` URIs reference is the `cryptohubs[].label` value defined in your `cryptohub.json` (the default is `CryptoHub`). If OpenSC's `pkcs11-tool` is installed, list the token slots directly against the CryptoHub module to confirm it:

```
pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so --list-token-slots
```

## Create a key pair in CryptoHub

If you do not yet have a key in CryptoHub, generate one with the bundled interactive `pkcs11-manager`. Pass the configuration path as its first argument, initialize the module, log in with the endpoint's UserPass password, and select the key-generation action. Give the key a label you will reference from OpenSSL, for example `my_rsa2048_key`.

```
pkcs11-manager /etc/cryptohub.json
```

The key is created in CryptoHub with the asymmetric usages pinned by this template's `config.json` (Sign, Verify, Encrypt, and Decrypt), which is what the OpenSSL examples below exercise.

<Note>
  Keep the ENGINE configuration and `pkcs11:` URIs free of `PIN`, `pin-value`, and `pin-source`. The CryptoHub Client Library authenticates with the credential in the endpoint configuration.
</Note>

## OpenSSL example commands

Below are several OpenSSL example commands, most of which use the key created in CryptoHub above. In the commands that use a CryptoHub key, the pkcs11 OpenSSL engine is specified.

<Note>
  The purpose of this section is not to provide an exhaustive list of OpenSSL commands that you can run using the pkcs11 OpenSSL Engine, but rather to give a few examples of use-cases and confirm that everything is configured correctly. Refer to OpenSSL's documentation for the full list of compatible commands.
</Note>

Running one of these commands successfully forces a cryptographic operation against the key in CryptoHub: this is the proof that the engine reached CryptoHub, not merely that the configuration parses.

### Example 1: Output the public key from the CryptoHub

Perform the following step to output the public key from the CryptoHub:

<Steps>
  <Step>
    In a terminal, run the following command to output the public key:

    ```
    openssl rsa -engine pkcs11 -pubout -inform engine -in "pkcs11:token=CryptoHub;object=my_rsa2048_key;type=private"
    ```

    <Check>
      If the command succeeds, it should output the public key to the screen, similar to the following example:

      ```
      engine "pkcs11" set.
      writing RSA key
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoqFl+qYGJ9ou+tycLDCm
      7RSTKxYcytiqA2yD3WGfrd72X8iAkuB2QL/IF/Kande1gSRaCTs5vnC0JZ9SP0nU
      J3bY9b0GfXKR5kJsQGdQOKs29m0kyHjge7QRT6rfZuHhj8TRfqpPNzNnZU9MflMx
      85XlTLE2HUV+e1vKHfkFC1gQrULDQ1ROb8HZKe13k7SIv4iMOZrswq7qgvyFFWOV
      3Kn27yNsAKORMAoEPEwc5hre3rwJrP/W9I+EfFPDtMzI7wWPaQork3AE+bV3c8Dd
      +Iv7fnXKPjK/n+4ctjnMfeTT/tG99ShkhkJkHRqGr4VNFv34hOQlwcJYr6NLrCA4
      EQIDAQAB
      -----END PUBLIC KEY-----
      ```
    </Check>
  </Step>
</Steps>

### Example 2: Encrypt and decrypt data

Perform the following steps to encrypt data with the public key and decrypt it with the CryptoHub-stored private key:

<Steps>
  <Step>
    In a terminal, run the following command to generate a file called `clear_data` containing sample ASCII data:

    ```
    echo "This is a test file" > ./clear_data
    ```
  </Step>

  <Step>
    Retrieve the public key from the CryptoHub.

    ```
    openssl rsa -engine pkcs11 -inform ENGINE -in "pkcs11:token=CryptoHub;object=my_rsa2048_key;type=private" -pubout -outform PEM -out pubkey.pem
    ```
  </Step>

  <Step>
    Encrypt the `clear_data` file by using the public key retrieved from CryptoHub and output the results to a file called `encrypted_data`.

    ```
    openssl pkeyutl -pubin -inkey pubkey.pem -in ./clear_data -encrypt -out ./encrypted_data -pkeyopt rsa_padding_mode:oaep
    ```
  </Step>

  <Step>
    Decrypt the `encrypted_data` file by using the CryptoHub-stored private key and output the results to a file called `clear_data2`.

    ```
    openssl pkeyutl -engine pkcs11 -keyform engine -inkey "pkcs11:token=CryptoHub;object=my_rsa2048_key;type=private" -decrypt -in ./encrypted_data -out ./clear_data2 -pkeyopt rsa_padding_mode:oaep
    ```
  </Step>

  <Step>
    Confirm that the contents of the `clear_data` and `clear_data2` files are identical.

    ```
    diff clear_data clear_data2
    ```

    <Check>
      If the command runs successfully and the files are identical, no output is displayed.
    </Check>
  </Step>
</Steps>

### Example 3: Sign a data file

Perform the following steps to sign a data file using the CryptoHub-stored private key and verify the signature using the public key:

<Steps>
  <Step>
    Sign the `clear_data` file by using the CryptoHub-stored private key and output the signature to a file called `clear_data.sig`.

    ```
    openssl dgst -sha256 -engine pkcs11 -keyform engine -sign "pkcs11:token=CryptoHub;object=my_rsa2048_key;type=private" -out ./clear_data.sig ./clear_data
    ```
  </Step>

  <Step>
    Verify the signature using the public key.

    ```
    openssl dgst -sha256 -verify pubkey.pem -signature ./clear_data.sig ./clear_data
    ```

    <Check>
      The command outputs `Verified OK`.
    </Check>
  </Step>
</Steps>

### Example 4: Generate a CSR

Run the following command to generate a Certificate Signing Request (CSR) with the CryptoHub-stored private key:

```
openssl req -new -engine pkcs11 -keyform engine -key "pkcs11:token=CryptoHub;object=my_rsa2048_key;type=private" -subj "/CN=client.example.com" -out ssl-client-cert-req.pem
```

<Check>
  The command creates `ssl-client-cert-req.pem`. Run `openssl req -in ssl-client-cert-req.pem -noout -verify` and confirm that it outputs `Certificate request self-signature verify OK`.
</Check>