Skip to content

docs(signatures): cite the RFC 9421 sections that define the ECDSA raw r||s rule - #963

Merged
damaz91 merged 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/signatures-ecdsa-rfc-section
Oct 26, 2026
Merged

damaz91 merged 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/signatures-ecdsa-rfc-section

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

signatures.md cites RFC 9421 §3.3.1 for the ECDSA raw r||s rule. §3.3.1 is RSASSA-PSS Using SHA-512. The rule the sentence states is defined in §3.3.4 for P-256 and §3.3.5 for P-384, which are the two curves the same bullet goes on to name.

Observed, docs/specification/signatures.md L494 to L497 on main d9c18e0d:

  • ECDSA signatures MUST use fixed-width raw r||s encoding per
    RFC 9421 §3.3.1, not ASN.1/DER. The signature value is the
    concatenation of r and s as fixed-length unsigned big-endian
    integers: 64 bytes for P-256 (32 + 32), 96 bytes for P-384 (48 + 48).

Expected, from RFC 9421 §3.3:

Section Title
3.3.1 RSASSA-PSS Using SHA-512
3.3.2 RSASSA-PKCS1-v1_5 Using SHA-256
3.3.3 HMAC Using SHA-256
3.3.4 ECDSA Using Curve P-256 DSS and SHA-256
3.3.5 ECDSA Using Curve P-384 DSS and SHA-384
3.3.6 EdDSA Using Curve edwards25519
3.3.7 JSON Web Signature (JWS) Algorithms

§3.3.4 is also where the encoding this sentence describes is specified, in the same terms: "These encoded values are concatenated into a single 64-octet array consisting of the encoded value of r followed by the encoded value of s."

This PR changes the citation only. The requirement, the encoding, the byte counts and the DER prohibition are untouched.

Scope

One site. I swept every RFC 9421 citation in the file: L362 §2.3, L367 §2.1.2, L373 §3.2.1, L382 §2.3, L387 §4.3, L671 §4.3 and L855 §3.2.1 all resolve correctly against the RFC, and the EdDSA bullet immediately below cites RFC 8032 §5.1.6, which is correct for Ed25519. L495 is the only wrong one.

The same wrong citation is present at tag v2026-08-25 (cd78fb38) and on release/2026-08-25. I am happy to send the branch backport separately if that is wanted; this PR targets main only.

Verification

  • the repository pinned pre-commit run --files docs/specification/signatures.md: all applicable hooks Passed, exit 0. That includes validate-examples-changed, which needs ucp-schema on PATH; with a ucp-schema 1.4.1 binary on PATH it runs and passes rather than erroring out.
  • markdownlint-cli 0.47.0 with .github/linters/.markdownlint.json: exit 0 before and after the change, output byte identical.
  • RFC section titles and the §3.3.4 encoding sentence read from https://www.rfc-editor.org/rfc/rfc9421.txt rather than from memory.
  • reproduced from a fresh clone of main at d9c18e0d.

Note on neighbouring PRs

Six open PRs edit signatures.md: #618, #659, #699, #782, #785 and #938. None of them touches this bullet, and a trial merge of this change against each current head is clean. I noted the same citation in a comment on #659 as outside the scope of that change.

The number is also live on the published site: both https://ucp.dev/specification/signatures/ and https://ucp.dev/2026-08-25/specification/signatures/ carry it.

…w r||s rule

The ECDSA bullet cites RFC 9421 section 3.3.1 for fixed-width raw r||s encoding.
Section 3.3.1 is RSASSA-PSS Using SHA-512. The rule the sentence states is defined
in section 3.3.4 for P-256 and section 3.3.5 for P-384, the two curves the same
bullet goes on to name, and 3.3.4 states the encoding in the same terms: "These
encoded values are concatenated into a single 64-octet array consisting of the
encoded value of r followed by the encoded value of s."

Citation only. The requirement, the encoding, the byte counts and the DER
prohibition are unchanged.

One site: every other RFC 9421 citation in the file resolves correctly, and the
EdDSA bullet below correctly cites RFC 8032 section 5.1.6.
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage documentation Improvements or additions to documentation status:under-review area:common Issues and pull requests related to common protocol schemas and specifications and removed status:needs-triage Signal that the PR is ready for human triage labels Oct 16, 2026

@karangoel16 karangoel16 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked this against RFC 9421 itself, not just the PR body. §3.3.1 is RSASSA-PSS Using SHA-512 — the RFC's own registry table says so. The raw r||s rule the sentence describes lives in §3.3.4 for P-256 ("concatenated into a single 64-octet array") and §3.3.5 for P-384 (96-octet). The old citation was simply wrong.

One-line fix, nothing else to touch. Approving.

@sbeashwar sbeashwar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Reviewed aa82022a

@damaz91
damaz91 merged commit f9a1e39 into Universal-Commerce-Protocol:main Oct 26, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:common Issues and pull requests related to common protocol schemas and specifications documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants