Application Programming Interface Developer's Guide

Contents

API Methods Index

Introduction

This chapter is a developer's guide for the HyTrust Application Programming Interface for managing the operations on a KeyControl cluster.

HyTrust KeyControl is a multi-tenant virtual appliance that performs key management. Key Control manages multiple virtual machines running on an infrastructure of a cloud service provider like Azure and Amazon, or inside a private cloud. They can also be physical machines. Each VM has zero or more disks. The Key Control also manages administrative users and groups. The HyTrust KeyControl API is RESTful API which provides programmatic access to the various functions of Key Control.

Resources

All API functions are HTTP methods on the Key Control resources that are accessed over HTTPS.

The following figure is a model of the Key Control resources which may be acted upon using the Key Control API.

Admin Roles

URIs

The Key Control resources are specified using URIs of the form:

/<API_version>/<resource_class>/

or

/<API_version>/<resource_class>/<resource_id>/

The <resource_id>; may contain alphanumeric characters, spaces, "˜ (tilde)", "_ (underscore)" and "- (hyphen)". Do not assume any particular format for these ids, as they may change between minor releases of the API. They should always be retrieved from other API calls.

Input and Output Formats

  • Input parameters must be URL-encoded.
  • Input parameters that are list-typed must be encoded as multi-value parameters, e.g. group=admins&group=managers&group=others
  • Non-parameter input should be JSON encoded.
  • API responses always have an HTTP response-status of 200, and a body consisting of a JSON string.
  • All responses contain a result field, which contains the value success or failure.
  • In case of failure, the response also contains an error field with a string indicating the reason for failure.

Access Token

Once an API user authenticates with Key Control, an access token is returned to the user. For all subsequent API requests, this token should be sent in the HTTP Auth-Token header.

In the API descriptions which follow, the access token is not mentioned. However, it is an implicit requirement for all the calls except login.

Example API call

$ curl -i -H "Auth-Token: TOKEN" https://kc.example.com/v3/users/
HTTP/1.1 200 OK
Date: Wed, 12 Feb 2014 06:28:45 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/1.0.0c mod_fastcgi/2.4.6 DAV/2
Vary: Cookie
Set-Cookie: sessionid=83500fb320dac40288c98642e0e45769; Path=/
X-Frame-Options: DENY
Transfer-Encoding: chunked
Content-Type: application/json
{"result": "success", "users": [{"status": "ACTIVE",
"name":
"Security Administrator", "privileges": ["SEC_ADMIN",
"DOMAIN_ADMIN", "CLOUD_ADMIN"], "id": "c2Vjcm9vdA",
"last_login":
"2014-02-12 11:56:38 IST", "login_name": "secroot"}]}

API Methods

Hytrust Data Control offers the following API methods:

Authentication

The API user has to authenticate with Key Control, before accessing any of its resources.

Login

Login to Key Control server. The API user should have a valid user account on the Key Control server.

Request

Method     URI
POST       v3/kc/login/

Parameters

Name         Type        Example
username     string      secroot
password     string      foobar8

Response

Name            Type        Example
access_token    string      c2Vjcm9vdA-1366890805-353e1

Errors

Reason                          Example Error String
Invalid username/password       Authentication failed


The access token returned by this request must be supplied as a parameter in all other API requests.The token is opaque. Handle the token with as much care as a plaintext username and password, since the possession of the token is sufficient to carry out any operation on behalf of the user.

A token is valid for one hour from the time it is issued, after which it expires. If a user changes his or her password, all tokens issued using the previous password are immediately invalidated.

Renew Token

Renew the access token. It is typically used by the clients who want to extend the session without having to ask the user to re-enter his or her credentials every hour.

Method           URI
POST             v3/kc/renew/

Parameters

Name		Type		Example
None

Response

Name		  Type		Example
access_token      string        c2Vjcm9vdA-1366890805-353e1…

Errors

Reason		    Example Error String
Invalid token       Invalid or expired session; please login

This request does make the the previous tokens invalid. All issued tokens remain valid until their expiry, unless the user changes her password.

Logout

Logout from the system. All issued tokens are invalidated

Request

Method		 	URI
POST  			v3/kc/logout/

Parameters

Name		Type		Example
None

Response

Name		  Type	       Example
result	     	  string       success

Errors

Reason		    Example Error String
Invalid token       Invalid or expired session; please login

User and Group Management

The Key Control maintains a list of users and groups. Users are the human administrators, who belong to one or more groups. In the HyTrust KeyControl system, groups (rather than individual users) own resources. A user can access and modify a resource as a member of the group that owns that resource. Users have one or more roles, like 'Security Admin' and 'Cloud Admin' (also referred to as SEC_ADMIN and CLOUD_ADMIN in this document).

With a few exceptions, to use most API methods in this section the calling user needs to have SEC_ADMIN privileges.

List the users in the system. If the user has SEC_ADMIN privileges, then she can see all the users in the system. Otherwise, the list only includes the members of the group to which the user belongs.

Request

Method		 	URI
GET			v3/users/

Parameters

Name		Type		Example
None

Response

