NAME

hcl - Encrypt disks, filesystems, and files using HyTrust DataControl

SYNOPSIS

hcl OPTIONS

DESCRIPTION

The hcl command manages 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 for available disks, including the partition type and whether a disk GUID exists.

Registration

register -c -h myname -d description -p certificate_password -o one_time_passphrase kc_hostnameport,kc_hostname2port2,... /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. For simplified registration, see the "register -a" version of this command below.

The -c option indicates a clone certificate, so specify it only if you are registering a clone VM.

The -h option lets you name the VM, which will be visible in the webGUI and through APIs.

The -d option lets you specify an optional VM description. This will also be visible in the webGUI and through APIs.

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

The -o option lets you enter a one-time passphrase 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 expire 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

The final argument is the certificate path.

register -a -c -h myname -d description -n mapping -N [-u username -s password -e certificate expiration -v vault_id -z cvmset kc_hostnameport,kc_hostname2port2,...

Registers the VM using simplified registration, so you don't 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 optionally specifying a KeyControl mapping.

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

The -h option lets you name the VM, which will be visible in the webGUI and through APIs.

The -d option allows you to specify an optional description for the VM. This will also be visible in the webGUI and 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 you omit this option, it will display the list of mappings and prompt you to select one. If you associate the VM with a mapping, KeyControl will automatically update the list when the VM heartbeats against the cluster.

The -N option allows you to skip KeyControl mapping for the VM. If you provide this option, the mapping list will not be displayed even if you omit -n. If both -n and -N options are set, the -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 lets you specify the certificate expiration date in MM/DD/YYYY format. For example, 12/25/2017. If you don't specify an expiration date, the certificate is valid for one year from the creation date.

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

 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 effectively uninstalls and reinstalls the product and should be used with extreme caution.

When dealing with VM clones, Do Not use this command unless the VM is registered as a clone (refer to '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 VM's registered name in KeyControl. If no VM called "newname" exists in the Cloud VM Set to which this VM belongs, KeyControl changes the VM's registered name to "newname".

KeyControl Management

updatekc kc_hostnameport,kc_hostname2port2,...

Manually updates the list of KeyControl node IP addresses on the VM. The correct list of IP addresses enables automatic failover if a node becomes unreachable.

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

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 lets you switch to a new mapping. This command requires KeyControl Cloud Admin credentials.

The Cloud Admin can maintain multiple KeyControl mappings in KeyControl. Each mapping lists KeyControl nodes. You can associate the VM with one of those mappings. If you do, KeyControl will fetch the list of KeyControl nodes and update it automatically during each heartbeat.

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

The -n option allows you to specify a KeyControl mapping for the VM. If KeyControl has mappings available for the specified Cloud Admin and you omit this option, it will display the mappings and prompt you to select one. If you associate the VM with a mapping, KeyControl will automatically update the list when the VM heartbeats against the cluster.

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 username 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.

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

The -p option lets you specify the certificate passphrase if you specified one when you created the certificate 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" lets you download the certificate automatically through KeyControl instead of manually creating it in the webGUI and copying it to the VM.

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

The -e option lets you specify the certificate expiration date in MM/DD/YYYY format. For example, 12/25/2017. If you don't specify an expiration date, the certificate is valid for one year from the creation date.

update_ca -f /path/to/cert.pem

Updates the local certificate bundle.

If you update the SSL certificate on the KeyControl cluster, download the certificate, copy it to this computer, and use the "hcl update_ca" command to apply it.

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 expire after 15 minutes.

Use this command if a VM fails to contact the KeyControl cluster within the "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 fails and suggests running: "hcl auth -a [-u user -s password]" instead.

auth -a [-u user -s password]

Authenticates the VM with KeyControl in a single step using 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. Authentication will fail if the VM's hardware signature or IP address does not match the stored value on KeyControl, or if the Cloud Admin has revoked the VM.

Disk Encryption

list registered

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 with the "registered", "available", or "all" arguments. In this case, the output will be in CSV format. For example:

Windows clients will produce the following output

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

Encrypts a disk that already has a filesystem/data 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, it adds a HyTrust GUID and private region if space is available.

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

The -s option (Linux only) tells hcl to encrypt only allocated blocks, which can dramatically reduce encryption time. 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 the -s option does not work with "online encryption". If the "htcrypt" driver is loaded, then HTDC PA makes the clear text device available immediately. At that point, you can mount and access the device through the file system. Because the file system can change the free block map, we cannot 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 lets you specify how many days the key should be active before it expires. If you don't specify this option, the key never expires. What happens when a key expires is determined by the -z option.

The -z option lets you specify what happens when a key expires. If you specify "NOUSE", the key is deactivated but retained. You can then reactivate it 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 is/dev/mapper/clear_sdb1. To set the clear text path to /dev/mapper/clear_disk1, you would use "-m clear_disk1".

The -y option makes the command non-interactive.

The -x option (Windows data drive only) makes hcl check for a pagefile on the designated drive and abort if it finds one.

This command does not apply to boot disks.

decrypt -s -y diskname

Decrypts a disk and removes it from HyTrust control while leaving the filesystem and data intact.

The disk will be deregistered with the KeyControl cluster, which deletes the encryption key, just like 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 decrypt only allocated blocks, which can dramatically reduce decryption time. 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 the -s option does not work with "online decryption". If the "htcrypt" driver is loaded, HTDC PA keeps the clear text device available even while the device is being decrypted. Because the file system can change the free block map, we cannot 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. 

This command resizes the crypto mapping for this disk to match the underlying device size.

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:

This command does not apply to boot disks.

extend drive (Windows Only)

Extends an encrypted Windows partition.

First, extend the disk using the hypervisor's tools. Then you can use the "extend" command to extend the disk. It accounts for any hidden metadata partitions. This command does not apply to Windows boot disks.

rekey -u -s diskname

Rekeys an encrypted disk with a new encryption key. This operation creates a new key, decrypts the disk with the old key, and re-encrypts it with the new key. You do not need to do anything through the webGUI for this operation. 

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

On Linux, the disk detaches, and the contents become unavailable during a rekey operation.

The -s option (Linux only) tells hcl to rekey only allocated filesystem blocks, which can dramatically reduce rekey time. 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 the -s option does not work when "online rekey" is enabled. If the "htcrypt" driver is loaded, HTDC PA keeps the clear text device available even while the device is being rekeyed. Because the file system can change the free block map, we cannot 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 command name refers to "rekey", it shows statistics for encrypt, decrypt, and rekey operations.

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

Registers a new disk with KeyControl and creates a new encryption key for that disk. 

On Linux, only the disk name should 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 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. 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.

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

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 lets you specify how many 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 lets you specify what happens when a key expires. If you specify "NOUSE", the key is deactivated but retained. You can then reactivate it in the KeyControl webGUI. This is the default. If you specify "SHRED", the key is destroyed and cannot be retrieved.

By default, we will prevent you from accessing a whole disk. You should always use 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 whether a pagefile exists on the designated drive and aborts if it does.

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.

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

If you specify the -w option, the import command falls back to the SCSI WWN if it does not find a HyTrust GUID. 

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". Use this option if you want to prepare the disk but not bring it online until later.

The -m option (Linux only) lets you change the default clear text path, which is built from the disk's current path. For example, if the disk is /dev/sdb1, the default clear text path is/dev/mapper/clear_sdb1. To set the clear text path to /dev/mapper/clear_disk1, you would use "-m clear_disk1".

The -c option lets you specify the encryption cipher 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 cause any data encrypted on that disk to be lost. 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, you may not want the encrypted device to attach automatically and remain attached throughout the machine's uptime. In such cases, set the device's "auto_attach" property to "DISABLED" and invoke attach/detach 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 tells the command to look for a cached copy of the keys, while the -p option lets you specify the password that decrypts the keys and grants 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 you detach a disk, the filesystem is unmounted, and you won't be able to access the data until you attach the disk 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 the current key version for <diskname>, and if Single Encryption Key is enabled for the CVM set the VM is registered to, it returns the latest SEK key version.

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:

• mntpt=<path> If set, this property is supplied to the attach handler, a script run when attaching a device. The default attach handler uses this value as the device mountpoint.
• 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".
• auto_attach=ENABLED|DISABLED. Enables or disables auto-attach. Enabling this property means HyTrust attempts to attach the disk as soon as the system boots, or whenever the KeyControl cluster is reachable. The default is "ENABLED" if not supplied.
• attach_handler=DEFAULT|<path>. Sets the attach handler, a script run just after the attach operation succeeds. 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. You can customize the handler by modifying a copy of the default handler in /opt/hcs/handlers/default.attach. You can use customized attach handlers to prepare and start applications associated with this device.
• 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, and unmounts the filesystem. Like the attach handler, a customized detach handler can shut down applications, perform cleanup, and unmount the filesystem before the device is detached. 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.

You can change this order using the "devorder" command. The "devorder print" command shows the current device order.

devorder <up | down> diskname

Changes the device order to place the specified device 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 are added or removed while the VM is online. This command lets you update the device list in "real time" without rebooting the VM. You don't need to run this command to update devices 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 VM's HyTrust config file. 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 the admin provides should be a simple text string that KeyControl logs in the audit log and adds to the alert message generated during sync processing.

The -y option makes the command non-interactive.

We recommend running the "hcl updateconfig" command after "hcl devicesync".

gone <list | rm | test> device

The gone command manages hidden devices marked "GONE" in the hcl config file. Devices are marked GONE when, during initial device discovery, a previously encrypted device is found missing. The device is not automatically deleted, allowing 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 its 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 test commands can be either 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 lets you specify how many days to keep keys in the cache. Once this time expires, the keys are deleted. If you don't specify the -n option, keys are cached by default for one day.

The -p option lets you specify a password 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">

Creates a KeyID, a handle for an encryption key shared between VMs in the same Cloud VM Set. You can use KeyIDs to encrypt and decrypt files, which you can either pass securely between VMs or store 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 lets you specify how many 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 must be the correct length for the chosen cipher algorithm.

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. You can then reactivate it 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 key ID.

keyid -u -d description

Updates the specified KeyID. Currently, the only attribute you can update is the KeyID description, 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 lets you specify an existing keyID to use for encryption.

The "encryptedfile" option lets you specify a file name for the encrypted output. 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 you encrypt a file with the "encryptfile" command, it stores the keyID 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 lets you specify the file you want to decrypt.

The "filename" option lets you specify the file name for the decrypted output. 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 where you run this command is called the template VM. You can specify the IP address or MAC address with the -i or -m option, respectively. You must know the clone VM's IP address or MAC address 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 how many days the clone access token remains valid.

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 credentials, or if you specify the username but not the password, you will be prompted to enter this information.

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. Clone 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 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 daemon to do it periodically. Upon successful completion, the "Last Heartbeat" field updates to show how long it has been since the client and the KeyControl last communicated, and the return code is 0. If an error occurs, it will return the errno. This command can help 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 CPU features to see whether AES-NI crypto acceleration is available to the VM it runs on.

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 reinstalling the product and should be used with extreme caution. This operation cannot be reverted, and it will lose all encrypted data. 

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

To completely remove the VM from KeyControl, issue the 'hcl unregister' command before 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:

The default location of the Policy Agent configuration files.

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

On Windows:

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.

SEE ALSO

htroot(1)