README.rst 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. =================
  2. git-remote-gcrypt
  3. =================
  4. --------------------------------------
  5. GNU Privacy Guard-encrypted git remote
  6. --------------------------------------
  7. :Manual section: 1
  8. Description
  9. ===========
  10. Remote helper programs are invoked by git to handle network transport.
  11. This helper handles `gcrypt::` URLs that will access a remote repository
  12. encrypted with GPG, using our custom format.
  13. Supported locations are `local`, `rsync://` and `sftp://`, where the
  14. repository is stored as a set of files, or instead any `<giturl>` where
  15. gcrypt will store the same representation in a git repository, bridged
  16. over arbitrary git transport.
  17. The aim is to provide confidential, authenticated git storage and
  18. collaboration using typical untrusted file hosts or services.
  19. PLEASE help us evaluate how well we meet this design goal!
  20. .. NOTE:: This is a development version -- Repository format MAY CHANGE.
  21. Quickstart
  22. ..........
  23. * Install ``git-remote-gcrypt`` by running the supplied ``install.sh`` script.
  24. * Create an encrypted remote by pushing to it::
  25. git remote add cryptremote gcrypt::rsync://example.com:repo
  26. git push cryptremote master
  27. > gcrypt: Setting up new repository
  28. > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
  29. > [ more lines .. ]
  30. > To gcrypt::[...]
  31. > * [new branch] master -> master
  32. Configuration
  33. =============
  34. The following ``git-config(1)`` variables are supported:
  35. ``remote.<name>.gcrypt-participants``
  36. ..
  37. ``gcrypt.participants``
  38. Space-separated list of GPG key identifiers. The remote is encrypted
  39. to these participants and only signatures from these are accepted.
  40. ``gpg -k`` lists all public keys you know.
  41. If this option is not set, we encrypt to your default key and accept
  42. any valid signature. This behavior can also be requested explicitly
  43. by setting participants to ``simple``.
  44. The ``gcrypt-participants`` setting on the remote takes precedence
  45. over the repository variable ``gcrypt.participants``.
  46. ``user.signingkey``
  47. (From regular git configuration) The key to use for signing. You
  48. should set ``user.signingkey`` if your default signing key is not
  49. part of the participant list.
  50. Environment Variables
  51. =====================
  52. *GCRYPT_FULL_REPACK*
  53. This environment variable forces full repack when pushing.
  54. Examples
  55. ========
  56. How to set up a remote for two participants::
  57. git remote add cryptremote gcrypt::rsync://example.com:repo
  58. git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
  59. git push cryptremote master
  60. How to use a git backend::
  61. # notice that the target git repo must already exist and its
  62. # `next` branch will be overwritten!
  63. git remote add gitcrypt gcrypt::git@example.com:repo#next
  64. git push gitcrypt master
  65. The URL fragment (`#next` here) indicates which backend branch is used.
  66. Notes
  67. =====
  68. Collaboration
  69. The encryption of the manifest is updated for each push to match the
  70. participant configuration. Each pushing user must have the public
  71. keys of all collaborators and correct participant config. You can
  72. commit a keyring to the repo; further key management features do not
  73. yet exist.
  74. Dependencies
  75. ``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:``
  76. respectively. The main executable requires a POSIX-compliant shell
  77. that supports ``local``.
  78. GNU Privacy Guard
  79. Both GPG 1.4 and 2 are supported. You need a personal GPG key. GPG
  80. configuration applies to algorithm choices for public-key
  81. encryption, symmetric encryption, and signing. See ``man gpg`` for
  82. more information.
  83. Remote ID
  84. The Remote ID is not secret; it only ensures that two repositories
  85. signed by the same user can be distinguished. You will see
  86. a warning if the Remote ID changes, which should only happen if the
  87. remote was re-created.
  88. Repository Format
  89. .................
  90. | `EncSign(X):` Sign and Encrypt to GPG key holder
  91. | `Encrypt(K,X):` Encrypt using symmetric-key algorithm
  92. | `Hash(X):` SHA-2/256
  93. |
  94. | `B:` branch list
  95. | `L:` list of the hash (`Hi`) and key (`Ki`) for each packfile
  96. | `R:` Remote ID
  97. |
  98. | To write the repository:
  99. |
  100. | Store each packfile `P` as `Encrypt(Ki, P)` → `P'` in filename `Hi`
  101. | where `Ki` is a new random string and `Hash(P')` → `Hi`
  102. | Store `EncSign(B || L || R)` in the manifest
  103. |
  104. | To read the repository:
  105. |
  106. | Get manifest, decrypt and verify using GPG keyring → `(B, L, R)`
  107. | Warn if `R` does not match previously seen Remote ID
  108. | for each `Hi, Ki` in `L`:
  109. | Get file `Hi` from the server → `P'`
  110. | Verify `Hash(P')` matches `Hi`
  111. | Decrypt `P'` using `Ki` → `P` then open `P` with git
  112. Manifest file
  113. .............
  114. Example manifest file (with ellipsis for brevity)::
  115. $ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
  116. 542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
  117. 3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
  118. pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
  119. pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
  120. keep :SHA256:f2ad50316...cd4ba67092dc4 1
  121. repo :id:OYiSleGirtLubEVqJpFF
  122. Each item extends until newline, and matches one of the following:
  123. ``<sha-1> <gitref>``
  124. Git object id and its ref
  125. ``pack :<hashtype>:<hash> <key>``
  126. Packfile hash (`Hi`) and corresponding symmetric key (`Ki`).
  127. ``keep :<hashtype>:<hash> <generation>``
  128. Packfile hash and its repack generation
  129. ``repo <id>``
  130. The remote id
  131. ``extn <name> ...``
  132. Extension field, preserved but unused.
  133. See Also
  134. ========
  135. git-remote-helpers(1), gpg(1)
  136. License
  137. =======
  138. This document and git-remote-gcrypt are licensed under identical terms,
  139. GPL-3 (or 2+), see the git-remote-gcrypt file.
  140. .. this document generates a man page with rst2man
  141. .. vim: ft=rst tw=72 sts=4