Name		    	 Type			Example
users	     	    	 list       		
users[i].id	     	string			2083ab3093f911e3b4ed080027cbdf2a
users[i].name	     	string			Security
						Administrator
users[i].login_name 	string			secroot
users[i].status	     	string			ACTIVE
users[i].privileges	list			["SEC_ADMIN",
						"DOMAIN_ADMIN",
						"CLOUD_ADMIN"]
users[i].last_login	string			2013-05-02 12:24:29 UTC
users[i].uri		string			/v3/users
						/2083ab3093f911e3b4ed080027cbdf2a/

Errors

Reason		    Example Error String
Invalid token       Invalid or expired session; please login

User Details

Retrieve the attributes of a given user. Users with SEC_ADMIN privileges may get the details of any user. All other users may only retrieve their own attributes.

Request

Method		 	URI
GET			v3/users/<userid>/

<userid> is an id retrieved from a List Users operation (2083ab3093f911e3b4ed080027cbdf2a in the previous example).

Parameters

Name			Type		Example
None

Response

Name		  	    Type		Example
name	                    string		Security
						Administrator
login_name	  	    string		secroot
email		  	    string		some.user@somecompany.com
status	          	    string		ACTIVE
privileges	  	    list		["SEC_ADMIN",
						"DOMAIN_ADMIN",
						"CLOUD_ADMIN"]
passwd_expires    	    string		12/02/2013
account_expires   	    string		12/31/2015
last_login	            string		2013-05-02 12:24:29 UTC
failed_logins		    integer		0
groups		            list		12/31/2015
groups[i].id		    string		21172d4493f911e3b4ed
						  080027cbdf2a
groups[i].name		    string		Cloud Admin Group
groups[i].uri		    string		/v3/groups/21172d4493f911e
						3b4ed080027cbdf2a/

Errors

Reason		    Example Error String
Invalid user id       User not found

Create User

Create a new user. The API user should have SEC_ADMIN privileges to create new users.

Request

Method		 	URI
POST			v3/users/

Input

The password should be at least 8 characters long. Groups should be specified using the group names.

Name				Type		Default 	Example
full_name       	 	String				James P. Sullivan
login_name       		String				Sully
email		 		String				sully@monstersinc.com
password         		String				s3cr1tp4$$
privileges       		list				CLOUD_ADMIN,
								  SEC_ADMIN, etc.
authentication   		String		Local		Local or RADIUS
password_expires 		string		Never		12/25/2014
account_enable			string		yes		yes, no
account_expires 		string		Never		10/08/2015
groups				list		None 		Security Admin Group,
								CloudGroup, etc.

Response

Name		  Type		Example
result		  string	success

Errors

There may be several validation errors. A few of them are given below.

Reason		    Example Error String
Username 	    login_name: secroot exists.
already exists 	    Please enter a different Login Name

Edit User

Edit the attributes of an existing user. All users can use this method to change their own full names, email addresses and passwords. Security Administrators can change attributes of any user.

Request

Method		 	URI
PATCH			v3/users/<userid>/

Input

The password should be at least 8 characters long. Groups should be specified using the group-names.

Name				Type		Default 					Example
full_name        		String								James P. Sullivan
email		 		String								sully@monstersinc.com
password         		String								s3cr1tp4$$
privileges       		list								CLOUD_ADMIN,
												SEC_ADMIN, etc.
authentication   String		Local								Local or RADIUS
password_expires string		Never								12/25/2014
account_enable	string		yes								yes, no
account_expires string		Never								10/08/2015

All the attributes except full_name, email and password may be specified only if the API user has the SEC_ADMIN privileges.

Response

Name		  Type		Example
result		  string	success

Errors

There may be several validation errors. A few of them are given below.

Reason		            Example Error String
Invalid user id		    User not found
Invalid role		    Invalid roles: CLOUD ADMIN	
Invalid email		    Invalid email address
User not SEC_ADMIN	    Insufficient privileges

Delete User

Delete an existing user. This method may only be used by API users with SEC_ADMIN privileges.

Request

Method		 	URI
DELETE			v3/users/<userid>/

<userid> is an id of a user received from a List Users operation.

Parameters

Name		 Type		Example
NONE

Response

Name		 Type		Example
result		 string 	success

Errors

Reason		            Example Error String
Invalid user id		    User not found
User not SEC_ADMIN	    User has insufficient privilege

Change Default User Settings

Change default values of attributes for new users.

Request

Method		 	URI
PATCH			v3/users/

Input

Name		         Type		Example
authentication		 string 	Local or RADIUS
password_expiry	 integer	60
max_failed_logins	 integer	5
min_passwd_lnegth	 integer	8

Response

Name		        Type		Example
result		 	string 		success

Errors

Reason	                                Example Error String
Invalid authentication-type             Authentication type: LDAP not supported

List Groups

List the groups in the system. The API user with SEC_ADMIN privileges can see all the groups in the system. Otherwise, the listing is confined to those groups in which the API user is a member.

Request

Method	          URI
GET	          v3/groups/

Parameters

None

Response

Name		          	Type		Example
groups		          	list
groups[i].id		  	string        21172d4493f911e3
					      b4ed080027cbdf2a
groups[i].name		  	string        Cloud Admin Group
groups[i].desc		  	string        Default Group for Administering
					      Cloud VMs
groups[i].type		  	string        CLOUD_ADMIN
groups[i].objects         	integer       0
groups[i].uri		  	string        /v3/groups/21172d44
					      93f911e3b4ed080027cbdf2a/
groups[i].members        	list          0
groups[i].members[j].id   	string        2083ab3093f911e3b4e
					      d080027cbdf2a
groups[i].members[j].name 	string        secroot
groups[i].members[j].uri  	string        /v3/users/2083ab309
					      3f911e3b4ed080027cbdf2a/

The objects field gives the number of resources owned by the group.

Errors

Reason	          Example Error String
Invalid token	  Invalid or expired session; please login

Group Details

Retrieve the attributes of a group. Users with SEC_ADMIN privileges may get the details of any group. All other users may only retrieve details of the groups to which they belong.

Request

Method	          URI
GET	          v3/groups/<groupid>/

<groupid> is an id retrieved from the List Groups operation.

Parameters

None

Response

Name		          Type		Example
name		          string        Cloud Admin Group
desc		          string        Group for Administering Cloud VMs
type		          string        CLOUD_ADMIN
objects		          integer       0
members		          list          
members[i].id		  string        2083ab3093f911e3b4e
					d080027cbdf2a
members[i].name		  string        secroot
members[j].uri            string        /v3/users/2083ab309
					3f911e3b4ed080027cbdf2a/

The objects field gives the number of resources owned by the group.

Errors

Reason	                  Example Error String
Invalid group id	  Group not found

Create Group

Create a new group. This method may be used only by API users with SEC_ADMIN privileges.

Request

Method	          URI
POST	          v3/groups/

Input

Name		          Type		Example
name		          string	Engineering
privilege		  string	CLOUD_ADMIN
desc		          string	Scare Engineering
					Research Team
members		          list          
members[i].id		  string        secroot

The privilege attribute should be set to one of CLOUD_ADMIN, DOMAIN_ADMIN or VMSET_ADMIN.

Response

Name		          Type		Example
result		          string        success

Errors

There may be several validation errors. A few of them are given below.

Reason	                            Example Error String
Groupname already exists            name: VM Set Admin Group exists.
                                    Please enter a different Group Name

Edit Group

Edit an existing group. Only API users with SEC_ADMIN privileges may use this method to change group attributes.

Request

Method	          URI
PATCH	          v3/groups/<groupid>/

<groupid> is an id of a group retrieved from the List Groups operation.

Input

Name		          Type		Example
name		          string        Cloud Admin Group
desc		          string        Scare Engineering
					Research Team
members		          list          
members[i]		  string        secroot
add_members		  list          
add_members[i]		  string        sully
delete_members		  list          
delete_members[i]	  string        secroot

The members list may be used to replace the current member list. If the add_members list is specified, the users in the list are added to the group. If the delete_members list is specified, the users in the list are removed from the group. If either add_members or delete_members is specified and members is also specified, then the behavior is undefined. If the same user is specified in both the add_members list and the delete_members list, the behavior is undefined.

Response

Name		          Type		Example
 result		          string        success

Errors

Reason	                  Example Error String
Non-SEC_ADMIN user        User has insufficient privileges

Delete Group

Delete an existing gorup. This method may be used only by the API users with SEC_ADMIN privileges. Groups which contain users can be deleted, but the ones that own resources cannot be deleted. This is because resources must have an owner, and cannot be orphaned.

Request

Method	          URI
DELETE	          v3/groups/<groupid>/

<groupid> is an id of a group retrieved from the List Groups operation.

Parameters

None

Response

Name		          Type		Example
result                    string        success

Errors

Reason	          Example Error String
Invalid group id	  Group not found
User not SEC_ADMIN	  User has insufficient privileges
Group owns resources      Group not empty

Domain Administration

The API provides methods to administer the KeyControl domain.

List Domains

List all the domains in the system.

Request

Method	          URI
GET	          v3/domains/

Parameters

None

Response

Name		    Type		Example
domains          list
domains[i].id    string 		213f965193f911e3b4
						ed080027cbdf2a
domains[i].name  string 		KeyControl Domain
domains[i].status  string 		HEALTHY
domains[i].group  string 		Keycontrol Admin
						Group
domains[i].uri  string 			/v3/domains/213f965
						193f911e3b4ed080027cbdf2a

Errors

Reason	          Example Error String
Invalid token	  Invalid or expired session;
				  please login

Domain Details

Retrieve the attributes of a domain.

Request

Method	          URI
GET	          v3/domains/<domainid>/

<domainid> is an id of a domain retrieved from the List Domains operation.

Parameters

None

Response

Name		    Type		Example
name		    string		KeyControl Domain
status  	    string 		HEALTHY
group               string 		Keycontrol Admin
						Group
desc  	            string 		Domain of Clustered
						KeyControl Servers
