Merge pull request #107 from BitGo/WP-5523-seperate-mtls-configs

feat: seperate client/server mtls configs

Author: pranavjain97

.github/workflows/build-and-test.yaml

@@ -132,8 +132,8 @@ jobs:
         run: npm test
         env:
           NODE_OPTIONS: '--max-old-space-size=4096'
-          MASTER_BITGO_EXPRESS_KEYPATH: ./test-ssl-key.pem
-          MASTER_BITGO_EXPRESS_CRTPATH: ./test-ssl-cert.pem
+          MASTER_BITGO_EXPRESS_KEYPATH: ./demo.key
+          MASTER_BITGO_EXPRESS_CRTPATH: ./demo.crt
           MTLS_ENABLED: true
           MTLS_REQUEST_CERT: true
           MTLS_REJECT_UNAUTHORIZED: false

README.md

@@ -27,6 +27,7 @@ Configuration is managed through environment variables:
 ### Network Settings
 
 - `BIND` - Address to bind to (default: localhost)
+- `IPC` - IPC socket file path (optional)
 - `TIMEOUT` - Request timeout in milliseconds (default: 305000)
 - `KEEP_ALIVE_TIMEOUT` - Keep-alive timeout (optional)
 - `HEADERS_TIMEOUT` - Headers timeout (optional)
@@ -45,8 +46,6 @@ Configuration is managed through environment variables:
 - `BITGO_CUSTOM_ROOT_URI` - Custom BitGo API root URI (optional)
 - `BITGO_CUSTOM_BITCOIN_NETWORK` - Custom Bitcoin network (optional)
 - `ADVANCED_WALLET_MANAGER_URL` - Advanced Wallet Manager URL (required)
-- `ADVANCED_WALLET_MANAGER_CERT` - Path to Advanced Wallet Manager certificate (required)
-- `AWM_SERVER_CERT_ALLOW_SELF_SIGNED` - Allow self-signed certificates from Advanced Wallet Manager (default: false)
 
 ### TLS/mTLS Configuration
 
@@ -56,37 +55,46 @@ Both modes use the same TLS configuration variables:
 
 - `TLS_MODE` - Set to either "mtls" or "disabled" (defaults to "mtls" if not set)
 
-#### Certificate Configuration (required when TLS_MODE=mtls)
+#### mTLS Server Configuration (for incoming connections)
 
-**Option 1: Certificate Files**
+- `SERVER_TLS_KEY_PATH` - Path to the private key for the mTLS server
+- `SERVER_TLS_CERT_PATH` - Path to the certificate for the mTLS server
+- `SERVER_TLS_KEY` - The private key as a string (alternative to `_PATH`)
+- `SERVER_TLS_CERT` - The certificate as a string (alternative to `_PATH`)
 
-- `TLS_KEY_PATH` - Path to private key file (used for both inbound mTLS server and outbound mTLS client to KMS)
-- `TLS_CERT_PATH` - Path to certificate file (used for both inbound mTLS server and outbound mTLS client to KMS)
+#### mTLS Client Authentication Settings (for incoming connections)
 
-**Option 2: Environment Variables**
+- `ALLOW_SELF_SIGNED` - Allow self-signed certificates (default: false)
+- `MTLS_ALLOWED_CLIENT_FINGERPRINTS` - Comma-separated list of allowed client certificate fingerprints (optional)
 
-- `TLS_KEY` - Private key content (PEM format, used for both inbound and outbound)
-- `TLS_CERT` - Certificate content (PEM format, used for both inbound and outbound)
+#### Outbound mTLS to AWM (Master Express Mode only)
 
-#### mTLS Settings (when TLS_MODE=mtls)
+- `AWM_CLIENT_TLS_KEY_PATH` - Path to the client key that Master Express presents to the AWM
+- `AWM_CLIENT_TLS_CERT_PATH` - Path to the client cert that Master Express presents to the AWM
+- `AWM_CLIENT_TLS_KEY` - The client key as a string (alternative to `_PATH`)
+- `AWM_CLIENT_TLS_CERT` - The client cert as a string (alternative to `_PATH`)
+- `AWM_SERVER_CA_CERT_PATH` - Path to the CA certificate to verify the AWM server (required when TLS_MODE=mtls)
+- `AWM_SERVER_CA_CERT` - The CA certificate as a string (alternative to `_PATH`)
+- `AWM_SERVER_CERT_ALLOW_SELF_SIGNED` - Allow self-signed certificates from the AWM (default: false)
+- **Required:** Client certificates must be explicitly provided for outbound mTLS connections
 
