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:
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.
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.
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.
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.
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.
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.
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.
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.
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:
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:
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:
If the key file was lost, the private key must be used to recover it from the encrypted file using the following command:
"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:
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:
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:
"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.
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.
Decrypting from stdin is not yet supported.
This manual page was written by Shachar Shemesh <shachar@debian.org>