ecdsa-multikey v1.0.0

README.md

@@ -50,16 +50,16 @@ npm install
 
 To generate a new public/secret key pair:
 
-* `{string} [id]` Optional id for the generated key.
-* `{string} [controller]` Optional controller URI or DID to initialize the
-  generated key. (This will also init the key id.)
-* `{string} [seed]` Optional deterministic seed value from which to generate the
-  key.
+* `{string} [curve]` \[Required\] ECDSA curve used to generate the key:
+  \['P-256', 'P-384', 'P-521'\].
+* `{string} [id]` \[Optional\] ID for the generated key.
+* `{string} [controller]` \[Optional\] Controller URI or DID to initialize the
+  generated key. (This will be used to generate `id` if it is not explicitly defined.)
 
 ```js
 import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
 
-const edKeyPair = await EcdsaMultikey.generate();
+const keyPair = await EcdsaMultikey.generate({curve: 'P-384'});
 ```
 
 ### Importing a key pair from storage
@@ -82,9 +82,9 @@ await keyPair.export({publicKey: true});
 // ->
 {
   type: 'Multikey',
-  id: 'did:example:1234#z6Mkon3Necd6NkkyfoGoHxid2znGc59LU3K7mubaRcFbLfLX',
+  id: 'did:example:1234#zynkWQ2LUf58H4VwLGjscwb9KJwGUmqBFXdJKnCXxDMciFXioY7Hq7MvEdVfsBiQSVa9k9',
   controller: 'did:example:1234',
-  publicKeyMultibase: 'z6Mkon3Necd6NkkyfoGoHxid2znGc59LU3K7mubaRcFbLfLX'
+  publicKeyMultibase: 'zynkWQ2LUf58H4VwLGjscwb9KJwGUmqBFXdJKnCXxDMciFXioY7Hq7MvEdVfsBiQSVa9k9'
 }
 ```
 
@@ -98,10 +98,10 @@ await keyPair.export({publicKey: true, secretKey: true});
 // ->
 {
   type: 'Multikey',
-  id: 'did:example:1234#z6Mkon3Necd6NkkyfoGoHxid2znGc59LU3K7mubaRcFbLfLX',
+  id: 'did:example:1234#zynkWQ2LUf58H4VwLGjscwb9KJwGUmqBFXdJKnCXxDMciFXioY7Hq7MvEdVfsBiQSVa9k9',
   controller: 'did:example:1234',
-  publicKeyMultibase: 'z6Mkon3Necd6NkkyfoGoHxid2znGc59LU3K7mubaRcFbLfLX',
-  secretKeyMultibase: 'zruzf4Y29hDp7vLoV3NWzuymGMTtJcQfttAWzESod4wV2fbPvEp4XtzGp2VWwQSQAXMxDyqrnVurYg2sBiqiu1FHDDM'
+  publicKeyMultibase: 'zynkWQ2LUf58H4VwLGjscwb9KJwGUmqBFXdJKnCXxDMciFXioY7Hq7MvEdVfsBiQSVa9k9',
+  secretKeyMultibase: 'zEbCcd62anxNxioGCdP818UobJn1oEmgL5PHUvQ5AvdyVeLJxeJ4Kr73RqqvG5DN7Zq48'
 }
 ```
 
@@ -111,14 +111,14 @@ In order to perform a cryptographic signature, you need to create a `sign`
 function, and then invoke it.
 
 ```js
-const keyPair = EcdsaMultikey.generate();
+const keyPair = EcdsaMultikey.generate({curve: 'P-256'});
 
 const {sign} = keyPair.signer();
 
 // data is a Uint8Array of bytes
 const data = (new TextEncoder()).encode('test data goes here');
 // Signing also outputs a Uint8Array, which you can serialize to text etc.
-const signatureValueBytes = await sign({data});
+const signature = await sign({data});
 ```
 
 ### Creating a verifier function
