commit db96baa96bf6a9367cb51411ffb252c7f9c47352
parent 20fdd0aac69ec5f8de4a4effb4e856fd7402846f
Author: Daniel Barlow <dan@telent.net>
Date: Wed, 25 Sep 2024 21:30:32 +0100
improve README
Diffstat:
| D | README | | | 34 | ---------------------------------- |
| A | README.md | | | 53 | +++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 53 insertions(+), 34 deletions(-)
diff --git a/README b/README
@@ -1,33 +0,0 @@
-A small HTTPS API that accepts X509 CSRs and signs them if they
-contain the magic number.
-
-Modelled on the Puppet CA "Policy-based autosigning" functionality,
-but without the rest of Puppet
-
-[ This README is speculative ]
-
-
-## Try it out
-
-```
-# create CA key and cert
-openssl genrsa -out ca.key 4096
-CN=CA openssl req -config openssl.cnf -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt
-
-# create client CSR
-CN=rotuer openssl req -config openssl.cnf -newkey rsa:2048 -nodes -keyout client.key -out client.csr
-
-# start the server
-bin/certifix
-
-# send it
-
-curl -v -H 'content-type: application/x-pem-file' --data-binary @client.csr http://localhost:8201/sign
-```
-
-
-https://www.puppet.com/docs/puppet/7/ssl_attributes_extensions#csr_custom_attributes-recommended-oids-custom-attributes
-
-Custom attributes can use any public or site-specific OID, with the exception of the OIDs used for core X.509 functionality. This means you can’t re-use existing OIDs for things like subject alternative names.
-
-One useful OID is the challengePassword attribute — 1.2.840.113549.1.9.7. This is a rarely-used corner of X.509 that can easily be repurposed to hold a pre-shared key.
-\ No newline at end of file
diff --git a/README.md b/README.md
@@ -0,0 +1,53 @@
+A small HTTP(S)[*] API that accepts X509 CSRs and signs them if they
+contain the magic number (specifically, if they have a custom
+`challengePassword` attribute containing a pre-agreed value)
+
+Modelled on the Puppet CA "Policy-based autosigning" functionality,
+but without the rest of Puppet
+
+What's it for? I have a bunch of small devices on my LAN that may or
+may not be able to retain persistent state across reboots. I would
+like them to be able to talk securely to a server using standard TLS
+with client authentication, and without having to rely on network
+firewall rules to prevent the rest of the world also talking to the
+service.
+
+[*] it will do S, but as of writing this footnote it doesn't yet
+
+## To try it out
+
+_This is experiment-quality code that I have published mostly so that
+it does't die with my laptop. Some day it will be grown-up but in the
+meantime try it at your own risk - or even better, don't try it_
+
+It's written in [Fennel](https://www.fennel-lang.org). To build it
+either use Nix or read [package.nix](package.nix) and figure out how
+to replicate the steps manually. Note that it requires a patch to the
+luaossl module
+
+
+```
+# pick a PSK
+echo 'urban cookie collective' > psk
+chmod 0700 psk
+
+# create CA key and cert
+openssl genrsa -out ca.key 4096
+CN=CA openssl req -config openssl.cnf -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt
+
+# create client CSR
+CN=rotuer openssl req -config openssl.cnf -newkey rsa:2048 -nodes -keyout client.key -out client.csr
+
+# start the server
+bin/certifix
+
+# send it
+
+curl -v -H 'content-type: application/x-pem-file' --data-binary @client.csr http://localhost:8201/sign
+```
+
+## Background
+
+* [how Puppet does it](https://www.puppet.com/docs/puppet/7/ssl_attributes_extensions#csr_custom_attributes-recommended-oids-custom-attributes)
+
+* [RFC 5967 - spec for a CSR](https://datatracker.ietf.org/doc/html/rfc5967)
