`hcl` Man Page

NAME

hcl - Encrypt disks, filesystems and files using HyTrust DataControl

SYNOPSIS

hcl [OPTIONS]

DESCRIPTION

The hcl command is used to manage encrypted disks, filesystems and files on Linux and Windows.

OPTIONS

The options are as follows:

General Status

status

Display the list of KeyControl cluster nodes that this VM can communicate with, the status of the connection and the list of encrypted folders/disks and available disks.

status [-g] (Linux only)

Displays partition information about the available disks showing the partition type and the existence of any disk GUID.

Registration

register [-c] [-h myname] [-d description] [-p certificate_password] [-o one_time_passphrase] kc_hostname[:port],kc_hostname2[:port2],... /path/to/cert.bin"

Registers the VM with a KeyControl cluster. This method requires you to authenticate the VM with KeyControl using a one-time passphrase. If you want to use simplified registration, see the "register -a" version of this command described below.

The -c option indicates the presence of a clone certificate so should only be specified if you are registering a clone VM.

The -h option allows you to give a name to the VM which will be visible in the webGUI as well as through APIs.

The -d option allows you to specify an optional description for the VM. This will also be visible in the webGUI as well as through APIs.

The -p option allows you to specify the password for the certificate if one was specified when the certificate was created in the KeyControl webGUI. If you omit this option and a password is required, you will be prompted to enter it.

The -o option allows you to enter a one-time passphrase that you can use to authenticate this VM in the KeyControl webGUI. If you do not specify the -o option, you will be prompted to enter it. This passphrase must contain at least 16 alphanumeric characters or hyphens. The one-time passphrase will be expired after 15 minutes.

"kc_hostname" is a comma-separated list of KeyControl cluster nodes and, optionally, port numbers. The default port is 443. To enable automatic failover, you should enter the IP address of every KeyControl node in the cluster. For example, if you have a three node cluster, you would enter

192.168.162.133,192.168.162.135,192.168.162.137.

Note that if you add or remove any nodes, you should run the "hcl updatekc" command to update this list. Alternatively, if you have set up a KeyControl mapping, you can enter a single IP address and then select a KeyControl mapping when prompted.

The final argument is the pathname to the certificate.

