diff --git a/doc/hidden-paths.rst b/doc/hidden-paths.rst index fcaaa3039f..63b44e28a8 100644 --- a/doc/hidden-paths.rst +++ b/doc/hidden-paths.rst @@ -2,242 +2,333 @@ Hidden Paths ************ -This file documents the design for the Hidden Paths infrastructure. - -Naming -====== - -+------------------------------------------+-----------------------------------------------------------------+ -| Name | Explanation | -+==========================================+=================================================================+ -| Hidden Path Group (HPG) | Group within which hidden path information is shared | -+------------------------------------------+-----------------------------------------------------------------+ -| Hidden Path Group Configuration (HPGCfg) | Configuration defining a Hidden Path Group | -+------------------------------------------+-----------------------------------------------------------------+ -| Hidden Path Server (HPS) | Server caching hidden segments / answering hidden path requests | -+------------------------------------------+-----------------------------------------------------------------+ +This file documents the design for the hidden paths infrastructure. Overview ======== -Hidden path communication enables the hiding of specific path segments, i.e. certain path segments -are only available for authorized ASes. In the common case, path segments are publicly available to -any network entity. They are fetched from path servers and used to construct forwarding paths. In a -Hidden Path communication setting, certain down-segments are not registered at the public path -servers. Instead, they are registered at dedicated Hidden path servers (HPS) which enforce access -control, such that only authorized entities can fetch and use these segments to create forwarding -paths. Likewise, the corresponding up-segment is registered as hidden up-segment at the local Path -Server such that endhosts are aware that they are using hidden path communication to leave the AS. +Hidden path communication enables the hiding of specific path segments, i.e. +certain path segments are only available for authorized ASes. In the common +case, path segments are publicly available to any network entity. They are +fetched from the control service and used to construct forwarding paths. In a +hidden path communication setting, certain down-segments are not registered +publicly. Instead, they are registered at hidden segment service instances which +enforce access control, such that only authorized entities can fetch and use +these segments to create forwarding paths. Likewise, the corresponding +up-segment can be registered as hidden up-segment at the local hidden segment +service such that endhosts are aware that they are using hidden path +communication to leave the AS. .. image:: fig/hidden_paths/HiddenPath.png *Hidden Path communication scheme:* -#. Group Owner creates a HPG and shares the configuration out-of-band -#. Writer ASes register down-segments at Registries of their group -#. Reader ASes query local HPS for hidden segments -#. Reader ASes can communicate with Writer ASes based on hidden path segments +#. *Owner* AS creates a hidden path group and shares the configuration + out-of-band. + +#. *Writer* ASes register down-segments at *Registry* ASes of their group. + +#. *Reader* ASes query *Registry* ASes for hidden segments. + +#. *Reader* ASes can communicate with *Writer* ASes based on hidden path segments. Design ====== -Hidden Path Group +Hidden path group ----------------- A hidden path group is defined as a group of ASes within which hidden path information is shared. A hidden path group consists of: -- GroupID: Unique 64bit identification of the group: OwnerAS48bit||GroupID16bit +- GroupID: Unique 64bit identification of the group: + :math:`OwnerAS_{48bit}||GroupID_{16bit}` + - Version: A version indicating the version of the configuration -- Owner: AS ID of the owner of the hidden path group. The Owner AS is responsible for maintaining - the hidden path group configuration and keeping the group's HPS up-to-date with the latest - version *(Access: Read/Write)* -- Writers: All ASes in the group which are allowed to register hidden paths *(Access: Read/Write)* -- Readers: All ASes in the group which are allowed to read hidden path information *(Access: Read)* -- Registries: All ASes in the group at which writers register hidden paths -The HPGCfg is shared amongst the members of the group out-of-band. It -is the group owner's responsibility to disseminate updated versions to all -members. An online way to initially share and update the HPGCfg might be added in the future. +- Owner: AS ID of the owner of the hidden path group. The Owner AS is + responsible for maintaining the hidden path group configuration and + distributing it to all servers that require it. *(Access: Read/Write)* + +- Writers: All ASes in the group which are allowed to register hidden paths + *(Access: Read/Write)* -(See an example group configuration in the [Implementation](#Hidden-Path-Group-Configuration) section) +- Readers: All ASes in the group which are allowed to read hidden path + information *(Access: Read)* -Hidden Path Service -------------------- +- Registries: All ASes in the group at which *Writers* register hidden paths + *(Access: Read)* -Each AS in the hidden path group runs a Hidden Path Server as a service. While at first it seems -that HPS and PS serve a similar purpose, a closer look justifies why HPS should run as a dedicated -service: The segment lookup on an HPS is simple compared to the lookup done by a PS since only -down-segments need to be returned. Not much of the PS logic could be re-used. Furthermore, an HPS -needs to perform ACL checks on requesters based on HPGCfgs. This logic is not needed by a regular -PS. Merging the two services would unnecessarily complicate both designs and harm the development of -future, more sophisticated accesss control mechanisms on HPS. +The hidden path group configuration is shared amongst the members of the group +out-of-band. It is the group owner's responsibility to disseminate updated +versions to all members. An online way to initially share and update the hidden +path group configuration might be added in the future. -Each HPS serves two purposes: +Example group configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- Caching Hidden Path segment information and serving this information to sciond and forwarding HPS -- Forwarding hidden path requests on behalf of sciond to ``Registries`` of the group +Below is an example of a hidden path group configuration file +(``hp_group_ff00_0_110-69b5.json``): + +.. code-block:: json -Hidden Path Servers are listed as -``HiddenPathService`` in the topology file. The corresponding service address is -``SvcHPS``. + { + "group_id": "ff00:0:110-69b5", + "version": 1, + "owner": "1-ff00:0:110", + "writers": [ + "1-ff00:0:111", + "1-ff00:0:112" + ], + "readers": [ + "1-ff00:0:114" + ], + "registries": [ + "1-ff00:0:111", + "1-ff00:0:113" + ] + } -Segment Registration +Segment registration -------------------- -The Beacon Server needs to distinguish between segments to be registered at the Path Server and the -ones to be registered at the Hidden Path Server. Additionally, a segment can be registered as -up-segment only or as down-segment only. These decisions are based on a policy defined in the -Beacon Server's configuration file. The policy groups segments by public and hidden segments. For -each segment, identified by its interface ID, the following parameters can be defined: +The segment registration needs to distinguish between segments to be registered +publicly and hidden. Additionally, a segment can be registered as up-segment +only or as down-segment only. These decisions are based on a policy defined in a +configuration file. For each segment, identified by its interface ID, the +following parameters can be defined: -- MaxExpiration: The time interval after which the segment becomes invalid -- RegDown: Whether to register the segment as down-segment at the Core PS / HPS -- RegUp: Whether to register the segment as (hidden) up-segment at the local PS / HPS +- ``max_expiration``: The time interval after which the segment becomes invalid -Segments not explicitly listed are either fully registered as public up- and down-segments or not -registered at all, depending on the configured default action. +- ``reg_down``: Whether to register the segment as down-segment. -Note that a hidden segment registered as hidden and the same segment registered publicly need to be -distinguishable. This is achieved by adding an extension to the ``ASEntry`` of the final AS in the -segment. +- ``reg_up``: Whether to register the segment as up-segment. -The Beacon Server can be configured to not allow the registration of a segment both as public and hidden. +These parameters can be specified for *public* and for each hidden path group +individually. Segments not explicitly listed are either fully registered as +public up- and down-segments or not registered at all, depending on the +configured default action. -(See an example policy in the `Hidden Path Group Configuration`_ section) +The beaconing module can be configured to not allow the registration of a +segment both as public and hidden. -Path Lookup ------------ +Example registration configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Additional to up-, core- and down-segments, sciond is responsible for fetching hidden down-segments. -sciond periodically queries the local HPS to fetch all HPGCfgs of which it is a member. Clients of -sciond have to explicitly ask sciond for hidden paths. Clients can include a specific ``GroupID`` in -their request; otherwise sciond checks all HPGCfgs and extracts the HPG ``GroupID``'s of all those -groups where the destination is a Writer (or Owner) of that group. With the obtained ``GroupID``'s and -the given destination, sciond then requests hidden down-segments from its local HPS. The local HPS -selects a Registry for each ``GroupID``, partitioning the ``GroupID``'s into disjoint subsets based on -shared Registries. HPS then resolves the request by applying one of two cases for each subset: +Below is an example ``hp_policy.yml`` configuration. In ``hidden_path_groups`` +all the hidden path groups available to the service are listed. Furthermore, the +configuration contains the segment registration policies in the +``segment_registration`` section. The file ``hp_policy.yml`` in turn is pointed +to by the ``cs.toml`` file by specifying the ``hidden_path_registration`` +parameter. -#. The local HPS is a Registry of the groups in the subset, and thus resolves the request by - querying its database -#. The local HPS is *not* a Registry of the groups in the subset. The request is - resolved by querying the shared Registry of the given groups. +.. code-block:: yaml -The HPS then replies to sciond with a map of ``GroupID`` -> (``SegReply``, -``error``). + --- + hidden_path_groups: + "ff00:0:110-69b5": + config_file: testdata/hp_group_ff00_0_110-69b5.json + "ffaa:0:222-abcd": + config_file: testdata/hp_group_ffaa_0_222-abcd.json + segment_registration: + default_action: register + hidden_and_public: true + # Mapping from ingress interface to registration policy + policies: + 2: + public: + register_up: true + register_down: true + max_expiration: 1h + "ff00:0:110-69b5": + register_up: true + register_down: true + max_expiration: 1h + "ffaa:0:222-abcd": + register_up: true + register_down: true + max_expiration: 1h + 3: + public: + register_up: true + register_down: true + max_expiration: 1h -.. image:: fig/hidden_paths/PathLookup.png +The default action is set to ``register``, this means that all segments not +listed in this configuration are registered as public up- and down-segments with +default expiration. Note that the segment with interface ID 2 is both registered +as hidden and public. This is allowed by setting ``hidden_and_public`` to +``true``. -Security --------- +Hidden segment registration service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Various operations in this design are security critical and require client/server authentication: +The hidden segment registration service needs to verify that the sender of the +segment is a writer in the hidden path group it tries to register. -#. For the creation of HPGs we assume that the chosen out-of-band mechanism is safe. -#. For registrations from BS to HPS we need to authenticate the HPS. Currently, there is no server - authentication in SCION. This needs to be implemented for the segment registration to be secure. -#. sciond querying paths from the local HPS is secured by AS internal policies. -#. A local HPS fetching segments from a remote HPS is authenticated by signing the request with the - local ASes signing key. The remote HPS can verify the signature using the client ASes public key. +Below is the gRPC definition of the service that accepts hidden segment +registrations. -Implementation -============== +.. code-block:: protobuf -Hidden Path Group Configuration -------------------------------- + service HiddenSegmentRegistrationService { + // HiddenSegmentRegistration registers hidden segments at the remote. + rpc HiddenSegmentRegistration(HiddenSegmentRegistrationRequest) returns (HiddenSegmentRegistrationResponse) {} + } -Below is an example of a Hidden Path Group configuration file (``HPGCfg_ff00_0_110-69b5.json``): + message HiddenSegmentRegistrationRequest { + message Segments { + // List of path segments. + repeated PathSegment segments = 1; + } -.. code-block:: json + // Mapping from path segment type to path segments. The key is the integer + // representation of the SegmentType enum. + map segments = 1; - { - "GroupID": "ff00:0:110-69b5", - "Version": 1, - "Owner": "1-ff00:0:110", - "Writers": [ - "1-ff00:0:111", - "1-ff00:0:112" - ], - "Readers": [ - "1-ff00:0:113", - "1-ff00:0:114" - ], - "Registries": [ - "1-ff00:0:110", - "1-ff00:0:111", - "1-ff00:0:113" - ] + // GroupID is the group ID to which these segments should be registered. + uint64 group_id = 2; } -Segment Registration Policy ---------------------------- + message HiddenSegmentRegistrationResponse {} -Below is an example ``hp_policy.yml`` configuration. In ``HPGroups`` all the HPGs available to the -beacon service are listed. Furthermore, the configuration contains the segment registration policies -in the ``SegmentRegistration`` section. The file ``hp_policy.yml`` in turn is pointed to by the -``bs.toml`` file by specifying the ``HiddenPathRegistration`` parameter. +Note that ``PathSegment`` and ``SegmentType`` are already defined by the normal +segment registration service and should be reused from there. -.. code-block:: yaml +Path lookup +----------- - --- - HPGroups: - "ff00:0:110-69b5": - CfgFilePath: testdata/HPGCfg_ff00_0_110-69b5.json - "ffaa:0:222-abcd": - CfgFilePath: testdata/HPGCfg_ffaa_0_222-abcd.json - SegmentRegistration: - DefaultAction: register - HiddenAndPublic: true - Policies: - 2: - PS: - RegUp: true - RegDown: true - MaxExpiration: 1h - HPS: - "ff00:0:110-69b5": - RegUp: true - RegDown: true - MaxExpiration: 1h - "ffaa:0:222-abcd": - RegUp: true - RegDown: true - MaxExpiration: 1h - 3: - PS: - RegUp: true - RegDown: true - MaxExpiration: 1h +Hidden segment lookup service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The hidden segment lookup service can be queried for hidden segments to a given +destination. The request includes a set of hidden path group IDs and a +destination ISD-AS identifier. Upon receiving a request, the service must +validate the requester is allowed to access the requested hidden path groups. +For this, the service checks that for each requested group ID the requesting AS +has read access, i.e. is listed in the hidden path group. + +Once validation is completed, the hidden segment lookup service can take one of +the following actions for each group ID in the request: + +- lookup segments in the database for hidden path groups where the local AS is a + *Registry* and thus the service is *authoritative*. +- *forward* the request to a hidden segment lookup service in an AS that is a + *Registry* for the requested hidden path groups. Forwarding is only allowed if + the request comes from within the AS, i.e. from a SCION daemon. + +Note that multiple *forward* requests might be required depending on the hidden +path groups that are requested. To determine a small set of *Registry* ASes to +query for the required ``GroupID``'s the hidden paths lookup service should +partition the requested ``GroupID``'s into disjoint subsets, such that each +subset is covered by a single *Registry*. Note that a minimal set is not +strictly required since this is only an optimization. + +The gRPC definition of the service is as follows: + +.. code-block:: protobuf + + service HiddenSegmentLookupService { + // HiddenSegments returns all segments that match the request. + rpc HiddenSegments(HiddenSegmentsRequest) returns (HiddenSegmentsResponse) {} + } + + message HiddenSegmentsRequest { + // Hidden path group IDs for which a hidden segment is requested. + repeated uint64 group_ids = 1; + // The destination ISD-AS of the segment. + uint64 dst_isd_as = 2; + } + + message HiddenSegmentsResponse { + message Segments { + // List of path segments. + repeated PathSegment segments = 1; + } + + // Mapping from path segment type to path segments. The key is the integer + // representation of the SegmentType enum. + map segments = 1; + } + +SCION daemon +^^^^^^^^^^^^ + +Additional to up-, core- and down-segments, the daemon is responsible for +fetching hidden down-segments. The daemon is configured with the hidden path +group IDs it should query. Using the configured hidden path group IDs the daemon +queries the local hidden segment lookup service for the given destination. Once +the daemon has all segments collected it combines the segments to paths and returns the paths +to the requester. + +Everything combined the path lookup looks as follows: + +.. image:: fig/hidden_paths/PathLookup.png + +Hidden segment service discovery +-------------------------------- + +Hidden segment services in remote ASes can be discovered via a hidden segment +service discovery. Similar to the gateway discovery an initial UDP roundtrip is +done to find the discovery service. The discovery service can then be queried +for hidden segment services. The reply of the discovery contains a list of +hidden segment lookup services and a list of hidden segment registration +services. + +To make the information of what hidden segment services exist in an AS available +to the discovery service, the servers that run hidden segment services must +register in the topology file: + +- Servers that run the hidden segment lookup service must be listed as + ``hidden_segment_lookup_service``. -The default action is set to ``register``, this means that all segments not listed in this -configuration are registered as up- and down-segment with default expiration. -Note that the segment with IFID 2 is both registered as hidden and public. This is allowed by -setting ``HiddenAndPublic``. +- Servers that run the hidden segment registration service must be listed as + ``hidden_segment_registration_service``. -Message Definitions -------------------- +Note that having access control on the hidden segment discovery service is not +strictly required, since even if someone can get access to the enpoints, which +service hidden segment infrastructure, the services themselves must verify +that only authorized parties read or write hidden segment data. -(TBD) +Discovery service gRPC definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Hidden Path Server ------------------- +.. code-block:: protobuf -General Structure -^^^^^^^^^^^^^^^^^ + service DiscoveryService { + // Return the remote hidden segment services. + rpc HiddenSegmentServices(HiddenSegmentServicesRequest) returns (HiddenSegmentServicesResponse) {} + } + + message HiddenSegmentServicesRequest {} + + message HiddenSegmentServicesResponse { + // The list of lookup services. + repeated HiddenSegmentService lookup = 1; + // The list of registration services. + repeated HiddenSegmentService registration = 2; + } + + message HiddenSegmentService { + // The control address of this hidden segment service. + string control_address = 1; + } + +Security +-------- -The HPS is structured similar to existing go infra services. It uses: +Various operations in this design are security critical and require +client/server authentication: -- go/lib/env (for configuration and setting up the service) -- go/lib/infra (for sending messages) -- go/lib/pathdb (for storing hidden segments) +#. For the creation of hidden path groups we assume that the chosen out-of-band + mechanism is safe. -Handlers -^^^^^^^^ +#. For segment registrations from a control server to the hidden path + registration service we need to authenticate the AS of the registration + service. This can be done using TLS based on AS certificates. -The HPS has the following handlers: +#. The SCION daemon querying paths from the local hidden path lookup service is + secured by AS internal policies / PKIs. -- ``HPSegRegHandler``: Handler accepting a ``GroupID`` and a list of segments to be registered as hidden - down-segments for that group *(Access: Owner/Writers)* -- ``HPSegReqHandler``: Accepting a list of ``GroupID``'s, responding with hidden down-segments - corresponding to those groups *(Access: Owner/Readers)* -- ``HPGCfgReqHandler``: Returns a list of all ``HPGCfg``'s the requester is a Reader of *(Access: Owner/Writers/Readers)* +#. For inter-AS hidden segment lookups, clients are authenticated using + TLS client certificates based on the AS certificate.