> ## 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.

# Validate and test

> Procedures to validate and test the OpenSSL provider integration using environment variables and example commands.

Perform the following tasks to test OpenSSL provider architecture:

1. Set FXPKCS11 environment variables.
2. Explore some OpenSSL Provider 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
```

### Create a key pair

Perform the following steps by using the **pkcs11-tool** available from the OpenSC ([**github.com/OpenSC/OpenSC**](https://github.com/OpenSC/OpenSC)) suite to generate keys. On both DEB-based and RPM-based distributions, the package is called `opensc`.

<Steps>
  <Step>
    In a terminal, execute the following command using **pkcs11-tool** to generate and store 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 executes successfully, the generated keys will appear 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, signRecover
        Access:     sensitive, local
      Public Key Object; RSA 2048 bits
        label:      myrsa2048key
        ID:         123456
        Usage:      encrypt, verify, verifyRecover
        Access:     local
      ```

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

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

## OpenSSL example commands

The following OpenSSL example commands use the keys created on the Vectera Plus in the previous section. All commands specify the PKCS11 OpenSSL provider and the provider path.

This section does not provide an exhaustive list of OpenSSL commands that you can run using the PKCS11 OpenSSL Provider. Instead, it gives a few examples of use cases and confirms everything was configured 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 to a file from the HSM:

```shell expandable lines wrap title="Shell" theme={null}
openssl rsa -provider pkcs11 -provider-path $FXPKCS11_MODULE -in "pkcs11:token=Futurex;object=my_rsa2048_key" -pubout -out my_rsa2048_pubkey.pem
```

<Check>
  If the command succeeds, you should see the `myrsa2048pubkey.pem` file was generated, which contains the public key.
</Check>

### Example 2: Encrypt and decrypt data

Follow these steps to encrypt data using the public key and decrypt it with the private key stored on the HSM:

<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>
    Encrypt the `clear_data` file using the HSM's public key and output the results to a file, `encrypted_data`.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -provider pkcs11 -provider-path FXPKCS11_MODULE -encrypt -inkey "pkcs11:token=Futurex;object=my_rsa2048_key" -pubin -in clear_data -out encrypted_data
    ```
  </Step>

  <Step>
    Decrypt the `encrypted_data` file using the HSM's private key and output the results to a file, `decrypted_data`.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -provider pkcs11 -provider-path $FXPKCS11_MODULE -decrypt -inkey "pkcs11:token=Futurex;object=my_rsa2048_key" -in encrypted_data -out decrypted_data
    ```
  </Step>

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

    ```shell expandable lines wrap title="Shell" theme={null}
    diff clear_data decrypted_data
    ```

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

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

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

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

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -provider pkcs11 -provider-path $FXPKCS11_MODULE -sign -inkey "pkcs11:token=Futurex;object=my_rsa2048_key" -in clear_data -out clear_data.sig
    ```
  </Step>

  <Step>
    Verify the signature by using the HSM's public key.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl pkeyutl -provider pkcs11 -provider-path $FXPKCS11_MODULE -verify -inkey "pkcs11:token=Futurex;object=my_rsa2048_key" -pubin -in clear_data -sigfile clear_data.sig 
    ```

    <Check>
      If the signature was verified successfully, the message `Signature Verified Successfully` should display on the screen.
    </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's private key.

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl req -new -x509 -provider pkcs11 -provider-path $FXPKCS11_MODULE -key "pkcs11:token=Futurex;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 entering the required information (or leaving fields blank as needed), a successful command execution will generate the `ssl-ca-cert.pem` file.
    </Check>
  </Step>
</Steps>

### Example 5: Generate a CSR

Perform the following steps to generate a CSR:

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

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl req -new -provider pkcs11 -provider-path $FXPKCS11_MODULE -key "pkcs11:token=Futurex;object=my_rsa2048_key" -out ssl-client-cert-req.csr -days 365
    ```
  </Step>

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

    <Check>
      After entering the required information (or leaving fields blank as needed), a successful command execution will generate the`ssl-client-cert-req.pem`file.
    </Check>
  </Step>
</Steps>

### Example 6: Sign a CSR

Execute the following command to sign the previously generated CSR by using the HSM-stored private key and the self-signed CA generated earlier:

```shell expandable lines wrap title="Shell" theme={null}
openssl x509 -req -provider pkcs11 -provider-path $FXPKCS11_MODULE -in ssl-client-cert-req.csr -CA ssl-ca-cert.pem -CAkey "pkcs11:token=Futurex;object=my_rsa2048_key" -CAcreateserial -out signed-client-cert.pem -days 365
```

<Check>
  A successful command execution will generate the`signed-client-cert.pem` file, containing the signed certificate. Also, a serial number file, `ssl-ca-cert.srl`, is created to track the certificate’s serial number for future CA operations.
</Check>