NETCONF protocol specifies the set of requirements for the transport protocol in RFC 6241. There are currently 2 specifications how to use specific transport protocols for NETCONF: [RFC 6242][RFC6242] for Secure SHell (SSH) and RFC 5539bis for Transport Layer Security (TLS). SSH is mandatory transport for NETCONF implementations.

libnetconf supports SSH transport out of the box. From version 0.8, there is also experimental support for TLS transport. By default, this is not available by default. To enable TLS transport, following action must be performed:

run configure with --enable-tls option:
./configure --enable-tls

See the Netopeer project as a reference implementation.

Transport Support on the Client Side

To switch from the default SSH transport to the TLS transport, application must call nc_session_transport() with NC_TRANSPORT_TLS parameter. Remember, that this change applies only to the current thread.

Next step is to initiate TLS context for the new NETCONF session. Using nc_tls_init() function, client is supposed to set its client certificate and CA for server certificate validation.

Now the TLS context is ready and new NETCONF session over TLS can be established using nc_session_connect(). Application can run nc_tls_init() again, but the changed parameters will be applied only to the newly created NETCONF sessions.

To properly clean all resources, call nc_tls_destroy(). It will destroy TLS connection context. This function can be called despite the running NETCONF session, but creating a new NETCONF session over TLS is not allowed after calling nc_tls_destroy() - the client has to call nc_tls_init() again.

The whole process described here is supposed to be performed in a single thread. SSH transport works out of the box, so no specific step, as mentioned for TLS in this section, is required.

Transport Support on the Server Side

There is no specific support for neither SSH or TLS on the server side. libnetconf doesn't implement SSH nor TLS server - it is expected, that NETCONF server application uses external application (sshd, stunnel,...) serving as SSH/TLS server and providing NETCONF data to the NETCONF server stdin, where libnetconf can read the data, and getting data from the NETCONF server stdout to encapsulate the data and send to a client.

For both cases, SSH as well as TLS, there are two functions: nc_session_accept() and nc_session_accept_username(), that serve to accept incoming connection despite the transport protocol. As mentioned, they read data from stdin and write data to the stdout. Difference between those functions is in recognizing NETCONF username. nc_session_accept() guesses username from the process's UID. For example, in case of using SSH Subsystem mechanism in OpenSSH implementation, SSH daemon automatically changes UID of the launched SSH Subsystem process (NETCONF server/agent) to the UID of the logged user. But in case of other SSH/TLS server, this doesn't have to be done. In such a case, NETCONF server itself is supposed to correctly recognize the NETCONF username and specify it explicitly when establishing NETCONF session using nc_session_accept_username().