Provided by: rsyncrypto_1.14-1.2build3_amd64 
NAME
rsyncrypto - rsync friendly encryption
SYNOPSIS
rsyncrypto [options] srcfile dstfile keyfile key
rsyncrypto [options] -r srcdir dstdir keysdir key
rsyncrypto [options] --filelist=file srcdir dstdir keysdir key
DESCRIPTION
This manual page documents the rsyncrypto command.
rsyncrypto is a utility that encrypts a file (or a directory structure) in a way that ensures that local
changes to the plain text file will result in local changes to the cipher text file. This, in turn,
ensures that doing rsync to synchronize the encrypted files to another machine will have only a small
impact on rsync's wire efficiency.
rsyncrypto will encrypt files using a symmetric block cipher (AES). Each file is encrypted using a unique
key. The file key is stored in two locations. One is the "key" file, and the second is inside the
encrypted file itself. The second copy is encrypted using a RSA public key, which can be shared for all
encrypted files.
Decrypting the file can take place in one of two forms:
Warm Decryption
keyfile is used to decrypt srcfile into dstfile.
Cold Decryption
If keyfile is lost and key is the private key for the RSA encryption, extract and create keyfile
from the encrypted srcfile, and create both keyfile and dstfile.
If both keyfile and the private key are not available, decryption cannot take place. Typically, this
means that you would either want to transfer the encrypted files in whatever way (secure or insecure, but
probably rsync :), and keep the plain text file, as well as the key file, secure. As long as you saved
the RSA private key, you can reconstruct them both.
ARGUMENTS
The argument meaning depends on the existence of the -r, --filelist and -d flags.
srcfile or srcdir
This is the source for the operation. This will be the plain text file for encryption, and the
cipher text file for decryption. If the -r option is given, srcdir is the directory from which
files are to be encrypted/decrypted. If the --filelist option is given, srcdir is the directory in
relation to which the file names given by the filelist file are interpreted. If neither are given,
srcfile is the file to be encrypted/decrypted. In any case, src must exist prior to running
rsyncrypto.
dstfile or dstdir
Similar to src, this is the destination of the operation. It will be the plain text to be created
if -d was given, or the encrypted file otherwise.
keyfile or keydir
The file holding the symmetric key for the encryption, or a directory in which symmetric key files
reside. If the later, the key files will have the same name as the plain text files.
key This file can either be a X509 certificate holding a public key, or a PEM format private key. The
private key is never needed unless a cold decryption is required. See the req(1) or x509(1) manual
pages for more info.
If dst does not exist, it will be created. The directory in which it is to be created must exist prior to
running rsyncrypto.
If encrypting, and a symmetric key for the file is found, the same parameters will be used for the
encryption unless the --fr or --fk options are used. If that's the case, the key file is going to be
replaced with the correct parameters.
OPTIONS
These programs follow the usual GNU command line syntax, with long options starting with two dashes
(`--').
-h, --help
Show summary of options.
-V, --version
Print out the current version number.
-d, --decrypt
Decrypt src into dst. The default behavior is to encrypt src into dst, and create keyfile if it
does not exist.
-r, --recurse
Recursively encrypt/decrypt an entire directory structure. All files under srcdir will be
encrypted to files of the same name and path (almost, see "--trim") under dstdir. If not already
there, a key file will be created for each file under keydir.
--filelist=file
File is the name of a file (or "-" for stdin) that has a list of files and directories to process.
If the name matches a directory, the entire directory is encrytped in recursive mode.
Absolute file names in file are taken literally, but are stored as relative (stripped of the
leading slash and drive name where applicable). Relative names are interpreted in relation to the
directory name given by the srcdir argument. All names are trimmed according to the --trim
option.
dstdir is interpreted as with the -r option.
--filelist and -r are mutually exclusive.
BACKWARDS INCOMPATIBILITY NOTICE: Up until version 1.12 of rsyncrypto, --filelist did not receive
any parameters, and the file name to use was taken from the src argument. This was changed in
version 1.13 because the previous way could cause problems when the file list was created in
relation to a different work directory than the one in use. Pass `.' as srcdir to get the old
semantics.
-c, --changed
Check the src and destination modified time (see --modify-window) prior to performing the
operation. If the modified time is the same, assume that the files are also the same, and skip the
operation. Notice that unlike rsync, file sizes are not compared. This is because the file size is
expected to change during the encryption (and thus decryption) operation.
--risky-writes
Usually, when rsyncrypto writes a file, it uses a temporary name and moves the file to its final
name when successfully done. This serves two purposes. During encryption, this prevents the false
sense of security that may arise in case of an rsyncrypto interruption by preventing a partial
file from being present (and in case of an update, by keeping the old backup). This also ensures
that restarting rsyncrypto will enable it to correctly detect whether the operation needs to be
repeated. During decryption, this prevents overwriting a file until we are certain we can decrypt
its source.
The main problem with this approach is that, if the file being written is large, the file system
needs to have enough space for two copies of it for the duration of the operation. Also, if hard
links are maintained, the default rsyncrypto behavior will break the link.
Specify --risky-writes to make rsyncrypto directly overwrite the existing file using the final
name.
--modify-window=num
Only applicable when -c is in effect. When comparing file modification times, treat as equal
modification times that are num seconds apart. Default value is zero.
This option is most useful when the encrypted file is stored on a FAT file system. FAT can only
store modification time with a 2 seconds accuracy. This may result in the modification time
changing between original and encrypted file. In such a case, --modify-window=1 should be used.
--export-changes=logfile
Whenever encrypting or deleting a file, write the file's name to logfile. This allows passing
logfile to rsync(1) using the --include-from rsync option.
This option is mostly useful if rsyncrypto is used to repeatedly encrypt a huge directory tree,
and then using rsync to synchronize it remotely. The use of this option allows focusing rsync on
only those files that are known to have changed, rather than have it send the entire file list to
the remote machine, making the rsync operation faster. It should be noted that rsync version 3
starts the actual file transfer while it is still transferring the file list, making the
performance gain from this option less noticeable.
When using this option in conjunction with rsync, keep in mind that logfile is zeroed out before
being written into. This means that unless there is at least one completely successful rsync
operation for each rsyncrypto invocation, it is possible to have files that have been changed on
disk by a previous invocation of rsyncrypto, but were over written by a later invocation and do
not show up in the latest version of logfile. In other words, if rsyncrypto is run more than once
between two completely successful invocations of rsync, it is possible for logfile not to be
complete. Use this option at your own risk!
It is highly recommended that you upgrade to rsync version 3 or higher rather than rely on this
option.
-n, --name-encrypt=translation_file
Encrypt the file name. If this option is specified, this means that file names are encrypted as
well. This is done by changing the name of the encrypted file to a random string of characters,
and storing the translation in the file given as parameter. If working in recursive mode, this
file is automatically also included in the encryption, and is given the fixed name "filemap". This
is done so that decryption of the file names is possible when the symmetric keys are lost.
--ne-nesting=num
When the --name-encrypt option is used, by default all mangled file names are stored in a single
directory. When encrypting large directory trees, this can result in rather big directories. Using
"--ne-nesting" will split the files to sub directories, according to random bits that are part of
the encrypted file name. "num" is the number of directories to nest.
--trim=num
Determine how many directory levels to trim from the beginning of the srcdir path when creating
directories under dstdir. The default value is 1. See THE TRIM OPTION for more details.
--delete
When in recursive mode, delete files and directories under dstdir that do not exist under srcdir.
--delete-keys
When deleting files, also delete their symmetric key and file name mapping (if applicable). When
only --delete is used, the symmetric key and file mapping are kept, so that if the file is
recreated, it will be rsyncable with the original file. This option implies --delete.
-bnum --keybits=num
Specify the block cipher's key size. For AES, these can be 128, 192 or 256. Note that unless the
--fr or --fk options are also specified, this will only affect files for which no keyfile exists.
--noatime=num
(Only on some platforms, most notably Linux). The platform usually keeps track of when files were
last being accessed. Since rsyncrypto is typically used for backup, it opens the files it encrypts
with the O_NOATIME option, which is a Linux specific extension that tells the system not to update
the file's access time. When opening a file where the opening process is not owned by the file
owner, an attempt to open the file with O_NOATIME will cause the open to fail with "permission
denied".
num can be one of these options: 0 means do not use O_NOATIME at all. 1 (the default) means
attempt to only use O_NOATIME if rsyncrypto thinks it will not cause a permission denied error. 2
means to use O_NOATIME always.
--no-archive-mode
Do not try to preserve timestamps. This option is incompatible with -c.
--gzip=path
By default, rsyncrypto will compress the plain text prior to encrypting it. In order not to become
rsync unfriendly due to the compression, rsyncrypto will search the path for an instance of
gzip(1) that supports the --rsyncable option. If the system's default gzip does not support this
option (all Debian and derivatives, as well as some others, support it), use this option to tell
rsyncrypto to use a different instance of gzip. The tests directory of rsyncrypto's source has a
file called "gzip", that does NULL compression by redirecting the input and output to cat(1).
--roll-win=num, --roll-min=num, --roll-sensitivity=num
Affects the rolling block algorithm. See NOTES.
--fk, --fr
If command line, or a version with different defaults, dictate different values for the --roll-*
options or the -b option, these will only affect files for which keyfile does not yet exist.
specifying the --fk or --fr will recreate keyfile if it has values different than those in the
previous key file.
-v, --verbose
Increase verbosity level. Specify several times to be more verbose.
NOTES
encrypting stdin
If srcfile is given as `-', the plain text data will be read from stdin. This does not yet work for
decompression (see BUGS).
--roll-win=num, --roll-min=num, --roll-sensitivity=num
These values affect some of the inner workings of rsyncrypto's decision making. In particular, these
affect how rsyncrypto decides when to revert to the IV.
These options should not be played with unless you understand what you are doing. They are not dangerous,
in that they will never cause data loss. Any value should still allow decryption of the file. They do
have an affect on rsync's efficiency.
These options are only there to allow quick response in case a security problem pops up with their
default values. If that happens, an advisory may come out giving new values to fill in as a workaround.
Until that happens, most users are advised to leave these options alone.
THE TRIM OPTION
When running rsyncrypto in recursive mode, the directory structure under srcdir is re-created under
dstdir, with one directory stripped from the path. In other words, if we have a directory structure which
has:
a/b/c/file
running rsyncrypto with srcdir of "a/b", and dstdir of "f" will create "f/b/c/file".
The --trim options lets the user say how many parts to trim from srcdir when creating directories under
dstdir and keydir. If, in the above example, we said --trim=0 then "f/a/b/c/file" would have been
created. Likewise, if we said --trim=2 then "f/c/file" would have been created.
It is an error to give a trim value which is higher than the number of directory parts actually in
srcdir. In the above example, --trim=3 would result in an error.
SECURITY
The roll values affect, to a not totally known degree, how much information is "leaked" between plain
text and cipher text. The default values are supposed to leak less than 20 bits of aggregated information
about the plain text file for every 8KB, in the worst case. These values, we hope, will be considered
secure enough for most usages. However, if your country's fate is at stake, use a non-rsync optimized
encryption, such as the one provided by openssl(1).
EXAMPLES AND TUTORIAL
Before starting to use rsyncrypto you will need a public key in X509 certificate format. The quickest way
to generate one of these is using the openssl(1) package. To generate a new 1536 bit RSA key as
"backup.key", and store the corresponding unencrypted public key in "backup.crt", use the following
command:
openssl req -nodes -newkey rsa:1536 -x509 -keyout backup.key -out backup.crt
It does not matter what you answer for the certificate details, or when you set it to expire. Rsyncrypto
ignores everything in the certificate but the actual key.
To encrypt file "data" into "data.enc", storing the file's specific key at "data.key", run:
rsyncrypto data data.enc data.key backup.crt
Anywhere in these examples that "backup.crt" is used, "backup.key" can be used as well. The above could
also have "backup.key" as the last argument. If these examples list "backup.key" specifically, then it
means that "backup.crt" cannot be used instead.
"data.enc" will be created. If "data.key" exists from a previous run, then the newly created "data.enc"
will have the same symmetric key and other attributes, thus maintaining the rsync friendliness of the
encryption. It is therefor important to provide any previous key file for the data if one is available.
The command line to decrypt the file depends on whether you have the key file used when the file was
encrypted. If you do, then decryption can take place using only the public key, with the following
command:
rsyncrypto -d data.enc data.dec data.key backup.crt
If the key file was lost, the private key must be used to recover it from the encrypted file using the
following command:
rsyncrypto -d data.enc data.dec data.key backup.key
"data.key" will be created by the above command, as well as "data.dec".
Use of rsyncrypto to encrypt whole directories is similar, with directory names replacing file names in
the above example. To encrypt the content of a directory called "data" to a directory called "enc",
storing the symmetric keys in a directory called "keys", run the following command:
rsyncrypto -r data enc keys backup.crt
As before the directories "enc" and "keys" will be created if they do not already exist. The directory
structure under "plain" will be duplicated under "enc" and under "keys". That is, if there is a file
called "foo" under "data", an encrypted files called "foo" will be created under "enc", and a key file
named "foo" will be created under "keys". In other words, the first part of the path to "data/foo" (the
part that says "data") is eliminated from the path, and this determines the name of the files under "enc"
and "keys".
If a different trimming is required, the --trim option can be used. To have rsyncrypto create
"enc/data/foo" instead of the above, use the following command:
rsyncrypto -r --trim=0 data enc keys backup.crt
Instead of taking all files from a single directory, it is possible to supply rsyncrypto with a list of
files and directories which to encrypt. This is done using the --filelist option, like so:
rsyncrypto --filelist --trim=0 list enc keys backup.crt
"enc" and "keys" retain the same meaning as before. "list" is a text file with a list, one per line, of
files to encrypt. The --trim=0 option says that if list contains a line saying "/home/foo/bar" which
states the name of a file, then an encrypted file called "enc/home/foo/bar" will be created. Without it,
the file will be called "enc/foo/bar". Likewise, with --trim=2, the file would be created as "enc/bar".
It is often a problem that the file names are not encrypted. If that is the case, we can ask rsyncrypto
to encrypt the file names, as well as the actual files. Rsyncrypto does not actually encrypt the file
names. Instead, it replaces the actual file name with a random series of characters. The mapping between
the actual file name and the garbled name is stored in a mapping file.
rsyncrypto --name-encrypt=map --trim=0 -r plain enc keys backup.crt
This will encrypt the "plain" directory structure into enc, exactly as before. Unlike before, all files
will be directly under the "enc" directory, and will be named as a meaningless garble. A file called
"map" will be created under the current directory that contains a map between the gabled and the real
name of the file. In addition, two files, called "enc/filemap" and "keys/filemap", will also be created.
These are the encrypted and key file corresponding to the "map" file mentioned above. During decryption,
if "map" does not exist, it will be created by decrypting "enc/filemap".
Important note: When performing file name encryption, it is vitally important to give the correct --trim
values, both during encryption and during decryption. Failing to do so will cause rsyncrypto to search
for non-existing file names, and to fail to locate the files to decrypt.
BUGS
It is not yet possible to decrypt using password protected private key.
Decrypting from stdin is not yet supported.
SEE ALSO
rsync(1), gzip(1), openssl(1), x509(1), req(1).
AUTHOR
rsyncrypto was written by Shachar Shemesh for Lingnu Open Source Consulting ltd. http://www.lingnu.com
This manual page was written by Shachar Shemesh <shachar@debian.org>
PROJECT HOMEPAGE
http://rsyncrypto.lingnu.com
Lingnu Open Source Consulting October 22, 2008 RSYNCRYPTO(1)