Leader mode installation

Before you can deploy the Anapaya SCION CA in leader mode, the preparation instructions must be completed.

The high-level steps to install the Anapaya SCION CA in leader mode are as follows:

Prepare the initial configuration for step-ca (directories and configuration files). The step-ca service should not be started yet.
Set up the step-ca-rotator and generate the initial CA certificate.
Complete the step-ca configuration and start the step-ca service.
Set up the step-ca-adapter

Partially configure step-ca

Prepare the necessary directories with the correct ownership and permissions:

sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/secrets
sudo -u scion-ca chmod 0400 /etc/scion-ca/secrets/scion-ca-admin.pw

Create a random password for the step-ca admin user:

sudo -u scion-ca bash -c "step crypto rand > /etc/scion-ca/secrets/scion-ca-admin.pw"
sudo -u scion-ca bash -c "step crypto rand > /tmp/dummy.pw"

Store password securely

Create a backup of the /etc/scion-ca/secrets/scion-ca-admin.pw file in a secure storage. It is required when you interact with the step-ca admin API.

Initialize the step-ca instance:

sudo -u scion-ca step ca init \
    --name "SCION CA - 1-ff00:0:110" \
    --dns "localhost" \
    --address "localhost:8443" \
    --deployment-type "standalone" \
    --provisioner "scion-ca-admin" \
    --provisioner-password-file /etc/scion-ca/secrets/scion-ca-admin.pw \
    --password-file /tmp/dummy.pw

