Scripting Operations Using `hicli`

Introduction

This chapter describes hicli, which can be used for managing operations between the KeyControl cluster and a HyTrust DataControl Policy Agent (Policy Agent) present in Linux and Windows virtual machines. hicli uses a combination of the KeyControl REST APIs to communicate with KeyControl and SSH to invoke hcl commands on Windows and Linux VMs.

The Policy Agent provides for encryption of devices within Linux and Windows virtual machines. The management of keys and the administration of the Policy Agent is through a KeyControl cluster. Administration can take place solely through the webGUI, through the RESTful APIs or using the hicli command.

The following figure shows the servers that are involved:

We will be operating with one or more clustered KeyControl nodes, a number of Linux or Windows VMs and the API Server, a server from which hicli will be invoked. This can be any UNIX-like server including Linux, BSD variants, OS/X and so on.

NOTE - to use hicli with Windows, we need an SSH server, which is not available on Windows by default. Please install a tool such as cygwin/SSH or puTTY.

Installation and Configuration

The first step is to download the API bundle which is included with the HyTrust Policy Agent software. Navigate to the Cloud tab and select Download Policy Agent, as shown below:

You will get a file called hcs-client-agent.zip, which contains the Policy Agent software for Windows and Linux as well as hcs-api-3.3.tgz, the HyTrust API package.

Installation is very straightforward. Simply navigate to a directory where you wish to install the package and untar it as follows:

$ cd ~
$ tar xvfz hcs-api-3.3.tgz

x hcs-api/
x hcs-api/hclcomm.py
x hcs-api/kpsapi.py
x hcs-api/docopt.py
x hcs-api/hicli

After unpacking the software, you need to set up PYTHONPATH to point to the new directory and modify your PATH so that the shell can reference the hicli program. For example, if the install location is /Users/spate, the environment variables need to be set up as follows:

$ export PYTHONPATH=$PYTHONPATH:/Users/spate/hcs-api
$ export PATH=$PATH:/Users/spate/hcs-api

The next step is to set up a configuration file called ~/.hicli/.cfg. This should contain information about the virtual machines to be managed. Here is an example of such a configuration file that contains two Linux VMs:

{
    "cvmlist":  {
          "ubuntu10.04": { "host":"192.168.140.129", "port":"22", "user":"root"},
          "ubuntu12.10": { "host":"192.168.140.130", "port":"22", "user":"root"}
    }
}

To add a new VM to the list, just add another entry. For example:

{
    "cvmlist":  {
          "ubuntu10.04": { "host":"192.168.140.129", "port":"22", "user":"root"},
          "ubuntu12.10": { "host":"192.168.140.130", "port":"22", "user":"root"},
          "ubuntu13.04": { "host":"192.168.140.131", "port":"22", "user":"root"}
    }
}

Note that the number and location of curly brackets is important.

By default, the hicli.cfg file is used to resolve VM names. If no entries are found, DNS is used to resolve the VM names.

Once you have everything in place, run the hicli command and you should see a comprehensive listing of the command and its options.

To set up SSH communication on each Linux or Windows host, generate an SSH key pair for the root user as follows and copy the public key to the API server (in this case 10.0.1.9):

$ cd ~/.ssh
$ ssh-keygen -t dsa
$ scp id_dsa.pub spate@10.0.1.9:~/.ssh/id_dsa.pub.vm_name

and on the API server:

$  cd ~/.ssh
$  cat id_dsa.pub.vm_name >> authorized_keys

Make sure that:

You enable root login over SSH to the VM.
Turn off SSH warnings.

To test that SSH access is working between your API server and your VM, run a command such as follows:


$ ssh root@192.168.140.129 hostname
ubuntu13.04

In this case, the server returned ubuntu13.04.

How to use the API

The hicli command is at the heart of the system. It's a Python executable that lets you communicate with both the KeyControl cluster and the VMs you wish to manage. It can be invoked from any scripting language, compiled binary or can be run from the command line.

The APIs are broken down in to the following categories:

User and group administration.
Cloud VM Set management.
VM management.

There are certain user and group operations that only KeyControl Security Administrators can call, but anyone with Cloud Administration privileges can perform the other operations. The following table lists the hicli operations and which administrative privilege is required to perform each task.

`hicli` command	Sub-command	Accessibility
group	list	SEC_ADMIN sees all groups. Others see the groups of which they are members.
	new	SEC_ADMIN
	detail	SEC_ADMIN sees all groups. Others can see groups of which they are members..
	rm	SEC_ADMIN
	set `description`	SEC_ADMIN
	add_user	SEC_ADMIN
	rm_user	SEC_ADMIN
	set name	SEC_ADMIN
user	list	SEC_ADMIN sees all users. Others see users of groups to which they belong.
	new	SEC_ADMIN
	set email	SEC_ADMIN, and the user himself or herself
	set password	SEC_ADMIN, and user himself or herself
	set full_name	SEC_ADMIN, and user himself or herself
	set account_state	SEC_ADMIN
	set roles	SEC_ADMIN
	detail	SEC_ADMIN, and user himself or herself
	rm	SEC_ADMIN
	set password_expiration	SEC_ADMIN
	set account_expiration	SEC_ADMIN
	set groups	SEC_ADMIN
	defaults	SEC_ADMIN
domain	detail	DOMAIN_ADMIN
	set description	DOMAIN_ADMIN
	set allow_reconnect	DOMAIN_ADMIN
	set require_passphrase	DOMAIN_ADMIN
	set hide_passphrase	DOMAIN_ADMIN
	set check_hardware_id	DOMAIN_ADMIN
	server detail	DOMAIN_ADMIN
	server set description	DOMAIN_ADMIN
	server auth	DOMAIN_ADMIN
cvmset	list	CLOUD_ADMIN, list of cvmsets belonging to groups of which he or she is a member
	new	CLOUD_ADMIN, must belong to group specified, which must be a CLOUD_ADMIN-type group
	detail	CLOUD_ADMIN, any cvmset listed by `list`
	`list_tasks`	CLOUD_ADMIN, any cvmset listed by `list`
	rm	CLOUD_ADMIN, any cvmset listed by `list`, should be empty
	set description	CLOUD_ADMIN, any cvmset listed by list
	set group	CLOUD_ADMIN, to any group he or she is a member of, which is of type CLOUD_ADMIN
	`set rekey`	CLOUD_ADMIN, any cvmset listed by `list`
	`set rekeybucket`	CLOUD_ADMIN, any cvmset listed by `list`
	set name	CLOUD_ADMIN, any cvmset listed by list
	set heartbeat	CLOUD_ADMIN, any cvmset listed by list
	set grace	CLOUD_ADMIN, any cvmset listed by list
	cert rm	CLOUD_ADMIN
	keyid add	GUEST_ADMIN
	keyid set expiration	CLOUD_ADMIN
	keyid set onexpiry	CLOUD_ADMIN
	keyid revoke	CLOUD_ADMIN
	keyid unrevoke	CLOUD_ADMIN
	`keyid` rm	GUEST_ADMIN
cvm	list	CLOUD_ADMIN, all cvms belonging to currently selected cvmset
	new	CLOUD_ADMIN, new cvm part of current cvmset
	rm	CLOUD_ADMIN
	status	CLOUD_ADMIN
	revoke	CLOUD_ADMIN
	reauth	CLOUD_ADMIN
	set description	CLOUD_ADMIN
	set heartbeat	CLOUD_ADMIN
	set grace	CLOUD_ADMIN
	set reauth	CLOUD_ADMIN
	set rekey	CLOUD_ADMIN
	`list_tasks`	CLOUD_ADMIN
	encrypt task	CLOUD_ADMIN
	rekey_task	CLOUD_ADMIN
	decrypt_task	CLOUD_ADMIN
	set_mapping	CLOUD_ADMIN
	add_disk	CLOUD_ADMIN
	revoke_disk	CLOUD_ADMIN
	unrevoke_disk	CLOUD_ADMIN
	rm_disk	CLOUD_ADMIN
	renew clone	CLOUD_ADMIN
	detail	CLOUD_ADMIN
	detail_disk	CLOUD_ADMIN
	set_disk expiration	CLOUD_ADMIN
	rekey_disk	GUEST_ADMIN
	s3 add_file	GUEST_ADMIN
	s3 rm_file	GUEST_ADMIN
	s3 get_file	GUEST_ADMIN
s3	set aws_access_key_id	GUEST_ADMIN
	set aws_secret_access_key	GUEST_ADMIN
	create_bucket	GUEST_ADMIN
	delete_bucket	GUEST_ADMIN
	list_bucket	GUEST_ADMIN
