PROD-1221: More documentation around VEN client certificate processing

README.md

@@ -95,3 +95,15 @@ To get a `psql` session for the Docker Postgres database.
 If you don't want to spin up a separate Postgres database, you can follow the steps in `Running in Docker for development`,
 un-comment the 2 `port` lines under `db` in `docker-compose.yml`, then use a `DB_URL` of `postgres://vtn:vtn@127.0.0.1:55432/vtn_test`
 in your local NodeJS environment. This will let you change code quickly without rebuilding a Docker image.
+
+## Client certificate authentication
+
+OpenADR VENs connect using a client TLS certificate. In this Docker-compose configuration, nginx provides:
+
+1) TLS termination: Listens on HTTPS port 443 and proxies to NodeJS plaintext HTTP on port 8080
+2) Client certificate chain of trust validation: As mentioned above under `Configuration`, `clientssl.crt` contains a 
+Root Certificate and Intermediate Certificate from a trusted CA. These two certificates allow nginx to validate that the
+VEN-provided client certificate is issued by that trusted CA.
+3) HTTP headers to NodeJS: `ssl_client_s_dn_cn` contains the CN from the VEN client certificate. `ssl_client_certificate`
+contains the entire URI-encoded PEM-encoded X.509 client certificate. These headers are consumed by the `certificate-parser`
+ExpressJS middleware.

server/middleware/certificate-parser.js

@@ -5,6 +5,7 @@ const {
 } = require('../../modules/certificate');
 
 module.exports = async (req, res, next) => {
+  // this header from nginx contains the CN from the client certificate
   if (
     req.headers['ssl_client_s_dn_cn'] &&
     req.headers['ssl_client_s_dn_cn'] !== 'no_client_cert'
@@ -16,6 +17,7 @@ module.exports = async (req, res, next) => {
     return next(err);
   }
 
+  // this header from nginx contains the URI-encoded PEM-encoded X.509 client certificate
   if (req.headers['ssl_client_certificate']) {
     const pemCertificateEscaped = req.headers['ssl_client_certificate'];
     const fingerprint = calculatePartialFingerprintOfEscapedPemCertificate(