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

FreeBSD Manual Pages

  
 
  

home | help
GIT-REMOTE-GCRYPT(1)					  GIT-REMOTE-GCRYPT(1)

NAME
       git-remote-gcrypt - GNU Privacy Guard-encrypted git remote

DESCRIPTION
       git-remote-gcrypt  is a git remote helper to push and pull from reposi-
       tories encrypted	with GnuPG, using a custom format.  This remote	helper
       handles URIs prefixed with gcrypt::.

       Supported  backends  are	local, rsync://	and sftp://, where the reposi-
       tory is stored as a set of files, or instead any	_giturl_ where	gcrypt
       will  store  the	 same representation in	a git repository, bridged over
       arbitrary git transport.	 See "Performance" below for backends compari-
       son.

       There is	also an	experimental rclone:// backend for early adoptors only
       (you have been warned).

       The aim is to provide confidential, authenticated git storage and  col-
       laboration using	typical	untrusted file hosts or	services.

   Installation
       o apt-get install git-remote-gcrypt on Debian and Ubuntu	systems

       o run the supplied install.sh script on other systems

   Quickstart
       Create an encrypted remote by pushing to	it:

	  git remote add cryptremote gcrypt::rsync://example.com:repo
	  git push cryptremote master
	  > gcrypt: Setting up new repository
	  > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
	  > [ more lines .. ]
	  > To gcrypt::[...]
	  > * [new branch]	master -> master

CONFIGURATION
       The following git-config(1) variables are supported:

       remote.<name>.gcrypt-participants

       gcrypt.participants
	      Space-separated  list  of	GPG key	identifiers. The remote	is en-
	      crypted to these participants and	only signatures	from these are
	      accepted.	 gpg -k	lists all public keys you know.

	      If  this	option	is not set, we encrypt to your default key and
	      accept any valid signature. This behavior	can also be  requested
	      explicitly by setting participants to simple.

	      The  gcrypt-participants	setting	on the remote takes precedence
	      over the repository variable gcrypt.participants.

       remote.<name>.gcrypt-publish-participants

       gcrypt.publish-participants
	      By default, the gpg key ids of the participants are obscured  by
	      encrypting  using	 gpg  -R. Setting this option to true disables
	      that security measure.

	      The problem with using gpg -R is that to decrypt,	gpg tries each
	      available	 secret	key in turn until it finds a usable key.  This
	      can result in unnecessary	passphrase prompts.

       gcrypt.gpg-args
	      The contents of this setting are passed  as  arguments  to  gpg.
	      E.g. --use-agent.

       remote.<name>.gcrypt-signingkey

       user.signingkey
	      (The  latter  from regular git configuration) The	key to use for
	      signing.	You should set user.signingkey if your default signing
	      key is not part of the participant list. You may use the per-re-
	      mote version to sign different remotes using different keys.

       remote.<name>.gcrypt-rsync-put-flags

       gcrypt.rsync-put-flags
	      Flags to be passed to rsync when uploading to a remote using the
	      rsync:// backend.	If the flags are set to	a specific remote, the
	      global flags, if also set, will not be applied for that remote.

ENVIRONMENT VARIABLES
       GCRYPT_FULL_REPACK
	      When set (to anything), this environment variable	forces a  full
	      repack when pushing.

EXAMPLES
       How to set up a remote for two participants:

	  git remote add cryptremote gcrypt::rsync://example.com:repo
	  git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
	  git push cryptremote master

       How to use a git	backend:

	  # notice that	the target git repo must already exist and its
	  # `next` branch will be overwritten!
	  git remote add gitcrypt gcrypt::git@example.com:repo#next
	  git push gitcrypt master

       The URL fragment	(#next here) indicates which backend branch is used.

NOTES
       Collaboration
	      The encryption of	the manifest is	updated	for each push to match
	      the participant configuration. Each pushing user must  have  the
	      public keys of all collaborators and correct participant config.

       Dependencies
	      rsync, curl and rclone for remotes rsync:, sftp: and rclone: re-
	      spectively. The main executable requires a POSIX-compliant shell
	      that supports local.

       GNU Privacy Guard
	      Both  GPG	 1.4 and 2 are supported. You need a personal GPG key.
	      GPG configuration	applies	to algorithm  choices  for  public-key
	      encryption,  symmetric  encryption, and signing. See man gpg for
	      more information.

       Remote ID
	      The Remote ID is not secret; it only ensures that	two  reposito-
	      ries signed by the same user can be distinguished.  You will see
	      a	warning	if the Remote ID changes, which	should only happen  if
	      the remote was re-created.

       Performance
	      Using an arbitrary _giturl_ or an	sftp://	URI requires uploading
	      the entire repository history with each push.  If	 your  reposi-
	      tory  history is large or	you are	pushing	over a slow link, con-
	      sider using the rsync:// transport, which	 performs  incremental
	      pushes.  Note that the latter won't work with a repository host-
	      ing service like Gitolite, GitHub	or GitLab.

       rsync URIs
	      Note that	the URI	format for the rsync backend  is,  regretably,
	      non-standard.    git-remote-gcrypt  uses	rsync://user@host:path
	      whereas	plain	rsync	uses	either	  user@host:path    or
	      rsync://user@host/path.

       rclone backend
	      In  addition  to	adding the rclone backend as a remote with URI
	      like gcrypt::rclone://remote:subdir, you must add	the remote  to
	      the rclone configuration too.  This is typically done by execut-
	      ing rclone config.  See rclone(1).

	      The rclone backend is considered experimental and	is  for	 early
	      adoptors only.  You have been warned.

   Repository format
       EncSign(X):   Sign and Encrypt to GPG key holder
       Encrypt(K,X): Encrypt using symmetric-key algorithm
       Hash(X):	     SHA-2/256

       B: branch list
       L: list of the hash (Hi)	and key	(Ki) for each packfile
       R: Remote ID

       To write	the repository:

       Store each packfile P as	Encrypt(Ki, P) a P' in filename	Hi
	 where Ki is a new random string and Hash(P') a	Hi
       Store EncSign(B || L || R) in the manifest

       To read the repository:

       Get manifest, decrypt and verify	using GPG keyring a (B,	L, R)
       Warn if R does not match	previously seen	Remote ID
       for each	Hi, Ki in L:
	 Get file Hi from the server a P'
	 Verify	Hash(P') matches Hi
	 Decrypt P' using Ki a P then open P with git

   Manifest file
       Example manifest	file (with ellipsis for	brevity):

	  $ gpg	-d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
	  542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
	  3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
	  pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
	  pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
	  keep :SHA256:f2ad50316...cd4ba67092dc4 1
	  repo :id:OYiSleGirtLubEVqJpFF

       Each item extends until newline,	and matches one	of the following:

       <sha-1> <gitref>
	      Git object id and	its ref

       pack :<hashtype>:<hash> <key>
	      Packfile hash (Hi) and corresponding symmetric key (Ki).

       keep :<hashtype>:<hash> <generation>
	      Packfile hash and	its repack generation

       repo <id>
	      The remote id

       extn <name> ...
	      Extension	field, preserved but unused.

DETECTING GCRYPT REPOS
       To detect if a git url is a gcrypt repo,	use: git-remote-gcrypt --check
       url Exit	status is 0 if the repo	exists and can be decrypted, 1 if  the
       repo uses gcrypt	but could not be decrypted, and	100 if the repo	is not
       encrypted with gcrypt (or could not be accessed).

       Note that this has to fetch the repo contents into the local git	repos-
       itory, the same as is done when using a gcrypt repo.

KNOWN ISSUES
       Every  git  push	effectively has	--force.  Be sure to pull before push-
       ing.

       git-remote-gcrypt can decide to	repack	the  remote  without  warning,
       which  means that your push can suddenly	take significantly longer than
       you were	expecting, as your whole history has to	be  reuploaded.	  This
       push might fail over a poor link.

       git-remote-gcrypt  might	 report	 a  repository as "not found" when the
       repository does in fact exist, but git-remote-gcrypt is having  authen-
       tication, port, or network connectivity issues.

SEE ALSO
       git-remote-helpers(1), gpg(1)

CREDITS
       The original author of git-remote-gcrypt	was GitHub user	bluss.

       The de facto maintainer in 2013 and 2014	was Joey Hess.

       The    current	maintainer,   since   2016,   is   Sean	  Whitton   <-
       spwhitton@spwhitton.name>.

LICENSE
       This document and git-remote-gcrypt are licensed	under identical	terms,
       GPL-3 (or 2+); see the git-remote-gcrypt	file.

							  GIT-REMOTE-GCRYPT(1)

NAME | DESCRIPTION | CONFIGURATION | ENVIRONMENT VARIABLES | EXAMPLES | NOTES | DETECTING GCRYPT REPOS | KNOWN ISSUES | SEE ALSO | CREDITS | LICENSE

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

home | help