REST API  14
REST API for Luna Network HSMs
HSM and Partition Setup

The following procedures will allow you to initialize the HSM, set policies, create an application partition, and connect the partition to a client. You must first set up and enable the webserver on the appliance (see Webserver Setup).

REST API resources are used in place of LunaSH commands. Some REST API resources combine multiple LunaSH commands for efficiency. Therefore, many are not 1:1 mappings. The tables linked below provide a cross-reference for key resources used in the following procedures:

NOTES:

  • Resources and objects are case-sensitive; use this documentation as a reference for the correct case.
  • The default session timeout is 10 minutes; upon timeout, the REST server terminates an authenticated session. To keep the REST session alive, periodically query a resource such as GET /api/lunasa/services/webserver or POST /api/lunasa/logs/lunalogs with a suitable log message (to create a record of the keep-alive action).
  • HSM and partition serial numbers are unique; HSM and partition labels can be identical. Keep this point in mind when constructing logic for REST resources.
  • if you encounter the string NO ERR WITH THIS ID EXISTS, please contact Thales Technical Support and report how you encountered this string.
  • LunaSH imposes constraints on names, labels, etc. to prevent the use of characters that could be used to exploit the shell. You should use the same character set with the REST API. Refer to the product documentation for more details.
  • All discoverable resources (resources with a GET) will be referenced by an href in its parent resource; this documentation may not reflect all resources that follow this rule.

Initializing the HSM and Creating a Partition

  1. Open a session on the Luna Network HSM appliance.
    POST
https://LUNAIPADDRESS:PORT/auth/session
Authorization: Basic YWRtaW46MXFAVzNlJFI=
{}
  2. Change any desired HSM policies.
    PUT
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/policies/{policynum}
{"value":{value}}
  3. Initialize the HSM.
    PUT
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}
{
  "ped": "",
  "label": "{HSMlabel}",
  "password": "{SO_password}",
  "defaultDomain": false,
  "domain": "{domain_string}"
}
  4. Log in as HSM SO.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmSN}/login
{
  "ped": "0",
  "password": "password",
  "role": "so"
}
  5. [Optional] Run a self-test.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/actions/selfTest
  6. Create a partition on the HSM.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions
{
  "defaultDomain": true,
  "defaultChallenge": true,
  "name": "123",
  "allStorageSpace": false,
  "label": "123",
  "domain": "",
  "hasPso": true,
  "password": "password123",
  "size": 20480
}

Next, allow a client to access the partition using an NTLS or STC connection.

Creating an NTLS Client-Partition Connection

  1. [Optional] Get a list of clients currently registered on the appliance.
    GET
https://LUNAIPADDRESS:PORT/api/lunasa/ntls/clients
  2. Register the client with the appliance by specifying the client certificate as a string. Within the string, you must replace all newline characters with "\n". 
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/ntls/clients
{
  "ip": "1.2.3.4",
  "certificate": "-----BEGIN CERTIFICATE-----\n...{certificate}...\n-----END CERTIFICATE-----",
  "clientName": "testClient3"
}
  3. Restart the NTLS service.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/services/ntls/actions/restart
  4. Assign the partition to the client. 
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/ntls/clients/{clientid}/links
{"url": "/api/lunasa/hsms/{hsmid}/partitions/{partitionid}"}
  5. [Optional] Get a list of partitions assigned to the client. 
    GET
https://LUNAIPADDRESS:PORT/api/lunasa/ntls/clients/{clientid}/links/{linkid}
{
  "url": "/api/lunasa/hsms/{hsmid}/partitions/{partitionid}",
  "type": "hsm/partition"
}

Creating an STC Client-Partition Connection

