RSYNCRYPTO(1)

💖 RSYNCRYPTO(1) — the rsyncrypto manual, bestie edition 💖

Rsyncrypto User Manual · section 1

---

✨ NAME ✨

rsyncrypto — encryption that's rsync friendly, no cap 🦋

---

🌸 SYNOPSIS 🌸

okay so here's the vibe, literally just the shapes it takes:

rsyncrypto [options] srcfile dstfile keyfile key
rsyncrypto [options] -r srcdir dstdir keysdir key
rsyncrypto [options] --filelist=file srcdir dstdir keysdir key

---

💅 DESCRIPTION 💅

so like, this page is the whole lore on the rsyncrypto command. sit down, get comfy 🎀

rsyncrypto is a utility that encrypts a file (or a whole directory structure, she's flexible 💁) in a way that guarantees local changes to the plain text file will result in local changes to the cipher text file. and why do we care?? because that means when you rsync the encrypted files over to another machine, rsync's wire efficiency barely takes a hit. tiny impact. she ate. 🔥

rsyncrypto encrypts files using a symmetric block cipher (AES). every single file gets its own unique key, main character energy only. and that file key gets stored in two locations:

• the "key" file
• inside the encrypted file itself 👀

the second copy is encrypted using an RSA public key, which can be shared across all your encrypted files. one key to rule them all, periodt.

---

🫶 Decryption: two flavors 🫶

decrypting can go down one of two paths:

Warm Decryption : keyfile is used to decrypt srcfile into dstfile. the cozy route. ✨

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. the "we're so back" route 😭

⚠️ if both keyfile and the private key are not available, decryption cannot take place. like, at all. gone. 💀

typically this means you'd 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. keep that key safe bestie, fr fr 🔑

---

👑 ARGUMENTS 👑

the meaning of the arguments depends on whether the -r, --filelist and -d flags exist. it's giving context-sensitive 🦋

• srcfile or srcdir — this is the source for the operation. it'll 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. either way, src must exist prior to running rsyncrypto. no exceptions.
• 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 it's the latter, the key files will have the same name as the plain text files. cute and consistent ✨
• 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. iykyk 📜

---

if dst does not exist, it will be created. but the directory in which it is to be created must exist prior to running rsyncrypto. don't skip that step bestie 🙈

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

✨ OPTIONS ✨

okay bestie, these programs follow the usual GNU command line syntax, which means long options start with two dashes (--). slay. here's the whole menu 💅

• -h, --help — shows you a lil summary of all the options. a vibe check, basically 🌸
• -V, --version — prints out the current version number. know ur version, queen 👑
• -d, --decrypt — decrypts src into dst. the default behavior (no -d) is to encrypt src into dst, and create the keyfile if it doesn't already exist. 💖
• -r, --recurse — recursively encrypt/decrypt a whole entire directory structure. every file under srcdir gets encrypted into files of the same name and path (almost the same, see --trim) under dstdir. and if they're not already there, a key file gets created for each file under keydir. it's giving full-send 🦋
• --filelist=file — file is the name of a file (or - for stdin) that holds a list of files and directories to process. if a name matches a directory, the whole directory gets encrypted in recursive mode.

Absolute file names inside file are taken literally, but they're stored as relative (stripped of the leading slash and drive name where applicable). relative names get interpreted in relation to the directory name given by the srcdir argument. and all names are trimmed according to the --trim option.

dstdir is interpreted the same way as with the -r option.

--filelist and -r are mutually exclusive, bestie. pick a lane 🫶

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 got changed in version 1.13 because the old 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 — checks the src and destination modified time (see --modify-window) before doing the operation. if the modified time is the same, it assumes the files are the same too and skips the operation entirely. and notice how, unlike rsync, file sizes are not compared. that's because the file size is expected to change during the encryption (and thus decryption) operation. no size-shaming here 💅
• --risky-writes — usually, when rsyncrypto writes a file, it uses a temporary name and moves the file to its final name only when it's successfully done. this serves two purposes. during encryption, it prevents the false sense of security that could arise if rsyncrypto gets interrupted — no partial file just vibing there (and in case of an update, it keeps the old backup). it also means that restarting rsyncrypto will let it correctly detect whether the operation needs to be repeated. during decryption, it prevents overwriting a file until we're certain we can decrypt its source. 🎀

the main problem with this approach: if the file being written is large, the file system needs enough space for two copies of it for the whole duration of the operation. also, if hard links are maintained, the default rsyncrypto behavior will break the link. 😭

so specify --risky-writes to make rsyncrypto directly overwrite the existing file using the final name. live dangerously, i guess 🔥

• --modify-window=num — only applicable when -c is in effect. when comparing file modification times, treat modification times that are num seconds apart as equal. 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 the original and the 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 lets you pass 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 rsync is used to synchronize it remotely. using this option lets you focus rsync on only those files that are known to have changed, instead of having it send the entire file list to the remote machine, which makes 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 together 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's possible to have files that have been changed on disk by a previous invocation of rsyncrypto, but were overwritten by a later invocation and don't 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's possible for logfile to not 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, that means file names get 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 the parameter. if you're 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 get stored in a single directory. when encrypting large directory trees, this can result in rather big directories. using "--ne-nesting" will split the files into sub directories, according to random bits that are part of the encrypted file name. num is the number of directories to nest. 🌳
• --trim=num — determines 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 don't 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'll 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 — don't 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 doesn't 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 the command line, or a version with different defaults, dictates 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 it several times to be more verbose. the more the merrier 🗣️

---

🌈 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, bestie. they are not dangerous, in that they will never cause data loss. any value should still allow decryption of the file. but 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. hands off, babe 💅

✂️ THE TRIM OPTION ✂️

Okay so when you run rsyncrypto in recursive mode, it literally rebuilds the directory structure from under srcdir over under dstdir, and it strips one directory off the path. Like imagine you have a directory structure that looks like:

a/b/c/file

If you run rsyncrypto with srcdir as "a/b" and dstdir as "f", it will create:

f/b/c/file

The --trim option lets you say exactly how many parts to trim from srcdir when it's creating directories under dstdir and keydir. So in the example above, if we said --trim=0, then "f/a/b/c/file" would have been created. And if we said --trim=2, then "f/c/file" would have been created. math is mathing.

But bestie, it is an error to give a trim value that's higher than the number of directory parts actually in srcdir. In the example above, --trim=3 would result in an error. So don't do that. 💅

---

🔒 SECURITY 🔒

So the roll values affect — to a not totally known degree — how much information gets "leaked" between plain text and cipher text. Spooky. 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. We hope these values will be considered secure enough for most usages. Fingers crossed.

However, if your country's fate is at stake, use a non-rsync optimized encryption, such as the one provided by openssl(1). Like, actual geopolitical stakes? Please use openssl. 👑

---

📚 EXAMPLES AND TUTORIAL 📚

Before you even start using 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. Iconic, it only cares about the 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. Read the fine print, bestie.

"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. Reuse those keys, it's giving sustainable.

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". Recovery era!

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". Path trimming is the moment.

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". List mode activated.

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". Name encryption is such a serve.

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. Do not skip this, bestie. 😭

---

🐛 BUGS 🐛

• It is not yet possible to decrypt using password protected private key.
• Decrypting from stdin is not yet supported.

Not me waiting for stdin decryption support. 🙈

---

👀 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

---

And that's the whole vibe. This iconic page comes from Lingnu Open Source Consulting, dated October 22, 2008, and it's literally RSYNCRYPTO(1). Periodt. 💅🫶