rsyncrypto - rsync friendly encryption

rsyncrypto [options] srcfile dstfile keyfile key

rsyncrypto [options] -r srcdir dstdir keysdir key

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.

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.

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.

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.

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 src into dst. The default behavior is to encrypt src into dst, and create keyfile if it does not exist.

-r

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

Check the src and destination modified time (in one second resolution) 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.

-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=<n>

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 subdirectories, 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.

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

--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 (only Debian's does, at the time of this writing), 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

Increase verbosity level. Specify several time to be more verbose.

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

--meta-encrypt

The meta encrypt option allows encryption of file names, as well as other meta data. This is not so much "encryption", as it is table replacement. File names are replaced by a random string of characters, and the translation table is stored in a special file, that is given as a parameter to the "meta-encrypt" argument.

If the "-r" option is used, this file is automatically encrypted too. To allow cold decryption (i.e. - decryption using only the assymetric private key) this file's name is not encrypted itself, and it will always be called "filelist".

The filelist file format is a binary representation of the meta data for the files. The format is documented seperately.

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

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.

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

Soon.

Not providing a correct key file may result in segmentation fault.

It is not yet possible to decrypt using password protected private key.

Decrypting from stdin is not yet supported.

rsync(1), gzip(1), openssl(1), x509(1), req(1).

rsyncrypto was written by Shachar Shemesh for Lingnu Open Source Consulting ltd. http://www.lingnu.com

This manual page was written by Shachar Shemesh <debianpkg@shemesh.biz>

http://sourceforge.net/projects/rsyncrypto