Cryptography API

GenerateRandomBytes Random

Generates random bytes.

Signature

export function GenerateRandomBytes(length: number): Uint8Array;

Example

import { GenerateRandomBytes } from "@fast-china/utils";

const result = GenerateRandomBytes(16);

Input

Input	Type	Required / default	Description
length	number	Required	Safe integer from 0 to 65,536.

Returns

Value	Type	Description
result	Uint8Array	New Uint8Array.

FixedTimeEquals Compare

Compares two byte arrays without early exit.

Signature

export function FixedTimeEquals(left: Uint8Array, right: Uint8Array): boolean;

Example

import { FixedTimeEquals } from "@fast-china/utils";

const result = FixedTimeEquals(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]));

Input

Input	Type	Required / default	Description
left	Uint8Array	Required	First byte sequence.
right	Uint8Array	Required	Second byte sequence.

Returns

Value	Type	Description
result	boolean	true if lengths and every byte match.

MD5Encrypt Hash

Computes an MD5 digest as lowercase hexadecimal text.

Signature

export function MD5Encrypt(value: string): string;

Example

import { MD5Encrypt } from "@fast-china/utils";

const result = MD5Encrypt("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text.

Returns

Value	Type	Description
result	string	32-character lowercase hexadecimal digest.

SHA1Encrypt Hash

Computes a SHA-1 digest as uppercase hexadecimal text.

Signature

export function SHA1Encrypt(value: string): string;

Example

import { SHA1Encrypt } from "@fast-china/utils";

const result = SHA1Encrypt("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text.

Returns

Value	Type	Description
result	string	40-character uppercase hexadecimal digest.

SHA256Bytes Hash

Computes a SHA-256 digest.

Signature

export async function SHA256Bytes(value: string): Promise<Uint8Array>;

Example

import { SHA256Bytes } from "@fast-china/utils";

const result = await SHA256Bytes("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 string or raw bytes.

Returns

Value	Type	Description
result	Promise<Uint8Array>	32-byte digest.

SHA256Encrypt Hash

Computes SHA-256 and formats it as hexadecimal.

Signature

export async function SHA256Encrypt(value: string): Promise<string>;

Example

import { SHA256Encrypt } from "@fast-china/utils";

const result = await SHA256Encrypt("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 string or raw bytes.

Returns

Value	Type	Description
result	Promise<string>	64-character uppercase hexadecimal text.

SHA384Bytes Hash

Computes a SHA-384 digest.

Signature

export async function SHA384Bytes(value: string): Promise<Uint8Array>;

Example

import { SHA384Bytes } from "@fast-china/utils";

const result = await SHA384Bytes("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes.

Returns

Value	Type	Description
result	Promise<Uint8Array>	48-byte digest.

SHA384Encrypt Hash

Computes SHA-384 and formats it as hexadecimal.

Signature

export async function SHA384Encrypt(value: string): Promise<string>;

Example

import { SHA384Encrypt } from "@fast-china/utils";

const result = await SHA384Encrypt("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes.

Returns

Value	Type	Description
result	Promise<string>	96-character uppercase hexadecimal digest.

SHA512Bytes Hash

Computes a SHA-512 digest.

Signature

export async function SHA512Bytes(value: string): Promise<Uint8Array>;

Example

import { SHA512Bytes } from "@fast-china/utils";

const result = await SHA512Bytes("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes.

Returns

Value	Type	Description
result	Promise<Uint8Array>	64-byte digest.

SHA512Encrypt Hash

Computes SHA-512 and formats it as hexadecimal.

Signature

export async function SHA512Encrypt(value: string): Promise<string>;

Example

import { SHA512Encrypt } from "@fast-china/utils";

const result = await SHA512Encrypt("Fast 文档");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes.

Returns

Value	Type	Description
result	Promise<string>	128-character uppercase hexadecimal digest.

HMACSHA256Encrypt MAC

Authenticates text with HMAC-SHA-256 and returns a hexadecimal tag.

Signature

export async function HMACSHA256Encrypt(value: string, key: string): Promise<string>;

Example

import { HMACSHA256Encrypt } from "@fast-china/utils";

const result = await HMACSHA256Encrypt("Fast 文档", "secret-key");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes to authenticate.
key	string	Required	Nonempty UTF-8 key text or raw key bytes.

Returns

Value	Type	Description
result	Promise<string>	64-character lowercase hexadecimal authentication tag.

HMACSHA384Encrypt MAC

Authenticates text or bytes with HMAC-SHA-384 and returns a hexadecimal tag.

Signature

export async function HMACSHA384Encrypt(value: string, key: string): Promise<string>;

Example

import { HMACSHA384Encrypt } from "@fast-china/utils";

const result = await HMACSHA384Encrypt("Fast 文档", "secret-key");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes to authenticate.
key	string	Required	Nonempty UTF-8 key text or raw key bytes.

Returns

Value	Type	Description
result	Promise<string>	96-character lowercase hexadecimal authentication tag.

HMACSHA512Encrypt MAC

Authenticates text or bytes with HMAC-SHA-512 and returns a hexadecimal tag.

Signature

export async function HMACSHA512Encrypt(value: string, key: string): Promise<string>;

Example

import { HMACSHA512Encrypt } from "@fast-china/utils";

const result = await HMACSHA512Encrypt("Fast 文档", "secret-key");

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes to authenticate.
key	string	Required	Nonempty UTF-8 key text or raw key bytes.

Returns

Value	Type	Description
result	Promise<string>	128-character lowercase hexadecimal authentication tag.

PBKDF2SHA256 Derive

Derives a key from a password using PBKDF2-HMAC-SHA-256.

Signature

export async function PBKDF2SHA256(password: string, salt: Uint8Array, iterations = defaultPbkdf2Iterations, outputLength = 32): Promise<Uint8Array>;

Example

import { PBKDF2SHA256 } from "@fast-china/utils";

const result = await PBKDF2SHA256("correct horse battery staple", new Uint8Array([1, 2, 3, 4]));

Input

Input	Type	Required / default	Description
password	string	Required	Password of 1 to 1,024 UTF-8 bytes.
salt	Uint8Array	Required	Salt of at least 8 bytes.
iterations	unknown	Optional; defaults to defaultPbkdf2Iterations	Iteration count from 100,000 to 5,000,000.
outputLength	unknown	Optional; defaults to 32	Output length from 1 to 1,024 bytes.

Returns

Value	Type	Description
result	Promise<Uint8Array>	Derived key of the requested length.

HashPasswordPBKDF2SHA256 Password

Generates a persistable PBKDF2-HMAC-SHA-256 password hash with random salt.

Signature

export async function HashPasswordPBKDF2SHA256(password: string, iterations = defaultPbkdf2Iterations): Promise<string>;

Example

import { HashPasswordPBKDF2SHA256 } from "@fast-china/utils";

const result = await HashPasswordPBKDF2SHA256("correct horse battery staple");

Input

Input	Type	Required / default	Description
password	string	Required	Password of 1 to 1,024 UTF-8 bytes.
iterations	unknown	Optional; defaults to defaultPbkdf2Iterations	Iteration count from 100,000 to 5,000,000.

Returns

Value	Type	Description
result	Promise<string>	Self-describing string containing the version, iteration count, 16-byte random salt, and 32-byte derived key.

VerifyPasswordPBKDF2SHA256 Verify

Verifies a generated password hash.

Signature

export async function VerifyPasswordPBKDF2SHA256(password: string, passwordHash: string): Promise<boolean>;

Example

import { VerifyPasswordPBKDF2SHA256 } from "@fast-china/utils";

const storedHash = await HashPasswordPBKDF2SHA256("correct horse battery staple");
const result = await VerifyPasswordPBKDF2SHA256("correct horse battery staple", storedHash);

Input

Input	Type	Required / default	Description
password	string	Required	Password to verify.
passwordHash	string	Required	Self-describing PBKDF2-HMAC-SHA-256 password hash.

Returns

Value	Type	Description
result	Promise<boolean>	true for a valid format and matching password; false for malformed hashes or incorrect passwords.

HKDFSHA256 Derive

Derives context-separated key material using RFC 5869 HKDF-SHA-256.

Signature

export async function HKDFSHA256(
	inputKeyMaterial: Uint8Array,
	salt: Uint8Array = new Uint8Array(),
	info: Uint8Array = new Uint8Array(),
	outputLength = 32
): Promise<Uint8Array>;

Example

import { HKDFSHA256 } from "@fast-china/utils";

const result = await HKDFSHA256(new Uint8Array([1, 2, 3]), new Uint8Array(), new Uint8Array(), 32);

Input

Input	Type	Required / default	Description
inputKeyMaterial	Uint8Array	Required	Input key material, such as a raw ECDH shared secret.
salt	Uint8Array	Optional; defaults to new Uint8Array()	Optional salt; empty values use RFC 5869 zero-salt semantics.
info	Uint8Array	Optional; defaults to new Uint8Array()	Application, protocol, and key-purpose context.
outputLength	unknown	Optional; defaults to 32	Output length from 1 to 8,160 bytes.

Returns

Value	Type	Description
result	Promise<Uint8Array>	Derived key bound to salt and info.

AESEncrypt Encrypt

Encrypts UTF-8 text with AES-256 block encryption.

Signature

export function AESEncrypt(
	dataStr: string,
	key: string,
	vector: string,
	cipherMode: AesCipherMode = "CBC",
	paddingMode: AesPaddingMode = "PKCS7"
): string | null;

Example

import { AESEncrypt } from "@fast-china/utils";

const result = AESEncrypt("Fast", "0123456789abcdef0123456789abcdef", "0123456789abcdef");

Input

Input	Type	Required / default	Description
dataStr	string	Required	UTF-8 plaintext; blank text returns null.
key	string	Required	Nonblank key text.
vector	string	Required	Nonblank initialization-vector text; ECB still requires this parameter to match the .NET signature.
cipherMode	AesCipherMode	Optional; defaults to "CBC"	AES block mode; defaults to CBC.
paddingMode	AesPaddingMode	Optional; defaults to "PKCS7"	AES padding; defaults to PKCS7.

Returns

Value	Type	Description
result	string | null	Base64 ciphertext; returns null if input, key, or IV is blank.

AESDecrypt Decrypt

Decrypts Base64 block ciphertext with AES-256.

Signature

export function AESDecrypt(
	dataStr: string,
	key: string,
	vector: string,
	cipherMode: AesCipherMode = "CBC",
	paddingMode: AesPaddingMode = "PKCS7"
): DecodedText | null;

Example

import { AESDecrypt, AESEncrypt } from "@fast-china/utils";

const ciphertext = AESEncrypt("Fast", "0123456789abcdef0123456789abcdef", "0123456789abcdef");
const result = ciphertext === null ? null : AESDecrypt(ciphertext, "0123456789abcdef0123456789abcdef", "0123456789abcdef");

Input

Input	Type	Required / default	Description
dataStr	string	Required	Base64 ciphertext; blank text returns null.
key	string	Required	Key text used for encryption.
vector	string	Required	Initialization-vector text used for encryption.
cipherMode	AesCipherMode	Optional; defaults to "CBC"	AES block mode; defaults to CBC.
paddingMode	AesPaddingMode	Optional; defaults to "PKCS7"	AES padding; defaults to PKCS7.

Returns

Value	Type	Description
result	DecodedText | null	Raw UTF-8 string usable directly or through .parseJson<Value>(); returns null if input, key, or IV is blank.

AESEncryptAuthenticated Encrypt

Normalizes a text key with SHA-256, then authenticates and encrypts UTF-8 text using AES-256-GCM.

Signature

export async function AESEncryptAuthenticated(plaintext: string, key: string): Promise<string>;

Example

import { AESEncryptAuthenticated } from "@fast-china/utils";

const result = await AESEncryptAuthenticated("Fast", "0123456789abcdef0123456789abcdef");

Input

Input	Type	Required / default	Description
plaintext	string	Required	UTF-8 text to encrypt.
key	string	Required	Nonempty UTF-8 key text, internally normalized to a 32-byte SHA-256 digest.

Returns

Value	Type	Description
result	Promise<string>	Base64-encoded v1 authenticated AES-GCM payload.

AESDecryptAuthenticated Decrypt

Decrypts and authenticates payloads generated by the compatible encryptor or .NET AESEncryptAuthenticated.

Signature

export async function AESDecryptAuthenticated(payload: string, key: string): Promise<DecodedText>;

Example

import { AESDecryptAuthenticated, AESEncryptAuthenticated } from "@fast-china/utils";

const storedPayload = await AESEncryptAuthenticated("Fast", "0123456789abcdef0123456789abcdef");
const result = await AESDecryptAuthenticated(storedPayload, "0123456789abcdef0123456789abcdef");

Input

Input	Type	Required / default	Description
payload	string	Required	Base64-encoded v1 AES-GCM binary payload.
key	string	Required	Nonempty UTF-8 key text used for encryption.

Returns

Value	Type	Description
result	Promise<DecodedText>	Raw UTF-8 string usable directly or through explicit .parseJson<Value>().

AESEncryptWithPassword Encrypt

Derives a key with PBKDF2-HMAC-SHA-256, then authenticates and encrypts UTF-8 text with AES-256-GCM.

Signature

export async function AESEncryptWithPassword(plaintext: string, password: string, iterations = defaultPbkdf2Iterations): Promise<string>;

Example

import { AESEncryptWithPassword } from "@fast-china/utils";

const result = await AESEncryptWithPassword("Fast", "correct horse battery staple");

Input

Input	Type	Required / default	Description
plaintext	string	Required	Raw text without JSON inference; at most 8 MiB after UTF-8 encoding.
password	string	Required	Secret passphrase of 1 to 1024 UTF-8 bytes.
iterations	unknown	Optional; defaults to defaultPbkdf2Iterations	PBKDF2 work factor; defaults to 600,000.

Returns

Value	Type	Description
result	Promise<string>	Authenticated ciphertext string; repeated calls with identical input produce different results.

AESDecryptWithPassword Decrypt

Decrypts a generated v1 authenticated payload.

Signature

export async function AESDecryptWithPassword(payload: string, password: string): Promise<DecodedText>;

Example

import { AESDecryptWithPassword, AESEncryptWithPassword } from "@fast-china/utils";

const storedPayload = await AESEncryptWithPassword("Fast", "correct horse battery staple");
const result = await AESDecryptWithPassword(storedPayload, "correct horse battery staple");

Input

Input	Type	Required / default	Description
payload	string	Required	Unmodified v1 payload, at most approximately 16 MiB of text.
password	string	Required	Passphrase used for encryption.

Returns

Value	Type	Description
result	Promise<DecodedText>	Raw UTF-8 string usable directly or through explicit .parseJson<Value>().

GenerateRSAKeyPair Keypair

Generates a PEM key pair usable with both RSA-OAEP/SHA-256 and RSA-PSS/SHA-256.

Signature

export async function GenerateRSAKeyPair(modulusLength = 2048): Promise<PemKeyPair>;

Example

import { GenerateRSAKeyPair } from "@fast-china/utils";

const result = await GenerateRSAKeyPair(2048);

Input

Input	Type	Required / default	Description
modulusLength	unknown	Optional; defaults to 2048	RSA modulus size in bits; defaults to 2,048 and must be a multiple of 256 no smaller than 2,048.

Returns

Value	Type	Description
result	Promise<PemKeyPair>	PEM pair containing an unencrypted PKCS#8 private key and SubjectPublicKeyInfo public key.

RSAEncryptOAEP Encrypt

Encrypts UTF-8 text with an RSA-OAEP/SHA-256 public key.

Signature

export async function RSAEncryptOAEP(plaintext: string, publicKeyPem: string): Promise<string>;

Example

import { GenerateRSAKeyPair, RSAEncryptOAEP } from "@fast-china/utils";

const { publicKey } = await GenerateRSAKeyPair();
const result = await RSAEncryptOAEP("Fast", publicKey);

Input

Input	Type	Required / default	Description
plaintext	string	Required	UTF-8 plaintext within the RSA-OAEP modulus size limit.
publicKeyPem	string	Required	SubjectPublicKeyInfo PEM public key.

Returns

Value	Type	Description
result	Promise<string>	Base64-encoded RSA ciphertext.

RSADecryptOAEP Decrypt

Decrypts Base64 ciphertext with an RSA-OAEP/SHA-256 private key.

Signature

export async function RSADecryptOAEP(ciphertext: string, privateKeyPem: string): Promise<DecodedText>;

Example

import { GenerateRSAKeyPair, RSADecryptOAEP, RSAEncryptOAEP } from "@fast-china/utils";

const { privateKey, publicKey } = await GenerateRSAKeyPair();
const storedCiphertext = await RSAEncryptOAEP("Fast", publicKey);
const result = await RSADecryptOAEP(storedCiphertext, privateKey);

Input

Input	Type	Required / default	Description
ciphertext	string	Required	Base64-encoded RSA ciphertext.
privateKeyPem	string	Required	Unencrypted PKCS#8 PEM private key.

Returns

Value	Type	Description
result	Promise<DecodedText>	Raw UTF-8 string usable directly or through explicit .parseJson<Value>().

RSASignPSS Sign

Signs text or bytes with an RSA-PSS/SHA-256 private key.

Signature

export async function RSASignPSS(value: string, privateKeyPem: string): Promise<string>;

Example

import { GenerateRSAKeyPair, RSASignPSS } from "@fast-china/utils";

const { privateKey } = await GenerateRSAKeyPair();
const result = await RSASignPSS("Fast", privateKey);

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes to sign.
privateKeyPem	string	Required	Unencrypted PKCS#8 PEM private key.

Returns

Value	Type	Description
result	Promise<string>	Base64-encoded RSA-PSS signature with a fixed 32-byte salt.

RSAVerifyPSS Verify

Verifies a Base64 signature with an RSA-PSS/SHA-256 public key.

Signature

export async function RSAVerifyPSS(value: string, signature: string, publicKeyPem: string): Promise<boolean>;

Example

import { GenerateRSAKeyPair, RSASignPSS, RSAVerifyPSS } from "@fast-china/utils";

const { privateKey, publicKey } = await GenerateRSAKeyPair();
const storedSignature = await RSASignPSS("Fast", privateKey);
const result = await RSAVerifyPSS("Fast", storedSignature, publicKey);

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes used when signing.
signature	string	Required	Base64-encoded RSA-PSS signature.
publicKeyPem	string	Required	SubjectPublicKeyInfo PEM public key.

Returns

Value	Type	Description
result	Promise<boolean>	true if the signature matches the content and public key.

GenerateECDSAKeyPair Keypair

Generates an ECDSA PEM signing key pair.

Signature

export async function GenerateECDSAKeyPair(namedCurve: EcNamedCurve = "P-256"): Promise<PemKeyPair>;

Example

import { GenerateECDSAKeyPair } from "@fast-china/utils";

const result = await GenerateECDSAKeyPair("P-256");

Input

Input	Type	Required / default	Description
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve: P-256, P-384, or P-521.

Returns

Value	Type	Description
result	Promise<PemKeyPair>	PEM pair containing an unencrypted PKCS#8 private key and SubjectPublicKeyInfo public key.

ECDSASign Sign

Signs text or bytes with an ECDSA private key.

Signature

export async function ECDSASign(value: string, privateKeyPem: string, namedCurve: EcNamedCurve = "P-256"): Promise<string>;

Example

import { ECDSASign, GenerateECDSAKeyPair } from "@fast-china/utils";

const { privateKey } = await GenerateECDSAKeyPair();
const result = await ECDSASign("Fast", privateKey);

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes to sign.
privateKeyPem	string	Required	Unencrypted EC PKCS#8 PEM private key.
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve used by the private key.

Returns

Value	Type	Description
result	Promise<string>	Base64-encoded IEEE P1363 ECDSA signature.

ECDSAVerify Verify

Verifies a Base64 signature with an ECDSA public key.

Signature

export async function ECDSAVerify(value: string, signature: string, publicKeyPem: string, namedCurve: EcNamedCurve = "P-256"): Promise<boolean>;

Example

import { ECDSASign, ECDSAVerify, GenerateECDSAKeyPair } from "@fast-china/utils";

const { privateKey, publicKey } = await GenerateECDSAKeyPair();
const storedSignature = await ECDSASign("Fast", privateKey);
const result = await ECDSAVerify("Fast", storedSignature, publicKey);

Input

Input	Type	Required / default	Description
value	string	Required	UTF-8 text or raw bytes used when signing.
signature	string	Required	Base64-encoded IEEE P1363 ECDSA signature.
publicKeyPem	string	Required	EC SubjectPublicKeyInfo PEM public key.
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve used by the public key.

Returns

Value	Type	Description
result	Promise<boolean>	true if signature, content, public key, and curve match.

GenerateECDHKeyPair Keypair

Generates an ECDH PEM key-agreement pair.

Signature

export async function GenerateECDHKeyPair(namedCurve: EcNamedCurve = "P-256"): Promise<PemKeyPair>;

Example

import { GenerateECDHKeyPair } from "@fast-china/utils";

const result = await GenerateECDHKeyPair("P-256");

Input

Input	Type	Required / default	Description
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve: P-256, P-384, or P-521.

Returns

Value	Type	Description
result	Promise<PemKeyPair>	PEM pair containing an unencrypted PKCS#8 private key and SubjectPublicKeyInfo public key.

DeriveECDHSecret Derive

Derives a shared secret from the local ECDH private key and peer's public key.

Signature

export async function DeriveECDHSecret(privateKeyPem: string, publicKeyPem: string, namedCurve: EcNamedCurve = "P-256"): Promise<Uint8Array>;

Example

import { DeriveECDHSecret, GenerateECDHKeyPair } from "@fast-china/utils";

const own = await GenerateECDHKeyPair();
const peer = await GenerateECDHKeyPair();
const result = await DeriveECDHSecret(own.privateKey, peer.publicKey);

Input

Input	Type	Required / default	Description
privateKeyPem	string	Required	Local unencrypted EC PKCS#8 PEM private key.
publicKeyPem	string	Required	Peer's EC SubjectPublicKeyInfo PEM public key.
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve used by both key pairs.

Returns

Value	Type	Description
result	Promise<Uint8Array>	Raw ECDH shared secret with the curve field length.

DeriveECDHKeySHA256 Derive

Derives a shared key with SHA-256 after ECDH.

Signature

export async function DeriveECDHKeySHA256(privateKeyPem: string, publicKeyPem: string, namedCurve: EcNamedCurve = "P-256"): Promise<Uint8Array>;

Example

import { DeriveECDHKeySHA256, GenerateECDHKeyPair } from "@fast-china/utils";

const own = await GenerateECDHKeyPair();
const peer = await GenerateECDHKeyPair();
const result = await DeriveECDHKeySHA256(own.privateKey, peer.publicKey);

Input

Input	Type	Required / default	Description
privateKeyPem	string	Required	Local unencrypted EC PKCS#8 PEM private key.
publicKeyPem	string	Required	Peer's EC SubjectPublicKeyInfo PEM public key.
namedCurve	EcNamedCurve	Optional; defaults to "P-256"	NIST curve used by both key pairs.

Returns

Value	Type	Description
result	Promise<Uint8Array>	32-byte shared key.