src/session_client.h - github/CESNET/libnetconf2 - Gitiles

 /**
  * \file session_client.h
  * \author Michal Vasko <mvasko@cesnet.cz>
  * \brief libnetconf2 session client manipulation
  *
  * 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_SESSION_CLIENT_H_
 #define NC_SESSION_CLIENT_H_

 #include <libyang/libyang.h>

 #ifdef NC_ENABLED_SSH

 #include <libssh/libssh.h>

 #endif

 #ifdef NC_ENABLED_TLS

 #include <openssl/ssl.h>

 #endif

 #include "session.h"
 #include "netconf.h"
 #include "messages_client.h"

 /**
  * @brief Set location where libnetconf tries to search for YANG/YIN schemas.
  *
  * The location is searched when connecting to a NETCONF server and building
  * YANG context for further processing of the NETCONF messages and data.
  *
  * @param[in] path Directory where to search for YANG/YIN schemas.
  * @return 0 on success, 1 on (memory allocation) failure.
  */
 int nc_client_set_schema_searchpath(const char *path);

 /**
  * @brief Get schema searchpath that was set by nc_client_set_schema_searchpath().
  *
  * @return Schema searchpath directory, NULL if not set.
  */
 const char *nc_client_get_schema_searchpath(void);

 /**
  * @brief Initialize libssh and/or libssl/libcrypto for use in the client.
  */
 void nc_client_init(void);

 /**
  * @brief Destroy all libssh and/or libssl/libcrypto dynamic memory and
  *        the client options, for both SSH and TLS, and for Call Home too.
  */
 void nc_client_destroy(void);

 /**
  * @brief Connect to the NETCONF server via proviaded input/output file descriptors.
  *
  * Transport layer is supposed to be already set. Function do not cover authentication
  * or any other manipulation with the transport layer, it only establish NETCONF session
  * by sending and processing NETCONF \<hello\> messages.
  *
  * @param[in] fdin Input file descriptor for reading (clear) data from NETCONF server.
  * @param[in] fdout Output file descriptor for writing (clear) data for NETCONF server.
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL in case of error.
  */
 struct nc_session *nc_connect_inout(int fdin, int fdout, struct ly_ctx *ctx);

 #ifdef NC_ENABLED_SSH

 /**
  * @brief Set SSH authentication hostkey check (knownhosts) callback.
  *
  * @param[in] auth_hostkey_check Function to call, returns 0 on success, non-zero in error.
  *                               If NULL, the default callback is set.
  */
 void nc_client_ssh_set_auth_hostkey_check_clb(int (*auth_hostkey_check)(const char *hostname, ssh_session session));

 /**
  * @brief Set SSH password authentication callback.
  *
  * @param[in] auth_password Function to call, returns the password for username\@hostname.
  *                          If NULL, the default callback is set.
  */
 void nc_client_ssh_set_auth_password_clb(char *(*auth_password)(const char *username, const char *hostname));

 /**
  * @brief Set SSH interactive authentication callback.
  *
  * @param[in] auth_interactive Function to call for every question, returns the answer for
  *                             authentication name with instruction and echoing prompt.
  *                             If NULL, the default callback is set.
  */
 void nc_client_ssh_set_auth_interactive_clb(char *(*auth_interactive)(const char *auth_name, const char *instruction,
                                                                       const char *prompt, int echo));

 /**
  * @brief Set SSH publickey authentication encrypted private key passphrase callback.
  *
  * @param[in] auth_privkey_passphrase Function to call for every question, returns
  *                                    the passphrase for the specific private key.
  */
 void nc_client_ssh_set_auth_privkey_passphrase_clb(char *(*auth_privkey_passphrase)(const char *privkey_path));

 /**
  * @brief Add an SSH public and private key pair to be used for client authentication.
  *
  * Private key can be encrypted, the passphrase will be asked for before using it.
  *
  * @param[in] pub_key Path to the public key.
  * @param[in] priv_key Path to the private key.
  * @return 0 on success, -1 on error.
  */
 int nc_client_ssh_add_keypair(const char *pub_key, const char *priv_key);

 /**
  * @brief Remove an SSH public and private key pair that was used for client authentication.
  *
  * @param[in] idx Index of the keypair starting with 0.
  * @return 0 on success, -1 on error.
  */
 int nc_client_ssh_del_keypair(int idx);

 /**
  * @brief Get the number of public an private key pairs set to be used for client authentication.
  *
  * @return Keypair count.
  */
 int nc_client_ssh_get_keypair_count(void);

 /**
  * @brief Get a specific keypair set to be used for client authentication.
  *
  * @param[in] idx Index of the specific keypair.
  * @param[out] pub_key Path to the public key.
  * @param[out] priv_key Path to the private key.
  * @return 0 on success, -1 on error.
  */
 int nc_client_ssh_get_keypair(int idx, const char **pub_key, const char **priv_key);

 /**
  * @brief Set SSH authentication method preference.
  *
  * @param[in] auth_type Authentication method to modify the prefrence of.
  * @param[in] pref Preference of \p auth_type. Negative values disable the method.
  */
 void nc_client_ssh_set_auth_pref(NC_SSH_AUTH_TYPE auth_type, int16_t pref);

 /**
  * @brief Get SSH authentication method preference.
  *
  * @param[in] auth_type Authentication method to retrieve the prefrence of.
  * @return Preference of the \p auth_type.
  */
 int16_t nc_client_ssh_get_auth_pref(NC_SSH_AUTH_TYPE auth_type);

 /**
  * @brief Set client SSH username used for authentication.
  *
  * @param[in] username Username to use.
  * @return 0 on success, -1 on error.
  */
 int nc_client_ssh_set_username(const char *username);

 /**
  * @brief Get client SSH username used for authentication.
  *
  * @return Username used.
  */
 const char *nc_client_ssh_get_username(void);

 /**
  * @brief Connect to the NETCONF server using SSH transport (via libssh).
  *
  * SSH session is created with default options. If the caller needs to use specific SSH session properties,
  * they are supposed to use nc_connect_libssh().
  *
  * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
  *                 'localhost' is used by default if NULL is specified.
  * @param[in] port Port number of the target server. Default value 830 is used if 0 is specified.
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_ssh(const char *host, uint16_t port, struct ly_ctx *ctx);

 /**
  * @brief Connect to the NETCONF server using the provided SSH (libssh) session.
  *
  * SSH session can have any options set, they will not be modified. If no options were set,
  * host 'localhost', port 22, and the username detected from the EUID is used. If socket is
  * set and connected only the host and the username must be set/is detected. Or the \p ssh_session
  * can already be authenticated in which case it is used directly.
  *
  * @param[in] ssh_session libssh structure representing SSH session object. After passing it
  *                        to libnetconf2 this way, it is fully managed by it (including freeing!).
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_libssh(ssh_session ssh_session, struct ly_ctx *ctx);

 /**
  * @brief Create another NETCONF session on existing SSH session using separated SSH channel.
  *
  * @param[in] session Existing NETCONF session. The session has to be created on SSH transport layer using libssh -
  *                    it has to be created by nc_connect_ssh(), nc_connect_libssh() or nc_connect_ssh_channel().
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_ssh_channel(struct nc_session *session, struct ly_ctx *ctx);

 #endif /* NC_ENABLED_SSH */

 #ifdef NC_ENABLED_TLS

 /**
  * @brief Set client authentication identity - a certificate and a private key.
  *
  * @param[in] client_cert Path to the file containing the client certificate.
  * @param[in] client_key Path to the file containing the private key for the \p client_cert.
  *                       If NULL, key is expected to be stored with \p client_cert.
  * @return 0 on success, -1 on error.
  */
 int nc_client_tls_set_cert_key_paths(const char *client_cert, const char *client_key);

 /**
  * @brief Get client authentication identity - a certificate and a private key.
  *
  * @param[out] client_cert Path to the file containing the client certificate. Can be NULL.
  * @param[out] client_key Path to the file containing the private key for the \p client_cert. Can be NULL.
  */
 void nc_client_tls_get_cert_key_paths(const char **client_cert, const char **client_key);

 /**
  * @brief Set client trusted CA certificates paths.
  *
  * @param[in] ca_file Location of the CA certificate file used to verify server certificates.
  *                    For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
  * @param[in] ca_dir Location of the CA certificates directory used to verify the server certificates.
  *                   For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
  * @return 0 on success, -1 on error.
  */
 int nc_client_tls_set_trusted_ca_paths(const char *ca_file, const char *ca_dir);

 /**
  * @brief Get client trusted CA certificates paths.
  *
  * @param[out] ca_file Location of the CA certificate file used to verify server certificates.
  *                     Can be NULL.
  * @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates.
  *                    Can be NULL.
  */
 void nc_client_tls_get_trusted_ca_paths(const char **ca_file, const char **ca_dir);

 /**
  * @brief Set client Certificate Revocation List paths.
  *
  * @param[in] crl_file Location of the CRL certificate file used to check for revocated certificates.
  * @param[in] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
  * @return 0 on success, -1 on error.
  */
 int nc_client_tls_set_crl_paths(const char *crl_file, const char *crl_dir);

 /**
  * @brief Get client Certificate Revocation List paths.
  *
  * @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates.
  * @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
  */
 void nc_client_tls_get_crl_paths(const char **crl_file, const char **crl_dir);

 /**
  * @brief Connect to the NETCONF server using TLS transport (via libssl)
  *
  * TLS session is created with the certificates set using nc_client_tls_* functions, which must be called beforehand!
  * If the caller needs to use specific TLS session properties, they are supposed to use nc_connect_libssl().
  *
  * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
  *                 'localhost' is used by default if NULL is specified.
  * @param[in] port Port number of the target server. Default value 6513 is used if 0 is specified.
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_tls(const char *host, uint16_t port, struct ly_ctx *ctx);

 /**
  * @brief Connect to the NETCONF server using the provided TLS (libssl) session.
  *
  * The TLS session supplied is expected to be fully connected and authenticated!
  *
  * @param[in] tls libssl structure representing the TLS session object.
  * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
  *                (ignoring what is actually supported by the server side). If not set,
  *                YANG context is created for the session using \<get-schema\> (if supported
  *                by the server side) or/and by searching for YANG schemas in the searchpath
  *                (see nc_client_schema_searchpath()). In every case except not providing context
  *                to connect to a server supporting \<get-schema\> it is possible that
  *                the session context will not include all the models supported by the server.
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_libssl(SSL *tls, struct ly_ctx *ctx);

 #endif /* NC_ENABLED_TLS */

 /**
  * @brief Get session capabilities.
  *
  * @param[in] session Session to get the information from.
  * @return Session capabilities.
  */
 const char **nc_session_get_cpblts(const struct nc_session *session);

 /**
  * @brief Check capability presence in a session.
  *
  * @param[in] session Session to check.
  * @param[in] capab Capability to look for, capability with any additional suffix will match.
  * @return Matching capability, NULL if none found.
  */
 const char *nc_session_cpblt(const struct nc_session *session, const char *capab);

 /**
  * @brief Check whether the session has a notification thread running.
  *
  * @param[in] session Session to check.
  * @return 1 if notfication thread is running, 0 otherwise.
  */
 int nc_session_ntf_thread_running(const struct nc_session *session);

 /**
  * @brief Receive NETCONF RPC reply.
  *
  * Be careful, normally there is a whole RPC reply (output) of an RPC in the \p reply.
  * However, if a reply to \<get\> or \<get-config\> RPC is received, the \p reply is
  * actually the configuration (with either state data or not). This means, for example,
  * that the reply data in these cases should not be validated with #LYD_OPT_RPCREPLY,
  * but #LYD_OPT_GET and #LYD_OPT_GETCONFIG, respectively.
  *
  * @param[in] session NETCONF session from which the function gets data. It must be the
  *            client side session object.
  * @param[in] rpc Original RPC this should be the reply to.
  * @param[in] msgid Expected message ID of the reply.
  * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
  *            waiting and 0 for immediate return if data are not available on the wire.
  * @param[in] parseroptions libyang parseroptions flags, do not set the data type, it is set
  *            internally. LYD_OPT_DESTRUCT and LYD_OPT_NOSIBLINGS is ignored.
  * @param[out] reply Resulting object of NETCONF RPC reply.
  * @return #NC_MSG_REPLY for success,
  *         #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
  *         #NC_MSG_ERROR if reading has failed,
  *         #NC_MSG_NOTIF if a notification was read instead (call this function again to get the reply), and
  *         #NC_MSG_REPLY_ERR_MSGID if a reply with missing or wrong message-id was received.
  */
 NC_MSG_TYPE nc_recv_reply(struct nc_session *session, struct nc_rpc *rpc, uint64_t msgid, int timeout,
                           int parseroptions, struct nc_reply **reply);

 /**
  * @brief Receive NETCONF Notification.
  *
  * @param[in] session NETCONF session from which the function gets data. It must be the
  *            client side session object.
  * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
  *            waiting and 0 for immediate return if data are not available on the wire.
  * @param[out] notif Resulting object of NETCONF Notification.
  * @return #NC_MSG_NOTIF for success,
  *         #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
  *         #NC_MSG_ERROR if reading has failed, and
  *         #NC_MSG_REPLY if a reply was read instead (call this function again to get a notification).
  */
 NC_MSG_TYPE nc_recv_notif(struct nc_session* session, int timeout, struct nc_notif **notif);

 /**
  * @brief Receive NETCONF Notifications in a separate thread until the session is terminated
  *        or \<notificationComplete\> is received.
  *
  * @param[in] session Netconf session to read notifications from.
  * @param[in] notif_clb Function that is called for every received notification (including
  *            \<notificationComplete\>). Parameters are the session the notification was received on
  *            and the notification itself.
  * @return 0 if the thread was successfully created, -1 on error.
  */
 int nc_recv_notif_dispatch(struct nc_session *session,
                            void (*notif_clb)(struct nc_session *session, const struct nc_notif *notif));

 /**
  * @brief Send NETCONF RPC message via the session.
  *
  * @param[in] session NETCONF session where the RPC will be written.
  * @param[in] rpc NETCOFN RPC object to send via specified session. Object can be created by
  *            nc_rpc_lock(), nc_rpc_unlock() and nc_rpc_generic() functions.
  * @param[in] timeout Timeout for writing in milliseconds. Use negative value for infinite
  *            waiting and 0 for return if data cannot be sent immediately.
  * @param[out] msgid If RPC was successfully sent, this is it's message ID.
  * @return #NC_MSG_RPC on success,
  *         #NC_MSG_WOULDBLOCK in case of a busy session, and
  *         #NC_MSG_ERROR on error.
  */
 NC_MSG_TYPE nc_send_rpc(struct nc_session *session, struct nc_rpc *rpc, int timeout, uint64_t *msgid);

 #endif /* NC_SESSION_CLIENT_H_ */
	/**
	* \file session_client.h
	* \author Michal Vasko <mvasko@cesnet.cz>
	* \brief libnetconf2 session client manipulation
	*
	* 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_SESSION_CLIENT_H_
	#define NC_SESSION_CLIENT_H_

	#include <libyang/libyang.h>

	#ifdef NC_ENABLED_SSH

	#include <libssh/libssh.h>

	#endif

	#ifdef NC_ENABLED_TLS

	#include <openssl/ssl.h>

	#endif

	#include "session.h"
	#include "netconf.h"
	#include "messages_client.h"

	/**
	* @brief Set location where libnetconf tries to search for YANG/YIN schemas.
	*
	* The location is searched when connecting to a NETCONF server and building
	* YANG context for further processing of the NETCONF messages and data.
	*
	* @param[in] path Directory where to search for YANG/YIN schemas.
	* @return 0 on success, 1 on (memory allocation) failure.
	*/
	int nc_client_set_schema_searchpath(const char *path);

	/**
	* @brief Get schema searchpath that was set by nc_client_set_schema_searchpath().
	*
	* @return Schema searchpath directory, NULL if not set.
	*/
	const char *nc_client_get_schema_searchpath(void);

	/**
	* @brief Initialize libssh and/or libssl/libcrypto for use in the client.
	*/
	void nc_client_init(void);

	/**
	* @brief Destroy all libssh and/or libssl/libcrypto dynamic memory and
	* the client options, for both SSH and TLS, and for Call Home too.
	*/
	void nc_client_destroy(void);

	/**
	* @brief Connect to the NETCONF server via proviaded input/output file descriptors.
	*
	* Transport layer is supposed to be already set. Function do not cover authentication
	* or any other manipulation with the transport layer, it only establish NETCONF session
	* by sending and processing NETCONF \<hello\> messages.
	*
	* @param[in] fdin Input file descriptor for reading (clear) data from NETCONF server.
	* @param[in] fdout Output file descriptor for writing (clear) data for NETCONF server.
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL in case of error.
	*/
	struct nc_session nc_connect_inout(int fdin, int fdout, struct ly_ctx ctx);

	#ifdef NC_ENABLED_SSH

	/**
	* @brief Set SSH authentication hostkey check (knownhosts) callback.
	*
	* @param[in] auth_hostkey_check Function to call, returns 0 on success, non-zero in error.
	* If NULL, the default callback is set.
	*/
	void nc_client_ssh_set_auth_hostkey_check_clb(int (auth_hostkey_check)(const char hostname, ssh_session session));

	/**
	* @brief Set SSH password authentication callback.
	*
	* @param[in] auth_password Function to call, returns the password for username\@hostname.
	* If NULL, the default callback is set.
	*/
	void nc_client_ssh_set_auth_password_clb(char (auth_password)(const char username, const char hostname));

	/**
	* @brief Set SSH interactive authentication callback.
	*
	* @param[in] auth_interactive Function to call for every question, returns the answer for
	* authentication name with instruction and echoing prompt.
	* If NULL, the default callback is set.
	*/
	void nc_client_ssh_set_auth_interactive_clb(char (auth_interactive)(const char auth_name, const char instruction,
	const char *prompt, int echo));

	/**
	* @brief Set SSH publickey authentication encrypted private key passphrase callback.
	*
	* @param[in] auth_privkey_passphrase Function to call for every question, returns
	* the passphrase for the specific private key.
	*/
	void nc_client_ssh_set_auth_privkey_passphrase_clb(char (auth_privkey_passphrase)(const char *privkey_path));

	/**
	* @brief Add an SSH public and private key pair to be used for client authentication.
	*
	* Private key can be encrypted, the passphrase will be asked for before using it.
	*
	* @param[in] pub_key Path to the public key.
	* @param[in] priv_key Path to the private key.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_ssh_add_keypair(const char pub_key, const char priv_key);

	/**
	* @brief Remove an SSH public and private key pair that was used for client authentication.
	*
	* @param[in] idx Index of the keypair starting with 0.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_ssh_del_keypair(int idx);

	/**
	* @brief Get the number of public an private key pairs set to be used for client authentication.
	*
	* @return Keypair count.
	*/
	int nc_client_ssh_get_keypair_count(void);

	/**
	* @brief Get a specific keypair set to be used for client authentication.
	*
	* @param[in] idx Index of the specific keypair.
	* @param[out] pub_key Path to the public key.
	* @param[out] priv_key Path to the private key.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_ssh_get_keypair(int idx, const char pub_key, const char priv_key);

	/**
	* @brief Set SSH authentication method preference.
	*
	* @param[in] auth_type Authentication method to modify the prefrence of.
	* @param[in] pref Preference of \p auth_type. Negative values disable the method.
	*/
	void nc_client_ssh_set_auth_pref(NC_SSH_AUTH_TYPE auth_type, int16_t pref);

	/**
	* @brief Get SSH authentication method preference.
	*
	* @param[in] auth_type Authentication method to retrieve the prefrence of.
	* @return Preference of the \p auth_type.
	*/
	int16_t nc_client_ssh_get_auth_pref(NC_SSH_AUTH_TYPE auth_type);

	/**
	* @brief Set client SSH username used for authentication.
	*
	* @param[in] username Username to use.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_ssh_set_username(const char *username);

	/**
	* @brief Get client SSH username used for authentication.
	*
	* @return Username used.
	*/
	const char *nc_client_ssh_get_username(void);

	/**
	* @brief Connect to the NETCONF server using SSH transport (via libssh).
	*
	* SSH session is created with default options. If the caller needs to use specific SSH session properties,
	* they are supposed to use nc_connect_libssh().
	*
	* @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
	* 'localhost' is used by default if NULL is specified.
	* @param[in] port Port number of the target server. Default value 830 is used if 0 is specified.
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL on error.
	*/
	struct nc_session nc_connect_ssh(const char host, uint16_t port, struct ly_ctx *ctx);

	/**
	* @brief Connect to the NETCONF server using the provided SSH (libssh) session.
	*
	* SSH session can have any options set, they will not be modified. If no options were set,
	* host 'localhost', port 22, and the username detected from the EUID is used. If socket is
	* set and connected only the host and the username must be set/is detected. Or the \p ssh_session
	* can already be authenticated in which case it is used directly.
	*
	* @param[in] ssh_session libssh structure representing SSH session object. After passing it
	* to libnetconf2 this way, it is fully managed by it (including freeing!).
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL on error.
	*/
	struct nc_session nc_connect_libssh(ssh_session ssh_session, struct ly_ctx ctx);

	/**
	* @brief Create another NETCONF session on existing SSH session using separated SSH channel.
	*
	* @param[in] session Existing NETCONF session. The session has to be created on SSH transport layer using libssh -
	* it has to be created by nc_connect_ssh(), nc_connect_libssh() or nc_connect_ssh_channel().
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL on error.
	*/
	struct nc_session nc_connect_ssh_channel(struct nc_session session, struct ly_ctx *ctx);

	#endif /* NC_ENABLED_SSH */

	#ifdef NC_ENABLED_TLS

	/**
	* @brief Set client authentication identity - a certificate and a private key.
	*
	* @param[in] client_cert Path to the file containing the client certificate.
	* @param[in] client_key Path to the file containing the private key for the \p client_cert.
	* If NULL, key is expected to be stored with \p client_cert.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_tls_set_cert_key_paths(const char client_cert, const char client_key);

	/**
	* @brief Get client authentication identity - a certificate and a private key.
	*
	* @param[out] client_cert Path to the file containing the client certificate. Can be NULL.
	* @param[out] client_key Path to the file containing the private key for the \p client_cert. Can be NULL.
	*/
	void nc_client_tls_get_cert_key_paths(const char client_cert, const char client_key);

	/**
	* @brief Set client trusted CA certificates paths.
	*
	* @param[in] ca_file Location of the CA certificate file used to verify server certificates.
	* For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
	* @param[in] ca_dir Location of the CA certificates directory used to verify the server certificates.
	* For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_tls_set_trusted_ca_paths(const char ca_file, const char ca_dir);

	/**
	* @brief Get client trusted CA certificates paths.
	*
	* @param[out] ca_file Location of the CA certificate file used to verify server certificates.
	* Can be NULL.
	* @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates.
	* Can be NULL.
	*/
	void nc_client_tls_get_trusted_ca_paths(const char ca_file, const char ca_dir);

	/**
	* @brief Set client Certificate Revocation List paths.
	*
	* @param[in] crl_file Location of the CRL certificate file used to check for revocated certificates.
	* @param[in] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
	* @return 0 on success, -1 on error.
	*/
	int nc_client_tls_set_crl_paths(const char crl_file, const char crl_dir);

	/**
	* @brief Get client Certificate Revocation List paths.
	*
	* @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates.
	* @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
	*/
	void nc_client_tls_get_crl_paths(const char crl_file, const char crl_dir);

	/**
	* @brief Connect to the NETCONF server using TLS transport (via libssl)
	*
	* TLS session is created with the certificates set using nc_client_tls_* functions, which must be called beforehand!
	* If the caller needs to use specific TLS session properties, they are supposed to use nc_connect_libssl().
	*
	* @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
	* 'localhost' is used by default if NULL is specified.
	* @param[in] port Port number of the target server. Default value 6513 is used if 0 is specified.
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL on error.
	*/
	struct nc_session nc_connect_tls(const char host, uint16_t port, struct ly_ctx *ctx);

	/**
	* @brief Connect to the NETCONF server using the provided TLS (libssl) session.
	*
	* The TLS session supplied is expected to be fully connected and authenticated!
	*
	* @param[in] tls libssl structure representing the TLS session object.
	* @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
	* (ignoring what is actually supported by the server side). If not set,
	* YANG context is created for the session using \<get-schema\> (if supported
	* by the server side) or/and by searching for YANG schemas in the searchpath
	* (see nc_client_schema_searchpath()). In every case except not providing context
	* to connect to a server supporting \<get-schema\> it is possible that
	* the session context will not include all the models supported by the server.
	* @return Created NETCONF session object or NULL on error.
	*/
	struct nc_session nc_connect_libssl(SSL tls, struct ly_ctx *ctx);

	#endif /* NC_ENABLED_TLS */

	/**
	* @brief Get session capabilities.
	*
	* @param[in] session Session to get the information from.
	* @return Session capabilities.
	*/
	const char *nc_session_get_cpblts(const struct nc_session session);

	/**
	* @brief Check capability presence in a session.
	*
	* @param[in] session Session to check.
	* @param[in] capab Capability to look for, capability with any additional suffix will match.
	* @return Matching capability, NULL if none found.
	*/
	const char nc_session_cpblt(const struct nc_session session, const char *capab);

	/**
	* @brief Check whether the session has a notification thread running.
	*
	* @param[in] session Session to check.
	* @return 1 if notfication thread is running, 0 otherwise.
	*/
	int nc_session_ntf_thread_running(const struct nc_session *session);

	/**
	* @brief Receive NETCONF RPC reply.
	*
	* Be careful, normally there is a whole RPC reply (output) of an RPC in the \p reply.
	* However, if a reply to \<get\> or \<get-config\> RPC is received, the \p reply is
	* actually the configuration (with either state data or not). This means, for example,
	* that the reply data in these cases should not be validated with #LYD_OPT_RPCREPLY,
	* but #LYD_OPT_GET and #LYD_OPT_GETCONFIG, respectively.
	*
	* @param[in] session NETCONF session from which the function gets data. It must be the
	* client side session object.
	* @param[in] rpc Original RPC this should be the reply to.
	* @param[in] msgid Expected message ID of the reply.
	* @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
	* waiting and 0 for immediate return if data are not available on the wire.
	* @param[in] parseroptions libyang parseroptions flags, do not set the data type, it is set
	* internally. LYD_OPT_DESTRUCT and LYD_OPT_NOSIBLINGS is ignored.
	* @param[out] reply Resulting object of NETCONF RPC reply.
	* @return #NC_MSG_REPLY for success,
	* #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
	* #NC_MSG_ERROR if reading has failed,
	* #NC_MSG_NOTIF if a notification was read instead (call this function again to get the reply), and
	* #NC_MSG_REPLY_ERR_MSGID if a reply with missing or wrong message-id was received.
	*/
	NC_MSG_TYPE nc_recv_reply(struct nc_session session, struct nc_rpc rpc, uint64_t msgid, int timeout,
	int parseroptions, struct nc_reply **reply);

	/**
	* @brief Receive NETCONF Notification.
	*
	* @param[in] session NETCONF session from which the function gets data. It must be the
	* client side session object.
	* @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
	* waiting and 0 for immediate return if data are not available on the wire.
	* @param[out] notif Resulting object of NETCONF Notification.
	* @return #NC_MSG_NOTIF for success,
	* #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
	* #NC_MSG_ERROR if reading has failed, and
	* #NC_MSG_REPLY if a reply was read instead (call this function again to get a notification).
	*/
	NC_MSG_TYPE nc_recv_notif(struct nc_session* session, int timeout, struct nc_notif **notif);

	/**
	* @brief Receive NETCONF Notifications in a separate thread until the session is terminated
	* or \<notificationComplete\> is received.
	*
	* @param[in] session Netconf session to read notifications from.
	* @param[in] notif_clb Function that is called for every received notification (including
	* \<notificationComplete\>). Parameters are the session the notification was received on
	* and the notification itself.
	* @return 0 if the thread was successfully created, -1 on error.
	*/
	int nc_recv_notif_dispatch(struct nc_session *session,
	void (notif_clb)(struct nc_session session, const struct nc_notif *notif));

	/**
	* @brief Send NETCONF RPC message via the session.
	*
	* @param[in] session NETCONF session where the RPC will be written.
	* @param[in] rpc NETCOFN RPC object to send via specified session. Object can be created by
	* nc_rpc_lock(), nc_rpc_unlock() and nc_rpc_generic() functions.
	* @param[in] timeout Timeout for writing in milliseconds. Use negative value for infinite
	* waiting and 0 for return if data cannot be sent immediately.
	* @param[out] msgid If RPC was successfully sent, this is it's message ID.
	* @return #NC_MSG_RPC on success,
	* #NC_MSG_WOULDBLOCK in case of a busy session, and
	* #NC_MSG_ERROR on error.
	*/
	NC_MSG_TYPE nc_send_rpc(struct nc_session session, struct nc_rpc rpc, int timeout, uint64_t *msgid);

	#endif /* NC_SESSION_CLIENT_H_ */