nish/crypto/p384

ECDSA signature verification over NIST P-384 (secp384r1).

import {
  P384_POINT_SIZE,
  P384_SCALAR_SIZE,
  P384_SIGNATURE_SIZE,
  p384Verify,
  p384VerifySha384,
} from "nish/crypto/p384";
import { p384Verify, p384VerifySha384 } from "nish/crypto/p384";

// `pub` is a 97-byte key and `sig` a 96-byte `r || s`, a certificate's, say
const signedBy = (pub: u8[], message: u8[], sig: u8[]): boolean =>
  p384VerifySha384(pub, message, sig)
const signedDigest = (pub: u8[], digest: u8[], sig: u8[]): boolean =>
  p384Verify(pub, digest, sig)                          // a digest from any hash

A public key is the uncompressed SEC1 encoding of SEC 1 §2.3.3, 0x04 then X and Y as 48 big-endian bytes each; a signature is r and s as 48 big-endian bytes each. DER, which X.509 and TLS wrap a signature in, is not this module's business. A key or signature of the wrong length, a key that is not a point on the curve, an r or s of 0 or n or more, and a sum that is the identity answer false, never a panic. A digest longer than 48 bytes is truncated to its leftmost 384 bits (SEC 1 §4.1.4, FIPS 186-4 §6.4).

The module only verifies. It holds no private key and no secret intermediate: every value it computes on is a public key, a signature or a digest someone sent, so nothing here is a Secret and nothing is wiped.

Ported from fiat-crypto (https://github.com/mit-plv/fiat-crypto), fiat-c/src/p384_32.c and fiat-c/src/p384_scalar_32.c. Copyright (c) 2015-2020 the fiat-crypto authors (see the AUTHORS file). Used under the MIT licence; see std/crypto/LICENSE-fiat-crypto-p384.

What is ported and what is not

The p384Fiat* functions are fiat-crypto's generated, formally verified Montgomery arithmetic on twelve u32 limbs with u64 products — mul, add, sub, selectznz, nonzero and set_one mod p, and mul and set_one mod n — statement for statement, with fiat's variable names, translated the way nish/crypto/p256 translates P-256's:

  • C's out-pointers become a u64 answer, each of fiat's addcarryx, subborrowx and mulx helpers here answering its two outputs packed, the first in the low 32 bits and the second above them, and the caller declaring only the halves fiat goes on to read;
  • and each function opens with a length guard, so that the literal indices after it compile with no bounds check.

fiat's 64-bit p384_64.c needs a 128-bit product, which Nish has not got, so the 32-bit files are the ones ported. fiat's square is not: a square is a mul of an element by itself, which costs verification a little time and saves this file 2,500 lines. The scalar functions use the field's four helpers, which fiat generates identically for both. Everything else in this file — the curve, the encodings, the inversions and ECDSA — is written for this module from the documents it names.

The curve

The curve is y^2 = x^3 - 3x + b over GF(p), p = 2^384 - 2^128 - 2^96 + 2^32 - 1, with the base point G and its order n from SEC 2 §2.5.1 (FIPS 186-4 §D.1.2.4).

Points are projective (X : Y : Z), Z = 0 the identity, and are added and doubled with the complete formulas of J. Renes, C. Costello and L. Batina, "Complete addition formulas for prime order elliptic curves" (EUROCRYPT 2016), Algorithms 4 and 6 for a = -3, as nish/crypto/p256 uses them. Complete means no input is exceptional: P + P, P + (-P) and P + O all come out of the same straight line of field operations, so a crafted key or signature that steers u1 G onto ±u2 Q gets the right answer, not a special case.

Public values, so branches are allowed

Verification computes u1 G + u2 Q by Shamir's trick: one run of 384 doublings from the top bit down, adding G, Q or G + Q as the bits of u1 and u2 say. Those bits, the exponents p - 2 and n - 2 of the two Fermat inversions, and the range checks are all public, and the code branches on them. The field and scalar arithmetic is fiat's, constant time in its operands all the same.

Private names carry the p384 prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

p384Verify

Whether sig (r || s) is a valid ECDSA signature of digest under the public key pub (FIPS 186-4 §6.4.2): r and s in [1, n), and the x-coordinate of u1 * G + u2 * Q equal to r mod n, with w = s^-1, u1 = z w and u2 = r w, z the digest's leftmost 384 bits. A key or signature of the wrong length, a key that is not a point on the curve, and a sum that is the identity all answer false.

ECDSA is malleable, and so is this: when (r, s) verifies, (r, n - s) verifies too, as FIPS 186-4 and SEC 1 have it. Nothing here asks for the lower s, so a protocol that needs one signature per message and key has to refuse the upper half itself.

const p384Verify: (
  pub: u8[],
  digest: u8[],
  sig: u8[],
) => boolean
pubu8[]required

The signer's 97-byte uncompressed public key.

digestu8[]required

The message's hash; only its leftmost 384 bits count.

sigu8[]required

The 96-byte signature r || s.

returnsboolean

true when the signature is valid, false for anything else.

p384VerifySha384

p384Verify of the SHA-384 of msg: ECDSA with SHA-384 over the whole message.

const p384VerifySha384: (
  pub: u8[],
  msg: u8[],
  sig: u8[],
) => boolean
pubu8[]required

The signer's 97-byte uncompressed public key.

msgu8[]required

The whole message, hashed here.

sigu8[]required

The 96-byte signature r || s.

returnsboolean

true when the signature is valid, false for anything else.

Constants

97

P384_POINT_SIZE: i32

The length in bytes of a public key: 0x04, then X and Y big-endian (SEC 1 §2.3.3).

48

P384_SCALAR_SIZE: i32

The length in bytes of a scalar, and of each half of a signature: 48, big-endian.

96

P384_SIGNATURE_SIZE: i32

The length in bytes of a signature: r then s, 48 big-endian bytes each.