Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RSYNCRYPTO(1)		    Rsyncrypto User Manual		 RSYNCRYPTO(1)

NAME
       rsyncrypto - rsync friendly encryption

SYNOPSIS
       rsyncrypto [options] srcfile dstfile keyfile key
       rsyncrypto [options] -r 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	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  src-
	      file, and	create both keyfile and	dstfile.

       If  both	keyfile	and the	private	key are	not available, decryption can-
       not 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	recon-
       struct them both.

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

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

       -c, --changed
	      Check  the  src and destination modified time (see --modify-win-
	      dow) 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  com-
	      pared.  This is because the file size is expected	to change dur-
	      ing 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  cer-
	      tain 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	 modi-
	      fication	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 synchro-
	      nize 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 ver-
	      sion 3 starts the	actual file transfer while it is still	trans-
	      ferring  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 success-
	      ful 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 directo-
	      ries. Using "--ne-nesting" will split the	files to sub  directo-
	      ries,  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  dst-
	      dir 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  usu-
	      ally  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	deriv-
	      atives, 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  ver-
	      bose.

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.

       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	infor-
       mation is "leaked" between plain	text and cipher	text. The default val-
       ues are supposed	to leak	less than 20 bits  of  aggregated  information
       about  the plain	text file for every 8KB, in the	worst case. These val-
       ues, we hope, will be considered	secure enough for  most	 usages.  How-
       ever,  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	direc-
       tory names replacing file names in the above example.  To  encrypt  the
       content of a directory called "data" to a directory called "enc", stor-
       ing 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	dupli-
       cated  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 char-
       acters. 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  Con-
       sulting ltd.  http://www.lingnu.com

       This manual page	was written by Shachar Shemesh <shachar@debian.org>

PROJECT	HOMEPAGE
       http://rsyncrypto.lingnu.com

Lingnu Open Source Consulting	 July 22, 2008			 RSYNCRYPTO(1)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | OPTIONS | NOTES | THE TRIM OPTION | SECURITY | EXAMPLES AND TUTORIAL | BUGS | SEE ALSO | AUTHOR | PROJECT HOMEPAGE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rsyncrypto&sektion=1&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help