alert	list	User sees his or her alerts
alert	rm	User removes own alert
global	set heartbeat	SEC_ADMIN
	set grace	SEC_ADMIN

Selecting a KeyControl node

KeyControl nodes are typically clustered. For example, consider the following figure that shows a KeyControl cluster with three nodes:

Before invoking hicli commands, you must first select a KeyControl node to talk to. In our example above, it really does not matter which KeyControl node is chosen. Since the three nodes operate in an active-active cluster, any change to any node is immediately reflected on all nodes in the cluster.

You select a node as follows:

$ hicli kc select kc-1
$ hicli kc 
Current KeyControl: kc-1
$ hicli kc select 192.168.140.152
$ hicli kc 
Current KeyControl: 192.168.140.152

DNS is used to resolve hostnames so either be sure to set up DNS for all your KeyControl nodes or use IP addresses as shown above.

User and Group Management

The simpler level of these commands is also available through the webGUI. See Actions You Can Take by Clicking the Security Icon

Many user and group management functions can only be performed by Security Administrators. To get going, let's start with some simple commands that select one of the KeyControl nodes, login in as secroot, list users and groups, and then create a new user.

$ hicli kc select kc-1
$ hicli kc
Current KeyControl: kc-1
$ hicli user login secroot 
Password for secroot: ********
$ hicli user list
Username    Full Name               Privileges
---------------------------------------------------
secroot     Security Administrator  SEC_ADMIN,VMSET_ADMIN,DOMAIN_ADMIN,CLOUD_ADMIN
$ hicli group list
Group Name              Description                                 Members
---------------------------------------------------
Cloud Admin Group       Default Group for Administering Cloud VMs   secroot
KeyControl Admin Group  Default Group for Administering KeyControl Domain secroot
Storage Admin Group     Default Group for Administering Domains     secroot
VM Set Admin Group      Default Group for Administering VM Sets     secroot
$ hicli user new spate --email=spate@me.com --password=mypasswd236 \
     --roles=CLOUD_ADMIN --full_name="Steve Pate" \
     --groups="Cloud Admin Group""Security Admin Group" "Domain Admin Group"
$  hicli user list
Username    Full Name               Privileges
---------------------------------------------------
secroot     Security Administrator  SEC_ADMIN,VMSET_ADMIN,DOMAIN_ADMIN,CLOUD_ADMIN
spate       Steve Pate              CLOUD_ADMIN

If there is more than one KeyControl node in the cluster, you can select any node. As soon as changes are made on one node, they are automatically reflected on all other nodes. In the example here, we have selected kc-1.

Since we are creating a new user, we must first log on as a Security Administrator. In the example here, we are prompted for the password. Alternatively, you can specify the password on the command line using --password=. Login sessions are valid for one hour past the last command typed. We recommend that sets of commands be preceded by a login call and followed by a logout call.

Once logged on, we list the current set of users (only secroot), list the administration groups, create a new user called spate with CLOUD_ADMIN privileges and then list the users once more.

In order to check the progress of your API calls, log on to the webGUI and view the results.

Logging in / Viewing users

To login into the KeyControl, invoke hicli as follows:

$ hicli user login secroot
Password for secroot: ********

If you don't specify the --password option you will be prompted for it on the command line.

After logging in, a user context is set such that all subsequent operations will be performed as that user. To show which user is currently logged on, run the following command

$ hicli userCurrently logged-on user: secroot

You can also request details about yourself as follows:


$ hicli user detail secroot
Login name               | secroot
Status                   | Active
Full name                | Security Administrator
Email                    | spate@me.com
Last login               | 2014-06-13 10:22:15 PDT
Password Expiration      | Never
Account Expiration       | Never
Failed logins            | 0
Privileges               | SEC_ADMIN,VMSET_ADMIN,DOMAIN_ADMIN,CLOUD_ADMIN
Groups                   | Storage Admin Group,KeyControl Admin Group,\
                         | VM Set Admin Group,Cloud Admin Group

$ hicli user login spate 
Password for spate: ********

$ hicli user detail spate 
                        
