CSM Integration with LunaSA HSM
CSM integration with the LunaSA HSM provides support for rotating the Luna HSM SSH user passwords and partition role passwords (for example, the partition security officer, crypto officer, and crypto user) with multiple HSMs’.
Support for SSH user password rotation
Prerequisites for rotating SSH user password
Must have at least the Luna HSM appliance version 7.8.1 for rotating the SSH user password.
SSH user must be created. SSH user password rotation is only supported for the user having admin, monitor, or operator roles.
Luna HSM Server certificate should be signed by CA. Click here for detailed steps.
CA certificate (used to sign the server certificate) must be added to the CipherTrust Manager CA list and trusted CA list of the hsm-secrets service.
ksctl trusted-ca-cert add --trusted-ca-id <id> --trusted-ca-type local --service hsm-secrets
Add DNS host entry for the HSM server IP address and restart the service. Click here for details.
Note
CSM should be configured on the CipherTrust Manager. Don't use the same gateway admin credentials on multiple instances of the CipherTrust Manager unless the instances are connected in a cluster.
If the same gateway admin credentials are used on different CipherTrust Manager instances that are not in the cluster, Akeyless will send a request randomly to any of the instances irrespective of the instance on which the clusterURL
for Akeyless is configured.
Steps for generating CSR on Luna HSM and signing the certificate
Provide HSM IP, admin username, and password in the curl command for authentication. Define hostname in
subjectAltNames
as shown below.curl -k -X POST https://1.2.3.4:8443/api/lunasa/webServer/csr -H "Content-Type: application/vnd.safenetinc.lunasa+json;version=" -d '{"keyType" : "rsa", "keySize" : 2048,"cn" : "local_host","subjectAltNames": ["hsm_hostname"],"days" : 365,"organization": "Gemalto","locality": "Ottawa","state": "ontario","country": "CA"}' -u username:password
Click here for details.
Sign the CSR from an external CA or the CipherTrust Manager local CA. Use the below command to sign the CSR from the CipherTrust Manager local CA.
ksctl ca locals certs issue --ca-id <local-ca-id> --csr-infile csrfile --cert-outfile <signed_cert> -x 700 -o server
Update the server certificate of HSM with the signed certificate. Convert the signed certificate in the
\n
format and replace the current certificate with a given file. Upload the certificate using the Python code.Create a session ID using the below command and pass the session ID in the code.
curl -k -X POST https://1.2.3.4:8443/auth/session/ -H "Content-Type: application/vnd.safenetinc.lunasa+json;version=" -u username:Password -c cookies.txt | cat cookies.txt
Python code example
import requests import urllib3 urllib3.disable_warnings() f = open("certificate.pem", "w") f.write("-----BEGIN CERTIFICATE-----\nMIIFBTC…\n-----END CERTIFICATE-----") f.close() headers = {'Content-Type': "application/vnd.safenetinc.lunasa+octet-stream;version=","Access-Control-Allow-Origin":"*"} cookies = {'SESSION_ID':"eddbb1a2-45e7-45de-9f2b-fc1546477d47"} with open("certificate.pem", 'rb') as payload: r = requests.put(url="https://1.2.3.4:8443/api/lunasa/webServer/certificate", stream=True, data=payload, cookies=cookies, headers=headers, verify=False, allow_redirects=False,) print(r)
After updating the certificate, restart the web server service using the LunaSH command.
service restart webserver
Click here for details.
Steps for rotating SSH user password
Log on to the Akeyless Console and navigate to Targets > New > Web. Create a web target for the custom rotated secret. Below is the URL for the web target:
http://hsm-secrets/akeyless/hsm/ssh/rotate
The target will be the same for all SSH users of any HSM server.
In the Akeyless console, navigate to Secrets & Keys > New > Rotated Secret > Web. Create a rotated secret of type "web". Select the web target created in the previous step for SSH and add the payload in the given format.
{ "username": "ssh_username", "password": "password_of_user", "hsm_hostname": "HSM_server_hostname", "item_name": "/location_of_the_secret/name_of_the_secret" }
Example - If you create a custom rotated secret named "ssh-admin" in folder "hsm", the payload will be:
{ "username": "admin", "password": "password", "hsm_hostname": "local_host", "item_name": "/hsm/ssh-admin" }
Caution
Akeyless gateway 4.15 onward, do not reduce the "Webhook Wait Timeout" time for HSM SSH user secret. The timeout must be set either to the default value (40 seconds) or higher.
Note
For rotating a SSH user password, the username or password should not contain & _ - | \ ? ; : ' " < > ` characters and spaces.
You can schedule the rotation of password or rotate the secret manually.
Support for partition role password rotation
Prerequisites for rotating partition role password
Must have at least the Luna HSM appliance version 7.1.0 for rotating the partition role password.
Must have the SSH admin username and password for rotating the partition role password. Create one static secret or rotated secret to store the admin credentials of HSM server. The payload format is:
{ "username":"admin_username", "password":"admin_password" }
Note
When the Luna HSM server version is lower than 7.8 and a new "admin" user is created using
LunaSH
. Make sure to create the user on the Rest API, else, it will fail to authenticate.Partition and partition roles must be already initialized. In case of multiple partition password rotation where partitions are in an HA group, the "co" and "cu" passwords for all partitions must be the same.
CSM should be configured on the CipherTrust Manager.
Luna HSM Server certificate should be signed by CA. Click here for detailed steps.
CA certificate (used to sign the server certificate) must be added to the CipherTrust Manager CA list and trusted CA list of the hsm-secrets service.
ksctl trusted-ca-cert add --trusted-ca-id <id> --trusted-ca-type local --service hsm-secrets
Add DNS host entry for the HSM server IP address and restart the service. Click here for details.
Steps for generating CSR on Luna HSM and signing the certificate
Provide HSM IP, admin username, and password in the curl command for authentication. Define hostname in
subjectAltNames
as shown below.curl -k -X POST https://1.2.3.4:8443/api/lunasa/webServer/csr -H "Content-Type: application/vnd.safenetinc.lunasa+json;version=" -d '{"keyType" : "rsa", "keySize" : 2048,"cn" : "local_host","subjectAltNames": ["hsm_hostname"],"days" : 365,"organization": "Gemalto","locality": "Ottawa","state": "ontario","country": "CA"}' -u username:password
Click here for details.
If the Luna HSM server version is older than 7.7.1, use the following curl command to get the default CSR for the HSM web server.
curl -k -X GET https://1.2.3.4:8443/api/lunasa/webServer/csr -H "Content-Type: application/vnd.safenetinc.lunasa+json;version=" -u username:password
Click here for details.
Sign the CSR from an external CA or the CipherTrust Manager local CA. Use the below command to sign the CSR from the CipherTrust Manager local CA.
ksctl ca locals certs issue --ca-id <local-ca-id> --csr-infile csrfile --cert-outfile <signed_cert> -x 700 -o server
Update the server certificate of HSM with the signed certificate. Convert the signed certificate in the
\n
format and replace the current certificate with a given file. Upload the certificate using the Python code.Create a session ID using the below command and pass the session ID in the code.
curl -k -X POST https://1.2.3.4:8443/auth/session/ -H "Content-Type: application/vnd.safenetinc.lunasa+json;version=" -u username:password -c cookies.txt | cat cookies.txt
Phython code example
f = open("certificate.pem", "w") f.write("-----BEGIN CERTIFICATE-----\nMIIFBTC…\n-----END CERTIFICATE-----") f.close() headers = {'Content-Type': "application/vnd.safenetinc.lunasa+octet-stream;version=","Access-Control-Allow-Origin":"*"} cookies = {'SESSION_ID':"eddbb1a2-45e7-45de-9f2b-fc1546477d47"} with open("certificate.pem", 'rb') as payload: r = requests.put(url="https://1.2.3.4:8443/api/lunasa/webServer/certificate", stream=True, data=payload, cookies=cookies, headers=headers, verify=False, allow_redirects=False,) print(r)
After updating the certificate, restart the web server service using the LunaSH command.
service restart webserver
Click here for details.
Steps for rotating partition role password with multiple HSM
Log on to the Akeyless Console and navigate to Targets > New > Web. Create a web target for rotating the partition role password. Below is the URL for the web target:
http://hsm-secrets/akeyless/hsm/partition/rotate
The target will be the same for all partition roles of any HSM.
In the Akeyless console, navigate to Secrets & Keys > New > Rotated Secret > Web. Create a rotated secret of type "web". Select the web target created in the previous step for the partition role and add the payload in the below format. To enable rotation of the multiple "co role" passwords or "cu role" passwords, the user needs to provide details of all the partitions available in the HA group in the array format.
{ "user_role":"so/co/cu", "password":"password of the user", "connection_id":"akeyless connection id which holds the credentials of HSM admin details", "item_name":"/location_of_the_secret/name_of_the_secret", "partitions": [ { "admin_secret_name":"admin_secret_name", "admin_secret_type":"rotated secret/static secret", "hsm_hostname":"host_name_of_HSM_in_which_partition_present", "hsm_serial_number":"HSM_Serial_number", "partition_serial_number":"serial_number_of_the_partition", "allow_cn_verification":true/false }, ... ] }
Example - To create a custom rotated secret for the role "co" where partitions are in HA group, the payload will be:
{ "user_role":"co", "password": "password", "connection_id":"akeyless-connection", "item_name": "/hsm-secret/hsm-partition-co" "partitions":[ { "admin_secret_name":"admin-hsm1", "admin_secret_type":"static secret", "hsm_hostname":"sjtp16ivvq.sjinternal.com", "hsm_serial_number":"123456", "partition_serial_number":"1152352121624", "allow_cn_verification":true }, { "admin_secret_name":"admin-hsm2", "admin_secret_type":"rotated secret", "hsm_hostname":"sjtp16ivvq.sjinternal.com", "hsm_serial_number":"222222", "partition_serial_number":"1123456120625", "allow_cn_verification":false } ] }
The time required for the rotation of multiple partition passwords depends on the response time from HSM which varies due to various factors such as HSM configuration, network response time, and so on.
During testing, it has been observed that HSM serves the rotate request sequentially. We were capable of rotating three partition passwords belonging to a single HSM. In addition, we could rotate passwords of 8 partitions in a single custom rotated secret provided there are a maximum of three partitions from one HSM. This number may vary from different HSMs.
When using multiple partitions in one custom rotated secret payload and facing issues related to password rotation failure due to timeout, try to improve the network configuration, upgrade the HSM configuration, or lower the number of partitions in secret.
If password rotation fails due to timeout, then all the successful partition password rotations will be rolled back to the initial state with appropriate error message.
Caution
Akeyless Gateway 4.15 onward, do not reduce the "Webhook Wait Timeout" time for HSM Partition secret. The timeout must be set either to the default value (40 seconds) or higher.
Note
You can also provide single partition details in a payload.
If a role is "so", then multiple partitions are not supported in a payload.
connection_id
holds the "name" or "id" of the Akeyless connection where the admin secret is stored. If admin secret is stored in a different auth method, then create a connection on the CipherTrust Manager using auth method credentials and provide "name" or "id" of that connection in theconnection_id
field. Make sure the auth method has access to read the secret.If
admin_secret_type
is not defined, it is considered as a rotated secret.item_name
is optional for adding an extra level of security in the Akeyless authentication. In the item name, provide the name of the secret with the location preceded by "/".For HSM version lower than 7.7.1,
allow_cn_verification
must be true. The Common name present in the server certificate will be used as a hostname. It is abool
value, so do not add "true" or "false" values in quotes.During the multi-partition password rotation process, if any discrepancy arises in the details of a single partition or an error occurs within one of the partitions, the system promptly initiates a rollback procedure for other partitions. This ensures that all other partitions return to their previous state. Subsequently, an audit record is also added. In such a case, the user has to rectify the partition details or remove that partition from the payload to keep the integrity across all partitions.
If the system encounters difficulties during the rollback process, there's a possibility that the affected partition may not revert to its previous state as intended. Consequently, the password associated with that partition can be lost. In such rare case, the user should reset the password manually. An audit record will be added for the failed rollback operation with partition details.
You can rotate the secret manually or schedule the password rotation. The rotation interval should be a minimum of 5 minutes for multi-partition password rotation.