-- `MTLS_REQUEST_CERT` - Request client certificates (default: true)
-- `CLIENT_CERT_ALLOW_SELF_SIGNED` - Allow self-signed certificates for incoming client connections (default: false)
-- `MTLS_ALLOWED_CLIENT_FINGERPRINTS` - Comma-separated list of allowed fingerprints for incoming client connections (optional)
+#### Outbound mTLS to KMS (AWM Mode only)
 
-#### Outbound mTLS to KMS
-
-- When `TLS_MODE=mtls`, outbound mTLS to KMS is enabled by default.
-- The same `TLS_CERT` and `TLS_KEY` are used as the client certificate and key for outbound mTLS requests to KMS.
-- `KMS_TLS_CERT_PATH` - Path to the CA certificate to verify the KMS server (required when outbound mTLS is enabled).
-- If `TLS_MODE=disabled`, outbound mTLS to KMS is also disabled by default.
+- `KMS_CLIENT_TLS_KEY_PATH` - Path to the client key that AWM presents to the KMS
+- `KMS_CLIENT_TLS_CERT_PATH` - Path to the client cert that AWM presents to the KMS
+- `KMS_CLIENT_TLS_KEY` - The client key as a string (alternative to `_PATH`)
+- `KMS_CLIENT_TLS_CERT` - The client cert as a string (alternative to `_PATH`)
+- `KMS_SERVER_CA_CERT_PATH` - Path to the CA certificate to verify the KMS server (required when TLS_MODE=mtls)
+- `KMS_SERVER_CA_CERT` - The CA certificate as a string (alternative to `_PATH`)
 - `KMS_SERVER_CERT_ALLOW_SELF_SIGNED` - Allow self-signed certificates from the KMS (default: false)
-
-> **Note:** If you want to use a different client certificate for KMS, you will need to extend the configuration. By default, the same cert/key is used for both inbound and outbound mTLS.
+- **Required:** Client certificates must be explicitly provided for outbound mTLS connections
 
 ### Logging and Debug
 
 - `HTTP_LOGFILE` - Path to HTTP request log file (optional, used by Morgan for HTTP access logs)
+- `NODE_ENV` - Node environment (development, production, test)
+- `LOG_LEVEL` - Log level (silent, error, warn, info, http, debug)
+- `RECOVERY_MODE` - Enable recovery mode (default: false)
 
 ## Quick Start
 
@@ -107,31 +115,31 @@ openssl req -new -x509 -key server.key -out server.crt -days 365 -subj "/CN=loca
 ```bash
 export APP_MODE=advanced-wallet-manager
 export KMS_URL=https://your-kms-service
-export KMS_TLS_CERT_PATH=./server.crt
+export KMS_SERVER_CA_CERT_PATH=./server.crt
 export KMS_SERVER_CERT_ALLOW_SELF_SIGNED=true
-export TLS_KEY_PATH=./server.key
-export TLS_CERT_PATH=./server.crt
+export SERVER_TLS_KEY_PATH=./server.key
+export SERVER_TLS_CERT_PATH=./server.crt
 export CLIENT_CERT_ALLOW_SELF_SIGNED=true
 npm start
 ```
 
-### 4. Start Master Express
+### 3. Start Master Express
 
 In a separate terminal:
 
 ```bash
 export APP_MODE=master-express
 export BITGO_ENV=test
-export TLS_KEY_PATH=./server.key
-export TLS_CERT_PATH=./server.crt
+export SERVER_TLS_KEY_PATH=./server.key
+export SERVER_TLS_CERT_PATH=./server.crt
 export ADVANCED_WALLET_MANAGER_URL=https://localhost:3080
-export ADVANCED_WALLET_MANAGER_CERT=./server.crt
+export AWM_SERVER_CA_CERT_PATH=./server.crt
 export AWM_SERVER_CERT_ALLOW_SELF_SIGNED=true
 export CLIENT_CERT_ALLOW_SELF_SIGNED=true
 npm start
 ```
 
-### 5. Test the Connection
+### 4. Test the Connection
 
 Test that Master Express can communicate with Advanced Wallet Manager:
 
