> ## 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 to test OpenSSL engine functionality using environment variables and example commands.

Perform the following tasks to test OpenSSL engine:

1. Set FXPKCS11 environment variables.
2. Explore some OpenSSL Engine examples.

## Set FXPKCS11 environment variables

In a terminal, run the following sequence of commands to set the required **FXPKCS11** environment variables:

```shell expandable lines wrap title="Shell" theme={null}
export FXPKCS11_MODULE=/path/to/libfxpkcs11.so;
export FXPKCS11_CFG=/path/to/fxpkcs11.cfg;
```

### Create a key pair

Perform the following steps to create a key pair on the Vectera Plus by using **pkcs11-tool**:

<Steps>
  <Step>
    In a terminal, run the following command to use **pkcs11-tool** to create a new key pair on the Vectera Plus:

    ```shell expandable lines wrap title="Shell" theme={null}
    pkcs11-tool --module $FXPKCS11_MODULE --login --keypairgen --key-type rsa:2048 --label "my_rsa2048_key" --id "123456" --usage-sign --usage-decrypt
    ```
  </Step>

  <Step>
    Enter the password of the identity configured in the `fxpkcs11.cfg` file when prompted for the User PIN.

    <Check>
      If the command succeeds, the keys display in the output, as shown in the following example:

      ```shell expandable lines wrap title="Shell" theme={null}
      Key pair generated:
      Private Key Object; RSA 
        label:      myrsa2048key
        ID:         123456
        Usage:      decrypt, sign, unwrap
        Access:     sensitive, local
      Public Key Object; RSA 2048 bits
        label:      myrsa2048key
        ID:         123456
        Usage:      encrypt, verify, wrap
        Access:     local
      ```

      The command creates the following keys, which the next section uses in the test OpenSSL commands:

      * A private RSA 2048 key with asymmetric sign and verify usage
      * A public RSA 2048 key with verify usage.
    </Check>
  </Step>
</Steps>

## OpenSSL example commands

Most of the following OpenSSL example commands use the keys created on the Vectera Plus in the previous section. All the commands that use the keys created on the HSM specify the PKCS11 OpenSSL engine.

This section does not provide an exhaustive list of OpenSSL commands that you can run by using the PKCS11 OpenSSL Engine. Instead, it provides a few examples of use cases and confirms that you configured everything correctly. Refer to the OpenSSL documentation ([**www.openssl.org/docs/**](http://www.openssl.org/docs/)) for the full list of compatible commands.

### Example 1: Output the public key

In a terminal, run the following command to output the public key from the HSM:

```shell expandable lines wrap title="Shell" theme={null}
openssl rsa -engine pkcs11 -pubout -inform engine -in "pkcs11:object=my_rsa2048_key"
```

<Check>
  If the command succeeds, you should see output similar to the following example:

  ```shell expandable lines wrap title="Shell" theme={null}
  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>

### Example 2: Encrypt and decrypt data

Perform the following steps to encrypt data with the public key and decrypt with the HSM stored private key:

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

    ```shell expandable lines wrap title="Shell" theme={null}
    echo "This is a test file" > ./clear_data
    ```
  </Step>

  <Step>
    Retrieve the public key from the HSM.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl rsa -engine pkcs11 -inform ENGINE -in "pkcs11:object=my_rsa2048_key" -pubout -outform PEM -out pubkey.pem
    ```
  </Step>

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

    ```shell expandable lines wrap title="Shell" theme={null}
    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 HSM stored private key and output the results to a file, `clear_ data2`.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -engine pkcs11 -keyform engine -inkey "pkcs11:object=my_rsa2048_key" -decrypt -in ./encrypted_data -out ./clear_data2 -pkeyopt rsa_padding_mode:oaep
    ```
  </Step>

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

    ```shell expandable lines wrap title="Shell" theme={null}
    diff clear_data clear_data2
    ```
  </Step>
</Steps>

### Example 3: Sign a file and verify the signature

Perform the following step to sign a data file using the HSM stored private key and verify the signature by using the public key:

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

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -engine pkcs11 -keyform engine -inkey "pkcs11:object=my_rsa2048_key" -sign -in ./clear_data -out ./clear_data.sig
    ```
  </Step>

  <Step>
    Verify the signature by using the public key.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -pubin -inkey pubkey.pem -verify -in ./clear_data -sigfile ./clear_data.sig
    ```

    <Check>
      A message should display on the screen confirming that the signature was verified successfully.
    </Check>
  </Step>
</Steps>

### Example 4: Create a self-signed Root CA

Perform the following steps to create a self-signed Root CA:

<Steps>
  <Step>
    Generate a self-signed CA certificate with the HSM stored private key.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl req -new -x509 -engine pkcs11 -keyform engine -key "pkcs11:object=my_rsa2048_key" -out ssl-ca-cert.pem -days 365
    ```
  </Step>

  <Step>
    When prompted, enter information about the self-signed CA certificate.

    <Check>
      After you enter the information, the command creates the follwoing file: `ssl-ca-cert.pem`.
    </Check>
  </Step>
</Steps>

### Example 5: Generate a CSR

Perform the following steps to generate a CSR:

<Steps>
  <Step>
    Generate a CSR with the HSM stored private key.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl req -new -engine pkcs11 -keyform engine -key "pkcs11:object=my_rsa2048_key" -out ssl-client-cert-req.pem -days 365
    ```
  </Step>

  <Step>
    When prompted, enter information about the certificate.

    <Check>
      After you enter the information, the command creates the following file: `ssl-client-cert-req.pem`.
    </Check>
  </Step>
</Steps>

### Example 6: Sign a CSR

Execute the following command to sign a CSR by using the HSM-stored private key:

```shell expandable lines wrap title="Shell" theme={null}
openssl x509 -req -engine pkcs11 -in ssl-client-cert-req.pem -CA ssl-ca-cert.pem -CAkeyform engine -CAkey "pkcs11:object=my_rsa2048_key" -CAcreateserial -out signed-client-cert.pem -days 365
```

<Check>
  The command outputs the signed certificate to the `signed-client-cert.pem` file.
</Check>