Login name               | spate
Status                   | Active
Full name                | Steve Pate
Email                   | spate@me.com
Last login               | 2014-06-13 10:21:03 PDT
Password Expiration      | Never
Account Expiration       | 06/09/2015
Failed logins            | 0
Privileges               | CLOUD_ADMIN
Groups                   | Cloud Admin Group

Defaults for new users may be set. For example:

                        
$ hicli user defaults --authentication=local --password_expiry=60 \
     --max_failed_logins=4 --min_passwd_length=12

Once you have finished a current session, you can simply log out as follows:

$ hicli user
Currently logged-on user: spate
$ hicli user logout
$ hicli user  
Login first

Group Management

Cloud VM Sets are assigned to specific Cloud Administration Groups. Thus, if Jim and Bob are members of the "Department A" Cloud Administration group, and Jim creates a cloud VM Set called Amazon AWS within this group, the Amazon AWS Cloud VM Set will also be visible by Bob. Also, consider the following figure:

On the left of the figure, Jim and Bob are members of the "Department A" Cloud Admin group. Between them, they have created two Cloud VM Sets, Amazon AWS and vCloud Air. Jon is a member of the "Department B" Cloud Admin group and has created one Cloud VM Set called Rackspace. It is not possible for Jim and Bob to see Jon or his Cloud VM Sets. It is also not possible for Jon to see Jim or Bob or their Cloud VM Sets.

Operations that manipulate groups can only be performed by Security Administrators. To list the current set of groups:

$ hicli group list  
Group Name            	 Description                                       Members
---------------------------------------------------------------------------------
Cloud Admin Group     	 Default Group for Administering Cloud VMs         secroot,spate
KeyControl Admin Group  Default Group for Administering KeyControl Domain secroot
Domain Admin Group   	 Default Group for Administering Domains           secroot

To display more detailed information about a specific group:

$ hicli group detail "Cloud Admin Group"
Name                    Cloud Admin Group
Description             Default Group for Administering Cloud VMs
Type                    CLOUD_ADMIN
Number of objects       0
Users                   secroot,spate

Other group operations allow Security Admins to add/remove users from a group or create new groups / remove existing groups. The set description sub-command allows you to change the description of the group.

For group removal, one of the common problems is that if you remove all the users from a group, group removal fails because if the group holds one or more Cloud VM Sets. The only way to get out of this situation is to add a user (usually a Security Admin) to this empty-of-users group, remove the Cloud VM Sets, and then remove the group.

Creating new Users by Using `hicli`

Creation of users can only be performed by Security Administrators. Shown below is an example of a call to create a new user called spate with CLOUD_ADMIN privileges:

$ hicli user new spate --email=spate@me.com --password=mypasswd236 \ --roles=CLOUD_ADMIN \\ --full_name="Steve Pate" --groups="Cloud Admin Group"

As you try out commands, you can always view the result graphically by going to the webGUI. For example, following the above call, we can view our new user as shown in the following screenshot from the Security Icon's choices:

Passwords must be at least 8 characters in length. Roles are a comma-separated list of administrative types. The roles are:

SEC_ADMIN - Security Administration
DOMAIN_ADMIN - Domain Administration
CLOUD_ADMIN - Cloud Administration

Examples of combining roles could be:

--roles=SEC_ADMIN,CLOUD_ADMIN
--roles=DOMAIN_ADMIN,CLOUD_ADMIN
--roles=SEC_ADMIN,DOMAIN_ADMIN,CLOUD_ADMIN

The --groups option is a comma-separated list of Cloud Administration groups. For example, looking at the list of available groups:

                        
$ hicli group list
                        
Group Name            Description                                       Members
---------------------------------------------------
Cloud Admin Group     Default Group for Administering Cloud VMs         secroot,spate
KeyControl Admin Group Default Group for Administering KeyControl Domain        secroot
Domain Admin Group    Default Group for Administering Domains           secroot

Assuming we want to create a new user called spate and have this user be a member of new groups called "Acme Finance" and "Acme Legal", we would make the hicli calls as follows:


$ hicli group new "Acme Finance"
$ hicli group new "Acme Legal"
$ hicli user new spate --email=spate@me.com --password=mypasswd236 \
		--roles=CLOUD_ADMIN --full_name="Steve Pate" \
		--groups="Acme Finance","Acme Legal"
