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.
- createSenderContext
- createRecipientContext
Provides single-shot encryption API.
- seal
- open

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

CipherSuite
- CipherSuite

Index

Constructors

constructor

new CipherSuite(params: CipherSuiteParams): CipherSuite
Parameters
- params: CipherSuiteParams
  A set of parameters for building a cipher suite.
Returns CipherSuite
Throws
InvalidParamError
Overrides CipherSuiteNative.constructor
- Defined in src/cipherSuite.ts:81

Properties

`Protected`_api

_api: SubtleCrypto = undefined

`Protected`_kem

_kem: KemInterface

Accessors

aead

get aead(): AeadInterface
Gets the AEAD context of the ciphersuite.

Returns AeadInterface
Inherited from CipherSuiteNative.aead
- Defined in ../core/src/cipherSuiteNative.ts:185

kdf

get kdf(): KdfInterface
Gets the KDF context of the ciphersuite.

Returns KdfInterface
Inherited from CipherSuiteNative.kdf
- Defined in ../core/src/cipherSuiteNative.ts:178

kem

get kem(): KemInterface
Gets the KEM context of the ciphersuite.

Returns KemInterface
Inherited from CipherSuiteNative.kem
- Defined in ../core/src/cipherSuiteNative.ts:171

Methods

`Protected`_setup

_setup(): Promise<void>
Returns Promise<void>
Inherited from CipherSuiteNative._setup
- Defined in ../common/src/algorithm.ts:23

createRecipientContext

createRecipientContext(
params: RecipientContextParams,
): Promise<EncryptionContext>
Creates an encryption context for a recipient.

If the error occurred, throws DecapError | DeserializeError | ValidationError.
Parameters
- params: RecipientContextParams
  A set of parameters for the recipient encryption context.
Returns Promise<EncryptionContext>
A recipient encryption context.

Throws
DecapError, DeserializeError, ValidationError
Inherited from CipherSuiteNative.createRecipientContext
- Defined in ../core/src/cipherSuiteNative.ts:226

createSenderContext

createSenderContext(params: SenderContextParams): Promise<SenderContext>
Creates an encryption context for a sender.

If the error occurred, throws DecapError | ValidationError.
Parameters
- params: SenderContextParams
  A set of parameters for the sender encryption context.
Returns Promise<SenderContext>
A sender encryption context.

Throws
EncapError, ValidationError
Inherited from CipherSuiteNative.createSenderContext
- Defined in ../core/src/cipherSuiteNative.ts:198

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
- Defined in src/cipherSuite.ts:171

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
- Defined in src/cipherSuite.ts:154

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.
- isPublic: boolean = true
  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
- Defined in src/cipherSuite.ts:196

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.
- aad: ArrayBuffer = ...
  Additional authenticated data as bytes fed by an application.
Returns Promise<ArrayBuffer>
A decrypted plain text as bytes.

Throws
DecapError, DeserializeError, OpenError, ValidationError
Inherited from CipherSuiteNative.open
- Defined in ../core/src/cipherSuiteNative.ts:278

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.
- aad: 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
Inherited from CipherSuiteNative.seal
- Defined in ../core/src/cipherSuiteNative.ts:255

Class CipherSuite

Example: Use only ciphersuites supported internally.

Example: Use a ciphersuite consisting of an external module.

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns CipherSuite

Throws

Properties

Protected_api

Protected_kem

Accessors

aead

Returns AeadInterface

kdf

Returns KdfInterface

kem

Returns KemInterface

Methods

Protected_setup

Returns Promise<void>

createRecipientContext

Parameters

Returns Promise<EncryptionContext>

Throws

createSenderContext

Parameters

Returns Promise<SenderContext>

Throws

deriveKeyPair

Parameters

Returns Promise<CryptoKeyPair>

Deprecated

Throws

generateKeyPair

Returns Promise<CryptoKeyPair>

Deprecated

Throws

importKey

Parameters

Returns Promise<CryptoKey>

Deprecated

Throws

open

Parameters

Returns Promise<ArrayBuffer>

Throws

seal

Parameters

Returns Promise<CipherSuiteSealResponse>

Throws

Settings

On This Page

`Protected`_api

`Protected`_kem

`Protected`_setup