allow_reconnect    string           	yes, no
require_passphrase    string           	yes, no
hide_passphrase    string           	yes, no
check_hardware_id    string           	yes, no
servers              list           	
servers[i].id        string          	2256dc5c93f911e3b4e
						d080027cbdf2a
servers[i].name      string          	kcl.hytrust.com
servers[i].status    string          	ONLINE, UNREACHABLE
servers[i].ipaddr    string             192.168.140.151
servers[i].authenticated string         yes, no
servers[i].desc    string               Primary KeyControl Server 
servers[i].uri     string               /v3/servers/2256dc5c93
						f911e3b4ed080027cbdf2a/

Errors

Reason	          Example Error String
Invalid domain id         Domain not found 
Invalid token	  Invalid or expired session;
				  please login

Edit Domain

Change the attributes of a KeyControl Domain

Request

Method	          URI
PATCH			v3/domains/<domainid>/

<domainid> is an id retrieved from a List Domains operation (213f965193f911e3b4ed080027cbdf2a in the previous example).

Input

Name		          Type		Example
desc		          string        Domain of Clustered
					KeyControl Servers
allow_reconnect     	  string        yes, no
require_passphrase        string	yes, no
hide_passphrase           string        yes, no
check_hardware_id         string        yes, no

Errors

Reason	          		Example Error String
Invalid domain id  		Domain not found
Invalid token		        Invalid or expired session;
				please login

Edit Server

Change the description attribute of a KeyControl server.

Request

Method	          URI
PATCH	          v3/servers/<serverid>/

<serverid>is an id retrieved from a Domain Details operation (2256dc5c93f911e3b4ed080027cbdf2a in the previous example). The whole URI also may be retrieved from the same operation.

Input

Name		          Type		Example
desc		          string        Initial KeyControl Servers

Response

Name		    Type		Example
result	    	    string		success

Errors

Reason	                  Example Error String
Invalid server id         Server not found
Invalid token	          Invalid or expired session;
			  please login

Authenticate Server

Request

Method	          	URI
POST			v3/servers/<serverid>/operation/

<serverid> is an id retrieved from a Domain Details operation (2256dc5c93f911e3b4ed080027cbdf2a in the previous example). The entire URI may also be retrieved from the same operation.

Parameters

Name		    Type		Example
operation        string      authenticate
passphrase	    string		thisisasamplepassphrase

The operation parameter must be set to authenticate. The passphrase should be at least 16 characters long.

Errors

Reason	                  Example Error String
Invalid server id         Server not found
Invalid token	  	  Invalid or expired session;
			  please login

Cloud VM Set Management

A Cloud VM Set can be considered a logical grouping of related VMs - for example, "Amazon EC2 VM", "Legal Dept VM", and so on. A Cloud VM Set is owned by a group with CLOUD_ADMIN privileges. This section deals with APIs related to management of Cloud VM Sets.

List Cloud VM Sets

Any authenticated user can issue this request. Only the Cloud VM Sets which the user owns as a member of the groups that own those VM Sets are returned by this operation. Note that privileged users like secroot cannot see Cloud VM Sets just because they happen to have SEC_ADMIN and CLOUD_ADMIN privileges - they must be members of the groups that own the Cloud VM Sets in order to see them.

Request

Method	          URI
GET	          v3/cvmsets/

Parameters

None

Response

Name		    Type		Example
cvmsets	    	    list	
cvmsets[i].id       string	        78a7e865947a11e3b4e
					d080027cbdf2a
cvmsets[i].name     string	        Amazon AWS VMs	
cvmsets[i].groupid  string              21172d4493f911
				        e3b4ed080027cbdf2a
cvmsets[i].group    string              Cloud Admin Group
cvmsets[i].desc     string              AWS VMs for engineering
cvmsets[i].uri      string              /v3/cvmsets/78a7e865947a11e3
				        b4ed080027cbdf2a/

Errors

Reason	          Example Error String
Invalid token	  Invalid or expired session;
		  please login

Cloud VM Set Details

Retrieve the attributes of a Cloud VM Set.

Request

Method	          URI
GET	          v3/cvmsets/<cvmsetid>/

<cvmsetid> is an id retrieved from a List Cloud VM Sets operation (78a7e865947a11e3b4ed080027cbdf2a in the previous example). As a special case, if the <cvmsetid> is 0, the list of unauthenticated VMs will be returned in cvms.

Parameters

None

Response

Name		    		Type		Example
name		   		string		Amazon AWS VMs
desc		    		string		AWS VMs for engineering
group		    		string		Cloud Admin Group
cvms		    		list		
cvms[i].id	    		string		0c8373be947c11e3b
						4ed080027cbdf2a
cvms[i].name	    		string		ubuntu64
cvms[i].status	    		string		ONLINE
cvms[i].ndisk	    		integer		0
cvms[i].authenticated  		string	        yes, no
cvms[i].desc	    		string          Ubuntu 64-bit build
						server
cvms[i].ipaddr    		string   	192.168.100.2
cvms[i].uri	  		string		/v3/cvms/0c8373be947
					        c11e3b4ed080027cbdf2a/
