Authenticating to a SafeNet Network HSM Appliance

1. Sessions

REST API sessions store valuable information, they are required in order to use the service. There are two types of sessions that are available for use, user sessions and private sessions.

1.1 User Session

User sessions are the default session, when using basic authorization a user session will be used. User sessions are automatic and do not require a session header. User sessions are shared with all clients of the same user therefore they have limited access to resources.

1.2 Private Session

Private sessions need to be created using a resource (see /auth/session), this session is private and can only be used by the user that created it.

2. Authentication

In order to use the REST API service, you must authenticate to the web server on the SafeNet Network HSM appliance.

2.1 Authorization Header

The authorization header must be included in order to authenticate with the REST API. The REST API currently supports Basic Authorization and JWT access tokens.

2.1.1 Basic Authorization

In order to use basic authorization the keyword "Basic" must be included in the "Authorization" header followed by a Base64 blob that contains your colon separated username and password. Basic authorization will use user sessions. The credentials for the admin and monitor users are the same as Luna Shell.

Example:

Authorization: Basic Base64(Username:Password)

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

2.1.2 JWT Access Tokens

In order to use JWT access tokens the keyword "Bearer" must be included in the "Authorization" header followed by a JWT in its compact serialization. JWT tokens need to be created using a resource (see POST /auth/jwt). They will eventually expire, though if necessary can be explicitly revoked (see DELETE /auth/jwt). JWT access tokens will use user sessions.

Example:

Authorization: Bearer token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbmZvIjoiV2VsbCBhcmVuJ3QgeW91IGEgY2xldmVyIG9uZSBmb3IgcmVhZGluZyB0aGlzISJ9.HYMl0hEoRrwqLSeSKENIlFidvbxlUxk4T7xLScD-K2o

2.2 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.