Validate and test

this section demonstrates how to test the integration of ansible with the futurex pkcs#11 library and {{ch}} this is done thorugh 2 ssh example and signing and verifying a sample txt file the example highlights the flexibility and increased security of keys stored on the {{ch}} , allowing ansible to perform signing and verification operations instead of relying on password based authentication ansible playbooks ansible uses playbooks , which are yaml formatted files, to carry out automated tasks on a set of managed hosts within the playbook file, you can use the {{futurex}} pkcs #11 library to execute various functions by using the {{ch}} , including safeguarding, using ssh private keys, and signing data for more information on ansible playbooks, see the ansible https //docs ansible com/ansible/latest/playbook guide/playbooks intro html inventory file an inventory file in ansible defines the hosts that ansible will manage it can list ip addresses, hostnames, and groupings of machines, allowing you to organize and target them in playbooks the file can be written in ini or yaml format example (ini format) \[local] localhost ansible connection=local in the example above, local , is targeted for local execution, common in test setups the following examples demonstrate using playbook testing ansible integration with cryptohub prerequisites perform the following two tasks to create a key pair set {{futurex}} environment variables perform the following steps to set {{futurex}} pkcs #11 environment variables in a terminal, run the following commands to set the required fxpkcs11 environment variables export fxpkcs11 module=/path/to/libfxpkcs11 so; be sure to modify the file path to match the location where the libfxpkcs11 so is on your system generate a key pair perform the following steps by using the pkcs11 tool available from the opensc suite ( https //github com/opensc/opensc ) to generate keys on both deb based and rpm based distributions, the package is called opensc in a terminal, run the following command to create a new rsa key pair on the {{ch}} by using pkcs11 tool pkcs11 tool module $fxpkcs11 module login keypairgen key type rsa 2048 label "ansible rsa" id "123456" usage sign the preceding pkcs11 tool command prompts for the user pin enter the identity password configured inside the \<crypto opr pass> tag in the fxpkcs11 cfg file if successful, the command output lists the keys that pkcs11 tool created on the cryptohub for both ssh examples adding public key to ssh authorized keys before proceeding with the ssh example, the public key for ansible rsa must be added to /home/\<target user>/ ssh/authorized keys on the target host when the client initiates a connection, it queries the {{ch}} for its public keys, which are then sent to the server the server checks its authorized keys file to see if any of the public keys match if a match is found, the server issues a challenge that the client must sign the client passes this challenge to {{ch}} , which signs it using the corresponding private key once the server verifies the signature, the client is allowed to connect, eliminating the need for passwords entirely perform the following steps to get the public key from {{ch}} , put it in a format that openssh understands, and add it to the authorized keys file get the pulic key from the ansible rsa key pair and output the information to a der file pkcs11 tool module $fxpkcs11 module r label ansible rsa y pubkey o hsm pubkey der convert the public key file from der to pem openssl rsa pubin inform der in hsm pubkey der outform pem out hsm pubkey pem re encode the pem file into pkcs#8 so that openssh can read the file ssh keygen i m pkcs8 f hsm pubkey pem > hsm pubkey ssh pub put the information in the pub file in authorized keys if the ssh server is remote, first move the pub file to the target destination before running this command cat hsm pubkey ssh pub >> / ssh/authorized keys use {{futurex}} pkcs #11 with ansible local ssh example perform the following steps to use {{futurex}} pkcs #11 with ansible for testing ansible ssh on a local machine create a working directory for a new ansible project and change into it mkdir /ansible test ssh && cd /ansible test ssh create an inventory file nano inventory ini enter the following information for local ssh testing \[local] localhost ansible user=\<name of user of local machine> ansible host=localhost ansible ssh common args=' i /path/to/libfxpkcs11 so' create a playbook file local ssh playbook yml nano local ssh playbook yml the playbook file will test ansible's ssh connection using the private key created on the {{ch}} in the previous section ( ansible rsa ) enter the following information for local ssh testing with the playbook \ name test futurex hsm pkcs11 integration local ssh example hosts local gather facts false tasks \ name run a remote command ansible builtin command hostname register hostname result \ name show command output ansible builtin debug msg "remote command output {{ hostname result stdout }}" run the following command to execute the playbook while referencing the private key stored on the hsm during the ssh connection step ansible playbook i inventory ini local ssh playbool yml 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 see a response similar to the following play \[test futurex hsm pkcs11 integration local ssh example] task \[run a remote command] enter pin for 'futurex' \[warning] sftp transfer mechanism failed on \[localhost] use ansible debug=1 to see detailed information \[warning] scp transfer mechanism failed on \[localhost] use ansible debug=1 to see detailed information changed \[localhost] task \[show command output] ok \[localhost] => { "msg" "remote command output general integration" } play recap localhost ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 the remote command output should match the hostname of your local machine you can verify the successful pulling of the private key within the fxpkcs11 log file use futurex pkcs #11 with ansible remote ssh example in the same directory as the example before, create a new inventory file nano remote inventory ini enter the following information for remote ssh testing \[remote target] target ansible user=\<user of target server machine> ansible host=\<server ip> ansible ssh common args=' i /path/to/libfxpkcs11 so' create a playbook file remote ssh playbook yml nano local ssh playbook yml the playbook file will test ansible's ssh connection using the private key created on the {{ch}} in the previous section ( ansible rsa ) enter the following information for local ssh testing with the playbook \ name test futurex hsm pkcs11 integration remote ssh example hosts remote target gather facts false tasks \ name ensure connectivity to target host ansible builtin ping register ping result \ name show ping result ansible builtin debug msg "ssh connection successful via pkcs#11! result {{ ping result ping }}" \ name run a remote command ansible builtin command hostname register hostname result \ name show command output ansible builtin debug msg "remote command output {{ hostname result stdout }}" run the following command to execute the playbook while referencing the private key stored on the hsm during the ssh connection step ansible playbook i remote inventory ini remote ssh playbool yml if successful, you see a response similar to the following play \[test futurex hsm pkcs#11 integration] task \[ensure connectivity to target host] enter pin for 'futurex' \[warning] sftp transfer mechanism failed on \[10 40 20 10] use ansible debug=1 to see detailed information \[warning] scp transfer mechanism failed on \[10 40 20 10] use ansible debug=1 to see detailed information \[warning] platform linux on host target is using the discovered python interpreter at /usr/bin/python3 12, but future installation of another python interpreter could change the meaning of that path see https //docs ansible com/ansible core/2 16/reference appendices/interpreter discovery html for more information ok \[target] task \[show ping result] ok \[target] => { "msg" "ssh connection successful via pkcs#11! result pong" } task \[run a remote command] changed \[target] task \[show command output] ok \[target] => { "msg" "remote command output remote desktop" } play recap target ok=4 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 the remote command output should match the hostname of your target machine you can verify the successful pulling of the private key within the fxpkcs11 log file use {{futurex}} pkcs #11 with ansible signing data example perform the following steps to use {{futurex}} pkcs #11 with ansible signing data example create a working directory for a new ansible project mkdir /ansible test sign && cd /ansible test sign create an inventory file nano sign inventory ini the following example inventory file uses localhost \[local] localhost ansible user=\<name of user of local machine> ansible host=localhost create a sign playbook yml file nano sign verify playbook yml the following is an example ansible playbook file for signing data by using the private key created on the {{ch}} ( ansible rsa ) \ name test futurex hsm pkcs11 integration local sign and verify example hosts localhost connection local vars module path /path/to/libfxpkcs11 so key label "ansible rsa" vars prompt \ name hsm pin prompt "enter hsm pin" private yes tasks \ name create sample data copy dest /tmp/data txt content "this is the message to be signed " \ name sign data with cryptohub (using pkcs11 tool) command > pkcs11 tool module "{{ module path }}" \ sign label "{{key label}}" \ pin "{{ hsm pin }}" v \ mechanism sha256 rsa pkcs \ input file /tmp/data txt \ output file /tmp/data sig register sign result \ name verify signature with public key (using openssl) command > pkcs11 tool module "{{ module path }}" \ login pin "{{ hsm pin }}" \ label "{{ key label }}" \ verify \ mechanism sha256 rsa pkcs \ input file /tmp/data txt \ signature file /tmp/data sig register verify result ignore errors true \ debug msg \ "verify result {{ verify result stdout }}" replace pkcs11 module with the location of the {{futurex}} pkcs #11 library on your system run the following command to execute the playbook, while referencing the private key stored on the {{ch}} to perform the signing operation ansible playbook i sign inventory ini sign verify playbook yml when prompted, enter the identity password configured inside the \<crypto opr pass> tag in the fxpkcs11 cfg file if successful, you see a response similar to the following enter hsm pin play \[test futurex hsm pkcs11 integration local sign and verify example] task \[gathering facts] ok \[localhost] task \[create sample data] ok \[localhost] task \[sign data with cryptohub (using pkcs11 tool)] changed \[localhost] task \[verify signature with public key (using openssl)] changed \[localhost] task \[debug] ok \[localhost] => { "msg" \[ "verify result signature is valid" ] } play recap localhost ok=5 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 you can verify the signing operations within the fxpkcs11 log file