Authentication

This section contains the following information about authenticating to the webserver on the Luna Network HSM appliance using REST API:

• Sessions
• Basic Authorization
• Certificate-Based Authorization

Sessions

REST API sessions store valuable information required to use the service. Two types of sessions are available:

• User Sessions: This is the default session type, used for basic authorization. User sessions do not require a session header. They are shared with all clients of the same user, and are therefore granted limited access to resources.
• Private Sessions: These are created using a resource (see POST /auth/session). Private sessions can only be used by the user who created them.

Basic Authorization

To use basic authorization, you must include the following in the "Authorization" header:

• keyword "Basic"
• base64-encoded blob containing your colon-separated appliance username and password

Example: base64(admin:password123)

Authorization: Basic YWRtaW46cGFzc3dvcmQxMjM=

Certificate-Based Authorization

Certificate-based authorization requires you to upload a user certificate and perform a login handshake.

1. Log in to the appliance with your username and password.
2. Upload the certificate for the specified user. Replace newline characters with
   in the certificate string.
   

   POST
   https://LUNAIPADDRESS:PORT/users/{userid}/certificates
   {"certificate": "-----BEGIN CERTIFICATE-----\n...{certificate}...\n-----END CERTIFICATE-----\n"}
   

3. Generate a challenge for the user by specifying the username and client public certificate.
   

   POST
   https://LUNAIPADDRESS:PORT/auth/login/challenge
   {
     "username": "{username}",
     "certificate": "-----BEGIN CERTIFICATE-----\n...{certificate}...\n-----END CERTIFICATE-----\n"
   }
   

   The webserver responds with base64-encoded cryptographic challenge and nonce parameters.
4. Decode the challenge and nonce from base64.
5. Decrypt the decoded challenge using the client private key.
6. XOR the decoded and decrypted challenge with the decoded nonce. The result is the plaintext challenge answer.
7. Encrypt the answer with the webserver's public key. The result is the challenge response expected by the server.
8. Encode the challenge response to base64 so that it can be transmitted via REST API.
9. Answer the challenge with the encrypted base64 response.
   

   POST
   https://LUNAIPADDRESS:PORT/auth/login/basic
   {"challengeResponse": "{challenge_response}"}
   

   The server responds with return code 204 if successful, and 401 in case of authentication failure.