@@ -127,7 +127,7 @@ In order to verify a cryptographic signature, you need to create a `verify`
 function, and then invoke it (passing it the data to verify, and the signature).
 
 ```js
-const keyPair = EcdsaMultikey.generate();
+const keyPair = EcdsaMultikey.generate({curve: 'P-521'});
 
 const {verify} = keyPair.verifier();
 
@@ -151,4 +151,4 @@ Digital Bazaar: [email protected]
 
 ## License
 
-[New BSD License (3-clause)](LICENSE) © 2020 Digital Bazaar
+[New BSD License (3-clause)](LICENSE) © 2023 Digital Bazaar

lib/constants.js

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
+ */
+
+// Name of algorithm
+export const ALGORITHM = 'ECDSA';
+// Determines whether key pair is extractable
+export const EXTRACTABLE = true;
+// ECDSA curve P-256 type
+export const ECDSA_2019_SECP_256_KEY_TYPE = 'EcdsaSecp256r1VerificationKey2019';
+// ECDSA curve P-384 type
+export const ECDSA_2019_SECP_384_KEY_TYPE = 'EcdsaSecp384r1VerificationKey2019';
+// ECDSA curve P-521 type
+export const ECDSA_2019_SECP_521_KEY_TYPE = 'EcdsaSecp521r1VerificationKey2019';
+// ECDSA 2019 suite context v1 URL
+export const ECDSA_2019_SUITE_CONTEXT_V1_URL = 'https://w3id.org/security/suites/ecdsa-2019/v1';
+// Multikey context v1 URL
+export const MULTIKEY_CONTEXT_V1_URL = 'https://w3id.org/security/multikey/v1';
+export const MULTIBASE_BASE58_HEADER = 'z';
+
+// Multicodec ECDSA public key header byte 1
+export const MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1 = 0x12;
+// Multicodec p256-pub header byte 2
+export const MULTICODEC_P256_PUBLIC_KEY_HEADER_BYTE_2 = 0x00;
+// Multicodec p384-pub header byte 2
+export const MULTICODEC_P384_PUBLIC_KEY_HEADER_BYTE_2 = 0x01;
+// Multicodec p521-pub header byte 2
+export const MULTICODEC_P521_PUBLIC_KEY_HEADER_BYTE_2 = 0x02;
+
+// Multicodec ECDSA secret key header byte 1
+export const MULTICODEC_ECDSA_SECRET_KEY_HEADER_BYTE_1 = 0x13;
+// Multicodec p256-priv header byte 2
+export const MULTICODEC_P256_SECRET_KEY_HEADER_BYTE_2 = 0x03;
+// Multicodec p384-priv header byte 2
+export const MULTICODEC_P384_SECRET_KEY_HEADER_BYTE_2 = 0x04;
+// Multicodec p521-priv header byte 2
+export const MULTICODEC_P521_SECRET_KEY_HEADER_BYTE_2 = 0x05;

lib/ecdsa-browser.js

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
+ */
+// eslint-disable-next-line no-undef
+export const webcrypto = globalThis.crypto.webcrypto ?? globalThis.crypto;
+// eslint-disable-next-line no-undef
+export const CryptoKey = globalThis.CryptoKey ?? webcrypto.CryptoKey;

lib/ecdsa.js

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
+ */
+import {webcrypto} from 'node:crypto';
+const {CryptoKey} = webcrypto;
+export {CryptoKey, webcrypto};
+
+export const EcdsaCurve = {
+  P256: 'P-256',
+  P384: 'P-384',
+  P521: 'P-521'
+};
+
+export const EcdsaHash = {
+  Sha256: 'SHA-256',
+  Sha384: 'SHA-384',
+  Sha512: 'SHA-512'
+};

lib/factory.js

@@ -0,0 +1,48 @@
+/*!
+ * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
+ */
+import {ALGORITHM} from './constants.js';
+import {webcrypto, EcdsaCurve, EcdsaHash} from './ecdsa.js';
+
+export function createSigner({id, secretKey}) {
+  if(!secretKey) {
+    throw new Error('A secret key is not available for signing.');
+  }
+  const {namedCurve: curve} = secretKey.algorithm;
+  const algorithm = {name: ALGORITHM, hash: {name: _getEcdsaHash({curve})}};
+  return {
+    algorithm: ALGORITHM,
+    id,
+    async sign({data} = {}) {
+      return webcrypto.subtle.sign(algorithm, secretKey, data);
+    }
+  };
+}
+
+export function createVerifier({id, publicKey}) {
+  if(!publicKey) {
+    throw new Error('A public key is not available for verifying.');
+  }
+  const {namedCurve: curve} = publicKey.algorithm;
+  const algorithm = {name: 'ECDSA', hash: {name: _getEcdsaHash({curve})}};
+  return {
+    algorithm: ALGORITHM,
+    id,
+    async verify({data, signature} = {}) {
+      return webcrypto.subtle.verify(algorithm, publicKey, signature, data);
+    }
+  };
+}
+
+function _getEcdsaHash({curve}) {
+  if(curve === EcdsaCurve.P256) {
+    return EcdsaHash.Sha256;
+  }
+  if(curve === EcdsaCurve.P384) {
+    return EcdsaHash.Sha384;
+  }
+  if(curve === EcdsaCurve.P521) {
+    return EcdsaHash.Sha512;
+  }
+  throw Error(`Unsupported curve "${curve}".`);
+}

lib/helpers.js

@@ -0,0 +1,106 @@
+/*!
+ * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as base58 from 'base58-universal';
+import {
+  MULTIBASE_BASE58_HEADER,
+  MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1,
+  MULTICODEC_ECDSA_SECRET_KEY_HEADER_BYTE_1,
+  MULTICODEC_P256_PUBLIC_KEY_HEADER_BYTE_2,
+  MULTICODEC_P256_SECRET_KEY_HEADER_BYTE_2,
+  MULTICODEC_P384_PUBLIC_KEY_HEADER_BYTE_2,
+  MULTICODEC_P384_SECRET_KEY_HEADER_BYTE_2,
+  MULTICODEC_P521_PUBLIC_KEY_HEADER_BYTE_2,
+  MULTICODEC_P521_SECRET_KEY_HEADER_BYTE_2
+} from './constants.js';
+import {EcdsaCurve} from './ecdsa.js';
+
+export function getNamedCurve({publicMultikey}) {
+  if(publicMultikey[0] === MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1) {
+    if(publicMultikey[1] === MULTICODEC_P256_PUBLIC_KEY_HEADER_BYTE_2) {
+      return EcdsaCurve.P256;
+    }
+    if(publicMultikey[1] === MULTICODEC_P384_PUBLIC_KEY_HEADER_BYTE_2) {
+      return EcdsaCurve.P384;
+    }
+    if(publicMultikey[1] === MULTICODEC_P521_PUBLIC_KEY_HEADER_BYTE_2) {
+      return EcdsaCurve.P521;
+    }
+  }
+
+  // FIXME; also support P-256K/secp256k1
+  const err = new Error('Unsupported multikey header.');
+  err.name = 'UnsupportedError';
+  throw err;
+}
+
+export function getSecretKeySize({keyPair}) {
+  const key = keyPair.secretKey || keyPair.publicKey;
+  const {namedCurve: curve} = key.algorithm;
+  if(curve === EcdsaCurve.P256) {
+    return 32;
+  }
+  if(curve === EcdsaCurve.P384) {
+    return 48;
+  }
+  if(curve === EcdsaCurve.P521) {
+    return 66;
+  }
+  throw new Error(`Unsupported curve "${curve}".`);
+}
+
+export function setSecretKeyHeader({keyPair, buffer}) {
+  const key = keyPair.secretKey || keyPair.publicKey;
+  const {namedCurve: curve} = key.algorithm;
+  // FIXME: these must be added to the multicodec table
+  if(curve === EcdsaCurve.P256) {
+    buffer[0] = MULTICODEC_ECDSA_SECRET_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P256_SECRET_KEY_HEADER_BYTE_2;
+  } else if(curve === EcdsaCurve.P384) {
+    buffer[0] = MULTICODEC_ECDSA_SECRET_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P384_SECRET_KEY_HEADER_BYTE_2;
+  } else if(curve === EcdsaCurve.P521) {
+    buffer[0] = MULTICODEC_ECDSA_SECRET_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P521_SECRET_KEY_HEADER_BYTE_2;
+  } else {
+    throw new Error(`Unsupported curve "${curve}".`);
+  }
+}
+
+export function setPublicKeyHeader({keyPair, buffer}) {
+  const {namedCurve: curve} = keyPair.publicKey.algorithm;
+  if(curve === EcdsaCurve.P256) {
+    buffer[0] = MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P256_PUBLIC_KEY_HEADER_BYTE_2;
+  } else if(curve === EcdsaCurve.P384) {
+    buffer[0] = MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P384_PUBLIC_KEY_HEADER_BYTE_2;
+  } else if(curve === EcdsaCurve.P521) {
+    buffer[0] = MULTICODEC_ECDSA_PUBLIC_KEY_HEADER_BYTE_1;
+    buffer[1] = MULTICODEC_P521_PUBLIC_KEY_HEADER_BYTE_2;
+  } else {
+    throw new Error(`Unsupported curve "${curve}".`);
+  }
+}
+
+export function mbEncodeKeyPair({keyPair}) {
+  const publicKeyMultibase =
+    _encodeMbKey(MULTICODEC_PUB_HEADER, keyPair.publicKey);
+  const secretKeyMultibase =
+    _encodeMbKey(MULTICODEC_PRIV_HEADER, keyPair.secretKey);
+
+  return {
+    publicKeyMultibase,
+    secretKeyMultibase
+  };
+}
+
+// encode a multibase base58 multicodec key
+function _encodeMbKey(header, key) {
+  const mbKey = new Uint8Array(header.length + key.length);
+
+  mbKey.set(header);
+  mbKey.set(key, header.length);
+
+  return MULTIBASE_BASE58_HEADER + base58.encode(mbKey);
+}

lib/index.js

@@ -1,18 +1,83 @@
 /*!
  * Copyright (c) 2023 Digital Bazaar, Inc. All rights reserved.
  */
-import {MULTIKEY_CONTEXT_V1_URL} from './constants.js';
-
-export async function generate({id, controller} = {}) {
+import {EXTRACTABLE, MULTIKEY_CONTEXT_V1_URL} from './constants.js';
+import {CryptoKey, EcdsaCurve, webcrypto} from './ecdsa.js';
+import {createSigner, createVerifier} from './factory.js';
+import {exportKeyPair, importKeyPair} from './serialize.js';
+import {toMultikey} from './translators.js';
 
+// FIXME: support `P-256K` via `@noble/secp256k1`
+// Generate ECDSA key pair
+export async function generate({id, controller, curve} = {}) {
+  if(!curve) {
+    throw new TypeError('"curve" must be one of the following values: ' +
+      `${Object.values(EcdsaCurve).map((v) => `'${v}'`).join(', ')}.`);
+  }
+  const algorithm = {name: 'ECDSA', namedCurve: curve};
+  const keyPair = await webcrypto.subtle.generateKey(
+    algorithm, EXTRACTABLE, ['sign', 'verify']
+  );
+  keyPair.secretKey = keyPair.privateKey;
+  delete keyPair.privateKey;
+  const keyPairInterface = await _createKeyPairInterface({keyPair});
+  const exportedKeyPair = await keyPairInterface.export({ publicKey: true });
+  const {publicKeyMultibase} = exportedKeyPair;
+  if(controller && !id) {
+    id = `${controller}#${publicKeyMultibase}`;
+  }
+  keyPairInterface.id = id;
+  keyPairInterface.controller = controller;
+  return keyPairInterface;
 }
 
