== TCPMD5 User Guide

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

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>
----