--- Begin Message ---
|
Subject: |
[cuirass] doc: Document authentication. |
|
Date: |
Mon, 8 May 2023 12:07:45 -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@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
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#63375: [cuirass] doc: Document authentication. |
|
Date: |
Wed, 14 Jun 2023 23:17:15 +0200 |
|
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) |
Hi Maxim,
Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
> * etc/new-client-cert.scm: Add script.
> * doc/cuirass.texi (Authentication): Document it.
> * Makefile.am (noinst_SCRIPTS): Register it.
I had completely overlooked this patch; great work! Applied now.
BTW, if you’re interested, I can add you to ‘.guix-authorizations’ of
course; we need to increase the bus factor. Let me know what you think!
Thanks, and apologies for the delay.
Ludo’.
--- End Message ---