micro-key-producer
Version:
Produces secure passwords & keys for WebCrypto, SSH, PGP, SLIP10, OTP and many others
663 lines • 19.4 kB
TypeScript
import * as P from 'micro-packed';
import type { PKCS8Key as DERPKCS8Key } from './convert.ts';
import { CurveOID, DERUtils } from './convert.ts';
type KnownCurve = keyof typeof CurveOID;
/** Supported signing or key-agreement curve name. */
export type CertCurve = KnownCurve | `OID:${string}`;
/** Parsed PEM block with decoded DER bytes. */
export type PemBlock = {
/** PEM block tag between `BEGIN` and `END`. */
tag: string;
/** Base64 payload exactly as it appeared in the PEM block. */
b64: string;
/** Decoded DER bytes for the PEM payload. */
der: Uint8Array;
};
/** Parsed PKCS#8 attribute entry. */
export type Pkcs8Attr = {
/** Attribute OID. */
oid: string;
/** Raw ASN.1 values carried by the attribute. */
values: Uint8Array[];
};
type RSAPrivateKey = P.UnwrapCoder<typeof DERUtils.RSAPrivateKey>;
/** Decoded X.509 certificate. */
export type Cert = P.UnwrapCoder<typeof CERTUtils.Certificate>;
type KeyBase = {
pem: string;
der: Uint8Array;
attributes?: Pkcs8Attr[];
};
/** Parsed private-key PEM/DER bundle. */
export type PrivateKey = KeyBase & {
key: DERPKCS8Key;
rsa?: RSAPrivateKey;
};
/** Leaf certificate, private key, and optional chain used for signing. */
export type SigningPem = {
/** Leaf certificate used as the signer. */
leaf: Cert;
/** Private key matching the leaf certificate. */
key: PrivateKey;
/** Optional issuer chain sent alongside the leaf. */
chain: Cert[];
};
/** CMS verification options. */
export type CmsVerifyOpts = {
/** Validation time in UNIX milliseconds. */
time?: number;
/** Allow BER normalization before decoding. */
allowBER?: boolean;
/**
* Whether to verify CMS and certificate signatures for supported algorithms.
* When `false`, structure, path, and attribute validation still runs.
*/
checkSignatures?: boolean;
/** Intended verification purpose such as S/MIME or code signing. */
purpose?: 'any' | 'smime' | 'codeSigning';
/** Optional trust anchors or intermediates used for path building. */
chain?: (string | Uint8Array | Cert)[];
};
/** Result of CMS verification. */
export type CmsVerify = {
/** Signature algorithm OID from the CMS SignerInfo. */
signatureOid: string;
/** Parsed signer certificate. */
signer: Cert;
/** Whether signed attributes were present and validated. */
signedAttrs: boolean;
/** Parsed certificate path from signer toward issuer or root candidates. */
chain: Cert[];
};
/** Detached CMS payload and signature pair. */
export type CmsDetached = {
/** Original detached content bytes. */
content: Uint8Array;
/** Detached CMS SignedData blob. */
signature: Uint8Array;
/** Certificates bundled with the signature. */
certs: Cert[];
};
/** CMS signing options. */
export type CmsSignOpts = BEROpts & {
createdTs?: number;
extraEntropy?: boolean | Uint8Array;
smimeCapabilities?: string[];
messageDigest?: Uint8Array;
digestAlgorithm?: string;
digestAlgorithmParams?: 'absent' | 'null';
signatureAlgorithm?: string;
};
/** Decoded certificate extension data. */
export type CertExt = {
/** Extension OID. */
oid: string;
/** Whether the extension is marked critical. */
critical: boolean;
/** Subject Key Identifier extension. */
ski?: Uint8Array;
/** Basic Constraints extension. */
basic?: {
ca?: boolean;
pathLen?: bigint;
};
/** Key Usage extension bit string. */
keyUsage?: {
unused: number;
bytes: Uint8Array;
};
/** Extended Key Usage extension. */
eku?: {
list: string[];
};
/** Subject Alternative Name extension. */
san?: {
list: CertGeneralName[];
};
/** Authority Key Identifier extension. */
aki?: {
keyIdentifier?: Uint8Array;
authorityCertIssuer?: {
list: CertGeneralName[];
};
authorityCertSerialNumber?: bigint;
};
/** Authority Information Access extension. */
aia?: {
list: {
method: string;
location: CertGeneralName;
}[];
};
/** Proxy Certificate Information extension. */
proxyCertInfo?: {
pathLen?: bigint;
policy: {
language: string;
policy?: string;
};
};
/** TLS Feature extension. */
tlsFeature?: {
list: bigint[];
};
/** Signed Certificate Timestamps extension. */
sct?: {
version: number;
logID: Uint8Array;
timestamp: bigint;
extensions: string;
hash: number;
signatureAlgorithm: number;
signature: Uint8Array;
}[];
/** CRL Distribution Points extension. */
crlDistributionPoints?: {
list: {
distributionPoint?: CertDistributionPointName;
reasons?: {
unused: number;
bytes: Uint8Array;
};
cRLIssuer?: {
list: CertGeneralName[];
};
}[];
};
/** Certificate Policies extension. */
policies?: {
list: {
policy: string;
qualifiers?: {
list: CertPolicyQualifier[];
};
}[];
};
/** Name Constraints extension. */
nameConstraints?: {
permitted?: {
list: CertGeneralSubtree[];
};
excluded?: {
list: CertGeneralSubtree[];
};
};
/** Subject Directory Attributes extension. */
subjectDirectoryAttributes?: {
list: {
type: string;
typeName?: string;
values: CertAny[];
}[];
};
/** Private Key Usage Period extension. */
privateKeyUsagePeriod?: {
notBefore?: string;
notAfter?: string;
};
/** Issuer Alternative Name extension. */
issuerAltName?: {
list: CertGeneralName[];
};
/** Issuing Distribution Point extension. */
issuingDistributionPoint?: {
distributionPoint?: CertDistributionPointName;
onlyContainsUserCerts?: boolean;
onlyContainsCACerts?: boolean;
onlySomeReasons?: {
unused: number;
bytes: Uint8Array;
};
indirectCRL?: boolean;
onlyContainsAttributeCerts?: boolean;
};
/** Certificate Issuer extension. */
certificateIssuer?: {
list: CertGeneralName[];
};
/** Policy Mappings extension. */
policyMappings?: {
list: {
issuerDomainPolicy: string;
subjectDomainPolicy: string;
}[];
};
/** Freshest CRL extension. */
freshestCRL?: {
list: {
distributionPoint?: CertDistributionPointName;
reasons?: {
unused: number;
bytes: Uint8Array;
};
cRLIssuer?: {
list: CertGeneralName[];
};
}[];
};
/** Policy Constraints extension. */
policyConstraints?: {
requireExplicitPolicy?: bigint;
inhibitPolicyMapping?: bigint;
};
/** Inhibit Any Policy extension. */
inhibitAnyPolicy?: bigint;
/** QC Statements extension. */
qcStatements?: {
list: {
statementId: string;
statementName?: string;
statementInfo?: CertAny;
}[];
};
/** Subject Information Access extension. */
subjectInfoAccess?: {
list: {
method: string;
location: CertGeneralName;
}[];
};
/** Microsoft certificate type extension. */
msCertType?: CertAny;
};
/** Parsed GeneralName value. */
export type CertGeneralName = {
TAG: 'otherName';
data: {
type: string;
value: TLVNode;
};
} | {
TAG: 'rfc822Name';
data: string;
} | {
TAG: 'dNSName';
data: string;
} | {
TAG: 'x400Address';
data: Uint8Array;
} | {
TAG: 'directoryName';
data: NameCodec;
} | {
TAG: 'ediPartyName';
data: Uint8Array;
} | {
TAG: 'uniformResourceIdentifier';
data: string;
} | {
TAG: 'iPAddress';
data: string;
} | {
TAG: 'registeredID';
data: string;
};
/** Parsed CRL distribution-point name. */
export type CertDistributionPointName = {
TAG: 'fullName';
data: {
list: CertGeneralName[];
};
} | {
TAG: 'nameRelativeToCRLIssuer';
data: Array<{
oid: string;
value: NameValue;
}>;
};
/** Parsed reason flags from CRL-related extensions. */
export type CertReasonFlags = {
/** End-entity private key was compromised. */
keyCompromise: boolean;
/** CA private key was compromised. */
cACompromise: boolean;
/** Subject affiliation changed. */
affiliationChanged: boolean;
/** Certificate was superseded. */
superseded: boolean;
/** Subject ceased operation. */
cessationOfOperation: boolean;
/** Certificate was placed on hold. */
certificateHold: boolean;
/** Privileges were withdrawn. */
privilegeWithdrawn: boolean;
/** Attribute authority key was compromised. */
aACompromise: boolean;
};
/** Parsed GeneralSubtree value. */
export type CertGeneralSubtree = {
/** Base GeneralName covered by the subtree. */
base: CertGeneralName;
/** Minimum subtree depth, when explicitly present. */
minimum?: bigint;
/** Maximum subtree depth, when explicitly present. */
maximum?: bigint;
};
/** Parsed certificate-policy qualifier. */
export type CertPolicyQualifier = {
TAG: 'cps';
data: string;
} | {
TAG: 'userNotice';
data: {
noticeRef?: {
organization: CertText;
numbers: number[];
};
explicitText?: CertText;
};
} | {
TAG: 'unknown';
data: {
oid: string;
value: TLVNode;
};
};
/** Generic ASN.1 tree node used for unsupported extension payloads. */
export type TLVNode = {
/** Raw ASN.1 tag number. */
tag: number;
/** Nested child nodes for constructed values. */
children?: TLVNode[];
/** Hex-encoded payload for primitive values. */
valueHex?: string;
};
/** Decoded text value from certificate fields. */
export type CertText = {
/** Underlying ASN.1 string tag used by the source field. */
tag: 'utf8' | 'ia5' | 'visible' | 'bmp';
/** Decoded text content. */
text: string;
};
/** Best-effort decoded arbitrary ASN.1 value. */
export type CertAny = {
TAG: 'text';
data: NameValue;
} | {
TAG: 'oid';
data: {
oid: string;
name?: string;
};
} | {
TAG: 'int';
data: bigint;
} | {
TAG: 'bool';
data: boolean;
} | {
TAG: 'time';
data: {
TAG: 'utc' | 'generalized';
data: string;
};
} | {
TAG: 'octet';
data: Uint8Array;
} | {
TAG: 'raw';
data: TLVNode;
};
/**
* Extracts all PEM blocks from a text blob.
* @param text - Text containing one or more PEM blocks.
* @returns Parsed PEM blocks with decoded DER bytes.
* @example
* Extract all PEM blocks from a text blob.
* ```ts
* import { pemBlocks } from 'micro-key-producer/x509.js';
* pemBlocks(`-----BEGIN DATA-----
* AA==
* -----END DATA-----`);
* ```
*/
export declare const pemBlocks: (text: string) => PemBlock[];
/** Supported certificate/key curves. */
export type Curve = 'P-256' | 'P-384' | 'P-521' | 'brainpoolP256r1' | 'brainpoolP384r1' | 'brainpoolP512r1';
type EdKind = 'Ed25519' | 'Ed448';
type BERDoc = ReturnType<typeof DERUtils.BER.decode>;
type BEROpts = {
allowBER?: boolean;
};
type ASN1Tagged<T> = P.CoderType<T> & {
tagByte: number;
tagBytes: number[];
constructed: number;
inner: P.CoderType<T>;
};
declare const Time: P.CoderType<{
TAG: 'utc';
data: string;
} | {
TAG: 'generalized';
data: string;
}>;
declare const X509Time: {
decode: (der: Uint8Array) => number;
encode: (ts: number) => Uint8Array;
};
type NameValue = {
TAG: 'utf8';
data: string;
} | {
TAG: 'printable';
data: string;
} | {
TAG: 'teletex';
data: string;
} | {
TAG: 'ia5';
data: string;
} | {
TAG: 'bmp';
data: string;
} | {
TAG: 'visible';
data: string;
} | {
TAG: 'numeric';
data: string;
};
type NameCodec = {
rdns: Array<Array<{
oid: string;
value: NameValue;
}>>;
};
type ValidityCodec = {
notBefore: P.UnwrapCoder<typeof Time>;
notAfter: P.UnwrapCoder<typeof Time>;
};
type ExtCodec = {
oid: string;
rest: Uint8Array;
};
type AlgorithmIdentifierCodec = {
algorithm: string;
params: TLVNode | undefined;
};
type TBSCertificateCodec = {
version: bigint | undefined;
serial: bigint;
signature: AlgorithmIdentifierCodec;
issuer: NameCodec;
validity: ValidityCodec;
subject: NameCodec;
spki: {
algorithm: AlgorithmIdentifierCodec;
publicKey: Uint8Array;
};
issuerUniqueID: Uint8Array | undefined;
subjectUniqueID: Uint8Array | undefined;
extensions: {
list: ExtCodec[];
} | undefined;
};
type CertificateCodec = {
tbs: TBSCertificateCodec;
sigAlg: AlgorithmIdentifierCodec;
sig: Uint8Array;
};
declare const PrintableString: ASN1Tagged<string>;
declare const TeletexString: ASN1Tagged<string>;
declare const NumericString: ASN1Tagged<string>;
declare const X509C: {
Name: P.CoderType<NameCodec>;
TBSCertificate: P.CoderType<TBSCertificateCodec>;
Certificate: P.CoderType<CertificateCodec>;
};
type AttributeCodec = {
oid: string;
values: Uint8Array[];
};
type SignerIdentifierCodec = {
TAG: 'issuerSerial';
data: {
issuer: NameCodec;
serial: bigint;
};
} | {
TAG: 'subjectKeyIdentifier';
data: Uint8Array;
};
type SignerInfoCodec = {
version: bigint;
sid: SignerIdentifierCodec;
digestAlg: AlgorithmIdentifierCodec;
signedAttrs: AttributeCodec[] | undefined;
signatureAlg: AlgorithmIdentifierCodec;
signature: Uint8Array;
unsignedAttrs: AttributeCodec[] | undefined;
};
type SignedDataCodec = {
version: bigint;
digestAlgorithms: AlgorithmIdentifierCodec[];
encapContentInfo: {
eContentType: string;
eContent: Uint8Array | undefined;
};
certificates: CMSCertificateChoiceCodec[] | undefined;
crls: CMSRevocationInfoChoiceCodec[] | undefined;
signerInfos: SignerInfoCodec[];
};
type ContentInfoCodec = {
contentType: string;
content: Uint8Array;
};
type CMSCertificateChoiceCodec = {
TAG: 'certificate';
data: P.UnwrapCoder<typeof X509C.Certificate>;
} | {
TAG: 'extendedCertificate';
data: Uint8Array;
} | {
TAG: 'v1AttrCert';
data: Uint8Array;
} | {
TAG: 'v2AttrCert';
data: Uint8Array;
} | {
TAG: 'other';
data: Uint8Array;
};
type CMSRevocationInfoChoiceCodec = {
TAG: 'crl';
data: {
tbsCertList: Uint8Array;
signatureAlgorithm: AlgorithmIdentifierCodec;
signatureValue: Uint8Array;
};
} | {
TAG: 'other';
data: {
format: string;
info: Uint8Array;
};
};
declare const CMSCertificateChoices: P.CoderType<CMSCertificateChoiceCodec>;
declare const CMSRevocationInfoChoice: P.CoderType<CMSRevocationInfoChoiceCodec>;
declare const CMSSignedData: P.CoderType<SignedDataCodec>;
declare const CMSX: {
AlgorithmIdentifier: P.CoderType<AlgorithmIdentifierCodec>;
Attribute: P.CoderType<AttributeCodec>;
SignerInfo: P.CoderType<SignerInfoCodec>;
SignedData: P.CoderType<SignedDataCodec>;
ContentInfo: P.CoderType<ContentInfoCodec>;
};
/**
* Low-level X.509 coders used by the higher-level APIs.
* @example
* Use the low-level coders when you need to encode or decode individual X.509 structures.
* ```ts
* import { CERTUtils } from 'micro-key-producer/x509.js';
* CERTUtils.Name.encode({
* rdns: [[{ oid: '2.5.4.3', value: { TAG: 'utf8', data: 'example.com' } }]],
* });
* ```
*/
export declare const CERTUtils: {
Name: typeof X509C.Name;
TBSCertificate: typeof X509C.TBSCertificate;
Certificate: typeof X509C.Certificate;
};
declare const IPv4: P.CoderType<string>;
declare const IPv6: P.CoderType<string>;
export declare const X509: {
decode: (der: Uint8Array, opts?: BEROpts) => Cert;
encode: (cert: Cert) => Uint8Array;
extensions: (cert: Cert) => CertExt[];
};
type CMSApi = {
decode: (der: Uint8Array, opts?: BEROpts) => P.UnwrapCoder<typeof CMSX.ContentInfo> & {
ber?: BERDoc;
};
encode: (contentInfo: P.UnwrapCoder<typeof CMSX.ContentInfo> & {
ber?: BERDoc;
}) => Uint8Array;
contentType: (der: Uint8Array, opts?: BEROpts) => string;
signed: (der: Uint8Array, opts?: BEROpts) => P.UnwrapCoder<typeof CMSX.SignedData>;
verify: (der: Uint8Array, opts?: CmsVerifyOpts) => CmsVerify;
detach: (der: Uint8Array, opts?: BEROpts) => CmsDetached;
attach: (signature: Uint8Array, content: Uint8Array, opts?: BEROpts) => Uint8Array;
verifyDetached: (signature: Uint8Array, content: Uint8Array, opts?: CmsVerifyOpts) => CmsVerify;
sign: (content: string | Uint8Array, signingCertPem: string, privateKeyPem: string, chainPem?: string, opts?: CmsSignOpts) => Uint8Array;
signDetached: (content: string | Uint8Array, signingCertPem: string, privateKeyPem: string, chainPem?: string, opts?: CmsSignOpts) => Uint8Array;
compact: {
sign: (content: string | Uint8Array, signingCertPem: string, privateKeyPem: string, opts?: Pick<CmsSignOpts, 'createdTs' | 'extraEntropy' | 'smimeCapabilities' | 'messageDigest' | 'digestAlgorithm'>) => Uint8Array;
build: (content: string | Uint8Array, signature: Uint8Array, signingCertPem: string, chainPem?: string, opts?: CmsCompactBuildOpts) => Uint8Array;
};
};
type CmsCompactBuildOpts = Pick<CmsSignOpts, 'createdTs' | 'smimeCapabilities' | 'messageDigest' | 'digestAlgorithm' | 'signatureAlgorithm' | 'digestAlgorithmParams'>;
declare const SMIME_CAPS: {
readonly 'aes256-cbc': "2.16.840.1.101.3.4.1.42";
readonly 'aes192-cbc': "2.16.840.1.101.3.4.1.22";
readonly 'aes128-cbc': "2.16.840.1.101.3.4.1.2";
readonly 'aes256-gcm': "2.16.840.1.101.3.4.1.46";
readonly 'aes192-gcm': "2.16.840.1.101.3.4.1.26";
readonly 'aes128-gcm': "2.16.840.1.101.3.4.1.6";
readonly 'aes256-cfb': "2.16.840.1.101.3.4.1.44";
readonly 'aes192-cfb': "2.16.840.1.101.3.4.1.24";
readonly 'aes128-cfb': "2.16.840.1.101.3.4.1.4";
readonly 'aes256-kw': "2.16.840.1.101.3.4.1.45";
readonly 'aes192-kw': "2.16.840.1.101.3.4.1.25";
readonly 'aes128-kw': "2.16.840.1.101.3.4.1.5";
readonly 'des-ede3-cbc': "1.2.840.113549.3.7";
readonly 'rc2-cbc': "1.2.840.113549.3.2";
readonly 'des-cbc': "1.3.14.3.2.7";
};
export declare const CMS: CMSApi;
export declare const __TEST: {
IPv4: typeof IPv4;
IPv6: typeof IPv6;
PrintableString: typeof PrintableString;
NumericString: typeof NumericString;
TeletexString: typeof TeletexString;
X509Time: typeof X509Time;
CMSCertificateChoices: typeof CMSCertificateChoices;
CMSRevocationInfoChoice: typeof CMSRevocationInfoChoice;
CMSSignedData: typeof CMSSignedData;
SMIME_CAPS: typeof SMIME_CAPS;
keyCurve: (privateKeyPem: string) => CertCurve | EdKind;
};
export {};
//# sourceMappingURL=x509.d.ts.map