Ansible Vault configuration

9min
This section details the steps to configure the Ansible instance to integrate with the  PKCS #11 library.
Create a key pair on the CryptoHub
Perform the following tasks to create a key pair:
1 | 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.
2 | Create a key pair on the CryptoHub by using pkcs11-tool
1
In a terminal, run the following command to create a new ECC key pair on the  by using pkcs11-tool:
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 Vault playbooks
In Ansible, playbooks perform automated tasks. Refer to the  PKCS #11 library when performing these tasks inside the playbook file to perform various functions, including encrypting and decrypting files.
Prerequisites
You must create a file for the Vault Password (such as vault_password_file.txt) and place it in the appropriate folder. The Ansible Vault uses this password to encrypt the HSM key and the file to be encrypted with the HSM key.
You must adjust the security of this file based on your organization best practices.
This file is placed in the /tmp/ directory on the Linux machine for the encrypt and decrypt examples in this section. 
Encrypt example
You must copy and paste the contents of this example into a file with the .yml extension (such as encrypt.yml) and modify it as needed.
This example performs the following actions:
Retrieves the key from the .
Stores the key in a temporary file. 
Encrypts the temporary file with Ansible Vault.
Uses the encrypted temporary key file to encrypt the target file.
Cleans the encrypted temporary key file from the system.
YAML
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so" # Insert path to pkcs11 lib 
    pkcs11_pin: "safest" # Password utilized in fxpkcs11.cfg 
    pkcs11_key_label: "ansible_rsa_privatekey"  # Update this based on the actual label used when generating key pair
    temp_key_file: "/tmp/hsm_key.txt" # Location of temporary file generated to be placed
    file_to_encrypt: "/home/futurex/Desktop/test.txt" # Location of file to encrypt 
    encrypted_file: "/home/futurex/Desktop/test.txt.enc" # Location of encrypted file to be placed after encrypt.yml is run
  tasks:
    - name: Test connectivity
      command: echo "Hello, PKCS#11"

    - name: List objects in the HSM
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --list-objects
      register: list_objects

    - name: Show the list of objects
      debug:
        var: list_objects.stdout

    - name: Retrieve encryption key from HSM using PKCS#11
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --read-object --label "{{ pkcs11_key_label }}" --type privkey
      register: hsm_key

    - name: Check if the HSM key was retrieved successfully
      fail:
        msg: "Failed to retrieve HSM key"
      when: hsm_key.rc != 0

    - name: Store HSM key in a temporary file
      copy:
        content: "{{ hsm_key.stdout }}"
        dest: "{{ temp_key_file }}"

    - name: Encrypt the HSM key using Ansible Vault
      command: >
        ansible-vault encrypt {{ temp_key_file }} --vault-password-file /tmp/vault_password_file
      register: vault_encryption

    - name: Encrypt the file using the HSM key
      command: >
        openssl enc -aes-256-cbc -salt -in {{ file_to_encrypt }} -out {{ encrypted_file }} -pass file:{{ temp_key_file }}
      when: hsm_key.stdout is not none and vault_encryption.rc == 0

    - name: Display success message
      debug:
        msg: "File encrypted successfully!"
      when: hsm_key.stdout is not none and vault_encryption.rc == 0

    - name: Clean up temporary files
      file:
        path: "{{ temp_key_file }}"
        state: absent
      when: hsm_key.stdout is not none
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so" # Insert path to pkcs11 lib 
    pkcs11_pin: "safest" # Password utilized in fxpkcs11.cfg 
    pkcs11_key_label: "ansible_rsa_privatekey"  # Update this based on the actual label used when generating key pair
    temp_key_file: "/tmp/hsm_key.txt" # Location of temporary file generated to be placed
    file_to_encrypt: "/home/futurex/Desktop/test.txt" # Location of file to encrypt 
    encrypted_file: "/home/futurex/Desktop/test.txt.enc" # Location of encrypted file to be placed after encrypt.yml is run
  tasks:
    - name: Test connectivity
      command: echo "Hello, PKCS#11"

    - name: List objects in the HSM
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --list-objects
      register: list_objects

    - name: Show the list of objects
      debug:
        var: list_objects.stdout

    - name: Retrieve encryption key from HSM using PKCS#11
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --read-object --label "{{ pkcs11_key_label }}" --type privkey
      register: hsm_key

    - name: Check if the HSM key was retrieved successfully
      fail:
        msg: "Failed to retrieve HSM key"
      when: hsm_key.rc != 0

    - name: Store HSM key in a temporary file
      copy:
        content: "{{ hsm_key.stdout }}"
        dest: "{{ temp_key_file }}"

    - name: Encrypt the HSM key using Ansible Vault
      command: >
        ansible-vault encrypt {{ temp_key_file }} --vault-password-file /tmp/vault_password_file
      register: vault_encryption

    - name: Encrypt the file using the HSM key
      command: >
        openssl enc -aes-256-cbc -salt -in {{ file_to_encrypt }} -out {{ encrypted_file }} -pass file:{{ temp_key_file }}
      when: hsm_key.stdout is not none and vault_encryption.rc == 0

    - name: Display success message
      debug:
        msg: "File encrypted successfully!"
      when: hsm_key.stdout is not none and vault_encryption.rc == 0

    - name: Clean up temporary files
      file:
        path: "{{ temp_key_file }}"
        state: absent
      when: hsm_key.stdout is not none