@@ -157,28 +165,35 @@ curl -k -X POST https://localhost:3081/ping/advancedWalletManager
 ```bash
 export APP_MODE=advanced-wallet-manager
 export KMS_URL=https://production-kms.example.com
-export TLS_KEY_PATH=/secure/path/advanced-wallet-manager.key
-export TLS_CERT_PATH=/secure/path/advanced-wallet-manager.crt
-export MTLS_REQUEST_CERT=true
+export SERVER_TLS_KEY_PATH=/secure/path/awm-server.key
+export SERVER_TLS_CERT_PATH=/secure/path/awm-server.crt
+export KMS_CLIENT_TLS_KEY_PATH=/secure/path/awm-kms-client.key
+export KMS_CLIENT_TLS_CERT_PATH=/secure/path/awm-kms-client.crt
+export KMS_SERVER_CA_CERT_PATH=/secure/path/kms-ca.crt
 export CLIENT_CERT_ALLOW_SELF_SIGNED=false
 export MTLS_ALLOWED_CLIENT_FINGERPRINTS=ABC123...,DEF456...
 npm start
 ```
 
+**Note:** Client certificates for outbound connections must be separate from server certificates for security reasons.
+
 #### Master Express (Production)
 
 ```bash
 export APP_MODE=master-express
 export BITGO_ENV=prod
-export TLS_KEY_PATH=/secure/path/master.key
-export TLS_CERT_PATH=/secure/path/master.crt
+export SERVER_TLS_KEY_PATH=/secure/path/master-server.key
+export SERVER_TLS_CERT_PATH=/secure/path/master-server.crt
+export AWM_CLIENT_TLS_KEY_PATH=/secure/path/master-awm-client.key
+export AWM_CLIENT_TLS_CERT_PATH=/secure/path/master-awm-client.crt
 export ADVANCED_WALLET_MANAGER_URL=https://advanced-wallet-manager.internal.example.com:3080
-export ADVANCED_WALLET_MANAGER_CERT=/secure/path/advanced-wallet-manager.crt
-export MTLS_REQUEST_CERT=true
+export AWM_SERVER_CA_CERT_PATH=/secure/path/awm-ca.crt
 export CLIENT_CERT_ALLOW_SELF_SIGNED=false
 npm start
 ```
 
+**Note:** Client certificates for outbound connections must be separate from server certificates for security reasons.
+
 ## Container Deployment with Podman
 
 First, build the container image:
@@ -201,8 +216,8 @@ podman run -d \
   -e APP_MODE=advanced-wallet-manager \
   -e BIND=0.0.0.0 \
   -e TLS_MODE=mtls \
-  -e TLS_KEY_PATH=/app/certs/advanced-wallet-manager-key.pem \
-  -e TLS_CERT_PATH=/app/certs/advanced-wallet-manager-cert.pem \
+  -e SERVER_TLS_KEY_PATH=/app/certs/advanced-wallet-manager-key.pem \
+  -e SERVER_TLS_CERT_PATH=/app/certs/advanced-wallet-manager-cert.pem \
   -e KMS_URL=host.containers.internal:3000 \
   -e NODE_ENV=development \
   -e CLIENT_CERT_ALLOW_SELF_SIGNED=true \
@@ -221,10 +236,10 @@ podman run -d \
   -e APP_MODE=master-express \
   -e BIND=0.0.0.0 \
   -e TLS_MODE=mtls \
-  -e TLS_KEY_PATH=/app/certs/test-ssl-key.pem \
-  -e TLS_CERT_PATH=/app/certs/test-ssl-cert.pem \
+  -e SERVER_TLS_KEY_PATH=/app/certs/test-ssl-key.pem \
+  -e SERVER_TLS_CERT_PATH=/app/certs/test-ssl-cert.pem \
   -e ADVANCED_WALLET_MANAGER_URL=https://host.containers.internal:3080 \
-  -e ADVANCED_WALLET_MANAGER_CERT=/app/certs/advanced-wallet-manager-cert.pem \
+  -e AWM_SERVER_CA_CERT_PATH=/app/certs/advanced-wallet-manager-cert.pem \
   -e CLIENT_CERT_ALLOW_SELF_SIGNED=true \
   bitgo-onprem-express
 
@@ -295,9 +310,8 @@ openssl x509 -in certificate.crt -text -noout
 ```bash
 # Check that required variables are set
 env | grep -E "(APP_MODE|KMS_URL|ADVANCED_WALLET_MANAGER|TLS_)"
-``
+```
 
 ## License
 
 MIT
