Validate the Ansible integration - Futurex Documentation

Validate both supported Ansible paths with one CryptoHub-backed RSA key:

Sign data from an OpenSSL command task.
Authenticate Ansible’s SSH connection plugin to a managed host.

Generate the CryptoHub key

Set the client-library configuration path and open the endpoint-provided manager:

export CHLIBS_CONFIG=/etc/ansible/cryptohub/cryptohub.json
pkcs11-manager /etc/ansible/cryptohub/cryptohub.json

Initialize the module and log in with the endpoint UserPass password.

Generate an RSA-2048 key named ansible_rsa_privatekey.The template creates the key as TRUSTED with Sign and Verify usages. Both procedures below use this single RSA usage class.

Install OpenSC, export the public key, and convert it to PEM:

sudo apt install -y opensc
pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so \
  --read-object --type pubkey --label ansible_rsa_privatekey \
  --output-file /tmp/ansible-public.der
openssl pkey -pubin -inform DER -in /tmp/ansible-public.der \
  -out /tmp/ansible-public.pem
sudo install -m 644 /tmp/ansible-public.pem \
  /etc/ansible/cryptohub/ansible-public.pem

The PEM file contains only the public key. The private key remains in CryptoHub.

Sign data from a playbook

Read the PKCS #11 token label from the endpoint configuration:

jq -r '.cryptohubs[0].label' /etc/ansible/cryptohub/cryptohub.json

Use the returned label for <token-label> in the next step.

Create sign.yml:

---
- name: Sign with a CryptoHub key
  hosts: localhost
  connection: local
  gather_facts: false
  vars:
    pkcs11_uri: "pkcs11:token=<token-label>;object=ansible_rsa_privatekey;type=private"
  environment:
    OPENSSL_CONF: /etc/ansible/cryptohub/openssl-cryptohub.cnf
    CHLIBS_CONFIG: /etc/ansible/cryptohub/cryptohub.json
  tasks:
    - name: Create proof data
      ansible.builtin.copy:
        dest: /tmp/ansible-message.txt
        content: "Ansible CryptoHub signing proof"
        mode: "0600"

    - name: Sign with the CryptoHub key
      ansible.builtin.command:
        argv:
          - openssl
          - dgst
          - -provider
          - pkcs11
          - -provider
          - default
          - -sha256
          - -sign
          - "{{ pkcs11_uri }}"
          - -out
          - /tmp/ansible-signature.bin
          - /tmp/ansible-message.txt

    - name: Verify the signature
      ansible.builtin.command:
        argv:
          - openssl
          - dgst
          - -sha256
          - -verify
          - /etc/ansible/cryptohub/ansible-public.pem
          - -signature
          - /tmp/ansible-signature.bin
          - /tmp/ansible-message.txt
      register: verify_result
      changed_when: false

    - name: Require a valid signature
      ansible.builtin.assert:
        that:
          - verify_result.rc == 0
          - "'Verified OK' in verify_result.stdout"

Run the playbook:

ansible-playbook -i localhost, sign.yml

The Verify the signature task reports ok, the assertion reports All assertions passed, and the play recap reports failed=0.

Authenticate Ansible SSH with the CryptoHub key

Ansible Core 2.12 and later provides the ansible_ssh_pkcs11_provider connection option. The plugin uses sshpass to supply the PKCS #11 PIN through a protected input pipe.

Install sshpass and convert the public key to OpenSSH format:

sudo apt install -y sshpass
ssh-keygen -i -m PKCS8 \
  -f /etc/ansible/cryptohub/ansible-public.pem > ansible-public.ssh

sshpass -V must report version 1.06 or later.

Add ansible-public.ssh to the target account’s ~/.ssh/authorized_keys.The target account now trusts the public half of the CryptoHub key.

Create a protected variable file. The command reads the endpoint UserPass password without echoing it and JSON-encodes the value as valid YAML:

sudo install -m 640 -o root -g <ansible-runner-group> /dev/null \
  /etc/ansible/cryptohub/ssh-pin-vars.yml
read -r -s -p "Endpoint UserPass password: " ANSIBLE_PKCS11_PIN
printf '\n'
printf '%s' "$ANSIBLE_PKCS11_PIN" | \
  python3 -c 'import json, sys; print("ansible_password: " + json.dumps(sys.stdin.read()))' | \
  sudo tee /etc/ansible/cryptohub/ssh-pin-vars.yml >/dev/null
unset ANSIBLE_PKCS11_PIN
sudo chown root:<ansible-runner-group> /etc/ansible/cryptohub/ssh-pin-vars.yml
sudo chmod 640 /etc/ansible/cryptohub/ssh-pin-vars.yml

Encrypt this variable with Ansible Vault or supply it from your approved controller credential store when your policy requires encrypted secrets at rest.

Create inventory.ini. Replace <target-host> and <target-user>:

[pkcs11_targets]
target ansible_host=<target-host> ansible_user=<target-user> ansible_connection=ssh ansible_ssh_pkcs11_provider=/usr/local/lib/libcryptohub-pkcs11.so ansible_ssh_common_args='-o PreferredAuthentications=publickey -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no'

Do not add IdentitiesOnly=yes. That option prevents OpenSSH from trying keys enumerated through the PKCS #11 provider.

Create ssh.yml:

---
- name: Authenticate SSH with a CryptoHub key
  hosts: pkcs11_targets
  gather_facts: false
  vars_files:
    - /etc/ansible/cryptohub/ssh-pin-vars.yml
  tasks:
    - name: Read the managed host name
      ansible.builtin.command:
        argv:
          - hostname
      register: hostname_result
      changed_when: false

    - name: Display the managed host name
      ansible.builtin.debug:
        var: hostname_result.stdout

Set CHLIBS_CONFIG in the controller shell and run the playbook:

export CHLIBS_CONFIG=/etc/ansible/cryptohub/cryptohub.json
ansible-playbook -i inventory.ini ssh.yml

Set this variable in the controller shell, not the playbook environment: block. The Ansible environment keyword applies to remote tasks, not the SSH connection plugin.A successful run prints the target hostname and reports unreachable=0 and failed=0.

Troubleshoot the validation

No configuration file found: export CHLIBS_CONFIG in the process that loads the module.
operation not supported for this keytype from openssl dgst: confirm that OPENSSL_CONF loads pkcs11-provider 1.2.0 instead of the Ubuntu 24.04 distribution’s 0.3 provider.
to use pkcs11_provider you must specify a password/pin: load the endpoint UserPass password from the protected Ansible variable source.
Permission denied (publickey) after OpenSSH enumerates the matching key: confirm that the public key is in authorized_keys and remove IdentitiesOnly=yes from the SSH arguments.

​Generate the CryptoHub key

​Sign data from a playbook

​Authenticate Ansible SSH with the CryptoHub key

​Troubleshoot the validation

Generate the CryptoHub key

Sign data from a playbook

Authenticate Ansible SSH with the CryptoHub key

Troubleshoot the validation