IF Commons GitHub

Crypto

0001Draft

0001-crypto · owner if · domain commons

Digests

FR-001checkpassing

Crypto MUST give SHA-256 through Web Crypto as a branded Sha256 (64 lower-case hexadecimal digits), made only by sha256 or the validating sha256Of, with hexadecimal conversion and the reading of SHASUMS256 files.

Enforced (check): .github: cd commons/crypto && bun test suite/ — sha256.test.ts: FIPS 180-2 vectors, hexadecimal round trip, the brand, SHASUMS files

Proved by: crypto/suite/sha256.test.ts

Written in: crypto/src/sha256.ts

Tests: passed: suite/sha256.test.ts bytes to hexadecimal and back are the same bytes; passed: suite/sha256.test.ts a SHASUMS file is read as name to checksum, other lines skipped; passed: suite/sha256.test.ts only 64 hexadecimal digits are a checksum; checksums compare equal only where equal; passed: suite/sha256.test.ts the digests of FIPS 180-2's test vectors

Cited by: sha256, hex, Formats

FR-002checkpassing

Crypto MUST give MD5 (RFC 1321), which Web Crypto lacks, for the protocols that still ask for it (S3's Content-MD5, some ETags), as bytes and hexadecimal, and MUST say in its documentation that it is not for security.

Enforced (check): .github: cd commons/crypto && bun test suite/ — md5.test.ts: RFC 1321's examples

Proved by: crypto/suite/md5.test.ts

Written in: crypto/src/md5.ts

Tests: passed: suite/md5.test.ts a stream is digested as it is read; a digest taken takes no more bytes; passed: suite/md5.test.ts bytes and hexadecimal are the same digest; base64 of it is S3's Content-MD5; passed: suite/md5.test.ts the digest taken a piece at a time, cut anywhere, is the digest of the whole; passed: suite/md5.test.ts the digests of RFC 1321's test suite (appendix A.5); passed: suite/md5.test.ts the lengths around the padding boundary, whole and a byte at a time, give the digests of a

Cited by: md5

Passwords and requests

FR-003checkpassing

Crypto MUST hash a password as glibc's SHA-512 crypt ($6$, Drepper's algorithm, rounds written where they are given and clamped as glibc clamps them, the salt cut to 16 characters) on Web Crypto alone, giving the bytes glibc's crypt(3) gives, and verify a password against such a hash. The salt MUST be given (made from random bytes by the caller), so the kernel has no effect.

Enforced (check): .github: cd commons/crypto && bun test suite/ — graph.test.ts: glibc's own hashes, clamped rounds, verification, random salts from bytes

Proved by: crypto/suite/crypt.test.ts

Written in: crypto/src/crypt.ts

Tests: passed: suite/crypt.test.ts a salt from bytes is of crypt's alphabet, and a password hashed with it verifies; passed: suite/crypt.test.ts SHA-512 crypt gives what glibc's crypt(3) gives, rounds clamped as glibc clamps them

Cited by: crypt, Crypto, Net

FR-004checkpassing

Crypto MUST sign HTTP requests by AWS Signature Version 4 (AWS4-HMAC-SHA256) with HMAC-SHA256 on Web Crypto, from a request's parts or a web Request, the credentials (an access key, its secret and an optional session token), the region, the service and the time given by the caller (the kernel reads no clock): the canonical request (the path normalized and encoded twice except for S3, which keeps it as given and encoded once; the query sorted and encoded by RFC 3986; the headers in lower case, trimmed, sorted and signed with host and x-amz-date), the string to sign, the derived key and the Authorization header, with the payload's SHA-256 (or UNSIGNED-PAYLOAD where asked) also sent as x-amz-content-sha256 where asked and always for S3. Its signatures MUST be those of AWS's published examples.

Enforced (check): .github: cd commons/crypto && bun test suite/ — sigv4.test.ts: AWS's published Signature Version 4 examples, canonical request and string to sign, a web Request signed

Proved by: crypto/suite/sigv4.test.ts

Written in: crypto/src/sigv4.ts

Tests: passed: suite/sigv4.test.ts AWS's get-vanilla example: its canonical request, string to sign, signature and Authorizat; passed: suite/sigv4.test.ts AWS's test suite: the query sorted by its keys, headers trimmed, and POST with and without; passed: suite/sigv4.test.ts a session token is sent and signed, an unsigned payload is said, and a transport's own hea; passed: suite/sigv4.test.ts a web Request is signed as its parts are, its body hashed and kept; passed: suite/sigv4.test.ts paths are normalized and encoded twice, but for S3; queries are sorted and encoded by RFC and 1 more

Cited by: Crypto, sigv4, Net

Envelopes

FR-005checkpassing

Crypto MUST encrypt content as CMS AuthEnvelopedData (RFC 5652, RFC 5083): AES-256-GCM with a 16-byte tag (RFC 5084), the content key encrypted to each recipient's RSA key with RSAES-OAEP, SHA-256 and MGF1 with SHA-256 (RFC 8017, RFC 4055) in a KeyTransRecipientInfo naming the certificate by issuer and serial number; open it with a recipient's private key, accepting SHA-256 parameters written as NULL or absent, and refusing a changed message, a wrong key and a certificate it was not encrypted to with a typed error; read and write PEM; and read an X.509 certificate (RFC 5280) for its issuer, serial, key, addresses, validity and key usage, saying why it cannot encrypt to an address now. The content key and nonce MUST come from the caller.

Enforced (check): .github: cd commons/crypto && bun test suite/ — cms.test.ts: certificates built at run time with the kernel's DER; random content encrypted to two recipients and opened by each; RFC 5083's structure; OAEP parameters with NULL or absent SHA-256; a changed message, a wrong key, another recipient and an EC certificate refused (interoperability with OpenSSL 3 checked by hand both ways)