$ hicli group list
Group Name            		Description                                       Members
---------------------------------------------------
Acme Finance          		Acme Finance                                      spate
Acme Legal            		Acme Legal                                        spate
Cloud Admin Group     		Default Group for Administering Cloud VMs         secroot
KeyControl Admin Group       	Default Group for Administering KeyControl Domain secroot
Domain Admin Group   		Default Group for Administering Domains           secroot

Modifying User Information

For existing users, the following properties can be changed using the hicli user set command:

--email=<email>
--password=<passwd>
--full_name=<full_name>
--account_state=<active|disabled>
--roles=<privlist>
--password_expiration=<date>
--account_expiration=<date>

Note that non-Security Admins can only change email, full name and password.

As an example, consider the following user:

$ hicli user detail spate
Login name               | spate
Status                   | Active
Full name                | Steve Pate
Email                    | spate@me.com
Last login               | 2014-06-13 10:21:03 PDT
Password Expiration      | Never
Account Expiration       | 06/09/2015
Failed logins            | 0
Privileges               | CLOUD_ADMIN
Groups                   | Cloud Admin Group

The following call adds Security Admin privileges and changes the email:

$ hicli user set spate --roles=SEC_ADMIN,CLOUD_ADMIN --email=spate@hytrust.com
$ hicli user detail spate
Login name               | spate
Status                   | Active
Full name                | Steve Pate
Email                    | spate@hytrust.com
Last login               | 2014-06-13 10:21:03 PDT
Password Expiration      | Never
Account Expiration       | 06/09/2015
Failed logins            | 0
Privileges               | SEC_ADMIN,CLOUD_ADMIN
Groups                   | Cloud Admin Group

Most parameters are self explanatory. For information about combining roles, review the section on creating new users above.

Please note that you must specify all privileges that you wish the user to have. If the user already has Security Administration privileges and you make the following call:

$ hicli user set spate --roles=CLOUD_ADMIN

the user will now only have Cloud Admin privileges.

Removing Users

Only Security Administrators can remove users. In the example below, we display the current list of users and then remove the user spate. We then re-run the command to confirm that the removal took place. Note that you need to specify the username.

                      
$ hicli user list
Username    Full Name               Privileges
---------------------------------------------------
secroot     Security Administrator  SEC_ADMIN
spate       Steve Pate              CLOUD_ADMIN
$ hicli user rm spate
$ hicli user list
Username    Full Name               Privileges
---------------------------------------------------
secroot     Security Administrator  SEC_ADMIN

Note that all objects (Cloud VM Sets and VMs) are owned by administrative groups and not by the users themselves. Thus, if you remove a user, the object will stay intact.

Managing Domains

The table below shows the operations that can be performed on Domains:

`hicli` Command	Description
domain detail	Display information about a domain
`domain list`	Display all domains
domain select	Select a domain
domain set allow_reconnect	Display information about a domain
domain set check_hardware_id	Make sure that the hardware ID is checked
domain set description	Give the domain a new description
domain set hide_passphrase	Don't display the passphrase when adding a new node
domain set require_passphrase	Require a passphrase when adding a new node
`server auth`	Display information about a domain
`server detail`	Display detailed information about a server
`server set description`	Give a server within a domain a new description

Examples of how to manage domains are shown below. First, let's list the current set of domains:

$ hicli domain list
Domain                  Admin Group                     Servers   Status
---------------------------------------------------
KeyControl Domain       KeyControl Admin Group          1         Healthy
Storage Domain          Storage Admin Group             0         Healthy

And now get details about a specific domain:


$ hicli domain detail "KeyControl Domain"
Name			       KeyControl Domain
Status				Healthy
Group				KeyControl Admin Group
Description			Domain of Clustered KeyControl Servers
Allow reconnect		Yes
Passphrase required		Yes
Passphrase hidden		No
Check hardware id		Yes
Server Count			2
Server Names			kc1.hytrust.com,kc2.hytrust.com

To set KeyControl domain attributes:

$ hicli domain set "KeyControl Domain" --description="New description" \
    --allow_reconnect=yes --require_passphrase=yes \
    --hide_passphrase=no --check_hardware_id=yes

For KeyControl server operations we need to select a domain first:

$ hicli domain select "KeyControl Domain"

To show the current domain:


$ hicli domain
KeyControl Domain

Get KeyControl server details:


$ hicli server detail kc1.hytrust.com
Name		       kc1.hytrust.com
Status			Online
IP Address		192.168.140.151
Authenticated		Yes
Description		Primary KeyControl Server

