== TCPMD5 Developer Guide
=== Overview
-Provide an overview of the feature, what it logical functionality it
-provides and why you might use it as a developer. To be clear the target
-audience for this guide is a developer who will be _using_ the feature
-to build something separate, but _not_ somebody who will be developing
-code for this feature itself.
-NOTE: More so than with user guides, the guide may cover more than one
-feature. If that is the case, be sure to list all of the features this
-covers.
+The TCPMD5 project delivers the support for providing access to MD5 Signature
+Option on operating systems which support it in their TCP stack. The
+implementation is compliant with link:http://tools.ietf.org/html/rfc2385[RFC-2385].
+
+The project is available from the tcpmd5 repository. It is split into:
+
+tcpmd5-api
+
+tcpmd5-jni
+
+tcpmd5-nio
+
+tcpmd5-netty
+
+tcpmd5-controller-config
+
+tcpmd5-feature
=== TCPMD5 Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help. This may be the same
-as the diagram used in the user guide, but it should likely be less
-abstract and provide more information that would be applicable to a
-developer.
+
+This project defines a new TCP option for carrying an MD5 digest
+in a TCP segment. This digest acts like a signature for that segment,
+incorporating information known only to the connection end points.
=== Key APIs and Interfaces
-Document the key things a user would want to use. For some features,
-there will only be one logical grouping of APIs. For others there may be
-more than one grouping.
-Assuming the API is MD-SAL- and YANG-based, the APIs will be available
-both via RESTCONF and via Java APIs. Giving a few examples using each is
-likely a good idea.
+As this project is fairly small, it provides only one feature that installs and
+provides all APIs and implementations for this project.
+
+==== tcpmd5-api
+
+Defines the basic API and a dummy implementation.
+
+==== tcpmd5-jni
+
+Contains the JNI implementation and its Java binding. The core of the artifact
+is NativeKeyAccess.java, which is the Java frontend and binding class. It
+defines the two native methods, setChannelKey0() and isClassSupported0(). These
+are implemented in tcpmd5_jni.c. Individual instances are then provided by
+NativeKeyAccessFactory, which runs basic sanity tests before allowing itself
+being instantiated.
+
+==== tcpmd5-nio
+
+Contains the code to bridge the JNI component with java.nio package,
+specifically ServerSocketChannel, SocketChannel and SocketOption classes.
-==== API Group 1
-Provide a description of what the API does and some examples of how to
-use it.
+==== tcpmd5-netty
-==== API Group 2
-Provide a description of what the API does and some examples of how to
-use it.
+Contains the code to bridge the JNI component with netty.io, by providing the
+appropriate SocketChannelFactory.
-=== API Reference Documentation
-Provide links to JavaDoc, REST API documentation, etc.
== TCPMD5 User Guide
-Refer to this template to identify the required sections and information
-that you should provide for a User Guide. The user guide should contain
-configuration, administration, management, using, and troubleshooting
-sections for the feature.
+
+This user guide describes the configuration for Border Gateway Protocol (BGP) and Path Computation Element Protocol (PCEP)
+using MD5 authentication. It is destined for users who build applications using MD5 library.
=== Overview
-Provide an overview of the feature and the use case. Also include the
-audience who will use the feature. For example, audience can be the
-network administrator, cloud administrator, network engineer, system
-administrators, and so on.
-
-=== TCPMD5 Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help.
-
-=== Configuring TCPMD5
-
-Describe how to configure the feature or the project after installation.
-Configuration information could include day-one activities for a project
-such as configuring users, configuring clients/servers and so on.
-
-=== Administering or Managing TCPMD5
-Include related command reference or operations that you could perform
-using the feature. For example viewing network statistics, monitoring
-the network, generating reports, and so on.
-
-NOTE: Ensure that you create a step procedure whenever required and
-avoid concepts.
-
-For example:
-
-.To configure L2switch components perform the following steps.
-. Step 1:
-. Step 2:
-. Step 3:
-
-=== Tutorials
-<optional>
-If there is only one tutorial, you skip the "Tutorials" section and
-instead just lead with the single tutorial's name.
-
-==== <Tutorial Name>
-Ensure that the title starts with a gerund. For example using,
-monitoring, creating, and so on.
-
-===== Overview
-An overview of the use case.
-
-===== Prerequisites
-Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-Include any topology requirement for the use case. Ideally, provide
-visual (abstract) layout of network diagrams and any other useful visual
-aides.
-
-===== Instructions
-Use case could be a set of configuration procedures. Including
-screenshots to help demonstrate what is happening is especially useful.
-Ensure that you specify them separately. For example:
-
-. *Setting up the VM*
-To set up a VM perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Installing the feature*
-To install the feature perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Configuring the environment*
-To configure the system perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
+
+The TCPMD5 library provides access to link:http://tools.ietf.org/html/rfc2385[RFC-2385] MD5 Signature Option on operating systems which support it in their TCP stack.
+This option has been historically used to protect BGP sessions, but is equally useful for protecting PCEP sessions.
+
+IMPORTANT: *Before you continue with steps in this user guide, make sure BGP and/or PCEP is configured properly.*
+
+TCPMD5 authentication is *disabled* by default. To enable it (for both protocols), uncomment the contents of _20-tcpmd5.xml_.
+You can find this configuration file in your OpenDaylight directory _etc/opendaylight/karaf_ .
+
+CAUTION: [big]#*If the connection can not be established, there are no warnings or errors,
+so be sure to double check your configuration and passwords.*#
+
+=== Configuring TCPMD5 manually
+
+==== BGP
+
+IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
+
+To enable TCPMD5 for the BGP protocol, perform the following steps:
+
+. In _31-bgp.xml_ uncomment the TCP MD5 section:
++
+[source,xml]
+----
+<!--
+ Uncomment this block to enable TCPMD5 Signature support
+-->
+<md5-channel-factory>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
+ <name>md5-client-channel-factory</name>
+</md5-channel-factory>
+<md5-server-channel-factory>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
+ <name>md5-server-channel-factory</name>
+</md5-server-channel-factory>
+----
+. In _41-bgp-example.xml_ add <password> tag to module example-bgp-peer.
++
+[source,xml]
+----
+<!--
+ For TCPMD5 support, make sure the dispatcher associated with the rib has
+ "md5-channel-factory" attribute set and then add a "password" attribute here.
+ Note that the peer has to have the same password configured, otherwise the
+ connection will not be established.
+-->
+<module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-peer</type>
+ <name>example-bgp-peer</name>
+ <host>10.25.2.27</host>
+ <holdtimer>180</holdtimer>
+ <rib>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:cfg">prefix:rib</type>
+ <name>example-bgp-rib</name>
+ </rib>
+ <advertized-table>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
+ <name>ipv4-unicast</name>
+ </advertized-table>
+ <advertized-table>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
+ <name>ipv6-unicast</name>
+ </advertized-table>
+ <advertized-table>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
+ <name>linkstate</name>
+ </advertized-table>
+ <password>changeme</password>
+</module>
+----
+
+NOTE: Setting a password on other BGP devices is out of scope for this document.
+
+==== PCEP
+
+IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
+
+To enable TCPMD5 for PCE protocol, perform the following steps:
+
+. In _32-pcep.xml_ uncomment the TCPMD5 section:
++
+[source,xml]
+----
+<!--
+ Uncomment this block to enable TCPMD5 Signature support
+-->
+<md5-channel-factory>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
+ <name>md5-client-channel-factory</name>
+</md5-channel-factory>
+<md5-server-channel-factory>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
+ <name>md5-server-channel-factory</name>
+</md5-server-channel-factory>
+----
+
+. In _39-pcep-provider.xml_ uncomment following section:
++
+[source,xml]
+----
+<!--
+ For TCPMD5 support make sure the dispatcher has the "md5-server-channel-factory"
+ attribute set and then set the appropriate client entries here. Note that if this
+ option is configured, the PCCs connecting here must have the same password,
+ otherwise they will not be able to connect.
+ -->
+ <client>
+ <address>192.0.2.2</address>
+ <password>changeme</password>
+ </client>
+----
+
+IMPORTANT: *Change the <address> value to the address of PCC, the one that is advertized to PCE and provide password matching the one set on PCC.*
+
+NOTE: Setting a password on PCC is out of scope for this document.
+
+
+=== Configuring TCPMD5 through RESTCONF
+
+IMPORTANT: Before you start, make sure, you have installed features for BGP and/or PCEP. Install another feature, that will provide you the access to _restconf/config/_ URLs.
+[source,xml]
+----
+feature:install odl-netconf-connector-all
+----
+
+This log message indicates successful start of netconf-connector: _Netconf connector initialized successfully_
+
+- To check what modules you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+- To check what services you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/
+
+These URLs are also used to POST new configuration. If you want to change any other configuration that is listed here,
+make sure you include the correct namespaces. The correct namespace for <module> is always _urn:opendaylight:params:xml:ns:yang:controller:config_.
+The namespace for any other fields can be found by finding given module in configuration yang files.
+
+NOTE: RESTCONF will tell you if some namespace is wrong.
+
+To enable TCPMD5 for either one of the protocols, enable TCPMD5 modules and services:
+
+CAUTION: You have to make *separate* POST requests for each module/service!
+
+[big]#*URL:# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+[big]#*POST:*#
+
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:jni:cfg">x:native-key-access-factory</type>
+ <name>global-key-access-factory</name>
+</module>
+----
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-client-channel-factory</type>
+ <name>md5-client-channel-factory</name>
+ <key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
+ <name>global-key-access-factory</name>
+ </key-access-factory>
+</module>
+----
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory-impl</type>
+ <name>md5-server-channel-factory</name>
+ <server-key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
+ <name>global-key-access-factory</name>
+ </server-key-access-factory>
+</module>
+----
+
+[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/
+
+[big]#*POST:*#
+
+[source,xml]
+----
+<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
+ <instance>
+ <name>global-key-access-factory</name>
+ <provider>/modules/module[type='native-key-access-factory'][name='global-key-access-factory']</provider>
+ </instance>
+</service>
+----
+[source,xml]
+----
+<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
+ <instance>
+ <name>md5-client-channel-factory</name>
+ <provider>/modules/module[type='md5-client-channel-factory'][name='md5-client-channel-factory']</provider>
+ </instance>
+</service>
+----
+[source,xml]
+----
+<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
+ <instance>
+ <name>md5-server-channel-factory</name>
+ <provider>/modules/module[type='md5-server-channel-factory-impl'][name='md5-server-channel-factory']</provider>
+ </instance>
+</service>
+----
+
+==== BGP
+
+CAUTION: You have to introduce modules and services mentioned in the previous section. Your BGP client needs to be *ALREADY* configured. Check User Guide for BGP. // TODO: link to BGP section
+
+. Enabling TCPMD5 in BGP configuration:
++
+[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+[big]#*POST:*#
+
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-dispatcher-impl</type>
+ <name>global-bgp-dispatcher</name>
+ <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
+ <name>md5-client-channel-factory</name>
+ </md5-channel-factory>
+ <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
+ <name>md5-server-channel-factory</name>
+ </md5-server-channel-factory>
+</module>
+----
+
+. Set password:
++
+[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+[big]#*POST:*#
+
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-peer</type>
+ <name>example-bgp-peer</name>
+ <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">changeme</password> <!--CHANGE THE VALUE -->
+</module>
+----
+
+==== PCEP
+
+CAUTION: You have to introduce modules and services mentioned in the previous section.
+
+. Enable TCPMD5 in PCEP configuration:
++
+[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+[big]#*POST:*#
+
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">x:pcep-dispatcher-impl</type>
+ <name>global-pcep-dispatcher</name>
+ <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
+ <name>md5-client-channel-factory</name>
+ </md5-channel-factory>
+ <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
+ <name>md5-server-channel-factory</name>
+ </md5-server-channel-factory>
+</module>
+----
+
+. Set password:
++
+[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
+
+[big]#*POST:*#
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">x:pcep-topology-provider</type>
+ <name>pcep-topology</name>
+ <client xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">
+ <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">192.0.2.2</address> <!--CHANGE THE VALUE -->
+ <password>changeme</password> <!--CHANGE THE VALUE -->
+ </client>
+</module>
+----
Code Review / docs.git / commitdiff