This document describes the node, link, and service endpoint registration procedures in a Bayware network.
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)
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||✔||✔||✔||✔||✖||✔|
|Controller SB RESTful API||✖||✔||✔||✔||✖||✖|
|Controller NB RESTful API||✖||✖||✖||✖||✖||✔|
|Agent RESTful API||✖||✖||✖||✔||✖||✖|
Every node has several major attributes:
- node type
- node owner
- node name
- node identifier
- node locator
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.
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.
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.
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.
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¶
The User Authentication and Node Initialization procedure employs the OpenID Connect over OAuth2 protocol suite.
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 procedure relies on the OpenID Connect over OAuth2 protocol suite and utilizes the Controller Southbound API.
Node Registration Algorithm¶
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¶
Keep-alive and Configuration Management messages are part of the Bayware configuration protocol. The protocol has two stages:
- 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.
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.
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.
Service Endpoint Registration¶
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.