docs: cryptography fix, refactor and refer to draft by romshark · Pull Request #4933 · scionproto/scion

romshark · 2026-06-08T14:24:12Z

Instead of duplicating info on doc pages - simplify and refer to IETF drafts; specifically HTML in the latest version (currently 13: https://www.ietf.org/archive/id/draft-dekater-scion-pki-13.html)

Docs are giving a big picture introduction and leave the details to the actual spec.

This also fixes incorrect docs:

Regular voting cert validity: align with the draft (1y -> 5y).
Sensitive voting cert: "5 year" -> "5 years" wording.
Docs copyright: bump to 2026.

tzaeschke

I think we need to clarify what the intention of this document is.

I think the intention should be to give the reader a good understanding of how it works. The details can be left to the spec.

Currently the document seems a bit confused, some things are mentioned multiple times, e.g. sensitive vs regular updates and that the former concern policy and quorum). Other things are not mentioned at all anymore, like who is actually voting on these updates and what quorum and policy mean.

Basically, I would keep most of the text and remove only normative language and code blocks.

tzaeschke · 2026-06-16T11:20:04Z

-All constraints in :ref:`general-certificate-requirements` apply to **CP Root Certificates**.
+**CP Root Certificates** state which ASes are CA ASes for an ISD. They are
+self-signed CA certificates owned by CA ASes, and are embedded in TRCs to
+bootstrap trust (see the :doc:`TRC Specification <trc>`). Their full profile —


Remove "-"?

tzaeschke · 2026-06-16T11:23:08Z

-(``issuer`` and ``subject`` are the same entity). They are owned by CA ASes.
-
-**CP CA Certificates** are signed by **CP Root Certificates**.
+**CP CA Certificates** are used by CA ASes to sign **CP AS Certificates**. They


Remove "-"?
Also, this paragraph seems like an exact copy of the previous section (replacing some keywords only).

tzaeschke · 2026-06-16T11:36:46Z

-    AttributeValue  ::=  ANY
-
-    SignatureValue  ::=  OCTET STRING
+=================


Suggested change

=================

=================

-----------------

Not sure this should be a new Chapter?

tzaeschke · 2026-06-16T11:43:26Z

+are specified in `Certification Path — Trust Anchor Pool
+<https://www.ietf.org/archive/id/draft-dekater-scion-pki-13.html#name-certification-path-trust-an>`_.

 Voting Certificate


This section doesn't appear to contain any(much) new information, maybe merge it with TRC Update above?

tzaeschke · 2026-06-16T11:46:45Z

-implies, that the signer infos can be reordered without affecting verification.
-
-**Two TRCs are equal, if and only if their payloads are byte equal.**
+Two TRCs are equal if and only if their payloads are byte-equal; this is sufficient


This section doesn't explain why equality is relevant and discussed here. Maybe just keep the old text?

tzaeschke · 2026-06-16T11:48:42Z

