JSON Web Key Store (JWKS)

The relying party is expected to provide public keys to Myinfo in the JWK format. These public keys will be used in the following (non-exhaustive) scenarios:

• Signature JWK used to verify the signature of the client_assertion JWT presented during /token request.

• Encryption JWK used to encrypt the retrieved user's data in /person request.

The relying party is expected to host the JWKS with below specifications:

• is served behind HTTPS on port 443 using a TLS server certificate issued by a standard publicly verifiable CA issuer (no private CAs), with complete cert chain presented by the server

• is publicly accessible (no IP whitelisting, mTLS or other custom HTTP header requirements outside standard HTTP headers such as Content-Type, Accept)

• is able to respond in a timely fashion

• Contains at least 1 sig key with alg ES256

• Contains at least 1 enc key with alg ECDH-ES+A256KW

For Staging and Production environments, please ensure

• You have a separate JWKS endpoint for each environment

• Different keypairs configured in the JWKS endpoints for each environment

Generation of JSON Web Key Store

JWKS Endpoint Sample Code Sample Code to generate a Private/Public Key Pair

const jose = require('node-jose');
const crypto = require('crypto');
async function generateKey(){
  let key = crypto.generateKeyPairSync('ec', {
    namedCurve: 'prime256v1',
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
    },
  });
  let cryptoKey = await jose.JWK.asKey(key.privateKey, 'pem');
  return cryptoKey;
}

Sample Code to generate Signing and Encryption keys and create JWKS from public keys.

const jose = require('node-jose');
async function generateJwks() {
  //Creating Signing Key
  let signingKey = await generateKey();
  let publicSigningKeyJSON = signingKey.toJSON();
 
  //Creating Encryption Key
  let encryptionKey = await generateKey();
  let publicEncryptionKeyJSON = encryptionKey.toJSON();
 
    let jwks = {
      keys: [{...publicSigningKeyJSON,
              ...{use: 'sig'},
              ...{crv: 'P-256'},
              ...{alg: 'ES256'},
    },
    {...publicEncryptionKeyJSON,
              ...{use: 'enc'},
              ...{crv: 'P-256'},
              ...{alg: 'ECDH-ES+A256KW'},
    }]};
 
    console.log(JSON.stringify(jwks));
}

For production use, the private key must be generated separately in your production environment and stored directly. The Private Key should not leave your production Environment

Generating the JWK in this manner will set a default kid(Thumbprint of JWK). You may set your own value for kid, but ensure that upon signing with Private key, the correct corresponding kid is reflected in JWT header

Different keys are required to be created for Staging and Production

JWKS for signing

The signing JWK will be used to verify the client_assertion JWT provided during /token request, thereby authenticating the client.

Clients are allowed to provide multiple signature keys in the JWKS hosted on the JWKS url provided during onboarding on DPP.

The signature JWK should have the following attributes:

• Must have key use of value 'sig'

• Must be an EC key, with curves: P-256 (NIST curves, aka secp256r1)

• Must have an alg of value 'ES256'

Example EC signing key

{
    "kty": "EC",
    "use": "sig",
    "alg": ES256
    "kid": "sig-2021-01-15T12:09:06Z",
    "crv": "P-256",
    "x": "Tjm2thouQXSUJSrKDyMfVGe6ZQRWqCr0UgeSbNKiNi8",
    "y": "8BuGGu519a5xczbArHq1_iVJjGGBSlV5m_FGBJmiFtE"
}

Signing key rotation

Relying parties can rotate their signing keys in a self-driven manner. To do this with zero downtime, the Relying party must

• support use of JWKS URLs and be onboarded as such

• ensure their replacement signing key has a different key ID (kid) to the original key

• ensure their replacement signing key matches the other cryptographic key requirements

To do this with zero downtime, the following procedure should be followed by the Relying Party:

Time	Action
Prep	Relying party generates a new signing key pair (K2) supported for signing.
T0	Relying party adds public key K2 to its JWKS endpoint (and leaves K1 on the endpoint)
T0 - T+1 hour	Myinfo’s cache will expire, and re-retrieves the relying party’s published keys from their JWKS endpoint which now includes K2
> T+1 hour	Relying party changes their system to start signing client assertions using the new signing key K2
Clean Up	Post-validation, relying party can remove key K1 from their JWKS endpoint when they are comfortable their new signing key is working

---

JWKS for encryption

The encryption JWK will be used to encrypt ID user's requested data from the /person API.

The encryption JWK must have the following attributes:

• Must have key use of value 'enc'

• The key ID will be specified in the returned JWE header so that clients can pick the right key for decryption

• Must have key type (kty) of either EC

• Must have alg type of either ECDH-ES+A256KW

Example EC encryption key

{
    "kty": "EC",
    "use": "enc",
    "kid": "enc-2021-01-15T12:09:06Z",
    "crv": "P-256",
    "x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY",
    "y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE",
    "alg": "ECDH-ES+A128KW"
}

In the event of multiple encryption keys found. Myinfo will use the first compatible key. Relying party is expected to be able to choose the correct private key for decryption based on kid.

---

Encryption key rotation

Relying parties can rotate their encryption keys in a self-driven manner. To do this with zero downtime the Relying party must

• support use of JWKS URLs and be onboarded as such

• have the ability to decrypt tokens produced with either one of two different encryption keys based on either

  • selecting the correct decryption key by its key ID (kid)

  • trial-and-error decryption against multiple keys in a collection

• ensure their replacement key matches the other cryptographic key requirements noted above

To do this with zero downtime, the following procedure should be followed by the Relying Party:

Time	Action
Prep	Relying party generates a new encryption key pair (K2) supported for decryption. The existing key pair (K1) is still available for decryption of ID tokens
T0	Relying party removes public key K1 and adds public key K2 on its JWKS endpoint
T0 - T+1 hour	NDI’s caches will expire at any (indeterminate) time within this period, and start encrypting tokens with new encryption key K2.
T0 - T+1 hour	Relying party may be receiving tokens encrypted with either K1 or K2 keys throughout this period; and must be able to decrypt either.
> T+1 hour	Relying party can remove support for decrypting with the previous K1 key

---

Caching and key rotation policy

• Retrieval of Myinfo JWKS should be cached for at least one hour and not retrieved for every JWT validation.

• For varying reasons, keys used for signing can and will be rotated/changed with no defined schedule, and at the full discretion of Myinfo. When a key rotation happens, the new key will be available from the JWKS endpoint and will have a different kid value. The new kid value will be reflected in all the new JWTs signed by Myinfo. In such cases, cached copies of Myinfo public keys must be refreshed by re-invoking the JWKS endpoint.

• All Key pairs are recommended to be rotated every 2 years with the old key pairs removed once rotation is successful.

• Keying materials e.g shared secrets, seeds shall be destroyed immediately or as soon as possible when no longer requried.