Login
To begin using the REST API, you must first login.
The client provides several different login options under the Login tab. The top two options, API Password Login and API Cert Login, login to the API on the appliance you are using. API Password Login uses password-based authentication, while API Cert Login uses a certificate.
To login:
1.Fill in the Server URL box with your IP address.
2.Type your user name into the User Name box. The default user is admin (Administrator).
3.Type your password or load your certificate, depending on which option you are using.
4.Click Login.
If you are successful, the Raw IO tab at the bottom will turn green. If you are using the Formatted IO tab to track your outputs, you receive a success response. See Login Tab showing successful login on Raw IO
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.
Figure 1: Login Tab showing successful login on Raw IO
To perform any commands with the REST API, you must first login to the appliance.
The tabs underneath API Password Login and API Cert Login are for logging in to your HSM or partition. Login to your HSM or partition is required only if you are authorized to use those elements.
For detailed instructions for logging in to the appliance and/or your HSM or partition, see:
Appliance Login
Appliance login is always required to use the REST API. However, appliance login alone restricts you to commands that manage your appliance.
API Password Login
If you are using password-based authentication with your appliance, use this method.
Input your IP address, username, and password. Click Login.
When you are finished using the REST API, or if you need to login to a different server or as a different user, click Logout.
API Cert Login
If you want to login using a certificate, use this method.
1.Input your IP address and username.
2.Generate a new certificate by clicking Generate Cert.
3.Once your certificate has been successfully generated, click Load Cert to specify the path to the certificate.
4.Click Upload Cert to establish and accept the certificate's association with the specified user (User Name).
5.Once an association is established, click Login to communicate this information to the server and secure the relationship.
When you are finished using the REST API, or if you need to login to a different server or as a different user, click Logout.
HSM or Partition Login
You must login to your HSM or partition if you want to make full use of the REST API.
HSM Login
There are two ways to login, depending on how you typically access your HSM.
>If you have direct access to your HSM and are using password-based authentication, input your HSM serial number and password. Click Login.
>If you have indirect access to your HSM via PED, input your user role and PED identifier number. Use 0 if you are using local PED; 1 or greater for remote PED. Click Indirect Login. Use the PED to complete your login.
When you are finished using the REST API, or if you need to login to a different server or as a different user, click Logout.
Partition Login
There are two ways to login, depending on how you typically access your partition.
>If you have direct access to your partition on an HSM and are using password-based authentication, input your partition serial number and password. Click Login.
>If you have indirect access to your partition via PED, input your user role and PED identifier number. Use 0 if you are using local PED; 1 or greater for remote PED. Click Indirect Login. Use the PED to complete your login.
When you are finished using the REST API, or if you need to login to a different server or as a different user, click Logout.
Indirect
If you want to indirectly authenticate to your HSM by way of another HSM, this is the method to use.
NOTE This method requires two HSMs and is typically only used to perform an unattended login to a farm of HSMs.
Below, "Admin HSM" refers to the HSM you have direct access to; "Target HSM" refers to the target HSM that you are authenticating indirectly.
1.Login as co (crypto officer) to the partition on the Admin HSM that contains the indirect login key you wish to use.
2.Click Export Key to get the key from the Admin HSM.
3.Login as so (security officer) to the Target HSM.
4.Click Import Key to load the indirect login key onto the Target HSM. Logout of the Target HSM when finished.
5.Click Get Certificate to obtain the certificate needed for indirect login.
6.Click Indirect Challenge to get the indirect login challenge from the Admin HSM.
7.Click Generate Response to generate the indirect login response needed to communicate with the Target HSM.
8.Finally, click Indirect Login to indirectly login as so (security officer) to the Target HSM.
When you are finished using the REST API, or if you need to login to a different server or as a different user, click Logout.