sudo -u scion-ca mv /etc/scion-ca/.step /etc/scion-ca/step
sudo -u scion-ca sed -i 's|/.step/|/step/|g' /etc/scion-ca/step/config/ca.json
sudo -u scion-ca sed -i 's|/.step/|/step/|g' /etc/scion-ca/step/config/defaults.json
sudo -u scion-ca rm /etc/scion-ca/step/secrets/*key

note

This creates a temporary root and intermediate CA certificate, and corresponding private keys. Later on, they are replaced with the actual SCION CP-PKI root and CA certificates.

Copy the credentials for the Google Cloud KMS key ring to the step-ca configuration directory:

sudo cp $SCION_CA_STEP_CA_CREDS /etc/scion-ca/step/secrets/credentials.json
sudo chown scion-ca:scion-ca /etc/scion-ca/step/secrets/credentials.json
sudo chmod 0400 /etc/scion-ca/step/secrets/credentials.json

Modify /etc/scion-ca/step/config/ca.json to use PostgreSQL and Google Cloud KMS, using the following command:

sudo -u scion-ca jq '. + {
  "db": {
    "type": "postgresql",
    "dataSource": "postgresql://step_ca:super-secure@127.0.0.1:5432/",
    "database": "step_ca"
  },
  "kms": {
    "type": "cloudkms",
    "uri": "cloudkms:credentials-file=/etc/scion-ca/step/secrets/credentials.json"
  },
  "authority": (.authority + {"enableAdmin": true })
}' /etc/scion-ca/step/config/ca.json | sudo -u scion-ca tee /etc/scion-ca/step/config/ca.json > /dev/null

note

This modifies the step-ca configuration to use a PostgreSQL database and Google Cloud KMS for key management. Replace the db.dataSource with the actual connection string to your PostgreSQL database, and the kms.uri with the path to your Google Cloud KMS credentials file. You do not need to configure the key itself, because that is done by the step-ca-rotator.

Copy the actual SCION CP-PKI root certificate

sudo -u scion-ca cp $SCION_CA_ROOT /etc/scion-ca/step/certs/root_ca.crt
sudo chown scion-ca:scion-ca /etc/scion-ca/step/certs/root_ca.crt
sudo chmod 0600 /etc/scion-ca/step/certs/root_ca.crt

Next, you need to configure the step-ca-rotator, allowing you to create the actual SCION CP-PKI CA certificate based on the SCION CP-PKI root certificate. Afterwards, continue with finishing the step-ca configuration and starting the step-ca service.

Configure step-ca-rotator

Prepare the necessary directories with the correct ownership and permissions:

sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/rotator

Copy the crendentials located in $SCION_CA_STEP_CA_ROTATOR_CREDS for the Google Cloud KMS key ring to the step-ca-rotator configuration directory:

sudo cp $SCION_CA_STEP_CA_ROTATOR_CREDS /etc/scion-ca/rotator/credentials.json
sudo chown scion-ca:scion-ca /etc/scion-ca/rotator/credentials.json
sudo chmod 0400 /etc/scion-ca/rotator/credentials.json

Generate the step-ca-rotator configuration file:

step-ca-rotator sample config | sudo -u scion-ca tee /etc/scion-ca/rotator/config.toml > /dev/null
sudo chmod 0400 /etc/scion-ca/rotator/config.toml

Make sure to update the following fields in the configuration file:

database.dsn
instance.isd_as
instance.rotation_follower (set to false)
instance.key (do not include the version suffix`)
instance.root_key (do include the version suffix`)

You can also change other fields to your liking. E.g., you might want to change the log.console.format to human for easier manual inspection of the logs, or change the log.console.level to debug for more verbose logging.

Create the systemd service for step-ca-rotator:

step-ca-rotator sample systemd-service | sudo tee /etc/systemd/system/step-ca-rotator.service > /dev/null

Load and enable the step-ca-rotator service:

sudo systemctl daemon-reload
sudo systemctl enable --now step-ca-rotator
sudo systemctl status step-ca-rotator

Manually create the SCION CP-PKI CA certificate. It serves as the template for the step-ca-rotator to rotate the CA certificate in the future. Use the step-ca-rotator rotate command to manually create it:

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

important

Choose an appropriate common name for the CA certificate in accordance with your organization's and the ISD's naming conventions. If the common name contains a YYYY.Sequence suffix, the rotator automatically increases the serial number for the next rotation (or update the year when appropriate.)

tip

You can always use this command to manually rotate the CA certificate, when needed. For example, you can update the common name or change any other part of the distinguished name this way.

Continue configuring step-ca

Now that you have a CA certificate, continue configuring step-ca.

Set up the systemd service for step-ca:

sudo tee /etc/systemd/system/step-ca.service > /dev/null << 'EOF'
[Unit]
Description=step-ca service
Documentation=https://smallstep.com/docs/step-ca
Documentation=https://smallstep.com/docs/step-ca/certificate-authority-server-production
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=30
StartLimitBurst=3
ConditionFileNotEmpty=/etc/scion-ca/step/config/ca.json
ConditionFileNotEmpty=/etc/scion-ca/step/secrets/credentials.json

[Service]
Type=simple
User=scion-ca
Group=scion-ca
Environment=STEPPATH=/etc/scion-ca/step
WorkingDirectory=/etc/scion-ca/step
ExecStart=/usr/bin/step-ca config/ca.json
ExecReload=/bin/kill --signal HUP $MAINPID
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
StartLimitInterval=30
StartLimitBurst=3

; Process capabilities & privileges
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
SecureBits=keep-caps
NoNewPrivileges=yes

; Sandboxing
ProtectSystem=full
ProtectHome=true
RestrictNamespaces=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
PrivateTmp=true
PrivateDevices=true
ProtectClock=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectKernelLogs=true
ProtectKernelModules=true
LockPersonality=true
RestrictSUIDSGID=true
RemoveIPC=true
RestrictRealtime=true
SystemCallFilter=@system-service
SystemCallArchitectures=native
MemoryDenyWriteExecute=true
ReadWritePaths=/etc/scion-ca/step/config/ca.json

[Install]
WantedBy=multi-user.target
EOF

Load and enable the step-ca service:

sudo systemctl daemon-reload
sudo systemctl enable --now step-ca
sudo systemctl status step-ca

Create step-ca-adapter provisioner

The step-ca-adapter forwards certificate issuance requests to the step-ca instance. This is done through a X.509 provisioner in step-ca. The SCION CP-PKI requires specific parameters in the X.509 certificates. Thus, create an X.509 template that is used by the step-ca-adapter to provide the appropriate values.

sudo -u sicon-ca tee /etc/scion-ca/step/templates/step-ca-adapter.json > /dev/null << 'EOF'
{
    "subject": {{ toJson .Insecure.User.Subject }},
    "keyUsage": ["digitalSignature"],
    "extKeyUsage": ["timeStamping", "serverAuth", "clientAuth"]
}
EOF

Prepare the directory where the step-ca-adapter reads the credentials to use the provisioner from:

sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/adapter
sudo -u scion-ca bash -c "step crypto rand > /etc/scion-ca/adapter/step-ca-adapter.pw"
sudo -u scion-ca chmod 0400 /etc/scion-ca/adapter/step-ca-adapter.pw

Create the provisioner in step-ca:

sudo -u scion-ca \
  STEPPATH=/etc/scion-ca/step/ step ca provisioner add step-ca-adapter \
  --create \
  --password-file /etc/scion-ca/adapter/step-ca-adapter.pw \
  --admin-provisioner scion-ca-admin \
  --admin-subject step \
  --admin-password-file /etc/scion-ca/secrets/scion-ca-admin.pw \
  --x509-template /etc/scion-ca/step/templates/step-ca-adapter.json \
  --x509-max-dur 960h \
  --x509-default-dur 72h \
  --x509-min-dur 24h \
  --disable-smallstep-extensions

Next, enable remote provisioner management. This moves all the provisioners to the database, allowing multiple step-ca instances to have the same provisioner configuration.

sudo systemctl restart step-ca

sudo -u scion-ca jq '. + {
  "authority": {"enableAdmin": true }
}' /etc/scion-ca/step/config/ca.json | sudo -u scion-ca tee /etc/scion-ca/step/config/ca.json > /dev/null

sudo systemctl restart step-ca-rotator step-ca

Configure step-ca-adapter

Prepare the necessary directories with the correct ownership and permissions:

sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/adapter
sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/adapter/tls/
sudo -u scion-ca mkdir -m 0700 /etc/scion-ca/adapter/tls/acme

Create a shared secret that is used to authenticate the Anapaya appliance to the step-ca-adapter:

sudo -u scion-ca bash -c "step crypto rand > /etc/scion-ca/adapter/shared_secret"
sudo -u scion-ca chmod 0400 /etc/scion-ca/adapter/shared_secret

Generate the step-ca-adapter configuration file:

step-ca-adapter sample config | sudo tee -u scion-ca /etc/scion-ca/adapter/config.toml > /dev/null
sudo chmod 0400 /etc/scion-ca/adapter/config.toml

Make sure to update the following fields in the configuration file:

database.dsn
general.isd
public.api_addr (use a resolvable hostname)
public.acme.ca (if ACME is supported on step-ca, use https://localhost:8443/acme/acme/directory)

tip

To enable ACME support, follow the user guide.

Create the systemd service for step-ca-adapter:

step-ca-adapter sample systemd-service | sudo tee /etc/systemd/system/step-ca-adapter.service > /dev/null

Load and enable the step-ca-adapter service:

sudo systemctl daemon-reload
sudo systemctl enable --now step-ca-adapter
sudo systemctl status step-ca-adapter

Partially configure step-ca​

Configure step-ca-rotator​

Continue configuring step-ca​

Create step-ca-adapter provisioner​

Configure step-ca-adapter​

Partially configure step-ca

Configure step-ca-rotator

Continue configuring step-ca

Create step-ca-adapter provisioner

Configure step-ca-adapter