Skip to main content

Control Plane PKI

Time estimate: 45 minutes

This hands-on exercise introduces the basic concepts of working with the SCION Control Plane PKI; how to configure trust roots, how to provision CPPKI certificates, and how to inspect the state of the appliance.

At the end of this hands-on exercise, you should be comfortable with requesting, configuring, and inspecting the cryptographic material that is used in the SCION control plane.

note

Unless stated otherwise, all commands are assumed to be run from the workspace directory on your training VM. The built-in terminal in the editor will put you automatically in the right directory. To open the built-in terminal use the Ctrl+` shortcut. Alternatively, you can click the Menu button in the top left, then select View -> Show Terminal . This will bring up the terminal and puts you in the correct working directory (~/workspace) for all the tasks in this training.

Overview​

Refer to the diagram below, which visualizes the network topology we work on in this hands-on session. The depicted infrastructure consists of an ISD, called Finance ISD, which has three ASes:

  • Webspeed (ISD-AS 1-ff00:1:1)
  • Corpbank Switzerland (ISD-AS 1-ff00:1:2)
  • Stabank Private Banking (ISD-AS 1-ff00:1:3)

The Webspeed AS consists of three sites in Zurich, Geneva, and Lugano. Each of these sites includes exactly one host. These hosts are called core.zurich.webspeed, core.geneva.webspeed, and core.lugano.webspeed, respectively. This is a core AS.

The Corpbank Switzerland AS has two sites, one in Geneva and one in Zurich. Both of them have a host, respectively called edge.zurich.corpbank and edge.geneva.corpbank. Furthermore, the Stabank Private Banking AS includes only one site, in Lugano, with one host, called edge.lugano.stabank. They are both leaf ASes and each of them is connected to the Webspeed AS via two links, as depicted in the diagram.

warning

TODO: Topology image placeholder

Over the course of this lab, you will be working in a cloud-hosted playground of the SCION infrastructure. All the ASes run in a virtualized environment on a cloud machine.

Preparation​

important

This step is required to follow the hands-on.

In this task, you will work with a configured appliance that is only missing the required SCION CPPKI cryptographic material. You will need to run a setup script to prepare the environment. The appliance that we are targeting in this hands-on is edge.lugano.stabank.

From the cloud machine, run the setup script:

operator@training:~/workspace$ ./appliance_cppki_exercise setup
note

Unless stated otherwise, all commands are assumed to be run from the workspace directory on your training VM. The built-in terminal in the editor will put you automatically in the right directory. To open the built-in terminal use the Ctrl+` shortcut. Alternatively, you can click the Menu button in the top left, then select View -> Show Terminal . This will bring up the terminal and puts you in the correct working directory (~/workspace) for all the tasks in this training.

After the hands-on exercise is completed, the topology is in a working state. In case something is not working properly and you need to revert the changes, you can run the following command:

operator@training:~/workspace$ ./appliance_cppki_exercise restore
note

In this hands-on you will be asked to search the documentation for appropriate endpoints. You can find the documentation Anapaya CLI documentation

Task 1. Working with Roots of Trust​

The SCION Control Plane PKI is built around the concept of federated trust. There is no single entity that defines who to trust in the SCION network. Each ISD announces their own Trust Root Configuration (TRC) that anchors all of the trust inside that ISD. These 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. These TRCs build the trust anchors for verifying all of the control plane data that is exchanged in the SCION protocol, e.g., SCION path segments. 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.

Task 1.1. Install a Trust Root​

In this task, you will install the trusted TRC on the edge.lugano.stabank appliance. In the working directory of the training machine, you will find the trusted TRC as ISD1-B1-S1.trc. You can inspect the contents with the help of the scion-pki tool:

operator@training:~/workspace$ scion-pki trc inspect ISD1-B1-S1.trc

Check the appliance management API and try to find the appropriate endpoint for installing a trusted TRC. Install the TRC with the endpoint you have discovered.

Solution

