Manages public key encryption of backup keys to create a write-only backup, also known as asymmetric encryption.
$ hb readkey on [-c backupdir] [-b bits] [-p ask/env] $ hb readkey off [-c backupdir] $ hb readkey [-c backupdir]
The first form,
readkey on, enables public key encryption, creates a
public and private key pair, stores the public key in the database and
readkey.conf file in the backup directory containing the
private key. All existing and future backup session keys are
encrypted with the public key stored in the database. To restore any
backup data, the
readkey.conf file must be present and contain the
matching private key. Typically the
readkey.conf file is stored
separately from the backup, along with
readkey.conf is removed from the backup directory until a
restore or other read-type operation is needed.
-c - specifies the local backup directory
backupdir, or a
default backup directory according to built-in rules if
-c is not
-b - the number of bits to use for the RSA key. The default key
length is 2048 bits as recommended by the NIST through the year 2030.
Key lengths can be from 1024 - 4096 bits. Longer key lengths do not
affect backup performance but can cause delays during restores if many
versions are accessed. See below for details.
-p - specifies a passphrase with either
ask, meaning ask for the
env, meaning get the passphrase from the environment
HBREADPASS. This environment variable must be set (and
maybe exported) before enabling readkey.
The second form,
readkey off, disables public key encryption. The
readkey.conf file must be present because all of the backup session
keys stored in the database must be decrypted and this requires the
private key stored in
readkey.conf file remains
in the backup directory in case there is a copy of the backup stored
somewhere that has still has readkey enabled, but otherwise it can be
The third form,
readkey with no on/off command, shows whether
readkey is enabled and whether the
readkey.conf file is present. If
readkey.conf is present, a random string is encrypted with the
public key stored in the database and decrypted with the private key
readkey.conf to verify that the private key is valid.
How Does It Work?
During backups, HashBackup uses random session keys to encrypt your
backup data. These keys are stored in the database so that data can
be restored. The backup keys are symmetric keys, because the same key
is used to decrypt and encrypt data. The database is encrypted with a
key derived from
key.conf, so without it, the database and the
backup keys it contains are inaccessible. This is how HashBackup has
always provided security: the
key.conf file is kept in the local
backup directory and never copied to remote storage, so data on remote
servers is inaccessible.
However, a local user may have access to
key.conf, and in that case,
all backup data is readable. One way to prevent that is to put a
passphrase on the
key.conf file, either at
init time or with the
rekey command. This works well, but requires entering a passphrase
on every command, including the backup command, or storing the
passphrase in a file and using environment variables. It is better to
not store the passphrase of course, but then backups cannot be
automated in a cron job.
Public key encryption solves this dilemma by creating a new 2-part
key: the public key is stored in the database and is not a secret.
The private key is stored in
readkey.conf and is a secret. When
readkey is enabled, the backup session keys used to encrypt user data
are encrypted with the public key before being stored in the database.
To restore user data, the backup session keys have to be decrypted
first, and this requires the private key stored in
readkey.conf is present, all is fine. If
readkey.conf is not
present or contains the wrong key, no user data can be accessed.
readkey.conf Is NOT Present
readkey.conf is present, contains a valid key, and a passphrase is supplied if
-p was used, all HashBackup commands work normally, including read-type commands.
readkey.conf is not present, no user data can be read and this imposes restrictions:
selftest is limited to -v2 since arc files cannot be read
rm & retain can delete unneeded arc files but cannot pack arc files to remove deleted data; smaller arc files can be used to mitigate this restriction
mount fails with an I/O error on attempts to read user data; file attributes such as pathname and timestamps are still accessible, so you can do an
lsfor example, but cannot view a file
get fails immediately to avoid creating 0-length .hberror files
all other commands work normally, including backup and dedup
backup performance is the same
restore (get) may be slightly slower when accessing many versions, since each version has a backup session key and decrypting these with the private key is rather slow. The longer the key specified with
-b, the longer this takes. For example, it takes .05 seconds to decrypt a session key with a 2048-bit RSA key (the default), but takes .3 seconds (6x longer) with a 4096-bit key. On backups with many versions, such as a 1-year old hourly backup (8700 versions), restores could take up to 45 minutes longer with a 4096-bit key, but only 7 minutes longer with a 2048-bit key.
Enabling readkey does not prevent deleting or overwriting
backup data. This is not possible in a client-side program like
HashBackup without cooperation from the remote storage service. Use