Proved by: crypto/suite/cms.test.ts

Written in: crypto/src/cms.ts

Tests: passed: suite/cms.test.ts content encrypted to recipients is opened by each of them, and is what was encrypted; passed: suite/cms.test.ts a certificate is read for its issuer, serial, key, addresses, validity and key usage; PEM ; passed: suite/cms.test.ts a certificate that cannot encrypt to an address now is named with why; passed: suite/cms.test.ts a changed message, a wrong key, and a certificate it was not encrypted to are refused; passed: suite/cms.test.ts the structure is RFC 5083's: ContentInfo, version 0, one KeyTransRecipientInfo each, AES-2

Cited by: cms, Crypto

FR-006checkpassing

Crypto MUST build in-toto Statements v1 generic in their predicate (subjects named, with their digests) and DSSE envelopes: the pre-authentication encoding with lengths in bytes, signing with keys the caller imported (Ed25519; ECDSA on P-256, P-384 and P-521 with signatures in ASN.1 DER; RSA-PSS and RSASSA-PKCS1-v1_5), and verification against a threshold of distinct keys that checks the payload type first and refuses, by a typed error, a malformed envelope, a key that cannot verify, and too few valid signatures.

Enforced (check): .github: cd commons/crypto && bun test suite/ — dsse.test.ts: the DSSE specification's PAE example, sign and verify with six algorithms, a threshold of two over random payloads, every refusal by its kind, statements and their subjects' sha256

Proved by: crypto/suite/dsse.test.ts

Written in: crypto/src/dsse.ts

Tests: passed: suite/dsse.test.ts sign then verify gives the payload back, for any payload and payload type (Ed25519 and ECD; passed: suite/dsse.test.ts ECDSA signatures are ASN.1 DER, as sigstore and in-toto write them, and Web Crypto's raw f; passed: suite/dsse.test.ts PAE as the DSSE specification's example gives it, the lengths in bytes; passed: suite/dsse.test.ts a malformed envelope is refused: not JSON, a missing field, bad base64; passed: suite/dsse.test.ts a payload signed with ECDSA P-256 verifies, by the key's id and 8 more

Cited by: dsse, Crypto

Identifiers and keys

FR-007checkno test run

Crypto MUST give UUIDs by RFC 9562: the branded Uuid, its text form read and written, the name-based version 5 (SHA-1 of a namespace and a name, the same on every runtime) with the namespaces RFC 9562 defines (DNS, URL, OID, X.500), and a decoder from unknown to a Uuid.

Enforced (check): .github: cd commons/crypto && bun test suite/ — uuid.test.ts: RFC 9562's examples, version 5 and its namespaces, the text form

Written in: crypto/src/uuid.ts

FR-008checkno test run

Crypto MUST read a COSE key of ES256 and verify a WebAuthn registration and authentication for a relying party (the checks of Level 3's §7.1 and §7.2, each refusal a sentence and never an exception), as 0014-webauthn FR-002 to FR-008 say, which this library holds as cose and webauthn.

Enforced (check): .github: cd commons/crypto && bun test suite/ — webauthn.test.ts: a registration and an authentication of ES256 verified and every refusal named

Written in: crypto/src/cose.ts, crypto/src/webauthn.ts

The package

FR-009checkno test run

Crypto MUST depend on core and formats alone, MUST import nothing outside its own files, MUST name no host global, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/crypto, with an entry for the package (.) and one for each of its modules (./sha256, ./dsse, ...), each with its types (commons 0032-libraries-by-concern FR-005, FR-013), so that it runs on Bun, on Node 26 and in a browser with no build step.

Enforced (check): .github: cd commons/crypto && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs it on Node 26 and Bun and type-checks a consumer of every entry

Written in: crypto/about.ts, crypto/library.ts, crypto/src/mod.ts, crypto/tools/check.ts, crypto/tools/pack.ts

Acceptance scenarios

  1. Given the bytes abc, When they are hashed, Then the SHA-256 is ba7816bf...15ad, a Sha256, per FR-001.
  2. Given a password and a salt, When it is hashed as SHA-512 crypt, Then the hash is the one Drepper's specification gives for Hello world! with the salt saltstring, per FR-003.
  3. Given a request and credentials, When it is signed by Signature Version 4, Then the signature is the one AWS's published Signature Version 4 examples give, per FR-004.
  4. Given a statement and a key, When it is wrapped in a DSSE envelope, Then the envelope verifies and a changed payload does not, per FR-006.
  5. Given the packed package installed under node_modules, When Node 26 and Bun import @intellectual-frontiers/crypto and @intellectual-frontiers/crypto/sha256, Then both give the same digest, per FR-009.

Out of scope

  • The reading and writing of the formats these use (hexadecimal, base64, DER, CBOR): formats.
  • Signing files with keys on a disk: the host (runtime/sign, lifted with grc).

Edge cases

  • A SHA-256 text with upper-case digits: lowered by sha256Of, per FR-001.
  • A rounds value outside the range SHA-512 crypt allows: clamped as glibc does, per FR-003.

Assumptions

  • Web Crypto (crypto.subtle) is there, as in Bun, Node 26, browsers and Workers.

Open questions

  • None.

Key entities

  • Sha256 - a checksum the compiler keeps apart from any other string.
  • Envelope - signed content with its payload type, as DSSE says.

Success criteria

SC-001success criterion

A harness signs, checks and hashes with these and with no outside package.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

cms, crypt, dsse, Crypto, md5, sha256, sigv4, hex, Formats, Net

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