unused_certs  list
unused_certs[i].id		string		4c81a042a60b11e2b5
						cf000c29ed8423
unused_certs[i].desc   		string         	Created by spate at
						2013-04-15 20:30:23
unused_certs[i].expires	  	string  	12/31/2015
unused_certs[i].uri		string  	/v3/certificates/
						4c81a042a60b11e2b
						5cf000c29ed8423/
keyids	list
keyids[i].id			string		aws_key
keyids[i].name			string		aws_key
keyids[i].desc			string		Key for secure migration
keyids[i].algorithm		string		AES-256
keyids[i].expires		string		Never, 12/31/2015
keyids[i].onexpiry		string		NA,NO_USE,SHRED
keyids[i].status		string		ACTIVE, EXPIRED
keyids[i].uri 	        	string  	/v3/keyids/aws_key/

Errors

Reason	          		Example Error String
Invalid cvmset id	        Cloud VM Set not found

Create Cloud VM Set

Create a new Cloud VM Set. Any authenticated user with Cloud Admin privileges can use this method. The Cloud VM Set created as a result, will be owned by the Cloud Admin group to which the ownership is assigned at the time of creation. The API user must be a member of this Cloud Admin group.

Request

Method	          URI
POST	          v3/cvmsets/

Parameters

Name		    Type		Example
name		    string		Legal CVMs
group	    	    string		Cloud Admin Group
desc		    string		Legal Dept VMs
heartbeat           integer		20
grace_period	    integer		300

The group field specifies the name of the Cloud Administration group to which the Cloud VM Set will belong. The heartbeat and grace_period attributes are specified in seconds.

Reason	          Example Error String
Invalid group	  Group not found, or admin is not a member

Edit Cloud VM Set

Edit an existing Cloud VM Set. The API user must belong to the group which owns this Cloud VM Set. He or she can also move ownership of a Cloud VM Set to another group, as long as the API user is a member of the target group as well.

Request

Method	          URI
GET	          v3/cvmsets/<cvmsetid>/

<cvmsetid> is an id of a Cloud VM Set retrieved from a List Cloud VM Sets operation.

Input

Name		    Type		Example
name                string              Legal CVMs
desc                string              Legal Dept VMs
group               string              Cloud Admin Group
heartbeat           integer		20

The group field specifies the name of the Cloud Administration group to which the Cloud VM Set will belong. The heartbeat and grace_period attributes are specified in seconds.

Response

Name		    Type		Example
result		    string		success

Errors

Reason	          	  Example Error String
Invalid group	          Group not found, or admin  is not a member

Delete Unused Certificate

Delete unused certificate in a Cloud VM Set.

Request

Method	             	  URI
DELETE                    v3/certificates/<certid>/

<certid> is an id retrieved from a Cloud VM Set Details operation. The entire URI may also be retrieved from the same operation.

Parameters

None

Response

Name		    Type		Example
result		    string		success

Errors

Reason	          	                Example Error String
Invalid certificate id	  		Certificate not found

Delete Cloud VM Set

Delete an existing Cloud VM Set. The API user must belong to the group which owns this Cloud VM Set. Cloud VM Sets which contain VMs cannot be deleted. In order to delete such Cloud VM Sets, the VMs they contain must be removed first.

Request

Method	          	  URI
DELETE                    v3/cvmsets/<cvmsetid>/

<cvmsetid> is an id of a Cloud VM Set retrieved from a List Cloud VM Sets operation.

Parameters

None

Response

Name		    Type		Example
result		    string		success

Errors

Reason	                	Example Error String
Invalid group id	        Cloud VM Set not found
Cloud VM Set contains VMs	Cloud VM Set not empty

Edit KeyID

Edit a KeyID of a Cloud VM Set. KeyIDs are used to encrypt objects that can be moved between VMs within a single Cloud VM Set. The creation and deletion of the KeyIDs are done on the VM using hcl keyid. The objects are encrypted and decrypted also on the VM using hcl encryptfile and hcl decryptfile.

Request

Method	          	  URI
PATCH			  v3/keyids/<keyid>/

<keyid> is an id of a KeyID retrieved from a Cloud VM Set Details operation.

Input

Name		    Type		Example
expires 	    string              NEVER, 12/31/2015
onexpiry            string              NO_USE, SHRED

Response

Name		    Type		Example
result		    string		success

Errors

Reason	                Example Error String
Invalid key id	        KeyID not found

Revoke KeyID

Revoke a KEYID a Cloud VM Set.

Request

Method	          URI
POST	          v3/keyids/<keyid>/operation/

<keyid> is n id of a KeyID retrieved from a Cloud VM Set Details Operation.

Parameters

Name		    Type		Example
operation           string		revoke

The operation parameter has to be set to revoke.

Response

Name		    Type		Example
result		    string		success

Errors

Reason	                Example Error String
Invalid key id	        KeyID not found

Unrevoke KeyID

Unrevoke a KeyID of a Cloud VM Set.

Request

Method	          URI
POST	          v3/keyids/<keyid>/operation/

