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.3.0
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
/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'
/snaps/{snap_id}/connections/{socket_addr}:
delete:
tags:
- management
summary: Delete (close) a snaptun connection from the server side.
operationId: delete_snap_connection
responses:
'204':
description: Connection closed successfully
'404':
description: Connection not found
/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.
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
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.
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
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
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.
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+$
ReadyState:
type: string
description: PocketSCION ready state.
enum:
- Ready
- NotReady
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
ScionAsDto:
type: object
description: Human readable Pocket SCION AS
required:
- isd_asn
- is_core_as
- forwarding_key
properties:
forwarding_key:
type: array
items:
type: integer
format: int32
minimum: 0
is_core_as:
type: boolean
isd_asn:
$ref: '#/components/schemas/IsdAsn'
ScionTopologyDto:
type: object
description: Human readable ScionTopology
required:
- as_list
- links
properties:
as_list:
type: array
items:
$ref: '#/components/schemas/ScionAsDto'
links:
type: array
items:
$ref: '#/components/schemas/pocketscion::network::scion::topology::dto::ScionLinkDto'
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.
SystemStateDto:
type: object
description: The pocket SCION system state.
required:
- snap_token_public_key
- snaps
- routers
- endhost_apis
properties:
auth_server_state:
$ref: '#/components/schemas/AuthServerStateDto'
description: Test authentication server.
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
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
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