TLS Certificate Pinning and Force TLS Checks (#295)

* feat: add key pinning * refactor: naming, placement * refactor: error message * refactor: make feature even safer * fix: force override TLS_REJECT_UNAUTHORIZED --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> Co-authored-by: Julian König <[email protected]>
nmshd · Oct 30, 2024 · 47304af · 47304af
1 parent 81b16bf
commit 47304af
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 4 deletions.
diff --git a/src/ConnectorRuntime.ts b/src/ConnectorRuntime.ts
@@ -13,6 +13,7 @@ import fs from "fs";
 import { HttpsProxyAgent } from "https-proxy-agent";
 import { validate as validateSchema } from "jsonschema";
 import path from "path";
+import { checkServerIdentity, PeerCertificate } from "tls";
 import { ConnectorMode } from "./ConnectorMode";
 import { ConnectorRuntimeConfig } from "./ConnectorRuntimeConfig";
 import { ConnectorRuntimeModule, ConnectorRuntimeModuleConfiguration } from "./ConnectorRuntimeModule";
@@ -76,11 +77,12 @@ export class ConnectorRuntime extends Runtime<ConnectorRuntimeConfig> {
             throw new Error(errorMessage);
         }
 
-        this.forceEnableMandatoryModules(connectorConfig);
-
         const loggerFactory = new NodeLoggerFactory(connectorConfig.logging);
         ConnectorLoggerFactory.init(loggerFactory);
 
+        this.setServerIdentityCheckFromKeyPinning(connectorConfig, loggerFactory.getLogger(ConnectorRuntime));
+        this.forceEnableMandatoryModules(connectorConfig);
+
         const runtime = new ConnectorRuntime(connectorConfig, loggerFactory);
         await runtime.init();
 
@@ -92,6 +94,43 @@ export class ConnectorRuntime extends Runtime<ConnectorRuntimeConfig> {
         return runtime;
     }
 
+    private static setServerIdentityCheckFromKeyPinning(connectorConfig: ConnectorRuntimeConfig, logger: ILogger) {
+        if (!connectorConfig.pinnedTLSCertificateSHA256Fingerprints) return;
+        const pinnedFingerprints = connectorConfig.pinnedTLSCertificateSHA256Fingerprints;
+
+        for (const host in pinnedFingerprints) {
+            if (!host.match(/^((([A-Za-z0-9]+(-[A-Za-z0-9]+)*)\.)+[a-z]{2,}|localhost)$/)) {
+                throw new Error(`Invalid host '${host}' in pinnedTLSCertificateSHA256Fingerprints. The host must not contain a protocol, path or query.`);
+            }
+
+            logger.info(`Certificate pinning is enforced for host '${host}' with fingerprint(s) '${pinnedFingerprints[host].join(", ")}'.`);
+        }
+
+        connectorConfig.transportLibrary.httpsAgentOptions = {
+            ...connectorConfig.transportLibrary.httpsAgentOptions,
+            checkServerIdentity: (host: string, certificate: PeerCertificate) => {
+                const error = checkServerIdentity(host, certificate);
+                if (error) return error;
+
+                if (connectorConfig.enforceCertificatePinning && !(host in pinnedFingerprints)) {
+                    return new Error(
+                        `Certificate verification error: Certificate pinning is enforced, but no pinned certificate fingerprint is provided in the configuration for the requested host '${host}'.`
+                    );
+                }
+
+                if (!(host in pinnedFingerprints)) return;
+                const pinnedFingerprintsForHost = pinnedFingerprints[host];
+
+                const fingerprint = certificate.fingerprint256.replaceAll(":", "").toLocaleLowerCase();
+                if (pinnedFingerprintsForHost.find((e) => e.replaceAll(":", "").toLocaleLowerCase() === fingerprint)) return;
+
+                return new Error(
+                    `Certificate verification error: The SHA256 fingerprint of the received certificate '${fingerprint}' doesn't match a pinned certificate fingerprint for host '${host}'.`
+                );
+            }
+        };
+    }
+
     private static forceEnableMandatoryModules(connectorConfig: ConnectorRuntimeConfig) {
         connectorConfig.modules.decider.enabled = true;
         connectorConfig.modules.request.enabled = true;

diff --git a/src/ConnectorRuntimeConfig.ts b/src/ConnectorRuntimeConfig.ts
@@ -27,4 +27,7 @@ export interface ConnectorRuntimeConfig extends RuntimeConfig {
     infrastructure: {
         httpServer: HttpServerConfiguration;
     };
+
+    pinnedTLSCertificateSHA256Fingerprints?: Record<string, string[]>;
+    enforceCertificatePinning?: boolean;
 }
diff --git a/src/index.ts b/src/index.ts
@@ -81,6 +81,8 @@ function parseString(value: string) {
 
 async function run() {
     const config = createConnectorConfig();
+    if (!config.debug) process.env.TLS_REJECT_UNAUTHORIZED = "1";
+
     const runtime = await ConnectorRuntime.create(config);
     await runtime.start();
 }

diff --git a/src/jsonSchemas/connectorConfig.json b/src/jsonSchemas/connectorConfig.json
@@ -1053,13 +1053,25 @@
             },
             "type": "object"
         },
+        "pinnedTLSCertificateSHA256Fingerprints": {
+            "additionalProperties": {
+                "items": {
+                    "type": "string"
+                },
+                "type": "array"
+            },
+            "type": "object"
+        },
+        "enforceCertificatePinning": {
+            "type": "boolean"
+        },
         "transportLibrary": {
             "additionalProperties": false,
             "properties": {
-                "baseUrl": {
+                "addressGenerationHostnameOverride": {
                     "type": "string"
                 },
-                "addressGenerationHostnameOverride": {
+                "baseUrl": {
                     "type": "string"
                 },
                 "datawalletEnabled": {

diff --git a/src/jsonSchemas/connectorConfig.ts b/src/jsonSchemas/connectorConfig.ts
@@ -24,6 +24,9 @@ export interface ConnectorConfig {
     modules: Record<string, ModuleConfiguration>;
     infrastructure: InfrastructureConfiguration;
 
+    pinnedTLSCertificateSHA256Fingerprints?: Record<string, string[]>;
+    enforceCertificatePinning?: boolean;
+
     [key: string]: any;
 }