Please Note:

CSM Integration with Luna Network HSM

CSM integration with the Luna Network 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. You can also provide password policy (optional) in the payload as shown below.
```
{
    "username": "ssh_username",
    "password": "password_of_user",
    "hsm_hostname": "HSM_server_hostname",
    "item_name": "/location_of_the_secret/name_of_the_secret",
    "password_policy":{
      "length":<length-of-password>,
      "min_upper_case":<min-uppercase-characters-in-password>,
      "min_digits":<min-digits-in-password>,
      "min_lower_case":<min-lowercase-characters-in-password>,
      "min_special":<min-special-characters-in-password>
    }
}
```
Example
If you create a custom rotated secret named "ssh-admin" in folder "hsm" and define the password policy, the payload will be:
```
{
    "username": "admin",
    "password": "password",
    "hsm_hostname": "local_host",
    "item_name": "/hsm/ssh-admin",
    "password_policy":{
      "length":8,
      "min_upper_case":1,
      "min_digits":2,
      "min_lower_case":1,
      "min_special":1
    }
}
```
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.
Password policy rules
For SSH users, the password policy has the following set of rules:
- The length of the password must be 8 - 255 characters.
- In a password policy, the password length is a mandatory field.
- The password policy should contain at least three (3) fields out of four (4) mentioned below:
  - min_upper_case
  - min_digits
  - min_lower_case
  - min_special
Caution
- The value of length, min_upper_case, min_digits, min_lower_case, and min_special fields cannot be negative.
- The summation of the values of the min_upper_case, min_digits, min_lower_case, and min_special fields cannot exceed the value of length.
  min_upper_case + min_digits + min_lower_case + min_special =< length
Default policy
If the user does not define a password policy, the default policy is applied as described below.
```
"password_policy":
{
  "length":11,
  "min_upper_case":2,
  "min_digits":1,
  "min_lower_case":2
}
```
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
```

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. You can also provide password policy (optional) in the payload as shown below. 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
        },
    ],
    "password_policy":{
      "length":<length-of-password>,
      "min_upper_case":<min-upper-case-characters-in-password>,
      "min_digits":<min-digits-in-password>,
      "min_lower_case":<min-lower-case-characters-in-password>,
      "min_special":<min-special-characters-in-password>
    }
}
```
Example
If you create a custom rotated secret for the role "co" where partitions are in HA group and define the password policy, 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
        }
    ]
    "password_policy":
        {
          "length":8,
          "min_upper_case":3,
          "min_digits":1,
          "min_lower_case":1,
          "min_special":1
        }
}
```
Password policy rules
For Partition users, the password policy is optional and has the following set of rules:
- The length of the password must be 8 - 255 characters.
- In a password policy, the password length is a mandatory field.
- The password policy can contain any of the below fields:
  - min_upper_case
  - min_digits
  - min_lower_case
  - min_special
Caution
- The value of length, min_upper_case, min_digits, min_lower_case, and min_special fields cannot be negative.
- The summation of the values of the min_upper_case, min_digits, min_lower_case, and min_special fields cannot exceed the value of length.
  min_upper_case + min_digits + min_lower_case + min_special =< length
Default policy
If the user does not define a password policy, the default policy is applied as described below.
```
"password_policy":
{
  "length":11,
  "min_upper_case":2,
  "min_digits":1,
  "min_lower_case":2
}
```
- 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.
- Considering HSM serves the password rotate request sequentially, it is recommended to only configure rotating three partition passwords belonging to a single HSM in a single custom rotated secret. In addition, we can rotate passwords of 8 partitions in a single custom rotated secret provided there are a maximum of three partitions from one HSM.
  Note
  - Akeyless Gateway 4.15 onward, you can update the timeout duration in "Webhook Wait Timeout" to avoid timeout issues. When creating a custom rotated secret for partitions with more than one partition, set the Webhook Wait Timeout to 300 seconds. Make sure that Webhook Wait Timeout should not be less than the default value that is 40 seconds.
  - If the Webhook Wait Timeout is set to 300 seconds, you can add a maximum 5 partitions from a single HSM in a single payload. To add more partitions, use additional 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.
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 the connection_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 a bool 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.

CSM Integration with Luna Network HSM

Support for SSH user password rotation

Prerequisites for rotating SSH user password

Steps for generating CSR on Luna HSM and signing the certificate

Steps for rotating SSH user password

Support for partition role password rotation

Prerequisites for rotating partition role password

Steps for generating CSR on Luna HSM and signing the certificate

Steps for rotating partition role password with multiple HSM

On this page

Suggest A Change