<keyid> is an id of a KeyID retrieved from a Cloud VM Set Details operation.

Parameters

Name		    Type		Example
operation	    string		unrevoke

The operation parameter has to be set to unrevoke.

Response

Name		    Type		Example
result	    	    string		success

Errors

Reason	                Example Error String
Invalid key id	        KeyID not found

Cloud VM Management

A Cloud VM is a machine, usually virtual, which contains a running instance of the HyTrust Agent. It may have one or more disks protected by the HyTrust system.

Cloud VM Details

Retrieve the attributes of a Cloud VM.

Request

Method	          URI
GET	          v3/cvms/<cvmid>/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The entire URI may also be retrieved from the same operation.

Parameters

None

Response

Name		    Type		Example
name		    string		ubuntu64
status              string              ONLINE
authenticated       string              yes,no
desc                string              Ubuntu 64-bit build server
ipaddr              string              192.168.100.2
cvmset              string              Amazon AWS VMs
cvmsetid            string              78a7e865947a11e3b4e
					d080027cbdf2a
cvmset_uri          string              /v3/cvmsets/78a7e86
					5947a11e3b4ed080027cbdf2a/
heartbeat	    integer		10
grace_period        integer		86400
os		    string		Linux ubuntu64
						3.8.0-29-generic…
agent               string              2.4 (b5348)
reauthonip          string              yes,no
reauthonhwsig       string              yes,no
reauthoreboot       string              yes,no
cert_expires        string              02/13/2015
disks               list
disks[i].id         string              87c068b6b72699c75b9
					af7293351dc46
disks[i].uri        string              /v3/disks/87c068b6b
					72699c75b9af7293351
					dc46/

The heartbeat and grace_period attributes are specified in seconds.

Errors

Reason	                Example Error String
Invalid cvm id		Cloud VM not found

Edit Cloud VM

Edit a cloud VM.

Request

Method	          URI
PATCH	          v3/cvms/<cvmid>/

<cvmid> is an id retreived from a Cloud VM Set Details operation. The entire URI may also be retrieved from the same operation

Input

Name		    Type		Example
desc                string  		Legal Dept VMs
group		    string		Cloud Admin Group
heartbeat           integer             20
grace_period	    integer	        300
reauthonip          string              yes, no
reauthonhwsig       string              yes, no
reauthonreboot      string              yes, no

The heartbeat and grace_period attributes are specified in seconds.

Response

Name		    Type		Example
result              string              success

Errors

There may be several validation errors. A few of them are given below.

Reason	                Example Error String
Invalid cvm id		Cloud VM not found

Create Cloud VM Certificate

Create a certificate for a new Cloud VM to be created within a Cloud VM Set.

Request

Method         URI
POST           v3/cvmsets/
              <cvmsetid>/

<cvmsetid> is an id of a Cloud VM Set retrieved from a List Cloud VM Sets operation

Parameters

Name		    Type		Example
passphrase          string              passphrase

The expires attribute should be specified in MM/DD/YYYY format.

Response

Name		    Type		Example
result	    	    string		success
cvmid	            string		bf5283f813a811e3b3c
					308002778562f
certificate	    string		/v3/certificates/
					9ea3f1ba949111e
					3b4ed080027cbdf2a/

Errors

Reason	                	Example Error String
Invalid cvmset id		Cloud VM Set not found
Invalid expiration              Please enter a valid expiration date

On successful completion of the request, the newly created Cloud VM certificate can be downloaded from the URI provided in the response. hcl requires the name of the certificate file to be in a specific format: <cvmid>_<timestamp>.bin, where <cvmid> is obtained from the result of the above operation and <timestamp> is an integer corresponding to a locally computed Unix timestamp (seconds since epoch).

Renew Cloud VM Certificate

Create a new certificate for an existing Cloud VM. This method may be used to issue a new certificate for a Cloud VM whose certificate is about to expire.

Request

Method             URI
POST               v3/cvms/<cvmid>/operation/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The entire URI may also be retrieved from the same operation.

Name		    Type		Example
operation           string              renew
passphrase          string              thisisasamplepassphrase
expiration          string              12/05/2015

The operation parameter has to be set to renew. The expiration attribute should be specified in MM/DD/YYYY format.

Response

Name		    Type		Example
result              string              success

Errors

Reason	                        Example Error String
Invalid cvm id		        Cloud VM Set not found

Clone Cloud VM certificate

Clone the certificate of an existing Cloud VM. Trying to spin up a clone or a snapshot of an existing Cloud VM will normally fail for security reasons. To successfully bring up such a clone VM, it must be registered with the KeyControl. This method is used to retrieve a clone certificate which may be used to register the clone VM with access to the original encryption keys.

Request

Method                 URI
POST                   v3/cvms/<cvmid>/operation/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The whole URI also may be retrieved from the same operation.

Parameters

Name              Type         Example
Operation         string       clone
passphrase        string       thisisasamplepassphrase
expiration        string       12/05/2015

The operation parameter has to be set to clone.

Response

Name          Type      Example
result        string    success

Errors

