commit 10c4445c863f88e882efced06b63becbfd07d940
from: Stefan Sperling <stsp@stsp.name>
date: Mon Jul 04 11:58:45 2022 UTC

document SSH-based signing and verification in got(1) and got.conf(5)

commit - 48f194072bb9a53b38b7ccd52d49306033ba7414
commit + 10c4445c863f88e882efced06b63becbfd07d940
blob - d73ed0c727ae4ed79cb198a89ce04838ee62689e
blob + cd6dc8e50f799c6392612e374795bd9522d1ddad
--- got/got.1
+++ got/got.1
@@ -1183,7 +1183,7 @@ Git's garbage collector or
 .It Fl n
 Do not switch and update the work tree after creating a new branch.
 .El
-.It Cm tag Oo Fl c Ar commit Oc Oo Fl m Ar message Oc Oo Fl r Ar repository-path Oc Oo Fl l Oc Ar name
+.It Cm tag Oo Fl c Ar commit Oc Oo Fl m Ar message Oc Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl s Ar signer-id Oc Oo Fl v Oc Oo Fl V Oc Ar name
 Manage tags in a repository.
 .Pp
 Tags are managed via references which live in the
@@ -1236,6 +1236,47 @@ If a
 .Ar name
 argument is passed, show only the tag with the given
 .Ar name .
+.It Fl s Ar signer-id
+While creating a new tag, sign this tag with the identity given in
+.Ar signer-id .
+.Pp
+For SSH-based signatures,
+.Ar signer-id
+is the path to a file which may refer to either a private SSH key,
+or a public SSH key with the private half available via
+.Xr ssh-agent 1 .
+.Cm got tag
+will sign the tag object by invoking
+.Xr ssh-keygen 1
+with the
+.Fl Y Ar sign
+command, using the signature namespace
+.Dq git
+for compatibility with
+.Xr git 1 .
+.It Fl v
+Verbose mode.
+During SSH signature creation and verification this option will be passed to
+.Xr ssh-keygen 1 .
+Multiple -v options increase the verbosity.
+The maximum is 3.
+.It Fl V
+Verify tag object signatures.
+If a
+.Ar name
+is specified, show and verify the tag object with the provided name.
+Otherwise, list all tag objects and verify signatures where present.
+.Pp
+.Cm got tag
+verifies SSH-based signatures by invoking
+.Xr ssh-keygen 1
+with the options
+.Fl Y Ar verify Fl f Ar allowed_signers .
+A path to the
+.Ar allowed_signers
+file must be set in
+.Xr got.conf 5 ,
+otherwise verification is impossible.
 .El
 .Pp
 By design, the
blob - 5827c264f952cb78e122d0a899886cfbedf1aab2
blob + 7b2e234dbad1c046f7c60882658a72fb41612294
--- got/got.conf.5
+++ got/got.conf.5
@@ -55,6 +55,34 @@ Because
 may fail to parse commits without an email address in author data,
 .Xr got 1
 attempts to reject author information with a missing email address.
+.It Ic allowed_signers Pa path
+Configure a
+.Ar path
+to the "allowed signers" file which contains a list of trusted
+SSH signer identities.
+The file will be passed to
+.Xr ssh-keygen 1
+during verification of SSH-based signatures with
+.Cm got tag Fl V .
+The format of the "allowed signers" file is documented in the
+ALLOWED SIGNERS section of
+.Xr ssh-keygen 1 .
+.Pp
+Verification of SSH-based signatures is impossible unless the
+.Ic allowed_signers
+option is set in
+.Nm .
+.It Ic revoked_signers Pa path
+Configure a
+.Ar path
+to the optional "revoked signers" file, which contains a list of revoked
+SSH signer identities.
+This file is passed to
+.Xr ssh-keygen 1
+during signature verification with
+.Cm got tag Fl V .
+Revoked identities are no longer considered trustworthy and verification
+of relevant signatures will fail.
 .It Ic remote Ar name Brq ...
 Define a remote repository.
 The specified