docs/developer-guide/snbi-developer-guide.rst

   1 SNBI Developer Guide
   2 ====================
   3
   4 Overview
   5 --------
   6
   7 Key distribution in a scaled network has always been a challenge.
   8 Typically, operators must perform some manual key distribution process
   9 before secure communication is possible between a set of network
  10 devices. The Secure Network Bootstrapping Infrastructure (SNBI) project
  11 securely and automatically brings up an integrated set of network
  12 devices and controllers, simplifying the process of bootstrapping
  13 network devices with the keys required for secure communication. SNBI
  14 enables connectivity to the network devices by assigning unique IPv6
  15 addresses and bootstrapping devices with the required keys. Admission
  16 control of devices into a specific domain is achieved using whitelist of
  17 authorized devices.
  18
  19 SNBI Architecture
  20 -----------------
  21
  22 At a high level, SNBI architecture consists of the following components:
  23
  24 -  SNBI Registrar
  25
  26 -  SNBI Forwarding Element (FE)
  27
  28 .. figure:: ./images/snbi/snbi_arch.png
  29    :alt: SNBI Architecture Diagram
  30
  31    SNBI Architecture Diagram
  32
  33 SNBI Registrar
  34 ~~~~~~~~~~~~~~
  35
  36 Registrar is a device in a network that validates device against a
  37 whitelist and delivers device domain certificate. Registrar includes the
  38 following:
  39
  40 -  RESTCONF API for Domain Whitelist Configuration
  41
  42 -  Certificate Authority
  43
  44 -  SNBI Southbound Plugin
  45
  46 **RESTCONF API for Domain Whitelist Configuration:.**
  47
  48 RESTCONF APIs are used to configure the whitelist set device in the
  49 registrar in the controller. The registrar interacts with the MD-SAL to
  50 obtain the whitelist set of devices and validate the device trying to
  51 join a domain. Furthermore it is possible to run multiple registrar
  52 instances pertaining to each domain.
  53
  54 **SNBI Southbound Plugin:.**
  55
  56 The Southbound Plugin implements the protocol state machine necessary to
  57 exchange device identifiers, and deliver certificates. The southbound
  58 plugin interacts with MD-SAL and the certificate authority to validate
  59 and create device domain certificates. The device domain certificate
  60 thus generated could be used to prove the validity of the devices within
  61 the domain.
  62
  63 **Certificate Authority:.**
  64
  65 A simple certificate authority is implemented using the Bouncy Castle
  66 package. The Certificate Authority creates the certificates from the
  67 device CSR requests received from the devices. The certificates thus
  68 generated are delievered to the devices using the Southbound Plugin as
  69 discussed earlier.
  70
  71 SNBI Forwarding Element (FE)
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73
  74 The SNBI Forwarding Element runs on Linux machines which have to join
  75 the domain. The Device UDI(Universal Device Identifier) or the device
  76 identifier could be derived from a multitude of parameters in the host
  77 machine, but most of the parameters derived from the host are known
  78 ahead or doesn’t remain constant across reloads. Therefore, each of the
  79 SNBI FE should be configured explicitly with a UDI that is already
  80 present in the device white list. The registrar service IP address must
  81 be provided to the first host (Forwarding Element) to be bootstrapped.
  82 As mentioned in the `section\_title <#_host_configuration>`__ section,
  83 the registrar service IP address is **fd08::aaaa:bbbb:1**. The First
  84 Forwarding Element must be configured with this IPv6 address.
  85
  86 The forwarding element must be installed or unpacked on a Linux host
  87 whose network layer traffic must be secured. The FE performs the
  88 following functions:
  89
  90 -  Neighour Discovery
  91
  92 -  Bootstrapping with device domain certificates
  93
  94 -  Host Configuration
  95
  96 Neighbour Discovery
  97 ^^^^^^^^^^^^^^^^^^^
  98
  99 Neighbour Discovery (ND) is the first step in accommodating devices in a
 100 secure network. SNBI performs periodic neighbour discovery of SNBI
 101 agents by transmitting ND hello packets. The discovered devices are
 102 populated in an ND table. Neighbour Discovery is periodic and
 103 bidirectional. ND hello packets are transmitted every 10 seconds. A 40
 104 second refresh timer is set for each discovered neighbour. On expiry of
 105 the refresh timer, the Neighbour Adjacency is removed from the ND table
 106 as the Neighbour Adjacency is no longer valid. It is possible that the
 107 same SNBI neighbour is discovered on multiple links, the expiry of a
 108 device on one link does not automatically remove the device entry from
 109 the ND table. In the exchange of ND keepalives, the device UDI is
 110 exchanged.
 111
 112 Bootstrapping with Device Domain Certificates
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 Bootstrapping a device involves the following sequential steps:
 116
 117 -  Authenticate a device using device identifier (UDI-Universal Device
 118    Identifier or SUDI-Secure Universal Device Identifier) - The device
 119    identifier is exchanged in the hello messages.
 120
 121 -  Allocate the appropriate device ID and IPv6 address to uniquely
 122    identify the device in the network
 123
 124 -  Allocate the required keys by installing a Device Domain Certificate
 125
 126 -  Accommodate the device in the domain
 127
 128 A device which is already bootstrapped acts as a proxy to bootstrap the
 129 new device which is trying to join the domain.
 130
 131 -  Neighbour Invite phase - When a proxy device detects a new neighbor
 132    bootStrap connect message is initiated on behalf of the New device
 133    --**NEIGHBOUR CONNECT** Msg. The message is sent to the registrar to
 134    authenticate the device UDI against the whitelist of devices. The
 135    source IPv6 address is the proxy IPv6 address and the destination
 136    IPv6 address is the registrar IPv6 address. The SNBI Registrar
 137    provides appropriate device ID and IPv6 address to uniquely identify
 138    the device in the network and then invites the device to join the
 139    domain. — \ **NEIGHBOUR INVITE** Msg.
 140
 141 -  Neighbour Reject - If the Device UDI is not in the white list of
 142    devices, then the device is rejected and is not accepted into the
 143    domain. The proxy device just updates its DB with the reject
 144    information but still maintains the Neighbour relationship.
 145
 146 -  Neighbour BootStrap Phase - Once the new device gets a neighbour
 147    invite message, it tries to boot strap itself by generating a key
 148    pair. The device generates a Certificate Sign Request (CSR) PKCS10
 149    request and gets it signed by the CA running at the SNBI
 150    Registrar. — \ **BS REQ** Msg. Once the certificate is enrolled and
 151    signed by the CA, the generated x.509 certificate is returned to the
 152    new device to complete the bootstrap process. — \ **BS RESP** Msg.
 153
 154 Host Configuration
 155 ~~~~~~~~~~~~~~~~~~
 156
 157 Host configuration involves configuring a host to create a secure
 158 overlay network, assigning appropriate IPv6 address, setting up GRE
 159 tunnels, securing the tunnels traffic via IPsec and enabling
 160 connectivity via a routing protocol. Docker is used to package all the
 161 required dependent software modules.
 162
 163 .. figure:: ./images/snbi/first_fe_bs.png
 164    :alt: SNBI Bootstrap Process
 165
 166    SNBI Bootstrap Process
 167
 168 -  Interace configuration: The Iproute2 package, which comes by default
 169    packaged in the Linux distributions, is used to configure the
 170    required interface (snbi-fe) and assign the appropriate IPv6 address.
 171
 172 -  GRE Tunnel Creation: LinkLocal GRE tunnels are created to each of the
 173    discovered devices that are part of the domain. The GRE tunnels are
 174    used to create the overlay network for the domain.
 175
 176 -  Routing over the Overlay: To enable reachability of devices within
 177    the overlay network a light weight routing protocol is used. The
 178    routing protocol of choice is the RPL (Routing Protocol for Low-Power
 179    and Lossy Networks) protocol. The routing protocol advertises the
 180    device domain IPv6 address over the overlay network. **Unstrung** is
 181    the open source implementation of RPL and is packaged within the
 182    docker image. More details on unstrung is available at
 183    http://unstrung.sandelman.ca/
 184
 185 -  IPsec: IPsec is used to secure any traffic routed over the tunnels.
 186    StrongSwan is used to encrypt traffic using IPsec. More details on
 187    StrongSwan is available at https://www.strongswan.org/
 188
 189 Docker Image
 190 ~~~~~~~~~~~~
 191
 192 The SNBI Forwarding Element is packaged in a docker container available
 193 at this link: https://hub.docker.com/r/snbi/boron/. For more information
 194 on docker, refer to this link: https://docs.docker.com/linux/.
 195
 196 To update an SNBI FE Daemon, build the image and copy the image to
 197 /home/snbi directory. When the docker image is run, it autoamtically
 198 generates a startup configuration file for the SNBI FE daemon. The
 199 startup configuration script is also available at /home/snbi.
 200
 201 .. figure:: ./images/snbi/docker_snbi.png
 202    :alt: SNBI Docker Image
 203
 204    SNBI Docker Image
 205
 206 Key APIs and Interfaces
 207 -----------------------
 208
 209 The only API that SNBI exposes is to configure the whitelist of devices
 210 for a domain.
 211
 212 The POST method below configures a domain - "secure-domain" and
 213 configures a whitelist set of devices to be accommodated to the domain.
 214
 215 ::
 216
 217     {
 218       "snbi-domain": {
 219         "domain-name": "secure-domain",
 220         "device-list": [
 221           {
 222             "list-name": "demo list",
 223             "list-type": "white",
 224             "active": true,
 225             "devices": [
 226               {
 227                 "device-id": "UDI-FirstFE"
 228               },
 229               {
 230                 "device-id": "UDI-dev1"
 231               },
 232               {
 233                 "device-id": "UDI-dev2"
 234               }
 235             ]
 236           }
 237          ]
 238       }
 239     }
 240
 241 The associated device ID must be configured on the SNBI FE (see above).
 242
 243 API Reference Documentation
 244 ---------------------------
 245
 246 See the generated RESTCONF API documentation at:
 247 http://localhost:8181/apidoc/explorer/index.html
 248
 249 Look for the SNBI module to expand and see the various RESTCONF APIs.
 250