Change KeyControl server description:


$ hicli server set kc1.hytrust.com --description="New description"

Authenticate KeyControl server:


$ hicli server auth kc1.hytrust.com

Managing Cloud VM Sets

The table below shows the Cloud VM Set operations that can be performed by individual Cloud Administrators:

`hicli` `C`ommand	Description
`cvmset`	Display current Cloud VM Set
`cvmset cert rm`	Remove an unused certificate
cvmset detail	Display details about the specified Cloud VM Set
cvmset keyid add	Create a KeyID
cvmset keyid keyid rm	Remove a KeyID
cvmset keyid revoke	Revoke access to a KeyID
cvmset keyid set expiration	Set the expiration date for a KeyID
cvmset keyid set onexpiry	When a KeyID expires, set the expiration policy
cvmset keyid unrevoke	Unrevoke access to a KeyID
cvmset list	List all Cloud VM Sets
`cvmset list_tasks`	Display list of tasks for the specified Cloud VM Set
cvmset new	Create a new Cloud VM Set
`cvmset select`	Select a Cloud VM Set
cvmset set	Change properties
`cvmset set grace`	Set the value for the grace period in seconds (default is 1 day)
`cvmset set heartbeat`	Set the value for the heartbeat in seconds (default is 5 minutes, or 300 seconds)
`cvmset set name`	Change the name of the Cloud VM Set
`cvmset set rekey`	Set the value for the automatic rekey of disks interval in days/months/years (defaults to 0 which means not set)
`cvmset set rekeybucket`	Set the value for the rekeybucket for cvmset which controls the max number of auto rekeys that can be processed in parallel. Auto rekey is triggered when rekey interval expires. This value defaults to 1.

Cloud VM Sets are managed by any administrator with CLOUD_ADMIN privileges.

For example, consider the following list of Cloud VM Sets for user spate. There are three Cloud VM Sets that appear when you click the Cloud icon.

Cloud VM Sets can be listed using hicli as follows:

$ hicli cvmset list
Cloud VM Set Name     Admin Group           Description
---------------------------------------------------
Amazon AWS            Cloud Admin Group     VMs sets sited on Amazon Servers
vCloud Air            Cloud Admin Group     VMs sets deployed on vCloud Air \                   servers
Sales Staff           Cloud Admin Group     Sales staff worldwide

Below, we create a new Cloud VM Set called Rackspace then check to make sure that it has been created:


$ hicli cvmset new "Rackspace" "Cloud Admin Group" --description="VMs in Rackspace"
$ hicli cvmset list  | grep Rackspace
Rackspace             Cloud Admin Group     VMs in Rackspace

You can view details about an existing Cloud VM Set as follows:


$ hicli cvmset detail "Amazon EC2"
                        
Name                    Amazon EC2
Admin Group             Cloud Admin Group
Description             VMs running in Amazon Ubuntu-10.04,linux-12.10
Unused Certificate Ids  4c81a042a60b11e2b5cf000c29ed8423
KeyIDs                  aws_key,test_key

In this example, there are two VMs associated with this Cloud VM Set.

To change properties use the hicli cvmset set command. For example:

$ hicli cvmset set "Amazon EC2" --description="Amazon AWS"

More attributes (default Heartbeat and Grace Period) may be specified using Cloud VM Set creation and Modification:

$ hicli cvmset new "Rackspace" "Cloud Admin Group" \
    --description="VMs in Rackspace" --heartbeat=60 --grace=600
$ hicli cvmset set "Rackspace" --group="Cloud Admin Group" \
    --description="Rackspace" --heartbeat=60 --grace=600

For Certificate and KeyID operations, a Cloud VM Set has to be selected:


$ hicli cvmset select "Amazon EC2"

Show Unused Certificate description:


$ hicli cvmset cert detail 4c81a042a60b11e2b5cf000c29ed8423
Description             Created by spate at 2013-04-15 20:30:23

Delete Unused Certificate:


$ hicli cvmset cert rm 4c81a042a60b11e2b5cf000c29ed8423

Create a KeyID:


$ hicli cvmset keyid add aws_key -d "Key for Amazon"

Show KeyID details:


$ hicli cvmset keyid detail aws_key
Description		Key for secure migration
Algorithm		AES-256
Expires			Never
Onexpiry		Shred
Status			Active

