OVSDB Library Developer Guide
Overview
The OVSDB library manages the Netty connections to network nodes and handles bidirectional JSON-RPC messages. It not only provides OVSDB protocol functionality to OpenDaylight OVSDB plugin but also can be used as standalone JAVA library for OVSDB protocol.
The main responsibilities of OVSDB library includes:
Manage connections to peers
Marshal and unmarshal JSON Strings to JSON objects.
Marshal and unmarshal JSON Strings from and to the Network Element.
Connection Service
OVSDB library provides connection management through OvsdbConnection interface. OvsdbConnection interface provides OVSDB connection management APIs which includes both active and passive connections. From the library perspective, active OVSDB connections are initiated from the controller to OVS nodes while passive OVSDB connection are initiated from OVS nodes to controller. In the active connection scenario, application needs to provide IP address and listening port on OVS nodes to library management API. On the other hand, the library management API only requires the info of controller listening port in passive connection scenario.
For passive connection scenario, the library also provides connection event listener through OvsdbConnectionListener interface. The listener interface has connected() and disconnected() methods to notify application when a new passive connection is established or an existing connection is terminated.
SSL Connection
In additional to regular TCP connection, the OvsdbConnection interface also provides connection management API for SSL connection. To start OVSDB connection with SSL, application will need to provide an Java SSLContext object to the management API. There could be different ways to create JAVA SSLContext, but in most case a Java KeyStore with certificate and private key provided by the application is required. Detail steps about how to create Java SSLContext is out of the scope of this document and can be found in Java doc JAVA Class SSlContext.
In active connection scenario, the library uses given SSLContext to create Java SSLEngine and configure the SSL engine with client mode for SSL handshaking. Normally clients are not required to authenticate themselves.
In the passive connection scenario, the library uses given SSLContext to create Java SSLEngine which will operate on server mode for SSL handshaking. For security reason, SSLv3 protocol and some cipher suites are disabled. Currently the OVSDB server only supports TLS_RSA_WITH_AES_128_CBC_SHA cipher suite and following protocols: SSLv2Hello, TLSv1, TLSv1.1, TLSv1.2.
The SSL engine is also configured to operate on two-way authentication mode for passive connection scenario, i.e, the OVSDB server (controller) will authenticate clients (OVS nodes) and clients (OVS nodes)l are also required to authenticate the server (controller). In two-way authentication mode, application should keep a trust manager to store certificates of trusted clients and initialize Java SSLContext with this trust manager. Thus during SSL handshaking process the OVSDB server (controller) can use the trust manager to verify clients and only accept connection request from trusted clients. On the other hand, user should also configure OVS nodes to authenticate the controller. OpenVswitch already supports this functionality in ovsdb-server command with option --ca-cert=cacert.pem
and --bootstrap-ca-cert=cacert.pem
. On OVS node, user can use option --ca-cert=cacert.pem
to specify controller certificate directly and the node will only allow connection to controller with specified certificate. If the OVS node runs ovsdb-server with option --bootstrap-ca-cert=cacert.pem
, it will authenticate the controller with the specified certificate cacert.pem. If the certificate file doesn’t exist, it will attempt to obtain a certificate from the peer (controller) on its first SSL connection and save it to the named PEM file cacert.pem
. Here is an example of ovsdb-server with --bootstrap-ca-cert=cacert.pem
option: