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 the 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.
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.
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.
group=admins&group=managers&group=others200 and a body consisting of a JSON string.
success or failure.
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.
$ 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"}]}
HyTrust DataControl offers the following API methods:
The API user has to authenticate with KeyControl before accessing any of its resources.
Login to the KeyControl server. The API user should have a valid user account on the KeyControl server.
Method
|
URI
|
| POST v4/ | kc/login/ |
Name
|
Type
|
Example
|
username
|
string
|
secroot
|
| password | string | foobar8 |
Name
|
Type
|
Example
|
access_token
|
string
|
c2Vjcm9vdA-1366890805-353e1
|
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 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 URIPOST v4/kc/renew/Parameters
Name Type Example
None
Response
Name Type Exampleaccess_token string c2Vjcm9vdA-1366890805-353e1…Errors
Reason Example Error StringInvalid token Invalid or expired session; please loginThis request does make the previous tokens invalid. All issued tokens remain valid until their expiry, unless the user changes her password.
Logout from the system. All issued tokens are invalidated.
Request
MethodURI
POST v4/kc/logout/
Parameters
Name Type Example
None
Response
Name Type Exampleresult string successReason Example Error String
Invalid token Invalid or expired session; please login
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 he or she can see all the users in the system. Otherwise, the list only includes the members of the group to which the user belongs.
Method URI
GET v4/users/Name Type Example
None
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/
Reason Example Error String
Invalid token Invalid or expired session; please log inRetrieve 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.
Method URI
GET v4/users/<userid>/<userid> is an id retrieved from a List Users
operation (2083ab3093f911e3b4ed080027cbdf2a in the previous
example).
Name Type Example
None
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/
Reason Example Error String
Invalid user id User not foundCreate a new user. The API user should have SEC_ADMIN privileges to create new users.
Method URI
POST v4/users/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 Sullyemail 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.
Name Type Example
result string successThere 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 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.
Method URI
PATCH v4/users/<userid>/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.
Name Type Example
Result string success
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 an existing user. This method may only be used by API users with SEC_ADMIN privileges.
Method URI
DELETE v4/users/<userid>/<userid> is an id of a user received
from a List Users operation.
Name Type Example
result string successReason Example Error String
Invalid user id User not foundUser not SEC_ADMIN User has insufficient privilegeChange default values of attributes for new users.
Method URI
PATCH v4/users/| Name | Type | Example |
|---|---|---|
authentication |
string | Local or RADIUS |
| password_expiry | integer | 60 |
| max_failed_logins | integer | 5 |
| min_passwd_length | integer | 8 |
Name Type Example
result string successReason Example Error String
Invalid authentication-type Authentication type: LDAP not supported
List the groups in the system. An 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.
Method URI
GET v4/groups/None
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.
Reason Example Error String
Invalid token Invalid or expired session; please loginRetrieve 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.
Method URI
GET v4/groups/<groupid>/
<groupid> is an id retrieved from the List Groups
operation.
NoneName 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.
Reason Example Error String
Invalid group id Group not foundCreate a new group. This method may be used only by API users with SEC_ADMIN privileges.
Method URI
POST v4/groups/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 or DOMAIN_ADMIN.
Name Type Example
result string success
There may be several validation errors. A few of them are given below.
Reason Example Error String
Groupname already exists name: Domain Admin Group exists.
Please enter a different Groupname
Edit an existing group. Only API users with SEC_ADMIN privileges may use this method to change group attributes.
Method URI
PATCH v4/groups/<groupid>/<groupid> is an id of a group retrieved from the
List Groups operation.
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.
Name Type Example
result string successReason Example Error String
Non-SEC_ADMIN user User has insufficient privilegesDelete an existing group. This method may be used only by 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.
Method URI
DELETE v4/groups/<groupid>/<groupid>is an id of a group retrieved from the
List Groups operation.
None
Name Type Example
result string successReason Example Error String
Invalid group id Group not found
User not SEC_ADMIN User has insufficient privileges
Group owns resources Group not empty
The API provides methods to administer the KeyControl domain.
List all the domains in the system.
Method URI
GET v4/domains/None
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
Reason Example Error String
Invalid token Invalid or expired session; please login
Retrieve the attributes of a domain.
Method URI
GET v4/domains/<domainid>/<domainid> is an id of a domain retrieved from the
List Domains operation.
None
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/
Reason Example Error String
Invalid domain id Domain not found
Invalid token Invalid or expired session; please login
Change the attributes of a KeyControl Domain.
Method URI
PATCH v4/domains/<domainid>/<domainid> is an id retrieved from a List Domains
operation (213f965193f911e3b4ed080027cbdf2a in the previous
example).
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
Reason Example Error String
Invalid domain id Domain not found
Invalid token Invalid or expired session; please login
Change the description attribute of a KeyControl server.
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.
Name Type Example
desc string Initial KeyControl Servers
Name Type Example
result string successReason Example Error String
Invalid server id Server not found
Invalid token Invalid or expired session; please login
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.
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.
Reason Example Error String
Invalid server id Server not found
Invalid token Invalid or expired session; please login
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.
Any authenticated user can issue this request. Only the Cloud VM Sets that 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.
Method URI
GET v4/cvmsets/
None
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/
Reason Example Error String
Invalid token Invalid or expired session; please login
Retrieve the attributes of a Cloud VM Set.
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.
None
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 lists
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/
Reason Example Error String
Invalid cvmset id Cloud VM Set not found
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.
Method URI
POST v4/cvmsets/
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, and rekey_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 an existing Cloud VM Set. The API user must belong to the group that 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.
Method URI
GET v4/cvmsets/<cvmsetid>/<cvmsetid> is an id of a Cloud VM Set retrieved from
a List Cloud VM Sets operation.
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.
Name Type Example
result string successReason Example Error Strin
Invalid group Group not found, or admin is not a member
Delete unused certificate in a Cloud VM Set.
Method URIDELETE 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.
None
Name Type Example
result string successReason Example Error String
Invalid certificate id Certificate not foundDelete an existing Cloud VM Set. The API user must belong to the group that owns this Cloud VM Set. Cloud VM Sets that contain VMs cannot be deleted. In order to delete such Cloud VM Sets, the VMs they contain must be removed first.
Method URI
DELETE v4/cvmsets/<cvmsetid>/
<cvmsetid> is an id of a Cloud VM Set retrieved from
a List Cloud VM Sets operation.
None
Name Type Example
result string successReason Example Error String
Invalid group id Cloud VM Set not found
Cloud VM Set contains VMs Cloud VM Set not empty
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
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.
Reason Example Error String
Invalid cvmset id Cloud VM Set not found
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.
Method URI
PATCH v4/keyids/<keyid>/<keyid> is the id of a KeyID retrieved from a Cloud
VM Set Details operation.
Name Type Example
expires string NEVER, 12/31/2015
onexpiry string NO_USE, SHRED
Name Type Example
result string successReason Example Error String
Invalid key id KeyID not foundRevoke a KeyID of a Cloud VM Set.
Method URI
POST v4/keyids/<keyid>/operation/<keyid> is an id of a KeyID retrieved from a Cloud VM
Set Details Operation.
Name Type Example
operation string revokeThe operation parameter has to be set to revoke.
Name Type Example
result string successReason Example Error String
Invalid key id KeyID not foundUnrevoke the KeyID of a Cloud VM Set.
Method URI
POST v4/keyids/<keyid>/operation/<keyid> is the id of a KeyID retrieved from a Cloud
VM Set Details operation.
Name Type Example
operation string unrevoke
The operation parameter has to be set to unrevoke.
Name Type Example
result string successReason Example Error String
Invalid key id KeyID not foundA Cloud VM is a machine, usually virtual, which contains a running instance of the HyTrust DataControl Policy Agent. It may have one or more disks protected by the HyTrust system.
Retrieve the attributes of a Cloud VM.
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.
None
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 86400os 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.
Reason Example Error String
Invalid cvm id Cloud VM not foundEdit a cloud VM.
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.
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, grace_period and rekey_interval attributes are specified in seconds, and rekey_bucket is an integer.
Name Type Example
result string success
There may be several validation errors. A few of them are given below.
Reason Example Error String
Invalid cvm id Cloud VM not foundCreate a “set mapping” task on a 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 idCloud VM Set not foundCreate a certificate for a new Cloud VM to be created within a Cloud VM Set.
Method URI
POST v4/cvmsets/<cvmsetid>/<cvmsetid> is an id of a Cloud VM Set retrieved from
a List Cloud VM Sets operation.
Name Type Example
passphrase string passphraseThe expires attribute should be specified in MM/DD/YYYY format.
Name Type Example
result string success
cvmid string bf5283f813a811e3b3c 308002778562f
certificate string /v4/certificates/ 9ea3f1ba949111e 3b4ed080027cbdf2a/
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).
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.
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.
Name Type Example
result string successReason Example Error String
Invalid cvm id Cloud VM Set not foundClone 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.
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.
Name Type Example
Operation string clonepassphrase string thisisasamplepassphrase
expiration string 12/05/2015
The operation parameter has to be set to clone.
Name Type Example
result string successReason Example Error String
Invalid cvm id Cloud VM not foundRemove 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.
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.
None
Name Type Example
Result string successReason Example Error String
Invalid cvm id Cloud VM not foundAuthenticate 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.
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.
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.
Name Type Example
result string successReason Example Error String
Invalid cvm id Cloud VM not foundRevoke 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.
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.
Name Type Example
operation string revokepassphrase string thisissamplephraseThe operation parameter has to be set to revoke.
Name Type Example
result string successReason Example Error String
Invalid cvm id Cloud VM not foundRetrieve list of tasks for a Cloud VM.
Method URI
GET v4/cvms/<cvmid>/tasks/
<cvmid> is an id retrieved from a Cloud VM Set Details operation.
None
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
Retrieve details of a disk on a Cloud VM. The disk should have been placed under HyTrust management.
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.
None
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.
Reason Example Error String
Invalid disk id Device not foundAdd task to encrypt / rekey / decrypt a specific disk on a Cloud VM.
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.
Name Type Example
operation string encrypt/rekey/decryptThe operation parameter has to be set to revoke.
Name Type Example
result string successReason Example Error String
Invalid disk id Device not foundRevoke 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.
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.
Name Type Example
Operation string revoke
The operation parameter has to be set to revoke.
Name Type Example
result string success
Reason Example Error String
Invalid disk id Device not found
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.
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.
Name Type Example
operation string unrevoke
The operation parameter has to be set to unrevoke.
Name Type Example
result string success
Reason Example Error String
Invalid disk id Device not found
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.
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.
Name Type Example
expires string 12/05/2015
onexpiry string NO_USE, SHRED
The expires attribute should be specified in MM/DD/YYYY format.
Name Type Example
result string success
Reason Example Error String
Invalid disk id Device not found
Invalid expiration Please enter a valid expiration date.
Change global settings, such as the default heartbeat interval and
grace_period.
Method URI
PATCH v4/kc/
Name Type Example
heartbeat integer 20
grace_period integer 300
The heartbeat and grace_period attributes are specified in
seconds.
Name Type Example
name string successReason Example Error String
Values beyond range Heartbeat interval too highDisplay the most recent Alert.
Method URI
GET v4/alerts/None
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 an Alert message.
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.
None
Name Type Example
result string successReason Example Error String
Invalid alert id Alert not foundcvm.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'
Reason Example Error String
Invalid command Invalid Commandcurl Commands
Tip: If the jq command is installed, pipe the output of curl into jq '.' to get the formatted output.
Login.
$ curl -s -k -d "username=secroot&password=mypassword" https://kc1/3.0/kc/
{
"result": "success",
"access_token": "c2Vjcm9vdA-1399191404-6c652fbbf2a4c087bb2ffb517773690a461d0620eedc71f594f0b1bf27648cc4"
}
$ ACCESS_TOKEN=$(curl -s -k -d "username=secroot&password=mypassword" https://kc1/3.0/kc/|awk -F\" '{print $4}')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"
}