Change KeyID attributes:

$ hicli cvmset keyid set aws_key --expiration="12/31/2015" --onexpiry=no_use

Revoke a KeyID:

$ hicli cvmset keyid revoke aws_key

Unrevoke a KeyID:


$ hicli cvmset keyid unrevoke aws_key

Remove a KeyID:


$ hicli cvmset keyid rm aws_key

Managing Cloud VMs

The table below shows the Cloud VM operations that can be performed. All operations can be performed by Cloud Administrators.

`hicli` `Command`	Description
cvm add_disk	Add a disk to be encrypted
`cvm decrypt_task`	Perform decryption on specified disk
cvm detail	Get the status of the VM (KeyControl perspective)
cvm detail_disk	Display details about a specified disk
cvm encrypt_task	Perform encryption on specified disk
cvm list	List the VMs in the current Cloud VM Set
`cvm list_tasks`	Display list of tasks for the specified VM
cvm new	Add a new VM
cvm reauth	Re-authorize a VM
cvm rekey_task	Perform rekey on specified disk
cvm renew clone	Clone a VM certificate
cvm revoke	Revoke access to the VM and its devices
cvm revoke_disk	Revoke access to the specified disk
cvm rm	Remove a VM
cvm rm_disk	Remove a disk from HyTrust management
cvm s3 add_file	Add a file to an S3 bucket
cvm s3 get_file	Retrieve a file from an S3 bucket
cvm s3 rm_file	Remove a file from an S3 bucket
cvm set	Set properties of the VM
`cvm set rekey`	Set the value for the automatic rekey of disks interval in days/months/years (defaults to 0 which means not set)
cvm set_disk expiration	Set the expiration date for a disk
`cvm set_mapping`	Set KC mapping
cvm status	Get the status of the VM (as in `hcl status`)
cvm unrevoke_disk	Give permissions back to access the device

All of these operations are performed in the context of a Cloud VM Set. So, before invoking any of these commands, you need to set the Cloud VM Set first. Let's first look at the current Cloud VM Set:

$ hicli cvmset
Current Cloud VM Set: Amazon EC2

You can change the current Cloud VM Set as follows:


$ hicli cvmset select "Amazon AWS"
$ hicli cvmset 
Current Cloud VM Set: Amazon AWS

To list the VMs associated with a Cloud VM Set:

$  hicli cvm list
VM Name               Status
---------------------------------------------------
ubuntu-10.04          Online
ubuntu-12.10          Online

To request more information about a specific VM. There are two options. The first is equivalent to running hcl status on the VM. For example:

$ hicli cvm status ubuntu-12.10
                        
Host Status on ubuntu12.10
---------------------------------------------------
Summary
---------------------------------------------------
KeyControl: kc-1:443
KeyControl list: kc-1:443
Status: Connected

Registered Devices
---------------------------------------------------
Disk Name         Clear                             Cipher      Status
---------------------------------------------------
sdb2              /dev/mapper/clear_sdb2            AES-256     Attached
 '--> auto_attach=ENABLED, attach_handler=DEFAULT, detach_handler=DEFAULT
sdb1              /dev/mapper/clear_sdb1            AES-256     Attached
 '--> auto_attach=ENABLED, attach_handler=DEFAULT, detach_handler=DEFAULT
                        


                        
Available Devices
---------------------------------------------------
Disk Name           Device Node                     Size (in MB)
---------------------------------------------------
sde                 /dev/sde                        2048
sdd                 /dev/sdd                        2048
sdc                 /dev/sdc                        2048

Other Devices
---------------------------------------------------
Disk Name           Device Node                     Status
---------------------------------------------------
sda5                /dev/sda5                       Mounted (swap)
sda1                /dev/sda1                       Mounted (/)

And the second displays abbreviated information:

$ hicli cvm detail ubuntu-12.10
KeyControl Status for ubuntu12.10
---------------------------------------------------
Name                            ubuntu12.10
Status                          Online
Description
Cloud VM Set                    HCS
OS                              Linux ubuntu 2.7.32-38-generic #83-Ubuntu
				SMP Wed Jan 4 11:12:07 UTC 2014 x86_64 GNU/Linux
