Commit 10c4445c863f88e882efced06b63becbfd07d940
2022-07-04T11:58:45
document SSH-based signing and verification in got(1) and got.conf(5)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
diff --git a/got/got.1 b/got/got.1
index d73ed0c..cd6dc8e 100644
--- a/got/got.1
+++ b/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
diff --git a/got/got.conf.5 b/got/got.conf.5
index 5827c26..7b2e234 100644
--- a/got/got.conf.5
+++ b/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