feat(internal-plugin-encryption): validate kms cert

.gitignore

@@ -37,6 +37,8 @@ tasks/selenium
 .grunt
 .github-publish
 .idea
+.kms-caroots.json
+.kms-caroots.bootstrap.js
 .npm
 .nvm
 .python-version

docs/samples/browser-plugin-meetings/app.js

@@ -141,6 +141,10 @@ function generateWebexConfig({credentials}) {
       },
       enableAutomaticLLM: enableLLM.checked,
     },
+    // Samples don't ship a KMS CA root bundle, so disable cert validation.
+    encryption: {
+      shouldValidateKMSCertificate: false,
+    },
     credentials,
     // Any other sdk config we need
   };

docs/samples/browser-read-status/app.js

@@ -29,7 +29,10 @@ let haveFetchedAll = false;
 function authorize() {
   webex = Webex.init({
     config: {
-
+      // Samples don't ship a KMS CA root bundle, so disable cert validation.
+      encryption: {
+        shouldValidateKMSCertificate: false,
+      },
     },
     credentials: {
       access_token: document.getElementById('access-token').value

docs/samples/browser-socket/app.js

@@ -26,7 +26,10 @@ function authorize() {
   // eslint-disable-next-line no-multi-assign
   webex = window.webex = Webex.init({
     config: {
-
+      // Samples don't ship a KMS CA root bundle, so disable cert validation.
+      encryption: {
+        shouldValidateKMSCertificate: false,
+      },
     },
     credentials: {
       access_token: document.getElementById('access-token').value

docs/samples/calling/app.js

@@ -284,6 +284,7 @@ async function initCalling(e) {
         kmsMaxTimeout: 40000,
         batcherMaxCalls: 30,
         caroots: null,
+        shouldValidateKMSCertificate: false,
       },
       dss: {},
     },

docs/samples/contact-center/app.js

@@ -3096,6 +3096,10 @@ function generateWebexConfig({credentials}) {
       disableWebRTCRegistration: isWebRTCRegistrationDisabled,
       enableWxBetterTogether: isWxBetterTogetherEnabled,
     },
+    // Samples don't ship a KMS CA root bundle, so disable cert validation.
+    encryption: {
+      shouldValidateKMSCertificate: false,
+    },
     credentials,
   };
 }

docs/samples/plugin-encryption/app.js

@@ -68,6 +68,10 @@ async function initWebex(e) {
       logger: {
         level: 'debug', // set the desired log level
       },
+      // Samples don't ship a KMS CA root bundle, so disable cert validation.
+      encryption: {
+        shouldValidateKMSCertificate: false,
+      },
     },
     credentials: {
       access_token: tokenElm.value

package.json

@@ -59,6 +59,7 @@
     "test:integration": "node ./tooling/index.js test --integration --browser",
     "test:ci:github": "node ./tooling/index.js ci --github",
     "test:ci:integration": "node ./tooling/index.js ci --integration",
+    "caroots:generate": "webex-kms-caroots",
     "distsrc": "find ./packages -name 'package.json' -print0 | xargs -0 sed -ibak 's#\"main\": \"dist/index.js#\"main\": \"src/index.js#' && find ./packages -name '*bak' -print0 | xargs -0 rimraf",
     "srcdist": "find ./packages -name 'package.json' -print0 | xargs -0 sed -ibak 's#\"main\": \"src/index.js#\"main\": \"dist/index.js#' && find ./packages -name '*bak' -print0 | xargs -0 rimraf",
     "get-current-version": "node ./tooling/index.js version current",

packages/@webex/internal-plugin-encryption/README.md

@@ -29,6 +29,87 @@ const webex = new WebexCore();
 webex.internal.encryption.WHATEVER;
 ```
 
+## KMS certificate validation
+
+When the SDK negotiates an ECDH key with the KMS, it validates the KMS
+certificate chain against a set of trusted CA roots. This is controlled by these
+configuration options on the `encryption` config:
+
+- `shouldValidateKMSCertificate` — whether to validate the KMS certificate
+  chain. Defaults to `true` as a secure default. When enabled the SDK **fails
+  closed**: a `caroots` bundle must be configured and the chain must validate
+  against it, otherwise the ECDH negotiation fails. Set to `false` to
+  temporarily opt out of validation, for example while upgrading and wiring up
+  the CA root bundle.
+- `caroots` — an array of raw base64-encoded CA root certificates. Required when
+  `shouldValidateKMSCertificate` is `true`.
+- `carootsReportOnly` — an additional array of CA roots validated alongside
+  `caroots`. A failure here is only reported as a metric instead of failing the
+  negotiation, which lets a new bundle be trialled in parallel with the enforced
+  `caroots`.
+
+Supplying the CA roots is the responsibility of the consuming application. The
+SDK does not ship a bundle, so that certificate updates don't require an SDK
+upgrade. Cisco first-party clients should source their roots from the Cisco
+Trusted Root Store, using the **Union** bundle:
+<https://www.cisco.com/security/pki/trs/readme.html>
+
+### Generating the CA roots
+
+Use the [`@webex/kms-caroots`](https://github.com/webex/webex-js-sdk/tree/master/packages/%40webex/kms-caroots)
+package, which downloads the Cisco Union bundle, verifies its signature against
+the pinned Cisco trust anchors, and decodes it into the `caroots` format (an
+array of raw base64-encoded certificates). It requires the `openssl` binary on
+`PATH`.
+
+```bash
+# Print the JSON array to stdout
+npx webex-kms-caroots
+
+# Or write it to a file
+npx webex-kms-caroots --out ./caroots.json
+```
+
+```js
+const {generateKmsCaroots} = require('@webex/kms-caroots');
+
+const caroots = await generateKmsCaroots();
+const webex = new WebexCore({config: {encryption: {caroots}}});
+```
+
+The SDK itself does no file or network I/O to obtain roots — supplying them is a
+build/config concern for the consuming application (important since a prebuilt
+library cannot read files in the browser).
+
+The SDK's own integration/browser tests generate these roots automatically: the
+test runner (`@webex/legacy-tools`) calls `@webex/kms-caroots` and configures
+webex-core before the tests run, so the KMS certificate is validated against the
+real trust store.
+
+### Configuring manually
+
+The referenced Cisco page is authoritative for how to download, verify, and
+extract the bundle. Each `caroots` entry is the raw base64-encoded certificate
+(the DER body, without the `-----BEGIN/END CERTIFICATE-----` lines or newlines):
+
+```js
+import '@webex/internal-plugin-encryption';
+
+import WebexCore from '@webex/webex-core';
+
+const webex = new WebexCore({
+  config: {
+    encryption: {
+      // Raw base64-encoded certificates extracted from the Cisco Union bundle
+      caroots: [
+        'MIIF8TCCA9mgAwIBAgIIVE2lvEA1VlowDQYJKoZIhvcNAQELBQAw...',
+        // ...additional roots
+      ],
+    },
+  },
+});
+```
+
 ## Maintainers
 
 This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).

packages/@webex/internal-plugin-encryption/src/config.js

@@ -48,8 +48,26 @@ export default {
     batcherMaxWait: 150,
 
     /**
-     * PEM encoded CA root bundle used to validate the KMS certificate chain.
-     * When omitted, the KMS certificate chain signature is not verified.
+     * Whether to validate the KMS certificate chain against `caroots`. Defaults
+     * to true as a secure default: when enabled the KMS certificate must
+     * validate against a configured `caroots` bundle, and a missing bundle
+     * fails closed. Set to false to temporarily opt out of validation, e.g.
+     * while upgrading and wiring up the CA root bundle.
+     * @type {boolean}
+     */
+    shouldValidateKMSCertificate: true,
+
+    /**
+     * CA root bundle used to validate the KMS certificate chain, as an array of
+     * raw base64-encoded certificates (the DER body, without the
+     * -----BEGIN/END CERTIFICATE----- lines). Required when
+     * `shouldValidateKMSCertificate` is true.
+     *
+     * Supplied by the consuming application at build/config time; the SDK does
+     * not ship a bundle and does no file/network I/O to obtain one. Cisco
+     * first-party clients should source these roots from the Cisco Trusted Root
+     * Store Union bundle. See the plugin README, tooling/generate-kms-caroots.js,
+     * and https://www.cisco.com/security/pki/trs/readme.html for details.
      * @type {?string[]}
      */
     caroots: undefined,

packages/@webex/internal-plugin-encryption/src/kms-certificate-validation.js

@@ -198,16 +198,21 @@ const validateCertificatesSignature = (certificates, caroots = []) => {
 
 /**
  * Validates the information provided by the KMS. This is a curried function.
- * The first function takes the caroots param and returns a second function.
- * The second function takes the credentials of the KMS and validates it
- * @param {string[]} caroots PEM encoded certificates that will be used
- *   as Certificate Authorities
- * @param {Object} jwt Object containing the fields necessary to
- *   validate the KMS
- * @returns {Promise} when resolved will return the jwt
+ * The first function takes the validation options and returns a second
+ * function. The second function takes the credentials of the KMS and validates
+ * it
+ * @param {Object} [options]
+ * @param {string[]} [options.caroots] base64-encoded certificates that will be
+ *   used as Certificate Authorities
+ * @param {boolean} [options.validateSignature=true] when true, the KMS
+ *   certificate chain must validate against `caroots`; if no `caroots` are
+ *   provided the validation fails closed. Set to false to skip signature
+ *   validation entirely.
+ * @returns {Function} function that takes the jwt and returns a Promise which,
+ *   when resolved, returns the jwt
  */
 const validateKMS =
-  (caroots) =>
+  ({caroots, validateSignature = true} = {}) =>
   (jwt = {}) =>
     Promise.resolve().then(() => {
       validateKtyHeader(jwt);
@@ -221,12 +226,16 @@ const validateKMS =
       validateCommonName(certificates, jwt);
       validatePublicCertificate(certificates, jwt);
 
-      // Skip validating signatures if no CA roots were provided
-      const promise = caroots
-        ? validateCertificatesSignature(certificates, caroots)
-        : Promise.resolve();
+      if (!validateSignature) {
+        return jwt;
+      }
+
+      // Fail closed: signature validation is required but no CA roots exist
+      if (!(isArray(caroots) && caroots.length > 0)) {
+        throwError('no CA roots configured to validate the KMS certificate against');
+      }
 
-      return promise.then(() => jwt);
+      return validateCertificatesSignature(certificates, caroots).then(() => jwt);
     });
 
 export default validateKMS;

packages/@webex/internal-plugin-encryption/src/kms.js

@@ -784,24 +784,28 @@ const KMS = WebexPlugin.extend({
   },
 
   /**
-   * Validates the KMS static public key against the configured CA roots. The
-   * enforced `caroots` bundle rejects on failure. When a `carootsReportOnly`
-   * bundle is also configured, it is validated in addition to `caroots`, but a
-   * failure against it is only reported as a metric so a new bundle can be
-   * trialled without risking failure.
+   * Validates the KMS static public key against the configured CA roots.
+   * Validation is enabled by default (`shouldValidateKMSCertificate`) and fails
+   * closed: when enabled the enforced `caroots` bundle must be configured and
+   * the chain must validate against it. When a `carootsReportOnly` bundle is
+   * also configured, it is validated in addition to `caroots`, but a failure
+   * against it is only reported as a metric so a new bundle can be trialled
+   * without risking failure.
    * @private
    * @param {Object} kmsStaticPubKey
    * @returns {Promise<Object>} the KMS static public key
    */
   _validateKMSStaticPubKey(kmsStaticPubKey) {
-    const {caroots, carootsReportOnly} = this.config;
+    const {caroots, carootsReportOnly, shouldValidateKMSCertificate} = this.config;
 
-    return validateKMS(caroots)(kmsStaticPubKey).then((jwt) => {
+    return validateKMS({caroots, validateSignature: shouldValidateKMSCertificate})(
+      kmsStaticPubKey
+    ).then((jwt) => {
       if (!carootsReportOnly) {
         return jwt;
       }
 
-      return validateKMS(carootsReportOnly)(kmsStaticPubKey)
+      return validateKMS({caroots: carootsReportOnly, validateSignature: true})(kmsStaticPubKey)
         .catch((reason) => {
           this.logger.warn('kms: report-only certificate validation failed', reason);
 

packages/@webex/internal-plugin-encryption/test/unit/spec/kms-certificate-validation.js

@@ -40,7 +40,7 @@ const VALID_JWT_SAN = {
   e: 'AQAB',
 };
 
-const validate = validateCert(caroots);
+const validate = validateCert({caroots});
 
 describe('internal-plugin-encryption', () => {
   describe('kms-certificate-validation', () => {
@@ -152,14 +152,22 @@ describe('internal-plugin-encryption', () => {
       return assert.isRejected(validate(jwt), KMSError);
     });
 
-    it('accepts self signed certificate if no CA roots.', () => {
+    it('rejects when validation is required but no CA roots are configured', () =>
+      assert.isRejected(validateCert()(VALID_JWT), KMSError));
+
+    it('rejects when validation is required and CA roots are empty', () =>
+      assert.isRejected(validateCert({caroots: []})(VALID_JWT), KMSError));
+
+    it('accepts self signed certificate when signature validation is disabled', () => {
       const jwt = {
         ...VALID_JWT,
         x5c: x5cSelfSigned,
         n: x5cSelfSignedModulus,
       };
 
-      return validateCert()(jwt).then((results) => assert.equal(results, jwt));
+      return validateCert({validateSignature: false})(jwt).then((results) =>
+        assert.equal(results, jwt)
+      );
     });
   });
 });

packages/@webex/internal-plugin-encryption/test/unit/spec/kms.js

@@ -263,6 +263,7 @@ describe('internal-plugin-encryption', () => {
 
       beforeEach(() => {
         webex.internal.metrics = {submitClientMetrics: sinon.stub()};
+        webex.internal.encryption.config.shouldValidateKMSCertificate = true;
         webex.internal.encryption.config.caroots = caroots;
         webex.internal.encryption.config.carootsReportOnly = undefined;
       });
@@ -276,6 +277,27 @@ describe('internal-plugin-encryption', () => {
         assert.notCalled(webex.internal.metrics.submitClientMetrics);
       });
 
+      it('rejects when validation is enabled but no caroots are configured', async () => {
+        webex.internal.encryption.config.caroots = undefined;
+
+        await assert.isRejected(
+          webex.internal.encryption.kms._validateKMSStaticPubKey(validKey),
+          /INVALID KMS/
+        );
+
+        assert.notCalled(webex.internal.metrics.submitClientMetrics);
+      });
+
+      it('resolves without validating when shouldValidateKMSCertificate is false', async () => {
+        webex.internal.encryption.config.shouldValidateKMSCertificate = false;
+        webex.internal.encryption.config.caroots = undefined;
+
+        const result = await webex.internal.encryption.kms._validateKMSStaticPubKey(validKey);
+
+        assert.equal(result, validKey);
+        assert.notCalled(webex.internal.metrics.submitClientMetrics);
+      });
+
       it('resolves without a metric when no report-only bundle is configured', async () => {
         const result = await webex.internal.encryption.kms._validateKMSStaticPubKey(validKey);
 

packages/@webex/kms-caroots/.eslintrc.js

@@ -0,0 +1,17 @@
+module.exports = {
+  root: true,
+  ignorePatterns: ['*.d.ts'],
+  env: {
+    node: true,
+    es2021: true,
+  },
+  parserOptions: {
+    ecmaVersion: 2021,
+    sourceType: 'script',
+  },
+  extends: ['eslint:recommended'],
+  rules: {
+    'no-console': 'off',
+    'no-plusplus': 'off',
+  },
+};