-```

demo.crt

@@ -0,0 +1,24 @@
+-----BEGIN CERTIFICATE-----
+MIID9TCCAt2gAwIBAgIUKCkJ6fcl2+2EsK0n9v7iqGu1qgIwDQYJKoZIhvcNAQEL
+BQAwgYkxCzAJBgNVBAYTAkNBMQswCQYDVQQIDAJPTjEQMA4GA1UEBwwHVG9yb250
+bzEhMB8GA1UECgwYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMQ8wDQYDVQQDDAZQ
+cmFuYXYxJzAlBgkqhkiG9w0BCQEWGHByYW5hdmphaW4xMTk3QGdtYWlsLmNvbTAe
+Fw0yNTA4MDEyMjE4MTVaFw0yNjA4MDEyMjE4MTVaMIGJMQswCQYDVQQGEwJDQTEL
+MAkGA1UECAwCT04xEDAOBgNVBAcMB1Rvcm9udG8xITAfBgNVBAoMGEludGVybmV0
+IFdpZGdpdHMgUHR5IEx0ZDEPMA0GA1UEAwwGUHJhbmF2MScwJQYJKoZIhvcNAQkB
+FhhwcmFuYXZqYWluMTE5N0BnbWFpbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQC+QfWH5GbQidrIawVbjZ7RL/uZtF7wbmacER2wYlOO7Ib+Je1h
+03P3BQlI5bTBE3KkxrwDqycxWk/MA9hj2VT1tL3+bE/yuYVaOgGN4fiibG9Cc8MG
+MrWsZKRvP5Hy/ZUobVfLAPXvpUKM+nf//MaO6x9F/9TEwIb9rqfoD+bynL1s2LhR
+wr2ppYZXoOmdS/yhEiXloX4fO//5ivC/1zpt6bYaqdA2WAkBHyM24LOm02lJvRV+
+oq5dFxH0c0YCAEe05QfVLXgb/S/JTpxfOlabAVomb9+9ESOpEWqCyOo3U3QaSh49
+FdCUGFnaZHXc4324E/La955dSdeziLlDKXrdAgMBAAGjUzBRMB0GA1UdDgQWBBSe
+jCcPNqJHmbsXhsdKaJj9BUIhfTAfBgNVHSMEGDAWgBSejCcPNqJHmbsXhsdKaJj9
+BUIhfTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQARJW7QnfwS
+afy2M9ShDC7mqVa54LOaT6Ics+QYRPvJIRazlkODGm/n49rYZatgUNN1ouK6m7xk
+HuycnsWFZKly+w0/ugoe9fK59KUJCFNtPlTrAmJM4/x2yzSky/XlqEt0n8L8U8N1
+dbWcIC8EWNcUVKCKiS8ecoOm4G34I7YFOc5JwqEPJwfaQ76EHTKwEQe3MtM+wZaQ
+TrSm8WuYwlio53nyoyHHNGnJLKuN9DjOp9VdAtJcgCU8TutlKxAn1aDixrjcuzrk
+cqxn97OnE6eXsHurFY193lFs0HWpIAztXhjdtLjFJy68nVVmPcWAAWbcu4JhbBUX
+jZJ7DNuCDOoV
+-----END CERTIFICATE-----

demo.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC+QfWH5GbQidrI
+awVbjZ7RL/uZtF7wbmacER2wYlOO7Ib+Je1h03P3BQlI5bTBE3KkxrwDqycxWk/M
+A9hj2VT1tL3+bE/yuYVaOgGN4fiibG9Cc8MGMrWsZKRvP5Hy/ZUobVfLAPXvpUKM
++nf//MaO6x9F/9TEwIb9rqfoD+bynL1s2LhRwr2ppYZXoOmdS/yhEiXloX4fO//5
+ivC/1zpt6bYaqdA2WAkBHyM24LOm02lJvRV+oq5dFxH0c0YCAEe05QfVLXgb/S/J
+TpxfOlabAVomb9+9ESOpEWqCyOo3U3QaSh49FdCUGFnaZHXc4324E/La955dSdez
+iLlDKXrdAgMBAAECggEASWNI8eekzxj1xuwdL3EDy14OV34vRt/W/alOgeyTnaRX
+9+2qUNtPNn//Ulqkq/sz9CJigKnC3vMep6vuCqnY70QOK3cdKZvtN937Hn8FOKXK
+DuB3YEssL7jMgssLIac2I1d2D2yp8QwWjSnKIvieoJ9KO2aQ7Gn1SCJYSxfjNj6b
+Z4BBnLgfOZebf2zDnXOnfee35v00zLw6EFyMhdwPNEwy505M32EQLu6qyPllSG4a
+srlqRsOMyo5iWEV7P8EBzquaWDB/B9PZWkG9JTokaXPFQJnX6Kn5ha5wcuoKBdVy
+R0mgPgtfhpvN2Ott4YQdIuo2PTfpc/Y1cTqRTuKWowKBgQDz9F8CmauFHmzrCp6n
+cZcW+Z2kUbjI25qat53G4QHAVIcWhMyQaAi+9dbVAuH9r3f1BWb8TcCJ+ut5fONL
+WR4oJpgeG6UVMaF15HqSj2FDic1JzY2jWtbKKiytRXlPCNGeCftQalZzsJtTI0Bl
+TqFj32flI+ZsfJR3v+9a6Nr14wKBgQDHptlyggV9TCXtSCfLAbaUJeqOVymTymrr
+qMcnYp99jHy7tmZIdmULxkeyF54uAX1/xc+nvSGFIO09rH3nEnZovDnvbFPpiFZb
+bNMxmGahW4//boTFSFRxxecknDBcUin0b8YjQER6i4tHtj3qUUjvW/J1XlWzZo1z
+cPF4oI6oPwKBgQDw9jaGXf0iHrxcqP+uyq7/XY1NSf8oPmmGWsl4MLXHIHbSUlew
+Z2IEJNWPTyqjphbpqO1hVvdQEs1WEXp86Ui1RfHJA2ta9MvTo9tCOmdLC6j/Ng6q
+BMbVpzS77Tx2SXKrFJbshixgV1gElXQ83J7jBD8eAQjPrXoEkku80vW8GwKBgGmC
+SWP0RoZi2aA+A5mK/DvqlbxHX9eUn1COz0CHJBYrSjfBOuiMePXyAS2iwZs6emIt
+3YGdt7stHXL8V0ToQt8yqcNXkjjWLhz+s9V/3qzjQIQSmePQR6Agn/h++iev3DAr
+aaBzdDz2xdJOAwZzkoG8K7PO+KdoSNR7GYFQCFPtAoGAFlvGvoX6WvQ47AwmVLgk
+gBfe1nruqVyz7kubWsy/V2iAkzMcWUUrcvpZgqAy9pRJlWs1wM91SjtFbZ+/UPwQ
+HGCGuclXo89b5uCTYVA0B2PxivY9F+RcQtTJZvTGBGIAC5m1+EqR9pVWY9527WD6
+7/MjOwPWTPT7j0jwBkXTo1w=
+-----END PRIVATE KEY-----

enclaved-express-cert.pem

@@ -16,7 +16,7 @@
     "test:coverage": "nyc mocha --require ts-node/register 'src/**/__tests__/**/*.test.ts'",
     "lint": "eslint --quiet --ignore-pattern scripts/bump-version.ts .",
     "lint:fix": "eslint --quiet --ignore-pattern scripts/bump-version.ts . --fix",
-    "generate-test-ssl": "openssl req -x509 -newkey rsa:2048 -keyout test-ssl-key.pem -out test-ssl-cert.pem -days 365 -nodes -subj '/CN=localhost'",
+    "generate-test-ssl": "openssl req -x509 -newkey rsa:2048 -keyout demo.key -out demo.crt -days 365 -nodes -subj '/CN=localhost'",
     "generate:openapi:masterExpress": "npx @api-ts/openapi-generator --name @bitgo/master-bitgo-express ./src/api/master/routers/index.ts > masterBitgoExpress.json",
     "container:build": "podman build -t bitgo-onprem-express .",
     "bump-versions": "ts-node scripts/bump-version.ts"

enclaved-express-key.pem

@@ -49,7 +49,7 @@ describe('POST /api/:coin/wallet/:walletId/accelerate', () => {
       disableEnvCheck: true,
       authVersion: 2,
       advancedWalletManagerUrl: advancedWalletManagerUrl,
-      advancedWalletManagerCert: 'test-cert',
+      awmServerCaCert: 'test-cert',
       tlsMode: TlsMode.DISABLED,
       clientCertAllowSelfSigned: true,
     };

package.json

@@ -53,7 +53,7 @@ describe('POST /api/:coin/wallet/:walletId/consolidate', () => {
       disableEnvCheck: true,
       authVersion: 2,
       advancedWalletManagerUrl: advancedWalletManagerUrl,
-      advancedWalletManagerCert: 'test-cert',
+      awmServerCaCert: 'test-cert',
       tlsMode: TlsMode.DISABLED,
       clientCertAllowSelfSigned: true,
     };

src/__tests__/api/master/accelerate.test.ts

@@ -49,7 +49,7 @@ describe('POST /api/:coin/wallet/:walletId/consolidateunspents', () => {
       disableEnvCheck: true,
       authVersion: 2,
       advancedWalletManagerUrl: advancedWalletManagerUrl,
-      advancedWalletManagerCert: 'test-cert',
+      awmServerCaCert: 'test-cert',
       tlsMode: TlsMode.DISABLED,
       clientCertAllowSelfSigned: true,
     };