commit cebd4beed2990ad47383df6f9a11f2df0204fc6a
from: Stefan Sperling <stsp@stsp.name>
date: Mon Sep 09 13:18:02 2024 UTC

wording improvements for gotd-secrets.conf man page

commit - a839c406a7d2d882a0b2e068f71054688beadf39
commit + cebd4beed2990ad47383df6f9a11f2df0204fc6a
blob - 78e45385e723721f6e996d5f99378d14263aee4f
blob + c56c5bae8ccc6a1a360af1b34bb1152ea810078e
--- gotd/gotd-secrets.conf.5
+++ gotd/gotd-secrets.conf.5
@@ -21,28 +21,45 @@
 .Nd gotd secrets file
 .Sh DESCRIPTION
 .Nm
-holds the authentication data and HMAC secrets for
+contains authentication credentials for use with
 .Xr gotd 8
 notifications.
 This file must be owned by the root user and must not be readable
 by any other users.
 .Pp
 The file format is line-based, with one entry per line.
-Comments can be put at the start of the line using a hash mark
+Comments can appear at the start of a line using a hash mark
 .Pq Sq # ,
-and extend to the end of it.
-Empty lines are also ignored.
+and extend to the end of the line.
+Empty lines are ignored.
 .Pp
-Each entry is made by blanks-separated words.
-Arguments containing whitespaces should be surrounded by single or double
-quotes.
+Each entry consists of whitespace-separated tokens and defines a set
+of credentials.
+Any credential parameters containing whitespace should be surrounded
+by single or double quotes.
 .Pp
-The supported entries are:
+Each set of credentials must be given a
+.Ar label
+which can be used to refer to credentials in
+.Xr gotd.conf 5 .
+This
+.Ar label
+must be unique among all credentials of the same type.
+.Pp
+The supported credential types and their parameters are:
 .Bl -tag -width Ds
 .It Ic auth Ar label Ic user Ar user Ic password Ar password
-The entry is for HTTP Basic Authentication.
+The
+.Ic auth
+type represents HTTP Basic Authentication credentials consisting of a
+.Ar user
+and a
+.Ar password .
 .It Ic hmac Ar label Ar secret
-The entry is for signing the notification HTTP payload with HMAC.
+The
+.Ic hmac
+type represents shared secrets for use with HMAC signatures of HTTP
+request bodies.
 A suitable
 .Ar secret
 can be generated with
@@ -52,10 +69,6 @@ as follows:
 .Dl $ openssl rand -base64 32
 .El
 .Pp
-The
-.Ar label
-must be unique between entries with the same type
-.Pq i.e. Ic auth No or Ic hmac .
 .Sh FILES
 .Bl -tag -width Ds -compact
 .It Pa /etc/gotd-secrets.conf
@@ -64,17 +77,16 @@ Location of the
 configuration file.
 .El
 .Sh EXAMPLES
-This example configuration defines two secrets, the first for
-HTTP authentication and the second for HMAC signing.
+Define credentials for HTTP basic authentication and HMAC signatures:
 .Bd -literal -offset indent
 # /etc/gotd-secrets.conf
 auth mochi user "flan" password "super-strong-password!"
 hmac hacker q0tcl8QhjYs7U75MW/2rwB30CpdbAhONkfLGxFHm/+8=
 .Ed
 .Pp
-These values can be referenced in
+These credentials can be referenced in
 .Xr gotd.conf 5
-as:
+as follows:
 .Bd -literal -offset indent
 # /etc/gotd.conf
 repository "openbsd/src" {
@@ -82,7 +94,7 @@ repository "openbsd/src" {
 	permit rw :hackers
 
 	notify {
-		url https://flan.com/ci/ auth mochi hmac hacker
+		url https://example.com/ci/ auth mochi hmac hacker
 	}
 }
 .El