Agent version                   3.3
Valid till                      02/01/2015
Heartbeat (sec)                 10
Grace period (sec)              3600
Reauth on H/W signature change  Yes
Reauth on IP address change     Yes
Reauth on reboot                No

Disks:
sdb1                            ACTIVE
sdb2                            ACTIVE

Adding a new VM and adding devices to be encrypted is very straightforward, as the following script shows:

hicli user login spate --password=********
hicli cvmset set 'Amazon EC2'
hicli cvm new ubuntu10.04
hicli cvm ubuntu10.04 add_disk sdb1
hicli cvm ubuntu10.04 add_disk sdb2

We log on to the KeyControl as user spate. Next we select the Cloud VM Set into which we wish to place the VM. The new subcommand is used to register and authenticate the new VM. We then add two disks. Note that we are using the abbreviated names sdb1 and sdb2 in place of /dev/sdb1 and /dev/sdb2.

The hicli cvm new command involves calling the KeyControl to create and download a new certificate which is then copied to the VM. It then calls hcl register from the VM and completes authentication. The call to add_disk is the equivalent of hcl add, which adds and attaches the device including getting access to the key. Following the call to add_disk, the encrypted device is now ready to use.

NOTE - the Policy Agent software must be installed prior to adding the VM.

At this point, you can view the effects of your script through the webGUI, as shown in the following screen shot. Note that sdb1 appears as E: and sdb2 appears as F:, due to connectivity issues.

To undo the effects of the script above, to remove the devices and remove the VM, use the following script:

$ hicli cvmset select "Amazon EC2"
$ hicli cvm ubuntu-10.04 rm_disk sdb1
$ hicli cvm ubuntu-10.04 rm_disk sdb2
$ hicli cvm revoke ubuntu-10.04
$ hicli cvm rm ubuntu-10.04

At this point it will look like the original script was never run.

The revoke and unrevoke options allow you to forcibly remove access to clear-text data and then grant permissions back to a device. The following operation:

$ hicli cvm ubuntu-10.04 revoke_disk sdb2

is equivalent to selecting the Cloud Icon, choosing a virtual machine and disk, and then clicking the Actions button, and then Revoke Disk Access, as follows:

...while the following operation:

$ hicli cvm ubuntu-10.04 unrevoke_disk sdb2

...is equivalent to clicking Grant Disk Access next to a device in the webGUI as follows:

The revoke sub-command:

$ hicli cvm revoke ubuntu-10.04

...is equivalent to pressing the Actions button and then Revoke VM Authentication next to a device in the webGUI as follows:

The opposite operation is the reauth of the VM:

$ hicli cvm reauth ubuntu-10.04

This will perform the equivalent of running hcl auth on the command line of the VM and then typing the passphrase in the webGUI.

Some additional examples are shown below:

Renew the certificate of a Cloud VM:

$  hicli cvm renew ubuntu-12.10

Clone a Cloud VM:

$  hicli cvm clone ubuntu-12.10 ubuntu-clone

Get details of a disk:

$ hicli cvm ubuntu-12.10 detail_disk sdb1
                        
Name			sdb1
Mapped Device		clear_sdb1
Status			Active
Algorithm		AES-256
Expiration		Never
OnExpiry		Shred
Size (bytes)		104857600

Change disk attributes:

$ hicli cvm ubuntu-12.10 disk_set sdb1 --expiration="12/31/2015" --onexpiry=no_use

Rekey a disk:

$ hicli cvm ubuntu-12.10 disk_rekey sdb1

Encrypt a file:

$ hicli cvm ubuntu-12.10 encryptfile -k aws_key /tmp/files.zip

Decrypt a file:

$ hicli cvm ubuntu-12.10 decryptfile /tmp/files.zip.enc

Alerts

Get all alerts for the user:

$ hicli alert list
1 10/08/11 17:06:52 Account disabled for spate due to repeated failures
2 10/08/11 17:08:00 VM Set Admin Group group has been granted access to datastore dedup on

Get details of an alert:

$ hicli alert detail 1
ID          b62c3bb3954611e3bfe6080027cbdf2a
Message     Account disabled for spate due to repeated failures
Date        10/08/11 17:06:52

Delete an alert:

$ hicli alert rm b62c3bb3954611e3bfe6080027cbdf2a

Set global default settings:

$ hicli global set --heartbeat=60 --grace=600

Scripting Operations Using hicli