step-ca-rotator configuration

The step-ca-rotator is a key component of the Anapaya SCION CA responsible for automating the rotation of CA certificates.

• In leader mode, it generates new CA certificates at defined intervals and provisions them to step-ca automatically.
• In follower mode, it synchronizes with the leader and provisions step-ca with the latest CA certificate created by the leader.

This ensures seamless and secure certificate lifecycle management within the SCION CA infrastructure.

tip

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

Configuration

The step-ca-rotator 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-rotator.

The configuration file is located at /etc/scion-ca/rotator/config.toml. It contains various settings for the step-ca-rotator, 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-rotator sample config

Required fields

The configuration file must include the following fields:

• instance.isd_as
• instance.rotation_follower (true for follower mode, false for leader mode)
• instance.key (CloudKMS resource without version suffix)
• instance.root_key (CloudKMS resource with version suffix)
• database.dsn

Please ensure that only one instance is configured as a leader, and all others are configured as followers.

Provisioning

The step-ca-rotator in leader mode automatically creates new CA certificates and provision step-ca at the requested interval. However, an initial CA certificate must be provisioned in a manual step, which serves as a template for all subsequent CA certificates. Initialize it with the rotate command:

sudo -u scion-ca step-ca-rotator rotate \
    --config /etc/scion-ca/rotator/config.toml \
    --common-name "MyOrganization CP CA - GEN I 2025.1"

This infers all of the subject fields from the root certificate, and overrides the common name with the desired value. Afterwards, the step-ca-rotator can automatically rotate the CA certificate.

note

The step-ca-rotator searches for pattern YYYY.Sequence in the common name, and automatically increments the sequence number for subsequent CA certificates. Once the Year changes, the sequence number is reset to 1. This allows for easy identification of the CA certificates on issued certificate chains.

Quick reference

Files and directories

Path	Description
/etc/scion-ca/rotator	Directory containing step-ca-rotator
/etc/scion-ca/rotator/config.toml	Main configuration file for the step-ca-rotator
/etc/scion-ca/rotator/step-ca-rotator.creds	File storing the credentials for the step-ca-rotator
/etc/systemd/system/step-ca-rotator.service	Systemd unit file to manage the step-ca-rotator service

Commands

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

API endpoints

Endpoint	Description
GET localhost:41501/api/v1/health	Get health status of the step-ca-rotator

tip

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