register -a [-c] [-h myname] [-d description] [-n mapping] [-N] [-u username [-s password] [-e certificate expiration] [-v vault_id] [-z cvmset] kc_hostname[:port],kc_hostname2[:port2],...

Registers the VM using simplified registration, with which you do not need to manually create a certificate and copy it to the VM or enter a one-time passphrase. You can quickly register and authenticate a VM by providing your KeyControl credentials, selecting the Cloud VM Set and optional KeyControl mapping.

The -c option allows you to register this VM as clone of the original VM.

The -h option allows you to give a name to the VM which will be visible in the webGUI as well as through APIs.

The -d option allows you to specify an optional description for the VM. This will also be visible in the webGUI as well as through APIs.

The -n option allows you to specify a KeyControl mapping for the VM. If KeyControl has mappings available for the specified Cloud Admin, and this option is omitted, the list of mappings will be displayed and you will be prompted to select one. If you choose to associate the VM with a mapping, the KeyControl list will be automatically updated when the VM heartbeats against the cluster.

The -N option allows you to skip KeyControl mapping for the VM. If this option is provided, the mapping list will not be displayed even if -n is omitted. If both -n and -N options are set, -n option will be ignored.

The -v option allows you to specify a Vault ID for the vault. If you do not specify a vault_id, you will be prompted to enter it.

The -z option allows you to specify the name of the Cloud VM Set to which the VM should be registered. If this option is omitted, you will be prompted to choose the Cloud VM Set from the list of available Cloud VM Sets.

The -e option allows you to specify the certificate expiration date using the format MM/DD/YYYY. For example, 12/25/2017. If an expiration date is not specified, the certificate will be valid for one year from the date of creation.

The -u and -s options allow you to specify a KeyControl user account name and password with Cloud Admin privileges. If you do not specify credentials, or if you specify the user name but not the password, you will be prompted to enter this information.

kc_hostname is a comma-separated list of KeyControl cluster nodes and, optionally, port numbers. The default port is 443. To enable failover, you should enter the IP address of every KeyControl node in the cluster. For example, if you have a three node cluster, you would enter

192.168.162.133,192.168.162.135,192.168.162.137.

Note that if you add or remove any nodes, you should run the "hcl updatekc" command to replace this list. Alternatively, if you have set up KeyControl mappings, you can enter a single IP address and then select a KeyControl mapping when prompted.

unregister [-y] [-a [-u username -p password]]

Unregisters an authenticated VM from KeyControl. If the VM is unregistered successfully, then the local state on the VM is cleaned up. All HyTrust configuration about all disks and folders is removed. This has the effect of uninstalling and re-installing the product and should be used with extreme caution.

When dealing with VM clones, Do Not use this command unless VM is registered as a clone (refer 'hcl register') to avoid any accidental data loss.

The -y option makes the command non-interactive.

The -a option allows you to unregister a VM that is currently registered but not authenticated with KeyControl VME Vault. This option requires your KeyControl VME Vault credentials.

The -u and -p options allow you to specify a KeyControl user account name and password with Cloud Admin privileges. If you do not specify the credentials, or if you specify the user name but not the password, you will be prompted to enter this information.

rename newname

Changes the registered name of the VM with KeyControl. If there is no VM called "newname" in the Cloud VM Set to which this VM belongs, the registered name of the VM will be changed to "newname".

KeyControl Management

updatekc kc_hostname[:port],kc_hostname2[:port2],...

Manually updates the list of KeyControl node IP addresses on the VM. Having the correct list of IP addresses enables automatic failover in case one of the nodes becomes unreachable.

192.168.162.133,192.168.162.135,192.168.162.137.

Note that if you add or remove any nodes, you should run the "hcl updatekc" command to replace this list. Alternatively, if you have set up a KeyControl mapping, you can enter a single IP address and then select a KeyControl mapping when prompted.

updatekc -a [-n mapping] [-u username [-s password]]

Queries KeyControl for the available KeyControl mappings and allows you to select the mapping you want to use on this VM. This allows you to change to a new mapping. This command requires KeyControl Cloud Admin credentials.

The Cloud Admin can maintain multiple KeyControl mappings in KeyControl. Each of these mappings is a list of KeyControl nodes. You can associate the VM with one of those mappings. If you do, the list of KeyControl nodes will be fetched from the KeyControl and updated automatically during each heartbeat.

You will be prompted to enter your Cloud Admin credentials to use this command.

The -u and -s options allow you to specify a KeyControl user account name and password with Cloud Admin privileges. If you do not specify the credentials, or if you specify the user name but not the password, you will be prompted to enter this information.

Policy Agent Certificate Management

updatecert [-p certificate_password] /path/to/cert.bin

Updates the certificate on the VM using a local copy of the certificate.

Certificates are valid for one year by default unless you changed the expiration date when the certificate was created. To maintain access to data you should create a new certificate prior to expiration, copy that certificate to the VM, and use the "hcl updatecert" command to add the new certificate.

The -p option allows you to specify the passphrase for the certificate if one was specified when the certificate was created in the KeyControl webGUI. If you omit this option and a passphrase is required, you will be prompted to enter the passphrase.

updatecert -a [-u username [-p password]] [-e certificate expiration]

Updates the certificate on the VM through KeyControl.

This form of "updatecert" allows you to download the certificate automatically through KeyControl instead of manually creating the certificate in the webGUI and copying it to the VM.

The -e option allows you to specify the certificate expiration date using the format MM/DD/YYYY. For example, 12/25/2017. If the expiration date is not specified, the certificate will be valid for one year from the date of creation.

update_ca -f /path/to/cert.pem

Updates the local certificate bundle.

In case of any updates to the SSL certificate on KeyControl cluster you should download the certificate, copy that certificate to this computer, and use the "hcl update_ca" command to apply the new certificate.

Authentication

auth [-o one_time_passphrase]

Sends an authentication request from the VM to KeyControl. After you run this command, a Cloud Admin must complete the authentication process in KeyControl. The one-time passphrase will be expired after 15 minutes.

This command is needed if a VM fails to contact to the KeyControl cluster within "grace period" seconds or if the hardware ID changes. In the latter case, this will occur if you change the IP address or a network card.

If the KeyControl cluster is in degraded mode, this command will fail with the suggestion that the user should run: "hcl auth -a [-u user [-s password]]" instead.

auth -a [-u user [-s password]]

Authenticates the VM with KeyControl in a single step by providing the KeyControl Cloud Admin credentials.

The -u and -s options allow you to specify a KeyControl user account name and password. If you do not specify the credentials, or if you specify the user name but not the password, you will be prompted to enter this information.

If the KeyControl cluster is in degraded mode, you can still authenticate the VM if the connection failure is due to grace period expiration. The authentication will fail if the hardware signature of the VM or IP address does not match the stored value on KeyControl or the VM has been revoked by the Cloud Admin.

Note that the above restrictions do not apply if the KeyControl cluster is healthy.

Disk Encryption

list [registered|available|all]

Lists the various devices on the system. If no argument is given, it prints a list of the registered devices using the following format

device mapped-device status

You can also filter the display using the "registered", "available" or "all" arguments. In this case, the output will be in CSV format. For example:

device,mapped-device,status,guid

Windows clients will produce the following output

disk,partition,drive,status,guid

encrypt [-s] [-c cipher] [-m mapped_device] [-e days_to_expire] [-z "NO USE"|"SHRED"] [-o] [-y] [-x] diskname

Encrypts a disks that already has a filesystem/data on it that you want to preserve. This can take a fair amount of time depending on the size of the device and the processor / storage you have in place. The disk will be registered with the KeyControl cluster, which allocates a unique, per-disk encryption key.

As part of the encryption process, a HyTrust GUID and private region will be added if space is available.

If the operation is interrupted, you can complete the encrypt operation by running the command again. Encryption will continue from the place where it was interrupted.

Note that if you have migrated a disk from another VM and the disk is stamped with a HyTrust GUID, you should use the "hcl import" command to add the disk.

The -s option (Linux only) tells hcl to only encrypt allocated blocks which can reduce the time to encrypt dramatically. It uses system- provided utilities to determine the allocated filesystem blocks on a device. The current release supports this option on ext2/ext3/ext4 file systems. Note that -s option does not work in the presence of "online encryption". If "htcrypt" driver is loaded, then HTDC PA makes the clear text device available, immediately. At that point the device can be mounted and accessed through the file system. As the file system can change the free block map, we can not use it to skip free blocks.

The -c option allows you to specify the encryption cipher. Run "hcl ciphers" for the list of available ciphers.

The -e option allows you to specify the number of days the key should be active before it expires. If this option is not specified, the key never expires. What happens when a key expires is determined by the -z option.

The -z option allows you to specify what happens if a key expires. If you specify "NOUSE", the key is deactivated but retained. It can then be reactivated in the KeyControl webGUI. This is the default. If you specify "SHRED", the key is destroyed and cannot be retrieved.

The -m option (Linux only) allows you to change the default clear text path, which is constructed based on the current path to the disk. For example, if the disk is /dev/sdb1, the default clear text path would be /dev/mapper/clear_sdb1. To set the clear text path to /dev/mapper/clear_disk1, you would use "-m clear_disk1".

Note: Windows retains the same drive letter and label after reformatting, so the -m option is not needed.

The -y option makes the command non-interactive.

The -x option (Windows data drive only) causes hcl to check for the existence of a pagefile on the designated drive and will abort if one is found.

Note: By default, you cannot access a whole disk. You should always used partitioned disks since we can easily identify them (through on-disk GUIDs) and find the associated keys. You can override this feature using the -o option.

This command does not apply to boot disks.

decrypt [-s] [-y] diskname

Decrypts a disk and removes it from HyTrust's control but leaves the filesystem and data intact.

The disk will be deregistered with the KeyControl cluster, which deletes the encryption key, just like the the "rm" operation.

If the operation is interrupted you can complete the "decrypt" operation by running the same command again. Decryption will continue from where it was interrupted.

The -y option makes the command non-interactive.

The -s option (Linux only) tells hcl to only decrypt allocated blocks which can reduce the decryption time dramatically. It uses system provided utilities to determine the allocated blocks on a device. The current release supports this option on ext2/ext3/ext4 file systems. Note that -s option does not work in the presence of "online decryption". If "htcrypt" driver is loaded, then HTDC PA keeps the clear text device available, even as the device is being decrypted. As the file system can change the free block map, we can not use it to skip free blocks.

This command does not apply to boot disks.

resize [-y] diskname (Linux Only)

Resizes an active Linux disk and retains any filesystem or data. Note that resize command does not work in the presence of "online encryption". Please refer the admin guide section "Disk Size Management in Linux", for more details on volume resize.

This command resizes the crypto mapping for this disk so that it matches the size of underlying device.

The -y option makes the command non-interactive.

For example, if you have an ext2/ext3/ext4 file system on device myvg-myvol (LVM volume), you can use the following sequence of operations to extend the volume and file system online:

# lvextend -L<new size> /dev/myvg/myvol

# hcl resize myvg-myvol

# resize2fs /dev/mapper/clear_myvg-myvol

This command does not apply to boot disks.

extend drive (Windows Only)

Extends the size of an encrypted Windows partition.

The disk must first be extended using the tools available to the hypervisor. Then the "extend" command can be used to extend the disk. Any hidden metadata partitions are taken in to account. This command does not apply to Windows boot disks.

rekey [-u] [-s] diskname

Rekeys an encrypted disk with a new encryption key. This operation involves creating a new key, decrypting the disk with the old key, and re-encrypting it with the new key. You do not need to do anything through the webGUI for this operation. Note that this operation can take a long time depending on the amount of data and CPU/storage speed.

If the operation is interrupted, you can reverse the rekey by specifying the -u option. Alternatively if you run "hcl rekey" again, it will continue from where it was interrupted.

Please note that on Linux the disk is detached and the contents are unavailable during a rekey operation.

The -s option (Linux only) tells hcl to only rekey allocated filesystem blocks which can decrease the rekey time dramatically. It uses system-provided utilities to determine the allocated blocks on a device. The current release supports this option on ext2/ext3/ext4 file systems. Note that -s option does not work in the presence of "online rekey". If "htcrypt" driver is loaded, then HTDC PA keeps the clear text device available, even as the device is being rekeyed. As the file system can change the free block map, we can not use it to skip free blocks.

This command does not apply to boot disks.

rekey status diskname

It shows the state of the encryption operation on the disk while it is in progress. Although the name of the command refers to "rekey", it shows statistics for any of encrypt, decrypt and rekey operations.

add [-F fstype | "none"] [-n] [-c cipher] [-m mapped_device] [-p parent disk] [-e days_to_expire] [-z "NO USE"|"SHRED"] [-o] [-y] [-x] diskname

Registers a new disk with KeyControl and creates a new encryption key for that disk. Note: If the disk already contains a filesystem and/or data you want to retain, use the "hcl encrypt" command instead. By default, "hcl add" reformats the disk.

On Linux, only the disk name should to be specified (for example "sdb1" as opposed to "/dev/sdb1"). On Windows the disk must already have a drive letter which is then used as the diskname argument.

By default, this command checks for the presence of an existing HyTrust GUID. If it finds one, it adds the disk without reformatting. Otherwise, it formats the disk and adds a HyTrust GUID and private region. For Windows, the only supported format is NTFS. For Linux, the default format is ext3.

The -F option (Linux only) allows you to specify a format other than ext3. You can also use -F to specify that the disk should not be formatted by specifying "-F none".

The -n option allows you to specify that the disk should not be attached immediately. You can use this option if you want to prepare the disk but not bring it online until later.

The -c option allows you to specify the encryption cipher. Run "hcl ciphers" for the list of available ciphers.

Note: Windows retains the same drive letter and label after reformatting, so the -m option is not needed.

The -p option allows you to specify a snapshot of the encrypted LVM volume by specifying the name of the registered parent volume. To get the exact name, run "hcl status".

WARNING: If the snapshot was taken before registering the parent volume, then the snapshot will not have encrypted data.

The -e option allows you to specify the number of days the key should be active before it expires. (If this option is not specified, the key never expires.) What happens when a key expires is determined by the -z option.

By default we will prevent you from accessing a whole disk. You should always used partitioned disks since we can easily identify them (through on-disk GUIDs) and find the associated keys. You can override this by passing the -o option.

The -y option makes the command non-interactive.

The -x option (Windows data drive only) tells hcl to check for the existence of a pagefile on the designated drive and will abort if one is found.

import [-y] [-w] [-n] [-m mapped_device] [-c cipher] diskname

Add a device that has been copied/moved from another VM. The operation requires that the device was previously registered and contains a HyTrust GUID. If no GUID is present, the operation will fail and the disk will not be modified in any way.

To see GUIDs associated with a given disk, use the "hcl status -g" command on Linux and the "hcl status" command on Windows.

A device can also be imported using its SCSI WWN (Linux only), if it does not have a HyTrust GUID. Use command "hcl status -G" to see the GUIDs/WWN

If -w option is specified, import command falls back to SCSI WWN if HyTrust GUID is not found. Note that if HyTrust GUID is present then it is used even if -w is specified.

The -y option makes the command non-interactive.

The -n option allows you to specify that the disk should not be attached immediately. The "auto_attach" property is set to "DISABLED". You can use this option if you want to prepare the disk but not bring it online until later.

The -c option allows you to specify the encryption cipher that was used during the initial encryption. Run "hcl ciphers" for the list of available ciphers.

rm [-y] <diskname | -a>

Removes a single disk or all disks from HyTrust control. This issues an implicit "detach" command before removing the disk from HyTrust's configuration.

WARNING: Removing a disk will result in any data encrypted on that disk being lost. If you want to retain the data, use the "hcl decrypt" command.

You can specify a single disk name or use the -a option to remove all disks.

"hcl rm" unregisters the device from the KeyControl cluster configuration and destroys the encryption key.

The -y option makes the command non-interactive.

attach [-l [-p passphrase] ] <diskname | -a>

Fetches the key associated with the encrypted device from the KeyControl cluster, "unlocks" the disk making the clear text data available via the clear text device path, and runs the attach handler, which typically mounts the device. By default, devices have the "auto_attach" property set to "ENABLED", so the attach operation is done automatically at boot time.

However, there may be cases when it is not desirable for the encrypted device to be automatically attached and exposed throughout the uptime of the machine. In such cases, the "auto_attach" property of the device should be set to "DISABLED" and attach/detach should be invoked manually.

If a disk becomes detached, for example if the VM reboots and the KeyControl cluster is unreachable, use this command to manually attach one or all disks.

The -l option allows tells the command to look for a cached copy of the keys, while the -p option allows you to specify the password that decrypts the keys and allows access to the disk. If you specify -l but do not specify -p, the command prompts you for the password. (For information about caching keys, see the "hcl cache" command.)

You can specify a single disk name or use the -a option to attach all disks.

detach <diskname | -a>

Detaches a specific disk or all disks. When a disk is detached, the filesystem will be unmounted and access to data will not be available until the disk is attached again.

The detach operation runs the detach handler associated with the device, which typically unmounts the filesystem and removes the clear text device path. The key will be removed from the VM (unless it has been cached using "hcl cache", in which case it is stored encrypted by a passphrase), encrypted data is no longer accessible until a subsequent "attach" operation fetches the key from the KeyControl cluster.

You can specify a single disk or use the -a option to detach all disks.

keyversion <diskname>

Returns current keyversion for <diskname> and if Single Encryption Key is enabled for CVMset that VM is registered to will return the latest SEK keyversion.

set property=value <diskname | -a>

Sets a property value for a specific disk or for all disks. You can specify one of the following properties:

1. mntpt=<path> If set, this property is supplied to the attach handler, a script which is run at the time of attaching a device. The default attach handler uses this value as the mountpoint of the device.

2. mntopts=<string> If set, this property is supplied to the attach handler. The default attach handler uses this value as a command line argument to the mount command. An example could be "-o rw,data=journal,commit=20".

3. auto_attach=ENABLED|DISABLED. Enables or disables auto attach. Enabling this property means that HyTrust attempts to attach the disk as soon as the system is booted or the disk will be attempted to be attached as soon as the system is booted, or whenever the KeyControl cluster is reachable. The default is "ENABLED" if not supplied.

4. attach_handler=DEFAULT|<path>. Sets the attach handler, which is a script run just after the attach operation is successful. Attach handlers are called with 2-4 arguments: e.g. default.attach <path of clear text device> <path of encrypted device> [<mountpoint>] [<mount options>] The default attach handler fscks and mounts the device if the "mntpt" property is set. The handler can be customized by modifying a copy of the default handler located in /opt/hcs/handlers/default.attach. Customized attach handlers can be used for preparing and starting applications associated with this device.

5. detach_handler=DEFAULT|<path>. Sets the detach handler, which is run just before the device is detached. Detach handlers are called with 2 arguments: e.g. default.detach <path of clear text device> <path of encrypted device>. The default detach handler attempts to "kill -9" all processes using the mount point, if any, associated with this device, unmounts the filesystem. Just like the attach handler, a customized detach handler can be used to shutdown applications and carry out cleanup activities and unmount the filesystem before the device is detached. Note that a detach handler must succeed.

You can specify a single disk name or use the -a option to set the property value for all disks.

Disk Management

devorder print

Displays the current device order. To change the order, use the "devorder" command, described below.

Devices are attached automatically at boot in the order in which they were initially registered. On Linux, if the "mntpt" property is set on the device then it is also automatically mounted when attached. So the devices are mounted in the order in which they are initially registered.

This order can be changed using "devorder" command. The "devorder print" command shows the current device order.

devorder <up | down> diskname

Changes where the specified device falls in the device attach order.

The "up" option moves the device higher in the order.

The "down" option moves the device lower in the order.

updateconfig

Updates the HyTrust config file on a VM when devices have been removed or added, while the VM is online. This command lets you update the device list in "real time" without needing to reboot the VM. You do not need to run this command to update the devices that were removed or added while the VM was offline, as those updates happen automatically when the VM boots.

devicesync [-y] reason_for_sync

Synchronizes the registered device list on KeyControl with the HyTrust config file on the VM. It is particularly useful when KeyControl and the VM go out of sync after the VM is restored to an older snapshot.

As this causes a major configuration change, the admin must provide a "reason" for running this command. The information provided by admin, which should be a simple text string which is then logged in the audit log on KeyControl and added to the alert message generated during sync processing.

The -y option makes the command non-interactive.

We recommended that the admin runs the "hcl updateconfig" command after "hcl devicesync".

gone <list | rm | test> [device]

The gone command can be used to manage the hidden devices that have been marked "GONE" in the hcl config file. Devices are marked GONE when, during initial device discovery, a device which was previously encrypted is found missing. The device is not automatically deleted in order allow for recovery of accidentally removed devices.

gone list produces a list of all devices marked "GONE" in the config file. It will print both the device name and it mapped name.

gone rm device removes the hidden "GONE" entry in the config file. On the next heartbeat, it will also remove the associated entry from the KC.

gone test device returns 1 (TRUE) if the hidden device entry is marked "GONE" and 0 (FALSE) if it is not.

The device name used by both the rm and the test command can either be the physical device name or its current mapped name. These are presented in the hcl gone list command.

Disk Key Caching

cache [-n duration in days] [-p passphrase] <diskname | -a>

Caches the encryption keys for a specific disk or all disks locally on the VM for the specified number of days.

Encryption keys are generally fetched from the KeyControl cluster when a disk is added or post boot/authentication. If you have an unstable network connection between the VM and the KeyControl cluster or you are using the DataControl agent on a VM that is not always connected to the network, you can cache the keys on the VM.

The -n option allows you to specify the number of days that the keys should be kept in the cache. Once this time expires, the keys are deleted. If the -n option is not specified, keys will be cached for a default of one day.

The -p option allows you to specify a password that must be supplied to encrypt/decrypt the keys in the cache.

You can specify a single disk name or use the -a option to cache the keys for all disks.

cache -l

Displays information about disks for which keys have been cached and the duration for which the cached keys are valid.

cache -r <diskname | -a>

Removes cached keys for a specified disk or for all disks.

You can specify a single disk name or use the -a option to remove the cached keys for all disks.

File Encryption

keyid <-c keyid_to_create [-s] [-a cipher] [-d description] [-e days_to_expire] [-k key] [-i initialization_vector] [-o "NO USE"|"SHRED"]>

Creates a KeyID, which is a handle for an encryption key that is shared between VMs in the same Cloud VM Set. KeyIDs can be used to encrypt and decrypt files which can be either passed securely between these VMs or placed on external storage for backup. For example, you can encrypt an archive from a VM that has the Policy Agent installed and move that encrypted image safely to cloud storage.

The -c option allows you to specify the name of the new KeyID.

The -s option tells KeyControl to make sure the cipher specified with the -a option is compatible with the version of OpenSSL currently installed on the VM.

The -a option allows you to specify the encryption cipher. Run "hcl ciphers" for the list of available ciphers.

The -d option allows you to specify a description for the KeyID. We recommend you use this option to better identify KeyIDs.

The -e option allows you to specify the number of days the KeyID should be active before it expires. (If this option is not specified, the KeyID never expires.) What happens when a KeyID expires is determined by the -o option.

The -k option allows you to specify the base64 encoded key string for the keyID to be created. The key value should have proper length corresponding to the cipher algorithm chosen.

The -i option allows you to specify the base64 encoded initialization_vector(IV) for the keyID to be created, the Initialization_vector must be present when using the -k option and the length must be at least 16 bytes(128 bits).

The -o option allows you to specify what happens if a KeyID expires. If you specify "NOUSE", the key is deactivated but retained. It can then be reactivated in the KeyControl webGUI. This is the default. If you specify "SHRED", the KeyID is destroyed and cannot be retrieved.

keyid -r [-f]

Removes the specified KeyID. Without the -f option, you will be prompted to confirm the removal of the KeyID.

keyid -F <keyid to fetch>

Retrieves the base64 encoded value of the key and IV associated with the keyid.

keyid -u [-d description]

Updates the specified KeyID. Currently the only attribute that can be updated is the description for the KeyID, which you specify with the -d option.

keyid -l

Displays a list of KeyIDs available to the VM based on the Cloud VM Set with which this VM is registered. You can also view the list of KeyIDs in the KeyControl webGUI.

encryptfile [-k keyid] filename [encryptedfile]

Encrypts the specified file.

The -k option allows you to specify an existing keyID to use for the encryption.

The "encryptedfile" option allows you specify a file name into which the encrypted output will be placed. By default, the command writes the output to stdout.

decryptfile encryptedfile [filename]

Decrypts a file encrypted with the "encryptfile" command on this VM or on any other VM in the Cloud VM Set.

When a file is encrypted using the "encryptfile" command, information about the keyID is stored in the encrypted file. From the same VM or any other VM in the same Cloud VM Set, you can decrypt the file using the "decryptfile" command.

The "encryptedfile" option allows you to specify the name of the file that you want to decrypt.

The "filename" option allows you specify a file name into which the decrypted output will be placed. By default, the command writes the output to stdout.

Clone Handling

template <-i ipaddr | -m macaddr> [-u username -p password] days_to_expire

This command prepares a VM for automatic clone deployment. The VM on which we run this command is called the template VM. The IP address or the MAC address can be specified with the -i or -m option respectively. The IP address or the MAC address for the clone VM must be known in advance.

Running the "hcl template" command on a template VM has two effects. First, KeyControl will recognize a VM with the provided IP or MAC address and the same certificate as a legitimate clone. Secondly, KeyControl provides limited access to keys. The "hcl template" command downloads a token which is later used to automatically register the clone VM.

The "days_to_expire" option specifies the number of days for which the clone access token remains valid.

The sequence of operations in which this command is used is:

1. Install the Policy Agent software on the template VM.

2. Register the template VM with KeyControl.

3. Encrypt the required data devices (root device, swap etc).

4. Reserve IP addresses or MAC addresses for the clone VMs.

5. Run the "hcl template" command on the template VM.

6. Take a clone of the template VM using hypervisor tools.

7. When the clone VM boots, it will be automatically deployed and registered with a new name on KeyControl.

template remove <-i ipaddr | -m macaddr> [-u username -p password]

Removes the previously added IP address or MAC address as a legitimate clone of this VM

template list

Displays a list of all IP addresses and MAC addresses which have been added as legitimate clone VMs of this VM.

Miscellaneous

heartbeat

This command sends a heartbeat message to the KeyControl immediately instead of waiting for the hcld deamon to do it periodically. Upon successful completion, the "Last Heartbeat" field will be updated to indicate how long it has been since the client and the KeyControl have successfully communicated and the return code will be 0. If an error occurs, it will return the errno. This command can be useful to test connectivity between the VM and KeyControl.

You can view the "Last Heartbeat" field using the "hcl status" command.

ciphers

Displays the default and available ciphers.

aesni-check

Checks the CPU features to see if AES-NI crypto acceleration is available to the VM on which it is running.

htcrypt-check

Checks if the htcrypt encryption driver is present and usable.

destroy [-y]

Removes all HyTrust configuration about all disks and folders from the VM. This has the same effect as uninstalling and re-installing the product and should be used with extreme caution. This operation cannot be reverted and all encrypted data will be lost. Note that any cleanup on the KeyControl must be performed separately.

When dealing with VM clones, Do Not use this command unless VM is registered as a clone (refer 'hcl register') to avoid any accidental data loss.

To completely remove the VM from the KeyControl, the 'hcl unregister' command should be issued prior to the 'hcl destroy' command.

The -y option makes the command non-interactive.

version

Displays the version of the DataControl Policy Agent software.

-h | -?

Displays all the options available through the hcl command.

FILES

On Linux:

/opt/hcs

The default location of the Policy Agent configuration files.

/var/log/hcl.log

The Policy Agent log file. If errors are detected, you will be requested to provide this file to HyTrust support staff.

On Windows:

C:\Program Files\hcs\hcl.log

The Policy Agent log file. If errors are detected, you will be requested to provide this file to HyTrust support staff.

BUGS

See the HyTrust Release Notes for information about bugs and caveats in the software.

AUTHOR

HyTrust Inc.

hcl Man Page

`hcl` Man Page