Every package, in order

Authenticated encryption with associated data.

[`open`] raises rather than returning an option, because "the tag did not match" is the one outcome a caller must not silently treat as empty plaintext. `cipher~` is the ciphertext with its tag appended, the layout every AEAD construction in use writes.

A block cipher: a keyed permutation of a fixed-size block.

It is the thing a mode of operation is built on, which is why it is a contract rather than a concrete type — GCM is defined for any 128-bit block cipher, so it takes one of these and SM4-GCM costs nothing more than an SM4 that implements it.

Both directions are here although a counter mode needs only [`encrypt`]: a permutation that cannot be inverted is not a block cipher, and a mode such as CBC needs the inverse.

A cryptographic hash, as a state you feed and then read.

Five methods and no more, because everything mooncrypt builds on top of a hash needs exactly these: HMAC needs [`block`] to size its pads, HKDF and PBKDF2 need [`size`] to count output blocks, and every one-shot needs [`write`] then [`finish`]. A third-party digest becomes usable throughout the library the moment it implements this.

[`finish`] does not consume the state, so a caller may keep writing and read again; [`reset`] returns it to the initial vector, which is how HMAC reuses one allocation for both passes.

A message authentication code: a hash that a key has been mixed into.

It is deliberately not a [`Hash`] — a MAC has no block size worth exposing and must never be used where an unkeyed digest is expected.

Something that holds a private key and can sign with it.

Something that holds a public key and can check a signature.

It answers `Bool` and never raises: a bad signature is an expected answer, not an exceptional one, and raising here invites a caller to swallow the error and carry on.

A ciphertext that did not authenticate, or a key that cannot be used.

One whole message through a hash, in one call.

It resets first, so passing a state that has already been used is not a silent corruption of the result.

Compare two byte strings in time that does not depend on their contents.

The obvious loop returns at the first differing byte, and the time it took tells an attacker how long a prefix they guessed right — enough to recover a tag or a token byte by byte across many requests. This one reads both strings to the end and folds the differences together.

Length is not treated as a secret: unequal lengths answer immediately, which is what every library does, because the length is visible on the wire anyway.

This is the only comparison mooncrypt offers. Use it for tags, digests and anything else derived from a key.

Overwrite a buffer with zeroes.

Key material lives longer than the code that used it: a scratch array stays in whatever memory the runtime hands out next until something else writes over it. Erasing at the end of the operation shortens that window. Under a garbage collector it is a best-effort measure, not a guarantee — a copy the collector moved is out of reach — which is why keys are held in [`FixedArray`] here rather than in [`Bytes`], where they could not be erased at all.

Which BLAKE2. `b` is the 64-bit variant and `s` the 32-bit one; the digest length, the salt length and the personalisation length all follow from that.

The last block is compressed here and nowhere else: BLAKE2 holds one block back, because the final block is marked as final and a block that was already compressed cannot be told otherwise.

It runs on copies, so a caller may read a digest and keep writing — the reading is what makes the copy worth it.

A fresh hasher.

`len` is the digest length, and 0 means the full length for the variant. `salt` and `person` are fields of the parameter block, so their lengths must be exactly 0 or the variant's salt size — a short one is not zero-padded, it is a different parameter block. `key` is what makes this a MAC; it may be at most 64 bytes for `b` and 32 for `s`.

Back to the parameterised state, key block and all.

The block length: 128 or 64 bytes.

The salt and personalisation lengths, 16 or 8 bytes.

The longest digest this variant can produce: 64 or 32 bytes.

Hash one whole message.

One whole message as a keyed MAC of the variant's full length.

The block length in bytes.

The chunk length in bytes — the unit the tree is built from.

The digest length in bytes, which is what [`@spec.Hash`] reports.

Key derivation mode: the context string is hashed first, and its digest becomes the key, so two contexts give two unrelated functions.

A keyed hasher, which is a MAC: the key stands in for the initial vector, so a keyed hash has no relation to the unkeyed one.

A plain BLAKE3 hasher.

Read `len` bytes of output from everything written so far, without disturbing the state: a caller may read and then keep writing.

A keyed or deriving hasher cannot be reset to a bare state without losing what makes it that hasher, so this keeps the key and the flags.

Hash one whole message, read to `len` bytes.

Derive `len` bytes of key material for `context` from `material`.

Hash one whole message to 32 bytes.

Keyed hash of one whole message, read to `len` bytes.

MD5 counts and emits little-endian, where SHA-1 and SHA-2 are big-endian — the one place the two designs part company in the padding.

Hash one whole message to a 16-byte digest.

The padding is MD4's — a one bit, zeroes, and the length in bits as a little-endian sixty-four bit number — and the digest is emitted the same way, five words least significant byte first.

The five chaining words start at the same values MD4 and MD5 use, which is not a coincidence: the compression function was inherited and only the round structure changed.

Hash one whole message to a 20-byte digest.

Hash one whole message to a 20-byte digest.

Which member of the SHA-2 family.

The six are one design at two word widths. `Sha512_224` and `Sha512_256` are SHA-512 with a different initial vector and a truncated digest, which is why they are not simply SHA-512 cut short — cutting SHA-512 short would leave the discarded half recoverable in a length-extension.

A fresh hasher, SHA-256 unless another member is named.

The compression block length in bytes.

The digest length in bytes.

Hash one whole message.

Which member of the Keccak family.

The four SHA-3 lengths and the two SHAKE lengths are the same permutation with a different rate — a wider rate means fewer rounds of work per byte, so SHAKE128 is the fastest and the weakest, and the numbers in the names are the security level in bits, not the output size.

Reads on a copy of the state, so a caller may keep writing afterwards — the same rule SHA-2 follows here.

A fresh hasher, SHA3-256 unless another member is named.

The rate in bytes: how much of the 200-byte state a block of message fills before the permutation runs. The rest is capacity, and the security level is half of it.

The digest length in bytes. SHAKE has no fixed length; the value here is the conventional default output, 32 or 64 bytes, used when a caller asks for a `Hash` rather than a stream.

Absorb more message.

A SHAKE, or a cSHAKE when `name` or `custom` is non-empty (SP 800-185 §3.3).

The two strings are not secret. `name` distinguishes one function from another and is fixed by the standard that defines the function; `custom` distinguishes one application from another. Both empty means plain SHAKE, whose suffix differs — 0x1f rather than 0x04 — so the two can never collide.

Start over, keeping the rate and the customisation.

Read `len` bytes, continuing where the last read stopped.

`bytepad(x, w)`: `x` padded with zeroes to a multiple of `w`, after its own length. A rate-sized `w` makes the following message start on a block boundary, which is what keeps a key from being read as message.

One whole message through cSHAKE128.

One whole message through cSHAKE256.

`encode_string(s)`: the bit length, then the bytes (SP 800-185 §2.3.2).

Hash one whole message.

`left_encode(x)`: the length of `x` in bytes, then `x`, both big-endian (SP 800-185 §2.3.1).

`right_encode(x)`: `x` big-endian, then its length in bytes (SP 800-185 §2.3.1). What tells a reader where an output length ends.

One whole message through SHAKE128.

One whole message through SHAKE256.

The block length in bytes.

The digest length in bytes.

Hash one whole message.

CMAC over any block cipher, as a state you feed and then read.

The two subkeys are computed once, when the context is made, from a single encryption of the zero block — that is the whole of the setup.

