commit - 99e753aa3e4563cf1da22c72e5162aca59cdcd60
commit + 89ce4476468695fce7134a5b43a426112ebc34ae
blob - 78e45385e723721f6e996d5f99378d14263aee4f
blob + c56c5bae8ccc6a1a360af1b34bb1152ea810078e
--- gotd/gotd-secrets.conf.5
+++ gotd/gotd-secrets.conf.5
.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
.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
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" {
permit rw :hackers
notify {
- url https://flan.com/ci/ auth mochi hmac hacker
+ url https://example.com/ci/ auth mochi hmac hacker
}
}
.El