IF Commons GitHub

cms

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-crypto FR-005

CMS (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))));
  }
}

Source: commons/crypto/src/cms.ts

11 of 30 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

cmsnamespace
namespace cms
cms.OIDconstno test imports it
const 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 it
type 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 it
function formatCmsError(e: CmsError): string

A CMS error as one sentence.

cms.readPemfunctionno test imports it
function 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 it
function toPem(der: Uint8Array<ArrayBufferLike>, label: string): string

DER as a PEM block of a label, base64 in 64-column lines.

cms.Certificatetypeno test imports it
type 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 it
function 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 it
type 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 it
function certificateProblem(c: Certificate, address: string, now: Date): CertificateProblem | undefined

Why a certificate cannot be used to encrypt to address at now, or undefined where it can.

cms.oaepSha256functionno test imports it
function oaepSha256(): Uint8Array<ArrayBufferLike>

RSAES-OAEP with SHA-256 and MGF1 with SHA-256, as an AlgorithmIdentifier (RFC 4055 §4.1).

cms.CmsKeystypeno test imports it
type 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 it
function cmsKeys(random: (length: number) => Uint8Array<ArrayBufferLike>): CmsKeys

Fresh secrets from a source of random bytes, such as (n) => crypto.getRandomValues(new Uint8Array(n)).

cms.authEnvelopedfunctionno test imports it
function 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 it
function isOaepSha256(t: Tlv): boolean

Whether 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 it
function 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).

OIDconst
const 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

CmsErrortypeno test imports it
type 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 it
function formatCmsError(e: CmsError): string

A CMS error as one sentence.

readPemfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

toPemfunction
function toPem(der: Uint8Array<ArrayBufferLike>, label: string): string

DER as a PEM block of a label, base64 in 64-column lines.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Certificatetype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

readCertificatefunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

CertificateProblemtypeno test imports it
type 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.

certificateProblemfunction
function certificateProblem(c: Certificate, address: string, now: Date): CertificateProblem | undefined

Why a certificate cannot be used to encrypt to address at now, or undefined where it can.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

oaepSha256function
function oaepSha256(): Uint8Array<ArrayBufferLike>

RSAES-OAEP with SHA-256 and MGF1 with SHA-256, as an AlgorithmIdentifier (RFC 4055 §4.1).

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

CmsKeystypeno test imports it
type 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.

cmsKeysfunction
function cmsKeys(random: (length: number) => Uint8Array<ArrayBufferLike>): CmsKeys

Fresh secrets from a source of random bytes, such as (n) => crypto.getRandomValues(new Uint8Array(n)).

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

authEnvelopedfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

isOaepSha256function
function isOaepSha256(t: Tlv): boolean

Whether an AlgorithmIdentifier is RSAES-OAEP with SHA-256, MGF1 with SHA-256 and the default label, however its NULLs are written.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

openAuthEnvelopedfunction
function 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).

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.