Class CipherSuite

The Hybrid Public Key Encryption (HPKE) ciphersuite, which is implemented using only Web Cryptography API.

This class is the same as @hpke/core#CipherSuiteNative as follows: which supports only the ciphersuites that can be implemented on the native Web Cryptography API. Therefore, the following cryptographic algorithms are not supported for now:

DHKEM(X25519, HKDF-SHA256)
DHKEM(X448, HKDF-SHA512)
ChaCha20Poly1305

In addtion, the HKDF functions contained in this CipherSuiteNative class can only derive keys of the same length as the hashSize.

If you want to use the unsupported cryptographic algorithms above or derive keys longer than the hashSize, please use hpke-js#CipherSuite.

This class provides following functions:

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 by Web Cryptography API.

import {
  Aes128Gcm,
  DhkemP256HkdfSha256,
  HkdfSha256,
  CipherSuite,
} from "@hpke/core";

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

Example: Use a ciphersuite which is currently not supported by Web Cryptography API.

import { Aes128Gcm, HkdfSha256, CipherSuite } from "@hpke/core";
import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
const suite = new CipherSuite({
  kem: new DhkemX25519HkdfSha256(),
  kdf: new HkdfSha256(),
  aead: new Aes128Gcm(),
});

Hierarchy

CipherSuiteNative
- CipherSuite

Index

Constructors

constructor

new CipherSuite(params: CipherSuiteParams): CipherSuite
Parameters
- params: CipherSuiteParams
  A set of parameters for building a cipher suite.
  
  If the error occurred, throws InvalidParamError.
Returns CipherSuite
Throws
InvalidParamError
Inherited from CipherSuiteNative.constructor
- Defined in src/cipherSuiteNative.ts:140

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 src/cipherSuiteNative.ts:185

kdf

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

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

kem

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

Returns KemInterface
Inherited from CipherSuiteNative.kem
- Defined in 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 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 src/cipherSuiteNative.ts:198

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 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 src/cipherSuiteNative.ts:255

Class CipherSuite

Example: Use only ciphersuites supported by Web Cryptography API.

Example: Use a ciphersuite which is currently not supported by Web Cryptography API.

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

open

Parameters

Returns Promise<ArrayBuffer>

Throws

seal

Parameters

Returns Promise<CipherSuiteSealResponse>

Throws

Settings

On This Page

`Protected`_api

`Protected`_kem

`Protected`_setup