HCL(1) User Manuals HCL(1)
NAME
hcl - Encrypted disks and files using HyTrust DataControl Policy Agent
SYNOPSIS
hcl [OPTIONS]
DESCRIPTION
The hcl command is used to manage encrypted disks and files using
HyTrust's DataControl Policy Agent.
OPTIONS
The options are as follows:
status Display information about connection the KeyControl nodes, the
status of the connection and the list of KeyControl nodes that
this VM can communicate with.
status -g (Linux only)
Display partition information about the available disks showing
the partition type and the existence of any disk GUID.
ciphers
Show default and available ciphers.
add [-f] [-F fstype | "none"] [-n] [-c cipher] [-m mapped_device] [-o]
diskname
When a new disk needs to be added for encryption, the add com-
mand should be called which registers the device with the Key-
Control cluster which then allocates a unique encryption key for
the device. On Linux only the device name needs to be added such
as sdb1 (as opposed to /dev/sdb1). On Windows the disk must
already have a drive letter which is then passed as the diskname
argument.
By default, the disk will be formatted unless the disk has been
moved from another VM and has a HyTrust GUID on the disk. If
space is available a HyTrust GUID and private region will be
added to a new device by default. On Windows, NTFS is the only
filesystem supported. On Linux, the disk will be formatted with
ext3 by default unless a different filesystem is specified using
the -F option. If you wish to encrypt an already existing
filesystem use hcl encrypt in place of hcl add the disk, rather
than the destructive "hcl add". If you pass "none" to the -F
option, the Linux disk will not be formatted.
Windows will retain the same drive letter and label after for-
matting. For Linux, a clear text path will be created. In the
case of adding /dev/sdb1, the clear text path will be /dev/map-
per/clear_sdb1 unless the -m option is specified in which case
you can supply your own device path.
Check ciphers option for default cipher and ciphers available
with the -c option.
By default we will prevent you from accessing whole disks. You
should always used partitioned disks since we can easily iden-
tify them (through on-disk GUIDs) and find the associated keys.
You can overide this by passing the -o option.
You can use -f option for loopback devices when testing encryp-
tion capabilities but be warned the loopback devices are not
generally available post boot and may not be displayed when run-
ning hcl status
rm
To remove a disk from HyTrust control, use the rm option. This
will issue an implicit detach command before removing the disk
from HyTrust's configuration. You can remove all disks by speci-
fying the -a option. The rm option unregisters the device from
the KeyControl cluster configuration which then destroys the
encryption key.
WARNING: removing a disk will result in any data encrypted on
that disk being lost. If you want to retain the data, see
decrypt option
set property=value
Properties can be one of:
1. mntpt= 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 mount-
point of the device.
2. mntopts="" 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. Examples of mntopts:
"-o rw,data=journal,commit=20"
3. auto_attach=ENABLED|DISABLED. Enables or disables auto
attach. Enabling this property means that the disk will be
attempted to be attached as soon as the system is booted, or
whenever the KeyControl cluster is reachable. Defaults to
ENABLED if not supplied.
4. attach_handler=DEFAULT|. 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 [] [] The default attach han-
dler 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 applica-
tions associated with this device.
5. detach_handler=DEFAULT|. Sets the detach handler,which is run
just before the device is detached. Detach handlers are called
with 2 arguments: e.g. default.detach. The default detach han-
dler 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.
attach [-l [-p passphrase] ]
The attach operation fetches the key associated with the
encrypted device from the KeyControl cluster, "unlocks" it,
makes the clear text data available via the clear text device
node, 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, you can manually attach
a disk. If keys are cached, the -l option allows the user to
supply the passphrase which will decrypt the key(s) and allow
access to the disk.
If you specify -l option but do not specify the -p option you
will be prompted for the passphrase.
detach
The detach command can be used to detach a disk. All disks can
be detached by using the -a option. 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, removes the
clear text device node. The key is no longer present on the VM
(unless it has been cached using the 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.
cache [-n duration in days] [-p passphrase]
Encryption keys are generally fetched from the KeyControl clus-
ter when a disk is added or post boot/authentication. If you
have an unstable network connection between the VM and the Key-
Control cluster or you are using the Policy Agent on a VM
that is not always connected to the network, you can cache the
keys on the VM. They will be encrypted on disk using the sup-
plied passphrase. Keys are only cached for the specified number
of days. If you wish to cache keys for all disks, use the -a
option. If you do not specify the -p option you will be
prompted for the passphrase.
cache -l
The -l option displays information about disks for which keys
have been cached and the duration for which the cached keys are
valid.
cache -r
The -r option allows you to remove cached keys for the specified
disk or for all disks if the -a option is passed.
encrypt [-s] [-f] [-c cipher] [-o] diskname
If the disk that you wish to encrypt already has a filesys-
tem/data on it that you wish to preserve, you should use the
encrypt option. This can take a fair amount of time depending on
the size of the device and the processor / storage you have in
place.
If the operation is interrupted, you can complete encrypt oper-
ation by running it again. The encryption will continue from
where it was interrupted.
Note that if you have migrated a disk from another VM and the
disk has a HyTrust GUID, you should use the hcl add command to
add the disk. As part of encrypt a HyTrust GUID and private
region will be added if space is available.
The disk is registered with the KeyControl cluster, which allo-
cates it a unique encryption key, just like in the 'add' opera-
tion.
Check ciphers option for default cipher and ciphers available
with the -c option.
By default we will prevent you from accessing whole disks. You
should always used partitioned disks since we can easily iden-
tify them (through on-disk GUIDs) and find the associated keys.
You can overide this by passing the -o option.
If you pass the -s option, we will skip free file system blocks
which can increase the speed of the operation dramatically. It
uses system provided utilities to find out the file system free
and allocated blocks on a device. The current release supports
ext2/ext3/ext4 file systems.
decrypt [-s] diskname
If you wish to remove a disk from HyTrust control but want to
retain the filesystem / data on it, you can use the decrypt
option. This will decrypt the disk and remove it from HyTrust
control.
If the operation is interrupted, you can complete decrypt oper-
ation by running it again. The decryption will continue from
where it was interrupted.
The disk is deregistered with the KeyControl cluster, which
deletes the encryption key, just like in the 'rm' operation.
If you pass the -s option, we will skip free file system blocks
which can increase the speed of the operation dramatically. It
uses system provided utilities to find out the file system free
and allocated blocks on a device. The current release supports
ext2/ext3/ext4 file systems.
rekey [-u] [-s] diskname
The rekey option can be used to rekey the disk. This operation
involves allocating a new key, decrypting the disk with the old
key and 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 rekey again,
it will continue from where it was interrupted.
Please note that the disk is detached and the contents are
unavailable during this operation.
If you pass the -s option, we will skip free file system blocks
which can increase the speed of the operation dramatically. It
uses system provided utilities to find out the file system free
and allocated blocks on a device. The current release supports
ext2/ext3/ext4 file systems.
register [-c] [-h myname] [-d description] [-p certificate_password]
[-o one_time_passphrase] kc_hostname[:port],kc_hostname2[:port2],...
/path/to/cert.bin
The register command is used to register the VM with a KeyCon-
trol cluster.
The -c option indicates the presence of a clone certificate so
should only be specified if you are cloning a VM.
The -h option allows you to give a symbolic name to the VM which
will be visible in the webGUI as well as through the APIs.
The -d option allows you to specify an optional description for
the VM.
If you chose a passphrase for the certificate you can enter the
passphrase using the -p option. If you omit this option and you
typed a passphrase when the certificate was generated, you will
be prompted to type the passphrase.
If you do not specify the -o otion you will be prompted for the
one time passphrase. This passphrase will be entered in the
webGUI when you authenticate the VM.
The kc_hostname list option is a comma separate list of KeyCon-
trol cluster servers. If you have a two node cluster you should
enter both IP addresses. If you have a three node cluster, enter
all three IP addresses. Note that if you add or remove any
nodes, you should run the updatekc command to replace this list.
The final option is a pathname to the certificate.
register -a [-h myname] [-d description] kc_hostname[:port],kc_host-
name2[:port2],...
A simpler form of registration is available by which you do not
need to manually create a certificate and copy it to the VM. You
can quickly register and authenticate a VM by providing your
KeyControl credentials and selecting the Cloud VM Set.
The -h option allows you to give a symbolic name to the VM which
will be visible in the webGUI as well as through the APIs.
The -d option allows you to specify an optional description for
the VM.
You will be prompted to provide the KeyControl credentials. The
command will fetch the list of Cloud VM Sets visible to corre-
sponding Cloud Admin. Now you will be prompted to choose the
Cloud VM Set, in which this VM should be registered.
If the KeyControl has KeyControl mappings for this Cloud Admin,
the list of these mappings will also be displayed. You can
choose to associate the VM with one of those mappings or can
skip this step. If you choose to associate the VM with a map-
ping, then the KeyCotrol list will be fetched from the KeyCon-
trol and maintained upto date.
The kc_hostname list option is a comma separate list of KeyCon-
trol cluster servers. If you have a two node cluster you should
enter both IP addresses. If you have a three node cluster, enter
all three IP addresses. Note that if you add or remove any
nodes, you should run the updatekc command to replace this list.
updatekc kc_hostname[:port],kc_hostname2[:port2],...
When a change is made to the list of KeyControl nodes in the
cluster, the updatekc command should be invoked to inform the
Policy Agent of the change. The Key Control list passed as
an argument is a comma separated list of IP addresses, for exam-
ple 192.168.140.151:443,192.168.140.152:443 The port number is
optional and will default to 443.
updatekc -a
The Cloud Admin can maintain multiple KeyControl mappings on the
KeyControl. Each of this mapping is a list of KeyControl nodes,
as visible to the VM. You can associate the VM with one of
those mappings. If you choose to associate the VM with a map-
ping, then the list of KeyCotrol nodes will be fetched from the
KeyControl and maintained upto date automatically.
The Cloud Admin credentials will be required to use this com-
mand.
updatecert [-p certificate_password] /path/to/cert.bin
Certificates are valid for one year by default unless you
changed the expiration date when the certificate was created. To
keep access to data you should create a new certificate prior to
expiration and call updatecert command to add the new certifi-
cate. If the certificate was passphrase protected you can supply
the passphrase using the -p option otherwise you will be
prompted to enter it on the command line.
auth [-o one_time_passphrase]
This call 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.
auth -a
A simpler form of re-authentication is available by which you do
not need to manually login to KeyControl. You can quickly
authenticate a VM by providing your KeyControl credentials.
updateconfig
This command updates HyTrust config file on a VM when devices
have been removed or added. This does not need to called for any
devices that have been removed or added when VM is offline as
they will be recognized at boot; rather, only devices removed or
added when VM is online and that need to be recognized as such
prior to next reboot will require this update.
keyid <-c keyid_to_create [-s] [-a cipher] [-e days_to_expire] [-o "NO
USE"|"SHRED"] [-d description]> <-r keyid_to_remove [-f]> <-u
keyid_to_update [-d description]> <-l>
KeyIDs are handles for encryption keys that are shared between
VMs in the same Cloud VM Set. They 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 only required option is -c in which case you specify a name
for the KeyID. Generally speaking you will want to add a
description for your key (using the -d option).
Check ciphers option for default cipher and ciphers available
with the -a option. To ensure default cipher compatibility with
openssl currently installed on VM, use -s option.
By default keys do not expire. If you choose a number of days by
which the key will expire, by default the key will switch to
NO_USE in which case the key cannot be used. You can also spec-
ify that the key be shredded in which case it will be destroyed
at expiration. In the "NO USE" case, the key can be made active
again through the webGUI.
If you wish to remove a KeyID, use the -r option and give the
name of the KeyID. Currently, the only KeyID property that can
be updated using the -u option is the description. The -l
option will show KeyIDs that are available for the Cloud VM Set
to which a VM is registered. These are also displayed in the
GUI under each Cloud VM Set.
encryptfile [-k keyid] filename [encryptedfile]
A file can be encrypted using the encryptfile option. The -k
option is used to specify the KeyID which was previously created
using the keyid command. You specify the filename of the file to
be encrypted. By default, the contents will be written to stdout
although an encrypted file can be chosen by specifying the
encryptedfile option.
decryptfile encryptedfile [filename]
When a file is encrypted using the encryptfile command, informa-
tion 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. Simply pass the
encryptedfile as an argument. By default, the decrypted contents
will be written to stdout although an decrypted file can be cho-
sen by specifying the filename option.
destroy
The destroy
command removes all HyTrust configuration about all disks. This
has the effect of uninstalling and installing the product and
should be used with extreme caution.
version
Display the version of the Policy Agent software.
-h | -?
This command displays all the options avaialble through the hcl
command.
FILES
/opt/hcs
The location of the HyTrust DataControl configuration files.
/var/log/hcl.log
The HyTrust DataControl log file. If errors are detected, you
will be requested to provide this file to HyTrust support staff.
C:\Program Files\hcs\hcl.log
The HyTrust DataControl 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.
Linux DECEMBER 2014 HCL(1)