net.quic: 13a - Certificate, CertificateVerify signing, Finished, HRR

Completes the message-construction half of 13a's TLS 1.3 server handshake:

- encode_certificate (tls13_certificate.v): server Certificate message,
  reusing the existing CertificateEntry/ParsedCertificate types. certificate_
  request_context is always empty per RFC 8446 SS4.4.2 ("in the case of
  server authentication, this field SHALL be zero length").

- encode_certificate_verify (tls13_certificate.v): signs
  certificate_verify_signed_content(.server, ...) via crypto.ecdsa.PrivateKey.
  sign() -- a pre-existing V primitive, untouched by net.quic work so far.
  Only sig_scheme_ecdsa_secp256r1_sha256 is wired up; RSA-PSS signing is
  explicitly rejected with a clear error rather than silently mis-signing --
  it needs a mbedtls_pk_sign_ext V wrapper that doesn't exist yet (only the
  verify side, verify_rsa_pss_signature, does).

- build_finished (tls13_messages.v): thin wrapper around the already
  side-agnostic compute_finished_verify_data. Verified against the real RFC
  8448 SS3 vector, not just round-tripped against this module's own parser.

- build_hello_retry_request (tls13_server_hello.v): shares ServerHello's wire
  type, distinguished by the fixed magic random. key_share carries a bare
  NamedGroup (RFC 8446 SS4.2.8's KeyShareHelloRetryRequest) -- a third,
  distinct wire shape from both the client's and the real-ServerHello
  key_share encodings.

Every function round-trips through its already-existing, independently-
written parse counterpart -- a real cross-check, not tautological, since
build and parse were each derived from the RFC text separately. Full
net.quic suite 54/54, ./vnew missdoc clean, ./vnew fmt -w applied.

Certificate/CertificateVerify signature framing is verified; the produced
ECDSA signature's cryptographic validity is not cross-verified against an
independent verifier in this repo (no PublicKey.verify() in crypto.ecdsa, no
EC certificate fixture) -- the same documented gap Phase 2c's own
x509_standalone_signature_test.v already states for the identical reason.

Still to come within 13a: the server-side state machine wiring these five
functions into an actual handshake driver (see PROGRESS.md).

Author: Richard Wheeler

vlib/net/quic/PROGRESS.md

@@ -1240,11 +1240,28 @@ QUIC layer is already role-parameterized (`role QuicRole` on `QuicConn`;
 explicitly) — none of that foundation needs rework. Same one-sub-phase-per-
 stacked-PR convention as Phase 12's 12a-12d.
 
-- [ ] **13a** (in progress) — TLS 1.3 server handshake: ServerHello +
-      EncryptedExtensions construction, Certificate presentation,
-      CertificateVerify **signing** (only verify exists today), server-side
-      Finished, HelloRetryRequest generation (cookie extension — the client
-      only ever rejects a second HRR, never sends one).
+- [ ] **13a** (in progress) — TLS 1.3 server handshake:
+  - [x] Message construction, all five pieces (`tls13_server_hello.v`,
+        `tls13_certificate.v`, `tls13_messages.v`): `build_server_hello`,
+        `build_encrypted_extensions`, `encode_certificate`,
+        `encode_certificate_verify` (ECDSA P-256 signing only —
+        `sig_scheme_ecdsa_secp256r1_sha256`; RSA-PSS signing needs a
+        `mbedtls_pk_sign_ext` V wrapper that doesn't exist yet, only the
+        verify side does), `build_finished` (verified against the real RFC
+        8448 §3 vector, not just round-tripped against this module's own
+        parser), `build_hello_retry_request`. Every function round-trips
+        through its ALREADY-EXISTING, independently-written parse
+        counterpart — a real cross-check, not tautological. Caught one
+        real bug this way before commit: a server's `key_share` is a bare
+        `KeyShareEntry` (RFC 8446 §4.2.8), not the client's list-wrapped
+        shape.
+  - [ ] Server-side state machine (mirroring `Tls13ClientHandshake` in
+        `tls13_handshake.v`) — orchestrating the above into an actual
+        handshake driver: deciding when to send Certificate vs. reuse
+        cached state, whether to send an HRR, deriving/tracking the
+        transcript hash across all these messages, discarding keys at the
+        right checkpoints. NOT started — none of the five functions above
+        are wired into anything yet.
 - [ ] **13b** — Retry + address validation: Retry packet + opaque token
       minting/validation (`retry.v` currently only verifies), RFC 9000 §8.1
       anti-amplification 3x accounting (already flagged as a deferred,

vlib/net/quic/tls13_certificate.v

@@ -1,5 +1,7 @@
 module quic
 
+import crypto.ecdsa
+
 // CertificateEntry is one X.509 certificate plus its per-certificate
 // extensions (RFC 8446 §4.4.2). v1 only speaks the X509 CertificateType —
 // RawPublicKey (RFC 7250) is never negotiated (v1's EncryptedExtensions
@@ -113,6 +115,66 @@ pub fn parse_certificate(body []u8) !ParsedCertificate {
 	}
 }
 
+// encode_certificate constructs a complete Certificate handshake message
+// (RFC 8446 §4.4.2), framed via encode_handshake_message. `certificate_list`
+// is this server's own certificate chain, leaf-first (RFC 8446 §4.4.2's own
+// implicit ordering -- the peer's chain-validation walk, mirrored by this
+// codebase's own verify_certificate_chain, always treats the first entry as
+// the leaf). certificate_request_context is always encoded as empty: RFC
+// 8446 §4.4.2 states it is only non-empty "if this message is in response
+// to a CertificateRequest" -- "Otherwise (in the case of server
+// authentication), this field SHALL be zero length" -- and v1 is
+// server-authentication-only (client-cert auth is out of scope), so this
+// function never takes a caller-supplied context, the same scope
+// restriction parse_certificate's own doc comment already states for the
+// parse side.
+pub fn encode_certificate(certificate_list []CertificateEntry) ![]u8 {
+	// RFC 8446 §4.4.2.4 (quoted in parse_certificate's own doc comment):
+	// "the server MUST always provide a non-empty certificate_list" --
+	// enforced here on the encode side too, not just checked on the way
+	// back in when a peer's Certificate is parsed.
+	if certificate_list.len == 0 {
+		return error('quic: Certificate certificate_list must not be empty (server certificate_list MUST always be non-empty, RFC 8446 §4.4.2.4)')
+	}
+
+	mut body := []u8{}
+	body << u8(0) // certificate_request_context: always empty, see doc comment above
+
+	mut list := []u8{}
+	for entry in certificate_list {
+		if entry.cert_data.len == 0 || entry.cert_data.len > 0xff_ffff {
+			return error('quic: CertificateEntry cert_data length ${entry.cert_data.len} out of range (opaque cert_data<1..2^24-1>)')
+		}
+		list << u8(entry.cert_data.len >> 16)
+		list << u8(entry.cert_data.len >> 8)
+		list << u8(entry.cert_data.len)
+		list << entry.cert_data
+		// parse_certificate's own doc comment establishes that this
+		// client's ClientHello offers neither status_request nor
+		// signed_certificate_timestamp, so the only RFC 8446 §4.2-legal
+		// CertificateEntry extensions for THIS codebase's peer are illegal
+		// to send here (RFC 8446 §4.4.2: "Extensions in the Certificate
+		// message from the server MUST correspond to ones from the
+		// ClientHello message") -- enforced here too, not just on the
+		// parse side, so a caller can never accidentally construct a
+		// message a compliant peer would reject.
+		if entry.extensions.len != 0 {
+			return error('quic: CertificateEntry.extensions must be empty -- this server never negotiates status_request or signed_certificate_timestamp (RFC 8446 §4.4.2)')
+		}
+		list << u8(0) // extensions length: always 0, see above
+		list << u8(0)
+	}
+	if list.len > 0xff_ffff {
+		return error('quic: Certificate certificate_list too large: ${list.len} bytes')
+	}
+	body << u8(list.len >> 16)
+	body << u8(list.len >> 8)
+	body << u8(list.len)
+	body << list
+
+	return encode_handshake_message(.certificate, body)!
+}
+
 pub struct ParsedCertificateVerify {
 pub:
 	algorithm u16
@@ -201,3 +263,56 @@ pub fn certificate_verify_signed_content(role CertificateVerifyRole, transcript_
 	out << transcript_hash
 	return out
 }
+
+// encode_certificate_verify constructs a complete CertificateVerify
+// handshake message (RFC 8446 §4.4.3) by SIGNING
+// certificate_verify_signed_content(.server, transcript_hash) with
+// `signing_key`, then framing the result via encode_handshake_message. v1
+// is server-authentication-only (client CertificateVerify is never sent),
+// so this function always signs the `.server` context -- see
+// certificate_verify_signed_content's own doc comment for why the `.client`
+// variant exists at all without a real caller.
+//
+// Only sig_scheme_ecdsa_secp256r1_sha256 is wired up so far: rejected with
+// a clear "not implemented yet" error for any other algorithm rather than
+// silently producing a signature under the wrong scheme -- RSA-PSS signing
+// needs a still-missing mbedtls_pk_sign_ext V wrapper (only the verify side,
+// verify_rsa_pss_signature in net.mbedtls, exists today), tracked as
+// follow-up work within 13a, not built here.
+//
+// `signing_key` MUST be a P-256 (prime256v1) key -- the only curve this
+// codebase's own key generation/loading ever produces (Phase 1's scope
+// decision, `crypto.ecdsa`'s CurveOptions defaults to prime256v1 and no v1
+// caller ever overrides it). crypto.ecdsa exposes no curve accessor to
+// verify this defensively at the V level; behavior for a caller-supplied
+// non-P-256 key is undefined by construction, not validated here -- the
+// same trust boundary this function's own signing_key parameter implies
+// for any local, non-peer-supplied cryptographic material.
+pub fn encode_certificate_verify(algorithm u16, signing_key ecdsa.PrivateKey, transcript_hash []u8) ![]u8 {
+	if algorithm != sig_scheme_ecdsa_secp256r1_sha256 {
+		return error('quic: CertificateVerify signing for algorithm 0x${algorithm:04x} is not implemented yet (only ecdsa_secp256r1_sha256 is wired up)')
+	}
+
+	content := certificate_verify_signed_content(.server, transcript_hash)
+	// PrivateKey.sign's default hash_config (.with_recommended_hash) picks
+	// SHA-256 for a 256-bit (P-256) key -- see default_digest in
+	// vlib/crypto/ecdsa/ecdsa.v, keyed off the key's own bit size, matching
+	// exactly what sig_scheme_ecdsa_secp256r1_sha256 requires. The
+	// resulting signature is OpenSSL's standard ASN.1 DER ECDSA-Sig-Value
+	// encoding, the same format net.mbedtls's verify_ecdsa_signature (used
+	// on the client-side verify path, tls13_certificate_chain.c.v) already
+	// parses -- no reformatting needed between the two libraries.
+	signature := signing_key.sign(content, hash_config: .with_recommended_hash)!
+
+	mut body := []u8{}
+	body << u8(algorithm >> 8)
+	body << u8(algorithm)
+	if signature.len > 0xffff {
+		return error('quic: CertificateVerify signature too large: ${signature.len} bytes')
+	}
+	body << u8(signature.len >> 8)
+	body << u8(signature.len)
+	body << signature
+
+	return encode_handshake_message(.certificate_verify, body)!
+}

vlib/net/quic/tls13_certificate_test.v

@@ -2,6 +2,7 @@
 module quic
 
 import encoding.hex
+import crypto.ecdsa
 
 // RFC 8446 §4.4.3's own worked example: transcript hash = 32 bytes of
 // 0x01, server context -> this exact 130-byte signed content. Extracted
@@ -220,3 +221,97 @@ fn test_parse_certificate_verify_rejects_truncated_header() {
 	}
 	assert false, 'expected an error for a header shorter than 4 bytes'
 }
+
+// encode_certificate / encode_certificate_verify (Phase 13a, server-role
+// construction). Round-tripped through this same file's own
+// parse_certificate/parse_certificate_verify, the same real cross-check
+// discipline as tls13_server_hello_test.v's build_server_hello tests.
+
+fn test_encode_certificate_round_trips_through_parse_certificate() {
+	entries := [
+		CertificateEntry{
+			cert_data: []u8{len: 300, init: 0x30}
+		},
+		CertificateEntry{
+			cert_data: []u8{len: 150, init: 0x31}
+		},
+	]
+	msg := encode_certificate(entries)!
+	parsed_msg, consumed := parse_handshake_message(msg)!
+	assert consumed == msg.len
+	assert parsed_msg.typ == .certificate
+	result := parse_certificate(parsed_msg.body)!
+	assert result.certificate_request_context.len == 0
+	assert result.certificate_list.len == 2
+	assert result.certificate_list[0].cert_data == entries[0].cert_data
+	assert result.certificate_list[1].cert_data == entries[1].cert_data
+}
+
+fn test_encode_certificate_rejects_empty_list() {
+	encode_certificate([]CertificateEntry{}) or {
+		assert err.msg().contains('must not be empty')
+		return
+	}
+	assert false, 'expected an error for an empty certificate_list'
+}
+
+fn test_encode_certificate_rejects_entry_with_extensions() {
+	entries := [
+		CertificateEntry{
+			cert_data:  []u8{len: 10, init: 0x30}
+			extensions: [TlsExtension{
+				typ:  0x1234
+				data: []u8{}
+			}]
+		},
+	]
+	encode_certificate(entries) or {
+		assert err.msg().contains('extensions must be empty')
+		return
+	}
+	assert false, 'expected an error for a CertificateEntry carrying extensions'
+}
+
+// test_encode_certificate_verify_round_trips_through_parse_certificate_verify
+// verifies the WIRE FRAMING (algorithm field, signature length prefix) is
+// correct and that the signature this function produces is plausible ECDSA
+// DER output -- non-empty, and different for different transcript hashes
+// (a constant/garbage signature would fail this). It does NOT
+// cryptographically verify the signature against the public key: this
+// codebase has no PublicKey.verify() exposed by crypto.ecdsa and no EC
+// certificate fixture to build an mbedtls_pk_context from, the SAME
+// documented gap Phase 2c's own x509_standalone_signature_test.v already
+// states ("No EC private key exists anywhere in this repo, so the ECDSA
+// path is tested only via rejecting an incompatible key") -- not silently
+// skipped, stated here for the same reason.
+fn test_encode_certificate_verify_round_trips_through_parse_certificate_verify() {
+	_, priv_key := ecdsa.generate_key()!
+	transcript_hash := []u8{len: 32, init: 0x01}
+
+	msg := encode_certificate_verify(sig_scheme_ecdsa_secp256r1_sha256, priv_key, transcript_hash)!
+	parsed_msg, consumed := parse_handshake_message(msg)!
+	assert consumed == msg.len
+	assert parsed_msg.typ == .certificate_verify
+
+	result := parse_certificate_verify(parsed_msg.body)!
+	assert result.algorithm == sig_scheme_ecdsa_secp256r1_sha256
+	assert result.signature.len > 0
+
+	other_transcript_hash := []u8{len: 32, init: 0x02}
+	other_msg := encode_certificate_verify(sig_scheme_ecdsa_secp256r1_sha256, priv_key,
+		other_transcript_hash)!
+	_, other_consumed := parse_handshake_message(other_msg)!
+	other_parsed, _ := parse_handshake_message(other_msg)!
+	other_result := parse_certificate_verify(other_parsed.body)!
+	assert other_consumed == other_msg.len
+	assert other_result.signature != result.signature
+}
+
+fn test_encode_certificate_verify_rejects_unimplemented_algorithm() {
+	_, priv_key := ecdsa.generate_key()!
+	encode_certificate_verify(sig_scheme_rsa_pss_rsae_sha256, priv_key, []u8{len: 32}) or {
+		assert err.msg().contains('not implemented yet')
+		return
+	}
+	assert false, 'expected an error for an unimplemented signing algorithm'
+}

vlib/net/quic/tls13_messages.v

@@ -117,6 +117,20 @@ pub fn compute_finished_verify_data(base_secret []u8, transcript_hash []u8) ![]u
 	return hmac.new(finished_key, transcript_hash, sha256.sum256, sha256.block_size)
 }
 
