Skip to content

Protocol.md

Latest commit

 

History

History
134 lines (103 loc) · 5.11 KB

Protocol.md

File metadata and controls

134 lines (103 loc) · 5.11 KB

The zeitgitter Protocol

The zeitgitter protocol sits on top of HTTPS and can be used to obtain timestamped, signed git objects to be added to one's git repository, typically using the git timestamp command.

Like this, the timestamping server does not need to know any contents of your git repository, with the exception of some hashes and, when signing a tag, also the name of the tag. Most importantly, the timestamper does not learn about:

  • then contents of your files
  • your users
  • the number or times of any commits not submitted for timestamping

Obtaining public key of timestamper

GET request to the URL with the following variables:

  • request: get-public-key-v1

Obtaining a tag signature

POST request to URL with the following variables:

  • request: stamp-tag-v1
  • commit: The SHA-1 commit ID to be tagged and timestamped
  • tagname: The name of the tag, limited to ASCII digits, letters, dash and underscore of at most 100 characters. Must start with a letter.

Returns a signed git tag object referring to the commit object in the response body as follows:

object <commit object ID>
type commit
tag <tagname>
tagger <timestamper name> <timestamper email> <Unix time> +0000

<message by the timestamper>
-----BEGIN PGP SIGNATURE-----

[…]
-----END PGP SIGNATURE-----

Before adding the object to the git object store, the client should verify that:

  • The commit ID matches what it sent
  • The tag name matches what it sent
  • The timestamper name/email matches what it expects; its length does not exceed 200 characters
  • The Unix time lies between the start of the request and the end of the request, within a given fuzz parameter (e.g., 30 seconds)
  • The message contains only ASCII printable characters and newline (\n, ' '…'~'); its length does not exceed 1000 characters
  • The PGP signature contains only ASCII printable characters and newline; its length does not exceed 4000 characters
  • The PGP signature verifies as a detached signature to the remainder of the tag's contents (the contents are treated as binary data, no text normalization is done).
  • The PGP signature timestamp also lies within the window of the Unix time as specified above (it does not necessary need to be identical, as the timestamping process does not make it easy to guarantee this)
  • Only a single signature should be present

POST parameters can submitted in either application/x-www-form-urlencoded or multipart/form-data format.

Obtaining a branch signature

POST request to the URL with the following variables:

  • request: stamp-branch-v1
  • commit: The SHA-1 commit ID to be timestamped
  • parent (optional): The SHA-1 commit ID to be listed as the branch parent
  • tree: The SHA-1 tree ID of the file contents

Returns a signed git commit, looking like a merge from the commit to the branch of the parent, but with the exact file contents of the tree at commit:

tree <tree ID>
parent <parent ID>
parent <commit ID>
author <timestamper name> <timestamper email> <Unix time> +0000
committer <timestamper name> <timestamper email> <Unix time> +0000
gpgsig -----BEGIN PGP SIGNATURE-----
 […]
 -----END PGP SIGNATURE-----

<message by the timestamper>

Before adding the object to the git object store, similar to the tag signature behavior above, the client should verify that:

Assuming you branch-sign every commit of the master branch into the timestamp branch, the two will develop in parallel, with timestamp being a timestamper-signed equivalent of the former.

Many signatures on many projects

If your organisation would like to issue many timestamps a day, we recommend operating your own local zeitgitter instance and timestamp internally against your local instance and only obtain timestamps for your zeitgitter repository from outside source(s). This results in several advantages:

  • No information about your commit rates is leaked.
  • No information about your developer's IP addresses is leaked.
  • You can assure a level of service according to your own needs.
  • You can adjust the security parameters according to your own needs.
  • The global network of timestamping servers is being loaded less, …
  • … even if you cross-timestamp against multiple outside sources.
  • Using multiple cross-timestamps will increase the trust.

(We would appreciate if you would also allow other public timestampers to cross-timestamp against your server to increase the overall trust in the system.)

✅ Help us building an efficient hierarchy of trusted timestampers, or even a complete web of timestampers.