Bootstrap a lab SCION CP-PKI (cppkigen)

This cookbook shows how to use the cppkigen tool to bootstrap and operate the SCION Control Plane PKI (CP-PKI) cryptographic material for a test ISD in a lab environment. It walks through creating the Trust Root Configurations (TRCs), signing appliance certificate signing requests (CSRs), and the day-two operations of updating a TRC, adding an AS, and recovering lost state.

Lab and test deployments only

cppkigen is not for production. All voting and root private keys are derived deterministically from a hardcoded, public seed. Anyone with the binary can mint valid certificates for any TRC it produced! Two tripwires keep it on the lab side:

• It refuses to operate outside the SCION private-use ranges: ISD 1–64, AS ff00:0:0/32 and ffaa:0:0/24.
• Every TRC it produces carries a not-for-production marker, and cppkigen sign refuses TRCs without it.

For production, run a proper TRC signing ceremony (see Bootstrap SCION CP-PKI for more information).

Overview

cppkigen is stateless. Its working directory holds only two kinds of files: one *.topo topology file and the TRC files (one chain per ISD). No private keys are ever stored on disk. Because the voting and root keys are derived deterministically from (ISD-AS, role, generation), the tool recovers any private key by matching derived candidates against the public keys embedded in the TRC. The TRC is therefore both the trust anchor and the key database.

This guide uses the following example topology of two ISDs:

ISD	AS	Role	Appliances
16	16-ffaa:0:10	core, voting, authoritative, issuing	1 CORE
16	16-ffaa:0:11	issued by 16-ffaa:0:10	1 EDGE
17	17-ffaa:0:20	core, voting, authoritative, issuing	2 CORE
17	17-ffaa:0:21	issued by 17-ffaa:0:20	2 EDGE

Install cppkigen

Download cppkigen from cloudsmith and make it executable:

curl -1sLf -O 'https://dl.cloudsmith.io/public/anapaya/public/raw/versions/latest/cppkigen'
chmod +x cppkigen

Check that it runs:

./cppkigen --help

Run it on a CORE appliance

You do not need a separate external host. We recommend installing and running cppkigen directly on one of your CORE appliances. In this example 16-ffaa:0:10. This keeps the crypto material close to where it is used and avoids managing an extra machine.

This is safe because the tool is stateless: the working directory holds only the topology file and the TRCs, never private keys. If you lose the working directory, you can recover it from a TRC that is still installed on an appliance. See Recover lost state for more information.

Define the topology

The cppkigen tool reads a *.topo file describing the CP-PKI attributes of each AS from its working directory. To get started, create lab-cppki/lab.topo with the following contents:

lab-cppki/lab.topo

ASes:
  "16-ffaa:0:10":
    core: true
    voting: true
    authoritative: true
    issuing: true
  "16-ffaa:0:11":
    cert_issuer: 16-ffaa:0:10
  "17-ffaa:0:20":
    core: true
    voting: true
    authoritative: true
    issuing: true
  "17-ffaa:0:21":
    cert_issuer: 17-ffaa:0:20

Each ISD needs at least one voting and one issuing AS. If a cert_issuer is specified, it defines which AS issues the certificate chain for that AS. For non-issuing ASes, the cert_issuer field is required, issuing ASes can use it to reference a different issuer than themselves.

Bootstrap the ISDs

To bootstrap the CP-PKI for the ISDs, we need to create the initial TRCs. Run the following command:

Initialize TRCs on cppkigen host

./cppkigen -d lab-cppki init

This creates one TRC for ISD 16 and one for ISD 17 in the lab-cppki working directory. init refuses a working directory that already contains TRCs unless you pass --force (which restarts the TRC history). This command should be run exactly once for the whole topology. Only run this from your designated cppkigen host (for example, the CORE appliance 16-ffaa:0:10). The TRCs then need to be distributed to all appliances in the ISD, as described in the next section.

tip

The TRC files are created with a default validity of 3 years. You can override this with the --validity flag. E.g., --validity 5y will set the validity to 5 years. Eventually, the TRC will expire and you will need to update it. See Update and distribute a TRC for more information.

Install the TRC and certificate chain

