src/libnetconf.h

/**
 * \file libnetconf.h
 * \author Radek Krejci <rkrejci@cesnet.cz>
 * \author Michal Vasko <mvasko@cesnet.cz>
 * \brief libnetconf2 main internal header.
 *
 * Copyright (c) 2015 CESNET, z.s.p.o.
 *
 * This source code is licensed under BSD 3-Clause License (the "License").
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://opensource.org/licenses/BSD-3-Clause
 */

#ifndef NC_LIBNETCONF_H_
#define NC_LIBNETCONF_H_

#include "config.h"
#include "netconf.h"
#include "log_p.h"
#include "session_p.h"
#include "messages_p.h"

/* Tests whether string is empty or non-empty. */
#define strisempty(str) ((str)[0] == '\0')
#define strnonempty(str) ((str)[0] != '\0')

/**
 * @mainpage About
 *
 * libnetconf2 is a NETCONF library in C handling NETCONF authentication and all NETCONF
 * RPC communication both server and client-side. NETCONF datastore and session management is not a part of this library,
 * but it helps a lot with the sessions.
 *
 * @section about-features Main Features
 *
 * - Creating SSH (using libssh) or TLS (using OpenSSL) authenticated NETCONF sessions.
 * - Creating NETCONF sessions with a pre-established transport protocol
 *   (using this mechanism the communication can be tunneled through sshd(8), for instance).
 * - Creating NETCONF Call Home sessions.
 * - Creating, sending, receiving, and replying to RPCs.
 * - Receiving notifications.
 *
 * - \todo Creating and sending notifications.
 *
 * @section about-license License
 *
 * Copyright (c) 2015-2016 CESNET, z.s.p.o.
 *
 * (The BSD 3-Clause License)
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name of the Company nor the names of its contributors
 *    may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 */

/**
 * @page howto How To ...
 *
 * - @subpage howtoinit
 * - @subpage howtoclient
 * - @subpage howtoserver
 * - @subpage howtoclientcomm
 * - @subpage howtoservercomm
 */

/**
 * @page howtoinit Init and Thread-safety Information
 *
 * Before working with the library, it must be initialized using nc_init().
 * Based on how the library was compiled, also libssh and/or libssh/libcrypto
 * are initialized (for multi-threaded use) too. It is advised to compile
 * libnetconf2, for instance, with TLS support even if you do not want to
 * use lnc2 TLS functions, but only use libssl/libcrypto functions in your
 * application. You can then use libnetconf2 cleanup function and do not
 * trouble yourself with the cleanup. If you create
 * only sessions with pre-established transport protocol (_inout functions),
 * you do not need to call any init function at all, but there may be reachable
 * dynamic memory after your application exits.
 *
 * To prevent any reachable memory at the end of your application, there
 * are complementary destroy functions available. If your application is
 * multi-threaded, call the destroy functions in the last thread, after all
 * the other threads have ended. In every other thread you should call
 * nc_thread_destroy() just before it exits.
 *
 * If libnetconf2 is used in accordance with this information, there should
 * not be memory leaks of any kind at program exit. For thread-safety details
 * of libssh, libssl, and libcrypto please refer to the corresponding project
 * documentation. libnetconf2 thread-safety information is below.
 *
 * Client is NOT thread-safe and there is no access control in the client
 * functions at all. Server is MOSTLY thread-safe meaning you can set all the
 * options simultaneously while listening for or accepting new sessions or
 * polling the existing ones. It should even be safe to poll one session in
 * several threads, but it is definitely discouraged. Generally, servers can
 * use more threads without any problems as long as they keep their workflow sane
 * (behavior such as freeing sessions only after no thread uses them or similar).
 *
 * Functions List
 * --------------
 *
 * Available in both __nc_client.h__ and __nc_server.h__.
 *
 * - nc_init()
 * - nc_destroy()
 * - nc_thread_destroy()
 */

