RSYNCRYPTO(1) | Rsyncrypto User Manual | RSYNCRYPTO(1) |
NAME¶
rsyncrypto - rsync friendly encryptionSYNOPSIS¶
rsyncrypto [options] srcfile dstfile keyfile keyDESCRIPTION¶
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 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.
PARAMETERS¶
The parameters meaning depend on the existence of the -r 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. Otherwise, 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.
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
- The first argument is a pointer to a file (or "-" for stdin) that has a list of files to process. Any name ending with a "/" is taken to be a directory in recursive mode, and any other name is a file name. The second argument is a directory where the files are encrypted to. --filelist and -r are mutually exclusive.
- -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.
- --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.
- --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.
- -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. "n" 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 --fkP 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".
- --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 fro 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.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.comJuly 22, 2008 | Lingnu Open Source Consulting |