step-ca-adapter configuration

The step-ca-adapter acts as a bridge between the SCION CA API and the step-ca certificate authority. Its primary role is to translate SCION-specific certificate renewal and provisioning requests into a format that can be processed by step-ca, ensuring seamless integration between SCION infrastructure and the underlying CA.

In addition to forwarding requests, the step-ca-adapter performs validation and verification of certificate renewal requests, checking their authenticity and compliance with SCION policies. It also manages the provisioning of critical data such as Trust Root Configurations (TRCs) and blocklists, which are essential for secure operation. By centralizing these responsibilities, the step-ca-adapter simplifies the management of certificate lifecycles within SCION deployments and enhances the overall security posture of the system.

tip

Use the quick reference to get an overview of important files and commands.

Configuration

The step-ca-adapter is a systemd service that requires a configuration file to run. Follow the installation instructions for detailed instructions on how to set up the step-ca-adapter.

The configuration file is located at /etc/scion-ca/adapter/config.toml. It contains various settings for the step-ca-adapter, such as the database connection, logging settings, and API settings.

You can generate a sample configuration file, including explanations, using the following command:

step-ca-adapter sample config

Required fields

A minimal configuration file must include the following fields:

general.isd
public.api_addr
database.dsn

Provisioning

In addition to the configuration file, the step-ca-adapter must be provisioned with additional data for it to operate correctly. This includes all the TRCs for the ISD, and potentially a blocklist.

The state is shared through the database across all step-ca-adapter instances, so you only need to provision the step-ca-adapter on one instance. The remaining instances automatically pick up the state from the database. Provisioning is done through the step-ca-adapter admin API, which is exposed on localhost:41500 by default (and configurable through admin.api_addr in the configuration file). The list of endpoints is available at API reference

You can interact with the step-ca-adapter admin using the HTTP client of your choice. For example, to check the health of the step-ca-adapter using curl, run:

curl -X GET http://localhost:41500/api/v1/health

Provisioning TRCs

The step-ca-adapter requires all the TRCs for the ISD to be provisioned. The TRCs are used to verify the authenticity of the certificate renewal requests. You can add the TRC bundle using the /api/v1/trcs/bundle endpoint.

curl -X POST http://localhost:41500/api/v1/trcs/bundle --data-binary @trc.bundle

important

Make sure to provide the TRC bundle using the --data-binary flag to ensure that the file is read correctly. You can obtain the TRC bundle from the ISD registry

Provisioning blocklist

The step-ca-adapter can also maintain a blocklist that prohibits certain certificate renewal requests based on some attributes of the request itself. The blocklist allows you to block based on the subject ISD-AS number of the CSR, or on the certificate/public key fingerprint of the signing certificate. Additionally, you can block all requests that are signed by a certificate that were issued by a specific CA based on their ISD-AS number, or on the CA certificate/public key fingerprint.

To show the current blocklist, use the /api/v1/blocklist endpoint:

curl -X GET http://localhost:41500/api/v1/blocklist

To update the blocklist, use the /api/v1/blocklist endpoint. Both YAML and JSON formats are supported.

curl -X PUT http://localhost:41500/api/v1/blocklist --data-binary @blocklist.yaml

Example: Fully populated blocklist
blocklist:
    isd_ases:
        1-ff00:0:111:
            comment: "Block all requests for ISD-AS 1-ff00:0:111"
    fingerprints:
        8a2519af55d1b2ea6fc730bfe2dfa607bdc9a8ca030635234d8421709bda02ac:
            type: cert
            comment: >-
                Block all requests signed with certificate with this fingerprint.
                The fingerprint is the SHA-256 hash of the DER encoded certificate.
    issuer_isd_ases:
        1-ff00:0:110:
            comment: "Block all requests signed by a CA with ISD-AS 1-ff00:0:110"
    issuer_fingerprints:
        e2e72b4c571305aecc07602bd00ba5654bf78be1dc0f97cc470cd607fc4a9689:
            type: cert
            comment: >-
                Block all requests signed by a CA with this certificate fingerprint.
                The fingerprint is the SHA-256 hash of the DER encoded certificate.

Different ways to block certificate renewal requests are supported. They have different purposes and can be used to tailor the blocklist to your needs:

isd_ases: Use this to block all requests for a specific ISD-AS number. For example, if a specific ISD-AS has been compromised, or marked for exclusion from the ISD.
fingerprints: Use this to block all requests that are signed by a specific certificate that is identified by its fingerprint. For example, if a specific certificate has been compromised, you can block all requests signed by that certificate.
issuer_isd_ases: Use this to block all requests that are signed with a certificate issued by a specific CA.
issuer_fingerprints: Use this to block all requests that are signed with a certificate issued by a specific CA certificate that is identified by its fingerprint

In most cases, you want to reach for the isd_ases and fingerprints blocklist entries, as they are more targeted and precise. The issuer_isd_ases and issuer_fingerprints entries are more broad and block a larger set of requests, which might not be what you intended.

Calculating fingerprints

The certificate fingerprint is the SHA-256 hash of the DER encoded certificate. Calculate it using your preferred tool.

step
openssl

step certificate fingerprint <certificate_file>

For more information, consult the official step documentation.

openssl x509 -in <certificate_file> -noout -fingerprint -sha256 | cut -d'=' -f2 | tr -d ':' | tr 'A-F' 'a-f'

For more information, consult the official OpenSSL documentation.

Quick reference

Files and directories

Path	Description
`/etc/scion-ca/adapter`	Directory containing step-ca-adapter configuration and data
`/etc/scion-ca/adapter/config.toml`	Main configuration file for the step-ca-adapter
`/etc/scion-ca/adapter/shared_secret`	File storing the shared secret for API authentication
`/etc/scion-ca/adapter/step-ca-adapter.pw`	File storing the password for step-ca-adapter provisioner
`/etc/systemd/system/step-ca-adapter.service`	Systemd unit file to manage the step-ca-adapter service

Commands

Command	Description
`sudo systemctl start step-ca-adapter`	Start the step-ca-adapter service
`sudo systemctl stop step-ca-adapter`	Stop the step-ca-adapter service
`sudo systemctl restart step-ca-adapter`	Restart the step-ca-adapter service
`sudo systemctl status step-ca-adapter`	Check the status of the step-ca-adapter service
`sudo journalctl -u step-ca-adapter`	View the logs for the step-ca-adapter service
`step-ca-adapter sample config`	Generate a sample configuration file for the step-ca-adapter
`step-ca-adapter sample systemd-service`	Generate a sample systemd service file for the step-ca-adapter

API endpoints

Endpoint	Description
`POST localhost:41500/api/v1/trcs/bundle`	Add TRC bundle
`PUT localhost:41500/api/v1/blocklist`	Update blocklist
`GET localhost:41500/api/v1/health`	Get health status

tip

Find the full step-ca-adapter admin API specification in the resources.

Configuration​

Provisioning​

Provisioning TRCs​

Provisioning blocklist​

Calculating fingerprints​

Quick reference​

Files and directories​

Commands​

API endpoints​