/**
 * @page howtoclient Client sessions
 *
 * 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
 * ===
 *
 * It is mostly required to set any SSH options and then simply connect to
 * a NETCONF server. 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.
 *
 * Afterwards, there are 2 functions to use for a new server connection
 * and an additional one for creating a new SSH channel on an existing
 * NETCONF session. The libssh variant enables to customize the SSH session
 * in every way the libssh allows, although that should not normally be needed.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_client_ssh_set_auth_hostkey_check_clb()
 * - nc_client_ssh_set_auth_password_clb()
 * - nc_client_ssh_set_auth_interactive_clb()
 * - nc_client_ssh_set_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
 * ===
 *
 * With TLS authentication, is is mandatory to set the client certificate
 * with a private key and additional trusted certificates and revocation lists.
 *
 * Then there are again 2 functions for connecting, the libssl variant enables
 * to customize the TLS session in every way the 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
 * ==
 *
 * If you authenticated the connection using some tunneling software, you
 * can pass its file descriptors to libnetconf2, which will continue to
 * establish a full NETCONF session.
 *
 * Funtions List
 * -------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_connect_inout()
 *
 *
 * 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. Then connections can be
 * accepted.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_client_ssh_ch_set_auth_hostkey_check_clb()
 * - 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. To free it, destroy the client, it cleans up all
 * the options
 *
 * Functions List
 * --------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_client_destroy()
 */

/**
 * @page howtoserver Server sessions
 *
 * Init
 * ====
 *
 * Server has its own initialization function. With it, you set the
 * server context, which determines what modules it supports and what
 * capabilities to advertise. Few capabilities that cannot be learnt
 * from the context are set with separate functions. So are several
 * general options.
 *
 * Context does not only determine server modules, but its overall
 * functionality as well. For every RPC the server should support,
 * an nc_rpc_clb callback should be set on that node in the context.
 * Server then calls these as appropriate [during poll](@ref howtoservercomm).
 *
 * Server options can be only set, there are no getters.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_server_init()
 * - nc_server_set_capab_withdefaults()
 * - nc_server_set_capab_interleave()
 * - nc_server_set_hello_timeout()
 * - nc_server_set_idle_timeout()
 *
 *
 * SSH
 * ===
 *
 * To be able to accept SSH connections, an endpoint must be added
 * and its options set.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_server_ssh_add_endpt_listen()
 * - nc_server_ssh_endpt_set_address()
 * - nc_server_ssh_endpt_set_port()
 * - nc_server_ssh_del_endpt()
 *
 * - nc_server_ssh_endpt_set_hostkey()
 * - nc_server_ssh_endpt_set_banner()
 * - nc_server_ssh_endpt_set_auth_methods()
 * - nc_server_ssh_endpt_set_auth_attempts()
 * - nc_server_ssh_endpt_set_auth_timeout()
 * - nc_server_ssh_endpt_add_authkey()
 * - nc_server_ssh_endpt_del_authkey()
 *
 *
 * TLS
 * ===
 *
 * TLS requires at least one endpoint too, but its options differ
 * significantly from the SSH ones, especially in the cert-to-name
 * options that TLS uses to derive usernames from client certificates.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_server_tls_add_endpt_listen()
 * - nc_server_tls_endpt_set_address()
 * - nc_server_tls_endpt_set_port()
 * - nc_server_tls_del_endpt()
 *
 * - nc_server_tls_endpt_set_cert()
 * - nc_server_tls_endpt_set_cert_path()
 * - nc_server_tls_endpt_set_key()
 * - nc_server_tls_endpt_set_key_path()
 * - nc_server_tls_endpt_add_trusted_cert()
 * - nc_server_tls_endpt_add_trusted_cert_path()
 * - nc_server_tls_endpt_set_trusted_ca_paths()
 * - nc_server_tls_endpt_clear_certs()
 * - nc_server_tls_endpt_set_crl_paths()
 * - nc_server_tls_endpt_clear_crls()
 * - nc_server_tls_endpt_add_ctn()
 * - nc_server_tls_endpt_del_ctn()
 *
 * FD
 * ==
 *
 * If you used a tunneling software, which does its own authentication,
 * you can accept a NETCONF session on its file descriptors.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_accept_inout()
 *
 *
 * Call Home
 * =========
 *
 * Call Home does not work with endpoints like standard sessions.
 * The options must be reset manually after another Call Home session
 * (with different options than the previous one) is to be established.
 * Also, monitoring of these sessions is up to the application.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_connect_callhome_ssh()
 * - nc_connect_callhome_tls()
 *
 * - nc_server_ssh_ch_set_hostkey()
 * - nc_server_ssh_ch_set_banner()
 * - nc_server_ssh_ch_set_auth_methods()
 * - nc_server_ssh_ch_set_auth_attempts()
 * - nc_server_ssh_ch_set_auth_timeout()
 * - nc_server_ssh_ch_add_authkey()
 * - nc_server_ssh_ch_del_authkey()
 * - nc_server_ssh_ch_clear_opts()
 *
 * - nc_server_tls_ch_set_cert()
 * - nc_server_tls_ch_set_cert_path()
 * - nc_server_tls_ch_set_key()
 * - nc_server_tls_ch_set_key_path()
 * - nc_server_tls_ch_add_trusted_cert()
 * - nc_server_tls_ch_add_trusted_cert_path()
 * - nc_server_tls_ch_set_trusted_ca_paths()
 * - nc_server_tls_ch_clear_certs()
 * - nc_server_tls_ch_set_crl_paths()
 * - nc_server_tls_ch_clear_crls()
 * - nc_server_tls_ch_add_ctn()
 * - nc_server_tls_ch_del_ctn()
 * - nc_server_tls_ch_clear_opts()
 *
 *
 * Connecting And Cleanup
 * ======================
 *
 * When accepting connections, all the endpoints are examined
 * and the first with a pending connection is used. To remove all
 * the endpoints and free any used dynamic memory, destroy the server.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_server.h__.
 *
 * - nc_accept()
 *
 * - nc_server_destroy()
 */

