@@ -25,7 +25,7 @@
bin_SCRIPTS = \
bin/cuirass
-noinst_SCRIPTS = pre-inst-env
+noinst_SCRIPTS = pre-inst-env etc/new-client-cert.scm
guilesitedir = $(datarootdir)/guile/site/@GUILE_EFFECTIVE_VERSION@
guileobjectdir = $(libdir)/guile/@GUILE_EFFECTIVE_VERSION@/site-ccache
@@ -57,6 +57,7 @@ Documentation License''.
* Parameters:: Cuirass parameters.
* Build modes:: Build modes.
* Invocation:: How to run Cuirass.
+* Authentication:: Configuring TLS authentication.
* Web API:: Description of the Web API.
* Database:: About the database schema.
@@ -711,6 +712,39 @@ Display the actual version of @code{cuirass}.
Display an help message that summarize all the options provided.
@end table
+@c *********************************************************************
+@node Authentication
+@chapter Authentication
+@cindex authentication
+
+It is necessary to be authenticated to accomplish some of the actions
+exposed via the web interface of Cuirass, such as cancelling or
+restarting a build. The authentication mechanism of Cuirass currently
+relies on the use of a private TLS certificate authority.
+
+To automate the creation of new user certificates, the
+@file{etc/new-client-cert.scm} Guile script can be used. It requires
+the @command{guix} command to be available and a preexisting certificate
+authority at @file{/etc/ssl-ca}. To issue a new user certificate, run
+it from your home directory with:
+
+@example
+sudo -E ./etc/new-client-cert.scm
+@end example
+
+You will be asked to input the password for the CA private key, if any,
+and again for your new certificate; save it carefully. The script
+requires to run as root to have access to the private certificate
+authority key; it outputs the new user certificate files in various
+formats to the current working directory.
+
+After your new certificate is generated, it needs to be registered with
+your web browser. To do so using GNU IceCat, for example, you can
+navigate to @samp{Parameters -> Security -> Show certificates} and then
+click the @samp{Import...} button and select to your @file{.pk12}
+personal certificate file. You should now be authenticated to perform
+privileged actions via the web interface of Cuirass.
+
@c *********************************************************************
@node Web API
@chapter Web API
new file mode 100755
@@ -0,0 +1,90 @@
+#!/usr/bin/env -S guix shell guile openssl -- guile \\
+--no-auto-compile -e main -s
+!#
+;;;; cuirass.scm -- Cuirass public interface.
+;;; Copyright © 2023 Ricardo Wurmus <rekado@elephly.net>
+;;;
+;;; This file is part of Cuirass.
+;;;
+;;; Cuirass is free software: you can redistribute it and/or modify
+;;; it under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation, either version 3 of the License, or
+;;; (at your option) any later version.
+;;;
+;;; Cuirass is distributed in the hope that it will be useful,
+;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with Cuirass. If not, see <http://www.gnu.org/licenses/>.
+
+(use-modules (ice-9 match)
+ (guix build utils))
+
+(define %CA-directory
+ "/etc/ssl-ca")
+
+(define CA-key
+ (string-append %CA-directory "/private/ca.key"))
+(define CA-cert
+ (string-append %CA-directory "/certs/ca.crt"))
+
+(define* (output who file)
+ (string-append (getcwd) "/" who file))
+
+(define (key-file who)
+ "Return the absolute file name of the key file for WHO."
+ (output who ".key"))
+
+(define (csr-file who)
+ "Return the absolute file name of the CSR file for WHO."
+ (output who ".csr"))
+
+(define (client-cert-file who)
+ "Return the absolute file name of the client certificate file for
+WHO."
+ (output who ".crt"))
+
+(define (exported-cert-file who)
+ "Return the absolute file name of the pkcs12 client certificate file
+for WHO. This is the file that users should import into their
+browsers."
+ (output who ".p12"))
+
+(define (generate-csr! who)
+ "Generate a new certificate signing request and key for WHO."
+ (invoke "openssl" "req" "-newkey" "rsa:4096"
+ "-nodes" ;no password
+ "-subj"
+ (format #false "/C=DE/ST=Berlin/L=Berlin/O=GNU Guix/OU=Cuirass/CN=~a" who)
+ "-keyout" (key-file who)
+ "-out" (csr-file who)))
+
+(define* (generate-client-certificate! who #:key (expiry 365))
+ "Generate a client certificate for WHO."
+ (invoke "openssl" "x509" "-req"
+ "-in" (csr-file who)
+ "-CA" CA-cert
+ "-CAkey" CA-key
+ "-out" (client-cert-file who)
+ "-days" (number->string expiry)))
+
+(define (export-p12! who)
+ (invoke "openssl" "pkcs12" "-export"
+ "-in" (client-cert-file who)
+ "-inkey" (key-file who)
+ "-out" (exported-cert-file who)))
+
+(define (main args)
+ (match (command-line)
+ ((script)
+ (set-program-arguments (list script (or (getenv "SUDO_USER")
+ (getenv "USER"))))
+ (apply main args))
+ ((script who)
+ (generate-csr! who)
+ (generate-client-certificate! who)
+ (export-p12! who))
+ ((script . rest)
+ (format (current-error-port) "usage: ~a [name]~%" script))))