Client sessions

To connect to a NETCONF server, a NETCONF session must be established, which requires a working transport session. It is possible to create NETCONF sessions with SSH (using libssh) or TLS (using libssl/libcrypto) as the underlying transport protocol. It is also possible to establish the transport protocol outside libnetconf2 and then provide these file descriptors (FD) for full NETCONF session creation.

There are a lot of options for both an SSH and a TLS client. All of them have setters and getters so that there is no need to duplicate them in a client.

SSH

Connecting to a server using SSH does not strictly require to set any options, there are sensible default values for all the basic ones. Except all the SSH options, optionally some authetication callbacks can be set, which are particulary useful in automated clients (passwords cannot be asked a user) or simply if any additional information is retrieved some other way than from standard terminal input.

Having the default options or changing any unsuitable ones, there are 2 functions to use for a new server connection. nc_connect_ssh() is the standard function that creates sessions using the set options. If there are some options, which cannot be changed with the provided API, there is nc_connect_libssh() available. It requires a libssh session, in which all the SSH options can be modified and even the connection established. This allows for full customization and should fit any specific situation.

New NETCONF sessions can also be created on existing authenticated SSH sessions. There is a new SSH channel needed, on which the NETCONF session is then created. Use nc_connect_ssh_channel() for this purpose.

Functions List

Available in nc_client.h.

• nc_client_ssh_set_auth_password_clb()
• nc_client_ssh_get_auth_password_clb()
• nc_client_ssh_set_auth_interactive_clb()
• nc_client_ssh_get_auth_interactive_clb()
• nc_client_ssh_set_auth_privkey_passphrase_clb()
• nc_client_ssh_get_auth_privkey_passphrase_clb()
• nc_client_ssh_add_keypair()
• nc_client_ssh_del_keypair()
• nc_client_ssh_get_keypair_count()
• nc_client_ssh_get_keypair()
• nc_client_ssh_set_auth_pref()
• nc_client_ssh_get_auth_pref()
• nc_client_ssh_set_username()
• nc_client_ssh_get_username()
• nc_connect_ssh()
• nc_connect_libssh()
• nc_connect_ssh_channel()

TLS

To connect to a server using TLS, there must be some client identification options set. Client must specify its certificate with a private key using nc_client_tls_set_cert_key_paths(). Also, the Certificate Authority of a server certificate must be considered trusted. Paths to all the trusted CA certificates can be set by nc_client_tls_set_trusted_ca_paths().

Then there are again 2 functions for connecting, nc_connect_tls() being the standard way of connecting. nc_connect_libssl() again enables to customize the TLS session in every way libssl allows.

Functions List

Available in nc_client.h.

• nc_client_tls_set_cert_key_paths()
• nc_client_tls_get_cert_key_paths()
• nc_client_tls_set_trusted_ca_paths()
• nc_client_tls_get_trusted_ca_paths()
• nc_client_tls_set_crl_paths()
• nc_client_tls_get_crl_paths()
• nc_connect_tls()
• nc_connect_libssl()

FD and UNIX socket

If you authenticated the connection using some tunneling software, you can pass its file descriptors to libnetconf2 using nc_connect_inout(), which will continue to establish a full NETCONF session. To connect locally on a UNIX socket avoiding all cryptography use nc_connect_unix().

Funtions List

Available in nc_client.h.

• nc_connect_inout()
• nc_connect_unix()

Call Home

Call Home needs the same options set as standard SSH or TLS and the functions reflect it exactly. However, to accept a connection, the client must first specify addresses and ports, which to listen on by nc_client_ssh_ch_add_bind_listen() and nc_client_tls_ch_add_bind_listen(). Then connections can be accepted using nc_accept_callhome().

Functions List

Available in nc_client.h.

• nc_client_ssh_ch_set_auth_password_clb()
• nc_client_ssh_ch_set_auth_interactive_clb()
• nc_client_ssh_ch_set_auth_privkey_passphrase_clb()
• nc_client_ssh_ch_add_bind_listen()
• nc_client_ssh_ch_del_bind()
• nc_client_ssh_ch_add_keypair()
• nc_client_ssh_ch_del_keypair()
• nc_client_ssh_ch_get_keypair_count()
• nc_client_ssh_ch_get_keypair()
• nc_client_ssh_ch_set_auth_pref()
• nc_client_ssh_ch_get_auth_pref()
• nc_client_ssh_ch_set_username()
• nc_client_ssh_ch_get_username()
• nc_client_tls_ch_add_bind_listen()
• nc_client_tls_ch_del_bind()
• nc_client_tls_ch_set_cert_key_paths()
• nc_client_tls_ch_get_cert_key_paths()
• nc_client_tls_ch_set_trusted_ca_paths()
• nc_client_tls_ch_get_trusted_ca_paths()
• nc_client_tls_ch_set_crl_paths()
• nc_client_tls_ch_get_crl_paths()
• nc_accept_callhome()

Cleanup

These options and the schema searchpath are stored in dynamically allocated memory. They are freed as a part of destroying the client.