/**
 * @page howtoclientcomm Client communication
 *
 * To send RPCs on a session, you simply create an RPC, send it,
 * and then wait for a reply. If you are subscribed, there are 2 ways
 * of receiving notifications. Either you wait for them the same way
 * as for standard replies or you create a dispatcher that asynchronously
 * (in a separate thread) reads notifications and passes them to your
 * callback.
 *
 * Functions List
 * --------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_rpc_generic()
 * - nc_rpc_generic_xml()
 * - nc_rpc_getconfig()
 * - nc_rpc_edit()
 * - nc_rpc_copy()
 * - nc_rpc_delete()
 * - nc_rpc_lock()
 * - nc_rpc_unlock()
 * - nc_rpc_get()
 * - nc_rpc_kill()
 * - nc_rpc_commit()
 * - nc_rpc_discard()
 * - nc_rpc_cancel()
 * - nc_rpc_validate()
 * - nc_rpc_getschema()
 * - nc_rpc_subscribe()
 *
 * - nc_send_rpc()
 * - nc_recv_reply()
 * - nc_recv_notif()
 * - nc_recv_notif_dispatch()
 */

/**
 * @page howtoservercomm Server communication
 *
 * Once at least one session is established, an nc_pollsession structure
 * should be created, filled with the session and polled. Based on
 * the return value from the poll further actions can be taken. More
 * sessions can be polled at the same time. Any requests received on
 * the sessions are [handled internally](@ref howtoserver).
 *
 * Functions List
 * --------------
 *
 * Available in __nc_client.h__.
 *
 * - nc_ps_new()
 * - nc_ps_add_session()
 * - nc_ps_del_session()
 * - nc_ps_free()
 *
 * - nc_ps_poll()
 * - nc_ps_clear()
 * - nc_ps_accept_ssh_channel()
 */

#endif /* NC_LIBNETCONF_H_ */