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

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[]required

The 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
keyRsaPublicKeyrequired

The signer's public key.

hashi32required

RSA_HASH_SHA256, RSA_HASH_SHA384 or RSA_HASH_SHA512.

msgu8[]required

The message signed, whole; it is hashed here.

sigu8[]required

The signature, big-endian.

returnsboolean

true 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
keyRsaPublicKeyrequired

The signer's public key.

hashi32required

RSA_HASH_SHA256, RSA_HASH_SHA384 or RSA_HASH_SHA512.

saltLeni32required

The salt's length in bytes; a signature with any other length is refused.

msgu8[]required

The message signed, whole; it is hashed here.

sigu8[]required

The signature, big-endian.

returnsboolean

true 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.