Commands
The Commands tab contains most of the operations you will be performing with the REST API. The Defaults section running along the top contains the HSM and partition serial numbers you entered on the Login tab (seeCommands Tab showing an error on Raw IO). If you wish to use a different HSM or partition, change these values.
Figure 1: Commands Tab showing an error on Raw IO
To perform a command:
1.Specify the HSM or partition you want to operate on by entering its serial number under Defaults.
2.Select the element you want to communicate with (HSM, Partition, or PED).
3.Click any command button to initiate its corresponding resource.
If the query is successful, the Raw IO tab at the bottom will turn green and show you a record of your request and its response. If you are using the Formatted IO tab to track your outputs, you only see the response values.
If you are unsuccessful, the Raw IO tab will turn red and return an error. The Formatted IO tab will fail to populate with defined values, returning an error.
Example
For example, to initialize your HSM:
1.Type the HSM serial number under Defaults.
2.Select the HSM tab.
3.Click Initialize.
The tables below list each command button on the Commands tab. Each command has a short description of what it does as well as its corresponding resource. The resources can be input manually in the Custom IO tab if you become very familiar with them.
NOTE There are some calls that are not included as buttons in the client. They must be input manually in the Custom IO tab. A complete list of resources you can query with the REST API can be found in the REST API Command Reference documentation.
Commands are grouped below by applicable element. Calls to time-consuming resources are listed under Tasks.
>HSM
>PED
HSM
The table below defines commands you can send to your HSM and references their corresponding resources.
| Command | Function | Resource |
|---|---|---|
| List | Lists all HSMs associated with appliance. | GET /api/lunasa/hsms |
| Info | Gets information associated with a specific HSM. | GET /api/lunasa/hsms/{hsmid} |
| Upgrade Firmware | Updates HSM firmware to the most recent version. | POST /api/lunasa/hsms/{hsmid}/firmware/actions/upgrade |
| Rollback Firmware | Downgrades HSM firmware to a previously installed version. | POST /api/lunasa/hsms/{hsmid}/firmware/actions/rollback |
| Set Policy | Sets a specific HSM policy. | PUT /api/lunasa/hsms/{hsmid}/policies/{policyid} |
| Apply Update | Applies a specific HSM update. | POST /api/lunasa/hsms/{hsmid}/updates/{updateid} |
| Initialize | Initializes the HSM. | PUT /api/lunasa/hsms/{hsmid}/ |
| Zeroize |
Removes all partitions and keys from the HSM. Does not reset HSM policies, erase RPV, or delete Auditor role. |
POST /api/lunasa/hsms/{hsmid}/actions/zeroize |
| List Roles | Lists all roles associated with the HSM. | GET /api/lunasa/hsms/{hsmid}/roles |
| Get Role | Gets information associated with a specific HSM role. | GET /api/lunasa/hsms/{hsmid}/roles/{roleid} |
| Set Password |
Opens a dialog box in which you can set a new HSM role password by following these steps: 1.Complete the form with your new password and old password. 2.Optionally change secret and/or challenge secret associated with a particular HSM or role by changing false to true and specifying HSM serial number and role. |
PATCH /api/lunasa/hsms/{hsmid}/roles/{roleid} |
| Factory Reset |
Sets the HSM back to its factory default settings. CAUTION! Deletes the HSM SO, all users, and all objects. |
POST /api/lunasa/hsms/{hsmid}/actions/factoryReset |
Partition
The table below defines commands you can send to your partition and references their corresponding resources.
| Command | Function | Resource |
|---|---|---|
| List | Lists all partitions associated with the HSM. | GET /api/lunasa/hsms/{hsmid}/partitions |
| Info | Gets information associated with a specific partition. | GET /api/lunasa/hsms/{hsmid}/partitions/{partitionid} |
| Create | Creates a partition. | POST /api/lunasa/hsms/{hsmid}/partitions |
| Delete | Removes a specific partition from the HSM. | DELETE /api/lunasa/hsms/{hsmid}/partitions/{partitionid} |
| Set Policy | Sets a specific partition policy. | PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid} |
| Delete All | Removes all partitions from the HSM. | DELETE /api/lunasa/hsms/{hsmid}/partitions |
| Initialize |
Initializes the partition. (Applicable only to PPSO partitions.) |
PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid} |
| Initialize Role | Initializes a specified partition role. | PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid} |
| List Roles | Lists all roles associated with the partition. | GET /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles |
| Get Role | Gets information associated with a specific partition role. | GET /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid} |
| Set Password |
Opens a dialog box in which you can set a new partition role password by following these steps: 1.Complete the form with your new password and old password. 2.Optionally change secret and/or challenge secret associated with a particular HSM, partition, and/or role by changing false to true and specifying HSM serial number, partition serial number, and role. |
PATCH /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid} |
| Create Challenge |
Opens a dialog box in which you can create a new challenge for the partition by following these steps: 1.Complete the form with your HSM serial number, partition serial number, and role. 2.Optionally change the default value from true to false to randomize the challenge value. NOTE Applies to PED-based partitions |
POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}/actions/createChallenge |
PED
The table below defines commands you can use with your PED and references their corresponding resources.
| Command | Function | Resource |
|---|---|---|
| Connect | Connects to a Remote PED. | POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/connect |
| Disconnect | Disconnects the currently active Remote PED. | POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/disconnect |
| Vector Init |
1.Initializes a Remote PED Vector (RPV). 2.Creates a new Remote PED Key (RPK). 3.Imprints the RPV onto the HSM and the RPK. |
POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/vectorInitialize |
| Vector Erase | Erases the Remote PED vector (RPV) from the current HSM. | POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/vectorErase |
Tasks
Tasks enable monitoring and administration of REST API resources that may require significant time to complete, such as updating HSM firmware. Rather than block and wait for these actions to complete, the REST API creates tasks to run the resource automatically in the background. Tasked resources return a response immediately and notify you of the status of the action: waiting, running, failed, etc. Because of their time-consuming nature, tasks are grouped separately. The table below defines each command and references its corresponding resource.
| Command | Function | Resource |
|---|---|---|
| List | Lists all available tasked resources. | GET /tasks |
| Kickstart | Starts a waiting task. | POST /tasks/{taskid}/actions/start |
| Result | Gets the result and deletes the task. | GET /tasks/{taskid}/response |
| Delete All | Deletes all tasks. | DELETE /tasks |
