Skip to main content

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.

This section details the steps to configure the Ansible instance to integrate with the Futurex PKCS #11 library.

​
Create a key pair on the Vectera Plus

Perform the following tasks to create a key pair:

​
Set Futurex environment variables

In a terminal, run the following commands to set the required FXPKCS11 environment variables:
Shell
export FXPKCS11_MODULE=/path/to/libfxpkcs11.so;

export FXPKCS11_CFG=/path/to/fxpkcs11.cfg;
Be sure to modify the file path to match the location of libfxpkcs11.so and fxpkcs11.cfg on your system.

​
Create a key pair

In a terminal, run the following command to create a new ECC key pair on the Vectera Plus by using pkcs11-tool:
Shell
sudo pkcs11-tool --module $FXPKCS11_MODULE --login --keypairgen --key-type rsa:2048 --label "ansible_rsa_privatekey" --id "123456"
When prompted for the user PIN, enter the identity password configured in the fxpkcs11.cfg file.
If successful, the command output lists the keys that pkcs11-tool created on the Vectera Plus.

​
Ansible playbooks

In Ansible, playbooks perform automated tasks. You can reference the Futurex PKCS #11 library when performing these tasks inside the playbook file to perform various functions, including SSH and signing data.

​
Use Futurex PKCS #11 with Ansible - SSH example

1
Run the following commands to create an Ansible project working directory and switch to it:
Shell
sudo mkdir ~/ansible_project
cd ~/ansible_project
2
Run the following command to create an inventory file:
Shell
sudo nano inventory
The following shows an example inventory file using localhost:
Shell
[local]
localhost ansible_connection=local
3
Run the following command to create a playbook.yml file:
Shell
sudo nano playbook.yml
The following shows an example Ansible playbook file for testing SSH referencing the private key created in the previous section (ansible_rsa_privatekey):
Shell
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so"
    pkcs11_pin: "safest"
    pkcs11_key_id: "ansible_rsa_privatekey"
  tasks:
    - name: Test connectivity
      command: echo "Hello, PKCS#11"

    - name: SSH to localhost using PKCS#11
      command: ssh -I {{ pkcs11_module }} jtitus@localhost echo "SSH with PKCS#11"
      register: ssh_result

    - name: Show SSH result
      debug:
        var: ssh_result.stdout
  • Replace pkcs11module with the location of the Futurex PKCS #11 library on your system.
  • Replace pkcs11pin with the password you configured for the identity created for this integration.
  • Replace pkcs11keyid with the label of the key you set when creating the key pair via PKCS11-tool.
4
To execute the playbook and reference the private key stored on the HSM during the SSH connection, run the following command, setting the username, inventory, and playbook file information according to your setup:
Shell
sudo ansible-playbook -u <your username> -i inventory playbook.yml -K
5
When prompted for the BECOME password in Ansible, use the become directive to escalate privileges when running tasks, similar to using sudo in the command line. The become_password is the user password specified in become_user (which defaults to root if not specified).
6
When prompted, enter the password of the user you are connecting to the machine with through SSH.
After entering the password, the process completes. If successful, you see a response similar to the following:
Shell
PLAY [local] ***************************************************************************************************************************************************************************************

TASK [Gathering Facts]**************************************************************************************************************************************************************************
ok: [localhost]

TASK [Test connectivity] ************************************************************************************************************************************************************************
changed: [localhost]

TASK [SSH to localhost using PKCS#11] ***********************************************************************************************************************************************************
user@localhost's password: 
changed: [localhost]

TASK [Show SSH result]**************************************************************************************************************************************************************************
ok: [localhost] => {
    "ssh_result.stdout": "<FXPKCS11 Log Output>" 
}

PLAY RECAP*****************************************************************************************************************************************************************************************
localhost                  : ok=4    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
7
You can verify the successful pull of the private key within the FXPKCS11 log file or the log output shown in the command response.

​
Encrypting and signing data example

The following steps demonstrate using Futurex PKCS #11 with Ansible to encrypt and sign data:
1
Run the following commands to create an Ansible project working directory and switch to it:
Shell
sudo mkdir ~/ansible_project
cd ~/ansible_project
2
Run the following command to create an inventory file:
Shell
sudo nano inventory
The following example shows an inventory file using localhost:
Shell
[local]
localhost ansible_connection=local
3
Run the following command to create a playbook.yml file:
Shell
sudo nano playbook.yml
The following example shows an Ansible playbook file you can copy and use for encrypting data and signing data referencing the private key created in the previous section (ansible_rsa_privatekey):
  • Replace pkcs11\module with the location of the Futurex PKCS #11 library on your system.
  • Replace pkcs11\pin with the password you configured for the identity created for this integration.
  • Replace pkcs11\key\id with the label of the key you set when creating the key pair by using PKCS11-tool.
Shell
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so"
    pkcs11_pin: "safest"
    pkcs11_key_id: "ansible_rsa_privatekey"
    data_to_encrypt: "Hello, PKCS#11"
    data_to_sign: "Sign this data"
  tasks:
    - name: Encrypt data using PKCS#11
      shell: |
        echo -n "{{ data_to_encrypt }}" | openssl pkeyutl -engine pkcs11 -keyform engine -inkey "pkcs11:object={{ pkcs11_key_id }}" -sign -out encrypted_data.bin
      register: encrypt_result
      environment:
        PKCS11_MODULE: "{{ pkcs11_module }}"
        PKCS11_PIN: "{{ pkcs11_pin }}"

    - name: Show encryption result
      debug:
        msg: "Data encrypted successfully"

    - name: Sign data using PKCS#11
      shell: |
        echo -n "{{ data_to_sign }}" | openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:object={{ pkcs11_key_id }}" -out signed_data.bin
      register: sign_result
      environment:
        PKCS11_MODULE: "{{ pkcs11_module }}"
        PKCS11_PIN: "{{ pkcs11_pin }}"

    - name: Show signing result
      debug:
        msg: "Data signed successfully"
4
To execute the playbook and reference the private key stored on the HSM during the SSH connection, run the following command, setting the username, inventory, and playbook file information according to your setup:
Shell
sudo ansible-playbook -u <your username> -i inventory playbook.yml -K
5
When prompted for the BECOME password in Ansible, use the become directive to escalate privileges when running tasks, similar to using sudo in the command line. The become_password is the password for the user specified in become_user (which defaults to root if not specified).
If successful, you should see a response similar to the following:
Shell
PLAY [local] ***************************************************************************************************************************************************************************************

TASK [Gathering Facts]**************************************************************************************************************************************************************************
ok: [localhost]

TASK [Encrypt data using PKCS#11] ***************************************************************************************************************************************************************
changed: [localhost]

TASK [Show encryption result]*******************************************************************************************************************************************************************
ok: [localhost] => {
    "msg": "Data encrypted successfully"
}

TASK [Sign data using PKCS#11]******************************************************************************************************************************************************************
changed: [localhost]

TASK [Show signing result]**********************************************************************************************************************************************************************
ok: [localhost] => {
    "msg": "Data signed successfully"
}

PLAY RECAP *****************************************************************************************************************************************************************************************
localhost                  : ok=5    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
6
You can verify the signing and encryption operations within the FXPKCS11 log file or by checking the contents of the output file.