Configure Ansible

5min
This section shows how to configure the Ansible instance to integrate with the  PKCS #11 library.
Create a key pair on the KMES Series 3 
Perform the tasks in the following sections to create a key pair on the :
Set Futurex PKCS #11 environment variables
1
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;
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 on the KMES Series 3 by using pkcs11-tool
1
In a terminal, run the following command to create a new RSA key pair on the :
Shell
sudo pkcs11-tool --module $FXPKCS11_MODULE --login --keypairgen --key-type rsa:2048 --label "ansible_rsa_privatekey" --id "123456"
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 password of the identity configured in the fxpkcs11.cfg file. 
If successful, the command output lists the keys that pkcs11-tool created on the .
Ansible Playbooks
In Ansible, Playbooks perform automated tasks. You can reference the  PKCS #11 library when performing these tasks inside the Playbook file to perform various functions, such as SSH and signing data. For more information on Ansible Playbooks, see the Ansible documentation. 
Use Futurex PKCS #11 with Ansible - SSH example
1
Create an Ansible project working directory and switch to it.
Shell
sudo mkdir ~/ansible_project
cd ~/ansible_project
sudo mkdir ~/ansible_project
cd ~/ansible_project
﻿
2
Create an inventory file. 
Shell
sudo nano inventory 
sudo nano inventory 
﻿
The following code shows an example inventory file using localhost:
Shell
[local]
localhost ansible_connection=local 
[local]
localhost ansible_connection=local 
﻿
3
Create a playbook.yml file.
Shell
sudo nano playbook.yml
sudo nano playbook.yml
﻿
The following code 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
---
- 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 pkcs11_module with the location of the  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 via PKCS11-tool.
4
To execute the Playbook and reference the private key stored on the HSM during 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
sudo ansible-playbook -u <your username> -i inventory playbook.yml -K
﻿
When prompted, enter the become_password In Ansible. The become directive escalates 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).
5
When prompted for the password of the user you are connecting to the machine with through SSH, enter it to complete the process.
If successful, you should 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 ********************************************************************************************************************************************************************************************
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 ********************************************************************************************************************************************************************************************
﻿
6
You can verify the successful pull of the private key within the FXPKCS11 log file or the log output shown in the command response.
Use Futurex PKCS #11 with Ansible - Signing Data example
1
Create an Ansible project working directory and switch to it.
Shell
sudo mkdir ~/ansible_project
cd ~/ansible_project
sudo mkdir ~/ansible_project
cd ~/ansible_project
﻿
2
Create an inventory file. 
Shell
sudo nano inventory 
sudo nano inventory 
﻿
The following code shows an example inventory file using localhost:
Shell
[local]
localhost ansible_connection=local 
[local]
localhost ansible_connection=local 
﻿
3
Create a playbook.yml file.
Shell
sudo nano playbook.yml
sudo nano playbook.yml
﻿
The following code shows an example Ansible Playbook file for signing data 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"
    data_to_sign: "Sign this data"
  tasks:
    - 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"
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so"
    pkcs11_pin: "safest"
    pkcs11_key_id: "ansible_rsa_privatekey"
    data_to_sign: "Sign this data"
  tasks:
    - 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"
﻿
Replace pkcs11_module with the location of the  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 via PKCS11-tool.
4
To execute the Playbook and reference the private key stored on the HSM during 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
sudo ansible-playbook -u <your username> -i inventory playbook.yml -K
﻿
When prompted, enter the become_password In Ansible. The become directive escalates 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).
5
When prompted for the password of the user you are connecting to the machine with through SSH, enter it to complete the process.
If successful, you should see a response similar to the following:
Shell
PLAY [local] *****************************************************************************

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

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

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

PLAY RECAP *******************************************************************************
localhost                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
PLAY [local] *****************************************************************************

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

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

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

PLAY RECAP *******************************************************************************
localhost                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
﻿
6
You can verify the signing operations within the FXPKCS11 log file or by checking the output file contents. 
﻿
Updated 14 Aug 2024
Did this page help you?
Install and configure OpenSSL Engine
Key management