hpke-js
Version:
A Hybrid Public Key Encryption (HPKE) module for various JavaScript runtimes
108 lines • 4.18 kB
TypeScript
import type { CipherSuiteParams } from "@hpke/core";
import { CipherSuite as CipherSuiteNative } from "@hpke/core";
/**
* The Hybrid Public Key Encryption (HPKE) ciphersuite,
* which supports all of the ciphersuites defined in
* {@link https://datatracker.ietf.org/doc/html/rfc9180 | RFC9180}.
*
* The class consists of the {@link https://jsr.io/@hpke/core/doc | @hpke/core},
* {@link https://jsr.io/@hpke/chacha20Poly1305/doc | @hpke/chcha20poly1305},
* {@link https://jsr.io/@hpke/dhkem-x25519/doc | @hpke/dhkem-x25519} and
* {@link https://jsr.io/@hpke/dhkem-x448/doc | @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.
* - {@link createSenderContext}
* - {@link createRecipientContext}
* - Provides single-shot encryption API.
* - {@link seal}
* - {@link 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.
*
* ```ts
* 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.
*
* ```ts
* 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,
* });
* ```
*/
export declare class CipherSuite extends CipherSuiteNative {
/**
* @param params A set of parameters for building a cipher suite.
* @throws {@link InvalidParamError}
*/
constructor(params: CipherSuiteParams);
/**
* Generates a key pair for the cipher suite.
*
* If the error occurred, throws {@link NotSupportedError}.
*
* @deprecated Use {@link KemInterface.generateKeyPair} instead.
*
* @returns A key pair generated.
* @throws {@link NotSupportedError}
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Derives a key pair for the cipher suite in the manner
* defined in [RFC9180 Section 7.1.3](https://www.rfc-editor.org/rfc/rfc9180.html#section-7.1.3).
*
* If the error occurred, throws {@link DeriveKeyPairError}.
*
* @deprecated Use {@link KemInterface.deriveKeyPair} instead.
*
* @param ikm A byte string of input keying material. The maximum length is 128 bytes.
* @returns A key pair derived.
* @throws {@link DeriveKeyPairError}
*/
deriveKeyPair(ikm: ArrayBuffer): Promise<CryptoKeyPair>;
/**
* Imports a public or private key and converts to a {@link CryptoKey}.
*
* Since key parameters for {@link createSenderContext} or {@link createRecipientContext}
* are {@link CryptoKey} format, you have to use this function to convert provided keys
* to {@link CryptoKey}.
*
* Basically, this is a thin wrapper function of
* [SubtleCrypto.importKey](https://www.w3.org/TR/WebCryptoAPI/#dfn-SubtleCrypto-method-importKey).
*
* If the error occurred, throws {@link DeserializeError}.
*
* @deprecated Use {@link KemInterface.generateKeyPair} instead.
*
* @param format For now, `'raw'` and `'jwk'` are supported.
* @param key A byte string of a raw key or A {@link JsonWebKey} object.
* @param isPublic The indicator whether the provided key is a public key or not, which is used only for `'raw'` format.
* @returns A public or private CryptoKey.
* @throws {@link DeserializeError}
*/
importKey(format: "raw" | "jwk", key: ArrayBuffer | JsonWebKey, isPublic?: boolean): Promise<CryptoKey>;
}
//# sourceMappingURL=cipherSuite.d.ts.map