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 Vectera Plus 
Perform the following two tasks to create a key pair:
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 Vectera Plus 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. You can reference 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. This is the password that Ansible Vault uses 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 organizations best practices.
For the following examples, this file is placed in the /tmp/ directory on the Linux machine. 
Encrypt example
You must copy and paste the contents of this example into a file with the .yml extension and modify as needed. (such as, encrypt.yml)
The following example, performs the follwing actions
Retrieves the key from the HSM.
Stores the key in a temporary file. 
Encryptes 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 own 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 and modify as needed. (such as, decrypt.yml)
The following example, performs the follwing actions
Retrieves the key from the HSM.
Stores the key in a temporary file. 
Encryptes 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 own 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 24 Oct 2024
Did this page help you?
OpenSSL Engine installation and configuration
Key management