SCION¶

The SCION section contains the configuration of the SCION protocol and AS. It consists of a list of SCION AS configurations and the appliance cluster configuration. An Anapaya appliance can have configurations for multiple SCION ASes, however, in most cases there will only be a single SCION AS configured.

Each SCION AS configuration is further divided into multiple sections - general AS configuration, data plane configuration, the control plane configuration, and - for ASes that also act as a certificate authority - the certificate authority configuration.

General AS Configuration¶

Each SCION AS has several general AS configuration options, such as the ISD-AS identifier, the AS forwarding secret key, or a human-readable description of the AS. The following configuration options are available:

isd_as: The ISD-AS identifier is the tuple that uniquely identifies the AS within a SCION isolation domain (ISD). This number is usually assigned by a numbering authority.
forwarding_key: The forwarding secret key is used to authenticate the hop field of the SCION path which corresponds to this AS. It is a local secret that only needs to be known to the AS. The forwarding key MUST be identical across all appliances in an AS. It is specified as a base64-encoded string in the configuration file.
core: The core flag must only be set if the AS is a core AS in its ISD. A core AS provides connectivity to other SCION ISDs and operates the main path directories within its ISD. It also regularly initiates path construction beacons that create path segments to other SCION ASes in the same ISD or to other core ASes in different ISDs. For most of the ASes this is not the case and the flag must be set to false or not specified (defaults to false).
shard_id: The control and the data plane of a SCION AS is split into multiple shards. Each shard is responsible for processing and disseminating path information only for a subset of links. Shards are units that operate and fail independently from other shards. Usually, each appliance operates as a separate shard to increase the resiliency of the network. This field is the ID of the shard to which the control service and the router on this appliance belong.
scion_mtu: The maximum transmission unit in bytes for SCION packets on the internal network of the AS. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as the maximum Ethernet payload - IP Header - UDP Header.
default: Default indicates whether the respective SCION AS should be used by default as the source AS by SCION applications, e.g., scion ping or scion showpaths. The configurations with more than one default ASes will be rejected because there can only be one default AS. If there is only a single AS configured, it will be the default. Therefore, this setting is only necessary if multiple ASes are configured on the appliance.
details: User-defined details about the SCION AS for informational purposes.

General SCION AS configuration

This example shows how to configure two SCION ASes on the appliance. It only includes the general AS configuration.

{
  "scion": {
    "ases": [
      {
        "isd_as": "1-ff00:1:1",
        "forwarding_key": "secret1",
        "core": true,
        "shard_id": 1,
        "scion_mtu": 1472,
        "default": true,
        "details": "This is a test AS in ISD 1"
      },
      {
        "isd_as": "2-ff00:1:1",
        "forwarding_key": "secret2",
        "core": false,
        "shard_id": 2,
        "scion_mtu": 1472,
        "default": false,
        "details": "This is a test AS in ISD 2"
      }
    ]
  }
}

Data Plane Configuration¶

Even though SCION is a layer 3 network protocol, SCION packets are encapsulated in UDP/IP packets between individual SCION routers and SCION endhosts (generally referred to as SCION nodes). In other terms, SCION is using a UDP/IP underlay to transport SCION packets between SCION nodes. These UDP/IP packets are only valid between two SCION nodes and change after every SCION hop.

The SCION data plane configuration consists of the router and the neighbors sections. The router section contains the configuration of the internal SCION interface internal_interface, while the neighbors section defines all the SCION links to other SCION ASes, i.e., the external SCION interfaces.

Internal SCION Interface¶

The internal SCION interface is where the appliance receives SCION packets from AS internal hosts for forwarding. It is defined as a UDP/IP network endpoint on which the SCION packets are received from the internal network. The endpoint needs to be specified as a string in the format <ip>:<port>. If the port is set to 0 it will be automatically assigned.

Internal SCION interface configuration

{
  "scion": {
    "ases": [
      {
        "router": {
          "enabled": true,
          "internal_interface": "192.168.1.1:31000"
        }
      }
    ]
  }
}

Neighbors¶

Each entry in the neighbors section contains a remote SCION AS to which one or multiple links are established. It contains the following entries:

neighbor_isd_as

The ISD-AS of the neighbor.

relationship

The relationship with the neighbor. Possible values for the relationship are CORE, CHILD, PARENT, and PEER. A CHILD/PARENT relationship indicates that the remote AS is a child/parent, i.e., downstream/upstream of the local AS. A PEER relationship indicates a (usually) settlement-free peering relationship with the neighboring AS. A CORE relationship is specific to a link between two SCION Core ASes. These are the ASes that are at the core of a SCION ISD. The relationship applies to all the links between two ASes, i.e., it is not possible to have a CORE and at the same time a PARENT link to the same remote AS.

