@hpke/hybridkem-x-wing/esm/src/xWing.d.ts

A Hybrid Public Key Encryption (HPKE) module extension for X-Wing: general-purpose hybrid post-quantum KEM.

import { MlKem768 } from "mlkem";
import type { JsonWebKeyExtended, KemInterface, RecipientContextParams, SenderContextParams } from "@hpke/common";
import { KemId } from "@hpke/common";
import { X25519 } from "@hpke/dhkem-x25519";
/**
 * The Hybrid Post-Quantum KEM (X25519, Kyber768).
 *
 * This class is implemented using
 * {@link https://github.com/Argyle-Software/kyber | pqc-kyber }.
 *
 * The instance of this class can be specified to the
 * {@link https://jsr.io/@hpke/core/doc/~/CipherSuiteParams | CipherSuiteParams} as follows:
 *
 * @example Use with `@hpke/core`:
 *
 * ```ts
 * import { Aes128Gcm, CipherSuite, HkdfSha256 } from "@hpke/core";
 * import { XWing } from "@hpke/hybridkem-x-wing";
 * const suite = new CipherSuite({
 *   kem: new XWing(),
 *   kdf: new HkdfSha256(),
 *   aead: new Aes128Gcm(),
 * });
 * ```
 */
export declare class XWing implements KemInterface {
    readonly id: KemId;
    readonly name: string;
    readonly secretSize: number;
    readonly encSize: number;
    readonly publicKeySize: number;
    readonly privateKeySize: number;
    readonly auth: boolean;
    protected _m: MlKem768;
    protected _x25519: X25519;
    private _api;
    constructor();
    serializePublicKey(key: CryptoKey): Promise<ArrayBuffer>;
    deserializePublicKey(key: ArrayBuffer): Promise<CryptoKey>;
    serializePrivateKey(key: CryptoKey): Promise<ArrayBuffer>;
    deserializePrivateKey(key: ArrayBuffer): Promise<CryptoKey>;
    /**
     * Generates a new key pair.
     *
     * @returns {Promise<CryptoKeyPair>} A promise that resolves with a new key pair.
     */
    generateKeyPair(): Promise<CryptoKeyPair>;
    /**
     * Generates a key pair from the secret key.
     * @param sk The secret key.
     * @returns {Promise<CryptoKeyPair>} A promise that resolves with a new key pair.
     * @throws {InvalidParamError} Thrown if the length of the secret key is not 32 bytes.
     * @throws {DeriveKeyPairError} Thrown if the key pair cannot be derived.
     */
    generateKeyPairDerand(sk: Uint8Array): Promise<CryptoKeyPair>;
    /**
     * Derives a key pair from the input keying material.
     *
     * @param {ArrayBuffer} ikm The input keying material.
     * @returns {Promise<CryptoKeyPair>} A promise that resolves with a new key pair.
     * @throws {DeriveKeyPairError} Thrown if the key pair cannot be derived.
     * @throws {InvalidParamError} Thrown if the length of the IKM is not 32 bytes.
     */
    deriveKeyPair(ikm: ArrayBuffer): Promise<CryptoKeyPair>;
    /**
     * Imports a key from the input.
     * @param format The format of the key. "raw" or "jwk" can be specified.
     * @param key The key to import. If the format is "raw", the key must be an ArrayBuffer. If the format is "jwk", the key must be a JsonWebKey.
     * @param isPublic A boolean indicating whether the key is public or not. The default is true.
     * @returns {Promise<CryptoKey>} A promise that resolves with the imported key.
     * @throws {DeserializeError} Thrown if the key cannot be imported.
     */
    importKey(format: "raw" | "jwk", key: ArrayBuffer | JsonWebKeyExtended, isPublic?: boolean): Promise<CryptoKey>;
    /**
     * Encapsulates the shared secret and the `ct` (ciphertext) as `enc`.
     * @param params The parameters for encapsulation.
     * @returns {Promise<{ sharedSecret: ArrayBuffer; enc: ArrayBuffer }>} A promise that resolves with the `ss` (shared secret) as `sharedSecret` and the `ct` (ciphertext) as `enc`.
     * @throws {InvalidParamError} Thrown if the length of the `ekm` is not 64 bytes.
     * @throws {EncapError} Thrown if the shared secret cannot be encapsulated.
     */
    encap(params: SenderContextParams): Promise<{
        sharedSecret: ArrayBuffer;
        enc: ArrayBuffer;
    }>;
    /**
     * Decapsulates the `ss` (shared secret) from the `enc` and the recipient's private key.
     * The `enc` is the same as the `ct` (ciphertext) resulting from `X-Wing::Encapsulate(),
     * which is executed under the `encap()`.
     * @param params The parameters for decapsulation.
     * @returns {Promise<ArrayBuffer>} A promise that resolves with the shared secret.
     * @throws {InvalidParamError} Thrown if the length of the `enc` is not 1120 bytes.
     * @throws {DecapError} Thrown if the shared secret cannot be decapsulated.
     */
    decap(params: RecipientContextParams): Promise<ArrayBuffer>;
    /**
     * Sets up the MlKemBase instance by loading the necessary crypto library.
     * If the crypto library is already loaded, this method does nothing.
     * @returns {Promise<void>} A promise that resolves when the setup is complete.
     */
    private _setup;
    /**
     * Generates a key pair from the secret key.
     * @param sk The secret key.
     * @returns {Promise<[Uint8Array, Uint8Array]>} A promise that resolves with the key pair derived from the secret key.
     */
    private _generateKeyPairDerand;
    /**
     * Expands the decapsulation key.
     * @param sk The secret key.
     * @returns {Promise<[Uint8Array, Uint8Array, Uint8Array, Uint8Array]>} A promise that resolves with the keys derived by expanding the secret key.
     */
    private _expandDecapsulationKey;
    private _serializePublicKey;
    private _deserializePublicKey;
    private _serializePrivateKey;
    private _deserializePrivateKey;
    private _importJWK;
}
//# sourceMappingURL=xWing.d.ts.map