Skip to main content

Provision SCION AS certificate and TRC

The SCION Control Plane PKI (CP-PKI) is built around the concept of federated trust. There is no single entity that defines whom to trust in the SCION network. Each ISD announces their own Trust Root Configuration (TRC) that anchors all of the trust inside that ISD. The TRCs are needed to verify the authenticity of the SCION control plane data.

In order for the Anapaya appliance to join the SCION network and communicate with other nodes, it has to be configured with a set of trusted TRCs. Furthermore, for the appliance to participate in the SCION control plane, a SCION CP-PKI AS certificate and the associated private key are necessary.

This tutorial first introduces the basic concepts of the SCION Control Plane PKI, namely TRC, CA certificate, and AS certificate. It then explains how to provision and inspect TRCs, as well as CP- PKI certificates.

Overview​

Trust root configuration (TRC)​

The SCION TRC is a signed collection of X.509v3 certificates and additional ISD policy information. A TRC acts as a distribution mechanism for the trust anchors of the local ISD. It enables securing the control plane interactions and thus is an integral part of the SCION infrastructure.

A set of trusted TRCs are required for the appliance to join the SCION network and communicate with other nodes. These TRCs build the trust bases for verifying all of the control plane data that is exchanged in the SCION protocol. At the very least, the TRC of the local ISD of the appliance needs to be configured to communicate with the direct neighbors and all the ASes in the ISD.

To communicate with a SCION AS in another ISD, you need to install the TRC of that ISD and the TRCs of all ISDs on at least one path reaching to that AS. This ensures that the appliance can verify all the necessary control plane data to reach these remote ASes.

Control Plane Public Key Infrastructure (CP-PKI) certificates​

Trust within an ISD is rooted in the TRC. The TRC contains one or more root certificates, which are used to sign new CA Certificates, which are in turn used to sign one or more AS Certificates.

SCION certificates are x.509v3 certificates. Every certificate has a subject (the entity that owns the certificate) and an issuer (the entity that issued the certificate). Like in Web PKI, in SCION sometimes both the subject and the issuer can be the same entity.

TRC handling​

Installing TRCs​

A TRC is created in a TRC ceremony where the voters of the ISD meet in person to sign an agreed-upon TRC. As part of the ceremony, the public keys of all voters are exchanged. More details on this can be found in TRC Signing Ceremony.

Installing a TRC​

The appliance exposes an endpoint to install a TRC. For further information, check out the documentation for this endpoint: Add TRC.

Install a TRC using the appliance CLI or API.

appliance-cli post cppki/trcs < $PATH_TO_TRC_FILE

Installing a TRC bundle​

When your appliance does not have any TRCs installed, you can use the Add TRC bundle endpoint to install the full chain of TRCs at once. You can directly copy and execute the installation command for each ISD from Isolation Domains Overview, or alternatively download the TRC bundles from Isolation Domains Overview and use the appliance CLI or API to install the bundle.

appliance-cli post cppki/trcs/bundle < $PATH_TO_TRC_BUNDLE

The given TRC is first validated before it is added to the trust store. Only valid TRCs are added to the trust store.

danger

You can use the force query parameter to force the addition of the TRC regardless of its validity.

Adding a TRC forcefully is a dangerous operation and you should only perform it if you are completely aware of the implications.

Inspecting TRCs​

Inspecting a TRC​

Inspect the TRC contents in a human-readable form using the scion-pki tool.

scion-pki trc inspect $PATH_TO_TRC_FILE
note

This command shows the content of the TRC file itself and not the installed TRC on the appliance.

Listing installed TRCs​

You can see the list of TRCs which are configured on the appliance by running the command:

appliance-cli get cppki/trcs
note

This endpoint returns the list of TRCs that are installed on the appliance. It does not return the content of the TRC files themselves.

Certificate handling​

Generating a certificate signing request​

