Merge pull request rauc#1620 from jluebbe/pki-docs

docs: update links and warn against simply using test/openssl-ca-create.sh

docs/advanced.rst

@@ -31,15 +31,19 @@ CMS is well proven in S/MIME and has widely available implementations, while
 supporting simple as well as complex PKI use-cases (certificate expiry,
 intermediate CAs, revocation, algorithm selection, hardware security modules…)
 without additional complexity in RAUC itself.
-
 RAUC uses OpenSSL_ as a library for signing and verification of bundles.
-A PKI with intermediate CAs for the unit tests is generated by the
-``test/openssl-ca-create.sh`` shell script available from `GitHub
-<https://github.com/rauc/rauc/blob/master/test/openssl-ca-create.sh>`_, which
-may also be useful as an example for creating your own PKI.
 
 .. _OpenSSL: https://www.openssl.org/
 
+For RAUC's unit test, a PKI with intermediate CAs and separate sub-trees for
+development and release is generated by the script
+``test/openssl-ca-create.sh``.
+This PKI is much more complex than what is needed for almost all use-cases, as
+it is intended to exercise many different code paths in RAUC.
+
+If you are unsure which PKI to create, carefully consider if a simple
+:ref:`single key setup <sec-pki-single-key>` matches your requirements.
+
 In the following sections, general CA configuration, some use-cases and
 corresponding PKI setups are described.
 
@@ -51,17 +55,19 @@ CA Configuration
 OpenSSL uses an ``openssl.cnf`` file to define paths to use for signing, default
 parameters for certificates and additional parameters to be stored during
 signing.
-Configuring a CA correctly (and securely) is a complex topic and obviously
+Configuring a CA/PKI correctly (and securely) is a complex topic and obviously
 exceeds the scope of this documentation.
-As a starting point, the OpenSSL manual pages (especially ca_, req_, x509_, cms_,
-verify_ and config_) and Stefan H. Holek's pki-tutorial_ are useful.
-
-.. _ca: https://www.openssl.org/docs/man1.1.1/man1/ca.html
-.. _req: https://www.openssl.org/docs/man1.1.1/man1/req.html
-.. _x509: https://www.openssl.org/docs/man1.1.1/man1/x509.html
-.. _cms: https://www.openssl.org/docs/man1.1.1/man1/cms.html
-.. _verify: https://www.openssl.org/docs/man1.1.1/man1/verify.html
-.. _config: https://www.openssl.org/docs/man1.1.1/man5/config.html
+As a starting point, the OpenSSL manual pages (especially ca_, req_, x509_,
+cms_, verification-options_ and config_) and Stefan H. Holek's pki-tutorial_
+are useful.
+If in doubt, obtain advice from an expert.
+
+.. _ca: https://docs.openssl.org/3.4/man1/openssl-ca/
+.. _req: https://docs.openssl.org/3.4/man1/openssl-req/
+.. _x509: https://docs.openssl.org/3.4/man1/openssl-x509/
+.. _cms: https://docs.openssl.org/3.4/man1/openssl-cms/
+.. _verification-options: https://docs.openssl.org/3.4/man1/openssl-verification-options/
+.. _config: https://docs.openssl.org/3.4/man5/config/
 
 .. _pki-tutorial: https://pki-tutorial.readthedocs.io/
 
@@ -107,6 +113,8 @@ Also, you can optionally use *extendedKeyUsage* attributes on intermediate CA
 certificates to limit which ones are allowed to issue code signing
 certificates.
 
+.. _sec-pki-single-key:
+
 Single Key
 ~~~~~~~~~~
 
@@ -118,6 +126,9 @@ While you can use RAUC with these, you can't:
 * distinguish between development versions and releases
 * revoke a compromised key
 
+Carefully consider the certificate's validity period in relation to your
+intended update and certificate rollover cycles.
+
 Simple CA
 ~~~~~~~~~
 

test/openssl-ca-create.sh

@@ -1,5 +1,14 @@
 #!/bin/bash
 
+# WARNING:
+#
+# The PKI generated by this script is much more complex than what is needed for
+# almost all use-cases, as it is intended to exercise many different code paths
+# in RAUC.
+#
+# Refer to https://rauc.readthedocs.io/en/latest/advanced.html#security for an
+# introduction to possible PKI structures.
+
 set -xe
 
 ORG="Test Org"