The tag for everything written so far. The state is left as it was, so more message can be added and the tag read again — which is what makes a MAC usable for a running transcript.

Start a CMAC context over a block cipher.

`tag` is the length of the tag to produce. SP 800-38B allows any prefix of the full block, but each bit given up halves the forgery resistance, so the default is the whole block and shorter values are a deliberate trade.

Put the context back to the state a newly made one is in, keeping the subkeys.

The tag length in bytes.

Overwrite the subkeys and the chain.

Feed more message. Any length is fine; the last block is held back until [`finish`](#finish) says which subkey it takes.

The tag of a message, in one call.

GMAC: the authentication half of GCM, with the message authenticated instead of encrypted.

The nonce makes it a MAC rather than a hash. It must never repeat under one key: two tags under the same nonce give away the hash subkey, and from there every tag under that key is forgeable. Twelve bytes is the length the standard prefers, because it skips a derivation step and so is both faster and easier to reason about.

The tag for everything written so far. Reading it does not consume the message, so a transcript can be tagged as it goes and continue afterwards.

Start a GMAC context.

`tag` is the tag length in bytes; the same values GCM allows are allowed here, and the default is the full sixteen.

Throw away the message, keeping the nonce, so the context can tag another transcript. Only useful when the same nonce is meant to be reused, which for a MAC means the two transcripts must be compared, never both trusted.

The tag length in bytes.

Compare a tag with what this context would produce, in constant time.

Feed more of the message.

The tag of a message, in one call.

Key an HMAC with `hash` as its digest.

A key longer than the hash's block is replaced by its digest and a shorter one is zero-padded, both per RFC 2104 §2 — so a 100-byte key and the 20-byte digest of that key authenticate identically, which is a property of the standard and not a defect here.

Start over on the same key, so one keyed state can authenticate a stream of messages without re-deriving the pads.

Authenticate one whole message.

Which KMAC. The number is the security level in bits and picks the cSHAKE underneath, so it also sets the largest key that fits in one block.

The cSHAKE rate in bytes, which is also the longest key KMAC accepts (SP 800-185 §4.2 requires the encoded key to fit in one block).

The conventional tag length in bytes, 32 or 64. KMAC itself has no fixed length; this is what [`Kmac`] uses when the length is not given.

Key a KMAC. `custom` separates the uses of one key: two tags computed under different strings are independent even when the key and message are the same.

Read `len` bytes, continuing where the last read stopped.

One whole message through KMAC, with a tag of `len` bytes.

One whole message through KMACXOF.

A Poly1305 computation under one key, fed in pieces. The accumulator is held in five 26-bit limbs so every product fits in 64 bits.

The tag length in bytes.

The tag. The computation is spent: a one-time key signs one message.

A computation under the 32-byte one-time `key`: `r` (clamped) then `s`.

The tag of `msg` under the one-time `key`.

A SipHash-2-4 in progress.

The buffer needs at most seven bytes: a full eight-byte word is mixed in the moment it is available, and only a trailing partial word waits for the length, which goes into the top byte of the last block.

The key length in bytes. SipHash is defined for exactly 16.

The tag length in bytes.

Key a SipHash-2-4. The key must be exactly [`key_size`] bytes; anything else is refused rather than padded, because a key that silently became shorter would be a weaker MAC that still looked like a working one.

Feed more bytes. Whole eight-byte words are mixed in as they arrive; whatever does not fill one is held until [`value`](#value).

The tag as a number.

The last block carries the message length in its top byte, so a message and the same message with a zero byte appended hash differently — without it, padding ambiguities would let an attacker move bytes between messages. The finalisation is four rounds, the "4" in the name.

The state is copied rather than consumed, so this can be called more than once.

The SipHash-2-4 tag of a whole message.

An Adler-32 in progress.

The digest length in bytes.

Start an Adler-32.

The initial sums are `a = 1` and `b = 0`, which is why the empty message has a checksum of 1 and not 0.

Feed more bytes.

The checksum of everything fed so far: `b` in the high half, `a` in the low, which is the order every format that carries it writes.

The Adler-32 of a whole message.

A CRC-16 in progress.

Which CRC-16.

Named after the catalogue, which is the only way to be unambiguous: "CRC-16" alone has meant at least four different functions in shipping protocols. The check value of each is stated on its case so that a reader can tell them apart at a glance.

Start a CRC-16. The default is CRC-16/ARC, the oldest of the six.

Feed more bytes.

The checksum of everything fed so far, as the number the formats that write it store.

One byte at a time, which is what [`@spec.Hash::block`] reports.

The checksum length in bytes.

The CRC-16 of a whole message.

A CRC-32 in progress.

The running value is kept complemented, as the reference implementation does, so the final xor is one operation at the end rather than a correction at every step.

Which CRC-32.

The two differ only in the polynomial, but they detect different faults: the IEEE one is the one on Ethernet and in zip files, and the Castagnoli one has better distance properties for the short blocks a filesystem or a storage protocol writes.

Start a CRC-32. The default is the IEEE polynomial, which is what "CRC-32" means when nothing else is said.

Feed more bytes.

The checksum of everything fed so far, as the number the formats that write it actually store.

One byte at a time: that is the stride this machine works in, and it is what [`@spec.Hash::block`] reports.

The checksum length in bytes.

The CRC-32 of a whole message.

An FNV digest in progress.

The state is always 64 bits wide and only the low half is used for the 32-bit kinds, because the multiply has to be truncated to the width anyway and keeping one register is simpler than two.

Which FNV.

Two widths and two orderings, and all four produce different answers. The `_1a` variants xor the byte in before the multiply, which is what gives them their better avalanche; the `_1` variants are the original and are kept because existing formats use them.

Start an FNV digest. The default is FNV-1a at 64 bits, which is the one new code should use.

Feed more bytes.

The digest of everything fed so far, as the number the formats that write it store.

The stride, which for FNV is one byte.

How many bytes the digest occupies.

The FNV digest of a whole message.

A MurmurHash3 in progress.

Bytes are buffered until a whole block is present. That is not an optimisation but a requirement: the trailing partial block is mixed differently from a whole one, and its length is only known at the end.

Which MurmurHash3.

The names are the ones the reference implementation uses: `x86_32` is the 32-bit-output variant tuned for 32-bit machines, `x64_128` the 128-bit-output variant for 64-bit machines. There is also an `x86_128` upstream, left out because `x64_128` dominates it on the machines anyone runs today.

The block length: how many bytes one pass of the mixing loop consumes, and what [`@spec.Hash::block`] reports.

The digest length in bytes.

Start a MurmurHash3. The seed is mixed in from the first byte, so two seeds give unrelated digests of the same message.

Feed more bytes, a block at a time, holding back whatever does not fill one.

The digest as a pair of 64-bit halves, high half first. The 32-bit kind gives `(digest, 0)`.

The MurmurHash3 of a whole message, as the 128-bit pair.

An xxHash in progress.

Bytes are buffered until a whole stripe is present, because a stripe is the smallest unit the lanes can consume: a partial stripe has to be re-read from the start at [`finish`](#finish), so it cannot be folded in early.

Which xxHash.

The two are not a truncation of each other: the 64-bit one multiplies 64-bit words and rotates by different amounts, so XXH64 of a message says nothing about its XXH32.

The stripe length: how many bytes the four lanes consume before the state moves to the next stripe, and what [`@spec.Hash::block`] reports.

The digest length in bytes.

Start an xxHash. The seed is zero by default, which is what a plain checksum wants; a hash table passes its own so that the same keys land in a different order.

Feed more bytes, a stripe at a time, holding back whatever does not fill one.

The digest as a number.

The buffered partial stripe is folded in here: whole 4- or 8-byte words first, then the remaining bytes one at a time, then the avalanche.

The xxHash of a whole message.

The three numbers a derivation is defined by.

`memory` is in kibibytes, and it is what the function is really about: the derivation allocates that much and reads it back in a password-dependent order, so an attacker who cannot afford the memory cannot compute the hash cheaply at all. `passes` multiplies the time without changing the memory. `lanes` is how many independent chains are kept; it is the only knob that helps when the work runs on a GPU, and each lane needs eight blocks.

The tag length is not here: it is an argument to the derivation, because two calls that differ only in how long an output they want are still the same function with the same cost.

Which of the three functions to run. They differ only in where the index of the reference block comes from.

The second option: 64 MiB, three passes, four lanes. A tenth of the memory and about the same time, for the case where 2 GiB per login is not affordable.

The smallest derivation that is still Argon2: 8 KiB, one pass, one lane. It exists so that tests and protocol fixtures can name a size rather than invent one, and it is not a safe way to store a password.

The first option RFC 9106 §4 recommends: 2 GiB, one pass, four lanes. Big enough that a dedicated attacker has to buy the memory, and one pass keeps the wall-clock time at a single sweep.

The number the function is identified by inside the initial hash.

The spelling the RFC uses, for error messages and parameter records.

How many bytes a derivation with these parameters will actually allocate: the memory is rounded down to a whole number of blocks per slice, and each block is 1 KiB.

Check the three numbers before a derivation allocates anything.

`memory` has to leave room for eight blocks per lane, which is the point below which the reference block rule in §3.4.1 stops working; `lanes` has to be at least one and small enough that the lane number fits in the address computation; and `passes` has to be at least one, since zero passes would leave the memory untouched.

Derive a key with Argon2.

`secret` is a pepper: a value kept outside the database, so that a stolen table is useless without it. `ad` is associated data, which binds the output to a context such as a user name. Both are optional and both change the result, which is why the RFC gives them their own length fields.

`len` is the tag length; anything from 4 bytes up is allowed, and the default matches what a password hash is normally stored as. `params` sets the cost, and `kind` picks the variant — leave both alone unless you know why not.

```moonbit nocheck let tag = @argon2.key( password, salt, kind=@argon2.Argon2id, params=@argon2.interactive, ) ```

Twelve rounds of key setup: about a quarter of a second on the machine this was written on, which is the usual compromise between logging in and guessing.

The dearest cost the format allows. A cost of 31 is expressible and would take a machine a lifetime, which is the point of allowing it.

The most password bytes the format can use. Anything past it cannot affect the result, so it is refused rather than silently ignored — a caller who truncates their own password knows they did.

The cheapest cost the format allows.

The salt is always sixteen bytes; the format has no way to say otherwise.

Format a password and salt as a `$2b$` hash string.

This is what gets written to a database. The cost travels inside it, so raising [`default_cost`] later leaves existing hashes verifiable.

Hash a password with a caller-supplied salt.

The salt is sixteen raw bytes; the format only stores its base64 form, so callers usually let [`parse`] hand it back from a stored hash instead of making one. The result is the 24-byte output of the scheme, of which the text format keeps 23.

Raises rather than truncating if the password is longer than [`max_password`] bytes, because a password that silently becomes a prefix of itself is a password that can be confused with another.

Read the cost and the salt out of a stored hash.

Returns `None` for anything that is not a well-formed `$2a$`, `$2b$`, `$2x$` or `$2y$` string. The three prefixes are the same function here: the differences between them are historical bugs in other implementations that only showed up for passwords with the high bit set or longer than 72 bytes.

Check a password against a stored hash.

Never raises: a malformed string is simply a wrong password, because a caller who has to handle the difference between "this row is corrupt" and "this password is wrong" can call [`parse`] first and get it there.

The comparison is constant time, so the time it takes says nothing about how much of the stored hash the password got right.

Derive `len` bytes of key from a shared secret.

`z` is the secret the key exchange agreed on; `other_info` is everything the protocol wants bound into the derivation — the algorithm identifiers, the two parties' key info, the length of the key being made. SP 800-56A §5.8.1 spells that structure out as a DER `OtherInfo` and calls it optional; the octets are taken as given here, because a protocol that defines its own layout (TLS 1.3, CMS, S/MIME each do) has to pass its own.

The counter starts at one, and a call longer than one digest concatenates as many blocks as it needs, each counted from one upwards.

The expand step (RFC 5869 §2.3): stretch a pseudorandom key to `len` bytes.

The counter is one byte, so no more than 255 digests can be produced from one key; asking for more is a programming error, not a runtime condition.

The extract step (RFC 5869 §2.2): concentrate whatever entropy the input has into one uniform pseudorandom key of the hash's own length.

An absent salt is a string of zeroes as long as the digest, which is what the RFC specifies — not a special case.

Extract-then-expand in one call: turn input keying material into `len` bytes of key.

`info` separates the uses of one secret — two derivations with different `info` are independent keys, which is how one handshake secret yields a separate key for each direction. `salt` need not be secret and need not be present; when it is, the extraction is stronger against a non-uniform input.

Stretch a password into `len` bytes of key by iterating an HMAC `rounds` times (RFC 8018 §5.2).

The whole security argument is the iteration count: it costs the defender one derivation and the attacker one per guess. Pick it from what the deployment can afford today, not from a number copied out of an old document — SCRAM servers name their own count on the wire, and for password storage the memory-hard KDFs are the better answer where they are available.

`rounds` and `len` have no defaults, which is itself the mainstream choice: Python's `hashlib.pbkdf2_hmac`, Go's `pbkdf2.Key` and Node's `crypto.pbkdf2` all require both. A default iteration count is a number that goes out of date silently, and this is the one place where being made to type it is the point.

A count below one and a negative length abort rather than raise. Neither can come from input: they are the calling code saying something it cannot mean.

The three numbers a scrypt derivation is defined by.

`n` is the number of blocks the inner loop keeps, so the memory it takes is `128 * r * n` bytes; `r` is the block size divided by 128; and `p` is how many of those passes run in parallel, which multiplies the time but not the memory. Doubling `n` doubles both, which is why it is the knob to turn.

A preset for logging in: 16 MiB of memory, one pass. Fast enough to answer a request, slow enough that a guess costs a real machine a real fraction of a second.

The smallest `n` RFC 7914 allows: it must be a power of two above one.

A preset for storing a password that will not be asked for often: 1 GiB of memory. Anything that must run on a small device cannot afford it.

Check the three numbers before a derivation spends memory on them.

The RFC's own limits: `n` a power of two greater than one, `r` and `p` positive, and `128 * r * p` below 2³⁰ so that the block counter cannot overflow.

Derive `len` bytes from a password and a salt (RFC 7914 §6).

`n`, `r` and `p` are the cost. The memory is `128 * r * n` bytes, so the default preset's 16 MiB is deliberate rather than incidental: it is what makes a hardware attack cost memory as well as time.

An expanded key.

The schedule is held in a [`FixedArray`] so it can be erased; see [`@spec.wipe`] for why that matters and what it does not promise.

The block length, in bytes. AES is defined for one block size only; the key is what varies.

The block length in bytes, which is 16 whatever the key.

Decrypt one block (FIPS 197 §5.3 InvCipher).

Encrypt one block (FIPS 197 §5.1 Cipher).

The state is column-major: byte `k` is row `k % 4`, column `k / 4`.

Expand a key, which is 16, 24 or 32 bytes for AES-128, AES-192 or AES-256.

The key length is the only thing that distinguishes the three, so there is no variant to name: `new` reads it off the key, as every AES interface in use does. A length that is none of the three raises rather than being rounded to one, because a key that is not the key is not a smaller mistake than no key.

The key length in bytes: 16, 24 or 32.

Forget the expanded key. See [`@spec.wipe`] for what that is worth.

A Blowfish key schedule. The subkeys are the whole state; there is nothing else to keep.

The block length in bytes. Sixty-four bits, which is why this cipher is only safe inside something that does not care about birthday bounds — bcrypt, for instance, encrypts a fixed 24-byte string and nothing else.

How many bytes the bcrypt key schedule may feed it: 72 characters plus the terminator that the format appends.

The longest key the original specification allows.

The shortest key the original specification allows.

The block length in bytes.

Decrypt one block.

Encrypt one block.

Key the cipher the ordinary way.

The key must be between [`min_key`] and [`max_key`] bytes, the range the original specification names.

The expensive key schedule bcrypt is built on: one salted pass, then `2^cost` rounds of rekeying with the password and with the salt alternately.

Every round throws away the whole schedule and rebuilds it, which is why a guess at a password costs one full setup rather than one block encryption. The salt is always sixteen bytes, because that is the only width the format stores; the key may be up to [`eks_max_key`] bytes, since bcrypt appends a terminator to the password.

Overwrite the subkeys. After a bcrypt derivation the schedule is as secret as the password, so it should not be left for a later allocation to hand back out.

A Camellia key, with both directions already scheduled.

Decryption uses the same network as encryption with every list reversed, so the two schedules are built once here and the entry point is all that differs between [`encrypt`] and [`decrypt`].

The block length in bytes. Camellia is defined for one block size only; the key is what varies, over 128, 192 or 256 bits.

The block length in bytes.

Decrypt one 16-byte block.

Encrypt one 16-byte block.

The key schedule (RFC 3713 §2.2).

KL is the leftmost 128 bits of the key. KR is the rest of it, except that a 192-bit key has only 64 bits of remainder, so those are followed by their own complement — a trick that keeps KR 128 bits wide without inventing key material. KA and KB are then derived by running the round function a few times over KL, KR and the sigma constants.

Overwrite both schedules.

The key is at most 256 bits but the schedule is up to twenty-four subkeys and two whitening sets, and anyone holding them can decrypt everything the key can without ever seeing the key. They are wiped for the same reason a key is.

A DES key, expanded into its sixteen forty-eight-bit round keys.

A Triple DES key: three DES keys, applied in the order E-D-E.

The block length in bytes.

The key length in bytes. Eight, but only 56 of the 64 bits are key material: the low bit of every byte is a parity bit that DES ignores.

The Triple DES key length in bytes: three DES keys, used encrypt-decrypt-encrypt.

The block length in bytes.

Decrypt one 8-byte block: the same cipher with the round keys in reverse.

Encrypt one 8-byte block.

The sixteen round keys of FIPS 46-3 §3.2: permute the key to 56 bits, split it in half, rotate the halves by the schedule, and squeeze each pair through PC-2.

Overwrite the round keys.

There are sixteen of them, each forty-eight bits, so a whole DES schedule holds nearly the entire key — and unlike the key it is not parity-masked.

The block length in bytes.

Decrypt one 8-byte block: E-D-E in reverse, which is D-E-D.

Encrypt one 8-byte block.

Key Triple DES from a sixteen-byte key, the two-key form where the third key repeats the first.

Two-key triple DES gives about 80 bits of security rather than 112, which is why it was deprecated before the three-key form was. It is still what a lot of stored data was encrypted with.

Key Triple DES.

The key is three DES keys and the operation is encrypt with the first, decrypt with the second, encrypt with the third — E-D-E, chosen so that a key of `K ‖ K ‖ K` is exactly single DES and a deployment could be upgraded one endpoint at a time.

Overwrite all three round-key schedules.

Cipher Block Chaining: each block is XORed with the ciphertext of the one before it, so the same plaintext block at two positions encrypts differently and a change anywhere propagates to everything after it.

The chaining state carries across calls, so a message can be encrypted in pieces as long as every piece is a whole number of blocks. Use [`pad`] and [`unpad`] when the message is not.

Counter mode: the cipher encrypts a counter that goes up by one per block, and the result is the keystream. Encryption and decryption are the same operation, no padding is needed, and blocks can be processed in parallel — which is why it is the mode inside GCM.

It authenticates nothing on its own, and reusing a counter value under the same key reuses the keystream, which reveals the XOR of the two plaintexts.

The block length in bytes.

Decrypt a whole number of blocks, continuing the chain from where the last call left off.

Encrypt a whole number of blocks, continuing the chain from where the last call left off.

Start a CBC context.

The initialisation vector does not have to be secret, but it must not repeat under the same key: two messages that begin with the same blocks would then begin with the same ciphertext, which is the one thing CBC exists to avoid.

Put the chaining value back to the initialisation vector, so the context can be used again for another message.

XOR a byte string with the keystream, continuing from wherever the last call stopped. Encrypting and decrypting are the same call.

The block length in bytes.

Start a counter-mode context.

The nonce is the whole initial counter block, so for a 128-bit block cipher it is sixteen bytes. It must never repeat under the same key.

Put the counter back to the initial block and forget the leftover keystream, so the context can encrypt another message from the same nonce.

PKCS#7 padding: append `n` bytes each holding the value `n`, where `n` is whatever brings the length up to a multiple of the block size.

A message that is already a whole number of blocks gains a whole extra block of padding, which is what makes the padding removable without guessing: the last byte always says how much to take off.

Strip PKCS#7 padding, raising [`@spec.Broken::Tag`] if it is not there.

The error is deliberately the same one an AEAD gives for a bad tag: whether the padding was wrong or the key was, a caller that reacts differently to the two has built a padding oracle, and that is a complete break of CBC. Treat every failure as "the ciphertext is wrong" and nothing else.

An SM4 key schedule: thirty-two round keys, either direction.

The block length in bytes.

The key lengths this cipher takes: one, 16 bytes (GB/T 32907 §6.2).

The block length in bytes.

Decrypt one block.

Encrypt one block.

Expand a 16-byte key (GB/T 32907 §7.3).

Overwrite the round keys.

A ChaCha20 key, ready to produce keystream for any nonce and counter.

The key length in bytes.

The nonce length in bytes.

One 64-byte keystream block for `counter` and `nonce` (RFC 8439 §2.3).

The cipher for a 32-byte `key`.

`data` XORed with the keystream that starts at block `counter` (RFC 8439 §2.4): encryption and decryption are the same operation. The counter starts at 0, as libsodium's does; AEAD_CHACHA20_POLY1305 starts the payload at 1.

HChaCha20, draft-irtf-cfrg-xchacha §2.2.

The same twenty rounds as [`Cipher::block`], with two changes: the nonce is sixteen bytes and takes the whole fourth row, and the feed-forward addition of the input state is left out. What comes back is therefore not keystream but a value that looks like a key — which is exactly how XChaCha20 turns a twenty-four byte nonce into the twelve-byte nonce ChaCha20 has room for.

The halves of the output that are kept are the first and last rows, the two the nonce did not touch, so the derived key depends on the whole key and the whole nonce.

An RC4 keystream.

The state advances as bytes are produced, so one `Cipher` encrypts a stream and cannot be rewound. Two messages under the same key therefore need two instances — or, in practice, two keys, because reusing one is what broke WEP.

The longest key the algorithm has room for.

The key is used to seed a permutation of 256 bytes, so anything longer than 256 bytes would be folded back onto itself. Shorter keys are the practical case: 5, 13 and 16 bytes cover WEP, WPA-TKIP and Kerberos.

The next `n` bytes of keystream.

Key the cipher: the key-scheduling algorithm of RFC 6229 §2.1.

The permutation starts as the identity and is then shuffled by the key, one swap per byte. A key of zero bytes is refused — it has no entropy to begin with, and accepting it would make an empty key and a missing key both "RC4 with nothing".

The next byte of keystream (RFC 6229 §2.2).

One swap and two lookups: the generator is four lines long, which is why it could be implemented from memory in every language, and why the statistical weakness is worth taking seriously rather than checking for.

`data` XORed with the keystream that follows the current state: encryption and decryption are the same operation, which is what a stream cipher means.

The first `n` bytes of keystream for `key`, without consuming a cipher.

Encrypt `data` in one call, starting from the beginning of the keystream.

A Salsa20 key, ready to produce keystream for any nonce and counter.

The key length in bytes.

Salsa20 also defines a sixteen-byte key, which uses a different constant in the middle of the state; only the thirty-two byte form is here, because it is the one that appears in every protocol that uses Salsa20 at all.

The nonce length in bytes. Salsa20 proper has sixty-four bits of nonce and sixty-four of counter, which is what XSalsa20 extends with a longer nonce.

One 64-byte keystream block for `counter` and `nonce`.

The counter is 64 bits. That is not academic: a 32-bit counter wraps after 256 GiB of keystream, and two blocks that share a counter share their keystream entirely.

The cipher for a 32-byte `key`.

`data` XORed with the keystream that starts at block `counter`: encryption and decryption are the same operation.

Encrypt `data` in one call, starting from block zero.

`n` bytes of keystream from the start.

An XChaCha20 key, ready to produce keystream for any nonce and counter.

The key is kept rather than the derived subkeys, because a subkey belongs to one nonce and a cipher is made once and used with many.

The key length in bytes.

The nonce length in bytes.

One 64-byte keystream block for `counter` and a 24-byte `nonce`.

The cipher for a 32-byte `key`.

`data` XORed with the keystream that starts at block `counter`. Encryption and decryption are the same operation.

The counter starts at 0, matching [`@chacha20`]; XChaCha20-Poly1305 starts its payload at 1 because block 0 is spent on the Poly1305 key.

The subkey HChaCha20 derives from a 32-byte `key` and a 16-byte `nonce`.

This is ChaCha20's block function with the feed-forward left out, so what comes back is a value that looks like a key. It is public because it is useful on its own — libsodium's sealed boxes derive a key from a shared secret and a nonce the same way — and because it is the one part of XChaCha20 a reader is likely to want to check in isolation.

CCM over any 128-bit block cipher.

The tag length is fixed when the context is made because it goes into the first byte of the MAC input: a 12-byte tag and a 16-byte tag are not the same computation truncated, they are different computations. It is also why CCM cannot be used with a tag shorter than four bytes — the encoding has no way to say so.

The default tag length in bytes.

Wrap a block cipher in CCM.

The cipher must have a sixteen-byte block. Everything else — the key — is the cipher's business.

Authenticate and decrypt.

Raises [`@spec.Broken::Tag`] if the tag does not match. The tag is checked before the plaintext is returned, and the comparison is constant time, so a caller learns only that the message was wrong and not which part of it.

Encrypt and authenticate.

The result is the ciphertext followed by the tag; the tag length comes from the context. The nonce may be 7 to 13 bytes, and shorter is not better: the number of messages that are safe under one key is bounded by the nonce space, so 13 bytes — the longest that leaves room for a two-byte counter — is what the standard recommends.

The tag length in bytes.

Authenticate and decrypt in one call.

Encrypt and authenticate in one call, with a context that lives just long enough.

ChaCha20-Poly1305 under one 32-byte key. Nonces are 12 bytes and must never repeat under the same key.

The tag length in bytes.

The plaintext of `cipher` (ciphertext then tag), checked before anything is decrypted. Every failure is the same `Tag`, so a caller learns nothing about which part was wrong.

The ciphertext of `plain` followed by its tag. A nonce that is not 12 bytes is a programming error and aborts: `seal` has no error to return.

The tag length every implementation writes unless told otherwise: the full 128 bits, which is the only length SP 800-38D appendix C leaves unqualified.

Wrap a block cipher in GCM.

`tag` is the authentication tag length in bytes. The default is the full 16; SP 800-38D §5.2.1.2 also allows 15, 14, 13 and 12, and 8 or 4 only for applications whose own analysis says so — appendix C works out how much forgery resistance each one costs, so a shorter tag is a decision to take deliberately rather than a default to inherit.

The cipher must have a 16-byte block; GCM is not defined for any other.

Check the tag and, only then, decrypt.

It raises rather than returning an option because "the tag did not match" is the one outcome a caller must not quietly read as empty plaintext. Nothing decrypted is returned before the tag is checked, so a caller cannot act on plaintext that was never authenticated.

Encrypt and authenticate, returning the ciphertext with its tag appended.

The nonce is at least one octet; an empty one aborts. It must never repeat under one key: GCM's confidentiality and its authentication both collapse if it does, and recovering the hash subkey from two messages sharing a nonce is arithmetic rather than cryptanalysis. That is the caller's to guarantee, because only the caller knows where its nonces come from.

The tag length in bytes this instance writes and checks.

SIV over two 128-bit block ciphers.

The two ciphers are keyed separately — see [`halves`] — and the same object can seal any number of messages. It also keeps one CMAC context between calls so that the two subkeys are not recomputed for every block of every message.

The tag length in bytes, which for SIV is also the length of the synthetic IV.

Wrap two block ciphers in SIV.

`mac` produces and checks the synthetic IV and must be keyed with K1; `ctr` encrypts and must be keyed with K2. Both must have a sixteen-byte block.

Open with one associated data string.

Open with a vector of associated data, RFC 5297 §2.7.

Authenticates before anything is returned, and compares the recomputed IV to the one that came with the ciphertext in constant time.

Seal with one associated data string, which is all most callers have.

Seal with a vector of associated data, RFC 5297 §2.6.

The result is the synthetic IV followed by the ciphertext — the IV first, unlike GCM and CCM, which append the tag. A non-empty `nonce` becomes the last associated data component, which is the nonce-based mode of §2.6: it costs nothing extra and makes a repeated message look different.

Passing the components as a vector rather than one string is the point of SIV: `["user", "1"]` and `["user1"]` are different messages, and a header that is parsed in two places can be authenticated field by field without having to be re-serialised.

The tag length in bytes.

Split a key into the two halves SIV wants.

RFC 5297 §2.6 divides the key into K1, which drives the CMAC, and K2, which drives the counter. The halves must be independent: reusing one key for both halves would let the CTR keystream be related to the CMAC output, and the construction's security argument assumes they are separate.

Open in one call.

Seal in one call, with a context that lives just long enough.

The key length in bytes.

The tag length in bytes.

A GCM instance keyed with SM4, ready to seal and open.

Open one message in one call, raising [`@spec.Broken`] if it does not authenticate.

Seal one message in one call.

Which digest a signature is taken over.

PKCS#1 v1.5 embeds an ASN.1 algorithm identifier in the block it signs, so the scheme cannot be written over an arbitrary hash the way HMAC can: only a digest with a registered identifier is signable. That constraint is this enum.

Which padding a signature uses.

`Pkcs1` is the deterministic block of RFC 8017 §9.2, which JOSE calls RS256 and almost every certificate in existence carries. `Pss` is the probabilistic scheme of §9.1, which JOSE calls PS256 and which new designs should prefer — its security rests on a proof rather than on the absence of a known attack.

Decrypt an RSAES-OAEP block (RFC 8017 §7.1.2).

Every way the block can be wrong reports the same [`@spec.Tag`], and the checks all run before any of them is acted on: which check failed is exactly what Manger's 2001 attack reads off, so it is not told apart here.

`digest`, `mgf` and `label` mean what they do in [`PublicKey::encrypt`] and must match what encrypted the block.

Read a signing key from its modulus and its two exponents, big-endian.

The public half of a signing key — what verifies what it signs.

The modulus width in bytes, which is also the signature width.

The same key, signing under `digest` and `scheme` instead of the ones it was built with — TLS 1.3 negotiates the PSS digest per handshake, an X.509 issuer names its own per certificate.

Encrypt under RSAES-OAEP (RFC 8017 §7.1.1), returning a block exactly as wide as the modulus.

`seed` is the `hLen` random octets OAEP masks with, and it is a required parameter rather than something drawn here: this library holds no entropy source, and the seed is what makes the same message encrypt differently twice. Go's `rsa.EncryptOAEP` and Rust's `rsa` crate take the randomness the same way. **Reusing a seed across messages destroys OAEP's security** — draw it fresh from the platform's CSPRNG for every call.

`digest` is the hash OAEP runs, and `mgf` the one MGF1 masks with; leaving `mgf` out uses `digest`, which is what Go and Node do, while Python and Java let the two differ, which is why it is a parameter here.

`digest` defaults to SHA-1: it is RFC 8017's own default, and what OpenSSL, Java's `OAEPParameterSpec.DEFAULT` and Node all take. OAEP does not rest on the hash's collision resistance, so this is not the choice it would be for a signature — but Go and Python require the caller to name it, and a new design should pass `digest=Sha256`.

The key's own `digest` and `scheme` govern signatures and are not consulted here; encryption and signing are separate schemes over the same key.

The public exponent, big-endian with no leading zeroes.

The modulus, big-endian and fixed-width.

Read a verification key from its modulus and exponent, big-endian.

The modulus width in bytes, which is also the signature width.

The same key, verifying under `digest` and `scheme`.

The scalar this key is written as, big-endian and fixed-width.

Which curve this key is on.

Read a signing key from its scalar, big-endian and fixed-width.

The verification key that matches this signing key: `Q = [d]G`.

A signing key read against a digest of the caller's choosing.

The key as an uncompressed SEC 1 point, `04 ∥ X ∥ Y`.

Which curve this key is on.

Read a public key from a SEC 1 §2.3.3 encoded point.

Both forms are accepted: `04 ∥ X ∥ Y` uncompressed, and `02`/`03 ∥ X` compressed, where the prefix gives the parity of `Y` and the rest is recovered from the curve equation.

The digest is the one the curve is standardly paired with — SHA-256 for the 256-bit curves, SHA-384 for P-384, SHA-512 for P-521 — which is what ES256, ES384 and ES512 mean. Use [`PublicKey::with_hash`] for any other pairing.

Read a public key from its two affine coordinates — the shape a JWK carries.

A public key read against a digest of the caller's choosing.

The two affine coordinates, each fixed-width — the shape a JWK wants.

The length of a seed, a public key and half a signature.

The length of a signature: `R ∥ S`.

The secret this key was built from — the 32-byte seed for a key from [`PrivateKey::new`], and whatever was handed to [`PrivateKey::of_secret`] otherwise.

Read a signing key from its 32-byte seed.

A signing key from a secret of any length.

[`PrivateKey::new`] takes the 32-byte seed the key format stores. The expansion itself — SHA-512 over the secret, then clamping — is defined for an input of any length; RFC 8032 fixes the seed at 32 octets so that keys have one written form, not because the arithmetic needs it. MariaDB's `client_ed25519` keys a connection with the password directly, which is the protocol this entry point exists for.

Anything that holds a real seed wants `new`: it is the one that refuses a secret of the wrong length, and a length check is worth having.

The verification key that matches this signing key: `A = [s]B`.

The 32 bytes this key is written as.

Read a public key from its 32 compressed bytes.

The length of a secret, a public key and half a signature: 57 bytes, which is 456 bits — the bit width `b` in RFC 8032's table, not the field width.

The longest context RFC 8032 allows, since `dom4` writes its length in one octet.

The length of a signature: `R ∥ S`, 114 bytes.

The secret this key was built from.

Read a signing key from its 57-byte secret.

The verification key that matches this signing key: `A = [s]B`.

The point is decoded from its own encoding so that a `PublicKey` always holds the pair together. That decode cannot fail — `[s]B` is a point on the curve by construction — so a failure here is a bug in this file, not something a caller could cause or handle.

Sign a message with a context, RFC 8032 §5.2.6.

The context is optional and defaults to empty, which is the plain Ed448 of the RFC. `prehash` selects Ed448ph, where the message is replaced by its 64-byte SHAKE256 digest before signing — the variant for streams too large to hold in memory.

As with Ed25519 the signature is deterministic: `r` comes from the key's prefix and the message, not from a random source.

The 57 bytes this key is written as.

Read a public key from its 57-byte encoding.

Raises [`@spec.Broken::Weak`] when the bytes are not a point on the curve: a key that does not decode cannot verify anything, and accepting it invites a caller to compare garbage against garbage.

Check a signature with a context, RFC 8032 §5.2.7.

Returns `false` for anything wrong with the signature — a point that does not decode, `S` at or above the group order, the equation not holding — and raises only when the *caller* is at fault, which for Ed448 means a context longer than 255 bytes.

A signing key.

A verification key: the even-y point whose x coordinate is the key.

The length of a secret key, a public key and half a signature.

A public key is 32 bytes and not 33, because BIP 340 drops the parity byte that SEC1 keeps: the scheme only ever uses the even-y point for a given x.

The length of a signature: `R.x ∥ s`, sixty-four bytes.

The 32 bytes this key is written as.

Read a signing key from its 32 bytes.

The scalar has to lie in `[1, n-1]`. Zero is not a key, and a value at or above the group order is a different scalar — the same number modulo `n` — which would give a signature that verifies against a different key than the one the caller thought they were using.

The verification key that matches this signing key.

The x coordinate is taken from `d·G` and the parity is thrown away; signing then works with whichever of `d` and `n-d` lands on the even-y point.

Sign a message with fresh auxiliary randomness mixed into the nonce.

`aux` is 32 bytes that do not have to be secret and do not have to be random to be correct — but they are what protects the key if the entropy source ever repeats itself, which is why BIP 340 asks for them. Deterministic signing is `sign` with none.

The 32 bytes this key is written as: the x coordinate.

Read a verification key from its 32 bytes.

The bytes are an x coordinate, and not every 32-byte string is one: it has to be below the field prime, and `x³+7` has to be a square. Either failing is a key that cannot exist, so both are refused here rather than at verification time, where the answer would be a silent `false`.

A signing key: a scalar in `[1, n-1]`.

A verification key: the public point.

The default identity a signature is bound to (GB/T 32918.2-2016 §5.5). It is not a secret and not a key; it separates one application's signatures from another's, the way a domain separator does.

The coordinate width in bytes, and the width of each half of a signature.

The 32-byte big-endian encoding of the scalar.

A private key from a scalar, refused unless it is in range.

A private key from its 32-byte big-endian encoding.

The public point this key signs under.

Sign `msg`, bound to `id`. The signature is `r ∥ s`, thirty-two bytes each.

The identity is part of what is signed, so a signature made under one `id` does not verify under another — which is what stops a signature from being lifted from one protocol into a different one.

The uncompressed encoding, `04 ∥ X ∥ Y`.

A public key from a SEC 1 §2.3.3 point: `04 ∥ X ∥ Y` uncompressed, or `02`/`03 ∥ X` compressed. A point off the curve is refused.

Check `sig` against `msg` and `id`. A malformed signature is a `false` answer, not an error: it is an expected thing for the peer to send.

A private key: a group and an exponent.

One of the five finite-field groups of RFC 7919.

They differ only in size, and the size is the whole choice: a larger group is slower and buys a larger margin against a discrete logarithm. `ffdhe2048` is the smallest the RFC defines and the one TLS picks when it has to.

The generator every ffdhe group uses.

Two, and not because it is convenient: RFC 7919 §3 fixes it, and a group with a different generator is a different group.

The size of the group in bits.

The name the group is known by, which is what a protocol writes in a negotiated list.

The prime, decoded on demand.

Decoding costs a hex conversion; an exponentiation over the same number costs thousands of multiplications, so there is nothing to gain by caching it and a mutable global to lose.

How much security the group is estimated to give, in bits (RFC 7919 §5.1).

It is the number to compare against a symmetric key size: `ffdhe3072` is roughly a 128-bit cipher, and anything smaller than that is the weak link in a handshake that otherwise negotiates AES-128.

The size of the group in bytes, which is also the width every value in it is written at.

The group this exponent belongs to.

Key an exponent.

The exponent is taken as given. RFC 7919 §5.1 suggests a length of twice the security level — 225 bits and up — and leaves it to the caller because a short exponent weakens nothing that the group size has not already fixed, but it does weaken the exchange, so the length is worth thinking about.

Zero is refused: it produces a public key of one and a shared secret of one, which is not a secret at all.

The public value: the generator raised to the secret, modulo the prime, written at the width of the group.

The shared secret: the peer's public value raised to the secret.

The peer's value is checked before it is used. It has to be exactly as wide as the group — a shorter one is a peer that did not pad, and accepting it would make two encodings of the same value mean different things — and it has to lie in `[2, p-2]`, because 0, 1 and p-1 are the fixed points that make the result independent of the secret.

The public value for a secret, without keeping the secret.

The shared secret for one side of an exchange.

The public value for the private `scalar` (big-endian, `curve.size()` bytes, in `[1, n)`): the uncompressed SEC 1 point `04 ∥ X ∥ Y`, which is what a TLS key share carries.

The shared secret between the private `scalar` and the `peer`'s public value: the X coordinate of their product, `curve.size()` bytes. The peer's point is refused unless it lies on the curve, which is what keeps an invalid-curve attack from reading the scalar out a few bits at a time. Both SEC 1 forms are read; TLS sends only the uncompressed one.

The base point, `u = 9`, little-endian (RFC 7748 §4.1).

The length of a scalar, a u-coordinate and a shared secret, in bytes. All three are 32; X25519 has no other size.

The public key for a private one: the scalar applied to the base point.

Apply a scalar to a u-coordinate, which is the whole of X25519 (RFC 7748 §5).

Both inputs and the answer are 32 little-endian bytes. The scalar is clamped and the u-coordinate's high bit is masked, as §5 requires: a caller may hand in whatever 32 bytes it has, and the ones that are not part of the value are ignored rather than rejected, because that is what makes a random 32 bytes a valid private key.

An all-zero shared secret is refused. It is what a low-order point produces, and it means the peer chose the answer rather than contributing to it — the check is a MAY in RFC 7748 §6.1 and a MUST in TLS 1.3 (RFC 8446 §7.4.2), and every implementation in use makes it. There is no knob to turn it off: no protocol served here wants the unchecked primitive, and offering it would only make the dangerous call the short one.

The base point, `u = 5`, little-endian (RFC 7748 §4.2).

The length of a scalar, a u-coordinate and a shared secret, in bytes. All three are 56; X448 has no other size.

The public key for a private one: the scalar applied to the base point.

Apply a scalar to a u-coordinate, which is the whole of X448 (RFC 7748 §5).

Both inputs and the answer are 56 little-endian bytes. The scalar is clamped — and, unlike X25519, nothing is masked off the u-coordinate, because 56 bytes is exactly the width of the field.

An all-zero shared secret is refused, as in [`@x25519`]: it is what a low-order point produces, and it means the peer chose the answer rather than contributing to it.

A decoded BIT STRING: the content bytes and how many low bits of the last byte are padding.

One decoded element: the tag byte, the contents, and `raw` — tag, length and contents together. `raw` is what a signature covers and how far to step to reach the next element.

A refused encoding. `Malformed` is a hostile or corrupt certificate; `Unsupported` is well-formed DER this parser deliberately does not read, and the two are separated so a caller can log an interop gap without calling it an attack.

Whether bit `i` is set, counting from the most significant bit of the first byte — the numbering X.509 uses for keyUsage. Bits inside the padding, or past the end, read as unset.

A BIT STRING.

A BOOLEAN. DER admits only 0x00 and 0xFF, so any other octet is refused.

An INTEGER, two's complement as X.690 §8.3 defines it.

The elements a constructed value holds, in encoding order.

An OCTET STRING's contents.

An OBJECT IDENTIFIER in dotted-decimal form. The first octet packs two arcs (X.690 §8.19.4); the rest are base-128, high bit set on every byte but an arc's last.

A DirectoryString or IA5String as text — the string types an X.509 Name and a SAN entry are written in. UniversalString is refused: it is UTF-32 and no certificate in practice uses it.

A UTCTime or GeneralizedTime as seconds since the Unix epoch. RFC 5280 §4.1.2.5 pins both to the seconds-and-`Z` form, and a two-digit year to 1950..2049, so the other shapes X.690 allows are refused rather than guessed at.

Octets of one of the ASCII string types as text. Taken on its own because a subjectAltName tags its entries with the field number, not the string type, so the octets arrive with nothing left to dispatch on.

A DER BIT STRING (tag 0x03) with no unused trailing bits: a leading 0x00 count then `content`.

Whether `tag` is the context-specific `[n]` of an IMPLICIT or EXPLICIT field.

A context-specific constructed value `[tag_num]` wrapping `content` (tag `0xA0 | tag_num`) — the EXPLICIT tagging X.509 uses for the certificate version and extensions.

A DER INTEGER (tag 0x02) from a big-endian magnitude: strip redundant leading zero bytes, then prepend one 0x00 if the top bit is set, so the value stays non-negative (X.690 §8.3).

Encode a definite length (X.690 §8.1.3): the short form is the single byte for lengths under 128; the long form is `0x80 | n` followed by the length in `n` big-endian bytes.

A DER NULL (tag 0x05, empty).

A DER OCTET STRING (tag 0x04).

A DER OBJECT IDENTIFIER (tag 0x06) from its arcs (X.690 §8.19): the first byte encodes `40·arc1 + arc2`, and each later arc is base-128 big-endian with the high bit set on every byte but the last.

Read the one element that is the whole of `input`. Bytes after it are an error — a certificate with a payload glued to its end is two documents, and the second one is not covered by the signature over the first.

Read the element at the head of `input`. Raises rather than reading past the end: the length is checked against the bytes that remain, in 64-bit arithmetic so a length near 2^31 cannot wrap the check.

A DER SEQUENCE (tag 0x30): the concatenated `elements`.

A DER SET (tag 0x31): the concatenated `elements`.

A tag-length-value: the `tag` byte, the definite length of `value`, then `value`.

A DER UTCTime (tag 0x17), the `YYMMDDHHMMSSZ` form X.509 validity uses before 2050.

A DER UTF8String (tag 0x0c).

Which curve a key lives on.

The four short-Weierstrass curves that protocols in use actually name: the three NIST primes, which TLS and JOSE speak, and secp256k1, which Bitcoin and Ethereum speak. They differ only in their parameters, so the arithmetic below is written once and each curve is a row in a table.

The width in bytes of a coordinate, a scalar, and each half of a signature.

An elliptic-curve private key as SEC1 (RFC 5915) holds it.

The curve name and the public point are both optional in the format. A key without them is still a key — the scalar is the secret — but it cannot be used without being told which curve it is on, so [`curve`](#curve) being `None` is the parser saying "this file is not enough on its own".

An RSA signing key as PKCS#1 holds it.

The seven numbers after the modulus and the two exponents are the CRT parameters: they let a signer do two half-size exponentiations instead of one full-size one. They are carried rather than recomputed because a format that stores them would lose information otherwise, and because computing them back from silence costs two big-integer factorisations per load.

An RSA verification key as PKCS#1 holds it: two integers.

How wide a PEM body line is before it wraps, in base64 characters.

RFC 7468 §2 asks for exactly 64, and every other width in the world is a parser's problem rather than a writer's — but no width at all is what makes a file hard to read in a terminal, so this is not optional.

Wrap a DER blob as a PEM block: the `BEGIN` line, the base64 body wrapped at [`line_width`], and the `END` line.

The label is written as given and appears twice, so the two lines agree — RFC 7468 §3 requires that, and a reader that checks it is entitled to reject the file otherwise.

The curve a namedCurve identifier names, or `None` for a curve this library does not have parameters for.

The namedCurve identifier of a curve, as the arcs a SEC1 key writes in its `[0]` field and a SubjectPublicKeyInfo writes in its parameters.

Read a PEM block: its label and the DER it wraps.

Loose in the ways a key file is loose in practice — leading text, blank lines, carriage returns and trailing whitespace are all tolerated, because a key that came out of an email or a Windows editor is still the same key. Strict about the two things that matter: the `END` label must match the `BEGIN` label, and the body must decode as base64.

Read a PKCS#8 `PrivateKeyInfo` and return the octets inside, which for an RSA key are a PKCS#1 `RSAPrivateKey`.

The algorithm identifier is checked rather than returned: a caller that got back the octets of an EC key and parsed them as RSA integers would not find out until the numbers failed to make sense, and that is a long way from the mistake.

Read a PKCS#1 `RSAPrivateKey`.

Read a PKCS#1 `RSAPublicKey`.

Read a SEC1 `ECPrivateKey`.

The optional fields are found by their tag rather than by their position, because RFC 5915 marks them `OPTIONAL` and a writer that omits the curve is encoding the same type as one that includes it.

Read a `SubjectPublicKeyInfo` and return the DER inside its BIT STRING.

Read an EC `SubjectPublicKeyInfo`: the curve it names and the point.

Wrap a PKCS#1 `RSAPrivateKey` in the PKCS#8 `PrivateKeyInfo` of RFC 5958.

The PKCS#1 `RSAPrivateKey` of RFC 8017 §A.1.2, version 0.

The two-prime form is the only one written: `version` 1 exists for keys with more than two primes, which no library here generates and no format in practice carries.

The PKCS#1 `RSAPublicKey` of RFC 8017 §A.1.1.

The SEC1 `ECPrivateKey` of RFC 5915 §3, with the curve always written.

`public` is written when it is given. It is derivable from the scalar — it is the scalar times the generator — so a file that carries it is carrying a convenience, not a second secret.

Wrap a PKCS#1 `RSAPublicKey` in a `SubjectPublicKeyInfo` (RFC 5280 §4.1.2.7).

A `SubjectPublicKeyInfo` for an EC key: the algorithm identifier names the curve, and the BIT STRING holds the point in its uncompressed form.

A one-time password generator: a shared secret and a code length.

The secret is the only thing that has to be kept, and it is shared out of band — the QR code an authenticator app scans is nothing but this key and a label.

How many digits a code carries.

An enumeration rather than a number because the value is a modulus, not a quantity: six digits means "modulo one million, printed with leading zeroes". RFC 4226 §5.3 fixes the range at six to eight; nine is here because a nine-digit code still fits the 31-bit value dynamic truncation produces, and because banks use them.

Thirty seconds: the time step TOTP is defined over (RFC 6238 §5.2).

A different step is legal and some systems use one, which is why every time-based function here takes it — but it is not a tuning knob, because a step that disagrees with the verifier's produces codes that never match.

How many digits a code of this kind has.

Whether `code` is the time-based code for `unix_time`, or for one of the `skew` steps on either side of it.

Both directions are checked because the clock that produced the code and the clock that checks it are different clocks, and either may be the fast one.

Whether `code` is the counter-based code for `counter`, or for one of the `ahead` counters after it.

The look-ahead is the HOTP resynchronisation of RFC 4226 §7.4: a token that has been pressed more times than the server counted is ahead of it, and accepting a few steps forward is what lets the two catch up. It is a small number for a reason — every step tried is another guess an attacker gets.

The counter-based code of RFC 4226 §5.3, keyed with SHA-1 as that standard specifies.

The counter-based code of RFC 4226 §5.3 over any hash.

RFC 6238 extends HOTP by allowing SHA-256 and SHA-512, and appendix B of that RFC gives a table for each — which is why this takes a factory rather than hard-coding SHA-1.

Key a generator.

The secret is taken as given: RFC 4226 leaves its length to the application, and the 20-byte recommendation is a recommendation because the security is the HMAC's, not the code's.

The time-based code of RFC 6238, keyed with SHA-1.

`unix_time` is seconds since 1970, taken as an argument rather than read from a clock: the package then has no opinion about time and can be tested against a fixed table.

The time-based code of RFC 6238 over any hash.

The counter-based code of RFC 4226 for a six-digit code, the shape the standard's own examples have.

The time-based code of RFC 6238 for a six-digit code.