doc: COSE -> JWK Mappings

Start by reviewing the COSE/JWK mapping tables and the linked IANA, RFC, Node WebCrypto, and caniuse references. Determine where this repository's documentation presents passkey key types, then document the agreed modern and legacy mappings with browser and Node support. Done means the mappings and compatibility notes are complete and internally consistent.

Note:

• Browser WebCrypto only supports P-256
  • https://caniuse.com/mdn-api_subtlecrypto_sign_ed25519
• Node node:crypto and WebCrypto also supports Ed25519 and secp256k1 (as just SHA256) - whatever is supported by openssl v3
  • https://nodejs.org/docs/latest/api/webcrypto.html#algorithm-matrix
  • https://nodejs.org/docs/latest/api/crypto.html#cryptocreatesignalgorithm-options
  • openssl list -digest-algorithms (TL;DR: always use SHA256)
  • openssl ecparam -list_curves (secp256k1, prime256v1: X9.62/SECG, a.k.a secp256r1 a.k.a. P-256)
  • openssl list -public-key-algorithms (1.3.101.112, ED25519, 1.2.840.10045.2.1, EC, id-ecPublicKey)

Node WebCrypto Key Gen Example

'use strict';

let Fs = require('node:fs/promises');

async function generateKeyPair(algo) {
  let keyPair = await crypto.subtle.generateKey(algo, true, ['sign', 'verify']);

  let privateKeyAb = await crypto.subtle.exportKey('pkcs8', keyPair.privateKey);
  let privateKeyDER = new Uint8Array(privateKeyAb);
  let privateKeyPath = `./key.${algo.name}.der`.toLowerCase();
  await Fs.writeFile(privateKeyPath, privateKeyDER);

  let publicKeyAb = await crypto.subtle.exportKey('spki', keyPair.publicKey);
  let publicKeyDER = new Uint8Array(publicKeyAb);
  let publicKeyPath = `./pub.${algo.name}.der`.toLowerCase();
  await Fs.writeFile(publicKeyPath, publicKeyDER);

  console.info(`Key pair generated and saved as ${privateKeyPath} and ${publicKeyPath}`);
}

async function main() {
  await generateKeyPair({ name: 'Ed25519' });
  await generateKeyPair({ name: 'ECDSA', namedCurve: 'P-256' });
}

main().catch(function (err) {
  console.error(err.stack);
  process.exit(1);
});

Adapted From https://www.iana.org/assignments/cose/cose.xhtml

OKP (EdDSA / ed25519)

EC (ECDSA, secp256k1)

Modern Keypairs

These are the key types that are still relevant in 2024+ and will be relevant for the next decade:

let coseMap = {
  "keys": {
    "kty": 1,
    "alg": 3
  },
  "okp": {
    "crv": "-1",
    "x": "-2",
    "d": "-4"
  },
  "ec": {
    "crv": "-1",
    "x": "-2",
    "y": "-3",
    "d": "-4"
  },
  "kty": {
    "1": "OKP",
    "2": "EC"
  },
  "alg": {
    "-47": "ES256K",
    "-8": "EdDSA",
    "-7": "ES256"
  },
  "crv": {
    "1": "P-256",
    "6": "Ed25519",
    "8": "secp256k1"
  }
};

Legacy Keypairs

let coseMap = {
  "keys": {
    "kty": 1,
    "alg": 3
  },
  "okp": {
    "crv": "-1",
    "x": "-2",
    "d": "-4"
  },
  "ec": {
    "crv": "-1",
    "x": "-2",
    "y": "-3",
    "d": "-4"
  },
  "rsa": {
    "n": "-1",
    "e": "-2",
    "d": "-3",
    "p": "-4",
    "q": "-5",
    "dp": "-6",
    "dq": "-7",
    "qi": "-8"
  },
  "kty": {
    "1": "OKP",
    "2": "EC",
    "3": "RSA"
  },
  "alg": {
    "-259": "RS512",
    "-258": "RS384",
    "-257": "RS256",
    "-39": "PS512",
    "-38": "PS384",
    "-37": "PS256",
    "-36": "ES512",
    "-35": "ES384",
    "-47": "ES256K",
    "-8": "EdDSA",
    "-7": "ES256"
  },
  "crv": {
    "1": "P-256",
    "2": "P-384",
    "3": "P-521",
    "6": "Ed25519",
    "8": "secp256k1"
  }
};

RSA (legacy)

RSA's not bad or broken, it's just not efficient.