From 29871926f7f1dc0cf6dc24ba214a9a0b95b2737a Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Tue, 16 May 2023 11:57:21 +0200 Subject: [PATCH] doc: control service manuals --- doc/beacon-metadata.rst | 60 +-- doc/conf.py | 1 + doc/control-plane.rst | 278 +++++++++- doc/cryptography/ca-operations.rst | 2 + doc/cryptography/drkey.rst | 4 + doc/glossary.rst | 36 +- doc/manuals/common.rst | 10 +- doc/manuals/control.rst | 805 +++++++++++++++++++++++++++++ doc/manuals/control/http-api.rst | 6 + doc/manuals/router.rst | 1 + doc/manuals/router/http-api.rst | 3 + doc/overview.rst | 2 + doc/protocols/scion-header.rst | 3 + doc/requirements.in | 1 + doc/requirements.txt | 126 ++++- 15 files changed, 1268 insertions(+), 70 deletions(-) diff --git a/doc/beacon-metadata.rst b/doc/beacon-metadata.rst index deaa479ad6..0086d95efc 100644 --- a/doc/beacon-metadata.rst +++ b/doc/beacon-metadata.rst @@ -294,64 +294,10 @@ are available: | Notes | The notes for each AS on the path | +-------------------+---------------------------------------------------------------------------------+ -Configuration File Format -========================= - -The control service obtains the information for the ``StaticInfoExtension`` -for the PCBs it sends out from a JSON configuration file, ``staticInfoConfig.json``. - -There is one top-level entry for each type of metadata. All entries are optional. - -- ``Latency`` is a map where the key is Interface ID ``i`` and the values are: - - +-------------+-------------------------------------------+-------------------------------------------------+ - | Name | Type | Description | - +=============+===========================================+=================================================+ - | ``Inter`` | Duration | Latency from interface ``i`` to remote AS | - +-------------+-------------------------------------------+-------------------------------------------------+ - | ``Intra`` | Map: Interface ID ``j`` : Duration | Latency from interface ``i`` to interface ``j`` | - +-------------+-------------------------------------------+-------------------------------------------------+ - -- ``Bandwidth`` is a map where the key is Interface ID ``i`` and the values are: - - +-------------+-------------------------------------------+-----------------------------------------------------------------+ - | Name | Type | Description | - +=============+===========================================+=================================================================+ - | ``Inter`` | Integer | Bandwidth in Kbit/s between interface ``i`` and the remote AS | - +-------------+-------------------------------------------+-----------------------------------------------------------------+ - | ``Intra`` | Map: Interface ID ``j`` : Integer | Bandwidth in Kbit/s between interface ``i`` and interface ``j`` | - +-------------+-------------------------------------------+-----------------------------------------------------------------+ - -- ``Geo`` is a map where the key is Interface ID ``i`` and the values are: - - +-----------------+-----------------+-----------------------------------------------+ - | Name | Type | Description | - +=================+=================+===============================================+ - | ``Latitude`` | Decimal value | Longitude GPS coordinates of interface ``i`` | - +-----------------+-----------------+-----------------------------------------------+ - | ``Longitude`` | Decimal value | Latitude GPS coordinate of interface ``i`` | - +-----------------+-----------------+-----------------------------------------------+ - | ``Address`` | String | Address of interface ``i`` | - +-----------------+-----------------+-----------------------------------------------+ - -- ``LinkType`` is a map where the key is Interface ID ``i`` and the value is one of - - - ``"direct"`` - - ``"multihop"`` - - ``"opennet"`` - -- ``Hops`` is a map where the key is Interface ID ``i`` and the values are: - - +-------------+------------------------------------+----------------------------------------------------------------------+ - | Name | Type | Description | - +=============+====================================+======================================================================+ - | ``Intra`` | Map: Interface ID ``j`` : Integer | Number of internal hops between interface ``i`` and interface ``j`` | - +-------------+------------------------------------+----------------------------------------------------------------------+ - -- ``Note`` is a string. +.. _path-metadata-example-conf: Example Configuration ---------------------- +===================== Let us look at an AS with three interfaces with IDs 1, 2, 3 and 5 which looks like the diagram below. The values attached to the connections @@ -360,7 +306,7 @@ represent the latency in milliseconds between interfaces. .. figure:: fig/beacon_metadata/example_config_metrics.png :width: 50% -The configuration file for this AS could then look like this: +The :ref:`staticInfoConfig.json ` configuration file for this AS could then look like this: .. code:: JSON diff --git a/doc/conf.py b/doc/conf.py index 4a466f4c74..a3bd61c410 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,6 +21,7 @@ 'recommonmark', 'sphinx_rtd_theme', 'sphinx.ext.extlinks', + 'sphinxcontrib.openapi', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/control-plane.rst b/doc/control-plane.rst index 1ab5645bb8..bfb263c7e4 100644 --- a/doc/control-plane.rst +++ b/doc/control-plane.rst @@ -10,11 +10,283 @@ Control Plane hidden-paths beacon-metadata + +Introduction +============ + The SCION control plane is responsible for discovering path segments and making them available to endpoints. This includes path-segment exploration (also called "beaconing"), registration, lookup, and finally the combination of path-segments to end-to-end paths. -.. admonition:: TODO +.. Note: content based on (extracts from) IETF draft draft-dekater-scion-controlplane-00. + +The **control service** is responsible for the path exploration and registration processes in the +control plane. +It is the main control-plane infrastructure component within each SCION :term:`AS`. +The control service of an AS has the following tasks: + +- Generating, receiving, and propagating :term:`Path Construction Beacons (PCBs) `. + Periodically, the control service of a core AS generates a set of PCBs, which are forwarded to the + child ASes or neighboring core ASes. + In the latter case, the PCBs are sent over policy-compliant paths to discover multiple paths + between any pair of core ASes. +- Selecting and registering the set of path segments via which the AS wants to be reached. +- Managing certificates and keys to secure inter-AS communication. + Each PCB contains signatures of all on-path ASes. + Every time the control service of an AS receives a PCB, it validates the PCB's authenticity. + When the control service lacks an intermediate certificate, it can query the control service of + the neighboring AS that sent the PCB. + +Path Segments +------------- + +As described previously, the main goal of SCION's control plane is to create and manage path +segments, which can then be combined into forwarding paths to transmit packets in the data plane. +SCION distinguishes the following types of path segments: + +- A path segment from a non-core AS to a core AS is an *up-segment*. +- A path segment from a core AS to a non-core AS is a *down-segment*. +- A path segment between core ASes is a *core-segment*. + +So each path segment either ends at a core AS, or starts at a core AS, or both. + +.. note:: + + There are no SCION path segments that start and end at a non-core AS. However, when combining + path segments into an end-to-end SCION path, shortcuts and peering-links can be used. + +All path segments are reversible: A core-segment can be used bidirectionally, and an up-segment can +be converted into a down-segment, or vice versa, depending on the direction of the end-to-end path. +This means that all path segments can be used to send data traffic in both directions. + +.. _control-plane-beaconing: + +Path Exploration (Beaconing) +============================ + +**Path exploration** is the process where an AS discovers paths to other ASes. In SCION, this +process is referred to as *beaconing*. + +In SCION, the *control service* of each AS is responsible for the beaconing process. +The control service generates, receives, and propagates *path-segment construction beacons (PCBs)* +on a regular basis, to iteratively construct path segments. +PCBs contain topology and authentication information, and can also include additional metadata that +helps with path management and selection. +The beaconing process itself is divided into routing processes on two levels, where *inter-ISD* or +core beaconing is based on the (selective) sending of PCBs without a defined direction, and +*intra-ISD* beaconing on top-to-bottom propagation. +This division of routing levels is a key architectural decision of SCION and important for achieving +a better scalability. + +- *Inter-ISD or core beaconing* is the process of constructing path segments between core ASes in + the same or in different ISDs. During core beaconing, the control service of a core AS either + initiates PCBs or propagates PCBs received from neighboring core ASes to other neighboring core + ASes. Core beaconing is periodic; PCBs are sent over policy-compliant paths to discover multiple + paths between any pair of core ASes. +- *Intra-ISD beaconing* creates path segments from core ASes to non-core ASes. For this, the control + service of a core AS creates PCBs and sends them to the non-core child ASes (typically customer + ASes). The control service of a non-core child AS receives these PCBs and forwards them to its + child ASes, and so on. This procedure continues until the PCB reaches an AS without any customer + (leaf AS). As a result, all ASes within an ISD receive path segments to reach the core ASes of + their ISD. + +On its way, a PCB accumulates cryptographically protected path- and forwarding information per +traversed AS. At every AS, metadata as well as information about the AS's ingress and egress +interfaces are added to the PCB. + +Origination of PCBs +------------------- + +Every core AS originates PCBs at regular intervals, and sends these to all egress interfaces to +connected neighbor ASes. +An originated PCB sent to a neighboring core ASes initiates an inter-ISD beacon, ultimately +resulting in a core-segment. +An originated PCB sent to a child AS initiates the intra-ISD beacon creating an up/down segment. + +Propagation of PCBs +------------------- + +PCBs are propgated at regular intervals at each AS. +When PCBs are received, they are not propagated immediately, but put into temporary storage +until the next propagation event. +The selection and propagation of PCBs differs between the inter-ISD and intra-ISD beacon schemes. + +Core ASes implement the inter-ISD / core beaconing scheme. +For every interface connecting to a neighboring core AS: + +1. Select the best :math:`N` PCBs for each origin core AS. + This can take into account both the available PCBs as well as local policies and information + about the link to the neighbor. +2. Extend the selected PCBs by adding an *AS Entry* +3. Send the extended PCBs over the interface + +Non-core ASes implement the intra-ISD / non-core beaconing scheme. +For every interface connecting to a child AS: + +1. Select the best :math:`N` PCBs. + This can take into account both the available PCBs as well as local policies and information + about the link to the child AS. +2. Extend the selected PCBs by adding an *AS Entry* +3. Send the extended PCBs over the interface + +AS Entries +---------- + +Every AS adds a signed *AS entry* to the PCBs it originates, propagates or terminates. + +This AS entry includes the relevant network topology information for this AS-hop +defined by the ingress and egress :term:`interface IDs ` of the beacon. +The so-called *hop field* includes a MAC that authorizes the use of this hop in the path +segment defined by the PCB, until it expires. +See the description of the :ref:`SCION Path ` in the data plane section for more +details on the hop field format and the MAC chaining mechanism. + +Additionally, an AS entry can contain :doc:`metadata ` such as the link MTU, +geographic locations of the AS routers, latencies, etc. + +Such an AS entry includes a hop field that specifies the ingress and egress +:term:`interface ID ` for this hop through the AS. +This hop field includes an expiration time MAC, + +Peering Links +------------- + +PCBs do not traverse peering links. +Instead, available peering links are announced along with a regular path in the individual AS +entries of PCBs. +If both ASes at either end of a peering link have registered path segments that include a specific +peering link, then it can be used to during segment combination to create an end-to-end path. + +.. _control-plane-registration: + +Registration of Path Segments +============================= + +**Path registration** is the process where an AS transforms selected PCBs into path segments, +"terminating" them by adding a final AS entry with a zero egress interface, +and adds these segments to the relevant path databases, thus making them available for the path +lookup process. + +As mentioned previously, a non-core AS typically receives several PCBs representing path segments to +the core ASes of the ISD the AS belongs to. +Out of these PCBs, the non-core AS selects those down-path segments through which it wants to be +reached, based on AS-specific selection critera. +The next step is to register the selected down-segments with the control service of the +core AS that originated the PCB. + + +Intra-ISD Path-Segment Registration +----------------------------------- + +Every *registration period* (determined by each AS), the AS's control service selects of +PCBs to transform into path segments: + +- Up-segments, which allow the infrastructure entities and endpoints in this AS to communicate with + core ASes. + Up-segments are registered in the local path database of the AS. +- Down-segments, which allow remote entities to reach this AS. + Down-segments are registered, via a remote-procedure call, in the path-segment database of the + core AS that originated the PCB. + As a result, a core AS's path database contains all down-segments registered by the + non-core ASes in its customer cone. + +Core Path-Segment Registration +------------------------------ + +The core beaconing process creates PCBs from core AS to core AS. +Every *registration period*, the AS's control service selects sets of PCBs to turn into path +segments and register. +These selected core-segments are added to the local path database of the core AS that created the +segment (i.e. the one at the end of the beacon chain), so that local and remote endpoints can obtain +and use these core-segments. +In contrast to the down-segment registration procedure, there is no need to register core-segments +with other core ASes (as each core AS will receive PCBs originated from every other core AS). + + +Path Lookup +=========== + +An endpoint (source) that wants to start communication with another endpoint (destination), needs +up to three path segments: + +- An up-path segment to reach the core of the source ISD +- a core-path segment to reach + + - another core AS in the source ISD, in case the destination AS is in the same source ISD, or + - a core AS in a remote ISD, if the destination AS is in another ISD, and + +- a down-path segment to reach the destination AS. + +The process to look up and fetch path segments consists of the following steps: + +1. First, the source endpoint queries the control service in its own AS (i.e., the source AS) for + the required segments. + The control service has up-path segments stored in its path database. +2. The control service in the source AS queries the control services of the reachable core ASes in + the source ISD, for core-path segments to core ASes in the destination ISD (which is either the + local or a remote ISD). + To reach the core control services, the control service of the source AS uses the locally stored + up-path segments. +3. The control service then queries the control services of the remote core ASes in the destination + ISD, to fetch down-path segments to the destination AS. + To reach the remote core ASes, the control service of the source AS uses the previously obtained + and combined up- and core segments. +4. Finally, the control service of the source AS returns all retrieved path segments to the source + endpoint. +5. The endpoint combines all path segments into an end-to-end path + +All remote path-segment lookups by the control service are cached. + +On SCION end-hosts, a :doc:`SCION daemon ` is usually employed to do the +path-lookup on behalf of applications. This SCION daemon also caches path-segment lookup results. + +.. table:: Control services responsible for different types of path segments + + ============ =========================== + Segment Type Responsible control service(s) + ============ =========================== + Up-segment Control service of the source AS + Core-segment Control service of core ASes in source ISD + Down-segment Control service of core ASes in destination ISD (either the local ISD or a remote ISD) + ============ =========================== + +Path-Segment Combination +======================== + +The last step of the path-resolution process is to combine the available up-, core- and down- +path segments to end-to-end forwarding paths. +This path-segment combination process is done by each endpoint separately. +Typically, end-hosts run the :doc:`SCION daemon ` which centralizes the +path-resolution process and returns fully formed end-to-end paths to applications. +However, applications could also choose to bypass the daemon and perform the path-resolution +directly. + +The figures below illustrate the various ways in which segments can be combined +to form end-to-end paths. +See the description of the :ref:`SCION Path` for the specifics on how these +end-to-end paths are encoded in the packet header. + +.. figure:: fig/beacon_metadata/path_combinations.png + :alt: Path Combinations + + Combination of path segments to paths: the blue circles represent the end + hosts; the shaded gray circles represent core ASes, possibly in different + ISDs; blue lines without arrow heads denote hops of created forwarding + paths; the dashed blue line denotes a peering link (labeled "p"); orange + lines with arrows stand for PCBs and indicate their dissemination direction; + dashed orange lines represent core beacons exchanged over core links + (labeled "c"). All created forwarding paths in cases 1a-1e traverse the ISD + core(s), whereas the paths in cases 2-4 do not enter the ISD core. + + +.. seealso:: + + :doc:`overview` + Introduction to the SCION architecture and core concepts. + + :doc:`data-plane` + Description of SCION packet header formats and processing rules for packet forwarding based + the packed-carried forwarding state. - Control plane overview and detailed description of beaconing, registration, lookup, and - combination + `IETF Draft SCION Control Plane `_ + Formal description and specification of the SCION control plane. diff --git a/doc/cryptography/ca-operations.rst b/doc/cryptography/ca-operations.rst index 3a582e5f94..379b6a373f 100644 --- a/doc/cryptography/ca-operations.rst +++ b/doc/cryptography/ca-operations.rst @@ -120,6 +120,8 @@ To comply with custom security policies that dictate that a Root Key should sit behind an air gap, multiple CA certificates can be pre-generated for the same entity. +.. _ca-ops-as-certs: + AS Certificates =============== diff --git a/doc/cryptography/drkey.rst b/doc/cryptography/drkey.rst index a0e80d4010..36c63c4864 100644 --- a/doc/cryptography/drkey.rst +++ b/doc/cryptography/drkey.rst @@ -65,12 +65,16 @@ the :ref:`drkey-generic-derivation`. Both of them leverage the 4-level derivatio 4-level derivation ------------------ +.. _drkey-secret: + **Secret value (Level 0)** Each AS locally derives one :math:`SV_A^{protocol}` per protocol and epoch. This secret value is renewed at every epoch and it is only shared with trustworthy entities that require to derive keys on the fly for the specified protocol. +.. _drkey-as-as: + **AS-AS (Level 1)** The ``AS-AS`` key is derived locally in the AS :math:`A` CS (:math:`CS_A`) and exchanged diff --git a/doc/glossary.rst b/doc/glossary.rst index 561b6cbf95..74c975cf89 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -27,6 +27,13 @@ Glossary In SCION, BFD is used to determine the liveness of the link between two border routers and trigger :term:`SCMP` error messages. + CA + Certificate Authority + + An entity that signs and issues digital certificates , certifying the ownership of a public + key by the named subject of the certificate. + CAs are a part of a public key infrastructure, like the SCION :term:`Control-Plane PKI`. + CP-PKI Control-Plane PKI @@ -34,6 +41,8 @@ Glossary allows to tie cryptographic keys to SCION AS identifiers. This is the machinery that allows to authenticate SCION control-plane messages. + See :doc:`/cryptography/index`. + End Host Endpoint A SCION **end host** is a computer or other device connected to a computer network in a @@ -48,13 +57,19 @@ Glossary End host is preferred where the focus is (physical or virtual) machines and the software running on them, and endpoint is used otherwise. + Interface ID + An interface ID is the AS-local identifier for an inter-domain link. + + The interface ID is an arbitrary number between 1 and 65535, + assigned without external coordination by the operator of the AS. + ISD Isolation Domain An Isolation Domain (ISD) is a set of participating :term:`ASes `. ISDs can overlap, i.e. ASes can participate in multiple ISDs. - An ISD represents a scope for Certificate Authorities (CAs) in the :term:`Control-Plane PKI`; + An ISD represents a scope for :term:`CAs ` in the :term:`Control-Plane PKI`; CAs can issue certificates exclusively to ASes in their ISD. At the same time Isolation Domains also serve as a local routing domain. @@ -63,6 +78,17 @@ Glossary Only the core ASes (i.e. the ASes at the top(s) of this directed acyclic graph) need to participate in the less efficient inter-ISD path discovery. + See :ref:`overview-isds`. + + Beacon + PCB + Path-Segment Construction Beacon + + Path-Segment Construction Beacons are control-plane messages that are propagated through a + SCION network during the :ref:`path exploration ("beaconing") ` process. + On their way, PCBs accumulate authenticated network topology information (on the granularity + of :term:`ASes `). + SCMP SCION Control Message Protocol @@ -72,3 +98,11 @@ Glossary send error messages and for diagnostics (ping and traceroute). See :doc:`/protocols/scmp` for more information. + + TRC + Trust-Root Configuration + + Each :term:`ISD` has a separate trust-root configuration, specifying the core ASes acting as + :term:`CAs `. + + See :doc:`/cryptography/trc`. diff --git a/doc/manuals/common.rst b/doc/manuals/common.rst index 859ea7e561..6bc3e4b218 100644 --- a/doc/manuals/common.rst +++ b/doc/manuals/common.rst @@ -168,7 +168,7 @@ of the individual fields below. .. option:: attributes = [<"core">?], default [] - Role of this AS. ``["core"]`` for core-ASes, ``[]`` for non-core ASes. + Role of this AS. ``["core"]`` for core ASes, ``[]`` for non-core ASes. .. Note:: @@ -196,12 +196,9 @@ of the individual fields below. .. object:: interfaces - .. object:: + .. option:: - An interface ID is the AS-local identifier for an inter-domain link. - - The interface ID is an arbitrary number between 1 and 65535, - assigned without external coordination by the operator of the AS. + The :term:`interface ID ` for an inter-domain link. In this ``topology.json`` file, the ID is contained in a string. @@ -304,6 +301,7 @@ of the individual fields below. .. option:: Identifier for a control service instance. + Matches the :option:`general.id ` of a control service instance. .. option:: addr = , required diff --git a/doc/manuals/control.rst b/doc/manuals/control.rst index b7c26e7299..7257066cf7 100644 --- a/doc/manuals/control.rst +++ b/doc/manuals/control.rst @@ -2,6 +2,792 @@ Control Service *************** +:program:`control` is the SCION control service. +It discovers SCION paths by participating in the inter-domain path-dissemination process called +"beaconing". +It signs and validates the path information based on the :term:`Control-Plane PKI `. + +The :program:`control` service is also the recursive resolver for path information for endpoints in +the local AS. + +In core ASes, the :program:`control` service also acts as the certificate authority from which ASes +in the local ISD request renewed certificates (or as a proxy thereof). + +See :doc:`/control-plane` for an introduction to the SCION control plane and the tasks of the +:program:`control` service. + +Command line reference +====================== + +.. program:: control + +.. option:: --config + + Specifes the :ref:`configuration file ` and starts the control service. + +.. option:: help, -h, --help [subcommand] + + Display help text for subcommand. + +.. option:: version + + Display version information. + +.. option:: sample [file] + + Display sample files. + + .. option:: config + + Display a sample :ref:`configuration file `. + + .. option:: policy + + Display a sample :ref:`beaconing policy file ` + +.. option:: completion [shell] + + Generate the autocompletion script for :program:`control` for the specified shell. + + Run :option:`control help completion ` for a list of the available shells. + + Run :option:`control help completion [shell] ` for usage information on the + autocomplete script for a particular shell. + + +Environment variables +--------------------- + +.. envvar:: SCION_TESTING_DRKEY_EPOCH_DURATION + + For **testing only**. + + Override the global duration for :doc:`/cryptography/drkey` epochs. + This can only work correctly if the same value is set for all connected control services in the + test network. + + The format is a :ref:`duration ` with unit suffix (e.g. ``10s``). + +Configuration +============= + +The :program:`control` service is configured with multiple files: + +- the :ref:`.toml `, + specified on the command line by the :option:`--config ` option, is the main + configuration file. + It configures common features like logging and metrics and + specifies the **configuration directory** from which all other configuration files are read. +- :ref:`topology.json `, contains information about the inter-AS links +- :ref:`beaconing policy ` configuration files +- :ref:`crypto/ and certs/ ` contain :term:`CP-PKI` certificates and private keys +- :ref:`keys/ ` contains the AS's forwarding secret keys +- :ref:`staticInfoConfig.json `, if it exists, specifies values for the :doc:`/beacon-metadata`. + +.. _control-conf-toml: + +Control service configuration +----------------------------- + +In addition to the :ref:`common .toml configuration options `, the control service +considers the following options. + +.. program:: control-conf-toml + +.. object:: general + + .. option:: general.id = (Required) + + Identifier for this control service. + + This is used to identify which parts of the :ref:`control-conf-topo` file refer to self. + Thus, ``id`` must match a key in the :ref:`control-conf-topo` files' ``control_service`` section. + + .. option:: general.config_dir = (Required) + + Path to a directory containing the remaining configuration files. + + If this is a relative path, it is interpreted as relative to the current working directory of the + program (i.e. **not** relative to the location of this .toml configuration file). + + .. option:: general.reconnect_to_dispatcher = (Default: false) + + Transparently reconnect to the dispatcher on dispatcher failure or restarts. + + .. Warning:: + This should be set to ``true``, unless your service orchestration ensures that + failures of the dispatcher trigger a restart of :program:`control` also. + +.. object:: features + + Features is a container for generic, boolean feature flags (usually for experimental or + transitional features). + + .. option:: features.appropriate_digest_algorithm = (Default: false) + + Enables the CA module to sign issued certificates + with the appropriate digest algorithm instead of always using ECDSAWithSHA512. + + **Transition**: This behaviour should be enabled unless there is a specific requirement to + interface with older versions of SCION that don't support these certificates. + The default for this flag will be changed to ``true`` in future releases, and the flag will + eventually be removed. + +.. object:: api + + .. option:: api.addr = (Optional) + + Address on which to expose the :ref:`control-rest-api`, + in the form ``host:port``, ``ip:port`` or ``:port``. + +.. object:: tracing + + Tracing with `OpenTracing `_ / `Jaeger `_. + This is especially helpful when collecting the traces of multiple service instances, e.g. when + :doc:`running a local SCION topology `. + + .. option:: tracing.enabled = (Default = false) + + .. option:: tracing.debug = (Default = false) + + .. option:: tracing.agent = (Default = "localhost:6831") + + Address of the local agent that handles the reported traces. + +.. object:: quic + + .. option:: quic.address = (Optional) + + Local SCION address for inter-AS communication by QUIC/gRPC. + By default, the address specified for this control service in its ``control_service`` entry of + the :ref:`control-conf-topo` is used. + +.. object:: beaconing + + .. option:: beaconing.origination_interval = (Default = "5s") + + Specifies the interval between originating beacons in a core AS. + + .. option:: beaconing.propagation_interval = (Default = "5s") + + Specifies the interval between propagating beacons. + + .. option:: beaconing.registration_interval = (Default = "5s") + + Specifies the interval between registering path segments. + + .. option:: beaconing.policies + + File paths for :ref:`control-conf-beacon-policies`. + If these are the empty string, the default policy is used. + + The different policies *may* point to the same file(s). + + .. option:: beaconing.policies.propagation = + .. option:: beaconing.policies.core_registration = + .. option:: beaconing.policies.up_registration = + .. option:: beaconing.policies.down_registration = + + + .. option:: beaconing.epic = (Default: false) + + Specifies whether the EPIC authenticators should be added to the beacons. + +.. object:: path + + .. option:: path.query_interval = (Default = "5m") + + Specifies after how much time path segments for a destination AS should be refetched. + + .. option:: path.hidden_paths_cfg = (Optional) + + Location of the :doc:`hidden paths ` configuration. + + The location is specified as a file path (relative to the working directory of the program) + or an HTTP/HTTPS URL. + +.. object:: ca + + .. option:: ca.mode = "disabled"|"in-process"|"delegating" (Default: "disabled") + + Mode defines whether the :program:`control` should handle certificate issuance requests. + This should be enabled in core ASes that are labeled as ``issuing`` ASes in the :term:`TRC`. + + If set to ``in-process``, :program:`control` handles certificate issuance requests on its own. + If set to ``delegated``, the certificate issuance is delegated to the service defined in + :option:`ca.service `. + + .. option:: ca.max_as_validity = (Default: "3d") + + Defines the the maximum lifetime for renewed AS certificates. + + .. option:: ca.service + + Configuration for the :term:`CA` service, + effective with the :option:`ca.mode ` mode ``delegated``. + + The CA service is expected to implement the API described by :file-ref:`spec/ca.gen.yml`. + + .. Hint:: + The `scionproto/scion `_ project does not include such + a standalone CA service implementation. + + The available options are: + + - use the built-in CA implementation (using :option:`ca.mode = "in-process" `), + - use the `netsys-lab/scion-ca `_ SCION CA + based on `smallstep's step-ca `_, + - ask SCION vendors for proprietary CA implementations and offerings, + - or plug in your own CA service implementing the :file-ref:`spec/ca.gen.yaml` API. + + .. option:: ca.service.address = + + Address of the CA Service that handles the delegated certificate renewal requests. + Specified with scheme, for example ``https://ca-service.local``, and optional + path relative to the server, such as ``https://ca-service.local/dev-test``. + + .. option:: ca.service.shared_secret = + + Path to the PEM-encoded shared secret that is used to create JWT tokens. + + The shared secret file is re-read from disk at 5 second intervals. + + .. option:: ca.service.lifetime = (Default: "10m") + + Validity period (a :ref:`duration `) of JWT authorization tokens + for the CA service. + + .. option:: ca.service.client_id = (Default: general.id) + + Client identifier for the CA service. + Defaults to :option:`general.id `. + +.. option:: beacon_db (Required) + + :ref:`Database connection configuration ` + for received :term:`PCB`\s. + + This database holds beacons that may be candidates for propagation. + If it is destroyed, the control service may temporarily not have beacons to propagate to + downstream neighbor ASes, until fresh PCBs are received from upstream neighbor ASes. + +.. option:: trust_db (Required) + + :ref:`Database connection configuration ` + for :term:`Control-Plane PKI` information. + + This database file contains cached TRC and AS certificate chains. + If it is destroyed, the control service will load locally available TRCs and certificate chains + from the corresponding :ref:`configuration directory `, and fetch other + certificate information from authoritative ASes on-demand. + +.. option:: path_db (Required) + + :ref:`Database connection configuration ` + for Path Segment data. + + This database contains path segments, both explicitly registered segments resulting from the + beaconing process, as well as cached results from path segment queries. + If it is destroyed, the explicitly registered paths may be lost until + they are rediscovered by the beaconing process. The path segments from cached path segment + queries will be re-fetched on-demand. + +.. object:: trustengine.cache + + Control the **experimental** in-memory caching of ISD/AS attribute information extracted from + :term:`TRCs `. + + .. option:: trustengine.cache.disable = (Default: false) + + Disable caching entirely. + + .. option:: trustengine.cache.expiration = (Default: 60000000000) + + Expiration of cached entries in nanoseconds. + + **TODO:** this should be changed to accept values in :ref:`duration format `. + +.. object:: drkey + + Configuration for the optional and still somewhat **experimental** :doc:`Dynamically Recreatable Key (DRKey) infrastructure `. + + See also :envvar:`SCION_TESTING_DRKEY_EPOCH_DURATION`. + + .. option:: drkey.level1_db (Optional) + + Enables the DRKey infrastructure if set. + + :ref:`Database connection configuration ` + for cached :ref:`AS-AS (Level 1) keys `. + + If it is destroyed, the control service may need to re-fetch keys from remote ASes. + + .. option:: drkey.secret_value_db + + Required if :option:`drkey.level1_db ` is set. + + :ref:`Database connection configuration ` + for key epochs and the corresponding :ref:`secret values (Level 0 keys) ` + derived from the :ref:`AS master keys `. + + .. warning:: + + This database is not a cache. + + If it is destroyed, the control service loses track of previously created key epochs. + As key derivation depends on the epoch, keys that have previously been requested / derived, + will not match any newly created keys. + The DRKey system is broken for this AS, at least until all entities have fetched new keys, + which may only happen after multiple epochs. + + .. option:: drkey.delegation = (Optional) + + Defines hosts with privileged access to obtain the protocol and epoch specific + :ref:`secret value (Level 0 key) `. + These hosts can locally derive keys shared with any remote AS, without having to request + them individually from the control service. + However, the hosts must be trusted to not abuse this, as they can also create keys + to impersonate any other host in the AS. + + The set of hosts authorized to access the secret value for delegated key derivation + are specified as a list of IP addresses per supported :ref:`DRKey protocol identifier `. + + .. code-block:: toml + + # Example + + [drkey.delegation] + scmp: ["203.0.113.17", "198.51.100.249"] + + .. option:: drkey.prefetch_entries = (Default: 10000) + + Maximum number of Level 1 keys that will be re-fetched preemptively before their expiration. + +.. _control-conf-topo: + +topology.json +------------- + +The :program:`control` reads the ``control_service`` section of the :ref:`topology.json ` file. + +The entry referring to its own :option:`general.id ` +define the addresses that :program:`control` will listen on. + +The interface definitions in the ``border_router`` entries define the inter-AS links. +These entries define the beacons that :program:`control` will originate and propagate. + +.. _control-conf-beacon-policies: + +Beaconing policies +------------------ + +A beaconing policy is a YAML file, defining processing rules for path-segment construction and +registration. +There are four policies with different but related purposes, that can individually be configured +with the :option:`beacon.policies ` options: + +Propagation + Propagation is the process of receiving a beacon from a neighbor AS, extending it + with the own AS entry and forwarding it to downstream neighbor ASes. + See :ref:`control-plane-beaconing`. + + The propagation policy determines which beacons are selected to be propagated and how they are + extended. + + Note that there is no separate policy type for beacon origination. The only policy value + affecting origination is the :option:`MaxExpTime `, which is + read from the propagation policy. + +Registration + Registration is the process of making beacons available as path-segments to the path lookup + process. + Beacons received from a neighbor AS are "terminated" by appending the own AS entry and registered + in a path-segment database, from which it can be later found with path-segment queries. + See :ref:`control-plane-registration`. + + CoreRegistration + Applies to the registration of core-segments in the local path store of a core AS. + + UpRegistration + Applies to the registration of up-segments in the local path store of a non-core AS. + + DownRegistration + Applies to the registration of down-segments. The policy is used by a non-core AS + to determine which down-segments it wants to make available to other ASes. + Each selected down-segments is registered, via a segment registration request, in the core AS + that originated it. + + .. note:: + There is currently no corresponding policy that applies to the processing of segment + registration requests in the core AS. + +From the description above, it is already evident that not all four policies are applicable for +core and non-core ASes. Summarizing this: + +.. table:: + + ================= ================================================ + AS type Applicable policies + ================= ================================================ + core Propagation, CoreRegistration + non-core Propagation, UpRegistration, DownRegistration + ================= ================================================ + + +The beaconing policy YAML configuration considers the following options: + +.. program:: control-conf-beacon-policy + +.. option:: Type = "Propagation"|"UpSegmentRegistration"|"DownSegmentRegistration"|"CoreSegmentRegistration" (Default: "") + + Restrict this policy configuration file to be used exclusively as one of the + :option:`beacon.policies ` options. + + Only as sanity check and organization of configuration files. No operational effect. + +.. option:: BestSetSize = int (Default: 20) + + Maximum number of segments to propagate/register **per origin AS**. + + In the ``Propagation`` policy, this parameter determines the number of beacons + propagated to neighbor ASes per origin AS. + That is, for each originating AS, up to ``BestSetSize`` beacons are forwarded. + For the core-beaconing process, the set of originating ASes are all other core ASes, which can + be very numerous. + + .. warning:: + + Keep this parameter reasonably low to avoid explosion of beacon numbers. + +.. option:: CandidateSetSize = int (Default: 100) + + Maximum number of segments to keep in beacon store and consider for selection to best set **per + origin AS**. + +.. option:: MaxExpTime = uint8 (Default: 63) + + Defines the maximum relative expiration time for the AS Entry when originating, propagating or + terminating a PCB. + + .. note:: + For beacon origination, the ``MaxExpTime`` value from the ``Propagation`` policy is used. + + The 8 bit unsigned integer :ref:`ExpTime ` fields represents an expiration + relative to the origination timestamp of the segment, with a nonzero minimum and a maximum + of 24 hours: + + .. math:: + (1 + ExpTime) \cdot \frac{24\cdot60\cdot60}{256}\mathrm{s} + + Every increment of `ExpTime` represents 5 minute and 37.5 seconds in duration. + + ============= ================ + ``ExpTime`` Duration (h:m:s) + ============= ================ + 0 0:05:37.5 + 1 0:11:15 + 2 0:16:52.5 + ... ... + 9 0:56:15 + 10 1:01:52.5 + 11 1:07:30 + ... ... + 63 6:00:00 + ... ... + 254 23:54:22.5 + 255 24:00:00 + ============= ================ + +.. option:: Filter + + Filters restrict the allowed beacons for the purposes of the policy (i.e. for propagation or + the different forms of registration). + + Filters are applied when a beacon is received, resulting in a "usage" classification of the + beacon that is stored in the local beacon database. + When the policy is changed, it will thus only be effective for newly received beacons. + + .. note:: + + Filters are currently not very expressive. Specifically, they cannot express filtering rules + that take into account the ingress or egress interface of the beacon. + + There are plans to extend this functionality but so far there are no concrete proposals. + If you're interested to work on this, get in contact in the :ref:`chat ` or create a + :ref:`proposal ` on github. + + .. option:: MaxHopsLength = + + Upper bound for the allowed number of AS entries in a received PCB. + + Filters are applied for received PCBs, before extending the segment. + Consequently, a propagated/terminated PCB may have up to ``MaxHopsLength + 1`` AS entries. + + .. option:: AsBlackList = + + Deny-list for ASes. + PCBs with any AS entry from any of the specified AS identifiers will be rejected. + + .. option:: IsdBlackList = + + Deny-list for ISDs. + PCBs with any AS entry from any of the specified ISD identifiers will be rejected. + + .. option:: AllowIsdLoop = (Default: true) + + Specifies whether ISD loops are allowed. + + A PCB is considered to be an ISD loop if it leaves and then re-enters an ISD. + +.. _control-conf-cppki: + +Control-Plane PKI +----------------- + +TRCs + :option:`/certs ` + + The :term:`TRC`\s for the :term:`Control-Plane PKI` are loaded from here. + TRCs are also written back to the :option:`trust_db `. + + Any TRC loaded from this directory will be written back to the trust_db. + Updated TRCs fetched from authoritative core ASes are stored both here in the filesystem and + in the trust_db. + + :program:`control` scans this directory for new TRCs at startup, and also when requesting signing + keys and the corresponding certificate chains. + + .. note:: + :program:`control` does **not** create TRCs. + TRC creation is an offline process, the :doc:`/cryptography/trc-signing-ceremony`. + + However, the :program:`control` does fetch new TRCs from neighbor ASes and store them into + this directory (/certs). + + +AS Certificates and Keys + :option:`/crypto/as ` + + :ref:`AS certificate chains ` and the corresponding keys, + used for signing control-plane messages and authenticating TLS sessions to other control + services, are loaded from here. + Certificates are also written back to the :option:`trust_db ` (but + keys are not). + + :program:`control` scans this directory for new certificates at startup, and also when loading + keys on demand. + + Keys are loaded from this directory on demand, with an in-memory cache with a lifetime of 5 + seconds. + + .. note:: + :program:`control` does **not** request renewal of its AS certificates. + + Certificate renewal can be requested using the :ref:`scion-pki_certificate_renew` tool. + Because AS certificates have short lifetimes, this *should* be automated by the operator. + +CA Certificates and Keys + :option:`/crypto/ca ` + + If the in-process :term:`CA` is used, :option:`ca.mode = "in-process" `, + the :ref:`CA certificates ` and corresponding keys are read from this + directory on demand, whenever a certificate renewal request is handled. + + .. note:: + Even if it is operating with active CA mode, + :program:`control` does **not** issue initial certificates for new ASes. + Issuance of initial AS certificates is an offline process. See :ref:`ca-ops-as-certs`. + +The control service is not directly involved in the creation of TRCs and consequently it is not +concerned with voting certificates. + +.. _control-conf-keys: + +Keys +---- + +:program:`control` loads the forwarding secret keys ``master0.key``/``master1.key`` from :option:`/keys `. + +The key files contain a base64-encoded high-entropy random string. +The keys should be exactly 16 bytes long (corresponding to a base64 encoding of 24 bytes with two trailing pad bytes ``==``). +These keys must be identical to the :ref:`corresponding keys used by the routers `. + +.. note:: + The :program:`router` and :doc:`control` currently use these keys as input for PBKDF2 to generate + the actual forwarding key. Consequently, keys of any size can currently be used. This may be changed + to only accept high-entropy 16 byte keys directly in the future. + +.. _control-conf-path-metadata: + +Path Metadata +------------- + +The ``StaticInfoExtension`` PCB extension allows to announce :doc:`path metadata in beacons `. + +:program:`control` loads the information for the ``StaticInfoExtension`` +for its AS entries from the optional JSON configuration file +:option:`/staticInfoConfig.json ` if it exists. + +This configuration is **optional**. +If the file does not exist, or if the configuration does not specify values for certain metadata +types or for certain interfaces, the corresponding ``StaticInfoExtension`` will either be omitted or +include only partial metadata. + +If the configuration file exists, it must be syntactically valid.. + +The structure of the configuration is presented as a pseudo-JSON with a more detailed explanation +of the individual fields below. + +.. code-block:: yaml + :caption: Pseudo-JSON description of the structure of the ``staticInfoConfig.json`` configuration file. + :name: staticinfoconfig-json-structure + + { + "Latency": { + : { + "Inter": , + "Intra": { + : + # ... + } + } + # ... + }, + "Bandwidth": { + : { + "Inter": , + "Intra": { + : + # ... + } + } + # ... + }, + "Geo": { + : { + "Latitude": , + "Longitude": , + "Address": + } + # ... + }, + "Linktype": { + : <"direct"|"multihop"|"opennet"> + # ... + }, + "Hops": { + : { + "Intra": { + : + # ... + } + } + # ... + }, + "Note": + } + +.. seealso:: + + :ref:`Example staticInfoConfig.json ` in the + :doc:`/beacon-metadata` section. + + +There is one top-level entry for each type of metadata, all of which are optional. +:term:`Interface ID` keys must be specified as strings (not numbers), e.g. ``"5"``. + +.. program:: control-conf-metadata + +.. option:: Latency + + Object where the keys are Interface ID ``i`` and the values are objects with: + + .. option:: Inter = + + Latency from interface ``i`` to the associated remote AS border router. + + .. option:: Intra = + + Latency from interface ``i`` to interface ``j``. + +.. option:: Bandwidth + + Object where the keys are Interface ID ``i`` and the values are objects with: + + .. option:: Inter = + + Bandwidth in Kbit/s between interface ``i`` and the associated remote AS border router. + + .. option:: Intra = + + Bandwidth in Kbit/s between interface ``i`` to interface ``j``. + +.. option:: Geo + + Object where the keys are Interface ID ``i`` and the values are objects with: + + .. option:: Latitude = + + Latitude GPS coordinate of interface ``i``. + + .. option:: address = + + Free-form civic address of interface ``i``. + +.. option:: LinkType + + Object where the keys are Interface ID ``i`` and the values describe the link associated + with interface ``i`` as one of: + + ``"direct"`` + Direct physical connection. + + ``"multihop"`` + Connection with local routing/switching. + + ``"opennet"`` + Connection overlayed over publicly routed Internet. + +.. option:: Hops + + Object where the keys are Interface ID ``i`` and the values are objects with: + + .. option:: Intra = map[interface-id j]: number + + Number of internal hops (e.g. number of AS-internal IP routers) between interface ``i`` and + interface ``j``. + +.. option:: Note = + + A free form string to communicate interesting/important information to other network operators. + + +.. _control-conf-duration: + +Duration Format +--------------- + +Where duration values are loaded from configuration options, the following format is expected: + +.. code-block:: + + [\-0-9]+(y|w|d|h|m|s|ms|us|µs|ns) + +The unit suffixes have their usual meaning of ``y`` year, ``w`` week, ``d`` day, ``h`` hour, +``m`` minute, ``s`` second, ``ms`` millisecond, ``us`` or ``µs`` microsecond, and ``ns`` nanosecond. + +Mixed unit durations are not supported (e.g. ``1h10m10s`` is not supported). +The long duration units are simple factors, not calendar offsets: + +- ``d`` is always 24 hours +- ``w`` is always 7 days +- ``y`` is always 365 days + + Port table ========== @@ -12,7 +798,26 @@ Metrics .. include:: ./control/metrics.rst +.. _control-http-api: + HTTP API ======== .. include:: ./control/http-api.rst + +.. _control-rest-api: + +REST API +======== + +The REST API described by the OpenAPI specification :file-ref:`spec/control.gen.yml` +is exposed by :program:`control` on the address defined by +:option:`api.addr `. + +Note that this is **separate** from the partially redundant, ad hoc :ref:`control-http-api`. + +Specification +------------- + +.. openapi:: /../spec/control.gen.yml + :group: diff --git a/doc/manuals/control/http-api.rst b/doc/manuals/control/http-api.rst index 39012418d9..54a39a9500 100644 --- a/doc/manuals/control/http-api.rst +++ b/doc/manuals/control/http-api.rst @@ -1,3 +1,9 @@ +.. warning:: + Note that this ad hoc HTTP API is **separate** from the partially redundant + :ref:`control-rest-api`. + The REST API should be preferred. + This HTTP API will be phased out. + The HTTP API is exposed by the ``control`` application on the IP address and port of the ``metrics.prometheus`` configuration setting. diff --git a/doc/manuals/router.rst b/doc/manuals/router.rst index 7bebbc39f1..4d2fe52f88 100644 --- a/doc/manuals/router.rst +++ b/doc/manuals/router.rst @@ -143,6 +143,7 @@ The :program:`router` loads the forwarding secret keys ``master0.key``/``master1 The key files contain a base64-encoded high-entropy random string. The keys should be exactly 16 bytes long (corresponding to a base64 encoding of 24 bytes with two trailing pad bytes ``==``). +These keys must be identical to the :ref:`corresponding keys used by the control service `. .. note:: The :program:`router` and :doc:`control` currently use these keys as input for PBKDF2 to generate diff --git a/doc/manuals/router/http-api.rst b/doc/manuals/router/http-api.rst index ebcc0bfe1f..4a9066d989 100644 --- a/doc/manuals/router/http-api.rst +++ b/doc/manuals/router/http-api.rst @@ -6,3 +6,6 @@ The HTTP API does not support user authentication or HTTPS. Applications will wa this port or bind to a loopback address. The :program:`router` currently only supports the :ref:`common HTTP API `. + +.. TODO + The router DOES appear to have a partially redundant OpenAPI as well! diff --git a/doc/overview.rst b/doc/overview.rst index f17a60446d..657b391f4d 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -19,6 +19,8 @@ important for the Internet to perform well, lie outside the scope of SCION. Concepts ======== +.. _overview-isds: + Isolation Domains (ISDs) ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/protocols/scion-header.rst b/doc/protocols/scion-header.rst index 81a7ada870..db71176cc9 100644 --- a/doc/protocols/scion-header.rst +++ b/doc/protocols/scion-header.rst @@ -245,6 +245,9 @@ E without further forwarding the request along the path. Use cases that require multiple routers/hops on the path to process a packet should instead rely on a **hop-by-hop extension**. + +.. _scion-path-exptime: + ExpTime Expiry time of a hop field. The field is 1-byte long, thus there are 256 different values available to express an expiration time. The expiration diff --git a/doc/requirements.in b/doc/requirements.in index 1a9af83dd1..880a8fd665 100644 --- a/doc/requirements.in +++ b/doc/requirements.in @@ -2,3 +2,4 @@ Sphinx recommonmark sphinx-autobuild sphinx-rtd-theme +sphinxcontrib-openapi diff --git a/doc/requirements.txt b/doc/requirements.txt index adac823144..05ea6e77e0 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -8,6 +8,10 @@ alabaster==0.7.13 \ --hash=sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3 \ --hash=sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2 # via sphinx +attrs==22.2.0 \ + --hash=sha256:29e95c7f6778868dbd49170f98f8818f78f3dc5e0e37c0b1f474e3561b240836 \ + --hash=sha256:c9227bfc2f01993c03f68db37d1d15c9690188323c067c641f1a35ca58185f99 + # via jsonschema babel==2.11.0 \ --hash=sha256:1ad3eca1c885218f6dce2ab67291178944f810a10a9b5f3cb8382a5a232b64fe \ --hash=sha256:5ef4b3226b0180dedded4229651c8b0e1a3a6a2837d45a073272f313e4cf97f6 @@ -114,12 +118,17 @@ commonmark==0.9.1 \ --hash=sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60 \ --hash=sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9 # via recommonmark +deepmerge==1.1.0 \ + --hash=sha256:4c27a0db5de285e1a7ceac7dbc1531deaa556b627dea4900c8244581ecdfea2d \ + --hash=sha256:59e6ef80b77dc52af3882a1ea78da22bcfc91ae9cdabc0c80729049fe295ff8b + # via sphinxcontrib-openapi docutils==0.18.1 \ --hash=sha256:23010f129180089fbcd3bc08cfefccb3b890b0050e1ca00c867036e9d161b98c \ --hash=sha256:679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06 # via # recommonmark # sphinx + # sphinx-mdinclude # sphinx-rtd-theme idna==3.4 \ --hash=sha256:814f528e8dead7d329833b91c5faa87d60bf71824cd12a7530b5526063d02cb4 \ @@ -133,10 +142,18 @@ importlib-metadata==6.0.0 \ --hash=sha256:7efb448ec9a5e313a57655d35aa54cd3e01b7e1fbcf72dce1bf06119420f5bad \ --hash=sha256:e354bedeb60efa6affdcc8ae121b73544a7aa74156d047311948f6d711cd378d # via sphinx +importlib-resources==5.12.0 \ + --hash=sha256:4be82589bf5c1d7999aedf2a45159d10cb3ca4f19b2271f8792bc8e6da7b22f6 \ + --hash=sha256:7b1deeebbf351c7578e09bf2f63fa2ce8b5ffec296e0d349139d43cca061a81a + # via jsonschema jinja2==3.1.2 \ --hash=sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852 \ --hash=sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61 # via sphinx +jsonschema==4.17.3 \ + --hash=sha256:0f864437ab8b6076ba6707453ef8f98a6a0d512a80e93f8abdb676f737ecb60d \ + --hash=sha256:a870ad254da1a8ca84b6a2905cac29d265f805acc57af304784962a2aa6508f6 + # via sphinxcontrib-openapi livereload==2.6.3 \ --hash=sha256:776f2f865e59fde56490a56bcc6773b6917366bce0c267c60ee8aaf1a0959869 \ --hash=sha256:ad4ac6f53b2d62bb6ce1a5e6e96f1f00976a32348afedcb4b6d68df2a1d346e4 @@ -193,18 +210,103 @@ markupsafe==2.1.2 \ --hash=sha256:f2bfb563d0211ce16b63c7cb9395d2c682a23187f54c3d79bfec33e6705473c6 \ --hash=sha256:f8ffb705ffcf5ddd0e80b65ddf7bed7ee4f5a441ea7d3419e861a12eaf41af58 # via jinja2 +mistune==2.0.5 \ + --hash=sha256:0246113cb2492db875c6be56974a7c893333bf26cd92891c85f63151cee09d34 \ + --hash=sha256:bad7f5d431886fcbaf5f758118ecff70d31f75231b34024a1341120340a65ce8 + # via sphinx-mdinclude packaging==23.0 \ --hash=sha256:714ac14496c3e68c99c29b00845f7a2b85f3bb6f1078fd9f72fd20f0570002b2 \ --hash=sha256:b6ad297f8907de0fa2fe1ccbd26fdaf387f5f47c7275fedf8cce89f99446cf97 # via sphinx +picobox==2.2.0 \ + --hash=sha256:0a14f8fae386a46e61671a3ce16e0d54d24fb8f15169b0971483228a3e274622 \ + --hash=sha256:c446ea34b5ee396ab8dc7cbed8f036e73e52403593088656b9b45b7d6382c926 + # via sphinxcontrib-openapi +pkgutil-resolve-name==1.3.10 \ + --hash=sha256:357d6c9e6a755653cfd78893817c0853af365dd51ec97f3d358a819373bbd174 \ + --hash=sha256:ca27cc078d25c5ad71a9de0a7a330146c4e014c2462d9af19c6b828280649c5e + # via jsonschema pygments==2.14.0 \ --hash=sha256:b3ed06a9e8ac9a9aae5a6f5dbe78a8a58655d17b43b93c078f094ddc476ae297 \ --hash=sha256:fa7bd7bd2771287c0de303af8bfdfc731f51bd2c6a47ab69d117138893b82717 - # via sphinx + # via + # sphinx + # sphinx-mdinclude +pyrsistent==0.19.3 \ + --hash=sha256:016ad1afadf318eb7911baa24b049909f7f3bb2c5b1ed7b6a8f21db21ea3faa8 \ + --hash=sha256:1a2994773706bbb4995c31a97bc94f1418314923bd1048c6d964837040376440 \ + --hash=sha256:20460ac0ea439a3e79caa1dbd560344b64ed75e85d8703943e0b66c2a6150e4a \ + --hash=sha256:3311cb4237a341aa52ab8448c27e3a9931e2ee09561ad150ba94e4cfd3fc888c \ + --hash=sha256:3a8cb235fa6d3fd7aae6a4f1429bbb1fec1577d978098da1252f0489937786f3 \ + --hash=sha256:3ab2204234c0ecd8b9368dbd6a53e83c3d4f3cab10ecaf6d0e772f456c442393 \ + --hash=sha256:42ac0b2f44607eb92ae88609eda931a4f0dfa03038c44c772e07f43e738bcac9 \ + --hash=sha256:49c32f216c17148695ca0e02a5c521e28a4ee6c5089f97e34fe24163113722da \ + --hash=sha256:4b774f9288dda8d425adb6544e5903f1fb6c273ab3128a355c6b972b7df39dcf \ + --hash=sha256:4c18264cb84b5e68e7085a43723f9e4c1fd1d935ab240ce02c0324a8e01ccb64 \ + --hash=sha256:5a474fb80f5e0d6c9394d8db0fc19e90fa540b82ee52dba7d246a7791712f74a \ + --hash=sha256:64220c429e42a7150f4bfd280f6f4bb2850f95956bde93c6fda1b70507af6ef3 \ + --hash=sha256:878433581fc23e906d947a6814336eee031a00e6defba224234169ae3d3d6a98 \ + --hash=sha256:99abb85579e2165bd8522f0c0138864da97847875ecbd45f3e7e2af569bfc6f2 \ + --hash=sha256:a2471f3f8693101975b1ff85ffd19bb7ca7dd7c38f8a81701f67d6b4f97b87d8 \ + --hash=sha256:aeda827381f5e5d65cced3024126529ddc4289d944f75e090572c77ceb19adbf \ + --hash=sha256:b735e538f74ec31378f5a1e3886a26d2ca6351106b4dfde376a26fc32a044edc \ + --hash=sha256:c147257a92374fde8498491f53ffa8f4822cd70c0d85037e09028e478cababb7 \ + --hash=sha256:c4db1bd596fefd66b296a3d5d943c94f4fac5bcd13e99bffe2ba6a759d959a28 \ + --hash=sha256:c74bed51f9b41c48366a286395c67f4e894374306b197e62810e0fdaf2364da2 \ + --hash=sha256:c9bb60a40a0ab9aba40a59f68214eed5a29c6274c83b2cc206a359c4a89fa41b \ + --hash=sha256:cc5d149f31706762c1f8bda2e8c4f8fead6e80312e3692619a75301d3dbb819a \ + --hash=sha256:ccf0d6bd208f8111179f0c26fdf84ed7c3891982f2edaeae7422575f47e66b64 \ + --hash=sha256:e42296a09e83028b3476f7073fcb69ffebac0e66dbbfd1bd847d61f74db30f19 \ + --hash=sha256:e8f2b814a3dc6225964fa03d8582c6e0b6650d68a232df41e3cc1b66a5d2f8d1 \ + --hash=sha256:f0774bf48631f3a20471dd7c5989657b639fd2d285b861237ea9e82c36a415a9 \ + --hash=sha256:f0e7c4b2f77593871e918be000b96c8107da48444d57005b6a6bc61fb4331b2c + # via jsonschema pytz==2022.7.1 \ --hash=sha256:01a0681c4b9684a28304615eba55d1ab31ae00bf68ec157ec3708a8182dbbcd0 \ --hash=sha256:78f4f37d8198e0627c5f1143240bb0206b8691d8d7ac6d78fee88b78733f8c4a # via babel +pyyaml==6.0 \ + --hash=sha256:01b45c0191e6d66c470b6cf1b9531a771a83c1c4208272ead47a3ae4f2f603bf \ + --hash=sha256:0283c35a6a9fbf047493e3a0ce8d79ef5030852c51e9d911a27badfde0605293 \ + --hash=sha256:055d937d65826939cb044fc8c9b08889e8c743fdc6a32b33e2390f66013e449b \ + --hash=sha256:07751360502caac1c067a8132d150cf3d61339af5691fe9e87803040dbc5db57 \ + --hash=sha256:0b4624f379dab24d3725ffde76559cff63d9ec94e1736b556dacdfebe5ab6d4b \ + --hash=sha256:0ce82d761c532fe4ec3f87fc45688bdd3a4c1dc5e0b4a19814b9009a29baefd4 \ + --hash=sha256:1e4747bc279b4f613a09eb64bba2ba602d8a6664c6ce6396a4d0cd413a50ce07 \ + --hash=sha256:213c60cd50106436cc818accf5baa1aba61c0189ff610f64f4a3e8c6726218ba \ + --hash=sha256:231710d57adfd809ef5d34183b8ed1eeae3f76459c18fb4a0b373ad56bedcdd9 \ + --hash=sha256:277a0ef2981ca40581a47093e9e2d13b3f1fbbeffae064c1d21bfceba2030287 \ + --hash=sha256:2cd5df3de48857ed0544b34e2d40e9fac445930039f3cfe4bcc592a1f836d513 \ + --hash=sha256:40527857252b61eacd1d9af500c3337ba8deb8fc298940291486c465c8b46ec0 \ + --hash=sha256:432557aa2c09802be39460360ddffd48156e30721f5e8d917f01d31694216782 \ + --hash=sha256:473f9edb243cb1935ab5a084eb238d842fb8f404ed2193a915d1784b5a6b5fc0 \ + --hash=sha256:48c346915c114f5fdb3ead70312bd042a953a8ce5c7106d5bfb1a5254e47da92 \ + --hash=sha256:50602afada6d6cbfad699b0c7bb50d5ccffa7e46a3d738092afddc1f9758427f \ + --hash=sha256:68fb519c14306fec9720a2a5b45bc9f0c8d1b9c72adf45c37baedfcd949c35a2 \ + --hash=sha256:77f396e6ef4c73fdc33a9157446466f1cff553d979bd00ecb64385760c6babdc \ + --hash=sha256:81957921f441d50af23654aa6c5e5eaf9b06aba7f0a19c18a538dc7ef291c5a1 \ + --hash=sha256:819b3830a1543db06c4d4b865e70ded25be52a2e0631ccd2f6a47a2822f2fd7c \ + --hash=sha256:897b80890765f037df3403d22bab41627ca8811ae55e9a722fd0392850ec4d86 \ + --hash=sha256:98c4d36e99714e55cfbaaee6dd5badbc9a1ec339ebfc3b1f52e293aee6bb71a4 \ + --hash=sha256:9df7ed3b3d2e0ecfe09e14741b857df43adb5a3ddadc919a2d94fbdf78fea53c \ + --hash=sha256:9fa600030013c4de8165339db93d182b9431076eb98eb40ee068700c9c813e34 \ + --hash=sha256:a80a78046a72361de73f8f395f1f1e49f956c6be882eed58505a15f3e430962b \ + --hash=sha256:afa17f5bc4d1b10afd4466fd3a44dc0e245382deca5b3c353d8b757f9e3ecb8d \ + --hash=sha256:b3d267842bf12586ba6c734f89d1f5b871df0273157918b0ccefa29deb05c21c \ + --hash=sha256:b5b9eccad747aabaaffbc6064800670f0c297e52c12754eb1d976c57e4f74dcb \ + --hash=sha256:bfaef573a63ba8923503d27530362590ff4f576c626d86a9fed95822a8255fd7 \ + --hash=sha256:c5687b8d43cf58545ade1fe3e055f70eac7a5a1a0bf42824308d868289a95737 \ + --hash=sha256:cba8c411ef271aa037d7357a2bc8f9ee8b58b9965831d9e51baf703280dc73d3 \ + --hash=sha256:d15a181d1ecd0d4270dc32edb46f7cb7733c7c508857278d3d378d14d606db2d \ + --hash=sha256:d4b0ba9512519522b118090257be113b9468d804b19d63c71dbcf4a48fa32358 \ + --hash=sha256:d4db7c7aef085872ef65a8fd7d6d09a14ae91f691dec3e87ee5ee0539d516f53 \ + --hash=sha256:d4eccecf9adf6fbcc6861a38015c2a64f38b9d94838ac1810a9023a0609e1b78 \ + --hash=sha256:d67d839ede4ed1b28a4e8909735fc992a923cdb84e618544973d7dfc71540803 \ + --hash=sha256:daf496c58a8c52083df09b80c860005194014c3698698d1a57cbcfa182142a3a \ + --hash=sha256:dbad0e9d368bb989f4515da330b88a057617d16b6a8245084f1b05400f24609f \ + --hash=sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174 \ + --hash=sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5 + # via sphinxcontrib-openapi recommonmark==0.7.1 \ --hash=sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f \ --hash=sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67 @@ -216,7 +318,9 @@ requests==2.28.2 \ six==1.16.0 \ --hash=sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926 \ --hash=sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254 - # via livereload + # via + # livereload + # sphinxcontrib-httpdomain snowballstemmer==2.2.0 \ --hash=sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1 \ --hash=sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a @@ -229,10 +333,16 @@ sphinx==6.1.3 \ # recommonmark # sphinx-autobuild # sphinx-rtd-theme + # sphinxcontrib-httpdomain + # sphinxcontrib-openapi sphinx-autobuild==2021.3.14 \ --hash=sha256:8fe8cbfdb75db04475232f05187c776f46f6e9e04cacf1e49ce81bdac649ccac \ --hash=sha256:de1ca3b66e271d2b5b5140c35034c89e47f263f2cd5db302c9217065f7443f05 # via -r requirements.in +sphinx-mdinclude==0.5.3 \ + --hash=sha256:02afadf4597aecf8255a702956eff5b8c5cb9658ea995c3d361722d2ed78cca9 \ + --hash=sha256:2998e3d18b3022c9983d1b72191fe37e25ffccd54165cbe3acb22cceedd91af4 + # via sphinxcontrib-openapi sphinx-rtd-theme==1.2.0 \ --hash=sha256:a0d8bd1a2ed52e0b338cbe19c4b2eef3c5e7a048769753dac6a9f059c7b641b8 \ --hash=sha256:f823f7e71890abe0ac6aaa6013361ea2696fc8d3e1fa798f463e82bdb77eeff2 @@ -249,6 +359,10 @@ sphinxcontrib-htmlhelp==2.0.1 \ --hash=sha256:0cbdd302815330058422b98a113195c9249825d681e18f11e8b1f78a2f11efff \ --hash=sha256:c38cb46dccf316c79de6e5515e1770414b797162b23cd3d06e67020e1d2a6903 # via sphinx +sphinxcontrib-httpdomain==1.8.1 \ + --hash=sha256:21eefe1270e4d9de8d717cc89ee92cc4871b8736774393bafc5e38a6bb77b1d5 \ + --hash=sha256:6c2dfe6ca282d75f66df333869bb0ce7331c01b475db6809ff9d107b7cdfe04b + # via sphinxcontrib-openapi sphinxcontrib-jquery==2.0.0 \ --hash=sha256:8fb65f6dba84bf7bcd1aea1f02ab3955ac34611d838bcc95d4983b805b234daa \ --hash=sha256:ed47fa425c338ffebe3c37e1cdb56e30eb806116b85f01055b158c7057fdb995 @@ -257,6 +371,10 @@ sphinxcontrib-jsmath==1.0.1 \ --hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \ --hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8 # via sphinx +sphinxcontrib-openapi==0.8.1 \ + --hash=sha256:04fcf87c259345162a504ce3dfee0f71389f507c3797798dc531c7748995b4eb \ + --hash=sha256:45ecad2a98e304d3665c133ea08a7083a2b5d86e75c6b64c60389240b3927ad5 + # via -r requirements.in sphinxcontrib-qthelp==1.0.3 \ --hash=sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72 \ --hash=sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6 @@ -285,7 +403,9 @@ urllib3==1.26.14 \ zipp==3.14.0 \ --hash=sha256:188834565033387710d046e3fe96acfc9b5e86cbca7f39ff69cf21a4128198b7 \ --hash=sha256:9e5421e176ef5ab4c0ad896624e87a7b2f07aca746c9b2aa305952800cb8eecb - # via importlib-metadata + # via + # importlib-metadata + # importlib-resources # WARNING: The following packages were not pinned, but pip requires them to be # pinned when the requirements file includes hashes. Consider using the --allow-unsafe flag.