@sphereon/ssi-sdk-ext.key-utils 0.10.2-unstable.14

package/src/functions.ts

@@ -0,0 +1,147 @@
+import { randomBytes } from '@ethersproject/random'
+import { generateKeyPair as generateSigningKeyPair } from '@stablelib/ed25519'
+
+import { JsonWebKey } from 'did-resolver'
+import * as u8a from 'uint8arrays'
+import { ENC_KEY_ALGS, Key, KeyCurve, KeyType, JwkKeyUse, SIG_KEY_ALGS, TKeyType } from './types'
+import elliptic from 'elliptic'
+
+/**
+ * Generates a random Private Hex Key for the specified key type
+ * @param type The key type
+ * @return The private key in Hex form
+ */
+export const generatePrivateKeyHex = (type: TKeyType): string => {
+  switch (type) {
+    case Key.Ed25519: {
+      const keyPairEd25519 = generateSigningKeyPair()
+      return u8a.toString(keyPairEd25519.secretKey, 'base16')
+    }
+    // The Secp256 types use the same method to generate the key
+    case Key.Secp256r1:
+    case Key.Secp256k1: {
+      const privateBytes = randomBytes(32)
+      return u8a.toString(privateBytes, 'base16')
+    }
+    default:
+      throw Error(`not_supported: Key type ${type} not yet supported for this did:jwk implementation`)
+  }
+}
+
+/**
+ * Converts hex value to base64url
+ * @param value hex value
+ * @return Base64Url encoded value
+ */
+export const hex2base64url = (value: string) => {
+  const buffer = Buffer.from(value, 'hex')
+  const base64 = buffer.toString('base64')
+  const base64url = base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+
+  return base64url
+}
+
+/**
+ * Converts a public key in hex format to a JWK
+ * @param publicKeyHex public key in hex
+ * @param type The type of the key (Ed25519, Secp256k1/r1)
+ * @param use The optional use for the key (sig/enc)
+ * @return The JWK
+ */
+export const toJwk = (publicKeyHex: string, type: TKeyType, use?: JwkKeyUse): JsonWebKey => {
+  switch (type) {
+    case Key.Ed25519:
+      return toEd25519Jwk(publicKeyHex, use)
+    case Key.Secp256k1:
+      return toSecp256k1Jwk(publicKeyHex, use)
+    case Key.Secp256r1:
+      return toSecp256r1Jwk(publicKeyHex, use)
+    default:
+      throw new Error(`not_supported: Key type ${type} not yet supported for this did:jwk implementation`)
+  }
+}
+
+/**
+ * Determines the use param based upon the key/signature type or supplied use value.
+ *
+ * @param type The key type
+ * @param suppliedUse A supplied use. Will be used in case it is present
+ */
+export const jwkDetermineUse = (type: TKeyType, suppliedUse?: JwkKeyUse): JwkKeyUse | undefined => {
+  return suppliedUse
+    ? suppliedUse
+    : SIG_KEY_ALGS.includes(type)
+    ? JwkKeyUse.Signature
+    : ENC_KEY_ALGS.includes(type)
+    ? JwkKeyUse.Encryption
+    : undefined
+}
+
+/**
+ * Assert the key has a proper length
+ *
+ * @param keyHex Input key
+ * @param expectedKeyLength Expected key length
+ */
+const assertProperKeyLength = (keyHex: string, expectedKeyLength: number) => {
+  if (keyHex.length !== expectedKeyLength) {
+    throw Error(`Invalid key length. Needs to be a hex string with length ${expectedKeyLength} instead of ${keyHex.length}. Input: ${keyHex}`)
+  }
+}
+
+/**
+ * Generates a JWK from a Secp256k1 public key
+ * @param publicKeyHex Secp256k1 public key in hex
+ * @param use The use for the key
+ * @return The JWK
+ */
+const toSecp256k1Jwk = (publicKeyHex: string, use?: JwkKeyUse): JsonWebKey => {
+  assertProperKeyLength(publicKeyHex, 130)
+  return {
+    alg: 'ES256K',
+    ...(use !== undefined && { use }),
+    kty: KeyType.EC,
+    crv: KeyCurve.Secp256k1,
+    x: hex2base64url(publicKeyHex.substr(2, 64)),
+    y: hex2base64url(publicKeyHex.substr(66, 64)),
+  }
+}
+
+/**
+ * Generates a JWK from a Secp256r1 public key
+ * @param publicKeyHex Secp256r1 public key in hex
+ * @param use The use for the key
+ * @return The JWK
+ */
+const toSecp256r1Jwk = (publicKeyHex: string, use?: JwkKeyUse): JsonWebKey => {
+  assertProperKeyLength(publicKeyHex, 64)
+  const secp256r1 = new elliptic.ec('p256')
+  const publicKey = `03${publicKeyHex}` // We add the 'compressed' type 03 prefix
+  const key = secp256r1.keyFromPublic(publicKey, 'hex')
+  const pubPoint = key.getPublic()
+  return {
+    alg: 'ES256',
+    ...(use !== undefined && { use }),
+    kty: KeyType.EC,
+    crv: KeyCurve.P_256,
+    x: hex2base64url(pubPoint.getX().toString('hex')),
+    y: hex2base64url(pubPoint.getY().toString('hex')),
+  }
+}
+
+/**
+ * Generates a JWK from an Ed25519 public key
+ * @param publicKeyHex Ed25519 public key in hex
+ * @param use The use for the key
+ * @return The JWK
+ */
+const toEd25519Jwk = (publicKeyHex: string, use?: JwkKeyUse): JsonWebKey => {
+  assertProperKeyLength(publicKeyHex, 64)
+  return {
+    alg: 'EdDSA',
+    ...(use !== undefined && { use }),
+    kty: KeyType.OKP,
+    crv: KeyCurve.Ed25519,
+    x: hex2base64url(publicKeyHex.substr(0, 64)),
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Provides `did:jwk` {@link @veramo/did-provider-jwk#JwkDIDProvider | identifier provider }
+ * for the {@link @veramo/did-manager#DIDManager}
+ *
+ * @packageDocumentation
+ */
+export * from './functions'
+export * from './jwk-jcs'
+export * from './types'
+export * from './x509-utils'
+export * from './digest-methods'

package/src/jwk-jcs.ts

@@ -0,0 +1,177 @@
+import { TextDecoder, TextEncoder } from 'web-encoding'
+import isPlainObject from 'lodash.isplainobject'
+import type { ByteView } from 'multiformats/codecs/interface'
+import type { JsonWebKey } from 'did-resolver'
+
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+/**
+ * Checks if the value is a non-empty string.
+ *
+ * @param value - The value to check.
+ * @param description - Description of the value to check.
+ */
+function check(value: unknown, description: string) {
+  if (typeof value !== 'string' || !value) {
+    throw new Error(`${description} missing or invalid`)
+  }
+}
+
+/**
+ * Checks if the value is a valid JSON object.
+ *
+ * @param value - The value to check.
+ */
+function validatePlainObject(value: unknown) {
+  if (!isPlainObject(value)) {
+    throw new Error('JWK must be an object')
+  }
+}
+
+/**
+ * Checks if the JWK is valid. It must contain all the required members.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-6
+ * @see https://www.rfc-editor.org/rfc/rfc8037#section-2
+ *
+ * @param jwk - The JWK to check.
+ */
+function validateJwk(jwk: any) {
+  validatePlainObject(jwk)
+  // Check JWK required members based on the key type
+  switch (jwk.kty) {
+    /**
+     * @see https://www.rfc-editor.org/rfc/rfc7518#section-6.2.1
+     */
+    case 'EC':
+      check(jwk.crv, '"crv" (Curve) Parameter')
+      check(jwk.x, '"x" (X Coordinate) Parameter')
+      check(jwk.y, '"y" (Y Coordinate) Parameter')
+      break
+    /**
+     * @see https://www.rfc-editor.org/rfc/rfc8037#section-2
+     */
+    case 'OKP':
+      check(jwk.crv, '"crv" (Subtype of Key Pair) Parameter')
+      check(jwk.x, '"x" (Public Key) Parameter')
+      break
+    /**
+     * @see https://www.rfc-editor.org/rfc/rfc7518#section-6.3.1
+     */
+    case 'RSA':
+      check(jwk.e, '"e" (Exponent) Parameter')
+      check(jwk.n, '"n" (Modulus) Parameter')
+      break
+    default:
+      throw new Error('"kty" (Key Type) Parameter missing or unsupported')
+  }
+}
+
+/**
+ * Extracts the required members of the JWK and canonicalizes it.
+ *
+ * @param jwk - The JWK to canonicalize.
+ * @returns The JWK with only the required members, ordered lexicographically.
+ */
+function minimalJwk(jwk: any) {
+  // "default" case is not needed
+  // eslint-disable-next-line default-case
+  switch (jwk.kty) {
+    case 'EC':
+      return { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }
+    case 'OKP':
+      return { crv: jwk.crv, kty: jwk.kty, x: jwk.x }
+    case 'RSA':
+      return { e: jwk.e, kty: jwk.kty, n: jwk.n }
+  }
+  throw Error(`Unsupported key type (kty) provided: ${jwk.kty}`)
+}
+
+/**
+ * Encodes a JWK into a Uint8Array. Only the required JWK members are encoded.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-6
+ * @see https://www.rfc-editor.org/rfc/rfc8037#section-2
+ * @see https://github.com/panva/jose/blob/3b8aa47b92d07a711bf5c3125276cc9a011794a4/src/jwk/thumbprint.ts#L37
+ *
+ * @param jwk - JSON Web Key.
+ * @returns Uint8Array-encoded JWK.
+ */
+export function jwkJcsEncode(jwk: unknown): Uint8Array {
+  validateJwk(jwk)
+  const strippedJwk = minimalJwk(jwk)
+  return textEncoder.encode(jcsCanonicalize(strippedJwk))
+}
+
+/**
+ * Decodes an array of bytes into a JWK. Throws an error if the JWK is not valid.
+ *
+ * @param bytes - The array of bytes to decode.
+ * @returns The corresponding JSON Web Key.
+ */
+export function jwkJcsDecode(bytes: ByteView<JsonWebKey>): JsonWebKey {
+  const jwk = JSON.parse(textDecoder.decode(bytes))
+  validateJwk(jwk)
+  if (JSON.stringify(jwk) !== jcsCanonicalize(minimalJwk(jwk))) {
+    throw new Error('The JWK embedded in the DID is not correctly formatted')
+  }
+  return jwk
+}
+
+// From: https://github.com/cyberphone/json-canonicalization
+export function jcsCanonicalize(object: any) {
+  let buffer = ''
+  serialize(object)
+  return buffer
+
+  function serialize(object: any) {
+    if (object === null || typeof object !== 'object' || object.toJSON != null) {
+      /////////////////////////////////////////////////
+      // Primitive type or toJSON - Use ES6/JSON     //
+      /////////////////////////////////////////////////
+      buffer += JSON.stringify(object)
+    } else if (Array.isArray(object)) {
+      /////////////////////////////////////////////////
+      // Array - Maintain element order              //
+      /////////////////////////////////////////////////
+      buffer += '['
+      let next = false
+      object.forEach((element) => {
+        if (next) {
+          buffer += ','
+        }
+        next = true
+        /////////////////////////////////////////
+        // Array element - Recursive expansion //
+        /////////////////////////////////////////
+        serialize(element)
+      })
+      buffer += ']'
+    } else {
+      /////////////////////////////////////////////////
+      // Object - Sort properties before serializing //
+      /////////////////////////////////////////////////
+      buffer += '{'
+      let next = false
+      Object.keys(object)
+        .sort()
+        .forEach((property) => {
+          if (next) {
+            buffer += ','
+          }
+          next = true
+          ///////////////////////////////////////////////
+          // Property names are strings - Use ES6/JSON //
+          ///////////////////////////////////////////////
+          buffer += JSON.stringify(property)
+          buffer += ':'
+          //////////////////////////////////////////
+          // Property value - Recursive expansion //
+          //////////////////////////////////////////
+          serialize(object[property])
+        })
+      buffer += '}'
+    }
+  }
+}

package/src/types/elliptic.d.ts

@@ -0,0 +1 @@
+declare module 'elliptic'

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './key-util-types'

package/src/types/key-util-types.ts

@@ -0,0 +1,44 @@
+export const JWK_JCS_PUB_NAME = 'jwk_jcs-pub'
+export const JWK_JCS_PUB_PREFIX = 0xeb51
+
+export type TKeyType = 'Ed25519' | 'Secp256k1' | 'Secp256r1' | 'X25519' | 'Bls12381G1' | 'Bls12381G2' | 'RSA'
+
+export enum Key {
+  Ed25519 = 'Ed25519',
+  Secp256k1 = 'Secp256k1',
+  Secp256r1 = 'Secp256r1',
+}
+
+export enum JwkKeyUse {
+  Encryption = 'enc',
+  Signature = 'sig',
+}
+
+export enum KeyCurve {
+  Secp256k1 = 'secp256k1',
+  P_256 = 'P-256',
+  Ed25519 = 'Ed25519',
+}
+
+export enum KeyType {
+  EC = 'EC',
+  OKP = 'OKP',
+}
+
+export const SIG_KEY_ALGS = ['ES256', 'ES384', 'ES512', 'EdDSA', 'ES256K', 'Ed25519', 'Secp256k1', 'Secp256r1', 'Bls12381G1', 'Bls12381G2']
+export const ENC_KEY_ALGS = ['X25519', 'ECDH_ES_A256KW', 'RSA_OAEP_256']
+
+export interface JWK extends JsonWebKey {
+  x5c?: string
+  x5u?: string
+}
+
+export type KeyVisibility = 'public' | 'private'
+
+export interface X509Opts {
+  cn?: string // The certificate Common Name. Will be used as the KID for the private key. Uses alias if not provided.
+  privateKeyPEM?: string // Optional as you also need to provide it in hex format, but advisable to use it
+  certificatePEM?: string // Optional, as long as the certificate then is part of the certificateChainPEM
+  certificateChainURL?: string // Certificate chain URL. If used this is where the certificateChainPEM will be hosted/found.
+  certificateChainPEM?: string // Base64 (not url!) encoded DER certificate chain. Please provide even if certificateChainURL is used!
+}

package/src/x509-utils.ts

@@ -0,0 +1,145 @@
+import * as u8a from 'uint8arrays'
+// @ts-ignore
+import keyto from '@trust/keyto'
+import { JWK, KeyVisibility } from './types'
+
+// Based on (MIT licensed):
+// https://github.com/hildjj/node-posh/blob/master/lib/index.js
+export function pemCertChainTox5c(cert: string, maxDepth?: number): string[] {
+  if (!maxDepth) {
+    maxDepth = 0
+  }
+  /*
+   * Convert a PEM-encoded certificate to the version used in the x5c element
+   * of a [JSON Web Key](http://tools.ietf.org/html/draft-ietf-jose-json-web-key).
+   *
+   * `cert` PEM-encoded certificate chain
+   * `maxdepth` The maximum number of certificates to use from the chain.
+   */
+
+  const intermediate = cert
+    .replace(/-----[^\n]+\n?/gm, ',')
+    .replace(/\n/g, '')
+    .replace(/\r/g, '')
+  let x5c = intermediate.split(',').filter(function (c) {
+    return c.length > 0
+  })
+  if (maxDepth > 0) {
+    x5c = x5c.splice(0, maxDepth)
+  }
+  return x5c
+}
+
+export function x5cToPemCertChain(x5c: string[], maxDepth?: number): string {
+  if (!maxDepth) {
+    maxDepth = 0
+  }
+  const length = maxDepth === 0 ? x5c.length : Math.min(maxDepth, x5c.length)
+  let pem = ''
+  for (let i = 0; i < length; i++) {
+    pem += base64ToPEM(x5c[i], 'CERTIFICATE')
+  }
+  return pem
+}
+
+export const toKeyObject = (PEM: string, visibility: KeyVisibility = 'public') => {
+  const jwk = PEMToJwk(PEM, visibility)
+  const keyVisibility: KeyVisibility = jwk.d ? 'private' : 'public'
+  const keyHex = keyVisibility === 'private' ? privateKeyHexFromPEM(PEM) : publicKeyHexFromPEM(PEM)
+
+  return {
+    pem: hexToPEM(keyHex, visibility),
+    jwk,
+    keyHex,
+    keyType: keyVisibility,
+  }
+}
+
+export const jwkToPEM = (jwk: JWK, visibility: KeyVisibility = 'public'): string => {
+  return keyto.from(jwk, 'jwk').toString('pem', visibility === 'public' ? 'public_pkcs8' : 'private_pkcs8')
+}
+
+export const PEMToJwk = (pem: string, visibility: KeyVisibility = 'public'): JWK => {
+  return keyto.from(pem, 'pem').toJwk(visibility)
+}
+export const privateKeyHexFromPEM = (PEM: string) => {
+  return PEMToHex(PEM)
+}
+
+export const hexKeyFromPEMBasedJwk = (jwk: JWK, visibility: KeyVisibility = 'public'): string => {
+  if (visibility === 'private') {
+    return privateKeyHexFromPEM(jwkToPEM(jwk, 'private'))
+  } else {
+    return publicKeyHexFromPEM(jwkToPEM(jwk, 'public'))
+  }
+}
+
+export const publicKeyHexFromPEM = (PEM: string) => {
+  const hex = PEMToHex(PEM)
+  if (PEM.includes('CERTIFICATE')) {
+    throw Error('Cannot directly deduce public Key from PEM Certificate yet')
+  } else if (!PEM.includes('PRIVATE')) {
+    return hex
+  }
+  const publicJwk = PEMToJwk(PEM, 'public')
+  const publicPEM = jwkToPEM(publicJwk, 'public')
+  return PEMToHex(publicPEM)
+}
+
+export const PEMToHex = (PEM: string, headerKey?: string): string => {
+  if (PEM.indexOf('-----BEGIN ') == -1) {
+    throw Error(`PEM header not found: ${headerKey}`)
+  }
+
+  let strippedPem: string
+  if (headerKey) {
+    strippedPem = PEM.replace(new RegExp('^[^]*-----BEGIN ' + headerKey + '-----'), '')
+    strippedPem = strippedPem.replace(new RegExp('-----END ' + headerKey + '-----[^]*$'), '')
+  } else {
+    strippedPem = PEM.replace(/^[^]*-----BEGIN [^-]+-----/, '')
+    strippedPem = strippedPem.replace(/-----END [^-]+-----[^]*$/, '')
+  }
+  return base64ToHex(strippedPem, 'base64pad')
+}
+
+/**
+ * Converts a base64 encoded string to hex string, removing any non-base64 characters, including newlines
+ * @param input The input in base64, with optional newlines
+ * @param inputEncoding
+ */
+export const base64ToHex = (input: string, inputEncoding?: 'base64pad' | 'base64urlpad') => {
+  const base64NoNewlines = input.replace(/[^0-9A-Za-z\/+=]*/g, '')
+  return u8a.toString(u8a.fromString(base64NoNewlines, inputEncoding ? inputEncoding : 'base64pad'), 'base16')
+}
+
+const hexToBase64 = (input: number | object | string, targetEncoding?: 'base64pad' | 'base64urlpad'): string => {
+  let hex = typeof input === 'string' ? input : input.toString(16)
+  if (hex.length % 2 === 1) {
+    hex = `0${hex}`
+  }
+  return u8a.toString(u8a.fromString(hex, 'base16'), targetEncoding ? targetEncoding : 'base64pad')
+}
+
+export const hexToPEM = (hex: string, type: KeyVisibility): string => {
+  const base64 = hexToBase64(hex, 'base64pad')
+  const headerKey = type === 'private' ? 'RSA PRIVATE KEY' : 'PUBLIC KEY'
+  if (type === 'private') {
+    const pem = base64ToPEM(base64, headerKey)
+    try {
+      PEMToJwk(pem) // We only use it to test the private key
+      return pem
+    } catch (error) {
+      return base64ToPEM(base64, 'PRIVATE KEY')
+    }
+  }
+  return base64ToPEM(base64, headerKey)
+}
+
+export function base64ToPEM(cert: string, headerKey?: 'PUBLIC KEY' | 'RSA PRIVATE KEY' | 'PRIVATE KEY' | 'CERTIFICATE'): string {
+  const key = headerKey ?? 'CERTIFICATE'
+  const matches = cert.match(/.{1,64}/g)
+  if (!matches) {
+    throw Error('Invalid cert input value supplied')
+  }
+  return `-----BEGIN ${key}-----\n${matches.join('\n')}\n-----END ${key}-----\n`
+}