Authenticating to a SafeNet Network HSM Appliance

Introduction

To obtain the services of the REST API, you must authenticate to the web server on the SafeNet Network HSM appliance. SafeNet Network HSM supports password- and certificate-based authentication.

Password Authentication

Password-based authentication is the only method supported for version 1 of the REST API. Other versions also allow PED-based authentication. The client supplies the required credentials (username and password) via POST to /auth/login/basic. The server responds with 204 return code if successful and 401 in case of authentication failure.

Certificate-Based Authentication

The certificate-based authentication uses the following steps:

• Uploading the user certificate

Step 1: Login to server using username and password

Step 2: Upload public key by posting to '/users/{user you wish to use}/certificates' with the certificate.

Replace everything within {} with the username to use in the login process

• Performing the login handshake

Step 1: Create a challenge by invoking POST to '/auth/login/challenge' with your username and the client public key. The server responds with a cryptographic challenge and nonce parameters.

Step 2: Decode the obtained challenge and nonce using base64.

Step 3: Decrypt the decoded challenge using the client private key in order to continue with the login process.

Step 4: To get the answer of the challenge, XOR the decoded and decrypted challenge with the decoded nonce. The result is the un-encrypted challenge answer.

Step 5: Encrypt the answer with the server public key to obtain the final challenge response as expected by the server.

Step 6: In order to transmit it over REST, encode the encrypted answer using base64.

Step 7: Answer the challenge by invoking POST to '/auth/login/basic' with your encrypted challenge response.

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