KMS integration with AWS Key Management Service

[panva]

Note

Author: @panva
Target version: ^9.5.0

Warning

No guarantees this is bug-free, if you find a bug please comment on the discussion

Caution

ExternalSigningKey support is an experimental feature.

This example enables PS256, ES256, Ed25519, and ML-DSA-44 signatures produced by private keys stored in AWS Key Management Service.

Ed25519 uses the fully specified Ed25519 JWS algorithm identifier. AWS KMS must receive the JWS Signing Input as a RAW message when ED25519_SHA_512 is selected; pre-hashing it would produce a different signature scheme.

Important

Create the Ed25519 KMS key with KeySpec: ECC_NIST_EDWARDS25519 and KeyUsage: SIGN_VERIFY. Do not substitute ED25519_PH_SHA_512; Ed25519ph is not the Ed25519 JWS algorithm.

Warning

AWS KMS accepts at most 4096 bytes in a RAW Sign request. Consequently, the complete JWS Signing Input for an Ed25519 signature must not exceed 4096 bytes.

import * as crypto from "node:crypto";

import * as KMS from "@aws-sdk/client-kms";
import { derToJose } from "ecdsa-sig-formatter";
import { Provider, ExternalSigningKey } from "oidc-provider";

const KeySpecs = {
  RSA_2048: 'PS256',
  RSA_3072: 'PS256',
  RSA_4096: 'PS256',
  ECC_NIST_P256: 'ES256',
  ECC_NIST_EDWARDS25519: 'Ed25519',
  ML_DSA_44: 'ML-DSA-44',
};

const SigningAlgorithmSpecs = {
  PS256: KMS.SigningAlgorithmSpec.RSASSA_PSS_SHA_256,
  ES256: KMS.SigningAlgorithmSpec.ECDSA_SHA_256,
  Ed25519: KMS.SigningAlgorithmSpec.ED25519_SHA_512,
  'ML-DSA-44': KMS.SigningAlgorithmSpec.ML_DSA_SHAKE_256,
};

const client = new KMS.KMSClient();

function shake256(data, outputLength) {
  return crypto.hash('shake256', data, {
    outputEncoding: 'buffer',
    outputLength,
  });
}

function sha256(data) {
  return crypto.hash('sha256', data, 'buffer');
}

class AwsKmsKey extends ExternalSigningKey {
  #KeyId;

  #alg;

  #publicKeyObject;

  #SigningAlgorithm;

  constructor(KeyId, publicKey, alg) {
    super();
    this.#KeyId = KeyId;
    this.#alg = alg;
    this.#publicKeyObject = publicKey;
    this.#SigningAlgorithm = SigningAlgorithmSpecs[alg];
  }

  get alg() {
    return this.#alg;
  }

  keyObject() {
    return this.#publicKeyObject;
  }

  #getMessageParams(data) {
    if (this.#SigningAlgorithm === KMS.SigningAlgorithmSpec.ED25519_SHA_512) {
      if (data.byteLength > 4096) {
        throw new RangeError('AWS KMS Ed25519 signing input exceeds 4096 bytes');
      }

      return {
        MessageType: KMS.MessageType.RAW,
        Message: data,
      };
    }

    if (this.#SigningAlgorithm === KMS.SigningAlgorithmSpec.ML_DSA_SHAKE_256) {
      const pubKeyBytes = Buffer.from(this.pub, 'base64url');
      const hashedPubKey = shake256(pubKeyBytes, 64);

      const externalMu = shake256(Buffer.concat([
        hashedPubKey,
        new Uint8Array([0x00, 0x00]),
        data,
      ]), 64);

      return {
        MessageType: KMS.MessageType.EXTERNAL_MU,
        Message: externalMu,
      };
    }

    return {
      MessageType: KMS.MessageType.DIGEST,
      Message: sha256(data),
    };
  }

  async sign(data) {
    const signOutput = await client.send(
      new KMS.SignCommand({
        KeyId: this.#KeyId,
        SigningAlgorithm: this.#SigningAlgorithm,
        ...this.#getMessageParams(data),
      }),
    );

    if (!signOutput.Signature) {
      throw new Error('unexpected SignCommand response', { cause: signOutput });
    }

    if (this.#SigningAlgorithm === KMS.SigningAlgorithmSpec.ECDSA_SHA_256) {
      return Buffer.from(derToJose(Buffer.from(signOutput.Signature), this.alg), 'base64url');
    }

    return signOutput.Signature;
  }
}

