SafeNet Network HSM REST API

Introduction

SafeNet Network HSM offers an exciting new way to administer the appliance. In addition to the long-standing Luna shell, administrators now have the ability to use a representational state transfer application programming interface — REST-ful API — to configure and query the appliance.

LunaSH Cross Reference

Most existing SafeNet Network HSM customers are familiar with LunaSH. The first question a SafeNet Network HSM administrator familiar with LunaSH might have is: What is the relationship between the REST API resources and the LunaSH commands of SafeNet Network HSM? The tables at the following links provide a cross reference between existing LunaSH commands and REST API resources. Note that the REST API condenses many of the LunaSH commands together for greater efficiency. For this reason, many cross references are not direct 1:1 mappings.

"client" commands ("client" LunaSH Commands Cross Reference)
"hsm" commands ("hsm" LunaSH Commands Cross Reference)
"ntls" commands ("ntls" LunaSH Commands Cross Reference)
"partition" commands ("partition" LunaSH Commands Cross Reference)
"service" commands ("service" LunaSH Commands Cross Reference)
"stc" commands ("stc" LunaSH Commands Cross Reference)

What Do I Need to Use the REST API?

SafeNet Network HSM 6.1 is the first release to support the REST API feature. If you have an appliance at an older release, you need to upgrade your appliance to 6.1 or a subsequent release to get the support necessary for the feature.

To make use of the REST API on a SafeNet Network HSM 6.1 or subsequent release appliance, you need to first install the rest-api secure package. The version will change over time but here is an example of the steps to install the REST API.

Obtain the REST API secure package update
Transfer it to the appliance via SCP
Login to the HSM (hsm login)
Apply the package update for the REST API (package update rest-api-1.0.0-45 -auth d69PbsY696LYW5YP)

You may want to test that the REST API is operational. To do so, follow these steps:

Open a LunaSH prompt on your appliance
Type: webserver enable NOTE: You must issue this command whenever you reboot or power cycle the appliance. The web server is disabled by default.
Type: webserver certificate generate –keytype rsa
Type: service restart webserver
Copy the following java script to a file and name it login.html. Replace YOURLUNASAIPADDRESS with the IP address of the SafeNet Network HSM appliance you want to administer and YOURLUNASAPASSWORD with the admin account password.

<html>
<head>
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
</head>

<body>
    <input id="login" type="button" value="Login"/>
    <a href="https:/YOURLUNASAIPADDRESS:8080/api/lunasa/hsms">hsms</a>

    <script>

        var loginData = {   username:"admin",
                            password:"YOURLUNASAPASSWORD"};

        $("#login").on("click", function(e){
            $.ajax({
                type: 'post',
                url: "https://YOURLUNASAIPADDRESS:8080/auth/login/basic",
                contentType: "application/vnd.safenetinc.lunasa+json;version=",
                dataType: 'json',
                data: JSON.stringify(loginData),
                success: function(data) {
                    console.log("worked");
                    console.log(data);
                },
                error: function(e,status,error){
                    console.log(e);
                    console.log(status);
                    console.log(error);
                },
                xhrFields: {
                    withCredentials: true
                },
                timeout: 2000
            });

        });
    </script>

</body>
</html>

Start your favorite browser.
Open the login.html Java script.
Click the "login" button in the top-right corner.
Click the "hsms" button in the top-right corner.
Accept the self-signed server certificate of the SafeNet Network HSM if informed that the server is unsafe or the connection is not private.
If successfully connected to the web server on the SafeNet Network HSM, you should see something similar to the following example in the top of your browser:

{"hsms":[{"id":"117290","label":"mysa","url":"/api/lunasa/hsms/117290"}]}
Form the URL with the serial number of your HSM to query more details of the HSM and hit enter. Using the above example, the URL is:

https://YOURLUNASAIPADDRESS:8080/api/lunasa/hsms/117290

You should see information similar to the following example in your browser (formatting with returns in this example):

 {"storageSpace":{"free":2097152,"used":0,"total":2097152},
"supportInfo":"",
"counter":"/api/lunasa/hsms/117290/counter",
"pkiEnabled":true,
"debugInfo":"",
"fipsModeEnabled":false,
"zeroized":false,
"loggedIn":false,
"authenticationMethod":"PASSWORD",
"model":"K6 Base",
"driverTimeout":0,
"firmwareVersion":"6.22.0",
"label":"Admin",
"licenses":"/api/lunasa/hsms/117290/licenses",
"partitions":"/api/lunasa/hsms/117290/partitions",
"roles":"/api/lunasa/hsms/117290/roles",
"policies":"/api/lunasa/hsms/117290/policies"}

Organization of Documentation

The best way to use this documentation is to have the list of pages open on the left and the viewing pane on the right as the following example shows.

Best way to view documentation

The pages in the left pane have the following organization.

The first page — this one — is an introduction to the REST API.
The next set up pages describe resources specific to the REST API framework. These pages are in alphabetical order.
The large set of pages that follow identify the various resources available in the REST API as plug-ins. These pages are in alphabetical order.
A set of pages thereafter describe each of the REST objects. These pages are in alphabetical order.
The documentation concludes with cross reference tables for the various LunaSH commands that the REST API replaces.

Notes