Skip to content

Latest commit

 

History

History
342 lines (220 loc) · 7.38 KB

KEM.md

File metadata and controls

342 lines (220 loc) · 7.38 KB

Interface: KEM

Key Encapsulation Mechanism (KEM) implementation interface.

This implementation interface defines the contract for additional KEM implementations to be usable with CipherSuite. While this module provides built-in KEM implementations based on Web Cryptography, this interface is exported to allow custom KEM implementations that may not rely on Web Cryptography (e.g., using native bindings, alternative crypto libraries, or specialized hardware).

Custom KEM implementations must conform to this interface to be compatible with CipherSuite and its APIs.

Contents

Example

import * as HPKE from 'hpke'

// Using a built-in KEM
const suite = new HPKE.CipherSuite(
  HPKE.KEM_DHKEM_P256_HKDF_SHA256,
  HPKE.KDF_HKDF_SHA256,
  HPKE.AEAD_AES_128_GCM,
)

// Creating and using a custom KEM implementation
const customKEM: HPKE.KEMFactory = (): HPKE.KEM => ({
  id: 0x9999,
  type: 'KEM',
  name: 'Custom-KEM',
  Nsecret: 32,
  Nenc: 32,
  Npk: 32,
  Nsk: 32,
  async DeriveKeyPair(ikm, extractable) {
    // perform DeriveKeyPair
    let kp!: HPKE.KeyPair

    return kp
  },
  async GenerateKeyPair(extractable) {
    // perform GenerateKeyPair
    let kp!: HPKE.KeyPair

    return kp
  },
  async SerializePublicKey(key) {
    // perform SerializePublicKey
    let publicKey!: Uint8Array

    return publicKey
  },
  async DeserializePublicKey(key) {
    // perform DeserializePublicKey
    let publicKey!: HPKE.Key

    return publicKey
  },
  async SerializePrivateKey(key) {
    // perform SerializePrivateKey
    let privateKey!: Uint8Array

    return privateKey
  },
  async DeserializePrivateKey(key, extractable) {
    // perform DeserializePrivateKey
    let privateKey!: HPKE.Key

    return privateKey
  },
  async Encap(pkR) {
    // perform Encap
    let shared_secret!: Uint8Array
    let enc!: Uint8Array

    return { shared_secret, enc }
  },
  async Decap(enc, skR, pkR) {
    // perform Decap
    let shared_secret!: Uint8Array

    return shared_secret
  },
})

const customSuite = new HPKE.CipherSuite(
  customKEM,
  HPKE.KDF_HKDF_SHA256,
  HPKE.AEAD_AES_128_GCM,
)

See

HPKE Key Encapsulation Mechanisms

Methods

Decap()

Decap(enc, skR, pkR): Promise<Uint8Array>

Decapsulates a shared secret using a recipient's private key.

This is the recipient-side operation that uses the private key to extract the shared secret from the encapsulated secret.

Parameters

Parameter Type Description
enc Uint8Array The encapsulated secret of Nenc length
skR Key The recipient's private key
pkR Key ∣ undefined The recipient's public key (when user input to CipherSuite.SetupRecipient is a KeyPair)

Returns

Promise<Uint8Array>

A promise resolving to the shared secret

DeriveKeyPair()

DeriveKeyPair(ikm, extractable): Promise<KeyPair>

Derives a key pair deterministically from input keying material.

Parameters

Parameter Type Description
ikm Uint8Array Input keying material already validated to be at least Nsk bytes
extractable boolean Whether the private key should be extractable

Returns

Promise<KeyPair>

A promise resolving to a KeyPair

DeserializePrivateKey()

DeserializePrivateKey(key, extractable): Promise<Key>

Deserializes a private key from bytes.

Parameters

Parameter Type Description
key Uint8Array The serialized private key already validated to be exactly Nsk bytes
extractable boolean Whether the private key should be extractable

Returns

Promise<Key>

A promise resolving to a !Key or a Key interface-conforming object

DeserializePublicKey()

DeserializePublicKey(key): Promise<Key>

Deserializes a public key from bytes.

Parameters

Parameter Type Description
key Uint8Array The serialized public key already validated to be exactly Npk bytes

Returns

Promise<Key>

A promise resolving to a !Key or a Key interface-conforming object

Encap()

Encap(pkR): Promise<{ enc: Uint8Array; shared_secret: Uint8Array; }>

Encapsulates a shared secret to a recipient's public key.

This is the sender-side operation that generates an ephemeral key pair, performs the KEM operation, and returns both the shared secret and the encapsulated secret to send to the recipient.

Parameters

Parameter Type Description
pkR Key The recipient's public key

Returns

Promise<{ enc: Uint8Array; shared_secret: Uint8Array; }>

A promise resolving to an object containing the shared secret and encapsulated secret

GenerateKeyPair()

GenerateKeyPair(extractable): Promise<KeyPair>

Generates a random key pair.

Parameters

Parameter Type Description
extractable boolean Whether the private key should be extractable

Returns

Promise<KeyPair>

A promise resolving to a KeyPair

SerializePrivateKey()

SerializePrivateKey(key): Promise<Uint8Array>

Serializes a private key to bytes.

Parameters

Parameter Type Description
key Key The private Key to serialize

Returns

Promise<Uint8Array>

A promise resolving to the serialized private key

SerializePublicKey()

SerializePublicKey(key): Promise<Uint8Array>

Serializes a public key to bytes.

Parameters

Parameter Type Description
key Key The public Key to serialize

Returns

Promise<Uint8Array>

A promise resolving to the serialized public key

Properties

id

readonly id: number

KEM algorithm identifier

name

readonly name: string

Human-readable name of the KEM algorithm

Nenc

readonly Nenc: number

Length in bytes of an encapsulated secret produced by this KEM

Npk

readonly Npk: number

Length in bytes of a public key for this KEM

Nsecret

readonly Nsecret: number

Length in bytes of a KEM shared secret produced by this KEM

Nsk

readonly Nsk: number

Length in bytes of a private key for this KEM

type

readonly type: "KEM"

Type discriminator, always 'KEM'