moonbitstack/mooncrypt/rsa does not have a README file

    Digest

    pub(all) enum Digest {
    Sha1
    Sha224
    Sha256
    Sha384
    Sha512
    Sha512_224
    Sha512_256
    Sha3_224
    Sha3_256
    Sha3_384
    Sha3_512
    } derive(Eq,
    Debug
    )

    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, and it is why the set is closed rather than a [@spec.Hash].

    The set is every digest an RSA encoding has a registered identifier for, in both families the library carries: SHA-2 including its two truncated forms, and SHA-3. The truncated forms are digests in their own right with their own initial vectors, not a SHA-512 cut short, and they carry their own identifiers.

    Digest::equal

    fn Digest::equal(Digest, Digest) -> Bool

    Digest::not_equal

    fn Digest::not_equal(x : Digest, y : Digest) -> Bool

    Digest::to_repr

    PrivateKey

    type PrivateKey

    An RSA signing key: modulus, public exponent and private exponent.

    The CRT factors, when carried, speed signing up fourfold: each half is an exponentiation to half the modulus width. They are optional, because a key read from its three numbers is the shape every JWK and every hand-written test gives, and without them the key still signs and decrypts — by the same fixed-width private exponentiation, only in one half rather than two. A key that carries them checks them against d when it is read, and refuses a factor that does not fit: a CRT implementation without that check leaks the factorisation to a single bit-flip, and this one will not make that the default.

    PrivateKey::decrypt

    fn PrivateKey::decrypt(self : PrivateKey, cipher : BytesView, digest? : Digest, mgf? : Digest, label? : BytesView) -> Bytes raise
    Broken

    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.

    PrivateKey::decrypt_pkcs1

    fn PrivateKey::decrypt_pkcs1(self : PrivateKey, cipher : BytesView) -> Bytes raise
    Broken

    Decrypt an RSAES-PKCS1-v1_5 block (RFC 8017 §7.2.2).

    Every way the block can be wrong reports the same [@spec.Tag], and every check runs before any of them is acted on — distinguishing "no separator" from "padding too short" is what Bleichenbacher's 1998 attack reads off, and what a great many implementations have been broken by since. A caller that puts this behind a network interface has to go further and make the failure indistinguishable from a valid one — a fresh random of the right length, the same work either way — because the timing of the answer is as good an oracle as the error is.

    PrivateKey::generate

    fn[S :
    Source
    ] PrivateKey::generate(source : S, bits? : Int, digest? : Digest, scheme? : Scheme) -> PrivateKey raise
    Unavailable

    Generate a fresh RSA signing key (FIPS 186-5 A.1.1): two random primes p and q, the modulus n = p·q, the public exponent 65537, and the private exponent d = e^{-1} mod phi(n).

    The primes are drawn from source, so a seeded [@moonseed.Source] makes the key reproducible and the platform's entropy makes it secret. bits is the modulus width, at least 512 and a multiple of 8; 2048 is the default every certificate and TLS stack accepts.

    PrivateKey::new

    fn PrivateKey::new(modulus : BytesView, exponent : BytesView, private_exponent : BytesView, digest? : Digest, scheme? : Scheme) -> PrivateKey raise
    Broken

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

    PrivateKey::new_crt

    fn PrivateKey::new_crt(modulus : BytesView, exponent : BytesView, private_exponent : BytesView, prime_p : BytesView, prime_q : BytesView, digest? : Digest, scheme? : Scheme) -> PrivateKey raise
    Broken

    Read a signing key that also carries its CRT factors: the modulus, the two exponents and the two primes, all big-endian. The factors are checked against d before the key is returned, so a pair that does not fit the exponent is refused here rather than producing a signature that leaks.

    PrivateKey::new_crt3

    fn PrivateKey::new_crt3(modulus : BytesView, exponent : BytesView, private_exponent : BytesView, prime_p : BytesView, prime_q : BytesView, prime_r : BytesView, digest? : Digest, scheme? : Scheme) -> PrivateKey raise
    Broken

    Read a signing key whose modulus is the product of three primes, as PKCS#1's multi-prime form allows. The three are checked against the modulus and against d before the key is returned, the same way the two-prime form is.

    A key like this signs and decrypts through three fixed-width exponentiations, one per prime, each a third of the modulus's width — the reason multi-prime keys exist at all. Everything else about it is ordinary: the public operation never learns how many factors there are.

    PrivateKey::public

    fn PrivateKey::public(self : PrivateKey) -> PublicKey

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

    PrivateKey::rsadp

    fn PrivateKey::rsadp(self : PrivateKey, cipher : BytesView) -> Bytes raise
    Broken

    RSADP (RFC 8017 §5.1.2): the inverse of PublicKey::rsaep. What comes back is unchecked, and a caller that branches on it has built a padding oracle.

    PrivateKey::sign

    fn PrivateKey::sign(self : PrivateKey, msg : BytesView) -> Bytes

    PrivateKey::size

    fn PrivateKey::size(self : PrivateKey) -> Int

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

    PrivateKey::with_scheme

    fn PrivateKey::with_scheme(self : PrivateKey, digest~ : Digest, scheme~ : Scheme) -> PrivateKey

    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.

    PublicKey

    type PublicKey

    An RSA verification key: modulus and public exponent.

    PublicKey::encrypt

    fn PublicKey::encrypt(self : PublicKey, plain : BytesView, seed~ : BytesView, digest? : Digest, mgf? : Digest, label? : BytesView) -> Bytes raise
    Broken

    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.

    PublicKey::encrypt_pkcs1

    fn PublicKey::encrypt_pkcs1(self : PublicKey, plain : BytesView, pad~ : BytesView) -> Bytes raise
    Broken

    Encrypt under RSAES-PKCS1-v1_5 (RFC 8017 §7.2.1), returning a block exactly as wide as the modulus.

    Legacy, and dangerous where a peer can see the answer: the padding carries no integrity, so a responder that tells a bad block from a bad padding hands over a Bleichenbacher oracle, and the scheme has no place in a new design. It is here because TLS's RSA key exchange, older CMS messages and a great deal of deployed data are built on it.

    pad is the PS octets, and it has to be k - 3 - plain.length() of them, none zero: draw it fresh from a CSPRNG for every message, as RFC 8017 §7.2.1 step 3 asks, and draw again if it comes back with a zero in it. A fixed pad makes the ciphertext deterministic, which is the one thing this scheme must not be.

    PublicKey::exponent

    fn PublicKey::exponent(self : PublicKey) -> Bytes

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

    PublicKey::modulus

    fn PublicKey::modulus(self : PublicKey) -> Bytes

    The modulus, big-endian and fixed-width.

    PublicKey::new

    fn PublicKey::new(modulus : BytesView, exponent : BytesView, digest? : Digest, scheme? : Scheme) -> PublicKey raise
    Broken

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

    PublicKey::rsaep

    fn PublicKey::rsaep(self : PublicKey, message : BytesView) -> Bytes raise
    Broken

    RSAEP (RFC 8017 §5.1.1): the message, k octets, raised to the public exponent. The bare operation, for a framing this package does not write itself, as TLS's RSA key exchange has.

    PublicKey::size

    fn PublicKey::size(self : PublicKey) -> Int

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

    PublicKey::verify

    fn PublicKey::verify(self : PublicKey, msg : BytesView, sig : BytesView) -> Bool

    PublicKey::with_scheme

    fn PublicKey::with_scheme(self : PublicKey, digest~ : Digest, scheme~ : Scheme) -> PublicKey

    The same key, verifying under digest and scheme.

    Salt

    pub(all) enum Salt {
    Auto
    Exact(Int)
    } derive(Eq,
    Debug
    )

    How long a PSS salt is.

    RFC 8017 §9.1 lets the signer choose and recommends the digest's own length, which is what TLS 1.3 and JOSE's PS256 require; [Auto] is that. On verification it reads the length back out of the block instead, because a peer that signed chose its own, and refusing anything but one length would refuse most of the signatures in the world. [Exact] holds both directions to the number given — zero included, which is a salt of no bytes and a deterministic signature, not a wildcard.

    Salt::equal

    fn Salt::equal(Salt, Salt) -> Bool

    Salt::not_equal

    fn Salt::not_equal(x : Salt, y : Salt) -> Bool

    Salt::to_repr

    Scheme

    pub(all) enum Scheme {
    Pkcs1
    Pss(salt~ : Salt)
    PssMgf(salt~ : Salt, mgf~ : Digest)
    PssShake(salt~ : Salt, xof~ : Xof)
    } derive(Eq,
    Debug
    )

    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.

    PssMgf is the same scheme with MGF1 masking under a hash of its own, which §9.1 defines as a parameter separate from the message's: every profile in use sets the two alike, which is what [Pss] is, but blocks exist that carry SHA-1 under a SHA-256 message, and verifying one must not mean weakening the message hash to match.

    PssShake is the third form: RFC 8702's RSASSA-PSS over SHAKE, where the message hash and the mask are one extendable-output function and the mask is that function run natively over the seed rather than MGF1's counter. Its two object identifiers — id-RSASSA-PSS-SHAKE128 and ...-SHAKE256 — carry no parameters, because the hash, the mask, the salt length and the trailer are all fixed by the identifier rather than chosen per signature.

    Scheme::equal

    fn Scheme::equal(Scheme, Scheme) -> Bool

    Scheme::not_equal

    fn Scheme::not_equal(x : Scheme, y : Scheme) -> Bool

    Scheme::to_repr

    Xof

    pub(all) enum Xof {
    Shake128
    Shake256
    } derive(Eq,
    Debug
    )

    SHAKE as RSASSA-PSS takes it (RFC 8702), at the output length that profile fixes for each variant: 32 octets from SHAKE128, 64 from SHAKE256.

    A SHAKE's output length is part of the call rather than of the function's name, so it cannot be a [Digest]: a Digest is something a DigestInfo carries an object identifier for, and no identifier exists for a SHAKE digest inside a PKCS#1 v1.5 block. RFC 8702 is what pins the two lengths, and the digest and the mask are the same SHAKE in both variants, so naming one variant names one scheme.

    Xof::equal

    fn Xof::equal(Xof, Xof) -> Bool

    Xof::not_equal

    fn Xof::not_equal(x : Xof, y : Xof) -> Bool

    Xof::size

    fn Xof::size(self : Xof) -> Int

    The digest length RFC 8702 gives self, in octets — the hLen of every block made under it.

    Xof::to_repr