nish/crypto/rsa
RSA signature verification: RSASSA-PKCS1-v1_5 and RSASSA-PSS over SHA-256, SHA-384 and SHA-512, under a public key read from its DER. Verification only; this module neither signs nor holds a private key.
import {
RSA_HASH_SHA256,
RSA_HASH_SHA384,
RSA_HASH_SHA512,
RSA_MAX_BITS,
RSA_MIN_BITS,
RsaPublicKey,
rsaParsePublicKey,
rsaVerifyPkcs1v15,
rsaVerifyPss,
} from "nish/crypto/rsa";
import { RSA_HASH_SHA256, RsaPublicKey, rsaParsePublicKey, rsaVerifyPkcs1v15, rsaVerifyPss } from "nish/crypto/rsa";
// der: a PKCS#1 RSAPublicKey; sig: as long as the modulus
const verify = (der: u8[], message: u8[], sig: u8[]): boolean => {
const key: RsaPublicKey | null = rsaParsePublicKey(der);
if (key === null) {
return false;
}
return rsaVerifyPkcs1v15(key, RSA_HASH_SHA256, message, sig) || rsaVerifyPss(key, RSA_HASH_SHA256, 32, message, sig);
};
rsaParsePublicKey
Reads the DER of a PKCS#1 RSAPublicKey (RFC 8017 §A.1.1), the whole of der.
rsaVerifyPkcs1v15
Verifies an RSASSA-PKCS1-v1_5 signature (RFC 8017 §8.2.2) of msg under key, with the hash id hash.
rsaVerifyPss
Verifies an RSASSA-PSS signature (RFC 8017 §8.1.2) of msg under key, with the hash id hash for the message and for MGF1, and a salt of exactly saltLen bytes.
RsaPublicKey
A public key as rsaParsePublicKey read it.
The key is the DER of PKCS#1's RSAPublicKey ::= SEQUENCE { modulus INTEGER, publicExponent INTEGER } (RFC 8017 §A.1.1), nothing before it and
nothing after it. It is read strictly: definite lengths in their shortest
form, each INTEGER positive and in its shortest form, a modulus of
RSA_MIN_BITS to RSA_MAX_BITS bits that is odd, and an exponent that is
odd, at least 3 and below 2^32 (so below the modulus). Anything else answers
null. The 2^32 bound is not RFC 8017's; it caps what one verification
costs, because the work grows with the exponent's length, and every
certificate in use carries 65537 (RSA-3, docs/security/crypto-rsa.md).
Verification
Verification answers false, never a panic, for an unknown hash id, a
signature that is not exactly as long as the modulus or is not below it, a
negative salt length, and any encoding that is not exactly the one RFC 8017
defines. PKCS#1 v1.5 builds the whole encoded message it expects, 00 01 FF … FF 00 DigestInfo, and compares it with what the signature opens to, so no
part of the opened block is parsed (Bleichenbacher's 2006 forgery against a
parser that skipped trailing bytes).
The DigestInfo carries the NULL parameters RFC 8017 §9.2 note 1 prints; the form without them, which the RFC lets a verifier accept, is refused. PSS is RFC 8017 §8.1.2 and §9.1.2 step by step, with MGF1 over the same hash as the message, the leftmost bits of the masked block checked to be zero and the 0x01 separator checked.
Variable time, on purpose
A public key, a signature and a message are
all public, so nothing here has a secret to leak: the exponentiation
branches on the exponent's bits, the reductions branch on comparisons and
the encodings are compared with an early exit. That is why this module does
not use nish:secret or nish/crypto/ct.
The arithmetic
The arithmetic is written for this module from the textbook. Numbers are
little-endian u32 limbs, products are taken in u64, and modular
multiplication is Montgomery's (P. L. Montgomery, "Modular multiplication
without trial division", Math. Comp. 44, 1985) in the coarsely integrated
operand scanning form of Ç. K. Koç, T. Acar and B. S. Kaliski, "Analyzing and
comparing Montgomery multiplication algorithms" (IEEE Micro, 1996), the same
algorithm as A. Menezes, P. van Oorschot and S. Vanstone, Handbook of
Applied Cryptography (1996), Algorithm 14.36, with one conditional
subtraction at the end.
The exponent is applied left to right by square and multiply (HAC Algorithm
14.79's binary special case). The closest upstream is BearSSL's i31 code
(br_i31_montymul, br_i31_modpow), and nothing here follows it: BearSSL
keeps 31-bit words and a constant-time structure, this keeps 32-bit words and
branches freely.
Private names carry the rsa prefix because a std/ module's private
functions share the importing program's flat symbol namespace
(docs/wp26-stdlib.md §3e).
Functions
rsaParsePublicKey
Reads the DER of a PKCS#1 RSAPublicKey (RFC 8017 §A.1.1), the whole of
der. Answers null for anything but one SEQUENCE of two positive,
minimally encoded INTEGERs with definite, minimal lengths and nothing
after it; for a modulus that is even or not RSA_MIN_BITS to
RSA_MAX_BITS bits long; and for an exponent that is even, below 3, or
not below 2^32 (which also keeps it below the modulus).
const rsaParsePublicKey: (der: u8[]) => RsaPublicKey | null
deru8[]requiredThe key's DER, nothing before it and nothing after it.
returnsRsaPublicKey | null
A new key whose modulus and exponent are copied out of der, or
null.
rsaVerifyPkcs1v15
Verifies an RSASSA-PKCS1-v1_5 signature (RFC 8017 §8.2.2) of msg under
key, with the hash id hash. The encoded message the signature should
open to, 00 01 FF … FF 00 DigestInfo, is built whole (EMSA-PKCS1-v1_5,
§9.2) and compared with what it does open to. false for an unknown hash
id, a modulus too short for the encoding, a signature that is not exactly
as long as the modulus or not below it, and any other bytes.
const rsaVerifyPkcs1v15: (
key: RsaPublicKey,
hash: i32,
msg: u8[],
sig: u8[],
) => boolean
keyRsaPublicKeyrequiredThe signer's public key.
hashi32requiredRSA_HASH_SHA256, RSA_HASH_SHA384 or RSA_HASH_SHA512.
msgu8[]requiredThe message signed, whole; it is hashed here.
sigu8[]requiredThe signature, big-endian.
returnsbooleantrue only when sig is key's signature of msg.
rsaVerifyPss
Verifies an RSASSA-PSS signature (RFC 8017 §8.1.2) of msg under key,
with the hash id hash for the message and for MGF1, and a salt of exactly
saltLen bytes. Every check of EMSA-PSS-VERIFY (§9.1.2) is made: the
length, the trailing 0xbc, the leftmost 8 emLen - emBits bits of the
masked block and of the unmasked one, the zero octets and the 0x01 before
the salt, and the hash. false for any of them, an unknown hash id, a
negative saltLen, and a signature that is not exactly as long as the
modulus or not below it.
const rsaVerifyPss: (
key: RsaPublicKey,
hash: i32,
saltLen: i32,
msg: u8[],
sig: u8[],
) => boolean
keyRsaPublicKeyrequiredThe signer's public key.
hashi32requiredRSA_HASH_SHA256, RSA_HASH_SHA384 or RSA_HASH_SHA512.
saltLeni32requiredThe salt's length in bytes; a signature with any other length is refused.
msgu8[]requiredThe message signed, whole; it is hashed here.
sigu8[]requiredThe signature, big-endian.
returnsbooleantrue only when sig is key's signature of msg.
Classes
RsaPublicKey
A public key as rsaParsePublicKey read it. One built by hand is not
checked: the verifiers answer it without a panic, and their answer means
something only for a key the parser would accept. They read n and e,
never bits.
class RsaPublicKey
| Member | |
|---|---|
new RsaPublicKey(n: u8[], e: u8[], bits: i32) |
Keeps the arrays given, without a copy or a check. |
bits: i32 |
The modulus's length in bits: 2048 for a 2048-bit key. |
e: u8[] |
The public exponent, big-endian with no leading zero byte. |
n: u8[] |
The modulus, big-endian with no leading zero byte. |
Limits
8,192
RSA_MAX_BITS: i32
The largest modulus rsaParsePublicKey accepts, in bits.
1,024
RSA_MIN_BITS: i32
The smallest modulus rsaParsePublicKey accepts, in bits. A policy that wants 2048 checks bits itself.
Constants
1
RSA_HASH_SHA256: i32
SHA-256, the hash id rsaVerifyPkcs1v15 and rsaVerifyPss take. The same number as nish/crypto/x509's X509_HASH_SHA256.
2
RSA_HASH_SHA384: i32
SHA-384.
3
RSA_HASH_SHA512: i32
SHA-512.