Reason                     Example Error String
Invalid cvm id             Cloud VM not found

Delete Cloud VM

Remove a Cloud VM from Key Control control. All states associated with the Cloud VM are wiped from the Key Control, including all keys. This operation must therefore be carried out with caution, as it will result in permanent data loss of any encrypted data stored in the Cloud VM.

Request

Method                   URI
DELETE                   v3/cvms/<cvmid>/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The entire URI may also be retrieved from the same operation.

Parameters

None

Response

Name          Type      Example
result        string    success

Errors

Reason                  Example Error String
Invalid cvm id          Cloud VM not found

Authenticate Cloud VM

Authenticate a Cloud VM on the Key Control side, using a one-time passphrase (OTP). This OTP must be the same one used at the CVM end to initiate an authentication using hcl register or hcl auth.

Request

Method                   URI
POST                     v3/cvms/<cvmid>/operation/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The entire URI also may be retrieved from the same operation.

Parameters

Name          Type      Example
operation     string    authenticate
passphrase    string    thisissamplephrase

The operation parameter has to be set to authenticate. The passphrase should be at least 16 characters long.

Response

Name          Type      Example
result        string    success

Errors

Reason                  Example Error String
Invalid cvm id          Cloud VM not found

Revoke Cloud VM

Revoke access to all encrypted disks on a given Cloud VM. Keys will no longer be served for that Cloud VM, and the HyTrust agent on the VM will forcibly detach all encrypted disks, making their clear-text contents unavailable. Once a Cloud VM has been revoked, the only way to re-enable access is to go through an authentication cycle by issuing the hcl auth command on the Cloud VM with a one-time password (OTP), and authenticating the Cloud VM on the Key Control using the OTP, either via the Key Control GUI or the Authenticate Cloud VM API method described above.

Request

Method                   URI
POST                     v3/cvms/<cvmid>/operation/

<cvmid> is an id retrieved from a Cloud VM Set Details operation. The whole URI also may be retrieved from the same operation.

Parameters

Name          Type      Example
operation     string    revoke
passphrase    string    thisissamplephrase

The operation parameter has to be set to revoke.

Response

Name          Type      Example
result        string    success

Errors

Reason                  Example Error String
Invalid cvm id          Cloud VM not found

Cloud VM Disk Management

Cloud VM Disk Details

Retrieve details of a disk on a Cloud VM. The disk should have been placed under HyTrust management.

Request

Method                          URI
GET                             v3/disks/<diskid>/

<diskid> is an id retrieved from a Cloud VM Details operation. The whole URI also may be retrieved from the same operation.

Parameters

None

Response

Name            Type             Example
name              string         sdb1
mapped_device     string         clear_sdb1
mapped_device     string         ACTIVE, DISABLED
algorithm         string         AES-256,AES-128
expires           string         NEVER, 12/31/2015
onexpiry          string         NA, NO_USE,SHRED
size              string         104857600

The size attribute is in bytes

Errors

Reason              Example Error String
Invalid disk id     Device not found

Revoke Cloud VM Disk

Revoke access to a specific disk on a Cloud VM. Keys will no longer be served for that disk, and the HyTrust agent on the VM will forcibly detach that disk, making its clear-text contents unavailable.

Request

Method             URI
POST                  v3/cvms/<diskid>/operation/

<diskid> is an id retrieved from a Cloud VM Details operation. The whole URI also may be retrieved from the same operation.

Parameters

Name          Type           Example
operation    string         revoke

The operation parameter has to be set to revoke.

Response

Name		    Type		Example
result           string		success

Errors

Reason	                        Example Error String
Invalid disk id		        Device not found

Unrevoke Cloud VM Disk

Re-enable access to a specific disk on a Cloud VM. Keys will be served for that disk, and the HyTrust agent on the VM will re-attach that disk (if it was marked for auto-attach), making its clear-text contents available.

Request

Method             URI
POST               v3/disks/<diskid>/operation/

<diskid> is an id id retrieved from a Cloud VM Details operation. The whole URI also may be retrieved from the same operation.

Parameters

Name          Type           Example
operation    string         unrevoke

The operation parameter has to be set to unrevoke.

Response

Name		   Type  		    Example
result            string	  	    success

Errors

Reason	                        Example Error String
Invalid disk id		        Device not found

Edit Cloud VM Disk

Change the key expiration time and/or action of a specific disk on a given Cloud VM. If the keys had previously expired, they will now be served for that disk, and the HyTrust agent on the VM will re-attach that disk (if it was marked for auto-attach), making its clear-text contents available.

Request

Method             URI
PATCH             v3/disks/<diskid>/

<diskid> is an id retrieved from a Cloud VM Details operation. The whole URI also may be retrieved from the same operation.

Input

Name        Type       Example
expires     string     12/05/2015
onexpiry    string     NO_USE, SHRED

The expires attribute should be specified in MM/DD/YYYY format.

Response

Name		    Type		Example
result       	    string		success

Errors

Reason	                   	Example Error String
Invalid disk id		        Device not found
Invalid expiration              Please enter a valid
				expiration date.

Change Global Settings

