Open topic with navigation


API Developer's Guide

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 node that performs key management. KeyControl manages multiple virtual machines running on an infrastructure of a cloud service provider such as Azure and Amazon, or inside a private cloud. They can also be physical machines. Each VM has zero or more disks. The KeyControl also manages administrative users and groups. The HyTrust KeyControl API is a RESTful API which provides programmatic access to the various functions of KeyControl.

Resources

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

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

URIs

The KeyControl 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

Access Token

Once an API user authenticates with KeyControl, 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 that 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/v4/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 DataControl offers the following API methods:

Authentication

The API user has to authenticate with KeyControl before accessing any of its resources.

Login

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

Request

 
Method URI
   
POST v4/ 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
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 Policy Agents that want to extend the session without having to ask the user to re-enter his or her credentials every hour.

Method          URI
POST            v4/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 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         v4/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 KeyControl 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	       v4/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	       /v4/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		     v4/users/<userid>/

<userid> is an id retrieved from aList 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		21172d4493f911e3b4edvx
						 
groups[i].name	string		Cloud Admin Group
groups[i].uri	string		/v4/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	 	     v4/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 v4/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
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		   v4/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 UserSettings

Change default values of attributes for new users.

Request

                Method		 	URI
            
PATCH			v4/users/

Input

Name		   Type	    Example
authentication	      string   Local or RADIUS
password_expiry	      integer  60
max_failed_logins     integer  5
min_passwd_length  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	         v4/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        /v4/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        /v4/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	             v4/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        /v4/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	          v4/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	          v4/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 group. 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	          UR
DELETE	          v4/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	          v4/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 			/v4/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	          v4/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               /v4/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      v4/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	       v4/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		v4/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	          v4/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              /v4/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	          v4/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		/v4/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  	/v4/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  	/v4/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	         v4/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, grace_period, andrekey_interval attributes are specified in seconds, and rekey_bucket is an integer.

                
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	          v4/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, grace_period, and rekey_interval attributes are specified in seconds, and rekey_bucket is an integer. 
            

            
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          v4/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          v4/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

            
Cloud Task List


            
Retrieve list of tasks for  Cloud VM Set.
Request

Method    URI

GET       v4/cvmsets/<cvmsetid>/tasks/


            

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


Parameters


            
None


            
Response

            
Name Type Example

tasks {
  uuid string ec3f3c06-9603-11e6-8d86-000c29cd584d
  vmguid string cb44a8cf-9604-11e6-8077-000c29cd584d
  aguid string f599badc-8af1-11e6-8d86-000c29cd584d
  admin string Security Administrator
  guest string Win2012
  op string encrypt
  params {
   name string C:
   altname string C:
  }
  state string inprogress
  progress  integer 88
  sched_time integer 1476885801
  start_time integer 1476895801
  end_time integer 1476985801
  update_time integer 1476995801
  description  string Scheduled key rotation.
  msg string device not available
}
summary {
  scheduled integer 1
  completed integer 1
  failed integer 1
  inprogress integer 1
  stopped integer 1
  total  integer 5
}
result string success


            
Time is specified as seconds from epoch.



            
Errors

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

            
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			  v4/keyids/<keyid>/
            

            

            
<keyid> is the 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 of a Cloud VM Set.

            
 Request
Method	          URI
            
POST	          v4/keyids/<keyid>/operation/
            

            

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

            
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 the KeyID of a Cloud VM Set.

            
 Request
Method	          URI
POST	          v4/keyids/<keyid>/operation/
            

            

            
<keyid> is the 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
DataControl Policy Agent (Policy 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	          v4/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              /v4/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              /v4/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	        v4/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
Nme		    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, grace_period and rekey_interval attributes are specified in seconds, and rekey_bucket is an integer.
            

            
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 set mapping task on Cloud VM

            

Create “set mapping” task on Cloud VM to update mapping.

            

                

                
                    Request
Method             URI
                

POST               v4/cvms/<cvmid>/operation/


            

            

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

                    
Name                Type                Example
operation           string              mapping
mapping_guid        string              guid of mapping to be set

            

                Response

            
Name            	Type        	Example
                
result              string              success
            

            
Errors
            

Reason                            Example Error String
Invalid cvm id                    Cloud VM Set 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           v4/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		/v4/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               v4/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                   v4/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 KeyControl control. All states associated with the Cloud VM are wiped from the KeyControl,
	 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                 v4/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 KeyControl 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                     v4/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 KeyControl using the OTP,
	 either via the KeyControl GUI or the Authenticate Cloud VM API method described above.
            

            
Request
                
Method                   URI
POST                     v4/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 Task List


            
Retrieve list of tasks for  a Cloud VM.

            
Request

Method   URI

GET       v4/cvms/<cvmid>/tasks/  


            
<cvmid> is an id retrieved from a Cloud VM Set Details operation. 



            
Parameters


            
None



            
Response



Name Type Example

tasks {
  uuid string ec3f3c06-9603-11e6-8d86-000c29cd584d
  vmguid string cb44a8cf-9604-11e6-8077-000c29cd584d
  aguid string f599badc-8af1-11e6-8d86-000c29cd584d
  admin string Security Administrator
  guest string Win2012
  op string encrypt
  params {
   name string C:
   altname string C:
  }
  state string inprogress
  progress  integer 88
  sched_time integer 1476885801
  start_time integer 1476895801
  end_time integer 1476985801
  update_time integer 1476995801
  description  string Scheduled key rotation.
  msg string device not available
}
result string success


            
Time is specified as seconds from epoch.



            
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                          v4/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
            

            
Encrypt/rekey/decrypt Cloud VM Disk

            

Add task to encrypt/rekey/decrypt a specific disk on a Cloud VM. 


            
Request
Method             URI

POST               v4/cvms/<diskid>/operation/


            

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

                    

            
Parameters
            
Name          Type           Example
operation    string         encrypt/rekey/decrypt



            

                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


            
Encrypt / Rekey Decrypt Cloud VM Disk

            
Add task to encrypt/rekey/decrypt a specific disk on a cloud VM.

            
Request
Method             URI

POST               v4/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         encrypt/rekey/decrypt

            
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

            
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                  v4/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               v4/disks/<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         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             v4/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, such as the  default Heartbeat interval and
            Grace Period.
            

            
Request
Method         URI
PATCH          v4/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
name       	   string		success
            

            
Errors
Reason	        	        Example Error String
Values beyond range             Heartbeat interval too high
            

            
Get Alert
            

            
Display the most recent Alert.

            
Request
Method             URI
GET                v4/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              /v4/alerts/b62c3bb3
					954611e3bfe6080027
					cbdf2a/

            
Delete Alert
            

            
Delete an alert message.

            
Request
Method             URI
DELETE             v4/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
            

            
KeyControl 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.3/kc/
            

            
{
            

            

"result": "success",
"access_token": "c2Vjcm9vdA-1399191404-6c652fbbf2a4c087bb2ffb517773690a4 \
            

            
61d0620eedc71f594f0b1bf27648cc4"

            

            
}
            

            
Login and Assign the Token to a Variable
                
$ ACCESS_TOKEN=$(curl -s -k -d "username=secroot&password=mypassword" \

            

                
                    
                                         https://kc1/3.3/kc/|awk -F\" '{print $4}')
                    
                
                
                    
                        
                            

                        
                    
                
            

            
User Management

            
List all users.
$   curl -s -k https://kc1/3.3/users/?access_token=$ACCESS_
{
  "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.3/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.3/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.3/users/testuser/   {
  "result": "success"
}
            

            

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


        

        
Open topic with navigation