cmsnamespacenamespace cmsCMS (RFC 5652) AuthEnvelopedData (RFC 5083), the S/MIME (RFC 8551) form a message is encrypted in, on Web Crypto and the kernel's DER alone (commons 0001-crypto FR-005). Content is encrypted once with AES-256-GCM (RFC 5084), and its key is encrypted to each recipient's RSA public key with RSAES-OAEP, SHA-256 and MGF1 with SHA-256 (RFC 8017, RFC 4055), named by the issuer and serial number of the recipient's X.509 certificate (RFC 5280). The holder of a private key opens it again. PEM is read and written, and a certificate is read for what encryption needs (issuer, serial, key, addresses, validity, key usage). The content key and nonce come from the caller (cmsKeys with a source of random bytes), so the kernel has no effect. Taken from Stolos's src/archon/export/smime.ts (emailed exports); opening, PEM writing and typed errors are new, and the mail headers stay in Stolos.
import { authEnveloped, cmsKeys, readCertificate, readPem } from "./cms.ts";
const pem = readPem(certificateText, "CERTIFICATE");
if (pem.kind === "ok") {
const cert = readCertificate(pem.value[0] ?? new Uint8Array());
if (cert.kind === "ok") {
const der = await authEnveloped(content, [cert.value], cmsKeys((n) => crypto.getRandomValues(new Uint8Array(n))));
}
}cmsnamespacenamespace cmscms.OIDconstno test imports itconst OID: { readonly data: "1.2.840.113549.1.7.1"; readonly authEnvelopedData: "1.2.840.113549.1.9.16.1.23"; readonly a… (481 characters)const OID: { readonly data: "1.2.840.113549.1.7.1"; readonly authEnvelopedData: "1.2.840.113549.1.9.16.1.23"; readonly aes256gcm: "2.16.840.1.101.3.4.1.46"; readonly rsaEncryption: "1.2.840.113549.1.1.1"; readonly rsaesOaep: "1.2.840.113549.1.1.7"; readonly mgf1: "1.2.840.113549.1.1.8"; readonly sha256: "2.16.840.1.101.3.4.2.1"; readonly commonName: "2.5.4.3"; readonly emailAddress: "1.2.840.113549.1.9.1"; readonly subjectAltName: "2.5.29.17"; readonly keyUsage: "2.5.29.15"; }The object identifiers used.
cms.CmsErrortypeno test imports ittype CmsError =
| { readonly kind: "pem"; readonly message: string }
| { readonly kind: "certificate"; readonly message: string }
| { readonly kind: "unsupported"; readonly message: string }
| { readonly kind: "structure"; readonly message: string }
| { readonly kind: "no-recipient"; readonly message: string }
| { readonly kind: "decrypt"; readonly message: string };Why CMS or a certificate could not be read, written or opened.
cms.formatCmsErrorfunctionno test imports itfunction formatCmsError(e: CmsError): stringA CMS error as one sentence.
cms.readPemfunctionno test imports itfunction readPem(text: string, label: string): Result<readonly Uint8Array<ArrayBufferLike>[], CmsError>Every PEM block of a label (CERTIFICATE, PRIVATE KEY) in a text, as DER; none found, or a block that is not base64, is an error.
cms.toPemfunctionno test imports itfunction toPem(der: Uint8Array<ArrayBufferLike>, label: string): stringDER as a PEM block of a label, base64 in 64-column lines.
cms.Certificatetypeno test imports ittype Certificate = {
/** The issuer's Name, its DER exactly as in the certificate. */
readonly issuer: Uint8Array;
… (1048 characters)type Certificate = {
/** The issuer's Name, its DER exactly as in the certificate. */
readonly issuer: Uint8Array;
/** The serial number's INTEGER element, exactly as in the certificate. */
readonly serial: Uint8Array;
/** The serial number in hexadecimal. */
readonly serialHex: string;
/** The SubjectPublicKeyInfo, DER. */
readonly spki: Uint8Array;
/** The public key's algorithm, as an OID. */
readonly keyAlgorithm: string;
/** The subject's common name, where it has one. */
readonly commonName: string | undefined;
/** The addresses it names (subjectAltName rfc822Name and the subject's emailAddress), in lower case. */
readonly emails: readonly string[];
/** When it starts being valid, where its time can be read. */
readonly notBefore: Date | undefined;
/** When it stops being valid, where its time can be read. */
readonly notAfter: Date | undefined;
/** Whether it may encrypt keys: true where it has no keyUsage extension, else its keyEncipherment bit. */
readonly keyEncipherment: boolean;
};What encryption and a person need from a recipient's X.509 certificate.
cms.readCertificatefunctionno test imports itfunction readCertificate(der: Uint8Array<ArrayBufferLike>): Result<Certificate, CmsError>An X.509 certificate read for what encryption needs, or why it is not one this reader takes.
cms.CertificateProblemtypeno test imports ittype CertificateProblem =
| { readonly kind: "not-rsa"; readonly algorithm: string }
| { readonly kind: "not-yet-valid"; readonly from: Date }
| { readonly kind: "expired"; readonly on: Date }
| { readonly kind: "signing-only" }
| { readonly kind: "other-address"; readonly names: readonly string[] };Why a certificate cannot encrypt to an address now.
cms.certificateProblemfunctionno test imports itfunction certificateProblem(c: Certificate, address: string, now: Date): CertificateProblem | undefinedWhy a certificate cannot be used to encrypt to address at now, or undefined where it can.
cms.oaepSha256functionno test imports itfunction oaepSha256(): Uint8Array<ArrayBufferLike>RSAES-OAEP with SHA-256 and MGF1 with SHA-256, as an AlgorithmIdentifier (RFC 4055 §4.1).
cms.CmsKeystypeno test imports ittype CmsKeys = { readonly contentKey: Uint8Array; readonly nonce: Uint8Array };The fresh secrets of one message: a 32-byte AES-256 content key and a 12-byte GCM nonce.
cms.cmsKeysfunctionno test imports itfunction cmsKeys(random: (length: number) => Uint8Array<ArrayBufferLike>): CmsKeysFresh secrets from a source of random bytes, such as (n) => crypto.getRandomValues(new Uint8Array(n)).
cms.authEnvelopedfunctionno test imports itfunction authEnveloped(content: Uint8Array<ArrayBufferLike>, recipients: readonly Certificate[], keys: CmsKeys): Promise<Result<Uint8Array<ArrayBufferLike>, CmsError>>A CMS ContentInfo holding AuthEnvelopedData, as DER: content encrypted with AES-256-GCM, its key encrypted to every recipient with RSA-OAEP SHA-256. No recipient, a recipient whose key is not RSA, or keys of the wrong size are errors.
cms.isOaepSha256functionno test imports itfunction isOaepSha256(t: Tlv): booleanWhether an AlgorithmIdentifier is RSAES-OAEP with SHA-256, MGF1 with SHA-256 and the default label, however its NULLs are written.
cms.openAuthEnvelopedfunctionno test imports itfunction openAuthEnveloped(der: Uint8Array<ArrayBufferLike>, cert: Certificate, privateKey: CryptoKey): Promise<Result<Uint8Array<ArrayBufferLike>, CmsError>>The content of an AuthEnvelopedData, opened by the recipient whose certificate is cert with its RSA-OAEP SHA-256 private key; or why it cannot be: not this structure, no RecipientInfo for this certificate, or a key or tag that does not decrypt (the content was changed).
OIDconstconst OID: { readonly data: "1.2.840.113549.1.7.1"; readonly authEnvelopedData: "1.2.840.113549.1.9.16.1.23"; readonly a… (481 characters)const OID: { readonly data: "1.2.840.113549.1.7.1"; readonly authEnvelopedData: "1.2.840.113549.1.9.16.1.23"; readonly aes256gcm: "2.16.840.1.101.3.4.1.46"; readonly rsaEncryption: "1.2.840.113549.1.1.1"; readonly rsaesOaep: "1.2.840.113549.1.1.7"; readonly mgf1: "1.2.840.113549.1.1.8"; readonly sha256: "2.16.840.1.101.3.4.2.1"; readonly commonName: "2.5.4.3"; readonly emailAddress: "1.2.840.113549.1.9.1"; readonly subjectAltName: "2.5.29.17"; readonly keyUsage: "2.5.29.15"; }The object identifiers used.
CmsErrortypeno test imports ittype CmsError =
| { readonly kind: "pem"; readonly message: string }
| { readonly kind: "certificate"; readonly message: string }
| { readonly kind: "unsupported"; readonly message: string }
| { readonly kind: "structure"; readonly message: string }
| { readonly kind: "no-recipient"; readonly message: string }
| { readonly kind: "decrypt"; readonly message: string };Why CMS or a certificate could not be read, written or opened.
formatCmsErrorfunctionno test imports itfunction formatCmsError(e: CmsError): stringA CMS error as one sentence.
readPemfunctionfunction readPem(text: string, label: string): Result<readonly Uint8Array<ArrayBufferLike>[], CmsError>Every PEM block of a label (CERTIFICATE, PRIVATE KEY) in a text, as DER; none found, or a block that is not base64, is an error.
toPemfunctionfunction toPem(der: Uint8Array<ArrayBufferLike>, label: string): stringDER as a PEM block of a label, base64 in 64-column lines.
Certificatetypetype Certificate = {
/** The issuer's Name, its DER exactly as in the certificate. */
readonly issuer: Uint8Array;
… (1048 characters)type Certificate = {
/** The issuer's Name, its DER exactly as in the certificate. */
readonly issuer: Uint8Array;
/** The serial number's INTEGER element, exactly as in the certificate. */
readonly serial: Uint8Array;
/** The serial number in hexadecimal. */
readonly serialHex: string;
/** The SubjectPublicKeyInfo, DER. */
readonly spki: Uint8Array;
/** The public key's algorithm, as an OID. */
readonly keyAlgorithm: string;
/** The subject's common name, where it has one. */
readonly commonName: string | undefined;
/** The addresses it names (subjectAltName rfc822Name and the subject's emailAddress), in lower case. */
readonly emails: readonly string[];
/** When it starts being valid, where its time can be read. */
readonly notBefore: Date | undefined;
/** When it stops being valid, where its time can be read. */
readonly notAfter: Date | undefined;
/** Whether it may encrypt keys: true where it has no keyUsage extension, else its keyEncipherment bit. */
readonly keyEncipherment: boolean;
};What encryption and a person need from a recipient's X.509 certificate.
readCertificatefunctionfunction readCertificate(der: Uint8Array<ArrayBufferLike>): Result<Certificate, CmsError>An X.509 certificate read for what encryption needs, or why it is not one this reader takes.
CertificateProblemtypeno test imports ittype CertificateProblem =
| { readonly kind: "not-rsa"; readonly algorithm: string }
| { readonly kind: "not-yet-valid"; readonly from: Date }
| { readonly kind: "expired"; readonly on: Date }
| { readonly kind: "signing-only" }
| { readonly kind: "other-address"; readonly names: readonly string[] };Why a certificate cannot encrypt to an address now.
certificateProblemfunctionfunction certificateProblem(c: Certificate, address: string, now: Date): CertificateProblem | undefinedWhy a certificate cannot be used to encrypt to address at now, or undefined where it can.
oaepSha256functionfunction oaepSha256(): Uint8Array<ArrayBufferLike>RSAES-OAEP with SHA-256 and MGF1 with SHA-256, as an AlgorithmIdentifier (RFC 4055 §4.1).
CmsKeystypeno test imports ittype CmsKeys = { readonly contentKey: Uint8Array; readonly nonce: Uint8Array };The fresh secrets of one message: a 32-byte AES-256 content key and a 12-byte GCM nonce.
cmsKeysfunctionfunction cmsKeys(random: (length: number) => Uint8Array<ArrayBufferLike>): CmsKeysFresh secrets from a source of random bytes, such as (n) => crypto.getRandomValues(new Uint8Array(n)).
authEnvelopedfunctionfunction authEnveloped(content: Uint8Array<ArrayBufferLike>, recipients: readonly Certificate[], keys: CmsKeys): Promise<Result<Uint8Array<ArrayBufferLike>, CmsError>>A CMS ContentInfo holding AuthEnvelopedData, as DER: content encrypted with AES-256-GCM, its key encrypted to every recipient with RSA-OAEP SHA-256. No recipient, a recipient whose key is not RSA, or keys of the wrong size are errors.
isOaepSha256functionfunction isOaepSha256(t: Tlv): booleanWhether an AlgorithmIdentifier is RSAES-OAEP with SHA-256, MGF1 with SHA-256 and the default label, however its NULLs are written.
openAuthEnvelopedfunctionfunction openAuthEnveloped(der: Uint8Array<ArrayBufferLike>, cert: Certificate, privateKey: CryptoKey): Promise<Result<Uint8Array<ArrayBufferLike>, CmsError>>The content of an AuthEnvelopedData, opened by the recipient whose certificate is cert with its RSA-OAEP SHA-256 private key; or why it cannot be: not this structure, no RecipientInfo for this certificate, or a key or tag that does not decrypt (the content was changed).