Registration

About document

This document describes the node, link, and service endpoint registration procedures in a Bayware network.

Overview

Procedures

The cornerstone procedures are:

• User authentication and node initialization
• Node registration
• Link registration
• Service endpoint registration
• Flow establishment
• FCAPS (GUI and OSS/BSS integration)

A user must be authenticated and a node must be initialized prior to any other action.

A node and its connection(s) must be registered before creating a service endpoint on that node.

A service endpoint must be registered so that it can be used for sending or receiving flows by a node’s application.

A flow must be established to maintain data exchange between applications.

FCAPS stands for Fault, Configuration, Accounting, Performance, and Security management.

Protocols and APIs

Bayware relies on the following protocols:

• OpenID Connect over OAuth2
• IPv6 NDP/SeND (message structure only)
• SNMPv2

As well, Bayware uses its own APIs:

• Controller Northbound RESTful API
• Controller Southbound RESTful API
• Agent RESTful API

The table below shows the relationship between the procedures and protocols/APIs.

Protocols & APIs	Procedures
	User Auth & Node Init	Node Reg	Link Reg	Svc Endpoint Reg	Flow Ctrl	Web, OSS/BSS Integ
OpenID Connect over Auth2	✔	✔	✔	✔	✖	✔
IPv6 SeND	✖	✖	✔	✖	✖	✖
Controller SB RESTful API	✖	✔	✔	✔	✖	✖
Controller NB RESTful API	✖	✖	✖	✖	✖	✔
Agent RESTful API	✖	✖	✖	✔	✖	✖
Instructions	✖	✖	✖	✖	✔	✖
Engine CLI	✖	✖	✖	✖	✖	✔
SNMPv2	✖	✖	✖	✔	✖	✖

Node Attributes

Every node has several major attributes:

• node type
• node owner
• node name
• node identifier
• node locator

Node Type

Any Bayware network comprises two types of nodes:

• Bayware Host
• Bayware Switch

A switch is a node that forwards packets not explicitly addressed to itself. A host is any node that is not a switch.

Node Owner

A node owner is a user authorized to run the node.

A user has a profile managed by one of the Identity Services. A user profile contains netprefix, userdomain, username, password, and user system roles. One or more system roles defines the user permissions on the controller.

Due to security reasons, a user can be an owner of either hosts or switches, but not both.

Node Name

A node name is a common name, i.e. fully qualified domain name (FQDN), assigned to the node by its owner. A node name is unique within the user domain. A node name is bound usually to a user. When bound, only the given user has permissions to register the node with the particular name.

Node Identifier

Every node possesses a node identifier. A node identifier is supposed to be a globally unique entity—not only within a given userdomain or organization, but across all organizations running Bayware.

A node identifier is bound to the node name. When the user changes the node name, a new node identifier is generated.

Cryptographically Generated Addresses (CGA) are used as Node Identifiers. The prefixes of either Unique Local Addresses or Public Unicast Addresses might be used to form the CGA.

As of current implementation, the Unique Local Address prefixes are used by default.

A node identifier is composed of four parts, such as:

• fd::/8 – ULA-specific IPv6 prefix assigned by IANA
• Global ID – pseudo-random global identifier generated by the service provider in accordance with the algorithm
• Subnet ID – identifier assigned to Identity Service by service provider
• Interface ID – identifier cryptographically generated by the node itself according to the algorithm

The combination of the fields–fd::/8, Global ID, Subnet ID–forms the prefix of the node identifier. Each Identity Service maintains one or more node identifier prefixes. On a user authentication and authorization request, the Identity Service provides the prefix as netprefix attribute of the user profile.

The prefix, public RSA key and auxiliary parameters are used to generate an interface part of the node identifier as it described here.

A key property of the node identifier is that its ownership is provable.

Node Locator

A node locator is used to identify the node location in an IP network. Either an IPv4 or IPv6 address can be used as a node locator. As of the current implementation, the host possesses one locator and switch might have multiple. As an example of the node locators use, the IP tunnel, established between two Bayware nodes, uses the node locators as the tunnel endpoint IP addresses.

Any Bayware switch can be attached to one or more IP virtual private networks. The switch receives at least one locator assigned per VPN.

User Authentication and Node Initialization

Protocol Suite

The User Authentication and Node Initialization procedure employs the OpenID Connect over OAuth2 protocol suite.

General Principles

Identity Service, a component of Bayware’s Controller, issues tokens to the authenticated and authorized users. Later on, these users provide tokens every time they call the controller’s APIs. Before executing any call, the controller API Gateways request the Identity Service to validate the tokens.

User Authentication and Node Initialization Algorithm