export async function setupKey(KeyId) {
  const describeKeyOutput = await client.send(
    new KMS.DescribeKeyCommand({
      KeyId,
    }),
  );

  if (!describeKeyOutput.KeyMetadata?.KeyId) {
    throw new Error('unexpected DescribeKeyCommand response', { cause: describeKeyOutput });
  }

  if (!describeKeyOutput.KeyMetadata.Enabled) {
    throw new Error('unexpected DescribeKeyCommandOutput.KeyMetadata.Enabled value', {
      cause: describeKeyOutput,
    });
  }

  const alg = KeySpecs[describeKeyOutput.KeyMetadata.KeySpec];

  if (!alg) {
    throw new Error('unsupported DescribeKeyCommandOutput.KeyMetadata.KeySpec value', {
      cause: describeKeyOutput,
    });
  }

  const expectedSigningAlgorithm = SigningAlgorithmSpecs[alg];

  if (!describeKeyOutput.KeyMetadata.SigningAlgorithms?.includes(expectedSigningAlgorithm)) {
    throw new Error(
      'unsupported DescribeKeyCommandOutput.KeyMetadata.SigningAlgorithms values',
      {
        cause: describeKeyOutput,
      },
    );
  }

  switch (describeKeyOutput.KeyMetadata.KeyUsage) {
    case KMS.KeyUsageType.SIGN_VERIFY:
      break;
    default:
      throw new Error('unsupported DescribeKeyCommandOutput.KeyMetadata.KeyUsage value', {
        cause: describeKeyOutput,
      });
  }

  const getPublicKeyOutput = await client.send(
    new KMS.GetPublicKeyCommand({
      KeyId,
    }),
  );

  if (!(getPublicKeyOutput.PublicKey instanceof Uint8Array)) {
    throw new Error('unexpected GetPublicKeyCommandOutput.PublicKey value', {
      cause: getPublicKeyOutput,
    });
  }

  const keyObject = crypto.createPublicKey({
    format: 'der',
    type: 'spki',
    key: getPublicKeyOutput.PublicKey,
  });

  return new AwsKmsKey(KeyId, keyObject, alg);
}

const provider = new Provider("/* your issuer identifier */", {
  jwks: {
    keys: await Promise.all([setupKey("<KeyId 1>"), setupKey("<KeyId 2>")]),
  },
  features: {
    externalSigningSupport: { enabled: true, ack: "experimental-01" },
  },
});

[autopulated]

Currently this requires the key to be available before the server can start, since the config for jwks.keys needs to be synchronously available.

Since ExternalSigningKey.sign is already async, if ExternalSigningKey.keyObject could also be async, then app startup could proceed without being blocked until the first use of keyObject?

[panva]

In the world of ESM and top level await I really don't see the point. Plus, this is just an example - adapt to your liking.

[autopulated]

I appreciate that this is true in an ideal world. But, in one case for example I have a large express app, which uses commonjs. The express setup is a large amount of, e.g.

app.register(require('./some/routes'));
app.register(require('./some/other/routes'));

require('./some/plugin')(app);
require('./some/other/plugin')(app);
require('./existing/outh-server')(app);

... etc

I'd like to add node-oidc-provider server to the app, and I need to use external signing.

I can't do:

require('./new-plugin-for-node-oidc.mjs')(app);

because I cannot configure node-oidc-provider synchronously with external signing, when the key object and ID aren't available synchronously for config.jwks. The only option is to migrate the app entry and boot to esm.

(fwiw the published types and docs for ExternalSigningKey.keyObject allow it to return a promise, but attempting to do so breaks .#ensurePublicJwk())

[panva]

Again, this example here is just that, an example. You can implement your own, overload the getters that depend on a sync returning .keyObject() with whatever suits your needs are and actually have .keyObject() be a promise if you need it to be. I've confirmed that works as intended in 78474ac.

[autopulated]

Maybe I'm missing something really obvious, but the getters in the test return a value synchronously, bypassing .keyObject(), which allows registerKey() to succeed. There's no way to do this for, e.g. .e, .n, nor the .kid when the keyObject isn't known synchronously?

[panva]

You need to prepare the public key values upfront, correct, intended. The provider can't run through its initialization without knowing the types of keys that it'll work with.