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

@@ -3098,6 +3098,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

@@ -786,24 +786,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/integration/spec/encryption.js

@@ -22,6 +22,18 @@ describe('Encryption', function () {
     'Admiral, if we go "by the book". like Lieutenant Saavik, hours could seem like days.';
   let FILE = makeLocalUrl('/sample-image-small-one.png');
 
+  function fetchKeyWithRetry(kms, options, retries = 2) {
+    return kms.fetchKey(options).catch((error) => {
+      if (error.status !== 404 || retries === 0) {
+        throw error;
+      }
+
+      return new Promise((resolve) => setTimeout(resolve, 500)).then(() =>
+        fetchKeyWithRetry(kms, options, retries - 1)
+      );
+    });
+  }
+
   before('create test user', () =>
     testUsers.create({count: 1}).then((users) => {
       user = users[0];
@@ -35,9 +47,12 @@ describe('Encryption', function () {
   );
 
   before('create unbound key', () =>
-    webex.internal.encryption.kms.createUnboundKeys({count: 1}).then(([k]) => {
-      key = k;
-    })
+    webex.internal.encryption.kms
+      .createUnboundKeys({count: 1})
+      .then(([k]) => fetchKeyWithRetry(webex.internal.encryption.kms, {uri: k.uri}))
+      .then((k) => {
+        key = k;
+      })
   );
 
   before('fetch file fixture', () =>
@@ -47,7 +62,7 @@ describe('Encryption', function () {
         responseType: 'buffer',
       })
       .then((res) => {
-        FILE = res.body;
+        FILE = Buffer.from(res.body);
       })
   );