The documentation for the endpoint can be found at Add TRC

operator@training:~/workspace$ appliance-cli context select edge.lugano.stabank
operator@training:~/workspace$ appliance-cli post cppki/trcs <ISD1-B1-S1.trc

Task 1.2. List installed Trust Roots​

The appliance should now be configured with the trusted TRC. Use the appliance management API to check that this is indeed the case.

Solution

The documentation for the endpoint can be found at: List TRCs

Run the following command to list all the installed TRCs:

operator@training:~/workspace$ appliance-cli get cppki/trcs

Task 2. Working with SCION AS Certificates​

In order for the appliance to participate in the SCION control plane, e.g., to propagate SCION beacons or to 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. SCION CPPKI AS certificates are regular x.509v3 certificates with a SCION specific profile.

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. Afterwards, 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 the CA ASes. 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.

Task 2.1. Generate a Certificate Signing Request​

We are interacting with the edge.lugano.stabank appliance again. Check the appliance management API and try to find the appropriate endpoint for generating a fresh CSR.

Solution

The documentation for the endpoint can be found at: Create CSR

The endpoint expects a request body that defines the distinguished name of the subject for the CSR.

Create a cp-as.json file in your current working directory in the expected format.

The ISD-AS number must be set to 1-ff00:1:3. The other values are optional, and you can choose them to your liking.

Solution
Loading...

Then, generate a fresh CSR and store it in the cp-as.csr file in the editor working directory.

Solution

The documentation for the endpoint can be found at: Create CSR

operator@training:~/workspace$ appliance-cli post cppki/csrs <cp-as.json --raw > cp-as.csr

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

operator@training:~/workspace$ scion-pki certificate inspect cp-as.csr

Task 2.2. Install the signed SCION AS Certificate​

Now that you have created the CSR, we need to create a proper SCION CPPKI AS certificate based on it. In a real deployment setup, this is an out-of-band mechanism. For the purpose of this hands-on exercise, we have built a small script that takes care of this. Run the following command:

operator@training:~/workspace$ ./appliance_cppki_exercise request cp-as.csr cp-as.pem

This command takes your CSR in cp-as.csr, requests an SCION CPPKI AS certificate, and writes the result to cp-as.pem.

You can inspect the contents of the certificate chain with scion-pki:

operator@training:~/workspace$ scion-pki certificate inspect cp-as.pem

Check the appliance management API and try to find the appropriate endpoint for installing the signed SCION CPPKI AS certificate. Install it with the endpoint you have discovered.

Solution

The documentation for the endpoint can be found at: Add certificate

operator@training:~/workspace$ appliance-cli post cppki/certificates <cp-as.pem

Task 2.3. List installed SCION AS Certificates​

The appliance should now be configured with the SCION CPPKI AS certificate. Use the appliance management API to check that this is indeed the case.

Solution

The documentation for the endpoint can be found at: List certificates

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

operator@training:~/workspace$ appliance-cli get cppki/certificates

Next, inspect the details of the SCION CPPKI AS certificate that you have just provisioned with the appliance management API.

Solution

The documentation for the endpoint can be found at: Get certificate Run the following command to list all the installed certificate chains:

operator@training:~/workspace$ appliance-cli get cppki/certificates

Find the id of the chain that you want to inspect. Then run the following command to get the details:

operator@training:~/workspace$ appliance-cli get cppki/certificates/<chain-id>

Congratulations, your appliance is now successfully configured with all the necessary cryptographic material to take part of the SCION control plane.

Task 2.4 Manually renew a SCION AS Certificate​

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.

With the help of the appliance management API, trigger a manual certificate renewal and change the organization to Stabank Private Banking and the country code to CH.

Solution

The documentation for the endpoint can be found at: Renew certificate

Modify the cp-as.json to contain the following contents

Loading...

Run the following command to manually renew the AS certificate:

operator@training:~/workspace$ appliance-cli post cppki/certificates/renew <cp-as.json