Certificate/TRC Provisioning¶

The SCION Control Plane PKI (CPPKI) 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 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 CPPKI AS certificate and the associated private key are necessary.

We first give a brief introduction to the basic concepts of SCION Control Plane PKI, namely TRC, CA certificate, and AS certificate. Then, we explain how you can provision and inspect TRCs, as well as CPPKI certificates.

Trust Root Configuration¶

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 remote SCION ASes in other ISDs, you will need to install the TRC of their respective ISDs and all the ISDs on the path. This ensures that the appliance can verify all the necessary control plane data to reach these remote ASes.

CPPKI 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.

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.

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

Assume that you have a TRC called ISD1-B1-S1.trc. To install this TRC, you just need to run the following command:

curl -k https://${mgmt_address}/api/v1/cppki/trcs -X POST --data-binary "@ISD1-B1-S1.trc"

Hint

The base URL for the API on the host is https://${mgmt_address}/api/v1.
The --data-binary "@<path/to/file>" flag attaches the TRC as the HTTP request body payload.

Note

${mgmt_address} needs to be replaced with the actual management address of the appliance.

The given TRC is first validated before it is added to the trust store. Only valid TRCs are added to the trust store. You can use the force query parameter to force the addition of the TRC regardless of its validity.

Warning

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

When working with cryptographic materials, the scion-pki tool comes in handy very often. In particular, it can be used to verify TRC updates or inspect the TRC contents in a human-readable form. For example, you can inspect the contents of the TRC by running:

scion-pki trc inspect ISD1-B1-S1.trc

Inspecting TRCs¶

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

curl -k https://${mgmt_address}/api/v1/cppki/trcs

Alternatively, to inspect the list in a browser, you can navigate to https://${mgmt_address}/api/v1/cppki/trcs.

For further information, check out the documentation for this endpoint: List the TRC files. There are two related endpoints that are useful when working with TRCs: Get the TRC and List the TRC blob.

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 CPPKI AS certificate and the associated private key are necessary. The SCION CPPKI AS certificate is used to verify the authenticity of the control plane material that is produced and signed by this appliance.

A SCION CPPKI AS certificate needs to be requested from one of the CA ASes of the local ISD. The initial certificate is requested with an out-of-band mechanism. Afterward, the SCION CPPKI AS certificates are periodically renewed by the appliance in a fully automatic fashion.

To request the initial certificate, you will need to instruct the appliance to 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 CPPKI AS certificate and the issuing SCION CPPKI 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 an AS certificate signing request. As you can see, the endpoint documentation explains what entries the request and response body include and what they would look like by providing concrete examples. To make a request, you need to understand and choose a suitable value for each entry.

Assume that you have created 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 CPPKI on the technical level. However, their format and presence might be required by a policy that is defined by your local ISD.

To generate a fresh CSR and store it in a file, say cp-as.csr, you can run:

curl -k https://${mgmt_address}/api/v1/cppki/csrs -X POST --data '@cp-as.json' > cp-as.csr

To check the contents of the freshly created CSR, you can use openssl or scion-pki:

openssl req -in cp-as.csr -noout -text
scion-pki certificate inspect cp-as.csr

Installing AS Certificates¶

Assume that you have generated a fresh CSR. Building on that, we need to create a proper SCION CPPKI 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 CPPKI AS certificate as part of a full SCION CPPKI certificate chain, you can install it on the appliance.

You can inspect the contents of the certificate chain, which is written in a file called cp-as.pem, with openssl or scion-pki by running the command:

openssl x509 -in cp-as.pem -noout -text
scion-pki certificate inspect cp-as.pem

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

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

curl -k https://${mgmt_address}/api/v1/cppki/certificates -X POST --data-binary "@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¶

You can run the following command to list all the installed certificate chains:

curl -k https://${mgmt_address}/api/v1/cppki/certificates

Alternatively, you can inspect the list of installed certificate chains in a browser by navigating to https://${mgmt_address}/api/v1/cppki/certificates

For further information, check out the documentation of the endpoint List the certificate chains.

Manually Renewing AS Certificates¶

The appliance periodically renews the SCION CPPKI AS certificate. No manual interaction is necessary during normal operation. During the periodic renewal, the distinguished name of the predecessor SCION CPPKI 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 Manually renew an AS certificate chain. As you can see, the request body is very similar to the one from Create an AS certificate signing request. 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:

curl -k https://${mgmt_address}/api/v1/cppki/certificates/renew -X POST --data '@cp-as.json'