interfaces

The interfaces section is used to configure a list of SCION links. The local end of the link is an external SCION interface. Each interface definition has the following entries:

interface_id

The unique ID of the external SCION interface. This is the identifier that is also contained in a SCION path that uses this interface.

address

The local UDP/IP endpoint on which SCION packets from the remote side of the link are received. address is specified as a <ip>:<port>, where both <ip> and <port> must be explicitly specified.

remote

The configuration for the remote end of the link. It contains the UDP/IP address and the interface_id of the remote side of the link. These parameters need to be agreed upon by the two ASes.

administrative_state

The administrative state of the interface with one of the following values:

UP The interface is up and ready to send/receive SCION packets as well as being advertised during beaconing.
DATAPLANE_ONLY The interface is up and ready to send/receive SCION packets, but is not advertised during beaconing.
ADMIN_DOWN The interface is down and neither sends/receives SCION packets nor is it advertised during beaconing.

scion_mtu

The maximum transmission unit in bytes for SCION packets on the external interface. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header. Note that the SCION MTU can differ between the various links and also from SCION MTU supported in the internal network of the local AS.

enable_scion_rss

Option to activate SCION RSS for this link. If activated, the router utilizes UDP source port entropy on the underlay such that the remote router can leverage RSS for SCION traffic. This must only be set to true if the neighbor supports the SCION RSS feature.

Single PARENT link to upstream AS

This example shows a single PARENT link to an upstream AS using an IPv6 underlay network.