For the appliance to participate in the SCION control plane, e.g., to propagate SCION beacons, or transform beacons into proper SCION path segments, a SCION CP-PKI AS certificate and the associated private key are necessary. The SCION CP-PKI AS certificate is used to verify the authenticity of the control plane material that is produced and signed by this appliance.

A SCION CP-PKI AS certificate must be requested from a CA ASes in the local ISD. Initially, the certificate must be requested out-of-band but is renewed automatically on a periodic basis ever after.

To request the initial certificate, create a Certificate Signing Request (CSR). This CSR then needs to be signed by a local CA AS. The result is a certificate chain consisting of the issued SCION CP-PKI AS certificate and the issuing SCION CP-PKI CA certificate. This certificate chain then needs to be installed on the appliance.

To learn about generating a new CSR, check out the documentation of the endpoint Create CSR. The endpoint documentation explains what entries the request and response body include. To make a request, you need to understand and choose a suitable value for each entry.

Create a file named cp-as.json, which matches the request structure of the endpoint. This, in particular, must include the ISD-AS number. The remaining entries are optional in the SCION CP-PKI on the technical level. However, their format and presence might be required by a policy that is defined by your local ISD.

Generate a fresh CSR and store it in the file name cp-as.csr:

appliance-cli post cppki/csrs <cp-as.json --raw > cp-as.csr

Check the content of the created CSR

scion-pki certificate inspect cp-as.csr

Installing AS certificates​

After generating a CSR, you can create a proper SCION CP-PKI AS certificate. This is an out-of-band mechanism and is defined by the CA that is responsible for issuing your initial AS certificate. After you have received back the SCION CP-PKI AS certificate as part of a full SCION CP-PKI certificate chain, you can install it on the appliance.

tip

If the appliance is part of a cluster and a sibling appliance already has a valid AS certificate, you can Request AS certificate via sibling appliance.

Inspect the contents of the certificate chain, in the file named cp-as.pem.

scion-pki certificate inspect cp-as.pem

For further information, check out the documentation of the endpoint Add certificate. This explains what the request and response bodies look like.

You can install the AS certificate cp-as.pem on the appliance by running::

appliance-cli post cppki/certificates <cp-as.pem

This first verifies the certificate chain against the active TRC of the local ISD before it is added. Only verifiable certificate chains are added. However, the endpoint provides the option to forcefully use a certificate chain regardless of its validity or verifiability.

note

If the certificate chain fails to verify, it might be that a TRC is missing which needs to be installed first.

warning

Adding a certificate chain forcefully is a dangerous operation and you should only perform it if you are completely aware of the implications.

Inspecting AS certificates​

Run the following command to list all the installed certificate chains:

appliance-cli get cppki/certificates

Manually renewing AS certificates​

The appliance periodically renews the SCION CP-PKI AS certificate. No manual interaction is necessary during normal operation. During the periodic renewal, the distinguished name of the predecessor SCION CP-PKI AS certificate is used.

Our appliance management API allows manually triggering a certificate renewal that runs in-band and does not need the manual CSR creation. This is useful, for example, to change the distinguished name or force the use of a new certificate.

For further information, check out the documentation for the endpoint Renew certificate. The request body is similar to the one from Create CSR. You can actually modify the cp-as.json file that we mentioned earlier to reflect the updates that you want to make. Then, by running the following command you can trigger a manual certificate renewal:

appliance-cli post cppki/certificates/renew <cp-as.json

Request AS certificate via sibling appliance​

When there are multiple appliances in one AS and at least one of the appliances already has a valid AS certificate, a new certificate can directly be requested from such an appliance.

In describing this process, we assume appliance A has a valid AS certificate and appliance B does not.

  1. Create a CSR as on appliance B as described in Generating a certificate signing request.

  2. Copy the CSR to appliance A, and save it there as cp-as.csr.

  3. On appliance A, request a new AS certificate.

    appliance-cli post cppki/certificates/request csr: @cp-as.csr --raw

  4. Copy the certificate to appliance B and save it as cp-as.pem.

  5. On appliance B, inspect and install the AS certificate chain as described in Installing AS certificate.