To create a Secure Trusted Channel (STC) connection, a partition identity is created directly on the partition, and the client and partition exchange identities. This allows end-to-end encryption of all communications between partition and client. This section describes how to establish an STC connection between a client and a new partition and initialize the partition over STC.
If you have the partition already initialized,you may follow the procedure mentioned in Converting an Initialized NTLS Partition-Client Connection to STC to create STC connection between partition and client.

  1. On the client workstation, import the HSM Appliance Server Certificate (server.pem) from the appliance, and register the HSM Server Certificate with the client
    scp admin<host/IP>:server.pem <target_filename>
    vtl addServer -n <Network_HSM_hostname/IP> -c <server_certificate>
  2. Launch LunaCM on the Luna HSM Client and create the STC token and client identity.
    lunacm:> stc tokeninit -label <token_label>
    lunacm:> stc identitycreate -label <ID_label>
  3. Encode the identity file using openssl so it can be registered via REST API call.
    openssl base64 -in <ID_filename> -out <encode_ID_filename>
    You must remove all newline characters within the encoded file.
  4. Log in as HSM SO.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/login
{
  "ped": "0",
  "password": "password",
  "role": "so"
}
  5. Export the partition identity.
    GET
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/stc
  6. Register the partition identity to the client using LunaCM. The fingerpint obtained is base64-encoded, so you must decode it first with openssl.
    Before decoding, create a file containing the base64-encoded fingerpint and within the file remove all the newline characters i.e, '\ n' and move the content enclosed within these to the newline, in order to maintain the required format.
    openssl base64 -d -in <encoded_parID_filename> -out <parID_filename>
    lunacm:> stc partitionregister -file <parID_filename>
  7. Enable STC using LunaCM on the client.
    lunacm:> clientconfig listservers
    lunacm:> stc enable -id <server_ID>
    LunaCM restarts. If successful, the partition appears in the list of available slots
  8. Initialize the partition.
    PUT
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}
{
  "password": "password",
  "label": "ABC123",
  "domain": "domain",
  "defaultDomain": true,
  "ped": "0"
}
  9. Log in as Partition SO.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/login
{
  "ped": "0",
  "role": "so",
  "password":"password"
}
  10. [Optional]Set partition policy 37: Enable Secure Trusted Channel to 1 (ON), for reserving the partition to be only allowed to create STC connection(not NTLS) with other clients
    PUT
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/37
{"value": 1}
  11. Register the client identity with the HSM by specifying the encoded file content.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/stc/clients
{
  "identity": "{encoded_ID_file_content}",
  "label": "{client_label}"
}

Converting an Initialized NTLS Partition-Client Connection to STC

If you have initialized partitions already assigned to a client using NTLS, you can use the following procedure to switch to a more secure STC connection. All of the client's assigned partitions on the specified Luna Network HSM must be converted.
Note: Before moving to the following procedure, please ensure that your partition is already initialized

  1. Launch LunaCM on the Luna HSM Client and create the STC token and client identity.
    lunacm:> stc tokeninit -label <token_label>
    lunacm:> stc identitycreate -label <ID_label>
    The STC client identity public key is automatically exported to:
    <client_install_directory>/data/client_identities/>
    Note: This step is not required if you have already created a client token and identity. Verify using stc identityshow. If you recreate the client identity, you will have to re-register any existing STC partitions.
  2. Encode the identity file using openssl so it can be registered via REST API call.
    openssl base64 -in <ID_filename> -out <encode_ID_filename>
    You must remove all newline characters within the encoded file.
  3. Log in as Partition SO.
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/login
{
  "ped": "0",
  "role": "so",
  "password":"password"
}
  4. [Optional]Set partition policy 37: Enable Secure Trusted Channel to 1 (ON), for reserving the partition to be only allowed to create STC connection(not NTLS) with other clients. 
    PUT
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/37
{"value": 1}
  5. Export the partition identity. 
    GET
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/stc
  6. Register the partition identity to the client using LunaCM. The fingerpint obtained is base64-encoded, so you must decode it first with openssl.
    Before decoding, create a file containing the base64-encoded fingerpint and within the file remove all the newline characters i.e, '\ n' and move the content enclosed within these to the newline, in order to maintain the required format.
    openssl base64 -d -in <encoded_parID_filename> -out <parID_filename>
    lunacm:> stc partitionregister -file <parID_filename>
  7. Register the client identity with the HSM by specifying the encoded file content. 
    POST
https://LUNAIPADDRESS:PORT/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/stc/clients
{
  "identity": "{encoded_ID_file_content}",
  "label": "{client_label}"
}
  8. Enable STC using LunaCM on the client.
    lunacm:> clientconfig listservers
    lunacm:> stc enable -id <server_ID>

REST API for Luna Network HSMs VERSION" Reference Guide
007-013322-007 Rev. A Copyright 2023  Thales. All rights reserved.