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 creates a 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 key.conf and dest.conf, then 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 used

-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 passphrase, or env, meaning get the passphrase from the environment variable 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. The 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 deleted.

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 in 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. If readkey.conf is present, all is fine. If readkey.conf is not present or contains the wrong key, no user data can be accessed.

Restrictions When readkey.conf Is NOT Present

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

When 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 ls for 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 the config options admin-passphrase, enable-commands, and disable-commands, and dest load to mitigate this risk.