-// import key pair from JSON Multikey
+// Import ECDSA key pair from JSON Multikey
 export async function from(key) {
+  if(key.type && key.type !== 'Multikey') {
+    key = await toMultikey({keyPair: key});
+    return _createKeyPairInterface({keyPair: key});
+  }
+  if(!key.type) {
+    key.type = 'Multikey';
+  }
+  if(!key['@context']) {
+    key['@context'] = MULTIKEY_CONTEXT_V1_URL;
+  }
+  if(key.controller && !key.id) {
+    key.id = `${key.controller}#${key.publicKeyMultibase}`;
+  }
 
+  _assertMultikey(key);
+  return _createKeyPairInterface({keyPair: key});
 }
 
 async function _createKeyPairInterface({keyPair}) {
+  if(!(keyPair?.publicKey instanceof CryptoKey)) {
+    keyPair = await importKeyPair(keyPair);
+  }
+  const exportFn = async ({
+    publicKey = true, secretKey = false, includeContext = true
+  } = {}) => {
+    return exportKeyPair({keyPair, publicKey, secretKey, includeContext});
+  };
+  const {publicKeyMultibase, secretKeyMultibase} = await exportFn({
+    publicKey: true, secretKey: true, includeContext: true
+  });
+  keyPair = {
+    ...keyPair,
+    publicKeyMultibase,
+    secretKeyMultibase,
+    export: exportFn,
+    signer() {
+      const {id, secretKey} = keyPair;
+      return createSigner({id, secretKey});
+    },
+    verifier() {
+      const {id, publicKey} = keyPair;
+      return createVerifier({id, publicKey});
+    }
+  };
+
   return keyPair;
 }
 
@@ -25,6 +90,7 @@ function _assertMultikey(key) {
   }
   if(key['@context'] !== MULTIKEY_CONTEXT_V1_URL) {
     throw new Error('"key" must be a Multikey with context ' +
-      `"${MULTIKEY_CONTEXT_V1_URL}".`);
+      `"${MULTIKEY_CONTEXT_V1_URL}".`
+    );
   }
 }