In order to take part in the SCION network, each appliance needs to have all the TRCs, and a valid certificate chain for its AS. Follow these steps to install the required cryptographic material. We use the appliance's standard endpoints, documented in Provision SCION AS certificate and TRC.

important

You must run the following step for every appliance. In every step, we indicate if it should be run on the cppkigen host or on the appliance itself. The example below executes the actions required for the placeholder $ISD_AS. Replace it with your desired value, e.g., 16-ffaa:0:11. If an AS consists of multiple appliances, you will need to run the same steps on each appliance, because the private keys are generated on the appliance and never leave it.

Install the TRCs

Each appliance needs to have all TRCs available. Follow these steps to install them.

1. Use cppkigen instruction bundle command to get an appliance-cli command that you can copy and paste into the appliance terminal to install the TRC bundle. This includes all the TRCs that were generated by init.

   Create TRC install instructions on cppkigen host

   ./cppkigen -d lab-cppki instruction bundle

2. Run the command returned in the output on all appliances to install the TRC bundle.

3. Verify that the TRCs are installed on the appliance:

   Verify TRC installation on appliance

   appliance-cli get cppki/trcs

Alternative: Install TRC bundle via file

If you want to install the TRC bundle via file instead. E.g., because you cannot copy and paste the command to the appliance shell. You can create a TRC bundle file, copy it to the appliance, and install it.

1. Create the TRC bundle file:

   Create TRC bundle on cppkigen host

   ./cppkigen -d lab-cppki bundle > bundle.trc

2. Manually copy the bundle.trc file to the appliance.

3. Install the TRC bundle on the appliance:

   Install TRC bundle on appliance

   appliance-cli post cppki/trcs < bundle.trc

Install the certificate chain

To take part in the SCION network, each appliance needs a valid certificate chain for its AS. Each appliance generates its own CSR and private key. Generate the CSR on the appliance as described in Provision SCION AS certificate and TRC.

1. Generate the CSR and store it in a .csr file on the appliance:

   Create CSR on appliance

   echo '{"subject": {"isd_as": "$ISD_AS"}}' | appliance-cli post cppki/csrs --raw > $ISD_AS.csr

2. Copy the CSR to the cppkigen host.

3. Sign the CSR into a full AS certificate chain:

   Sign CSR on cppkigen host

   ./cppkigen -d lab-cppki sign $ISD_AS.csr -o $ISD_AS.pem

   note

   The issuing CA is automatically selected based on the subject's cert_issuer from the topology. If the AS does not exist in the topology, or you want to select a different issuer, use the --ca flag to override the mapping.

4. Copy the signed certificate chain back to the appliance.

5. Install the certificate chain on the appliance:

   Install certificate on appliance

   appliance-cli post cppki/certificates < $ISD_AS.pem

   note

   The appliance verifies the chain against the active TRC of the local ISD before adding it. Make sure you have installed the TRC first.

6. Confirm everything is properly installed:

   Verify installation on appliance

   appliance-cli get cppki/certificates

At this point, the appliance has a valid certificate chain and can start participating in the SCION network. Repeat these steps for every appliance in the AS.

Certificate Expiration

The certificate chain will expire eventually. By default cppkigen creates certificates that expire 2 seconds before the TRC expiry to ensure they are valid for a sufficiently long time. To re-issue an expiring certificate, simply re-run the CSR creation and signing steps. If the TRC is close to expiry, you need to update it first. See Update and distribute a TRC for more information.

Check consistency

You can check the consistency of the lab crypto material at any time with the status command. It checks that the TRCs are consistent with the topology, and they are not expired.

./cppkigen -d lab-cppki status

tip

The tool will report any inconsitencies, such as missing TRCs or expired TRCs, and will inform you how to remedy the situation. If you have lost your working directory, you can recover it from a TRC that is still installed on an appliance. See Recover lost state for more information.

Update and distribute a TRC

A TRC update is needed when:

• the TRC is close to expiry
• a core AS is added or removed
• an issuing AS is added or removed

Edit lab-cppki/lab.topo to reflect the desired state, then create the updates:

./cppkigen -d lab-cppki update