{
  "scion": {
    "ases": [
      {
        "neighbors": [
          {
            "neighbor_isd_as": "1-ff00:1:1",
            "relationship": "PARENT",
            "interfaces": [
              {
                "interface_id": 1,
                "address": "[fd02:e8a2:c9e2:03e6::2]:30100",
                "administrative_state": "UP",
                "scion_mtu": 1452,
                "remote": {
                  "address": "[fd02:e8a2:c9e2:03e6::1]:30100",
                  "interface_id": 201
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Two CORE links between two SCION Core ASes

This example shows two CORE links to a neighboring SCION Core AS.

{
  "scion": {
    "ases": [
      {
        "neighbors": [
          {
            "neighbor_isd_as": "1-ff00:1:1",
            "relationship": "CORE",
            "interfaces": [
              {
                "interface_id": 1,
                "address": "169.254.1.1:30100",
                "administrative_state": "UP",
                "scion_mtu": 1472,
                "remote": {
                  "address": "169.254.1.2:30101",
                  "interface_id": 3
                }
              },
              {
                "interface_id": 200,
                "address": "169.254.100.1:30100",
                "administrative_state": "ADMIN_DOWN",
                "scion_mtu": 1472,
                "remote": {
                  "address": "169.254.100.2:30101",
                  "interface_id": 1
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Bidirectional Forwarding Detection¶

Bidirectional Forwarding Detection (BFD) is used to track the healthiness of a SCION link and can be configured for each external interface.

Note

In most cases, the default values work well and the BFD configuration does not need to be explicitly specified.

enabled: If set to true, then the BFD session is enabled on the SCION interface - if it is set to false, BFD is disabled on that SCION interface. When disabled, the health of the interface is not tracked and it is assumed to be healthy. Note that the remote side of this SCION interface should have the same setting for enabled. If not set this defaults to true.
desired_minimum_tx_interval: The minimum interval between transmission of BFD control packets that the operator desires. This value is advertised to the peer, however, the actual interval used is specified by taking the maximum of desired-minimum-tx-interval and the value of the remote required-minimum-receive interval value. This value is specified as an integer number of microseconds. Defaults to 200000 (200ms).
detection_multiplier: The number of packets that must be missed to declare this session as down. The detection interval for the BFD session is calculated by multiplying the value of the negotiated transmission interval by this value. Defaults to 3.
required_minimum_receive: The minimum interval between received BFD control packets that this system should support. This value is advertised to the remote peer to indicate the maximum frequency (i.e., minimum inter-packet interval) between BFD control packets that is acceptable to the local system. Defaults to 200000 (200ms).

Custom BFD configuration

This example shows how to configure BFD for an external interface that runs over an unreliable network. To account for that, the detection multiplier is increased to 10 and timers decreased to 50ms (50000us), i.e., BFD packets are sent more frequently and more missing packets are tolerated before declaring the link as down.

{
  "bfd": {
    "enabled": true,
    "desired_minimum_tx_interval": 50000,
    "detection_multiplier": 10,
    "required_minimum_receive": 50000
  }
}

Control Plane Configuration¶

The SCION control plane configuration consists of the control and cppki sections that configure the network endpoint of the control service and the AS certificate renewal parameters.

control

Section control is the configuration for the SCION control service.

address: This configures where the control service is exposed. Clients connect to this address to request control plane data, e.g., SCION path segments. The address needs to be specified as a string in the format <ip>:<port>. If the port is set to 0 it will be automatically assigned.
enabled: If set to true, the control service is enabled. If set to false, the control service is disabled.

cppki

The cppki section contains the configuration of the SCION control plane PKI.

issuers: A list of SCION certificate authorities that should be used to renew the SCION AS certificate of this appliance. isd_as is the ISD-AS identifier of the AS that runs the CA. priority indicates the priority of the issuing AS. The appliance attempts to get certificates issued from the AS with the highest priority. The value 0 indicates the highest priority, higher numbers are lower priority.
disable_auto_renewal: Whether automatic renewal of AS certificates should be disabled. Usually, this value should not be set. By disabling certificate renewal, the appliance is set into a manual mode where new AS certificates must be provisioned manually and periodically.

Control Plane configuration

This example shows how to configure the control plane including a primary and a secondary certificate issuing CA. The appliance will try to contact 1-ff00:1:100 first, and if that fails, fallback to 1-ff00:1:200.

{
  "scion": {
    "ases": [
      {
        "control": {
          "enabled": true,
          "address": "192.168.1.1:40100"
        },
        "cppki": {
          "issuers": [
            {
              "isd_as": "1-ff00:1:100",
              "priority": 0,
            },
            {
              "isd_as": "1-ff00:1:200",
              "priority": 1,
            }
          ]
        }
      }
    ]
  }
}

Certificate Authority Configuration¶

For ASes that act as a CA in one or multiple SCION ISDs, the CA configuration section contains the necessary parameters to interface with SCION CA backend.

Note

The certificate authority (CA) configuration is only needed for SCION ASes that act as a certificate authority in one or multiple SCION ISDs. For all other ASes this section must not be configured.

service_type

The service_type indicates what type of CA service is used. Currently, the Anapaya appliance supports three types of CA services:

ANAPAYA_VAULT is the SCION CA backend provided by Anapaya. It is based on Hashicorp Vault with a suitable frontend. If this service type is used, the anapaya_vault section must be configured.
EXTERNAL is a generic CA backend not implemented by Anapaya. Note that the external CA backend must implement the SCION CA API to be compatible with the Anapaya appliance. If this service type is used, the external section must be configured.
IN_PROCESS is a CA service that is implemented in the Anapaya appliance. It should only be used for testing purposes and is not suitable for productive use. If this service type is used, no other section needs to be configured.

Anapaya Vault CA¶

The anapaya_vault section contains the configuration for the Anapaya Vault based CA service. It must be provided if the service_type is set to ANAPAYA_VAULT.

addresses: This field contains a list of addresses where Anapaya Vault backend can be reached. Addresses are of the form https://<host>:<port>, where <host> can either be a hostname or an IP address. The list of addresses must not be empty.
role_id and secret_id: These are the credentials used to authenticate with the Anapaya Vault backend. Refer to the Anapaya Vault setup guide for how these credentials are created.

Anapaya Vault CA backend configuration

{
  "ca_service": {
    "service_type": "ANAPAYA_VAULT",
    "anapaya_vault": {
      "addresses": [
        "https://vault.example.com:8200"
      ],
      "role_id": "role-id",
      "secret_id": "secret-id"
    }
  }
}

External CA¶

The external section contains the configuration for a generic external CA backend that implements the SCION CA API.

address: The address of the external CA backend. It is of the form https://<host>:<port>, where <host> can either be a hostname or an IP address.
client_id and shared_secret: These are the credentials used to authenticate with the external CA backend. They must be agreed with the external CA backend operator. Starting with release v0.31, the shared secret can be configured directly. Prior releases require that the shared secret is PEM encoded with the type SYMMETRIC KEY.

External CA backend configuration

{
  "ca_service": {
    "service_type": "EXTERNAL",
    "external": {
      "address": "https://ca.example.com:5000",
      "client_id": "client-id",
      "shared_secret": "-----BEGIN SYMMETRIC KEY-----\nMIIB6jCCAZCgAwIBAgIUO1CvSfi8Kueey1+f\n-----END SYMMETRIC KEY-----"
    }
  }
}