Provided by: rsyncrypto_1.14-1.2build3_amd64 bug

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