GNU bug report logs - #63375
[cuirass] doc: Document authentication.

Previous Next

Full log

View this message in rfc822 format

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 63375 <at> debbugs.gnu.org
Cc: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, rekado <at> elephly.net,othacehe <at> gnu.org,efraim <at> flashner.co.il
Subject: [bug#63375] [cuirass v2] doc: Document authentication.
Date: Mon,  8 May 2023 13:07:01 -0400

* etc/new-client-cert.scm: Add script.
* doc/cuirass.texi (Authentication): Document it.
* Makefile.am (noinst_SCRIPTS): Register it.
---
 Makefile.am             |  2 +-
 doc/cuirass.texi        | 34 ++++++++++++++++
 etc/new-client-cert.scm | 90 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 125 insertions(+), 1 deletion(-)
 create mode 100755 etc/new-client-cert.scm

diff --git a/Makefile.am b/Makefile.am
index a40a76d..62b0860 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -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
diff --git a/doc/cuirass.texi b/doc/cuirass.texi
index db46a33..4441996 100644
--- a/doc/cuirass.texi
+++ b/doc/cuirass.texi
@@ -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
diff --git a/etc/new-client-cert.scm b/etc/new-client-cert.scm
new file mode 100755
index 0000000..fa8ac5c
--- /dev/null
+++ b/etc/new-client-cert.scm
@@ -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 <at> 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))))

base-commit: cf4e3e4ac4a9c8d6f0d82b0a173826f15bbca7f3
-- 
2.39.2

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.