From a855d4c03116d7d2878c8ddaf7202aba516cfc19 Mon Sep 17 00:00:00 2001
From: Konrad Bucheli <konrad.bucheli@psi.ch>
Date: Thu, 22 Dec 2022 16:36:29 +0100
Subject: [PATCH] add hint about encrypted backups for SSL private keys

---
 admin-guide/operations/certificates.md  | 64 +++++++++++++++++++++++++
 admin-guide/operations/certificates.rst | 62 ------------------------
 2 files changed, 64 insertions(+), 62 deletions(-)
 create mode 100644 admin-guide/operations/certificates.md
 delete mode 100644 admin-guide/operations/certificates.rst

diff --git a/admin-guide/operations/certificates.md b/admin-guide/operations/certificates.md
new file mode 100644
index 00000000..37177ba0
--- /dev/null
+++ b/admin-guide/operations/certificates.md
@@ -0,0 +1,64 @@
+# Managing SSL certificates
+
+We use DigiCert certificates.
+
+
+## Requesting certificates
+
+First create a certificate signing request (CSR) like this, replacing `$FQDN`
+and `$ALIASES`
+
+```
+cat >$FQDN.cnf <<EOF
+FQDN = $FQDN
+ORGNAME = Paul Scherrer Institut (PSI)
+
+# subjectAltName entries: to add DNS aliases to the CSR, delete
+# the '#' character in the ALTNAMES line, and change the subsequent
+# 'DNS:' entries accordingly. Please note: all DNS names must
+# resolve to the same IP address as the FQDN.
+ALTNAMES = DNS:\$FQDN $ALIASES
+
+# --- no modifications required below ---
+[ req ]
+default_bits = 2048
+default_md = sha256
+prompt = no
+encrypt_key = no
+distinguished_name = dn
+req_extensions = req_ext
+
+[ dn ]
+C = CH
+O = \$ORGNAME
+CN = \$FQDN
+OU = AWI
+
+[ req_ext ]
+subjectAltName = \$ALTNAMES
+
+EOF
+
+/usr/bin/openssl req -new -config $FQDN.cnf -keyout $FQDN.key -out $FQDN.csr
+```
+
+Finally, [submit the CSR](https://www.digicert.com/secure/requests/products?guest_key=11dqrl7540p3t4jm4qhnvsnzjkvk).
+Please note that the URL will work when accessed from PSI network (e.g. VPN).
+
+DigiCert will send an email including instructions on how to download the certificate.
+
+Our teams practice is to always create a new private key and to back it up encrypted in Gitlab, either
+- in Hiera as [EYAML](https://linux.psi.ch/admin-guide/puppet/hiera.html#secret-values)
+- for central infrastructure hosts in their [bootstrap repository](https://git.psi.ch/linux-infra/bootstrap)
+- for the rest in our [team secret store](https://git.psi.ch/linux-infra/core-linux-secrets)
+
+
+## Renewing certificates
+
+Using the same configuration file as above, generate a new private key and CSR,
+and submit the CSR as before.
+
+
+## Revoke certificates
+
+If you would like to revoke a DigiCert certificate, please send an e-mail to pki@psi.ch
diff --git a/admin-guide/operations/certificates.rst b/admin-guide/operations/certificates.rst
deleted file mode 100644
index 08a192c9..00000000
--- a/admin-guide/operations/certificates.rst
+++ /dev/null
@@ -1,62 +0,0 @@
-Managing SSL certificates
-=========================
-
-We use DigiCert certificates.
-
-
-Requesting certificates
------------------------
-
-First create a certificate signing request (CSR) like this, replacing ``$FQDN``
-and ``$ALIASES``::
-
-    cat >$FQDN.cnf <<EOF
-    FQDN = $FQDN
-    ORGNAME = Paul Scherrer Institut (PSI)
-
-    # subjectAltName entries: to add DNS aliases to the CSR, delete
-    # the '#' character in the ALTNAMES line, and change the subsequent
-    # 'DNS:' entries accordingly. Please note: all DNS names must
-    # resolve to the same IP address as the FQDN.
-    ALTNAMES = DNS:\$FQDN $ALIASES
-
-    # --- no modifications required below ---
-    [ req ]
-    default_bits = 2048
-    default_md = sha256
-    prompt = no
-    encrypt_key = no
-    distinguished_name = dn
-    req_extensions = req_ext
-
-    [ dn ]
-    C = CH
-    O = \$ORGNAME
-    CN = \$FQDN
-    OU = AWI
-
-    [ req_ext ]
-    subjectAltName = \$ALTNAMES
-
-    EOF
-
-    /usr/bin/openssl req -new -config $FQDN.cnf -keyout $FQDN.key -out $FQDN.csr
-
-
-Finally, `submit the CSR <https://www.digicert.com/secure/requests/products?guest_key=11dqrl7540p3t4jm4qhnvsnzjkvk>`_. Please note
-that the URL will work when accessed from PSI network (e.g. VPN).
-
-DigiCert will send an email including instructions on how to download the
-certificate.
-
-
-Renewing certificates
----------------------
-
-Using the same configuration file as above, generate a new private key and CSR,
-and submit the CSR as before.
-
-
-Revoke certificates
--------------------
-If you would like to revoke a DigiCert certificate, please send an e-mail to pki@psi.ch