﻿
After you modify the playbook file according to your environment, use the following shell command to run the playbook:
Shell
sudo ansible-playbook -u <your username> -i inventory encrypt.yml -K
sudo ansible-playbook -u <your username> -i inventory encrypt.yml -K
﻿
Decrypt example
You must copy and paste the contents of this example into a file with the .yml extension (such as decrypt.yml) and modify it as needed. 
This example performs the following actions:
Retrieves the key from the .
Stores the key in a temporary file. 
Encrypts the temporary file with Ansible Vault.
Uses the encrypted temporary key file to decrypt the target file.
Cleans the encrypted temporary key file from the system.
YAML
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so" # Insert path to pkcs11 lib 
    pkcs11_pin: "safest" # Password utilized in fxpkcs11.cfg 
    pkcs11_key_label: "ansible_rsa_privatekey"  # Update this based on the actual label used when generating key pair
    temp_key_file: "/tmp/hsm_key.txt" # Location of temporary file generated to be placed
    encrypted_file: "/home/futurex/Desktop/test.txt.enc" # Location of encrypted file to be placed after encrypt.yml is run
    decrypted_file: "/home/futurex/Desktop/decrypted_test.txt" #Location of decrypted file to be placed after decrypt.yml is run
  tasks:
    - name: Test connectivity
      command: echo "Hello, PKCS#11"

    - name: List objects in the HSM
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --list-objects
      register: list_objects

    - name: Show the list of objects
      debug:
        var: list_objects.stdout

    - name: Retrieve encryption key from HSM using PKCS#11
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --read-object --label "{{ pkcs11_key_label }}" --type privkey
      register: hsm_key

    - name: Check if the HSM key was retrieved successfully
      fail:
        msg: "Failed to retrieve HSM key"
      when: hsm_key.rc != 0

    - name: Store HSM key in a temporary file
      copy:
        content: "{{ hsm_key.stdout }}"
        dest: "{{ temp_key_file }}"
    
    - name: Encrypt the HSM key using Ansible Vault
      command: >
        ansible-vault encrypt {{ temp_key_file }} --vault-password-file /tmp/vault_password_file
      register: vault_encryption

    - name: Decrypt the file using the HSM key
      command: >
        openssl enc -d -aes-256-cbc -in {{ encrypted_file }} -out {{ decrypted_file }} -pass file:{{ temp_key_file }}
      when: hsm_key.stdout is not none

    - name: Display decryption success message
      debug:
        msg: "File decrypted successfully!"
      when: hsm_key.stdout is not none

    - name: Clean up temporary files
      file:
        path: "{{ temp_key_file }}"
        state: absent
      when: hsm_key.stdout is not none
---
- hosts: local
  vars:
    pkcs11_module: "/usr/local/bin/fxpkcs11/libfxpkcs11.so" # Insert path to pkcs11 lib 
    pkcs11_pin: "safest" # Password utilized in fxpkcs11.cfg 
    pkcs11_key_label: "ansible_rsa_privatekey"  # Update this based on the actual label used when generating key pair
    temp_key_file: "/tmp/hsm_key.txt" # Location of temporary file generated to be placed
    encrypted_file: "/home/futurex/Desktop/test.txt.enc" # Location of encrypted file to be placed after encrypt.yml is run
    decrypted_file: "/home/futurex/Desktop/decrypted_test.txt" #Location of decrypted file to be placed after decrypt.yml is run
  tasks:
    - name: Test connectivity
      command: echo "Hello, PKCS#11"

    - name: List objects in the HSM
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --list-objects
      register: list_objects

    - name: Show the list of objects
      debug:
        var: list_objects.stdout

    - name: Retrieve encryption key from HSM using PKCS#11
      command: >
        pkcs11-tool --module {{ pkcs11_module }} --read-object --label "{{ pkcs11_key_label }}" --type privkey
      register: hsm_key

    - name: Check if the HSM key was retrieved successfully
      fail:
        msg: "Failed to retrieve HSM key"
      when: hsm_key.rc != 0

    - name: Store HSM key in a temporary file
      copy:
        content: "{{ hsm_key.stdout }}"
        dest: "{{ temp_key_file }}"
    
    - name: Encrypt the HSM key using Ansible Vault
      command: >
        ansible-vault encrypt {{ temp_key_file }} --vault-password-file /tmp/vault_password_file
      register: vault_encryption

    - name: Decrypt the file using the HSM key
      command: >
        openssl enc -d -aes-256-cbc -in {{ encrypted_file }} -out {{ decrypted_file }} -pass file:{{ temp_key_file }}
      when: hsm_key.stdout is not none

    - name: Display decryption success message
      debug:
        msg: "File decrypted successfully!"
      when: hsm_key.stdout is not none

    - name: Clean up temporary files
      file:
        path: "{{ temp_key_file }}"
        state: absent
      when: hsm_key.stdout is not none
﻿
After you modify the playbook file according to your environment, use the following shell command to run the playbook:
Shell
sudo ansible-playbook -u <your username> -i inventory decrypt.yml -K
sudo ansible-playbook -u <your username> -i inventory decrypt.yml -K
﻿
﻿
Updated 03 Feb 2025
Did this page help you?
Install and configure OpenSSL Engine
Key management