ISD CA Operations

Once a new ISD is established through the completion of a key signing ceremony, certificates can be generated for the Certificate Authorities and ASes of the ISD.

Trust within an ISD flows from 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.

The process of creating new CA Certificates is described in section CA Certificates. The process of creating new AS Certificates is described in section AS Certificates.

To follow the steps in this document, openssl version 3.0.14 or later is required.

Note

The following document is meant as an example for easily running a manual CA for testing purposes. In productive environments, these processes should be automated and proper CA software should be used.

CA Certificates

CA Certificates in SCION are always signed by a Root Certificate, which is contained in the TRC. Because the Root Certificate is usually owned by the same entity that also acts as a CA, the entity is able to perform the signing step by itself.

Creating the initial CA Certificate

The steps in creating a new CA Certificate are:

  1. Define the subject of the CA Certificate.

  2. Create the certificate using the Root Key.

The subject template has already been created in preparation for the TRC ceremony. Here is a reminder how it looks like:

cat << EOF > subject.tmpl
{
    "country": "{{.Country}}",
    "state": "{{.State}}",
    "locality": "{{.Location}}",
    "organization": "{{.Organization}}",
    "organizational_unit": "{{.OrganizationalUnit}}",
    "isd_as": "{{.ISDAS}}"
}
EOF

export ORG="{{.ShortOrg}}"

The steps in creating a new CA Certificate are:

  1. Define the configuration of the CA Certificate in accordance with the SCION requirements.

  2. Create a new key pair.

  3. Create a Certificate Signing Request using the key pair.

  4. Use the Root Key and the Certificate Signing Request to create the new CA Certificate.

The configuration is defined in a file. OpenSSL reads the file and creates a certificate that is compatible with SCION. An example configuration file is included below. Note that the file includes the text {{.ShortOrg}}; this text must be replaced with the shortname of your organization. For example, if your organization name is ExampleCorp, the line should contain name = ExampleCorp Secure CA Certificate.

cat << EOF > cp-ca.cnf
openssl_conf    = openssl_init
x509_extensions = x509_ext
req_extensions  = req_ext

[common_name]
name = {{.ShortOrg}} Secure CA Certificate

[x509_ext]
basicConstraints       = critical, CA:TRUE, pathlen:0
keyUsage               = critical, keyCertSign
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid

[req_ext]
basicConstraints       = critical, CA:TRUE, pathlen:0
keyUsage               = critical, keyCertSign
subjectKeyIdentifier   = hash

[ca_defaults]
default_days = 11

.include basic.cnf
EOF

Attention

SCION CA certificates have short lifetimes (a lifetime of 11 days is recommended).

Note

Note that the commands below assume that the CA Key and Root Key are found in the $KEYDIR folder, and have the names cp-ca.key and cp-root.key. If this is not the case, the commands should be adjusted with the proper key locations.

Once the file is ready, create the certificate using the scion-pki binary with the desired common name.

# Uncomment and set the appropriate values:
#
# STARTDATE="2020-06-24T14:00:00+02:00"
# ENDDATE="2020-07-01T14:00:00+02:00"

scion-pki certificate create \
    --ca cp-root.crt \
    --ca-key $KEYDIR/cp-root.key \
    --not-before $STARTDATE \
    --not-after $ENDDATE \
    --common-name "$ORG Secure CA Certificate" \
    --profile cp-ca \
    subject.tmpl \
    cp-ca.crt \
    $KEYDIR/cp-ca.key

Once the file is ready, the rest of the steps can be executed through a series of openssl commands.

These commands contain must be configured using the following values:

  • CA Certificate validity start date. Prior to this date, the certificate is not considered valid. To configure this, replace occurrences of $STARTDATE with the date in YYYYMMDDHHMMSSZ notation. For example, June 24th, 2020 UTC at noon is formatted as 20200624120000Z.

  • CA Certificate validity end date. After this date, the certificate is no longer valid. To configure this, replace occurrences of $ENDDATE with the desired date. This uses the same notation as the $STARTDATE.

  • Folder where the keys are contained. To configure this, replace $KEYDIR with the folder name.

Finally, to create the CA certificate, run the commands below.

# Uncomment and set the appropriate values:
#
# STARTDATE="20200624120000Z"
# ENDDATE="20200701120000Z"

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
    -pkeyopt ec_param_enc:named_curve -out $KEYDIR/cp-ca.key

openssl req -new -key $KEYDIR/cp-ca.key -config cp-ca.cnf \
    -utf8 -out cp-ca.csr

openssl ca -in cp-ca.csr -config cp-ca.cnf \
    -keyfile $KEYDIR/cp-root.key -cert cp-root.crt \
    -startdate $STARTDATE -enddate $ENDDATE -preserveDN \
    -notext -batch -utf8 -out cp-ca.crt

After generating the certificate, check that the output is reasonable:

openssl x509 -in cp-ca.crt -noout -dates
openssl x509 -in cp-ca.crt -noout -text | grep -o "Signature Algorithm.*"

The certificate can be validated with with the scion-pki binary:

scion-pki certs validate --type cp-ca cp-ca.crt

Updating CA certificates

CA certificates should be periodically rolled over. A validity of 11 days with 4 days overlap between two CA certificates is recommended. The recommended schedule is shown below:

   Su | Mo | Tu | We | Th | Fr | Sa | Su | Mo | Tu | We | Th | Fr | Sa | Su | Mo
... 1 |  1 |  1 |  1 |  1 |    |    |    |    |    |    |    |    |    |    |
      |  2 |  2 |  2 |  2 |  2 |  2 |  2 |  2 |  2 |  2 |  2 |    |    |    |
      |    |    |    |    |    |    |    |  3 |  3 |  3 |  3 |  3 |  3 |  3 |  3 ...

Always on Monday a CA certificate with a validity of 11 days is created and enabled. This way there is an overlap period until Thursday with the previous CA certificate. That should leave enough room to debug issues during the work week and renewals never fall on a Weekend.

Because CA certificates are created by signing them with the Root certificate, the process for creating future CA certificates is the same as the initial one.

To comply with custom security policies that dictate that a Root Key should sit behind an air gap, multiple CA certificates can be pre-generated for the same entity.

AS Certificates

AS Certificates in SCION are always signed by a CA Certificate, which is in turn signed by the Root Certificate contained in the TRC.

Because the entities applying for an AS certificate (the ASes) are sometimes different from the CA entity signing the certificate (the CA), we separate the steps in this section into two: the AS steps and the CA steps.

Important

SCION Certificate Authorities are also SCION ASes. This means that every CA must also create an AS certificate for itself. In this specific case, the two entities in this section (the AS and the CA) are the same.

Creating the initial AS Certificate

The steps in creating a new AS Certificate are:

  1. The AS defines the configuration of the AS Certificate in accordance with the SCION requirements.

  2. The AS creates a new key pair.

  3. The AS creates a Certificate Signing Request using the key pair.

  4. (If the AS and CA are different entities) The AS sends the Certificate Signing Request to the CA.

  5. The CA uses its CA Key and the Certificate Signing Request to create the new AS Certificate.

  6. (If the AS and CA are different entities) The CA sends the AS Certificate back to the AS.

The subject template needs to be adapted to the entity that is creating the certificate signing request. For simplicity, we reuse the same template for both the CA and the AS. Adapt your template according to your needs.

    scion-pki certificate create \
        --profile cp-as \
        --common-name "$ORG AS Certificate" \
        --csr \
        subject.tmpl \
        cp-as.csr \
        $KEYDIR/cp-as.key

The configuration is defined in a file. OpenSSL reads the file and creates a certificate that is compatible with SCION. An example configuration file is included below. Note that the file includes the text {{.ShortOrg}}; this text must be replaced with the shortname of your organization. For example, if your organization name is ExampleCorp, the line should contain name = ExampleCorp Secure CA Certificate.

cat << EOF > cp-as.cnf
openssl_conf    = openssl_init
x509_extensions = x509_ext
req_extensions  = req_ext

[common_name]
name = {{.ShortOrg}} AS Certificate

[x509_ext]
keyUsage               = critical, digitalSignature
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid
extendedKeyUsage       = 1.3.6.1.5.5.7.3.1, 1.3.6.1.5.5.7.3.2, 1.3.6.1.5.5.7.3.8

[req_ext]
keyUsage               = critical, digitalSignature
subjectKeyIdentifier   = hash
extendedKeyUsage       = 1.3.6.1.5.5.7.3.1, 1.3.6.1.5.5.7.3.2, 1.3.6.1.5.5.7.3.8

[ca_defaults]
default_days = 3

.include basic.cnf
EOF

Attention

SCION AS certificates have short lifetimes (a lifetime of 3 days is recommended).

To create the key pair and certificate signing request (CSR), the AS then runs the OpenSSL commands below. In these commands, replace $KEYDIR with the folder where private keys should be stored:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
    -pkeyopt ec_param_enc:named_curve -out $KEYDIR/cp-as.key

openssl req -new -key $KEYDIR/cp-as.key -config cp-as.cnf \
    -utf8 -out cp-as.csr

If the AS and CA are different entities, the certificate signing request can then be sent to a CA for signing.

This step is performed by an entity that is a CA in the ISD. The CA creates the certificate using its private key and the certificate signing request received from the AS. The CA should set $KEYDIR to the folder in which the private key file (the file is called cp-ca.key, in this example) is stored.

The CA must also define the following:

  • AS Certificate validity start date and end date in RFC3339 format.

To create the certificate, the CA runs:

# Uncomment and set the appropriate values:
#
# STARTDATE="2020-06-24T14:00:00+02:00"
# ENDDATE="2020-06-27T14:00:00+02:00"

scion-pki certificate sign \
    --bundle \
    --ca cp-ca.crt \
    --ca-key $KEYDIR/cp-ca.key \
    --not-before $STARTDATE \
    --not-after $ENDDATE \
    cp-as.csr \
    > chain.pem

The CA must also define the following:

  • AS Certificate validity start date. Prior to this date, the certificate is not considered valid. To configure this, in the command below replace occurrences of $STARTDATE with the date in YYYYMMDDHHMMSSZ notation. For example, June 24th, 2020 UTC at noon is formatted as 20200624120000Z.

  • AS Certificate validity end date. After this date, the certificate is no longer valid. To configure this, in the command below replace occurrences of $ENDDATE with the desired date. This uses the same notation as the $STARTDATE.

To create the certificate, the CA runs:

# Uncomment and set the appropriate values:
#
# STARTDATE="20200624120000Z"
# ENDDATE="20200627120000Z"

openssl ca -in cp-as.csr -config cp-as.cnf \
    -keyfile $KEYDIR/cp-ca.key -cert cp-ca.crt \
    -startdate $STARTDATE -enddate $ENDDATE -preserveDN \
    -notext -batch -utf8 -out cp-as.crt

After generating the certificate, check that the output is reasonable:

openssl x509 -in cp-as.crt -noout -dates
openssl x509 -in cp-as.crt -noout -text | grep -o "Signature Algorithm.*"

The certificate can be validated with with the scion-pki binary:

scion-pki certs validate --type cp-as cp-as.crt

If the AS and CA are different entities, the CA should then send the certificate back to the AS that request it.

Creating future AS certificates

Because AS certificates are created by signing them with the CA certificate, the process for creating future CA certificates is the same as the initial one.

In a running ISD, AS certificates are usually built automatically by the SCION control plane.