Class CipherSuite

The Hybrid Public Key Encryption (HPKE) ciphersuite, which supports all of the ciphersuites defined in RFC9180.

The class consists of the @hpke/core, @hpke/chcha20poly1305, @hpke/dhkem-x25519 and @hpke/dhkem-x448 internally.

This class provides following functions:

  • [DEPRECATED] Generates a key pair for the cipher suite.
  • [DEPRECATED] Derives a key pair for the cipher suite.
  • [DEPRECATED] Imports and converts a key to a CryptoKey.
  • Creates encryption contexts both for senders and recipients.
  • Provides single-shot encryption API.

The calling of the constructor of this class is the starting point for HPKE operations for both senders and recipients.

Example: Use only ciphersuites supported internally.

import { AeadId, CipherSuite, KdfId, KemId } from "@hpke/hpke-js";

const suite = new CipherSuite({
  kem: KemId.DhkemP256HkdfSha256,
  kdf: KdfId.HkdfSha256,
  aead: AeadId.Aes128Gcm,
});

Example: Use a ciphersuite consisting of an external module.

import { AeadId, CipherSuite, KdfId } from "@hpke/hpke-js";
// Use an extension module.
import {
  HybridkemX25519Kyber768,
} from "@hpke/hybridkem-x25519-kyber768";

const suite = new CipherSuite({
  kem: new HybridkemX25519Kyber768(),
  kdf: KdfId.HkdfSha256,
  aead: AeadId.Aes128Gcm,
});

Hierarchy (View Summary)

Constructors

constructor

Properties

_api _kem

Accessors

aead kdf kem

Methods

_setup createRecipientContext createSenderContext deriveKeyPair generateKeyPair importKey open seal

Constructors

constructor

Properties

Protected_api

_api: undefined | SubtleCrypto

Protected_kem

_kem: KemInterface

Accessors

aead

  • get aead(): AeadInterface

  • Gets the AEAD context of the ciphersuite.

    Returns AeadInterface

kdf

  • get kdf(): KdfInterface

  • Gets the KDF context of the ciphersuite.

    Returns KdfInterface

kem

  • get kem(): KemInterface

  • Gets the KEM context of the ciphersuite.

    Returns KemInterface

Methods

Protected_setup

  • _setup(): Promise<void>

  • Returns Promise<void>

createRecipientContext

createSenderContext

  • createSenderContext(params: SenderContextParams): Promise<SenderContext>

  • Creates an encryption context for a sender.

    If the error occurred, throws DecapError | ValidationError.

    Parameters

    Returns Promise<SenderContext>

    A sender encryption context.

    Throws

    EncapError, ValidationError

deriveKeyPair

  • deriveKeyPair(ikm: ArrayBuffer): Promise<CryptoKeyPair>

  • Derives a key pair for the cipher suite in the manner defined in RFC9180 Section 7.1.3.

    If the error occurred, throws DeriveKeyPairError.

    Parameters

    • ikm: ArrayBuffer

      A byte string of input keying material. The maximum length is 128 bytes.

    Returns Promise<CryptoKeyPair>

    A key pair derived.

    Deprecated

    Use KemInterface.deriveKeyPair instead.

    Throws

    DeriveKeyPairError

generateKeyPair

  • generateKeyPair(): Promise<CryptoKeyPair>

  • Generates a key pair for the cipher suite.

    If the error occurred, throws NotSupportedError.

    Returns Promise<CryptoKeyPair>

    A key pair generated.

    Deprecated

    Use KemInterface.generateKeyPair instead.

    Throws

    NotSupportedError

importKey

  • importKey(
        format: "raw" | "jwk",
        key: ArrayBuffer | JsonWebKey,
        isPublic?: boolean,
    ): Promise<CryptoKey>

  • Imports a public or private key and converts to a CryptoKey.

    Since key parameters for createSenderContext or createRecipientContext are CryptoKey format, you have to use this function to convert provided keys to CryptoKey.

    Basically, this is a thin wrapper function of SubtleCrypto.importKey.

    If the error occurred, throws DeserializeError.

    Parameters

    • format: "raw" | "jwk"

      For now, 'raw' and 'jwk' are supported.

    • key: ArrayBuffer | JsonWebKey

      A byte string of a raw key or A JsonWebKey object.

    • OptionalisPublic: boolean

      The indicator whether the provided key is a public key or not, which is used only for 'raw' format.

    Returns Promise<CryptoKey>

    A public or private CryptoKey.

    Deprecated

    Use KemInterface.generateKeyPair instead.

    Throws

    DeserializeError

open

  • open(
        params: RecipientContextParams,
        ct: ArrayBuffer,
        aad?: ArrayBuffer,
    ): Promise<ArrayBuffer>

  • Decrypts a message from a sender.

    If the error occurred, throws DecapError | DeserializeError | OpenError | ValidationError.

    Parameters

    • params: RecipientContextParams

      A set of parameters for building a recipient encryption context.

    • ct: ArrayBuffer

      An encrypted text as bytes to be decrypted.

    • Optionalaad: ArrayBuffer

      Additional authenticated data as bytes fed by an application.

    Returns Promise<ArrayBuffer>

    A decrypted plain text as bytes.

    Throws

    DecapError, DeserializeError, OpenError, ValidationError

seal

  • seal(
        params: SenderContextParams,
        pt: ArrayBuffer,
        aad?: ArrayBuffer,
    ): Promise<CipherSuiteSealResponse>

  • Encrypts a message to a recipient.

    If the error occurred, throws EncapError | MessageLimitReachedError | SealError | ValidationError.

    Parameters

    • params: SenderContextParams

      A set of parameters for building a sender encryption context.

    • pt: ArrayBuffer

      A plain text as bytes to be encrypted.

    • Optionalaad: ArrayBuffer

      Additional authenticated data as bytes fed by an application.

    Returns Promise<CipherSuiteSealResponse>

    A cipher text and an encapsulated key as bytes.

    Throws

    EncapError, MessageLimitReachedError, SealError, ValidationError

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods