PUT /api/lunasa/hsms/{hsmid}

PUT /api/lunasa/hsms/{hsmid}

Initializes a specific HSM.

User Privileges

Users with the following role privileges can perform this command:

• admin

Parameters

hsmid

The serial number of the HSM of interest.

Use: Required

JSON Schema:

   Object
   type: integer
   format: int64
   minimum: 1
   maximum: 9999999999

ped

Indicator of whether HSM is local PED (0) or remote PED (> 0): not applicable for password-based HSMs. Optional in case of Password based HSM.

Use: Not Required

JSON Schema:

   Object
   type: string
   minLength: 1
   maxLength: 1
   pattern: ^(?:$|0|1)$

password

The Security Officer password if password-based HSM. Optional in case of PED based HSM.

Use: Not Required

JSON Schema:

   Object
   type: string
   format: password
   minLength: 8
   maxLength: 255
   pattern: ^([a-zA-Z0-9_!#$%'()*+,./:=? @[]^{}~-]*)$

domain

The cloning domain if password-based HSM. Optional in case of PED based HSM.

Use: Not Required

JSON Schema:

   Object
   type: string
   minLength: 1
   maxLength: 128
   pattern: ^[^ &|<>`;"\][a-zA-Z0-9_ !@#$%^*=+[]{}()/:',.~?-]+$

label

The user-friendly name to identify the HSM.

Use: Required

JSON Schema:

   Object
   type: string
   minLength: 1
   maxLength: 32
   pattern: ^[a-zA-Z0-9_]*$

defaultDomain

Optional for both of Password and PED based HSM with default value "false". Only applicable for password-based HSM.

Use: Not Required

JSON Schema:

   Object
   type: boolean

pptFile

Specifies the filename for a template file use to initialize the HSM. The filename should be either of '.txt' or '.ppt' format.

Use: Not Required

JSON Schema:

   Object
   type: string
   minLength: 1
   maxLength: 64
   pattern: ^([a-zA-Z0-9_-]|[a-zA-Z0-9_.-][a-zA-Z0-9_. -]*[a-zA-Z0-9_.-])$

Responses

204

Successful.

Location

"Location" is the URL to the HSM instance and is returned in the server response. You can use "Location" to form a GET resource to query the HSM instance.

see GET /api/lunasa/hsms/{hsmid}


For PED-based HSMs, "Location" is the URL to the task spawned to initialize the HSM.

400

FRAMEWORK_BAD_REQUEST

Returned when the input data does not conform to the required validation schema.

400

HSMPLUGIN_INVALID_FILENAME

The specified filename is invalid or contains system reserved name.

400

HSMPLUGIN_PPT_FILE_VALIDATION_FAILED

Policy template file provided is not valid.

404

HSMPLUGIN_HSM_DOES_NOT_EXIST

The hsm specified does not exist.

404

SERVERPLUGIN_FILEID_DOES_NOT_EXIST

Non-existent file name specified.

500

SERVERPLUGIN_INTERNAL_ERROR

Unexpected error.

Example Request for initializing a ped-based HSM.

   PUT
   https://1.2.3.4:8443/api/lunasa/hsms/154704
   {
      "label": "myPasswordHsm",
      "ped": "0"
   }

Example Request for initializing a ped-based HSM using template file.

   PUT
   https://1.2.3.4:8443/api/lunasa/hsms/154704
   {
   "ped": "1",
   "label": "myPEDHSM",
   "pptFile": "template.txt"
   }

Example Request for initializing a password-based HSM.

   PUT
   https://1.2.3.4:8443/api/lunasa/hsms/151256
   {
   "label": "myPasswordHSM",
   "password": "myPassword",
   "defaultDomain": false,
   "domain": "myDomain"
   }

Example Request for initializing a password-based HSM using template file.

   PUT
   https://1.2.3.4:8443/api/lunasa/hsms/151256
   {
   "label": "myPasswordHSM",
   "password": "myPassword",
   "defaultDomain": false,
   "domain": "myDomain",
   "pptFile": "template.txt"
   }

Example Result

{
password-based HSM:
{'Access-Control-Allow-Origin': '*', 'Content-Type': 'application/json', 'Location': '/api/lunasa/hsms/151256', 'Content-Length': '2', 'Access-Control-Allow-Credentials': 'true'}

PED-based HSM
{'Access-Control-Allow-Origin': '*', 'Content-Type': 'application/json', 'Location': '/tasks/2', 'Content-Length': '712', 'Access-Control-Allow-Credentials': 'true'}
}

Note:

1. If an HSM is initialized without using a template file, then it cannot be re-initialized with a template file.
2. If an HSM is initialized using a template file, then it can be re-initialized without using one.
3. If an HSM is initialized with a template file then re-initializing it again using a template file is not allowed. Conclusion: The template file can only be used during the first-time initialization of an HSM.