micro-key-producer
Version:
Produces secure passwords & keys for WebCrypto, SSH, PGP, SLIP10, OTP and many others
373 lines • 14.5 kB
TypeScript
import * as P from 'micro-packed';
/** Byte-array alias used across the PGP helpers. */
export type Bytes = Uint8Array;
/**
* RFC 4880 multi-precision integer coder.
* @example
* Encode one RFC 4880 multi-precision integer.
* ```ts
* import { mpi } from 'micro-key-producer/pgp.js';
* mpi.encode(1n);
* ```
*/
export declare const mpi: P.CoderType<bigint>;
/**
* Opaque MPI coder used by OpenPGP secret-key packets.
* @example
* Encode one opaque MPI for an OpenPGP secret-key packet.
* ```ts
* import { opaquempi } from 'micro-key-producer/pgp.js';
* opaquempi.encode(new Uint8Array([1, 2]));
* ```
*/
export declare const opaquempi: P.CoderType<Uint8Array>;
/**
* ASN.1 OID coder without DER tag/length wrappers.
* @example
* Encode one ASN.1 object identifier without DER tag and length bytes.
* ```ts
* import { oid } from 'micro-key-producer/pgp.js';
* oid.encode('1.3.6.1.4.1.11591.15.1');
* ```
*/
export declare const oid: P.CoderType<string>;
/**
* OpenPGP packet-length coder.
* @example
* Encode one OpenPGP packet length.
* ```ts
* import { PacketLen } from 'micro-key-producer/pgp.js';
* PacketLen.encode(191);
* ```
*/
export declare const PacketLen: P.CoderType<number>;
/** Supported OpenPGP public-key packet algorithms. */
export type PubKeyPacketAlgo = P.Values<{
EdDSA: {
TAG: 'EdDSA';
data: P.StructInput<{
curve: any;
pub: any;
}>;
};
ECDH: {
TAG: 'ECDH';
data: P.StructInput<{
curve: any;
pub: any;
params: any;
}>;
};
}>;
/**
* OpenPGP public-key packet coder.
* @example
* Encode one Ed25519 OpenPGP public-key packet.
* ```ts
* import { PubKeyPacket } from 'micro-key-producer/pgp.js';
* import { ed25519 } from '@noble/curves/ed25519.js';
* import { bytesToNumberBE } from '@noble/curves/utils.js';
* import { concatBytes } from '@noble/hashes/utils.js';
* const secretKey = ed25519.utils.randomSecretKey();
* PubKeyPacket.encode({
* created: 0,
* algo: {
* TAG: 'EdDSA',
* data: {
* curve: 'ed25519',
* pub: bytesToNumberBE(concatBytes(Uint8Array.of(0x40), ed25519.getPublicKey(secretKey))),
* },
* },
* });
* ```
*/
export declare const PubKeyPacket: P.CoderType<P.StructInput<{
version: undefined;
created: number;
algo: PubKeyPacketAlgo;
}>>;
type PacketData = P.StructInput<{
enc: any;
S2K: any;
iv: any;
secret: any;
}>;
declare const SecretKeyPacket: P.CoderType<P.StructInput<{
pub: P.StructInput<{
version: undefined;
created: number;
algo: PubKeyPacketAlgo;
}>;
type: P.Values<{
plain: {
TAG: 'plain';
data: P.StructInput<{
secret: any;
}>;
};
encrypted: {
TAG: 'encrypted';
data: PacketData;
};
encrypted2: {
TAG: 'encrypted2';
data: PacketData;
};
}>;
}>>;
type SecretKeyType = P.UnwrapCoder<typeof SecretKeyPacket>;
/**
* OpenPGP packet-stream coder.
* @example
* Encode a short sequence of OpenPGP packets into the binary stream format.
* ```ts
* import { Stream } from 'micro-key-producer/pgp.js';
* Stream.encode([{ TAG: 'userId', data: 'alice@example.com' }]);
* ```
*/
export declare const Stream: P.CoderType<any[]>;
/**
* Decrypts the secret scalar from a PGP secret-key packet.
* @param password - Secret-key passphrase.
* @param key - Parsed secret-key packet.
* @returns Secret scalar as a bigint.
* @throws If the packet uses unsupported encryption or fails checksum validation. {@link Error}
* @example
* Decrypt the secret scalar stored inside an armored private key packet.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { decodeSecretKey, getKeys, privArmor } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* const [packet] = privArmor.decode(getKeys(seed, 'alice@example.com', 'password').privateKey);
* decodeSecretKey('password', packet.data);
* ```
*/
export declare function decodeSecretKey(password: string, key: SecretKeyType): bigint;
/**
* ASCII armor for PGP public key blocks.
* @example
* Decode the armored public block that `getKeys()` produces.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeys, pubArmor } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* pubArmor.decode(getKeys(seed, 'alice@example.com').publicKey);
* ```
*/
export declare const pubArmor: P.Coder<any[], string>;
/**
* ASCII armor for PGP private key blocks.
* @example
* Decode the armored private block back into OpenPGP packets.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeys, privArmor } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* privArmor.decode(getKeys(seed, 'alice@example.com').privateKey);
* ```
*/
export declare const privArmor: P.Coder<any[], string>;
/**
* ASCII armor for detached PGP signatures.
* @example
* Decode an armored detached signature back into its packet list.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeyId, sigArmor, signDetached } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* sigArmor.decode(signDetached(seed, 'hello', getKeyId(seed).fingerprint));
* ```
*/
export declare const sigArmor: P.Coder<any[], string>;
/**
* Formats the armored public half of a deterministic OpenPGP keypair.
* @param edPriv - Ed25519 signing private key.
* @param cvPriv - Curve25519 encryption private key.
* @param user - OpenPGP user ID string.
* @param createdAt - Key creation time as UNIX timestamp in seconds.
* @returns ASCII-armored public key block.
* @throws If the supplied key material or timestamp cannot be encoded as OpenPGP packets. {@link Error}
* @example
* Build the public OpenPGP block from the signing key and its Curve25519 subkey.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { formatPublic } from 'micro-key-producer/pgp.js';
* import { ed25519 } from '@noble/curves/ed25519.js';
* const seed = randomBytes(32);
* const cvPriv = ed25519.utils.getExtendedPublicKey(seed).head;
* formatPublic(seed, cvPriv, 'alice@example.com', 0);
* ```
*/
export declare function formatPublic(edPriv: Bytes, cvPriv: Bytes, user: string, createdAt: number): string;
/**
* Formats the armored private half of a deterministic OpenPGP keypair.
* @param edPriv - Ed25519 signing private key.
* @param cvPriv - Curve25519 encryption private key.
* @param user - OpenPGP user ID string.
* @param password - Optional secret-key passphrase.
* @param createdAt - Key creation time as UNIX timestamp in seconds.
* @param edSalt - Salt for the signing secret-key S2K envelope.
* @param edIV - IV for the signing secret-key S2K envelope.
* @param cvSalt - Salt for the encryption subkey S2K envelope.
* @param cvIV - IV for the encryption subkey S2K envelope.
* @returns ASCII-armored private key block.
* @throws If the supplied key material, timestamp, or secret-key envelope parameters are invalid. {@link Error}
* @example
* Build the password-protected private key block and matching encryption subkey.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { formatPrivate } from 'micro-key-producer/pgp.js';
* import { ed25519 } from '@noble/curves/ed25519.js';
* const seed = randomBytes(32);
* const cvPriv = ed25519.utils.getExtendedPublicKey(seed).head;
* formatPrivate(seed, cvPriv, 'alice@example.com', 'password');
* ```
*/
export declare function formatPrivate(edPriv: Bytes, cvPriv: Bytes, user: string, password?: string, createdAt?: number, edSalt?: Uint8Array, edIV?: Uint8Array, cvSalt?: Uint8Array, cvIV?: Uint8Array): string;
/**
* Derives PGP key ID from the private key.
* PGP key depends on its date of creation.
* @param edPrivKey - Ed25519 signing private key.
* @param createdAt - Key creation time as UNIX timestamp in seconds.
* @returns Public packets plus fingerprint and key ID.
* @throws If the key material or creation time cannot be encoded as OpenPGP packets. {@link Error}
* @example
* Recompute the OpenPGP fingerprint and key ID for an existing signing key.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeyId } from 'micro-key-producer/pgp.js';
* getKeyId(randomBytes(32)).keyId;
* ```
*/
export declare function getKeyId(edPrivKey: Bytes, createdAt?: number): {
edPubPacket: {
readonly created: number;
readonly algo: {
readonly TAG: 'EdDSA';
readonly data: {
readonly curve: 'ed25519';
readonly pub: bigint;
};
};
};
fingerprint: string;
keyId: string;
cvPubPacket: {
readonly created: number;
readonly algo: {
readonly TAG: 'ECDH';
readonly data: {
readonly curve: 'curve25519';
readonly pub: bigint;
readonly params: {
readonly hash: 'sha256';
readonly encryption: 'aes128';
};
};
};
};
};
/**
* Derives PGP private key, public key and fingerprint.
* Uses S2K KDF, which means it's slow. Use `getKeyId` if you want to get key id in a fast way.
* PGP key depends on its date of creation.
* NOTE: gpg: warning: lower 3 bits of the secret key are not cleared
* happens even for keys generated with GnuPG 2.3.6, because check looks at item as Opaque MPI, when it is just MPI. See {@link https://dev.gnupg.org/rGdbfb7f809b89cfe05bdacafdb91a2d485b9fe2e0 | the GnuPG bugtracker note}.
* @param privKey - Ed25519 signing private key.
* @param user - OpenPGP user ID string.
* @param password - Optional secret-key passphrase.
* @param createdAt - Key creation time as UNIX timestamp in seconds.
* @returns Armored keypair plus fingerprint data.
* @throws If the key material or creation time cannot be encoded as OpenPGP packets. {@link Error}
* @example
* Derive the armored OpenPGP keypair from one Ed25519 private key.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeys } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* getKeys(seed, 'alice@example.com').publicKey;
* ```
*/
export declare function getKeys(privKey: Bytes, user: string, password?: string, createdAt?: number): {
keyId: string;
fingerprint: string;
privateKey: string;
publicKey: string;
};
/**
* Default export for deterministic OpenPGP key derivation.
* @param privKey - Ed25519 signing private key.
* @param user - OpenPGP user ID string.
* @param password - Optional secret-key passphrase.
* @param createdAt - Key creation time as UNIX timestamp in seconds.
* @returns Armored keypair plus fingerprint data.
* @throws If the key material or creation time cannot be encoded as OpenPGP packets. {@link Error}
* @example
* Use the default export when you want the full armored OpenPGP bundle in one call.
* ```ts
* import getKeys from 'micro-key-producer/pgp.js';
* import { randomBytes } from '@noble/hashes/utils.js';
* const seed = randomBytes(32);
* getKeys(seed, 'alice@example.com').publicKey;
* ```
*/
export default getKeys;
/**
* Creates an armored detached OpenPGP signature.
* @param privateKey - Ed25519 signing private key.
* @param data - Binary or text payload to sign.
* @param fingerprint - Full OpenPGP fingerprint of the signing key.
* @param signedAt - Signature creation time as UNIX timestamp in seconds.
* @returns ASCII-armored detached signature.
* @throws If the detached payload cannot be encoded or signed as OpenPGP data. {@link Error}
* @example
* Create a detached signature you can send alongside the original text payload.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeyId, signDetached } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* const { fingerprint } = getKeyId(seed);
* signDetached(seed, 'hello', fingerprint);
* ```
*/
export declare function signDetached(privateKey: Bytes, data: Bytes | string, fingerprint: string, signedAt?: number): string;
/**
* Verifies an armored detached OpenPGP signature with an Ed25519 public key.
* @param publicKey - Ed25519 public key bytes.
* @param signature - ASCII-armored detached signature.
* @param data - Original binary or text payload.
* @param fingerprint - Optional expected signer fingerprint.
* @returns Whether the detached signature verifies.
* @throws If the signature packet, payload type, or signer fingerprint is invalid. {@link Error}
* @example
* Verify the detached signature with the signer's Ed25519 public key and fingerprint.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeyId, signDetached, verifyDetached } from 'micro-key-producer/pgp.js';
* import { ed25519 } from '@noble/curves/ed25519.js';
* const privateKey = randomBytes(32);
* const { fingerprint } = getKeyId(privateKey);
* const signature = signDetached(privateKey, 'hello', fingerprint);
* verifyDetached(ed25519.getPublicKey(privateKey), signature, 'hello', fingerprint);
* ```
*/
export declare function verifyDetached(publicKey: Bytes, signature: string, data: Bytes | string, fingerprint?: string): boolean;
/**
* This is a basic parsing to extract enough information to signDetached signatures.
* Supports keys generated by us or PGP (ed25519 only + default opts), doesn't extract ECDH (x25519) keys.
* @param privateKey - ASCII-armored private key block.
* @param getPassword - Optional callback used to fetch the secret-key passphrase.
* @returns Parsed secret key bytes and identifying metadata.
* @throws If the armored packet layout, password callback, or decoded key material is invalid. {@link Error}
* @example
* Parse an armored secret key back into raw key bytes and OpenPGP metadata.
* ```ts
* import { randomBytes } from '@noble/hashes/utils.js';
* import { getKeys, parsePrivateKey } from 'micro-key-producer/pgp.js';
* const seed = randomBytes(32);
* const { privateKey } = getKeys(seed, 'alice@example.com');
* parsePrivateKey(privateKey).then(({ keyId }) => keyId);
* ```
*/
export declare function parsePrivateKey(privateKey: string, getPassword?: () => Promise<string>): Promise<any>;
//# sourceMappingURL=pgp.d.ts.map