feat: mTLS.getCertificate helper can return a X509Certificate object

panva · panva · commit be3f47f686ee · 2023-01-23T11:45:11.000+01:00
diff --git a/certification/fapi/index.js b/certification/fapi/index.js
@@ -2,7 +2,7 @@
 
 import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { randomUUID } from 'node:crypto';
+import * as crypto from 'node:crypto';
 import * as https from 'node:https';
 import { promisify } from 'node:util';
 import { URL } from 'node:url';
@@ -81,7 +81,7 @@ const adapter = (name) => {
       const [version, ...rest] = id.split('-');
 
       let metadata = {
-        cacheBuster: randomUUID(),
+        cacheBuster: crypto.randomUUID(),
       };
 
       if (version === '1.0') {
@@ -199,14 +199,14 @@ const fapi = new Provider(ISSUER, {
       selfSignedTlsClientAuth: true,
       getCertificate(ctx) {
         if (SUITE_BASE_URL === OFFICIAL_CERTIFICATION) {
-          return ctx.get('client-certificate');
+          try {
+            return new crypto.X509Certificate(Buffer.from(ctx.get('client-certificate'), 'base64'));
+          } catch {
+            return undefined;
+          }
         }
 
-        const peerCertificate = ctx.socket.getPeerCertificate();
-        if (peerCertificate.raw) {
-          return `-----BEGIN CERTIFICATE-----\n${peerCertificate.raw.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE-----`;
-        }
-        return undefined;
+        return ctx.socket.getPeerX509Certificate();
       },
     },
     jwtResponseModes: { enabled: true },
@@ -317,7 +317,7 @@ fapi.use(async (ctx, next) => {
   return next();
 });
 fapi.use((ctx, next) => {
-  const id = ctx.get('x-fapi-interaction-id') || randomUUID();
+  const id = ctx.get('x-fapi-interaction-id') || crypto.randomUUID();
   ctx.set('x-fapi-interaction-id', id);
   return next();
 });
diff --git a/certification/oidc/configuration.js b/certification/oidc/configuration.js
@@ -55,7 +55,11 @@ export default {
       certificateBoundAccessTokens: true,
       selfSignedTlsClientAuth: true,
       getCertificate(ctx) {
-        return ctx.get('client-certificate');
+        try {
+          return new crypto.X509Certificate(Buffer.from(ctx.get('client-certificate'), 'base64'));
+        } catch {
+          return undefined;
+        }
       },
     },
     claimsParameter: { enabled: true },
diff --git a/docs/README.md b/docs/README.md
@@ -1239,27 +1239,6 @@ _**default value**_:
 Function used to determine if the client certificate, used in the request, is verified and comes from a trusted CA for the client. Should return true/false. Only used for `tls_client_auth` client authentication method.   
   
 
-<a id="certificate-authorized-when-behind-a-tls-terminating-proxy-nginx-apache"></a><details><summary>(Click to expand) When behind a TLS terminating proxy (nginx/apache)</summary><br>
-
-
-When behind a TLS terminating proxy it is common that this detail be passed to the application as a sanitized header. This returns the chosen header value provided by nginx's `$ssl_client_verify` or apache's `%{SSL_CLIENT_VERIFY}s`
-  
-
-```js
-function certificateAuthorized(ctx) {
-  return ctx.get('x-ssl-client-verify') === 'SUCCESS';
-}
-```
-</details>
-<a id="certificate-authorized-when-using-node's-https-create-server"></a><details><summary>(Click to expand) When using node's `https.createServer`
-</summary><br>
-
-```js
-function certificateAuthorized(ctx) {
-  return ctx.socket.authorized;
-}
-```
-</details>
 
 #### certificateBoundAccessTokens
 
@@ -1276,53 +1255,12 @@ false
 Function used to determine if the client certificate, used in the request, subject matches the registered client property. Only used for `tls_client_auth` client authentication method.   
   
 
-<a id="certificate-subject-matches-when-behind-a-tls-terminating-proxy-nginx-apache"></a><details><summary>(Click to expand) When behind a TLS terminating proxy (nginx/apache)</summary><br>
-
-
-TLS terminating proxies can pass a header with the Subject DN pretty easily, for Nginx this would be `$ssl_client_s_dn`, for apache `%{SSL_CLIENT_S_DN}s`.
-  
-
-```js
-function certificateSubjectMatches(ctx, property, expected) {
-  switch (property) {
-    case 'tls_client_auth_subject_dn':
-      return ctx.get('x-ssl-client-s-dn') === expected;
-    default:
-      throw new Error(`${property} certificate subject matching not implemented`);
-  }
-}
-```
-</details>
 
 #### getCertificate
 
-Function used to retrieve the PEM-formatted client certificate used in the request.   
-  
-
-<a id="get-certificate-when-behind-a-tls-terminating-proxy-nginx-apache"></a><details><summary>(Click to expand) When behind a TLS terminating proxy (nginx/apache)</summary><br>
-
-
-When behind a TLS terminating proxy it is common that the certificate be passed to the application as a sanitized header. This returns the chosen header value provided by nginx's `$ssl_client_cert` or apache's `%{SSL_CLIENT_CERT}s`
+Function used to retrieve a `crypto.X509Certificate` instance, or a PEM-formatted string, representation of client certificate used in the request.   
   
 
-```js
-function getCertificate(ctx) {
-  return ctx.get('x-ssl-client-cert');
-}
-```
-</details>
-<a id="get-certificate-when-using-node's-https-create-server"></a><details><summary>(Click to expand) When using node's `https.createServer`
-</summary><br>
-
-```js
-function getCertificate(ctx) {
-  const peerCertificate = ctx.socket.getPeerCertificate();
-  if (peerCertificate.raw) {
-    return `-----BEGIN CERTIFICATE-----\n${peerCertificate.raw.toString('base64')}\n-----END CERTIFICATE-----`;
-  }
-}
-```
-</details>
 
 #### selfSignedTlsClientAuth
 
diff --git a/lib/helpers/certificate_thumbprint.js b/lib/helpers/certificate_thumbprint.js
@@ -1,16 +1,21 @@
-import { createHash } from 'node:crypto';
+import { createHash, X509Certificate } from 'node:crypto';
 
 import * as base64url from './base64url.js';
 
 export default function certThumbprint(cert) {
-  return base64url.encodeBuffer(
-    createHash('sha256')
+  let digest;
+  if (cert instanceof X509Certificate) {
+    digest = createHash('sha256').update(cert.raw).digest();
+  } else {
+    digest = createHash('sha256')
       .update(
         Buffer.from(
           cert.replace(/(?:-----(?:BEGIN|END) CERTIFICATE-----|\s|=)/g, ''),
           'base64',
         ),
       )
-      .digest(),
-  );
+      .digest();
+  }
+
+  return base64url.encodeBuffer(digest);
 }
diff --git a/lib/helpers/defaults.js b/lib/helpers/defaults.js
@@ -1059,31 +1059,8 @@ function makeDefaults() {
         /*
          * features.mTLS.getCertificate
          *
-         * description: Function used to retrieve the PEM-formatted client certificate used
-         *   in the request.
-         *
-         * example: When behind a TLS terminating proxy (nginx/apache)
-         *
-         * When behind a TLS terminating proxy it is common that the certificate be passed
-         * to the application as a sanitized header. This returns the chosen header value provided
-         * by nginx's `$ssl_client_cert` or apache's `%{SSL_CLIENT_CERT}s`
-         *
-         * ```js
-         * function getCertificate(ctx) {
-         *   return ctx.get('x-ssl-client-cert');
-         * }
-         * ```
-         *
-         * example: When using node's `https.createServer`
-         *
-         * ```js
-         * function getCertificate(ctx) {
-         *   const peerCertificate = ctx.socket.getPeerCertificate();
-         *   if (peerCertificate.raw) {
-         *     return `-----BEGIN CERTIFICATE-----\n${peerCertificate.raw.toString('base64')}\n-----END CERTIFICATE-----`;
-         *   }
-         * }
-         * ```
+         * description: Function used to retrieve a `crypto.X509Certificate` instance,
+         *   or a PEM-formatted string, representation of client certificate used in the request.
          *
          * @nodefault
          */
@@ -1096,26 +1073,6 @@ function makeDefaults() {
          *   request, is verified and comes from a trusted CA for the client. Should return true/false.
          *   Only used for `tls_client_auth` client authentication method.
          *
-         * example: When behind a TLS terminating proxy (nginx/apache)
-         *
-         * When behind a TLS terminating proxy it is common that this detail be passed
-         * to the application as a sanitized header. This returns the chosen header value provided
-         * by nginx's `$ssl_client_verify` or apache's `%{SSL_CLIENT_VERIFY}s`
-         *
-         * ```js
-         * function certificateAuthorized(ctx) {
-         *   return ctx.get('x-ssl-client-verify') === 'SUCCESS';
-         * }
-         * ```
-         *
-         * example: When using node's `https.createServer`
-         *
-         * ```js
-         * function certificateAuthorized(ctx) {
-         *   return ctx.socket.authorized;
-         * }
-         * ```
-         *
          * @nodefault
          */
         certificateAuthorized,
@@ -1127,22 +1084,6 @@ function makeDefaults() {
          *   request, subject matches the registered client property. Only used for `tls_client_auth`
          *   client authentication method.
          *
-         * example: When behind a TLS terminating proxy (nginx/apache)
-         *
-         * TLS terminating proxies can pass a header with the Subject DN pretty easily, for Nginx
-         * this would be `$ssl_client_s_dn`, for apache `%{SSL_CLIENT_S_DN}s`.
-         *
-         * ```js
-         * function certificateSubjectMatches(ctx, property, expected) {
-         *   switch (property) {
-         *     case 'tls_client_auth_subject_dn':
-         *       return ctx.get('x-ssl-client-s-dn') === expected;
-         *     default:
-         *       throw new Error(`${property} certificate subject matching not implemented`);
-         *   }
-         * }
-         * ```
-         *
          * @nodefault
          */
         certificateSubjectMatches,
diff --git a/test/certificate_bound_access_tokens/certificate_bound_access_tokens.config.js b/test/certificate_bound_access_tokens/certificate_bound_access_tokens.config.js
@@ -1,3 +1,5 @@
+import { X509Certificate } from 'node:crypto';
+
 import merge from 'lodash/merge.js';
 
 import getConfig from '../default.config.js';
@@ -9,7 +11,11 @@ merge(config.features, {
     enabled: true,
     certificateBoundAccessTokens: true,
     getCertificate(ctx) {
-      return ctx.get('x-ssl-client-cert');
+      try {
+        return new X509Certificate(Buffer.from(ctx.get('x-ssl-client-cert'), 'base64'));
+      } catch (e) {
+        return undefined;
+      }
     },
   },
   clientCredentials: { enabled: true },
diff --git a/test/certificate_bound_access_tokens/certificate_bound_access_tokens.test.js b/test/certificate_bound_access_tokens/certificate_bound_access_tokens.test.js
diff --git a/test/client_auth/client_auth.config.js b/test/client_auth/client_auth.config.js
diff --git a/test/client_auth/client_auth.test.js b/test/client_auth/client_auth.test.js