When a node is started with either a Bayware Agent or Supervisor component on it, that component checks for the presence of RSA keys bound to that node. If no keys associated with the node name are found, a new RSA pair is generated.

The node then calls the API Gateway. The gateway responds to this call by requesting that the user obtain an access token. The API Gateway specifies the Identity Service in its response.

The user initiates a token request. To be authenticated and authorized, the user provides the Identity Service with its userdomain, username and password.

The user receives the access and ID tokens (for future use) from the Identity Service after being authenticated.

Note: From this point, the Identity Service is ready to authorize the user on the requests of the API Gateways. Upon such a request, the Identity Service returns the user profile: netprefix, userdomain, username, and user system roles. The API Gateway executes the user API call only if the permissions needed to do this match the scope. As of current implementation, the API Gateway has the trusted connection with a single Controller Identity Service, thus the API Gateway can execute only the requests received from the nodes that have been authenticated and authorized by the Identity Service it trusts.

After the authorization, the user requests its own user profile from the Identity Service. As mentioned above, the Identity Service provides the netprefix among other pieces of user information.

The netprefix, RSA public key and auxiliary parameters are used to check the node CGA. If either the CGA is not present or the CGA parameters are not the same, the new CGA is generated. This step finishes the node initialization part of the procedure.

Node Registration

Protocol Suite

Node Registration procedure relies on the OpenID Connect over OAuth2 protocol suite and utilizes the Controller Southbound API.

Node Registration Algorithm

Registration Procedure

After all the modules of Bayware Agent or Supervisor are up, the SB API is called with the registerNode request. The access token, CGA option, nodename and RSA option are sent in the request.

The API Gateway requests the Identity Service for token validation. If the token is valid, the API Gateway receives the user profile comprising the netprefix, userdomain, username, and user roles from the Identity Service. If the token validation fails, the execution of the algorithm is stopped.

Based on user role information, the API Gateway checks whether the user is allowed to register the requested type of node. If checking permissions succeeds, the execution of the algorithm advances. Otherwise, the algorithm execution is stopped.

Next, the API Gateway verifies whether the prefix of the node CGA matches the netprefix from the user profile. After that, the gateway verifies the CGA as per RFC 3972. Subsequently, it checks CGA uniqueness. If the CGA verification fails at any step, the execution of the algorithm is stopped.

Following the successful CGA check, the Gateway validates the message RSA signature. Successful validation proves the node is an owner of the private RSA key, whose corresponding public RSA key was used for CGA generation.

After, the API Gateway checks whether a node with the same nodename has been registered in the given userdomain. Finding a duplicate terminates the registration.

At the end of the procedure, the API Gateway responds to the node specifying the result of the node request execution, either successful or failed.

Node Keep-alive and Configuration Management Procedures

Protocol Design

Keep-alive and Configuration Management messages are part of the Bayware configuration protocol. The protocol has two stages:

• Keep-alive
• configuration management

Protocol execution always starts with carrying out the keep-alive stage. The configuration stage follows, if the controller has one or more configuration commands in its queue.

Keep-alive

The node sends a keep-alive message to the API Gateway (Southbound):

• upon a node boot-up
• upon a node configuration update
• upon receiving of a CRT-message from the controller (switch only)
• every given interval of time

The keep-alive message, among other fields, contains:

• access token
• hashes of blocks of configuration

On each keep-alive request, the API Gateway updates the value of the last keep-alive time stored in the node registration entry, preventing the entry from aging out.

The keep-alive request is processed by the API Gateway, provided the token is valid.

In the keep-alive response the controller can specify following:

• to close connection
• to keep connection and start receiving commands from controller

Upon receiving a keep-alive response without a command, the node closes its TCP connection with the controller.

Configuration Management

Upon receiving a keep-alive response containing a command, the node sends a corresponding HTTP-request to the Controller Southbound RESTful API. This request might be subsequently followed by one or more controller commands.

The Configuration Management procedure is terminated when the node receives an HHTP-response without a command from the controller.

Upon such the HTTP-response, the node closes TCP connection with the controller.

The Configuration Management procedure is described in detail in the document Auto-configuration.

Node Token-Expire Procedure

When the node’s token is expired, the node receives the reply 401() instead of the Inform Response on its regular Inform message. The node sends the requestToken() message to the Identity Service. If the user credentials are still valid, the Identity Service replies with a new token.

Upon receiving the new token, the nodes repeats its Inform request to the controller. In this case, the nodes receives a regular Inform response from the controller.

Node Unregistration Procedure

When a node needs to be disconnected, the node sends a node unregistration request to the API Gateway. On the request, the API Gateway invalidates the node registration entry.

