gotd/gotd-secrets.conf.5

   1 .\"
   2 .\" Copyright (c) 2024 Omar Polo <op@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOTD-SECRETS.CONF 5
  18 .Os
  19 .Sh NAME
  20 .Nm gotd-secrets.conf
  21 .Nd gotd secrets file
  22 .Sh DESCRIPTION
  23 .Nm
  24 contains authentication credentials for use with
  25 .Xr gotd 8
  26 notifications.
  27 This file must be owned by the root user and must not be readable
  28 by any other users.
  29 .Pp
  30 The file format is line-based, with one entry per line.
  31 Comments can appear at the start of a line using a hash mark
  32 .Pq Sq # ,
  33 and extend to the end of the line.
  34 Empty lines are ignored.
  35 .Pp
  36 Each entry consists of whitespace-separated tokens and defines a set
  37 of credentials.
  38 Any credential parameters containing whitespace should be surrounded
  39 by single or double quotes.
  40 .Pp
  41 Each set of credentials must be given a
  42 .Ar label
  43 which can be used to refer to credentials in
  44 .Xr gotd.conf 5 .
  45 This
  46 .Ar label
  47 must be unique among all credentials of the same type.
  48 .Pp
  49 The supported credential types and their parameters are:
  50 .Bl -tag -width Ds
  51 .It Ic auth Ar label Ic user Ar user Ic password Ar password
  52 The
  53 .Ic auth
  54 type represents HTTP Basic Authentication credentials consisting of a
  55 .Ar user
  56 and a
  57 .Ar password .
  58 .It Ic hmac Ar label Ar secret
  59 The
  60 .Ic hmac
  61 type represents shared secrets for use with HMAC signatures of HTTP
  62 request bodies.
  63 A suitable
  64 .Ar secret
  65 can be generated with
  66 .Xr openssl 1
  67 as follows:
  68 .Pp
  69 .Dl $ openssl rand -base64 32
  70 .El
  71 .Pp
  72 .Sh FILES
  73 .Bl -tag -width Ds -compact
  74 .It Pa /etc/gotd-secrets.conf
  75 Location of the
  76 .Nm
  77 configuration file.
  78 .El
  79 .Sh EXAMPLES
  80 Define credentials for HTTP basic authentication and HMAC signatures:
  81 .Bd -literal -offset indent
  82 # /etc/gotd-secrets.conf
  83 auth mochi user "flan" password "super-strong-password!"
  84 hmac hacker q0tcl8QhjYs7U75MW/2rwB30CpdbAhONkfLGxFHm/+8=
  85 .Ed
  86 .Pp
  87 These credentials can be referenced in
  88 .Xr gotd.conf 5
  89 as follows:
  90 .Bd -literal -offset indent
  91 # /etc/gotd.conf
  92 repository "openbsd/src" {
  93         path "/var/git/src.git"
  94         permit rw :hackers
  95
  96         notify {
  97                 url https://example.com/ci/ auth mochi hmac hacker
  98         }
  99 }
 100 .El
 101 .Sh SEE ALSO
 102 .Xr got 1 ,
 103 .Xr gotsh 1 ,
 104 .Xr gotd.conf 5 ,
 105 .Xr gotd 8