.\"
.\" Copyright (c) 2024 Omar Polo <op@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GOTD-SECRETS.CONF 5
.Os
.Sh NAME
.Nm gotd-secrets.conf
.Nd gotd secrets file
.Sh DESCRIPTION
.Nm
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 appear at the start of a line using a hash mark
.Pq Sq # ,
and extend to the end of the line.
Empty lines are ignored.
.Pp
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
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
.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
.Ic hmac
type represents shared secrets for use with HMAC signatures of HTTP
request bodies.
A suitable
.Ar secret
can be generated with
.Xr openssl 1
as follows:
.Pp
.Dl $ openssl rand -base64 32
.El
.Pp
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/gotd-secrets.conf
Location of the
.Nm
configuration file.
.El
.Sh EXAMPLES
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 credentials can be referenced in
.Xr gotd.conf 5
as follows:
.Bd -literal -offset indent
# /etc/gotd.conf
repository "openbsd/src" {
	path "/var/git/src.git"
	permit rw :hackers

	notify {
		url https://example.com/ci/ auth mochi hmac hacker
	}
}
.El
.Sh SEE ALSO
.Xr got 1 ,
.Xr gotsh 1 ,
.Xr gotd.conf 5 ,
.Xr gotd 8