-votes are cast by a **Sensitive Voting Certificate**. In both cases, the relying
-party checks that all signatures are verifiable, and no superfluous signatures
-are attached.
+A TRC update is either a **regular update** (routine re-issuance with unchanged


I think we should keep the text about base numbers increments etc. This is important for the understanding how this works.

tzaeschke · 2026-06-16T11:59:53Z

 .. _trc-format:

 TRC Format
 ==========


I think much of the text in this section is actually useful, e.g. explaining authorative ASes, Voting ASes, core ASes. See my general comment.

+1, I think here it could be useful to add figure 1 or 2 from the PKI draft, since it gives the reader a quick overview

"MUST reject cryptographic algorithms not found on the list" is wrong.

nicorusti · 2026-06-18T14:28:38Z

Cryptography:

In the main page (Cryptography), have a brief paragraph explaining the purpose of it and scionproto's relation to the draft, something like:

SCION's control plane messages and path information are all authenticated. The verification of messages relies on the control-plane PKI or CP-PKI. It consists of a set of mechanisms, roles, and policies related to the management and usage of certificates, which enables the verification of signatures of, e.g., path-segment construction beacons (PCBs).
This implementation follows the SCION PKI specification in [IETF draft]

A question we often get is interop with existing PKI software. We should have some wording about that, and even link any compatible implementation (e.g. LibC SwissPKI https://www.swisspki.com/ and https://learn.anapaya.net/docs/technical-documentation/anapaya-scion-ca/ )

Certificate Specification

I think this page could be shrank a lot. It could just give an overview of each certificate type, and mention that there are additional constraints and extensions that are required, with a reference to the draft.
Subsections could only mention more implementation-focused details, that are sometimes not in the draft (e.g. the OIDs for the supported algorithms0

TRC

I think an overview picture here would be helpful, you could use figure 1 or 2 from the draft. Then you could briefly explain the role of various certificates contained in the TRC

Leaving more comments on the change directly

nicorusti · 2026-06-18T14:36:21Z


-This document contains the specification for **Control Plane (CP) Root
-Certificates**, **CP CA Certificates** and **CP AS Certificates**.
+SCION uses three types of X.509 v3 **Control Plane (CP) certificates** that build


Four, there are also Voting Certificates.

Additionally, SCION uses two **voting certificates** - the *sensitive voting certificate* and the *regular voting certificate* - which carry the keys that cast votes in the TRC update process (see the :doc:`TRC Specification <trc>`).

How about appending that after the list of CP certs?

I've applied this for now, but let me know whether it's good.

nicorusti · 2026-06-18T14:36:52Z

+- **CP Root Certificate** — a self-signed CA certificate, owned by a CA AS and
+  embedded in a TRC, that signals which ASes may act as certificate authorities in
+  an ISD.
+- **CP CA Certificate** — used by a CA AS to sign CP AS certificates.


IN the draft, we call them Issuing CA certificates. Not sure if you wan to align or not

nicorusti · 2026-06-18T14:44:39Z


 .. _cp-root-certificate:

 CP Root Certificate


Maybe this paragraph could go in the bullets in the introduction?

(same for CP CA Certificate and CP AS Certificate)

nicorusti · 2026-06-18T14:45:44Z

+Certificate
+<https://www.ietf.org/archive/id/draft-dekater-scion-pki-13.html#name-control-plane-root-certific>`_.

 The recommended maximum validity period of a **CP Root certificate** is 1 year.


Maybe in the intro you could mention that PKI relies on short-lived certificates, and that the recommended max validity is in the draft Table 2: Certificates

nicorusti · 2026-06-18T14:48:26Z

-verifiable at time of use. We cannot simply rely on them being verified on
-insert, since TRC updates that change the root key can invalidate a certificate
-chain.
+Most SCION control-plane messages (for example, each AS's hop information in a path


~~Most~~ SCION control-plane messages .. are signed

I think they are all signed

https://scionassociation.github.io/scion-cp_I-D/draft-dekater-scion-controlplane.html#name-distribution-of-cryptograph

Are ChainsRequest and ChainsResponse signed?

nicorusti · 2026-06-18T14:52:38Z

+   Cryptographic Material
+   <https://scionassociation.github.io/scion-cp_I-D/draft-dekater-scion-controlplane.html#name-distribution-of-cryptograph>`_.
+


There is also another section: 2.5. Renewal of Cryptographic Material

nicorusti · 2026-06-18T14:54:04Z

     Query: ISD
     Response: ISD, serial number, base number, signature

  The requester asks what the latest TRC for a given ISD known to the requestee


I think all the text below could be removed, and you could have just a little bit of text above explaining key interactions, then pointing to the spec for the RPCs.

nicorusti · 2026-06-18T14:58:28Z

+The TRC payload is a DER-encoded container holding the ISD's policy fields and the
+set of self-signed certificates that anchor trust for the ISD. Its schema, fields
+and the constraints on the certificate set are specified in `TRC Fields
+<https://www.ietf.org/archive/id/draft-dekater-scion-pki-13.html#name-trc-fields>`_.


I would specifically link its fields, but also its ASN.1 module in the appendix.

romshark self-assigned this Jun 8, 2026

romshark marked this pull request as ready for review June 15, 2026 11:46

romshark requested review from a team and oncilla June 15, 2026 14:43

tzaeschke reviewed Jun 15, 2026

View reviewed changes

Comment thread doc/cryptography/certificates.rst Outdated

tzaeschke reviewed Jun 15, 2026

View reviewed changes

Comment thread doc/cryptography/certificates.rst Outdated

doc: dedup crypto docs against SCION PKI draft

f8572ad

romshark force-pushed the docs-cryptography-fix-and-refer-to-draft branch from 2840b6a to f8572ad Compare June 15, 2026 18:26

romshark requested a review from tzaeschke June 15, 2026 18:51

tzaeschke reviewed Jun 16, 2026

View reviewed changes

romshark added 3 commits June 18, 2026 14:09

fix: Incorrect crypto algos requirement

b2acf17

"MUST reject cryptographic algorithms not found on the list" is wrong.

fix: Keep issuer close to original

84894c2

refactor: Improve title and formulation

c62eb25

nicorusti reviewed Jun 18, 2026

View reviewed changes

Comment thread doc/cryptography/certificates.rst Outdated

nicorusti reviewed Jun 18, 2026

View reviewed changes

Comment thread doc/cryptography/certificates.rst Outdated

nicorusti reviewed Jun 18, 2026

View reviewed changes

romshark added 6 commits June 18, 2026 17:11

refactor: Rename certificates section

7828b96

refactor: Rename TRC section

70a4574

refactor: Remove what's already stated in draft

2b9d2af

refactor: Simplify certificates.rst

9e5a91f

refactor: Remove unnecessary section

d0bf32f

fix: Grammar

32fb2b4

romshark added 2 commits June 18, 2026 19:51

fix: Grammar

cadcf52

fix: Add missing part

055a620

		Cryptographic Material
		<https://scionassociation.github.io/scion-cp_I-D/draft-dekater-scion-controlplane.html#name-distribution-of-cryptograph>`_.

Conversation

romshark commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tzaeschke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicorusti commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Cryptography:

Certificate Specification

TRC

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

romshark commented Jun 8, 2026 •

edited

Loading

nicorusti commented Jun 18, 2026 •

edited

Loading