The unregistration call is processed by the API Gateway, provided the token is valid.

Link Registration

Protocol Suite

The subset of IPv6 Secure Neighbor Discovery Protocol (SeND) messages is employed in the link registration procedure. The SeND guarantees authenticity and integrity of all the neighbor discovery messages. CGA is an integral part of the SeND protocol.

The Link Registration procedure relies on the OpenID Connect over OAuth2 protocol suite and utilizes the same controller Southbound API as the Node Registration procedure does.

SeND Messages

All the message used in the link registration procedure have the format defined in RFC 4861 and RFC 3971.

Four message types are used:

• Router Solicitation Message
• Router Advertisement Message
• Neighbor Solicitation Message
• Neighbor Advertisement Message

Each message has:

• the sender node’s CGA in the source address field of IPv6 header
• either the receiver node’s CGA or broadcast address (unsolicited messages only) in the destination address field of IPv6 header

As per the RFCs, each message contains five options:

• Source Link-Layer Address option
• CGA option
• Nonce option
• Time Stamp option
• RSA option

The CGA option contains a node’s public RSA key and parameters used to generate the source IP address.

The RSA option contains a hash of the public RSA key and an RSA signature of the entire massage. The signature covers among other things the source and destination addresses from the IP packet header and all the options.

This combination of these options helps a receiver of the message validate:

• the source address is derived from the public RSA key, prefix and auxiliary parameters – CGA option
• the message, including message’s source address and public RSA key, is signed with the private RSA key – RSA and CGA options
• it is not a repeat of a previous response – Nonce option
• it is not a duplicate – Time Stamp option

The receiver checks only once that the source address is derived from the public RSA key, prefix and auxiliary parameters. After checking, the receiver keeps the association between the address and public RSA key to check signatures of all messages having the given source address with the given public RSA key.

Link Registration Algorithm

Node Discovery Procedure

Detection of a new port by a node triggers the Node Discovery algorithm execution. On the new port detection, the switch starts sending SeND-URA messages into the port. The unsolicited router advertisement messages use the all-nodes multicast address as a destination address and the Node B CGA as a source address. When a port on the remote node (Node A) is up, this node transits to the Link Establishment phase. If the remote port is not ready, the SeND-URA message is lost. And the Node B eventually repeats this message every given interval of time.

When Node A detects a new port, the node–if a host–might not be willing to wait for a next scheduled SeND-URA. Thus, Node A prompts the remote switch (Node B) to generate Router Advertisement quickly by sending the SeND-RS message. The all-routers multicast address is used as a destination address in the SeND-RS message and the Node A CGA as a source address. Note: If the Node A is a switch, the node sends the SeND-URA messages upon new port detection as described above.

After successful validation of the SeND-RS message, Node B replies to the SeND-RS message with the SeND-RA message, wherein the Node A CGA is used as a destination address and the Node B CGA - as a source address. At the same time Node B transits to the Link Establishment phase, as it has at this stage the Node A CGA received in the SeND-RS message. If the SeND-RS message validation failed, Node B silently discards the message without algorithm advancing.

Receiving by Node A the SeND-RA message with the Node B CGA triggers transition of Node A to the Link Establishment phase. It happens only in case Node B validates the SeND-RA message successfully. Provided validation fails, Node B discards the message silently. If Node B does not receive any replay on its SeND-RS message, the node keeps sending SeND-RS messages every given interval of time.

Note: If a port supports point-to-point links only, the switch ceases dispatching the SeND-URA messages into the port after transition on this port to any other state but the Node Discovery.

Link Establishment Procedure

Node A Request

In the link establishment state, Node A sends the SeND-NS message to Node B. This message contains a nonce among other options. Provided the SeND-NS message is valid and Node B is in the Link Establishment state as well, Node B requests the controller to pre-authorize the link establishment providing such data:

• Node B access token (not shown on the diagram)
• Node A CGA
• Node A message nonce
• Node B CGA
• Node B interface identifier for this link
• Node B RCI of the egress connection for this link

First of all, Controller validates the access token. Then, if both nodes have been already registered, Controller stores the pre-authorized connection with all the attributes including its RCI identifier and message nonce in controller’s database. Whether creating the connection succeeds or fails, Controller responds to Node B.

Upon receiving a positive response from Controller, Node B dispatches the SeND-NA message to Node A. The message contains the same nonce that was received in the SeND-NS message.

After verifying the SeND-NA message, Node A requests Controller to authorize the connection created on a request with the given CGA and nonce. Node A provides Controller with such data:

• Node A access token (not shown on the diagram)
• Node A CGA
• Node A message nonce
• Node B CGA
• Node A interface identifier for this link

After receiving the connection authorization request, Controller adds the Node A port identifier and name to the pre-authorized connection entry. The entry key is a combination of:

• Node A CGA
• Node A message nonce
• Node B CGA

Following the entry update, Controller responses to Node A with the values:

• RCI-B
• IfaceNum-B

In the next step, Controller tries to register a link between Node A and Node B. This operation fails as Controller has only one connection out of two needed to create a link.

Node B Request

From Node B perspective, the link establishment procedure mirrors all the steps described in the Node A Request section of this document. It starts with dispatching the SeND-NS message by Node B and finishes with receiving by Node B the values:

• RCI-A
• IfaceNum-A

This time, since Controller has two matching connections, its attempt to create the link succeeds. Note: the two connections are matched if they have identical attributes, such as:

• pair of node CGAs
• pair of node iface numbers

One and only one link can be established between the two nodes via a single pair of interfaces. For example, a GRE tunnel can be utilized by one link only.

Neighbor Unreachability Detection Procedure

The same pair of SeND-NS/NA messages, as described earlier, is used in the Neighbor Unreachability Detection procedure. This document does not specify what triggers execution of the procedure. For example, a node can check a neighbor reachability every given interval of time or when a particular number of the expected ‘Link Ready’ Status Advertisement messages has not been received. As well, an upper-layer event may trigger the reachability check, e.g. setup of a new service endpoint on the host.

As per SeND specification, every node must respond to the SeND-NS message with the SeND-NA message containing the nonce received in the SeND-NS. The time stamp is used to prevent replay attacks.

The nodes on the both sides of the link must verify signatures of the messages before further processing.

‘Link Ready’ Status Advertisement Procedure

As soon as a node has two matching ingress and egress connections established (both the auth and pre-auth successfully done), the node creates the link and reports the ‘link-ready’ status to the remote node by sending the SeND-UNA message.

The SeND-UNA message uses the all-nodes multicast address as a destination address.

While a node has the link status Active, the node sends SeND-UNA messages into the link’s interface every given interval of time.

Link Keep-alive Procedure

Link Keep-alive message to the controller is a part of the node keep-alive message. The node includes a fingerprint of its link set in every node keep-alive message.

Link Unregistration Procedure

To unregister the link the node sends the node keep-alive message with a new configuration hash. Receiving the message with the unknown configuration hash triggers execution of the configuration management algorithm on the controller. In a response to this keep-alive message, the controller sends to the node the command Keep Connection. Next, an execution of the regular configuration management algorithm provides the controller with an updated list of active links.

Upon receiving the new list of active links, the API Gateway:

• invalidates the link registration entry that are not in the list
• removes the node’s egress connection related to the link

At the same time, the node terminates dispatching the SeND-UNA messages. From this point, the node might ignore all incoming SeND-NS messages on the port if the port supports point-to-point links only.

Eventually, the remote node detects the absence of the ingress connection – no incoming SeND-UNA messages any more. The remote node might keep trying to re-establish link a given period of time. Then, the node transitions into the neighbor discovery state or ceases the attempts to establish a link on this port until it receives a link establishment request itself.

Service Endpoint Registration

Protocol Suite

Service Endpoint Registration procedure relays on the OpenID Connect over OAuth2 protocol suite and utilizes the Controller Southbound API.

Service Endpoint Registration Algorithm

Service Endpoint Registration Procedure

A request from an application to create an endpoint triggers execution of the service endpoint registration algorithm. In this call, the application specifies a topic and, non-mandatory, a role in this topic. All other options–such as a port number, etc.–are optional.

The node translates the application’s call to the API Gateway, attaching an allocated port number and token.

The API Gateway processes the service endpoint registration request only from the nodes already registered on the controller.

After token validation, the API Gateway checks whether the node owner has permissions to set up endpoints. Secondly, the API Gateway validates if the node owner has permissions to work in the given topic in the particular role, provided the last has been specified.

Every time the permission check succeeds, the API Gateway responds to the node with service endpoint configuration.

Service Endpoint Keep-alive Procedure

Service Endpoint Keep-alive message is a part of the node keep-alive message. The node includes a fingerprint of its service endpoint set in every node keep-alive message.

Service Endpoint Unregistration Procedure

To unregister service endpoint the node sends the node keep-alive message with a new configuration hash. Receiving the message with the unknown configuration hash triggers execution of the configuration management algorithm on the controller. In response to this keep-alive message, the controller sends the node the command Keep Connection. Next, an execution of the regular configuration management algorithm provides the controller with an updated list of active service endpoint.