+// build_finished constructs a complete Finished handshake message (RFC 8446
+// §4.4.4) from `base_secret`/`transcript_hash`, framed via
+// encode_handshake_message. Side-agnostic like compute_finished_verify_data
+// itself, which this function wraps directly -- the caller picks which
+// traffic secret to sign with (client_handshake_traffic_secret for the
+// client's own Finished, server_handshake_traffic_secret for the server's)
+// and which transcript_hash checkpoint applies; see
+// compute_finished_verify_data's own doc comment for the exact checkpoint
+// each side uses.
+pub fn build_finished(base_secret []u8, transcript_hash []u8) ![]u8 {
+	verify_data := compute_finished_verify_data(base_secret, transcript_hash)!
+	return encode_handshake_message(.finished, verify_data)!
+}
+
 // verify_finished checks a peer-supplied Finished message's verify_data
 // against the expected value computed from our own key schedule and
 // transcript state, using a constant-time comparison

vlib/net/quic/tls13_messages_test.v

@@ -174,3 +174,19 @@ fn test_verify_finished_rejects_stale_transcript_hash() {
 	peer_verify_data := hex.decode(rfc8448_server_verify_data)!
 	assert verify_finished(base_secret, stale_transcript_hash, peer_verify_data)! == false
 }
+
+// build_finished (Phase 13a, server-role construction) -- tested against
+// the SAME real RFC 8448 §3 vector the functions above already use, not
+// just round-tripped against this module's own code, since this function
+// is a thin wrapper around already-vector-verified
+// compute_finished_verify_data.
+fn test_build_finished_matches_rfc8448_vector() {
+	base_secret := hex.decode(rfc8448_server_hs_traffic_finished)!
+	transcript_hash := hex.decode(rfc8448_transcript_hash_ch_thru_certverify)!
+	msg := build_finished(base_secret, transcript_hash)!
+
+	parsed_msg, consumed := parse_handshake_message(msg)!
+	assert consumed == msg.len
+	assert parsed_msg.typ == .finished
+	assert parsed_msg.body == hex.decode(rfc8448_server_verify_data)!
+}