Change global settings like default Heartbeat interval and Grace Period.

Request

Method         URI
PATCH          v3/kc/

Input

Name                   Type              Example
heartbeat              integer           20
grace_period           integer           300

The heartbeat and grace_period attributes are specified in seconds.

Response

Name		    Type		Example
result        	   string		success

Errors

Reason	        	        Example Error String
Values beyond range             Heartbeat interval too high

Get Alert

Heartbeat interval too high

Request

Method             URI
GET                v3/alerts/

Parameters

None

Response

Name		    Type		Example
alerts              list
alerts[i].id        string              b62c3bb3954611e3bfe
					6080027cbdf2a
alerts[i].message   string 		Account disabled for
					spate due to repeated
					failures
alerts[i].date      string              10/08/11 17:06:52
alerts[i].uri       string              /v3/alerts/b62c3bb3
					954611e3bfe6080027
					cbdf2a/

Delete Alert

Delete an alert message.

Request

Method             URI
DELETE             v3/alerts/<alertid>>/

<alertid> is an id retrieved from a Get Alerts operation. The whole URI also may be retrieved from the same operation.

Parameters

None

Response

Name		    Type		Example
result              string              success

Errors

Reason       		Example Error String
Invalid alert id        Alert not found

Enumerations

cvm.status :       'ONLNE', 'REVOKED'
disk.onexpiry:      'NA', 'NO_USE', 'SHRED'
disk.status:        'ACTIVE', 'DISABLED', 'REVOKED'
domain.status:      'HEALTHY', 'DEGRADED'
keyid.algorithm:    'AES-128', 'AES-256'
keyid.onexpiry:     'NA', 'NO_USE', 'SHRED'
keyid.status:       'ACTIVE', 'EXPIRED', 'REVOKED'
server.status:      'ONLINE', 'UNREACHABLE'
user.privileges:    'SEC_ADMIN', DOMAIN_ADMIN', 'CLOUD_ADMIN'
user.status:        'ACTIVE', 'DISABLED'

Generic Errors

Reason Example            Error String
Invalid command           Invalid Command

Key Control API Curl Commands

Tip: If the jq command is installed, pipe the output of curl into jq '.' to get the formatted output.

Login

login

$ curl -s -k -d "username=secroot&password=mypassword" https://kc1/3.0/kc/
{
"result": "success",
"access_token": "c2Vjcm9vdA-1399191404-6c652fbbf2a4c087bb2ffb517773690a461d0620eedc71f594f0b1bf27648cc4"
}

login and assign the token to a variable

$ ACCESS_TOKEN=$(curl -s -k -d "username=secroot&password=mypassword" https://kc1/3.0/kc/|awk -F\" '{print $4}')

User Management

list all users

$ curl -s -k https://kc1/3.0/users/?access_token=$ACCESS_TOKEN
{
  "users": [
	{
  	"login_name": "secroot",
  	"last_login": "2014-05-04 07:16:44 UTC",
  	"id": "secroot",
  	"privileges": [
    	"SEC_ADMIN",
    	"DOMAIN_ADMIN",
    	"CLOUD_ADMIN"
  	],
  	"name": "Security Administrator",
  	"status": "Active"
	}
  ],
  "result": "success"
}

list user details for secroot

$ curl -s -k https://kc1/3.0/users/secroot/?access_token=$ACCESS_TOKEN
{
  "account_expiration": "Never",
  "failed_logins": 0,
  "last_login": "2014-05-04 07:16:44 UTC",
  "email": "lalsam@gmail.com",
  "status": "Active",
  "access_time_period": "0 - 24",
  "password_expiration": "Never",
  "result": "success",
  "groups": [
	{
  	"name": "Storage Admin Group",
  	"id": "Storage Admin Group"
	},
	{
  	"name": "KeyControl Admin Group",
  	"id": "KeyControl Admin Group"
	},
	{
  	"name": "Cloud Admin Group",
  	"id": "Cloud Admin Group"
	}
  ],
  "name": "Security Administrator",
  "privileges": [
	"SEC_ADMIN",
	"DOMAIN_ADMIN",
	"CLOUD_ADMIN"
  ],
  "access_days": "daily"
}

create a new user named testuser

$ curl -s -k -X POST -H "Content-Type: application/json" \
       -H "Api-Authorization: token $ACCESS_TOKEN" \
    	-d '{"login_name":"testuser","full_name":"Test User",
    	"password":"hithere!","privileges":"SEC_ADMIN",
    	"email":"lalsam@gmail.com"}' \
    	https://kc1/3.0/users/
{
  "result": "success"
}

edit testuser to change full name

$ curl -s -k -X PATCH -H "Content-Type: application/json" \
       -H "Api-Authorization: token $ACCESS_TOKEN" \
       -d '{"full_name":"New Test User"}' \
       https://kc1/3.0/users/testuser/
{
  "result": "success"
}

delete testuser

$ curl -s -k -X DELETE -H "Api-Authorization: token $ACCESS_TOKEN" \
        https://kc1/3.0/users/testuser/
{
  "result": "success"
}

Back to Contents