The update command creates a TRC update for every ISD whose latest TRC diverges from the topology, and leaves TRCs for ISDs that already match untouched. All updates are sensitive updates, signed by the sensitive voters of the predecessor TRC. Embedded certificates that would expire before the new TRC are rotated automatically; use --rotate-root / --rotate-voting to force rotations.

Install on all appliances

Distribute the updated TRC to every appliance in the ISD by installing it the same way as the initial TRC. See the appliance crypto-provisioning docs for the full TRC installation flow.

Root rotation invalidates AS chains

After a root rotation, existing AS certificate chains only remain valid for the grace period (--grace-period, default 30d). Re-issue them with cppkigen sign and reinstall them as described in Install the certificate chain.

Add an AS

The mechanism to add an AS depends on whether the AS changes the ISD's trust anchors. New ASes that are not core or issuing do not change the trust anchors, and are therefore the simplest to add. Only a new certificate chain is needed. If a new core AS or issuing AS is added, the trust anchors change and a TRC update is needed.

Non-core, non-issuing AS

A plain AS that is issued by an existing CA does not change the trust anchors, so no TRC update is needed. Add it to the topology and sign its CSR.

For example, to add 16-ffaa:0:12 issued by 16-ffaa:0:10 the following steps are required.

1. Add the AS in the topology:

   cat <<EOF >> lab-cppki/lab.topo
     "16-ffaa:0:12":
       cert_issuer: 16-ffaa:0:10
   EOF

2. Sign its CSR as described in Install the certificate chain.

Core or issuing AS

An AS that is core and/or issuing changes the trust anchors of the ISD, so it must be included in a TRC update.

For example, to add a new issuing core AS 16-ffaa:0:13 the following steps are required.

1. Add the AS in the topology with the correct attributes:

   cat <<EOF >> lab-cppki/lab.topo
     "16-ffaa:0:13":
       core: true
       voting: true
       authoritative: true
       issuing: true
   EOF

2. Update the TRC to include it and distribute the new TRC. See Update and distribute a TRC:

   ./cppkigen -d lab-cppki update

3. Sign its CSR as described in Install the certificate chain.

Add an ISD

A new ISD requires a new TRC. At a minimum, it requires a core and issuing AS. To bootstrap the new ISD, we also use the update command. Add the AS(es) to lab-cppki/lab.topo with the correct attributes

For example, to create a new ISD a new issuing core AS and non-core AS, follow these steps.

1. Add the new ISD and its ASes to the topology:

   cat <<EOF >> lab-cppki/lab.topo
     "18-ffaa:0:30":
       core: true
       voting: true
       authoritative: true
       issuing: true
     "18-ffaa:0:31":
       cert_issuer: 18-ffaa:0:30
   EOF

2. Then, bootstrap the new TRC. See Update and distribute a TRC:

   ./cppkigen -d lab-cppki update

   Make sure to distribute the new TRC to all appliances. Otherwise, ASes in the existing ISDs will not be able to verify the new TRC and will reject any control plane messages from the new ISD.

3. Sign the new AS's CSR as in Install the certificate chain.

Recover lost state

Because cppkigen stores no keys, a lost working directory is recoverable as long as a TRC still exists somewhere in the lab (on an appliance, or in the system TRC directory).

1. Recreate the topology file. Write lab-cppki/lab.topo again with the same AS definitions.

2. Recover the TRC. update, sign, and status automatically import newer TRCs from the system TRC directory (default /etc/scion/crypto/trcs, configurable with --system-trc-dir), accepting only verifiable cppkigen-produced TRCs. If your working directory is empty, place a TRC downloaded from an appliance into that directory (or point --system-trc-dir at it).

3. Run an update if needed:

   ./cppkigen -d lab-cppki update

   If the recovered TRC already matches the topology, the tool detects this and reports that the TRC is up to date — it makes no change. You only get a new TRC if the topology has actually diverged.

Keys are recoverable, TRCs are not

Private keys are deterministic and always recoverable from a TRC. Certificates are not (they carry timestamps, serial numbers, and signatures). A TRC that is lost from the working directory and from every system in the lab cannot be regenerated.