openapi: 3.1.0
info:
title: Pocket SCION Management API
description: Management API for Pocket SCION
contact:
name: Anapaya Operations
email: ops@anapaya.net
license:
name: Apache-2.0
identifier: Apache-2.0
version: 0.5.2
servers:
- url: http://{host}:{port}/api/v1
paths:
/auth_server:
get:
tags:
- management
summary: Fake authorization server details.
operationId: get_auth_server
responses:
'200':
description: Authorization Server details
content:
application/json:
schema:
$ref: '#/components/schemas/AuthServerResponse'
'404':
description: No Authorization Server running
/endhost_apis:
get:
tags:
- management
operationId: get_endhost_apis
responses:
'200':
description: The pocket SCION endhost APIs.
content:
application/json:
schema:
$ref: '#/components/schemas/EndhostApisResponse'
/io_config:
get:
tags:
- management
summary: Get the current pocket SCION I/O config.
operationId: get_io_config
responses:
'200':
description: The pocket SCION I/O config
content:
application/json:
schema:
$ref: '#/components/schemas/IoConfigDto'
/link_state:
post:
tags:
- management
summary: Set the link state of a link in the topology.
description: Returns 200 OK on success or 404 Not Found if the link does not exist.
operationId: set_link_state
responses:
'200':
description: Link state set successfully
'404':
description: Link not found
/routers:
get:
tags:
- management
summary: List all available routers in pocket SCION.
operationId: get_routers
responses:
'200':
description: List all available routers
content:
application/json:
schema:
$ref: '#/components/schemas/RoutersResponse'
/snaps:
get:
tags:
- management
summary: List all available SNAPs of the Pocket SCION.
operationId: get_snaps
responses:
'200':
description: List all available SNAPs
content:
application/json:
schema:
$ref: '#/components/schemas/SnapsResponse'
/status:
get:
tags:
- management
summary: Status of the Pocket SCION service.
operationId: get_status
responses:
'200':
description: Pocket SCION status
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
/system_state:
get:
tags:
- management
summary: Get the current pocket SCION system state.
operationId: get_system_state
responses:
'200':
description: The pocket SCION system state.
content:
application/json:
schema:
$ref: '#/components/schemas/SystemStateDto'
components:
schemas:
AuthServerResponse:
type: object
description: Authorization server response.
required:
- addr
properties:
addr:
type: string
description: Address of the authorization server.
AuthServerStateDto:
type: object
description: The state of the authentication server.
required:
- token_exchanger
properties:
token_exchanger:
$ref: '#/components/schemas/TokenExchangerStateDto'
description: The token exchange state.
CertifiedKeyPair:
type: object
description: |-
Struct containing a certificate and private key for an AS, used for both AS certificates and
CA certificates
required:
- key
- cert
properties:
cert:
$ref: '#/components/schemas/StoreCertificateDer'
description: Certificate
key:
$ref: '#/components/schemas/StoreKeyDer'
description: Private Key
ControlServiceState:
type: object
description: Serializable PocketScion State for the control service
required:
- beaconing_interfaces
properties:
beaconing_interfaces:
type: object
additionalProperties:
$ref: '#/components/schemas/InterfaceBeaconState'
propertyNames:
type: object
description: Globally unique identifier for a SCION interface.
required:
- isd_as
- if_id
properties:
if_id:
type: integer
format: int32
description: Interface ID within the AS.
minimum: 0
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: ISD-AS number of the AS the interface belongs to.
example: 1-1#0
EndhostApiDiscoveryStateDto:
description: Serialized state for EndhostApiDiscoveryState
default: null
EndhostApiId:
type: integer
description: Endhost API instance identifier.
minimum: 0
EndhostApiResponseEntry:
type: object
description: Endhost API information.
required:
- id
- local_ases
- url
properties:
id:
$ref: '#/components/schemas/EndhostApiId'
description: The ID of the Endhost API.
local_ases:
type: array
items:
$ref: '#/components/schemas/IsdAsn'
description: The local ASes the Endhost API serves.
uniqueItems: true
url:
type: string
format: uri
description: The URL of the Endhost API.
EndhostApiState:
type: object
description: State per EndhostAPI instance
required:
- local_ases
properties:
local_ases:
type: array
items:
$ref: '#/components/schemas/IsdAsn'
uniqueItems: true
EndhostApisResponse:
type: object
description: Response for the endhost APIs.
required:
- endhost_apis
properties:
endhost_apis:
type: object
description: Map of endhost APIs.
additionalProperties:
$ref: '#/components/schemas/EndhostApiResponseEntry'
propertyNames:
type: integer
description: Endhost API instance identifier.
minimum: 0
ExternalAsInterfaceDto:
type: object
description: Serialized state for ExternalAsInterfaceState
required:
- interface_id
- target_addr
properties:
interface_id:
type: integer
format: int32
description: ID of the interface described
minimum: 0
target_addr:
type: string
description: |-
Address to where this interface connects, used for sending packets to the External AS and
validating received packets
ExternalAsStateDto:
type: object
description: Serialized state for ExternalAsState
required:
- interfaces
properties:
interfaces:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalAsInterfaceDto'
propertyNames:
type: integer
format: int32
minimum: 0
FakeIdpDto:
type: object
description: The fake identity provider configuration for testing.
required:
- public_key
properties:
public_key:
type: string
description: The public key (PEM format) used to verify ID tokens.
InterfaceBeaconState:
type: object
description: The beaconing state for a specific interface
required:
- interface
- is_core
- hop_expiry_units
- generate_forward_beacons
- beacon_interval
- beacon_retry_interval
- next_send_time
properties:
beacon_interval:
type: string
description: The interval at which beacons should be sent on this interface
beacon_retry_interval:
type: string
description: The interval to wait before retrying beacon sending after a failure
generate_forward_beacons:
type: boolean
description: |-
If beacons which would pass through this interface's AS should be generated and sent on
this interface
hop_expiry_units:
type: integer
format: int32
description: |-
The number of hop expiry units to set for generated beacons, which determines the
validity
minimum: 0
interface:
$ref: '#/components/schemas/ScionGlobalInterfaceId'
description: Beacon egress interface
is_core:
type: boolean
description: Whether the AS is a core AS, which determines the beacon generation logic
next_send_time:
type: string
format: date-time
description: The next scheduled time to send beacons on this interface
originator_ases:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/IsdAsn'
description: |-
The set of ISD-ASes that originate beacons which should be forwarded through this
interface. Only segments starting from these ASes will be forwarded.
If `None`, beacons from all originating ASes will be forwarded.
uniqueItems: true
IoAuthServerConfigDto:
type: object
description: The I/O configuration of the Auth server.
properties:
addr:
type: string
IoConfigDto:
type: object
description: The pocket SCION I/O configuration.
required:
- auth_server
- snaps
- router_sockets
- endhost_apis
- endhost_discovery_apis
- external_ases
- network_forwarders
properties:
auth_server:
$ref: '#/components/schemas/IoAuthServerConfigDto'
description: The I/O state of the optional Auth server.
endhost_apis:
type: object
description: Listening Sockets for Endhost APIs
additionalProperties:
type: string
propertyNames:
type: integer
description: Endhost API instance identifier.
minimum: 0
endhost_discovery_apis:
type: object
description: Listening Sockets for Endhost API discovery APIs
additionalProperties:
type: string
propertyNames:
type: integer
description: Endhost Discovery API instance identifier.
minimum: 0
external_ases:
type: object
description: Listening Sockets for External ASes, keyed by (ISD-AS, interface ID)
additionalProperties:
type: string
propertyNames:
type: array
items: false
prefixItems:
- type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
- type: integer
format: int32
minimum: 0
network_forwarders:
type: object
description: Listening Sockets for Network Forwarders
additionalProperties:
type: string
propertyNames:
type: string
router_sockets:
type: object
description: The list of SCION router sockets.
additionalProperties:
type: string
propertyNames:
type: integer
description: The router identifier.
minimum: 0
snaps:
type: object
description: The list of SNAP I/O configurations.
additionalProperties:
$ref: '#/components/schemas/IoSnapConfigDto'
propertyNames:
type: integer
description: The SNAP identifier.
minimum: 0
IoControlPlaneConfigDto:
type: object
description: The I/O configuration of a SNAP control plane.
properties:
api_addr:
type: string
description: The Control plane API address.
IoDataPlaneConfigDto:
type: object
description: The I/O configuration of a SNAP data plane.
properties:
addr:
type: string
description: The data plane address.
IoSnapConfigDto:
type: object
description: The I/O configuration of a SNAP.
required:
- control_plane
- data_plane
properties:
control_plane:
$ref: '#/components/schemas/IoControlPlaneConfigDto'
description: The control plane address of the SNAP.
data_plane:
$ref: '#/components/schemas/IoDataPlaneConfigDto'
description: The list of data plane I/O configurations.
Isd:
type: integer
format: int32
description: |-
A 16-bit identifier of a SCION Isolation Domain.
See [this table][anapaya-assignments] for current ISD network assignments.
[anapaya-assignments]: https://docs.anapaya.net/en/latest/resources/isd-as-assignments/
minimum: 0
IsdAsn:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
IsdCa:
type: object
description: |-
CA certificate for an ISD-AS, containing the certificate and private key for the CA, as well as
the root certificate for the ISD
required:
- isd_as
- root
- intermediary
properties:
intermediary:
$ref: '#/components/schemas/CertifiedKeyPair'
description: The intermediary identity for this CA
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: The ISD-AS for this CA
root:
$ref: '#/components/schemas/CertifiedKeyPair'
description: The root identity for this CA
IsdTrustStore:
type: object
description: Isd specific trust store, containing the TRC and CA certificates for the ISD
required:
- isd
- trc
- ca_certs
- as_certs
properties:
as_certs:
type: object
description: The AS certificates for this ISD, keyed by ISD-AS
additionalProperties:
$ref: '#/components/schemas/CertifiedKeyPair'
propertyNames:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
ca_certs:
type: object
description: The CA certificates for this ISD, keyed by ISD-AS
additionalProperties:
$ref: '#/components/schemas/IsdCa'
propertyNames:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
isd:
$ref: '#/components/schemas/Isd'
description: The ISD for this trust store
trc:
$ref: '#/components/schemas/StoreTrc'
description: The TRC of this ISD
NetworkForwarderState:
type: object
description: |-
Serializable state of a network forwarder stored in the system state. This is used to create a
[NetworkForwarder] when the app starts up.
required:
- local_as
- sim_addr
- queue_size
- forward_addr
properties:
forward_addr:
type: string
description: |-
The peer to send/receive packets to/from on the real network. The forwarder will only
accept packets from this address on the real network, and will forward packets to this
address on the real network.
local_as:
$ref: '#/components/schemas/IsdAsn'
description: |-
The AS number to listen for packets from the network simulation. The forwarder will only
accept packets from this AS on the network simulation, and will forward packets to this AS
on the network simulation.
queue_size:
type: integer
description: The maximum number of packets that can be queued for the sim socket.
minimum: 0
sim_addr:
type: string
description: |-
The IP address to listen for packets from the network simulation. The forwarder will only
accept packets to this address from the network simulation, and will forward packets as
this address on the network simulation.
ReadyState:
type: string
description: PocketSCION ready state.
enum:
- Ready
- NotReady
Router:
type: object
description: Router in pocketSCION.
required:
- isd_as
- addr
properties:
addr:
type: string
description: Router socket address.
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: The ISD-AS of the AS the router belongs to.
RouterStateDto:
type: object
description: The state of a SCION router emulated by PocketScion.
required:
- isd_as
- if_ids
properties:
if_ids:
type: array
items:
type: integer
format: int32
minimum: 0
description: The list of interface IDs of the router.
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: The ISD-AS of the router.
snap_data_plane_excludes:
type: array
items:
type: string
description: |-
The list of networks towards which SCION traffic will not be routed through
the available SNAPs.
snap_data_plane_interfaces:
type: object
description: The SNAP data planes that are connected to the router.
additionalProperties:
type: string
propertyNames:
type: string
RoutersResponse:
type: object
description: Router response.
required:
- routers
properties:
routers:
type: object
description: Map of routers.
additionalProperties:
$ref: '#/components/schemas/Router'
propertyNames:
type: integer
description: The router identifier.
minimum: 0
ScionAsDto:
oneOf:
- type: object
description: |-
AS that is simulated by PocketSCION. Packets to and from this AS will be handled by the
simulator.
required:
- isd_asn
- is_core_as
- forwarding_key
- type
properties:
forwarding_key:
type: array
items:
type: integer
format: int32
minimum: 0
description: Forwarding key of the AS, encoded as base64
is_core_as:
type: boolean
description: Whether this AS is a core AS
isd_asn:
$ref: '#/components/schemas/IsdAsn'
description: ISD-AS number of the AS
type:
type: string
enum:
- simulated
- type: object
description: |-
AS that is not simulated by PocketSCION, but is still part of the topology. Packets to and
from this AS will be handled by an external implementation.
required:
- isd_asn
- is_core_as
- type
properties:
is_core_as:
type: boolean
description: Whether this AS is a core AS
isd_asn:
$ref: '#/components/schemas/IsdAsn'
description: ISD-AS number of the AS
type:
type: string
enum:
- external
description: Human readable Pocket SCION AS
ScionGlobalInterfaceId:
type: object
description: Globally unique identifier for a SCION interface.
required:
- isd_as
- if_id
properties:
if_id:
type: integer
format: int32
description: Interface ID within the AS.
minimum: 0
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: ISD-AS number of the AS the interface belongs to.
example: 1-1#0
ScionRouter:
type: object
description: Representation of a SCION Router, which can be associated with an AS in the topology.
required:
- interfaces
- ip
properties:
interfaces:
$ref: '#/components/schemas/ScionRouterInterface'
description: The interface IDs of the router within the AS.
ip:
type: string
description: The IP address of the router.
example: 192.168.1.1
ScionRouterInterface:
oneOf:
- type: string
description: |-
The router is not explicitly associated with any interface, and should be used as a fallback
for the AS unless another router is explicitly assigned.
enum:
- Fallback
- type: object
description: The router is associated with the given interface IDs.
required:
- Ids
properties:
Ids:
type: array
items:
type: integer
format: int32
minimum: 0
description: The router is associated with the given interface IDs.
description: Defines the interfaces associated with a SCION router.
ScionTopologyDto:
type: object
description: Human readable ScionTopology
required:
- trust_store
- as_list
- links
- routers
properties:
as_list:
type: array
items:
$ref: '#/components/schemas/ScionAsDto'
links:
type: array
items:
$ref: '#/components/schemas/pocketscion::network::scion::topology::dto::ScionLinkDto'
routers:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/ScionRouter'
propertyNames:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
trust_store:
$ref: '#/components/schemas/TrustStore'
Snap:
type: object
description: SNAP in pocketSCION.
required:
- control_plane_api
properties:
control_plane_api:
type: string
description: SNAP control plane API address.
SnapStateDto:
type: object
description: The state of a SNAP.
required:
- isd_as
properties:
isd_as:
$ref: '#/components/schemas/IsdAsn'
description: The ISD-AS of the SNAP.
SnapsResponse:
type: object
description: SNAP response.
required:
- snaps
properties:
snaps:
type: object
description: Map of SNAPs.
additionalProperties:
$ref: '#/components/schemas/Snap'
propertyNames:
type: integer
description: The SNAP identifier.
minimum: 0
StatusResponse:
type: object
description: Status response.
required:
- state
properties:
state:
$ref: '#/components/schemas/ReadyState'
description: The current ready state of pocketSCION.
StoreCertificateDer:
type: string
description: Wrapper around CertificateDer
StoreKeyDer:
type: string
description: Wrapper around PrivateKeyDer
StoreTrc:
type: string
SystemStateDto:
type: object
description: The pocket SCION system state.
required:
- snap_token_public_key
- snaps
- routers
- endhost_apis
- endhost_api_discovery_api
- external_ases
- control_service_states
- network_forwarders
properties:
auth_server_state:
$ref: '#/components/schemas/AuthServerStateDto'
description: Test authentication server.
control_service_states:
type: object
description: The state of the control service for each ISD-AS
additionalProperties:
$ref: '#/components/schemas/ControlServiceState'
propertyNames:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
endhost_api_discovery_api:
type: object
description: Endhost API discovery state
additionalProperties:
$ref: '#/components/schemas/EndhostApiDiscoveryStateDto'
propertyNames:
type: integer
description: Endhost Discovery API instance identifier.
minimum: 0
endhost_apis:
type: object
description: The list of Endhost APIs
additionalProperties:
$ref: '#/components/schemas/EndhostApiState'
propertyNames:
type: integer
description: Endhost API instance identifier.
minimum: 0
external_ases:
type: object
description: The list of external ASes, keyed by ISD-AS.
additionalProperties:
$ref: '#/components/schemas/ExternalAsStateDto'
propertyNames:
type: string
description: |-
The combined ISD and AS identifier of a SCION AS (sometimes abbreviated as IA).
# Examples
```
# use scion_proto::address::IsdAsn;
#
# fn main() -> Result<(), Box<dyn std::error::Error>> {
assert_eq!(IsdAsn(0x1_ff00_0000_0110), "1-ff00:0:110".parse()?);
# Ok(())
# }
```
examples:
- 1-ff00:0:110
pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
network_forwarders:
type: object
description: |-
The list of network forwarders, keyed by the SCION address of the forwarder on the network
simulation.
additionalProperties:
$ref: '#/components/schemas/NetworkForwarderState'
propertyNames:
type: string
root_secret:
type:
- string
- 'null'
description: |-
The root secret used to derive the secrets for the SNAPs.
It must base 64 encoded and 32 bytes long.
routers:
type: object
description: The list of SCION routers.
additionalProperties:
$ref: '#/components/schemas/RouterStateDto'
propertyNames:
type: integer
description: The router identifier.
minimum: 0
snap_token_public_key:
type: string
description: The public key (PEM format) to verify SNAP tokens.
snaps:
type: object
description: The list of SNAPs in the system.
additionalProperties:
$ref: '#/components/schemas/SnapStateDto'
propertyNames:
type: integer
description: The SNAP identifier.
minimum: 0
snaptun_keepalive_interval:
type: string
description: The keepalive interval for the SNAPtun connection(s).
topology:
$ref: '#/components/schemas/ScionTopologyDto'
description: Scion Topology used for routing
TokenExchangerConfigDto:
type: object
description: Token exchanger configuration.
required:
- private_key
- token_lifetime
- fake_idp
properties:
fake_idp:
$ref: '#/components/schemas/FakeIdpDto'
description: The fake identity provider for testing.
private_key:
type: string
description: The private key (PEM format) used to sign SNAP tokens.
token_lifetime:
type: string
description: The lifetime of the SNAP tokens.
TokenExchangerStateDto:
type: object
description: The state of the token exchanger.
required:
- config
- id_mapping
properties:
config:
$ref: '#/components/schemas/TokenExchangerConfigDto'
description: The configuration of the token exchanger.
id_mapping:
type: object
description: List of identity mappings (SSID -> PSSID).
additionalProperties:
type: string
propertyNames:
type: string
TrustStore:
type: object
description: Pocket SCION trust store
required:
- isds
properties:
isds:
type: object
description: The ISD trust stores, keyed by ISD
additionalProperties:
$ref: '#/components/schemas/IsdTrustStore'
propertyNames:
type: integer
format: int32
description: |-
A 16-bit identifier of a SCION Isolation Domain.
See [this table][anapaya-assignments] for current ISD network assignments.
[anapaya-assignments]: https://docs.anapaya.net/en/latest/resources/isd-as-assignments/
minimum: 0
pocketscion::network::scion::topology::dto::ScionLinkDto:
type: string
examples:
- 1-ff00:0:110 parent_of ff00:0:111
tags:
- name: management
description: Operations related to the management of Pocket SCION