docs/user-guide/snbi-user-guide.rst

   1 SNBI User Guide
   2 ===============
   3
   4 This section describes how to use the SNBI feature in OpenDaylight and
   5 contains configuration, administration, and management section for the
   6 feature.
   7
   8 Overview
   9 --------
  10
  11 Key distribution in a scaled network has always been a challenge.
  12 Typically, operators must perform some manual key distribution process
  13 before secure communication is possible between a set of network
  14 devices. The Secure Network Bootstrapping Infrastructure (SNBI) project
  15 securely and automatically brings up an integrated set of network
  16 devices and controllers, simplifying the process of bootstrapping
  17 network devices with the keys required for secure communication. SNBI
  18 enables connectivity to the network devices by assigning unique IPv6
  19 addresses and bootstrapping devices with the required keys. Admission
  20 control of devices into a specific domain is achieved using whitelist of
  21 authorized devices.
  22
  23 SNBI Architecture
  24 -----------------
  25
  26 At a high level, SNBI architecture consists of the following components:
  27
  28 -  SNBI Registrar
  29
  30 -  SNBI Forwarding Element (FE)
  31
  32 .. figure:: images/snbi/snbi_arch.png
  33    :alt: SNBI Architecture Diagram
  34
  35    SNBI Architecture Diagram
  36
  37 SNBI Registrar
  38 ~~~~~~~~~~~~~~
  39
  40 Registrar is a device in a network that validates device against a
  41 whitelist and delivers device domain certificate. Registrar includes the
  42 following:
  43
  44 -  RESCONF API for Domain Whitelist Configuration
  45
  46 -  SNBI Southbound Plugin
  47
  48 -  Certificate Authority
  49
  50 **RESTCONF API for Domain Whitelist Configuration:.**
  51
  52 Below is the YANG model to configure the whitelist of devices for a
  53 particular domain.
  54
  55 ::
  56
  57     module snbi {
  58         //The yang version - today only 1 version exists. If omitted defaults to 1.
  59         yang-version 1;
  60
  61         //a unique namespace for this SNBI module, to uniquely identify it from other modules that may have the same name.
  62         namespace "http://netconfcentral.org/ns/snbi";
  63
  64         //a shorter prefix that represents the namespace for references used below
  65         prefix snbi;
  66
  67         //Defines the organization which defined / owns this .yang file.
  68         organization "Netconf Central";
  69
  70         //defines the primary contact of this yang file.
  71         contact "snbi-dev";
  72
  73         //provides a description of this .yang file.
  74         description "YANG version for SNBI.";
  75
  76         //defines the dates of revisions for this yang file
  77         revision "2024-07-02" {
  78             description "SNBI module";
  79         }
  80
  81         typedef UDI {
  82             type string;
  83             description "Unique Device Identifier";
  84         }
  85
  86         container snbi-domain {
  87             leaf domain-name {
  88                 type string;
  89                 description "The SNBI domain name";
  90             }
  91
  92             list device-list {
  93                 key "list-name";
  94
  95                 leaf list-name {
  96                     type string;
  97                     description "Name of the device list";
  98                 }
  99
 100                 leaf list-type {
 101                     type enumeration {
 102                         enum "white";
 103                     }
 104                     description "Indicates the type of the list";
 105                 }
 106
 107                 leaf active {
 108                     type boolean;
 109                     description "Indicates whether the list is active or not";
 110                 }
 111
 112                 list devices {
 113                     key "device-identifier";
 114                     leaf device-identifier {
 115                         type union {
 116                             type UDI;
 117                         }
 118                     }
 119                  }
 120              }
 121         }
 122     }
 123
 124 **Southbound Plugin:.**
 125
 126 The Southbound Plugin implements the protocol state machine necessary to
 127 exchange device identifiers, and deliver certificates.
 128
 129 **Certificate Authority:.**
 130
 131 A simple certificate authority is implemented using the Bouncy Castle
 132 package. The Certificate Authority creates the certificates from the
 133 device CSR requests received from the devices. The certificates thus
 134 generated are delivered to the devices using the Southbound Plugin.
 135
 136 SNBI Forwarding Element
 137 ~~~~~~~~~~~~~~~~~~~~~~~
 138
 139 The forwarding element must be installed or unpacked on a Linux host
 140 whose network layer traffic must be secured. The FE performs the
 141 following functions:
 142
 143 -  Neighour Discovery
 144
 145 -  Bootstrap
 146
 147 -  Host Configuration
 148
 149 **Neighbour Discovery:.**
 150
 151 Neighbour Discovery (ND) is the first step in accommodating devices in a
 152 secure network. SNBI performs periodic neighbour discovery of SNBI
 153 agents by transmitting ND hello packets. The discovered devices are
 154 populated in an ND table. Neighbour Discovery is periodic and
 155 bidirectional. ND hello packets are transmitted every 10 seconds. A 40
 156 second refresh timer is set for each discovered neighbour. On expiry of
 157 the refresh timer, the Neighbour Adjacency is removed from the ND table
 158 as the Neighbour Adjacency is no longer valid. It is possible that the
 159 same SNBI neighbour is discovered on multiple links, the expiry of a
 160 device on one link does not automatically remove the device entry from
 161 the ND table.
 162
 163 **Bootstrapping:.**
 164
 165 Bootstrapping a device involves the following sequential steps:
 166
 167 -  Authenticate a device using device identifier (UDI or SUDI)
 168
 169 -  Allocate the appropriate device ID and IPv6 address to uniquely
 170    identify the device in the network
 171
 172 -  Allocate the required keys by installing a Device Domain Certificate
 173
 174 -  Accommodate the device in the domain
 175
 176 **Host Configuration:.**
 177
 178 Involves configuring a host to create a secure overlay network,
 179 assigning appropriate ipv6 address, setting up gre tunnels, securing the
 180 tunnels traffic via IPsec and enabling connectivity via a routing
 181 protocol.
 182
 183 The SNBI Forwarding Element is packaged in a docker container available
 184 at this link: https://hub.docker.com/r/snbi/boron/. For more information
 185 on docker, refer to this link: https://docs.docker.com/linux/.
 186
 187 Prerequisites for Configuring SNBI
 188 ----------------------------------
 189
 190 Before proceeding further, ensure that the following system requirements
 191 are met:
 192
 193 -  64bit Ubunutu 14.04 LTS
 194
 195 -  4GB RAM
 196
 197 -  4GB of hard disk space, sufficient enough to store certificates
 198
 199 -  Java Virtual Machine 1.8 or above
 200
 201 -  Apache Maven 3.3.3 or above
 202
 203 -  Make sure the time on all the devices or synced either manually or
 204    using NTP
 205
 206 -  The docker version must be greater than 1.0 on a 14.04 Ubuntu
 207
 208 Configuring SNBI
 209 ----------------
 210
 211 This section contains the following:
 212
 213 -  Setting up SNBI Registrar on the controller
 214
 215 -  Configuring Whitelist
 216
 217 -  Setting up SNBI FE on Linux Hosts
 218
 219 Setting up SNBI Registrar on the controller
 220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 221
 222 This section contains the following:
 223
 224 -  Configuring the Registrar Host
 225
 226 -  Installing Karaf Package
 227
 228 -  Configuring SNBI Registrar
 229
 230 **Configuring the Registrar Host:.**
 231
 232 Before enabling the SNBI registrar service, assign an IPv6 address to an
 233 interface on the registrar host. This is to bind the registrar service
 234 to an IPv6 address (**fd08::aaaa:bbbb:1/128**).
 235
 236 ::
 237
 238     sudo ip link add snbi-ra type dummy
 239     sudo ip addr add fd08::aaaa:bbbb:1/128 dev snbi-ra
 240     sudo ifconfig snbi-ra up
 241
 242 **Installing Karaf Package:.**
 243
 244 Download the karaf package from this link:
 245 http://www.opendaylight.org/software/downloads, unzip and run the
 246 ``karaf`` executable present in the bin folder. Here is an example of
 247 this step:
 248
 249 ::
 250
 251     cd distribution-karaf-0.3.0-Boron/bin
 252     ./karaf
 253
 254 Additional information on useful Karaf commands are available at this
 255 link:
 256 https://wiki.opendaylight.org/view/CrossProject:Integration_Group:karaf.
 257
 258 **Configuring SNBI Registrar:.**
 259
 260 Before you perform this step, ensure that you have completed the tasks
 261 `above <#_configuring_snbi>`__:
 262
 263 To use RESTCONF APIs, install the RESTCONF feature available in the
 264 Karaf package. If required, install mdsal-apidocs module for access to
 265 documentation. Refer
 266 https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer
 267 for more information on MDSAL API docs.
 268
 269 Use the commands below to install the required features and verify the
 270 same.
 271
 272 ::
 273
 274     feature:install odl-restconf
 275     feature:install odl-mdsal-apidocs
 276     feature:install odl-snbi-all
 277     feature:list -i
 278
 279 After confirming that the features are installed, use the following
 280 command to start SNBI registrar:
 281
 282 ::
 283
 284     snbi:start <domain-name>
 285
 286 Configuring Whitelist
 287 ~~~~~~~~~~~~~~~~~~~~~
 288
 289 The registrar must be configured with a whitelist of devices that are
 290 accommodated in a specific domain. The YANG for configuring the domain
 291 and the associated whitelist in the controller is avaialble at this
 292 link:
 293 https://wiki.opendaylight.org/view/SNBI_Architecture_and_Design#Registrar_YANG_Definition.
 294 It is recommended to use Postman to configure the registrar using
 295 RESTCONF.
 296
 297 This section contains the following:
 298
 299 -  Installing PostMan
 300
 301 -  Configuring Whitelist using REST API
 302
 303 **Installing PostMan:.**
 304
 305 Follow the steps below to install postman on your Google Chrome Browser.
 306
 307 -  Install Postman via Google Chrome browser available at this link:
 308    https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en
 309
 310 -  In the chrome browser address bar, enter: chrome://apps/
 311
 312 -  Click Postman.
 313
 314 -  Enter the URL.
 315
 316 -  Click Headers.
 317
 318 -  Enter Accept: header.
 319
 320 -  Click Basic Auth tab to create user credentials, such as user name
 321    and password.
 322
 323 -  Send.
 324
 325 You can download a sample Postman configuration to get started from this
 326 link: https://www.getpostman.com/collections/c929a2a4007ffd0a7b51
 327
 328 **Configuring Whitelist using REST API:.**
 329
 330 The POST method below configures a domain - "secure-domain" and
 331 configures a whitelist set of devices to be accommodated to the domain.
 332
 333 ::
 334
 335     {
 336       "snbi-domain": {
 337         "domain-name": "secure-domain",
 338         "device-list": [
 339           {
 340             "list-name": "demo list",
 341             "list-type": "white",
 342             "active": true,
 343             "devices": [
 344               {
 345                 "device-id": "UDI-FirstFE"
 346               },
 347               {
 348                 "device-id": "UDI-dev1"
 349               },
 350               {
 351                 "device-id": "UDI-dev2"
 352               }
 353             ]
 354           }
 355          ]
 356       }
 357     }
 358
 359 The associated device ID must be configured on the SNBI FE (see below).
 360 You can also use REST APIs using the API docs interface to push the
 361 domain and whitelist information. The API docs could be accessed at
 362 link:http://localhost:8080/apidoc/explorer. More details on the API docs
 363 is available at
 364 link:https://wiki.opendaylight.org/view/OpenDaylight\_Controller:MD-SAL:Restconf\_API\_Explorer
 365
 366 Setting up SNBI FE on Linux Hosts
 367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 368
 369 The SNBI Daemon is used to bootstrap the host device with a valid device
 370 domain certificate and IP address for connectivity and to create a
 371 reachable overlay network by interacting with multiple software modules.
 372
 373 **Device UDI:.**
 374
 375 The Device UDI or the device Unique Identifier can be derived from a
 376 multitude of parameters in the host machine, but most derived parameters
 377 are already known or do not remain constant across reloads. Therefore,
 378 every SNBI FE must be configured explicitly with a UDI that is present
 379 in the device whitelist.
 380
 381 **First Forwarding Element:.**
 382
 383 The registrar service IP address must be provided to the first host
 384 (Forwarding Element) to be bootstrapped. As mentioned in the
 385 "Configuring the Registrar Host" section, the registrar service IP
 386 address is **fd08::aaaa:bbbb:1**. The First Forwarding Element must be
 387 configured with this IPv6 address.
 388
 389 **Running the SNBI docker image:.**
 390
 391 The SNBI FE in the docker image picks the UDI of the ForwardingElement
 392 via an environment variable provided when executing docker instance. If
 393 the Forwarding Element is a first forwarding element, the IP address of
 394 the registrar service should also be provided.
 395
 396 ::
 397
 398     sudo docker run -v /etc/timezone:/etc/timezone:ro --net=host --privileged=true
 399     --rm -t -i -e SNBI_UDI=UDI-FirstFE  -e SNBI_REGISTRAR=fd08::aaaa:bbbb:1 snbi/boron:latest /bin/bash
 400
 401 After the docker image is executed, you are placed in the snbi.d command
 402 prompt.
 403
 404 A new Forwarding Element is bootstrapped in the same way, except that
 405 the registrar IP address is not required while running the docker image.
 406
 407 ::
 408
 409     sudo docker run --net=host --privileged=true --rm -t -i -e SNBI_UDI=UDI-dev1 snbi/boron:latest /bin/bash
 410
 411 Administering or Managing SNBI
 412 ------------------------------
 413
 414 The SNBI daemon provides various show commands to verify the current
 415 state of the daemon. The commands are completed automatically when you
 416 press Tab in your keyboard. There are help strings "?" to list commands.
 417
 418 ::
 419
 420     snbi.d > show snbi
 421             device                Host deevice
 422             neighbors             SNBI Neighbors
 423             debugs                Debugs enabled
 424             certificate           Certificate information
 425