commit cebd4beed2990ad47383df6f9a11f2df0204fc6a from: Stefan Sperling 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