mima-kit
Version:
mima-kit is a cryptographic suite implemented in TypeScript. The goal is to provide an easy-to-use cryptographic library. mima-kit 是一个使用 TypeScript 实现的密码学套件。目标是提供一个简单易用的密码学库。
1,733 lines (1,696 loc) • 67.7 kB
TypeScript
/** 随机素数生成器 / Random Prime Generator */
interface RandomPrimeGenerator {
/**
* @param {bigint} b - 位数 / Bits
*/
(b: number): bigint;
}
/**
* 随机素数生成器 / Random Prime Generator
*
* @param {bigint} b - 位数 / Bits
*/
declare const genPrime: RandomPrimeGenerator;
/**
* 素性测试: 确定性 >= 1-.5^t
*
* Primality test: deterministic >= 1-.5^t
*
* @param {bigint} n - 待测试的数 / Number to be tested
* @param {number} t - 测试轮数 / Number of tests
*/
declare function isProbablePrime(n: bigint, t?: number): boolean;
/** 字符编解码器 / String Codec */
interface Codec {
/**
* 将编码字符串解析为 Uint8Array
*
* Parse encoded string to Uint8Array
*/
(input: string): U8;
/**
* 将 Uint8Array 编码为字符串
*
* Stringify Uint8Array to encoded string
*/
(input: Uint8Array): string;
FORMAT: string;
}
/** UTF-8 编解码器 / Codec */
declare const UTF8: Codec;
/** hex 编解码器 / Codec */
declare const HEX: Codec;
/** base64 编解码器 / Codec */
declare const B64: Codec;
/** base64url 编解码器 / Codec */
declare const B64URL: Codec;
interface B32Params {
variant?: 'rfc4648' | 'rfc4648-hex' | 'crockford';
padding?: boolean;
}
interface B32Codec extends Codec {
/**
* 创建一个 base32 编解码器
*
* Create a base32 codec
*/
(params: B32Params): Codec;
}
/** base32 编解码器 / Codec */
declare const B32: B32Codec;
/** 社会主义核心价值观编解码器 / Core Socialist Values Codec */
declare const CSV: Codec;
/**
* @extends Uint8Array
*/
declare class U8 extends Uint8Array {
/**
* 从 U8 中获取一个字 / Get a word from U8
*
* @param {number} word_size - 字长 / word size (byte)
* @param {number} index - 字索引 / word index
* @param {boolean} [little_endian] - 是否为小端序 / little-endian (default: false)
*/
getWord(word_size: number, index: number, little_endian?: boolean): bigint;
/**
* 将一个字写入 U8 / Set a word to U8
*
* @param {number} word_size - 字长 / word size (byte)
* @param {number} index - 字索引 / word index
* @param {bigint | Uint8Array} word - 字 / word
* @param {boolean} [little_endian] - 是否为小端序 / little-endian (default: false)
*/
setWord(word_size: number, index: number, word: bigint | Uint8Array, little_endian?: boolean): void;
/**
* U8 视图 / U8 view
*
* @param {number} word_size - 字长 / word size (byte)
*/
view(word_size: number): {
get: (index: number, little_endian?: boolean) => bigint;
set: (index: number, word: bigint | Uint8Array, little_endian?: boolean) => void;
length: number;
};
/**
* 将 U8 编码为字符串 / stringify U8 to encoded string
*/
to(codec: Codec): string;
/**
* 将 U8 转换为 BigInt / Convert U8 to BigInt
*
* @param {boolean} [little_endian] - 是否为小端序 / little-endian (default: false)
*/
toBI(little_endian?: boolean): bigint;
/**
* Convert U8 to Uint8Array
*
* 将 U8 转换为 Uint8Array
*/
toUint8Array(): Uint8Array<ArrayBuffer>;
/**
* Convert string to U8
*
* 将 字符串 转换为 U8
*/
static fromString(input: string, codec: Codec): U8;
/**
* Convert BigInt to U8
*
* 将 BigInt 转换为 U8
*/
static fromBI(bigint: bigint, length?: number, little_endian?: boolean): U8;
/**
* Returns the elements of an array that meet the condition specified in a callback function.
* @param predicate A function that accepts up to three arguments. The filter method calls
* the predicate function one time for each element in the array.
* @param thisArg An object to which the this keyword can refer in the predicate function.
* If thisArg is omitted, undefined is used as the this value.
*/
filter(predicate: (value: number, index: number, array: this) => any, thisArg?: any): U8;
/**
* Returns a new array from a set of elements.
* @param items A set of elements to include in the new array object.
*/
static of(...items: number[]): U8;
/**
* Creates an array from an array-like or iterable object.
* @param elements An iterable object to convert to an array.
*/
static from(elements: Iterable<number>): U8;
/**
* Creates an array from an array-like or iterable object.
* @param elements An iterable object to convert to an array.
* @param mapfn A mapping function to call on every element of the array.
* @param thisArg Value of 'this' used to invoke the mapfn.
*/
static from<T>(elements: Iterable<T>, mapfn?: (v: T, k: number) => number, thisArg?: any): U8;
/**
* Creates an array from an array-like or iterable object.
* @param arrayLike An array-like object to convert to an array.
*/
static from(arrayLike: ArrayLike<number>): U8;
/**
* Creates an array from an array-like or iterable object.
* @param arrayLike An array-like object to convert to an array.
* @param mapfn A mapping function to call on every element of the array.
* @param thisArg Value of 'this' used to invoke the mapfn.
*/
static from<T>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => number, thisArg?: any): U8;
/**
* Calls a defined callback function on each element of an array, and returns an array that
* contains the results.
* @param callbackfn A function that accepts up to three arguments. The map method calls the
* callbackfn function one time for each element in the array.
* @param thisArg An object to which the this keyword can refer in the callbackfn function.
* If thisArg is omitted, undefined is used as the this value.
*/
map(callbackfn: (value: number, index: number, array: this) => number, thisArg?: any): U8;
/**
* Returns a section of an array.
* @param start The beginning of the specified portion of the array.
* @param end The end of the specified portion of the array. This is exclusive of the element at the index 'end'.
*/
slice(start?: number, end?: number): U8;
/**
* Gets a new Uint8Array view of the ArrayBuffer store for this array, referencing the elements
* at begin, inclusive, up to end, exclusive.
* @param begin The index of the beginning of the array.
* @param end The index of the end of the array.
*/
subarray(begin?: number, end?: number): U8;
/**
* Copies the array and returns the copy with the elements in reverse order.
*/
toReversed(): U8;
/**
* Copies and sorts the array.
* @param compareFn Function used to determine the order of the elements. It is expected to return
* a negative value if the first argument is less than the second argument, zero if they're equal, and a positive
* value otherwise. If omitted, the elements are sorted in ascending order.
* ```ts
* const myNums = Uint8Array.from([11, 2, 22, 1]);
* myNums.toSorted((a, b) => a - b) // Uint8Array(4) [1, 2, 11, 22]
* ```
*/
toSorted(compareFn?: (a: number, b: number) => number): U8;
/**
* Copies the array and inserts the given number at the provided index.
* @param index The index of the value to overwrite. If the index is
* negative, then it replaces from the end of the array.
* @param value The value to insert into the copied array.
* @returns A copy of the original array with the inserted value.
*/
with(index: number, value: number): U8;
}
/**
* Merging multiple ArrayBuffers
*
* 合并多个 ArrayBuffer
*/
declare function joinBuffer(...buffers: Uint8Array[]): U8;
interface Digest {
/**
* @param {Uint8Array} M - 消息 / message
*/
(M: Uint8Array): U8;
}
interface HashDescription {
/** 算法名称 / Algorithm name */
ALGORITHM: string;
/** 分块大小 / Block size (byte) */
BLOCK_SIZE: number;
/** 摘要大小 / Digest size (byte) */
DIGEST_SIZE: number;
OID?: string;
}
interface Hash extends Digest, HashDescription {
}
/**
* 散列算法包装器,
* 提供散列算法描述, 以实现 `HMAC` 等拓展算法.
*
* Hash algorithm wrapper,
* provide hash algorithm description to implement extended algorithms such as `HMAC`.
*
* @param {Digest} digest - 摘要函数 / digest function
* @param {HashDescription} description - 算法描述 / algorithm description
*
* ```ts
* const digest: Digest = (M: Uint8Array): U8 => { ... }
* const description: HashDescription = { ... }
* const hash = createHash(digest, description)
* ```
*/
declare const createHash: (digest: Digest, description: HashDescription) => Hash;
interface TupleDigest {
/**
* @param {Uint8Array[]} M - 消息 / message
*/
(M: Uint8Array[]): U8;
}
interface TupleHashDescription extends HashDescription {
}
interface TupleHash extends TupleDigest, TupleHashDescription {
}
/**
* 元组散列算法包装器
*
* Tuple hash algorithm wrapper
*
* @param {TupleDigest} digest - 元组摘要函数 / tuple digest function
* @param {TupleHashDescription} description - 算法描述 / algorithm description
*
* ```ts
* const digest: TupleDigest = (M: Uint8Array[]): U8 => { ... }
* const description: TupleHashDescription = { ... }
* const hash = createTupleHash(digest, description)
* ```
*/
declare const createTupleHash: (digest: TupleDigest, description: TupleHashDescription) => TupleHash;
interface KeyDigest {
/**
* @param {Uint8Array} K - 密钥 / key
* @param {Uint8Array} M - 消息 / message
*/
(K: Uint8Array, M: Uint8Array): U8;
}
interface KeyHashDescription extends HashDescription {
/** 推荐的密钥大小 / Recommended key size (byte) */
KEY_SIZE: number;
}
/** 密钥散列函数 / Keyed hash function */
interface KeyHash extends KeyDigest, KeyHashDescription {
}
declare const sm3: Hash;
declare const md5: Hash;
declare const sha1: Hash;
declare const sha224: Hash;
declare const sha256: Hash;
declare const sha384: Hash;
declare const sha512: Hash;
/**
* @param {number} t - 截断长度 / truncation length (bit)
*/
declare function sha512t(t: number): Hash;
declare const sha3_224: Hash;
declare const sha3_256: Hash;
declare const sha3_384: Hash;
declare const sha3_512: Hash;
/**
* @param {number} d - 输出长度 / Digest Size (bit)
*/
declare function shake128(d: number): Hash;
/**
* @param {number} d - 输出长度 / Digest Size (bit)
*/
declare function shake256(d: number): Hash;
/**
* `cSHAKE128` 是 `SHAKE128` 的可定制变体
*
* `cSHAKE128` is a customizable variant of `SHAKE128`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} [N] - 函数名 / Function name
* @param {Uint8Array} [S] - 自定义参数 / Customization
*/
declare function cshake128(d: number, N?: Uint8Array<ArrayBuffer>, S?: Uint8Array<ArrayBuffer>): Hash;
/**
* `cSHAKE256` 是 `SHAKE256` 的可定制变体
*
* `cSHAKE256` is a customizable variant of `SHAKE256`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} [N] - 函数名 / Function name
* @param {Uint8Array} [S] - 自定义参数 / Customization
*/
declare function cshake256(d: number, N?: Uint8Array<ArrayBuffer>, S?: Uint8Array<ArrayBuffer>): Hash;
/**
* Keccak 消息认证码 (KMAC) 算法
* `KMAC128` 是 `KMAC` 的变体, 由 `cSHAKE128` 构建
*
* The Keccak Message Authentication Code (KMAC) algorithm
* `KMAC128` is a variant of `KMAC`, build from `cSHAKE128`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
* @param {number} k_size - 推荐密钥大小 / Recommended key size (bit)
*/
declare function kmac128(d: number, S?: Uint8Array<ArrayBuffer>, k_size?: number): KeyHash;
/**
* Keccak 消息认证码 (KMAC) 算法
* `KMAC256` 是 `KMAC` 的变体, 由 `cSHAKE256` 构建
*
* The Keccak Message Authentication Code (KMAC) algorithm
* `KMAC256` is a variant of `KMAC`, build from `cSHAKE256`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
* @param {number} k_size - 推荐密钥大小 / Recommended key size (bit)
*/
declare function kmac256(d: number, S?: Uint8Array<ArrayBuffer>, k_size?: number): KeyHash;
/**
* 可变长度输出的 `KMAC`
* `KMAC128XOF` 是 `KMAC128` 的 XOF 模式, 由 `cSHAKE128` 构建
*
* `KMAC` with Arbitrary-Length Output
* `KMAC128XOF` is a XOF mode of `KMAC128`, build from `cSHAKE128`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
* @param {number} k_size - 推荐密钥大小 / Recommended key size (bit)
*/
declare function kmac128XOF(d: number, S?: Uint8Array<ArrayBuffer>, k_size?: number): KeyHash;
/**
* 可变长度输出的 `KMAC`
* `KMAC256XOF` 是 `KMAC256` 的 XOF 模式, 由 `cSHAKE256` 构建
*
* `KMAC` with Arbitrary-Length Output
* `KMAC256XOF` is a XOF mode of `KMAC256`, build from `cSHAKE256`
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
* @param {number} k_size - 推荐密钥大小 / recommended key size (bit)
*/
declare function kmac256XOF(d: number, S?: Uint8Array<ArrayBuffer>, k_size?: number): KeyHash;
/**
* `TupleHash` 是一个具有可变长度输出的 `SHA3` 派生散列函数, 旨在以一种明确的方式简单地散列输入字符串的元组, 这些字符串中的任何一个或全部都可以是空字符串.
*
* `TupleHash` is a `SHA3` derived hash function with variable-length output that is designed to simply hash a tuple of input strings, any or all of which may be empty strings, in an unambiguous way.
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function tuplehash128(d: number, S?: Uint8Array): TupleHash;
/**
* `TupleHash` 是一个具有可变长度输出的 `SHA3` 派生散列函数, 旨在以一种明确的方式简单地散列输入字符串的元组, 这些字符串中的任何一个或全部都可以是空字符串.
*
* `TupleHash` is a `SHA3` derived hash function with variable-length output that is designed to simply hash a tuple of input strings, any or all of which may be empty strings, in an unambiguous way.
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function tuplehash256(d: number, S?: Uint8Array): TupleHash;
/**
* 可变长度输出的 `TupleHash`
*
* `TupleHash` with Arbitrary-Length Output
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function tuplehash128XOF(d: number, S?: Uint8Array): TupleHash;
/**
* 可变长度输出的 `TupleHash`
*
* `TupleHash` with Arbitrary-Length Output
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function tuplehash256XOF(d: number, S?: Uint8Array): TupleHash;
/**
* `ParallelHash` 的目的是利用现代处理器中可用的并行性, 支持对非常长的字符串进行高效散列.
*
* The purpose of `ParallelHash` is to support the efficient hashing of very long strings, by taking advantage of the parallelism available in modern processors.
*
* @param {number} b - 状态大小 / State size (bit)
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function parallelhash128(b: number, d: number, S?: Uint8Array): Hash;
/**
* `ParallelHash` 的目的是利用现代处理器中可用的并行性, 支持对非常长的字符串进行高效散列.
*
* The purpose of `ParallelHash` is to support the efficient hashing of very long strings, by taking advantage of the parallelism available in modern processors.
*
* @param {number} b - 状态大小 / State size (bit)
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function parallelhash256(b: number, d: number, S?: Uint8Array): Hash;
/**
* 可变长度输出的 `ParallelHash`
*
* `ParallelHash` with Arbitrary-Length Output
*
* @param {number} b - 状态大小 / State size (bit)
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function parallelhash128XOF(b: number, d: number, S?: Uint8Array): Hash;
/**
* 可变长度输出的 `ParallelHash`
*
* `ParallelHash` with Arbitrary-Length Output
*
* @param {number} b - 状态大小 / State size (bit)
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} S - 自定义参数 / Customization
*/
declare function parallelhash256XOF(b: number, d: number, S?: Uint8Array): Hash;
/**
* `Keccak-p` 置换函数 / Permutate Function
*/
interface Keccak_p {
/**
* @param {Uint8Array} S - 状态 / State
*/
(S: Uint8Array): Uint8Array;
}
/**
* `Keccak-p[1600, nr]` 置换函数 / Permutate Function
*
* @param {number} [nr] - 轮数 / Rounds (default: 24)
*/
declare function keccak_p_1600(nr?: number): Keccak_p;
/**
* `SPONGE` 填充函数 / Padding Function
*/
interface SpongePadding {
/**
* @param {Uint8Array} M - 消息 / Message
*/
(M: Uint8Array): U8;
}
/**
* `SPONGE` & `Keccak-p[1600]`
*
* @param {number} r_byte - 处理速率 / Rate
* @param {number} d_byte - 输出长度 / Digest Size
* @param {SpongePadding} pad - 填充函数 / Padding Function
* @param {Keccak_p} f - Keccak-p 置换函数 / Permutate Function
*/
declare function sponge_1600(r_byte: number, d_byte: number, pad: SpongePadding, f?: Keccak_p): (M: Uint8Array) => U8;
/**
* TurboSHAKE128
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {number} [D] - 域分隔符 / Domain Separator (range: 0x01 ~ 0x7F, default: 0x1F)
*/
declare function turboshake128(d: number, D?: number): Hash;
/**
* TurboSHAKE256
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {number} [D] - 域分隔符 / Domain Separator (range: 0x01 ~ 0x7F, default: 0x1F)
*/
declare function turboshake256(d: number, D?: number): Hash;
/**
* KangarooTwelve 128
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} [C] - 自定义参数 / Customization
*/
declare function kt128(d: number, C?: Uint8Array<ArrayBuffer>): Hash;
/**
* KangarooTwelve 256
*
* @param {number} d - 输出长度 / Digest Size (bit)
* @param {Uint8Array} [C] - 自定义参数 / Customization
*/
declare function kt256(d: number, C?: Uint8Array<ArrayBuffer>): Hash;
/**
* FIPS.198-1: 散列消息认证码 (HMAC).
* 如果 `d_size` 大于散列算法的摘要大小, 则回退到散列算法的摘要大小.
*
* FIPS.198-1: The Keyed-Hash Message Authentication Code (HMAC).
* If `d_size` is larger than the hash algorithm's digest size, fallback to the hash algorithm's digest size.
*
* @param {Hash} hash - 散列算法 / hash algorithm
* @param {number} [d_size] - 摘要大小 (bit) / digest size (bit)
* @param {number} [k_size] - 推荐密钥大小 (bit) / recommended key size (bit)
*/
declare function hmac(hash: Hash, d_size?: number, k_size?: number): KeyHash;
interface TOTP {
/**
* 生成 TOTP (时间同步的一次性密码)
*
* Generate TOTP (Time-based One-Time Password)
*
* @param {Uint8Array} secret - 密钥 / Secret key
* @returns {string} - 返回的 TOTP 字符串 / TOTP string
*/
(secret: Uint8Array): string;
}
interface TOTPParams {
/**
* 带密钥的加密散列算法 / Keyed Hashing Algorithm (default: HMAC-SHA1)
*/
mac?: KeyHash;
/**
* 当前时间戳 / Current timestamp (default: Date.now() milliseconds)
*
* 指定此参数时，将不再从 `Date.now()` 获取当前时间戳.
*
* When this parameter is specified, the current timestamp will not be obtained from `Date.now()`.
*/
current?: number;
/**
* 纪元时间戳 / Epoch timestamp (default: 0 milliseconds)
*/
epoch?: number;
/**
* 时间步长 / Time step (default: 30000 milliseconds)
*/
step?: number;
/**
* 计数器 / Counter
*
* `counter = (cuttent_time - epoch_time) / step`
*
* 指定此参数时，将不再从当前时间戳计算计数器.
*
* When this parameter is specified, the counter will not be calculated from the current timestamp.
*/
counter?: number | bigint | Uint8Array;
/**
* 返回的数字位数 / Number of digits in the returned OTP (default: 6)
*/
digits?: number;
}
/**
* 生成 TOTP (时间同步的一次性密码)
*
* Generate TOTP (Time-based One-Time Password)
*
* @param {Uint8Array} secret - 密钥 / Secret key
* @returns {string} - 返回的 TOTP 字符串 / TOTP string
*/
declare function totp(secret: Uint8Array): string;
/**
* 创建 TOTP 函数 / Create a TOTP function
*
* @param {TOTPParams} params - TOTP 参数 / TOTP parameters
* @returns {TOTP} - 返回的 TOTP 函数 / TOTP function
*/
declare function totp(params: TOTPParams): TOTP;
interface Cipherable {
/**
* @param {Uint8Array} plaintext - 明文 / plaintext
*/
encrypt: (plaintext: Uint8Array) => U8;
/**
* @param {Uint8Array} ciphertext - 密文 / ciphertext
*/
decrypt: (ciphertext: Uint8Array) => U8;
}
interface CipherInfo {
ALGORITHM: string;
/** 推荐的密钥大小 / Recommended key size (byte) */
KEY_SIZE: number;
/** 最小密钥大小 / Minimum key size (byte) */
MIN_KEY_SIZE: number;
/** 最大密钥大小 / Maximum key size (byte) */
MAX_KEY_SIZE: number;
}
interface IVCipherInfo extends CipherInfo {
/** 推荐的 IV 大小 / Recommended IV size (byte) */
IV_SIZE: number;
/** 最小 IV 大小 / Minimum IV size (byte) */
MIN_IV_SIZE: number;
/** 最大 IV 大小 / Maximum IV size (byte) */
MAX_IV_SIZE: number;
}
interface Cipher {
/**
* @param {Uint8Array} key - 密钥 / Key
*/
(key: Uint8Array): Cipherable;
}
interface IVCipher {
/**
* @param {Uint8Array} key - 密钥 / Key
* @param {Uint8Array} iv - 初始化向量 / Initialization Vector
*/
(key: Uint8Array, iv: Uint8Array): Cipherable;
}
interface BlockCipherInfo extends CipherInfo {
/** 分组大小 / Block size (byte) */
BLOCK_SIZE: number;
}
interface BlockCipher extends BlockCipherInfo {
/**
* @param {Uint8Array} key - 密钥 / Key
*/
(key: Uint8Array): Cipherable & BlockCipherInfo;
}
interface StreamCipherInfo extends CipherInfo {
}
interface StreamCipher extends StreamCipherInfo {
/**
* @param {Uint8Array} key - 密钥 / Key
*/
(key: Uint8Array): Cipherable & StreamCipherInfo;
}
interface IVStreamCipherInfo extends IVCipherInfo {
}
interface IVStreamCipher extends IVStreamCipherInfo {
/**
* @param {Uint8Array} key - 密钥 / Key
* @param {Uint8Array} iv - 初始化向量 / Initialization Vector
*/
(key: Uint8Array, iv: Uint8Array): Cipherable & IVStreamCipherInfo;
}
declare function createCipher(algorithm: Cipher, description: BlockCipherInfo): BlockCipher;
declare function createCipher(algorithm: Cipher, description: StreamCipherInfo): StreamCipher;
declare function createCipher(algorithm: IVCipher, description: IVStreamCipherInfo): IVStreamCipher;
interface DoPad {
/**
* 添加填充 / add padding
* @param {Uint8Array} M - 消息 / Message
* @param {number} BLOCK_SIZE - 分组大小 / Block size
*/
(M: Uint8Array, BLOCK_SIZE: number): U8;
}
interface UnPad {
/**
* 移除填充 / remove padding
* @param {Uint8Array} P - 填充消息 / Padded message
*/
(P: Uint8Array): U8;
}
interface PaddingInfo {
ALGORITHM: string;
}
interface Padding extends DoPad, UnPad, PaddingInfo {
}
/** PKCS7 填充方案 / Padding Scheme */
declare const PKCS7_PAD: Padding;
/** ISO/IEC 7816 填充方案 / Padding Scheme */
declare const ISO7816_PAD: Padding;
/** ANSI X9.23 填充方案 / Padding Scheme */
declare const X923_PAD: Padding;
/** Zero 零填充方案 / Padding Scheme */
declare const ZERO_PAD: Padding;
/** 无填充 / No Padding */
declare const NO_PAD: Padding;
interface ModeBaseInfo {
ALGORITHM: string;
}
interface ModeInfo extends BlockCipherInfo {
/** 填充方案 / Padding Scheme */
PADDING: Padding;
/** 推荐的 IV 大小 / Recommended IV size (byte) */
IV_SIZE: number;
/** 最小 IV 大小 / Minimum IV size (byte) */
MIN_IV_SIZE: number;
/** 最大 IV 大小 / Maximum IV size (byte) */
MAX_IV_SIZE: number;
}
interface Mode extends ModeBaseInfo {
/**
* @param {BlockCipher} cipher - 分组加密算法 / Block cipher
* @param {Padding} padding - 填充方案 / Padding Scheme (default: PKCS7)
*/
(cipher: BlockCipher, padding?: Padding): {
/**
* @param {Uint8Array} key - 密钥 / Key
* @param {Uint8Array} iv - 初始化向量 / Initialization Vector
*/
(key: Uint8Array, iv: Uint8Array): Cipherable & ModeInfo;
} & ModeInfo;
}
interface ECBMode extends ModeBaseInfo {
/**
* @param {BlockCipher} cipher - 分组加密算法 / Block cipher
* @param {Padding} padding - 填充方案 / Padding Scheme (default: PKCS7)
*/
(cipher: BlockCipher, padding?: Padding): {
/**
* ECB 不使用 IV, 如果提供 IV, 将被忽略. 仅为与其他模式兼容
*
* ECB do not use IV, if you provide IV, it will be ignored. It is only for compatibility with other Modes
*
* @param {Uint8Array} key - 密钥 / Key
* @param {Uint8Array} [iv] - 初始化向量 / Initialization Vector
*/
(key: Uint8Array, iv?: Uint8Array): Cipherable & ModeInfo;
} & ModeInfo;
}
/** 电子密码本模式 / Electronic Code Book Mode */
declare const ecb: ECBMode;
interface CBCMode extends Mode {
}
/** 密码块链接模式 / Cipher Block Chaining Mode */
declare const cbc: CBCMode;
interface PCBCMode extends Mode {
}
/** 传播密码块链接模式 / Propagating Cipher Block Chaining Mode */
declare const pcbc: PCBCMode;
interface CFBMode extends Mode {
}
/** 密码反馈模式 / Cipher Feedback Mode */
declare const cfb: CFBMode;
interface OFBMode extends Mode {
}
/** 输出反馈模式 / Output Feedback Mode */
declare const ofb: OFBMode;
interface CTRMode extends Mode {
}
/** 计数器模式 / Counter Mode */
declare const ctr: CTRMode;
interface GCMVerifiable {
/**
* @param {Uint8Array} cipherText - 密文 / ciphertext
* @param {Uint8Array} additional_data - 附加数据 / Additional data
* @returns {Uint8Array} - 认证标签 / Authentication tag
*/
sign: (cipherText: Uint8Array, additional_data?: Uint8Array) => U8;
/**
* @param {Uint8Array} auth_tag - 认证标签 / Authentication tag
* @param {Uint8Array} ciphertext - 密文 / ciphertext
* @param {Uint8Array} additional_data - 附加数据 / Additional data
*/
verify: (auth_tag: Uint8Array, ciphertext: Uint8Array, additional_data?: Uint8Array) => boolean;
}
interface GCMModeInfo extends ModeInfo {
/**
* 认证标签大小 / Authentication tag size (byte)
*
* @default 16
*/
AUTH_TAG_SIZE: number;
}
interface GCMMode extends ModeBaseInfo {
/**
* @param {BlockCipher} cipher - 分组加密算法 / Block cipher
* @param {Padding} padding - 填充方案 / Padding Scheme (default: PKCS7)
* @param {number} tag_size - 标签大小 / Authentication tag size (default: 16)
*/
(cipher: BlockCipher, padding?: Padding, tag_size?: number): {
/**
* @param {Uint8Array} key - 密钥 / Key
* @param {Uint8Array} iv - 初始化向量 / Initialization Vector
*/
(key: Uint8Array, iv: Uint8Array): Cipherable & GCMVerifiable & GCMModeInfo;
} & GCMModeInfo;
}
/** 伽罗瓦计数器模式 / Galois Counter Mode */
declare const gcm: GCMMode;
/**
* ARC4 流密码 / stream cipher
*/
declare const arc4: StreamCipher;
/**
* Rabbit 流密码 / stream cipher
*/
declare const rabbit: IVStreamCipher;
/**
* Salsa20 流密码 / Stream Cipher
*/
declare const salsa20: IVStreamCipher;
/**
* 3GPP ZUC 算法用于生成密钥流，每次调用返回一个 32 位的密钥流.
*
* 3GPP ZUC algorithm is used to generate a key stream, each call returns a 32-bit key stream.
*
* ```ts
* const K = new Uint8Array(16)
* const iv = new Uint8Array(16)
* const prg = zuc(K, iv)
* prg() // 32-bit number
* ```
*/
declare function zuc(K: Uint8Array, iv: Uint8Array): () => number;
interface ZUCParams {
/**
* 32-bit counter
*
* if `counter` is `number` type, convert to `Uint8Array` type in little-endian.
*
* 如果 `counter` 为 `number` 类型，则转换为小端存储的 `Uint8Array` 类型.
*/
COUNTER: Uint8Array | number;
/**
* 5-bit bearer
*/
BEARER: number;
/**
* 1-bit direction
*/
DIRECTION: 0 | 1;
/**
* 128-bit key
*/
KEY: Uint8Array;
/**
* 32-bit length
*/
LENGTH: number;
M: Uint8Array;
}
interface ZUC3GPP {
(param: ZUCParams): U8;
}
/**
* 3GPP ZUC 加密算法 / Encryption algorithm
*/
declare const eea3: ZUC3GPP;
/**
* 3GPP ZUC 完整性算法 / Integrity algorithm
*/
declare const eia3: ZUC3GPP;
/**
* 高级加密标准 (AES) 分组密码算法
*
* Advanced Encryption Standard (AES) block cipher algorithm
*
* @param {128 | 192 | 256} b - 密钥长度 / Key size (bit)
*/
declare function aes(b: 128 | 192 | 256): BlockCipher;
/**
* ARC5 分组加密算法 / block cipher algorithm
*
* ```ts
* const spec8 = arc5(8, 8) // ARC5-8/8
* const spec16 = arc5(16, 12) // ARC5-16/12
* const spec32 = arc5(32, 16) // ARC5-32/16 (default)
* const spec64 = arc5(64, 20) // ARC5-64/20
* const spec128 = arc5(128, 24) // ARC5-128/24
* ```
*
* @param {16 | 32 | 64} WORD_SIZE - 工作字长 / Word size (default: 32 bit)
* @param {number} round - 轮数 / Rounds (default: 16)
*/
declare function arc5(WORD_SIZE?: 8 | 16 | 32 | 64 | 128, round?: number): BlockCipher;
/**
* ARIA 分组密码算法 / block cipher algorithm
*
* @param {128 | 192 | 256} b - 密钥长度 / Key size (bit)
*/
declare function aria(b: 128 | 192 | 256): BlockCipher;
/**
* Blowfish 分组密码算法 / block cipher algorithm
*/
declare const blowfish: BlockCipher;
/**
* Camellia 分组密码算法 / block cipher algorithm
*
* @param {128 | 192 | 256} b - 密钥长度 / Key size (bit)
*/
declare function camellia(b: 128 | 192 | 256): BlockCipher;
/**
* Data Encryption Standard (DES) block cipher algorithm
*
* 数据加密标准（DES）分组密码算法
*/
declare const des: BlockCipher;
/**
* Triple Data Encryption Standard (3DES) block cipher algorithm
*
* 三重数据加密标准（3DES）分组密码算法
*
* @param {128 | 192} l - 密钥长度 / Key Size (bit)
*/
declare function t_des(l: 128 | 192): BlockCipher;
/**
* SM4 分组密码算法 / block cipher algorithm
*/
declare const sm4: BlockCipher;
/**
* 微型加密算法 (TEA) 分组密码算法
*
* Tiny Encryption Algorithm (TEA) block cipher algorithm
*
* @param {number} round - 轮数 / Rounds (default: 32)
*/
declare function tea(round?: number): BlockCipher;
/**
* 扩展微型加密算法 (XTEA) 分组密码算法
*
* eXtended Tiny Encryption Algorithm (XTEA) block cipher algorithm
*
* @param {number} round - 轮数 / Rounds (default: 32)
*/
declare function xtea(round?: number): BlockCipher;
interface XXTEAConfig {
/**
* 分组大小 / Block size (default: 16)
*
* `XXTEA` 本身设计用于加密任意数量的数据块。单独使用 `XXTEA` 时，该选项不起作用。
* 但是，如果需要将 `XXTEA` 用作分组密码和 `工作模式` 一起使用，则可以通过此选项设置分组大小。
*
* 注意: 这不是 `XXTEA` 的标准用法且缺乏相关的安全分析。
*
* `XXTEA` is natively designed to encrypt arbitrary amounts of data blocks.
* When used alone, this option does not take effect.
* However, if you need to use `XXTEA` as a block cipher and use it with `Operation Mode`,
* you can set the `BLOCK_SIZE` through this option.
*
* Note: This is not the standard usage of `XXTEA` and lacks relevant security analysis.
*/
BLOCK_SIZE?: number;
/**
* 填充方式 / Padding method (default: PKCS7)
*
* 如果要像其他分组密码一样使用 `XXTEA`，例如使用 `CBC` 模式，
* 应该将 `padding` 设置为 `NO_PAD` 并让 `工作模式` 处理填充。
*
* If you want to use `XXTEA` like other block ciphers, such as with `CBC` mode,
* you should set the `padding` to `NO_PAD` and let the `Operation Mode` handle the padding.
*/
padding?: Padding;
/**
* 轮数 / Rounds (default: undefined)
*
* `XXTEA` 的轮数可以通过这个选项设置，如果不设置则使用默认的轮数计算方式。
*
* The rounds of `XXTEA` can be set through this option,
* if not set, the default round calculation method will be used.
*/
round?: number;
}
/**
* 纠正块 TEA (XXTEA) 分组密码算法
*
* Corrected Block TEA (XXTEA) block cipher algorithm
*/
declare function xxtea(config?: XXTEAConfig): BlockCipher;
/**
* Twofish 分组密码算法 / block cipher algorithm
*
* @param {128 | 192 | 256} b - 密钥长度 / Key size (bit)
*/
declare function twofish(b: 128 | 192 | 256): BlockCipher;
interface RSAPublicKey {
/** 模数 / Modulus */
n: bigint;
/** 公钥指数 / Public Exponent */
e: bigint;
}
interface RSAPrivateKey extends RSAPublicKey {
/** 模数 / Modulus */
n: bigint;
/** 公钥指数 / Public Exponent */
e: bigint;
/** 私钥指数 / Private Exponent */
d: bigint;
p: bigint;
q: bigint;
dP: bigint;
dQ: bigint;
qInv: bigint;
}
interface RSACipherable {
/**
* 使用 RSA 加密原语加密消息
*
* Encrypt message using RSA encryption primitive
*/
encrypt: (M: Uint8Array) => bigint;
/**
* 使用 RSA 解密原语解密密文
*
* Decrypt ciphertext using RSA decryption primitive
*/
decrypt: (C: Uint8Array) => bigint;
}
interface RSAVerifiable {
/**
* 使用 RSA 签名原语对消息签名
*
* Sign message using RSA signature primitive
*/
sign: (M: Uint8Array) => bigint;
/**
* 使用 RSA 验证原语验证签名
*
* Verify signature using RSA verification primitive
*/
verify: (S: Uint8Array) => bigint;
}
/**
* 根据 RSA 私钥长度生成 RSA 密钥对, 并返回 RSA 加密原语和签名原语
*
* Generate RSA key pair according to RSA private key length, and return RSA encryption primitive and signature primitive
*
* @param {number} b - RSA 私钥长度 / RSA private key length
* @param {RandomPrimeGenerator} rpg - 随机素数生成器 / Random prime generator
*/
declare function rsa(b: number, rpg?: RandomPrimeGenerator): RSACipherable & RSAVerifiable & RSAPrivateKey;
/**
* 根据 RSA 公钥或私钥生成 RSA 加密原语和验证原语
*
* Generate RSA encryption primitive and verification primitive according to RSA public or private key
*
* @param {RSAPrivateKey | RSAPublicKey} key - RSA 公钥或私钥 / RSA public or private key
*/
declare function rsa<T extends RSAPrivateKey | RSAPublicKey>(key: T): RSACipherable & RSAVerifiable & T;
interface MGF {
(mdfSeed: Uint8Array, maskLen: number): Uint8Array;
}
/**
* PKCS#1 v2.2 的 掩码生成函数 MGF1
*
* Mask Generation Function MGF1 of PKCS#1 v2.2
*/
declare function mgf1(hash: Hash): MGF;
/**
* 最优非对称加密填充的 RSA 加密方案 (OAEP)
*
* RSA Encryption Scheme with Optimal Asymmetric Encryption Padding (OAEP)
*
* @param {RSAPublicKey | RSAPrivateKey} key - RSA 公钥或私钥 / RSA public or private key
* @param {Hash} [hash] - 散列函数 / Hash function (default: SHA-256)
* @param {MGF} [mgf] - 掩码生成函数 / Mask generation function (default: MGF1)
* @param {Uint8Array} [label] - 标签 / Label (default: empty)
*/
declare function pkcs1_es_oaep(key: RSAPublicKey | RSAPrivateKey, hash?: Hash, mgf?: MGF, label?: Uint8Array<ArrayBuffer>): {
encrypt: (M: Uint8Array) => U8;
decrypt: (C: Uint8Array) => U8;
};
/**
* RSA 加密方案 (PKCS#1 v1.5)
*
* RSA Encryption Scheme (PKCS#1 v1.5)
*
* @param {RSAPublicKey | RSAPrivateKey} key - RSA 公钥或私钥 / RSA public or private key
*/
declare function pkcs1_es_1_5(key: RSAPublicKey | RSAPrivateKey): {
encrypt: (M: Uint8Array) => U8;
decrypt: (C: Uint8Array) => U8;
};
/**
* 基于 概率签名方案 的 RSA 附录签名方案 (PSS)
*
* RSA Signature Scheme with Appendix - Probabilistic Signature Scheme (PSS)
*
* @param {RSAPublicKey | RSAPrivateKey} key - RSA 公钥或私钥 / RSA public or private key
* @param {Hash} [hash] - 散列函数 / Hash function (default: SHA-256)
* @param {MGF} [mgf] - 掩码生成函数 / Mask generation function (default: MGF1)
* @param {number} [sLen] - 盐长度 / Salt length (default: hash.DIGEST_SIZE)
*/
declare function pkcs1_ssa_pss(key: RSAPublicKey | RSAPrivateKey, hash?: Hash, mgf?: MGF, sLen?: number): {
sign: (M: Uint8Array) => U8;
verify: (M: Uint8Array, S: Uint8Array) => boolean;
};
/**
* RSA 附录签名方案 (PKCS#1 v1.5)
*
* RSA Signature Scheme with Appendix (PKCS#1 v1.5)
*
* @param {RSAPublicKey | RSAPrivateKey} key - RSA 公钥或私钥 / RSA public or private key
* @param {Hash} [hash] - 散列函数 / Hash function (default: SHA-256)
*/
declare function pkcs1_ssa_1_5(key: RSAPublicKey | RSAPrivateKey, hash?: Hash): {
sign: (M: Uint8Array) => U8;
verify: (M: Uint8Array, S: Uint8Array) => boolean;
};
interface KDF {
/**
* @param {number} k_byte - 期望的密钥长度 / output keying material length
* @param {Uint8Array} ikm - 输入密钥材料 / input keying material
* @param {Uint8Array} salt - 盐 / salt value
*/
(k_byte: number, ikm: Uint8Array, salt?: Uint8Array): U8;
}
/**
* ANSI-X9.63 Key Derivation Function
*
* ANSI-X9.63 密钥派生函数
*/
declare function x963kdf(hash: Hash, info?: Uint8Array<ArrayBuffer>): KDF;
/**
* HMAC-based Key Derivation Function (HKDF), please combine `hmac` and `hash` externally to control the behavior of calling `hmac` inside the function.
*
* 基于 HMAC 的密钥派生函数 (HKDF), 请在外部组合 `hmac` 和 `hash` 函数, 以控制在函数内部调用 `hmac` 时的行为.
*/
declare function hkdf(k_hash: KeyHash, info?: Uint8Array<ArrayBuffer>): KDF;
/**
* Password-Based Key Derivation Function 2 (PBKDF2), please combine `hmac` and `hash` externally to control the behavior of calling `hmac` inside the function.
*
* PBKDF2 密码基础密钥派生函数 (PBKDF2), 请在外部组合 `hmac` 和 `hash` 函数, 以控制在函数内部调用 `hmac` 时的行为.
*/
declare function pbkdf2(k_hash: KeyHash, iterations?: number): KDF;
interface ScryptConfig {
/**
* 开销因子 / Cost factor (default: 16384)
*
* 必须是 2 的幂
*
* Must be a power of 2
*/
N?: number;
/**
* 块数 / Block count (default: 8)
*/
r?: number;
/**
* 并行因子 / Parallelization factor (default: 1)
*/
p?: number;
/**
* 最大内存使用量 / Maximum memory usage
*
* 如果设置为 0，则不限制内存使用量
*
* If set to 0, there is no limit on memory usage
*
* (default: 0x40000400 bytes, 1GB + 1KB)
*/
maxmem?: number;
/**
* 密钥派生函数 / Key Derivation Function
*
* scrypt 标准使用了 `PBKDF2-HMAC-SHA256` 作为 KDF。
* 该参数允许用户指定其他 KDF，改变 scrypt 的内部行为。
*
* 注意: 这不是 `scrypt` 的标准用法且缺乏相关的安全分析。
*
* The scrypt standard uses `PBKDF2-HMAC-SHA256` as the KDF.
* This parameter allows users to specify a different KDF, changing the internal behavior of scrypt.
*
* Note: This is not the standard usage of `scrypt` and lacks relevant security analysis.
*
* (default: pbkdf2(hmac(sha256), 1))
*/
kdf?: KDF;
}
/**
* Scrypt Key Derivation Function
*
* Scrypt 密钥派生函数
*
* Based on https://github.com/paulmillr/noble-hashes
*/
declare function scrypt(config?: ScryptConfig): KDF;
/**
* 伽罗瓦域运算接口
*
* Galois Field Operations Interface
*/
interface GFUtils {
include: (a: bigint) => boolean;
add: (...args: bigint[]) => bigint;
sub: (a: bigint, ...args: bigint[]) => bigint;
mul: (...args: bigint[]) => bigint;
div: (a: bigint, b: bigint) => bigint;
mod: (a: bigint) => bigint;
inv: (a: bigint) => bigint;
pow: (a: bigint, b: bigint) => bigint;
squ: (a: bigint) => bigint;
root: (a: bigint) => bigint;
}
/**
* 素域
*
* Prime Field
*
* @param {bigint} p - 素数 / prime number
*/
declare function GF(p: bigint): GFUtils;
/**
* 二元扩域
*
* Binary Field
*
* @param {number} m - 次数 / degree
* @param {bigint} IP - 不可约多项式 / irreducible polynomial
*/
declare function GF2(m: bigint, IP: bigint): GFUtils;
type ECPoint = AffinePoint | JacobianPoint | LDPoint;
/**
* 仿射坐标系的点
*
* Affine Coordinate Point
*/
interface AffinePoint {
type: 'affine';
isInfinity: boolean;
x: bigint;
y: bigint;
}
/**
* 雅可比坐标系的点
*
* Jacobian Coordinate Point
*/
interface JacobianPoint {
type: 'jacobian';
isInfinity: boolean;
x: bigint;
y: bigint;
z: bigint;
}
/**
* 洛佩兹-达哈布坐标系的点
*
* López-Dahab Coordinate Point
*/
interface LDPoint {
type: 'ld';
isInfinity: boolean;
x: bigint;
y: bigint;
z: bigint;
}
/**
* 坐标系转换接口
*
* Coordinate System Conversion Interface
*/
interface CSUtils {
/**
* 雅可比坐标系 -> 仿射坐标系
*
* Jacobian Coordinate System to Affine Coordinate System
*/
toAffine: {
(P: ECPoint): AffinePoint;
(P: undefined): AffinePoint;
};
/**
* 仿射坐标系 -> 雅可比坐标系 (bigint)
*
* Affine Coordinate System to Jacobian Coordinate System (bigint)
*/
toJacobian: {
(P: JacobianPoint): JacobianPoint;
(P: AffinePoint, Z?: bigint): JacobianPoint;
(P: undefined): JacobianPoint;
};
/**
* 洛佩兹-达哈布坐标系 -> 仿射坐标系
*
* López-Dahab Coordinate System to Affine Coordinate System
*/
toLD: {
(P: LDPoint): LDPoint;
(P: AffinePoint, Z?: bigint): LDPoint;
(P: undefined): LDPoint;
};
}
/**
* TODO: 修改曲线参数的接口
*
* 使用这个数据库的格式: https://neuromancer.sk/std/
*
* 1. 更加通用的接口
* 2. 根据三项式基或五项式基优化二元扩域的运算和接口
*/
interface PointAddition<P> {
/**
* 椭圆曲线点加法
*
* Elliptic Curve Point Addition
*/
(A: P, B: P): P;
}
interface PointMultiplication<P> {
/**
* 椭圆曲线点乘法
*
* Elliptic Curve Point Multiplication
*/
(P: P, k: bigint | Uint8Array): P;
}
interface ECBase {
/**
* 域运算
*
* Field Operations
*/
field: GFUtils;
/**
* 坐标系工具
*
* Coordinate System Tools
*/
cs: CSUtils;
/**
* 椭圆曲线点加法 (仿射坐标系)
*
* Elliptic Curve Point Addition (Affine Coordinate System)
*/
_addPoint: (A: AffinePoint, B: AffinePoint) => AffinePoint;
/**
* 椭圆曲线点乘法 (仿射坐标系)
*
* Elliptic Curve Point Multiplication (Affine Coordinate System)
*/
_mulPoint: (P: AffinePoint, k: bigint | Uint8Array) => AffinePoint;
/**
* 仿射点转换为字节串
*
* Convert Affine Point to Byte String
*
* @param {boolean} [compress=false] - 是否压缩 / Whether to compress
*/
PointToU8: (point: AffinePoint, compress?: boolean) => U8;
/**
* 字节串转换为仿射点
*
* Convert Byte String to Point
*/
U8ToPoint: (buffer: Uint8Array) => AffinePoint;
/**
* 判断公钥是否合法
*
* Determine if the public key is legal
*/
isLegalPK: (Q: AffinePoint) => boolean;
/**
* 判断私钥是否合法
*
* Determine if the private key is legal
*/
isLegalSK: (d: bigint | Uint8Array) => boolean;
}
interface ECJacobian extends ECBase {
catalyst: 'jacobian';
addPoint: PointAddition<JacobianPoint>;
mulPoint: PointMultiplication<JacobianPoint>;
}
interface ECLópezDahab extends ECBase {
catalyst: 'ld';
addPoint: PointAddition<LDPoint>;
mulPoint: PointMultiplication<LDPoint>;
}
/**
* 椭圆曲线参数
*
* Elliptic Curve Parameters
*/
interface ECParams {
/** Coefficient a */
readonly a: bigint;
/** Coefficient b */
readonly b: bigint;
/** Base point */
readonly G: Readonly<AffinePoint>;
/** Order */
readonly n: bigint;
/** co-factor */
readonly h: bigint;
}
/**
* 素域椭圆曲线参数
*
* Prime Field Elliptic Curve Parameters
*/
interface FpECParams extends ECParams {
/** Prime */
readonly p: bigint;
}
/**
* 素域 Weierstrass 椭圆曲线参数
*
* Prime Field Weierstrass Elliptic Curve Parameters
*
* y^2 = x^3 + ax + b
*/
interface FpWECParams extends FpECParams {
type: 'Weierstrass';
}
/**
* 素域 Montgomery 椭圆曲线参数
*
* Prime Field Montgomery Elliptic Curve Parameters
*
* b * y^2 = x^3 + a * x^2 + x
*/
interface FpMECParams extends FpECParams {
type: 'Montgomery';
}
/**
* 二元扩域椭圆曲线参数
*
* Binary Field Elliptic Curve Parameters
*/
interface FbECParams extends ECParams {
/** Degree of the reduction polynomial */
readonly m: bigint;
/** Irreducible polynomial */
readonly IP: bigint;
}
/**
* 二元扩域 伪随机 椭圆曲线参数
*
* Binary Field Pseudo-Random Elliptic Curve Parameters
*
* y^2 + xy = x^3 + ax^2 + b
*/
interface FbPECParams extends FbECParams {
type: 'Pseudo-Random';
}
/**
* 二元扩域 Koblitz 椭圆曲线参数
*
* Binary Field Koblitz Elliptic Curve Parameters
*
* y^2 + xy = x^3 + ax^2 + b
*/
interface FbKECParams extends FbECParams {
type: 'Koblitz';
}
interface ECPublicKey {
/** 椭圆曲线公钥 / Elliptic Curve Public Key */
readonly Q: Readonly<AffinePoint>;
}
interface ECPrivateKey {
/** 椭圆曲线私钥 / Elliptic Curve Private Key */
readonly d: bigint;
}
interface ECKeyPair extends ECPrivateKey, ECPublicKey {
}
interface ECDH {
/**
* @param {ECPrivateKey} s_key - 己方私钥 / Self Private Key
* @param {ECPublicKey} p_key - 对方公钥 / Counterparty Public Key
*/
(s_key: ECPrivateKey, p_key: ECPublicKey): AffinePoint;
}
interface ECMQV {
/**
* @param {ECKeyPair} u1 - 己方密钥对 / Self Key Pair
* @param {ECKeyPair} u2 - 己方临时密钥对 / Self Temporary Key Pair
* @param {ECPublicKey} v1 - 对方公钥 / Counterparty Public Key
* @param {ECPublicKey} v2 - 对方临时公钥 / Counterparty Temporary Public Key
*/
(u1: ECKeyPair, u2: ECKeyPair, v1: ECPublicKey, v2: ECPublicKey): AffinePoint;
}
interface ECDSASignature {
/** 临时公钥 / Temporary Public Key */
r: bigint;
/** 签名值 / Signature Value */
s: bigint;
}
interface ECDSA {
/**
* @param {Digest} [hash=sha256] - 摘要函数 / Digest Function
*/
(hash?: Digest): {
/**
* @param {ECPrivateKey} s_key - 签名方私钥 / Signer's Private Key
* @param {Uint8Array} M - 消息 / Message
*/
sign: (s_key: ECPrivateKey, M: Uint8Array) => ECDSASignature;
/**
* @param {ECPublicKey} p_key - 签名方公钥 / Signer's Public Key
* @param {Uint8Array} M - 消息 / Message
*/
verify: (p_key: ECPublicKey, M: Uint8Array, signature: ECDSASignature) => boolean;
};
}
interface IVBlockCipher extends BlockCipherInfo {
(K: Uint8Array, iv: Uint8Array): ReturnType<BlockCipher>;
}
interface ECIESConfig {
/** 分组密码算法 / Block Cipher Algorithm (default: AES-256-GCM) */
cipher?: IVBlockCipher;
/** 密钥哈希函数 / Key Hash Function (default: HMAC-SHA-256) */
mac?: KeyHash;
/** 密钥派生函数 / Key Derivation Function (default: ANSI-X9.63-KDF with SHA-256) */
kdf?: KDF;
/** 附加数据1 / Additional Data 1 (default: empty) */
S1?: Uint8Array;
/** 附加数据2 / Additional Data 2 (default: empty) */
S2?: Uint8Array;
/** 初始化向量 / Initialization Vector (default: Uint8Array(cipher.BLOCK_SIZE)) */
iv?: Uint8Array;
}
interface ECIESCiphertext {
/** 临时公钥 / Temporary Public Key */
R: ECPublicKey;
/** 密文 / Ciphertext */
C: Uint8Array;
/** 校验值 / Check Value */
D: Uint8Array;
}
interface ECIESEncrypt {
/**
* 椭圆曲线集成加密算法
*
* Elliptic Curve Integrated Encryption Scheme
*
* @param {ECPublicKey} p_key - 接收方公钥 / Recipient's Public Key
* @param {Uint8Array} M - 明文 / Plaintext
*/
(p_key: ECPublicKey, M: Uint8Array): ECIESCiphertext;
}
interface ECIESDecrypt {
/**
* 椭圆曲线集成解密算法
*
* Elliptic Curve Integrated Decryption Scheme
*
* @param {ECPrivateKey} s_key - 接收方私钥 / Recipient's Private Key
* @param {ECIESCiphertext} C - 密文 / Ciphertext
*/
(s_key: ECPrivateKey, C: ECIESCiphertext): U8;
}
interface ECIES {
/**
* @param {IVBlockCipher} [config.cipher] - 分组密码算法 / Block Cipher Algorithm (default: AES-256-GCM)
* @param {KeyHash} [config.mac] - 密钥哈希函数 / Key Hash Function (default: HMAC-SHA-256)
* @param {KDF} [config.kdf] - 密钥派生函数 / Key Derivation Function (default: ANSI-X9.63-KDF with SHA-256)
* @param {Uint8Array} [config.S1] - 附加数据1 / Additional Data 1 (default: empty)
* @param {Uint8Array} [config.S2] - 附加数据2 / Additional Data 2 (default: empty)
* @param {Uint8Array} [config.iv] - 初始化向量 / Initialization Vector (default: Uint8Array(cipher.BLOCK_SIZE))
*/
(config?: ECIESConfig): {
encrypt: ECIESEncrypt;
decrypt: ECIESDecrypt;
};
}
/**
* 椭圆曲线密码学
*
* Elliptic Curve Crypto
*
* @template P - 点类型 / Point Type
* @template C - 曲线参数类型 / Curve Parameters Type
*/
interface ECCBase {
/**
* 生成椭圆曲线密钥
*
* Generate Elliptic Curve Key
*/
gen: {
/** 生成密钥对 / Generate Key Pair */
(type?: 'key_pair'): ECKeyPair;
/** 生成私钥 / Generate Private Key */
(type: 'private_key'): ECPrivateKey;
/** 生成公钥 / Generate Public Key */
(type: 'public_key', s_key: ECPrivateKey): ECKeyPair;
};
/**
* 椭圆曲线迪菲-赫尔曼, 密钥协商算法
*
* Elliptic Curve Diffie-Hellman Key Agreement Algorithm
*/
dh: ECDH;
/**
* 椭圆曲线余因子迪菲-赫尔曼, 密钥协商算法
*
* Elliptic Curve Co-factor Diffie-Hellman Key Agreement Algorithm
*/
cdh: ECDH;
/**
* 椭圆曲线梅内泽斯-奎-范斯通密钥协商算法
*
* Elliptic Curve Menezes-Qu-Vanstone Key Agreement Algorithm
*/
mqv: ECMQV;
/**
* 椭圆曲线数字签名
*
* Elliptic Curve Digital Signature Algorithm
*/
dsa: ECDSA;
/**
* 椭圆曲线集成加密算法
*
* Elliptic Curve Integrated Encryption Scheme
*/
ies: ECIES;
}
interface ECCFpWeierstrass extends ECCBase {
parameters: FpWECParams;
utils: ECJacobian;
}
interface ECCFpMontgomery extends ECCBase {
parameters: FpMECParams;
utils: ECJacobian;
}
interface ECCFbPseudoRandom extends ECCBase {
parameters: FbPECParams;
utils: ECLópezDahab;
}
interface ECCFbKoblitz extends ECCBase {
parameters: FbKECParams;
utils: ECLópezDahab;
}
/**
* 定义 ECIES 配置
*
* Define ECIES Configuration
*/
declare function defineECIES(config?: ECIESConfig): {
cipher: IVBlockCipher;
mac: KeyHash;
kdf: KDF;
S1: Uint8Array<ArrayBufferLike>;
S2: Uint8Array<ArrayBufferLike>;
iv: Uint8Array<ArrayBufferLike>;
};
declare function ECC(curve: FpWECParams): ECCFpWeierstrass;
declare function ECC(curve: FpMECParams): ECCFpMontgomery;
declare function ECC(curve: FbPECParams): ECCFbPseudoRandom;
declare function ECC(curve: FbKECParams): ECCFbKoblitz;
interface X25519PrivateKey<T = bigint | Uint8Array> {
/** 私钥 / Private Key */
d: T;
}
interface X25519PublicKey<T = bigint | Uint8Array> {
/** 公钥 / Public Key */
Q: T;
}
interface X25519KeyPair<T = bigint | Uint8Array> extends X25519PrivateKey<T>, X25519PublicKey<T> {
}
interface X448PrivateKey<T = bigint | Uint8Array> extends X25519PrivateKey<T> {
}
interface X448PublicKey<T = bigint | Uint8Array> extends X25519PublicKey<T> {
}
interface X448KeyPair<T = bigint | Uint8Array> extends X25519KeyPair<T> {
}
interface X25519 {
/**
* 生成 x25519 椭圆曲线密钥
*
* Generate x25519 Elliptic Curve Key
*/
gen: {
/** 生成密钥对 / Generate Key Pair */
(type?: 'key_pair'): X25519KeyPair<U8>;
/** 生成私钥 / Generate Private Key */
(type: 'private_key'): X25519PrivateKey<U8>;
/** 生成公钥 / Generate Public Key */
(type: 'public_key', s_key: X25519PrivateKey): X25519KeyPair<U8>;
};
/**
* x25519 椭圆曲线密钥协商算法
*
* x25519 Elliptic Curve Diffie-Hellman Key Agreement Algorithm
*/
dh: {
/**
* @param {X25519PrivateKey} s_key - 己方私钥 / Self Private Key
* @param {X25519PublicKey} p_key - 对方公钥 / Counterparty Public Key
*/
(s_key: X25519PrivateKey, p_key: X25519PublicKey): U8;
};
}
interface X448 {
/**
* 生成 x448 椭圆曲线密钥
*
* Generate x448 Elliptic Curve Key
*/
gen: {
/** 生成密钥对 / Generate Key Pair */
(type?: 'key_pair'): X448KeyPair<U8>;
/** 生成私钥 / Generate Private Key */
(type: 'private_key'): X448PrivateKey<U8>;
/** 生成公钥 / Generate Public Key