blob: 342943abf2d51c0d2fb63797e267539ea3698974 [file] [log] [blame]
Michal Vasko086311b2016-01-08 09:53:11 +01001/**
2 * \file session_client.h
3 * \author Michal Vasko <mvasko@cesnet.cz>
4 * \brief libnetconf2 session client manipulation
5 *
6 * Copyright (c) 2015 CESNET, z.s.p.o.
7 *
Radek Krejci9b81f5b2016-02-24 13:14:49 +01008 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
Michal Vaskoafd416b2016-02-25 14:51:46 +010011 *
Radek Krejci9b81f5b2016-02-24 13:14:49 +010012 * https://opensource.org/licenses/BSD-3-Clause
Michal Vasko086311b2016-01-08 09:53:11 +010013 */
14
15#ifndef NC_SESSION_CLIENT_H_
16#define NC_SESSION_CLIENT_H_
17
Michal Vaskoc09730e2019-01-17 10:07:26 +010018#ifdef __cplusplus
19extern "C" {
20#endif
21
Michal Vasko086311b2016-01-08 09:53:11 +010022#include <libyang/libyang.h>
23
Radek Krejci53691be2016-02-22 13:58:37 +010024#ifdef NC_ENABLED_SSH
Michal Vasko086311b2016-01-08 09:53:11 +010025
26#include <libssh/libssh.h>
27
28#endif
29
Radek Krejci53691be2016-02-22 13:58:37 +010030#ifdef NC_ENABLED_TLS
Michal Vasko086311b2016-01-08 09:53:11 +010031
32#include <openssl/ssl.h>
33
34#endif
35
Michal Vasko7bcb48e2016-01-15 10:28:54 +010036#include "messages_client.h"
Michal Vaskob83a3fa2021-05-26 09:53:42 +020037#include "netconf.h"
38#include "session.h"
Michal Vasko086311b2016-01-08 09:53:11 +010039
40/**
Radek Krejci6799a052017-05-19 14:23:23 +020041 * @addtogroup client
42 * @{
43 */
44
45/**
Michal Vasko086311b2016-01-08 09:53:11 +010046 * @brief Set location where libnetconf tries to search for YANG/YIN schemas.
47 *
Michal Vasko7f1c0ef2016-03-11 11:13:06 +010048 * The location is searched when connecting to a NETCONF server and building
Michal Vasko086311b2016-01-08 09:53:11 +010049 * YANG context for further processing of the NETCONF messages and data.
50 *
Radek Krejcifd5b6682017-06-13 15:52:53 +020051 * The searchpath is also used to store schemas retreived via \<get-schema\>
52 * operation - if the schema is not found in searchpath neither via schema
53 * callback provided via nc_client_set_schema_callback() and server supports
54 * the NETCONF \<get-schema\> operation, the schema is retrieved this way and
55 * stored into the searchpath (if specified).
56 *
Michal Vasko086311b2016-01-08 09:53:11 +010057 * @param[in] path Directory where to search for YANG/YIN schemas.
58 * @return 0 on success, 1 on (memory allocation) failure.
59 */
Michal Vasko7f1c0ef2016-03-11 11:13:06 +010060int nc_client_set_schema_searchpath(const char *path);
61
62/**
63 * @brief Get schema searchpath that was set by nc_client_set_schema_searchpath().
64 *
65 * @return Schema searchpath directory, NULL if not set.
66 */
67const char *nc_client_get_schema_searchpath(void);
Michal Vasko086311b2016-01-08 09:53:11 +010068
69/**
Radek Krejcifd5b6682017-06-13 15:52:53 +020070 * @brief Set callback function to get missing schemas.
71 *
72 * @param[in] clb Callback responsible for returning the missing model.
73 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb.
74 * @return 0 on success, 1 on (memory allocation) failure.
75 */
76int nc_client_set_schema_callback(ly_module_imp_clb clb, void *user_data);
77
78/**
79 * @brief Get callback function used to get missing schemas.
80 *
81 * @param[out] user_data Optionally return the private data set with the callback.
82 * Note that the caller is responsible for freeing the private data, so before
83 * changing the callback, private data used for the previous callback should be
84 * freed.
85 * @return Pointer to the set callback, NULL if no such callback was set.
86 */
87ly_module_imp_clb nc_client_get_schema_callback(void **user_data);
88
89/**
Radek Krejci5cebc6b2017-05-26 13:24:38 +020090 * @brief Use the provided thread-specific client's context in the current thread.
91 *
92 * Note that from this point the context is shared with the thread from which the context was taken and any
93 * nc_client_*set* functions and functions creating connection in these threads should be protected from the
94 * concurrent execution.
95 *
Radek Krejcifd5b6682017-06-13 15:52:53 +020096 * Context contains schema searchpath/callback, call home binds, TLS and SSH authentication data (username, keys,
Radek Krejci5cebc6b2017-05-26 13:24:38 +020097 * various certificates and callbacks).
98 *
99 * @param[in] context Client's thread-specific context provided by nc_client_get_thread_context().
100 */
101void nc_client_set_thread_context(void *context);
102
103/**
104 * @brief Get thread-specific client context for sharing with some other thread using
105 * nc_client_set_thread_context().
106 *
107 * @return Pointer to the client's context of the current thread.
108 */
109void *nc_client_get_thread_context(void);
110
111/**
Michal Vaskoa7b8ca52016-03-01 12:09:29 +0100112 * @brief Initialize libssh and/or libssl/libcrypto for use in the client.
113 */
114void nc_client_init(void);
115
116/**
117 * @brief Destroy all libssh and/or libssl/libcrypto dynamic memory and
118 * the client options, for both SSH and TLS, and for Call Home too.
Michal Vaskob7558c52016-02-26 15:04:19 +0100119 */
120void nc_client_destroy(void);
121
Michal Vasko4e6d3242021-05-26 09:13:24 +0200122/** @} Client */
Radek Krejci6799a052017-05-19 14:23:23 +0200123
124/**
125 * @defgroup client_session Client Session
126 * @ingroup client
127 *
128 * @brief Client-side NETCONF session manipulation.
129 * @{
130 */
131
Michal Vaskob7558c52016-02-26 15:04:19 +0100132/**
Michal Vasko086311b2016-01-08 09:53:11 +0100133 * @brief Connect to the NETCONF server via proviaded input/output file descriptors.
134 *
135 * Transport layer is supposed to be already set. Function do not cover authentication
136 * or any other manipulation with the transport layer, it only establish NETCONF session
137 * by sending and processing NETCONF \<hello\> messages.
138 *
Michal Vasko086311b2016-01-08 09:53:11 +0100139 * @param[in] fdin Input file descriptor for reading (clear) data from NETCONF server.
140 * @param[in] fdout Output file descriptor for writing (clear) data for NETCONF server.
141 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
142 * (ignoring what is actually supported by the server side). If not set,
143 * YANG context is created for the session using \<get-schema\> (if supported
144 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100145 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100146 * to connect to a server supporting \<get-schema\> it is possible that
147 * the session context will not include all the models supported by the server.
148 * @return Created NETCONF session object or NULL in case of error.
149 */
150struct nc_session *nc_connect_inout(int fdin, int fdout, struct ly_ctx *ctx);
151
Olivier Matzac7fa2f2018-10-11 10:02:04 +0200152/**
153 * @brief Connect to the NETCONF server via unix socket.
154 *
155 * Connect to netconf server via an unix socket. Function do not cover authentication
156 * or any other manipulation with the transport layer, it only establish NETCONF session
157 * by sending and processing NETCONF \<hello\> messages.
158 *
159 * @param[in] address Path to the unix socket.
160 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
161 * (ignoring what is actually supported by the server side). If not set,
162 * YANG context is created for the session using \<get-schema\> (if supported
163 * by the server side) or/and by searching for YANG schemas in the searchpath
164 * (see nc_client_schema_searchpath()). In every case except not providing context
165 * to connect to a server supporting \<get-schema\> it is possible that
166 * the session context will not include all the models supported by the server.
167 * @return Created NETCONF session object or NULL in case of error.
168 */
169struct nc_session *nc_connect_unix(const char *address, struct ly_ctx *ctx);
170
Michal Vasko4e6d3242021-05-26 09:13:24 +0200171/** @} Client Session */
Radek Krejci6799a052017-05-19 14:23:23 +0200172
Radek Krejci53691be2016-02-22 13:58:37 +0100173#ifdef NC_ENABLED_SSH
Michal Vasko086311b2016-01-08 09:53:11 +0100174
175/**
Radek Krejci6799a052017-05-19 14:23:23 +0200176 * @defgroup client_ssh Client SSH
177 * @ingroup client
178 *
179 * @brief Client-side settings for SSH connections.
180 * @{
181 */
182
183/**
Michal Vaskoef112d72016-02-18 13:28:25 +0100184 * @brief Set SSH authentication hostkey check (knownhosts) callback.
185 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200186 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
187 * freeing the private data when necessary (the private data can be obtained by
188 * nc_client_ssh_get_auth_hostkey_check_clb()).
189 *
Michal Vaskoef112d72016-02-18 13:28:25 +0100190 * @param[in] auth_hostkey_check Function to call, returns 0 on success, non-zero in error.
191 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200192 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vaskoef112d72016-02-18 13:28:25 +0100193 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200194void nc_client_ssh_set_auth_hostkey_check_clb(int (*auth_hostkey_check)(const char *hostname, ssh_session session, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200195 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200196
197/**
198 * @brief Get currently set SSH authentication hostkey check (knownhosts) callback and its private data previously set
199 * by nc_client_ssh_set_auth_hostkey_check_clb().
200 *
201 * @param[out] auth_hostkey_check Currently set callback, NULL in case of the default callback.
202 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
203 */
204void nc_client_ssh_get_auth_hostkey_check_clb(int (**auth_hostkey_check)(const char *hostname, ssh_session session, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200205 void **priv);
Michal Vaskoef112d72016-02-18 13:28:25 +0100206
207/**
Michal Vasko30e2c872016-02-18 10:03:21 +0100208 * @brief Set SSH password authentication callback.
209 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200210 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
211 * freeing the private data when necessary (the private data can be obtained by
212 * nc_client_ssh_get_auth_password_clb()).
213 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100214 * @param[in] auth_password Function to call, returns the password for username\@hostname.
Michal Vasko30e2c872016-02-18 10:03:21 +0100215 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200216 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100217 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200218void nc_client_ssh_set_auth_password_clb(char *(*auth_password)(const char *username, const char *hostname, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200219 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200220
221/**
222 * @brief Get currently set SSH password authentication callback and its private data previously set
223 * by nc_client_ssh_set_auth_password_clb().
224 *
225 * @param[out] auth_password Currently set callback, NULL in case of the default callback.
226 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
227 */
228void nc_client_ssh_get_auth_password_clb(char *(**auth_password)(const char *username, const char *hostname, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200229 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100230
231/**
232 * @brief Set SSH interactive authentication callback.
233 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200234 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
235 * freeing the private data when necessary (the private data can be obtained by
236 * nc_client_ssh_get_auth_interactive_clb()).
237 *
Michal Vasko30e2c872016-02-18 10:03:21 +0100238 * @param[in] auth_interactive Function to call for every question, returns the answer for
239 * authentication name with instruction and echoing prompt.
240 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200241 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100242 */
243void nc_client_ssh_set_auth_interactive_clb(char *(*auth_interactive)(const char *auth_name, const char *instruction,
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200244 const char *prompt, int echo, void *priv),
245 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200246
247/**
248 * @brief Get currently set SSH interactive authentication callback and its private data previously set
249 * by nc_client_ssh_set_auth_interactive_clb().
250 *
251 * @param[out] auth_interactive Currently set callback, NULL in case of the default callback.
252 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
253 */
254void nc_client_ssh_get_auth_interactive_clb(char *(**auth_interactive)(const char *auth_name, const char *instruction,
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200255 const char *prompt, int echo, void *priv),
256 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100257
258/**
259 * @brief Set SSH publickey authentication encrypted private key passphrase callback.
260 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200261 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
262 * freeing the private data when necessary (the private data can be obtained by
263 * nc_client_ssh_get_auth_privkey_passphrase_clb()).
264 *
Michal Vasko30e2c872016-02-18 10:03:21 +0100265 * @param[in] auth_privkey_passphrase Function to call for every question, returns
266 * the passphrase for the specific private key.
Radek Krejci90a84a22017-05-25 13:53:00 +0200267 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100268 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200269void nc_client_ssh_set_auth_privkey_passphrase_clb(char *(*auth_privkey_passphrase)(const char *privkey_path, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200270 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200271
272/**
273 * @brief Get currently set SSH publickey authentication encrypted private key passphrase callback and its private data
274 * previously set by nc_client_ssh_set_auth_privkey_passphrase_clb().
275 *
276 * @param[out] auth_privkey_passphrase Currently set callback, NULL in case of the default callback.
277 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
278 */
279void nc_client_ssh_get_auth_privkey_passphrase_clb(char *(**auth_privkey_passphrase)(const char *privkey_path, void *priv),
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200280 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100281
282/**
Michal Vasko3031aae2016-01-27 16:07:18 +0100283 * @brief Add an SSH public and private key pair to be used for client authentication.
284 *
285 * Private key can be encrypted, the passphrase will be asked for before using it.
286 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100287 * @param[in] pub_key Path to the public key.
288 * @param[in] priv_key Path to the private key.
Michal Vaskof0537d82016-01-29 14:42:38 +0100289 * @return 0 on success, -1 on error.
Michal Vasko3031aae2016-01-27 16:07:18 +0100290 */
291int nc_client_ssh_add_keypair(const char *pub_key, const char *priv_key);
292
293/**
294 * @brief Remove an SSH public and private key pair that was used for client authentication.
295 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100296 * @param[in] idx Index of the keypair starting with 0.
Michal Vasko3031aae2016-01-27 16:07:18 +0100297 * @return 0 on success, -1 on error.
298 */
299int nc_client_ssh_del_keypair(int idx);
300
301/**
302 * @brief Get the number of public an private key pairs set to be used for client authentication.
303 *
304 * @return Keypair count.
305 */
306int nc_client_ssh_get_keypair_count(void);
307
308/**
309 * @brief Get a specific keypair set to be used for client authentication.
310 *
311 * @param[in] idx Index of the specific keypair.
312 * @param[out] pub_key Path to the public key.
313 * @param[out] priv_key Path to the private key.
Michal Vasko3031aae2016-01-27 16:07:18 +0100314 * @return 0 on success, -1 on error.
315 */
316int nc_client_ssh_get_keypair(int idx, const char **pub_key, const char **priv_key);
317
318/**
319 * @brief Set SSH authentication method preference.
320 *
Radek Krejci62aa0642017-05-25 16:33:49 +0200321 * The default preference is as follows:
322 * - interactive authentication (3)
323 * - password authentication (2)
324 * - public key authentication (1)
325 *
326 * @param[in] auth_type Authentication method to modify the preference of.
327 * @param[in] pref Preference of \p auth_type. Higher number increases priority, negative values disable the method.
Michal Vasko3031aae2016-01-27 16:07:18 +0100328 */
329void nc_client_ssh_set_auth_pref(NC_SSH_AUTH_TYPE auth_type, int16_t pref);
330
331/**
332 * @brief Get SSH authentication method preference.
333 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100334 * @param[in] auth_type Authentication method to retrieve the prefrence of.
Michal Vasko3031aae2016-01-27 16:07:18 +0100335 * @return Preference of the \p auth_type.
336 */
337int16_t nc_client_ssh_get_auth_pref(NC_SSH_AUTH_TYPE auth_type);
338
339/**
340 * @brief Set client SSH username used for authentication.
341 *
342 * @param[in] username Username to use.
343 * @return 0 on success, -1 on error.
344 */
345int nc_client_ssh_set_username(const char *username);
346
Michal Vasko3031aae2016-01-27 16:07:18 +0100347/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100348 * @brief Get client SSH username used for authentication.
349 *
350 * @return Username used.
351 */
352const char *nc_client_ssh_get_username(void);
353
354/**
Michal Vasko086311b2016-01-08 09:53:11 +0100355 * @brief Connect to the NETCONF server using SSH transport (via libssh).
356 *
357 * SSH session is created with default options. If the caller needs to use specific SSH session properties,
358 * they are supposed to use nc_connect_libssh().
359 *
Michal Vasko086311b2016-01-08 09:53:11 +0100360 * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
361 * 'localhost' is used by default if NULL is specified.
362 * @param[in] port Port number of the target server. Default value 830 is used if 0 is specified.
Michal Vasko086311b2016-01-08 09:53:11 +0100363 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
364 * (ignoring what is actually supported by the server side). If not set,
365 * YANG context is created for the session using \<get-schema\> (if supported
366 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100367 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100368 * to connect to a server supporting \<get-schema\> it is possible that
369 * the session context will not include all the models supported by the server.
370 * @return Created NETCONF session object or NULL on error.
371 */
Michal Vasko3031aae2016-01-27 16:07:18 +0100372struct nc_session *nc_connect_ssh(const char *host, uint16_t port, struct ly_ctx *ctx);
Michal Vasko086311b2016-01-08 09:53:11 +0100373
374/**
375 * @brief Connect to the NETCONF server using the provided SSH (libssh) session.
376 *
377 * SSH session can have any options set, they will not be modified. If no options were set,
378 * host 'localhost', port 22, and the username detected from the EUID is used. If socket is
379 * set and connected only the host and the username must be set/is detected. Or the \p ssh_session
380 * can already be authenticated in which case it is used directly.
381 *
Michal Vasko086311b2016-01-08 09:53:11 +0100382 * @param[in] ssh_session libssh structure representing SSH session object. After passing it
383 * to libnetconf2 this way, it is fully managed by it (including freeing!).
384 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
385 * (ignoring what is actually supported by the server side). If not set,
386 * YANG context is created for the session using \<get-schema\> (if supported
387 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100388 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100389 * to connect to a server supporting \<get-schema\> it is possible that
390 * the session context will not include all the models supported by the server.
391 * @return Created NETCONF session object or NULL on error.
392 */
393struct nc_session *nc_connect_libssh(ssh_session ssh_session, struct ly_ctx *ctx);
394
395/**
396 * @brief Create another NETCONF session on existing SSH session using separated SSH channel.
397 *
Michal Vasko086311b2016-01-08 09:53:11 +0100398 * @param[in] session Existing NETCONF session. The session has to be created on SSH transport layer using libssh -
399 * it has to be created by nc_connect_ssh(), nc_connect_libssh() or nc_connect_ssh_channel().
400 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
401 * (ignoring what is actually supported by the server side). If not set,
402 * YANG context is created for the session using \<get-schema\> (if supported
403 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100404 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100405 * to connect to a server supporting \<get-schema\> it is possible that
406 * the session context will not include all the models supported by the server.
407 * @return Created NETCONF session object or NULL on error.
408 */
409struct nc_session *nc_connect_ssh_channel(struct nc_session *session, struct ly_ctx *ctx);
410
Michal Vasko4e6d3242021-05-26 09:13:24 +0200411/** @} Client SSH */
Radek Krejci6799a052017-05-19 14:23:23 +0200412
Radek Krejci53691be2016-02-22 13:58:37 +0100413#endif /* NC_ENABLED_SSH */
Michal Vasko086311b2016-01-08 09:53:11 +0100414
Radek Krejci53691be2016-02-22 13:58:37 +0100415#ifdef NC_ENABLED_TLS
Michal Vasko086311b2016-01-08 09:53:11 +0100416
417/**
Radek Krejci6799a052017-05-19 14:23:23 +0200418 * @defgroup client_tls Client TLS
419 * @ingroup client
420 *
421 * @brief Client-side settings for TLS connections.
422 * @{
423 */
424
425/**
Michal Vasko3031aae2016-01-27 16:07:18 +0100426 * @brief Set client authentication identity - a certificate and a private key.
Michal Vasko086311b2016-01-08 09:53:11 +0100427 *
Michal Vaskoe22c6732016-01-29 11:03:02 +0100428 * @param[in] client_cert Path to the file containing the client certificate.
Michal Vasko086311b2016-01-08 09:53:11 +0100429 * @param[in] client_key Path to the file containing the private key for the \p client_cert.
430 * If NULL, key is expected to be stored with \p client_cert.
Michal Vasko3031aae2016-01-27 16:07:18 +0100431 * @return 0 on success, -1 on error.
432 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100433int nc_client_tls_set_cert_key_paths(const char *client_cert, const char *client_key);
Michal Vasko3031aae2016-01-27 16:07:18 +0100434
435/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100436 * @brief Get client authentication identity - a certificate and a private key.
437 *
Michal Vaskoe22c6732016-01-29 11:03:02 +0100438 * @param[out] client_cert Path to the file containing the client certificate. Can be NULL.
439 * @param[out] client_key Path to the file containing the private key for the \p client_cert. Can be NULL.
440 */
441void nc_client_tls_get_cert_key_paths(const char **client_cert, const char **client_key);
442
443/**
444 * @brief Set client trusted CA certificates paths.
Michal Vasko3031aae2016-01-27 16:07:18 +0100445 *
Michal Vasko086311b2016-01-08 09:53:11 +0100446 * @param[in] ca_file Location of the CA certificate file used to verify server certificates.
447 * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
448 * @param[in] ca_dir Location of the CA certificates directory used to verify the server certificates.
449 * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
Michal Vasko3031aae2016-01-27 16:07:18 +0100450 * @return 0 on success, -1 on error.
451 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100452int nc_client_tls_set_trusted_ca_paths(const char *ca_file, const char *ca_dir);
Michal Vasko3031aae2016-01-27 16:07:18 +0100453
454/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100455 * @brief Get client trusted CA certificates paths.
456 *
457 * @param[out] ca_file Location of the CA certificate file used to verify server certificates.
458 * Can be NULL.
459 * @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates.
460 * Can be NULL.
461 */
462void nc_client_tls_get_trusted_ca_paths(const char **ca_file, const char **ca_dir);
463
464/**
465 * @brief Set client Certificate Revocation List paths.
Michal Vasko3031aae2016-01-27 16:07:18 +0100466 *
Michal Vasko086311b2016-01-08 09:53:11 +0100467 * @param[in] crl_file Location of the CRL certificate file used to check for revocated certificates.
468 * @param[in] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
Michal Vasko3031aae2016-01-27 16:07:18 +0100469 * @return 0 on success, -1 on error.
470 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100471int nc_client_tls_set_crl_paths(const char *crl_file, const char *crl_dir);
472
473/**
474 * @brief Get client Certificate Revocation List paths.
475 *
476 * @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates.
477 * @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
478 */
479void nc_client_tls_get_crl_paths(const char **crl_file, const char **crl_dir);
Michal Vasko3031aae2016-01-27 16:07:18 +0100480
Michal Vasko3031aae2016-01-27 16:07:18 +0100481/**
Michal Vasko086311b2016-01-08 09:53:11 +0100482 * @brief Connect to the NETCONF server using TLS transport (via libssl)
483 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100484 * TLS session is created with the certificates set using nc_client_tls_* functions, which must be called beforehand!
Michal Vasko086311b2016-01-08 09:53:11 +0100485 * If the caller needs to use specific TLS session properties, they are supposed to use nc_connect_libssl().
486 *
Michal Vasko086311b2016-01-08 09:53:11 +0100487 * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
488 * 'localhost' is used by default if NULL is specified.
489 * @param[in] port Port number of the target server. Default value 6513 is used if 0 is specified.
490 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
491 * (ignoring what is actually supported by the server side). If not set,
492 * YANG context is created for the session using \<get-schema\> (if supported
493 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100494 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100495 * to connect to a server supporting \<get-schema\> it is possible that
496 * the session context will not include all the models supported by the server.
497 * @return Created NETCONF session object or NULL on error.
498 */
499struct nc_session *nc_connect_tls(const char *host, uint16_t port, struct ly_ctx *ctx);
500
501/**
502 * @brief Connect to the NETCONF server using the provided TLS (libssl) session.
503 *
504 * The TLS session supplied is expected to be fully connected and authenticated!
505 *
Michal Vasko086311b2016-01-08 09:53:11 +0100506 * @param[in] tls libssl structure representing the TLS session object.
507 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
508 * (ignoring what is actually supported by the server side). If not set,
509 * YANG context is created for the session using \<get-schema\> (if supported
510 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100511 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100512 * to connect to a server supporting \<get-schema\> it is possible that
513 * the session context will not include all the models supported by the server.
514 * @return Created NETCONF session object or NULL on error.
515 */
516struct nc_session *nc_connect_libssl(SSL *tls, struct ly_ctx *ctx);
517
Michal Vasko4e6d3242021-05-26 09:13:24 +0200518/** @} Client TLS */
Radek Krejci6799a052017-05-19 14:23:23 +0200519
Radek Krejci53691be2016-02-22 13:58:37 +0100520#endif /* NC_ENABLED_TLS */
Michal Vasko086311b2016-01-08 09:53:11 +0100521
522/**
Radek Krejci6799a052017-05-19 14:23:23 +0200523 * @addtogroup client_session
524 * @{
525 */
526
527/**
Michal Vaskobdfb5242016-05-24 09:11:01 +0200528 * @brief Get session capabilities.
529 *
530 * @param[in] session Session to get the information from.
Radek Krejci82da7812017-05-25 13:52:04 +0200531 * @return NULL-terminated array of the \p session capabilities.
Michal Vaskobdfb5242016-05-24 09:11:01 +0200532 */
Michal Vasko1b2ddc92017-05-24 08:59:49 +0200533const char * const *nc_session_get_cpblts(const struct nc_session *session);
Michal Vaskobdfb5242016-05-24 09:11:01 +0200534
535/**
536 * @brief Check capability presence in a session.
537 *
538 * @param[in] session Session to check.
539 * @param[in] capab Capability to look for, capability with any additional suffix will match.
540 * @return Matching capability, NULL if none found.
541 */
542const char *nc_session_cpblt(const struct nc_session *session, const char *capab);
543
544/**
Michal Vasko9cd26a82016-05-31 08:58:48 +0200545 * @brief Check whether the session has a notification thread running.
546 *
547 * @param[in] session Session to check.
548 * @return 1 if notfication thread is running, 0 otherwise.
549 */
550int nc_session_ntf_thread_running(const struct nc_session *session);
551
552/**
Michal Vasko086311b2016-01-08 09:53:11 +0100553 * @brief Receive NETCONF RPC reply.
554 *
Michal Vasko086311b2016-01-08 09:53:11 +0100555 * @param[in] session NETCONF session from which the function gets data. It must be the
Michal Vasko77367452021-02-16 16:32:18 +0100556 * client side session object.
Michal Vasko086311b2016-01-08 09:53:11 +0100557 * @param[in] rpc Original RPC this should be the reply to.
558 * @param[in] msgid Expected message ID of the reply.
559 * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
Michal Vasko77367452021-02-16 16:32:18 +0100560 * waiting and 0 for immediate return if data are not available on the wire.
561 * @param[out] envp NETCONF rpc-reply XML envelopes.
562 * @param[out] op Parsed NETCONF reply data, if any (none for \<ok\> or error replies). Set only on #NC_MSG_REPLY
563 * and #NC_MSG_REPLY_ERR_MSGID return.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200564 * @return #NC_MSG_REPLY for success,
565 * #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
566 * #NC_MSG_ERROR if reading has failed,
567 * #NC_MSG_NOTIF if a notification was read instead (call this function again to get the reply), and
568 * #NC_MSG_REPLY_ERR_MSGID if a reply with missing or wrong message-id was received.
Michal Vasko086311b2016-01-08 09:53:11 +0100569 */
Michal Vaskod083db62016-01-19 10:31:29 +0100570NC_MSG_TYPE nc_recv_reply(struct nc_session *session, struct nc_rpc *rpc, uint64_t msgid, int timeout,
Michal Vasko77367452021-02-16 16:32:18 +0100571 struct lyd_node **envp, struct lyd_node **op);
Michal Vasko086311b2016-01-08 09:53:11 +0100572
573/**
574 * @brief Receive NETCONF Notification.
575 *
576 * @param[in] session NETCONF session from which the function gets data. It must be the
577 * client side session object.
578 * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
Michal Vasko71ba2da2016-05-04 10:53:16 +0200579 * waiting and 0 for immediate return if data are not available on the wire.
Michal Vasko77367452021-02-16 16:32:18 +0100580 * @param[out] envp NETCONF notification XML envelopes.
581 * @param[out] op Parsed NETCONF notification data.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200582 * @return #NC_MSG_NOTIF for success,
583 * #NC_MSG_WOULDBLOCK if \p timeout has elapsed,
584 * #NC_MSG_ERROR if reading has failed, and
585 * #NC_MSG_REPLY if a reply was read instead (call this function again to get a notification).
Michal Vasko086311b2016-01-08 09:53:11 +0100586 */
Michal Vasko77367452021-02-16 16:32:18 +0100587NC_MSG_TYPE nc_recv_notif(struct nc_session *session, int timeout, struct lyd_node **envp, struct lyd_node **op);
Michal Vasko086311b2016-01-08 09:53:11 +0100588
589/**
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100590 * @brief Receive NETCONF Notifications in a separate thread until the session is terminated
591 * or \<notificationComplete\> is received.
592 *
593 * @param[in] session Netconf session to read notifications from.
594 * @param[in] notif_clb Function that is called for every received notification (including
595 * \<notificationComplete\>). Parameters are the session the notification was received on
Michal Vasko77367452021-02-16 16:32:18 +0100596 * and the notification data.
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100597 * @return 0 if the thread was successfully created, -1 on error.
598 */
599int nc_recv_notif_dispatch(struct nc_session *session,
Michal Vasko77367452021-02-16 16:32:18 +0100600 void (*notif_clb)(struct nc_session *session, const struct lyd_node *envp, const struct lyd_node *op));
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100601
602/**
Michal Vasko086311b2016-01-08 09:53:11 +0100603 * @brief Send NETCONF RPC message via the session.
604 *
605 * @param[in] session NETCONF session where the RPC will be written.
606 * @param[in] rpc NETCOFN RPC object to send via specified session. Object can be created by
607 * nc_rpc_lock(), nc_rpc_unlock() and nc_rpc_generic() functions.
608 * @param[in] timeout Timeout for writing in milliseconds. Use negative value for infinite
609 * waiting and 0 for return if data cannot be sent immediately.
610 * @param[out] msgid If RPC was successfully sent, this is it's message ID.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200611 * @return #NC_MSG_RPC on success,
612 * #NC_MSG_WOULDBLOCK in case of a busy session, and
613 * #NC_MSG_ERROR on error.
Michal Vasko086311b2016-01-08 09:53:11 +0100614 */
Michal Vaskod083db62016-01-19 10:31:29 +0100615NC_MSG_TYPE nc_send_rpc(struct nc_session *session, struct nc_rpc *rpc, int timeout, uint64_t *msgid);
Michal Vasko086311b2016-01-08 09:53:11 +0100616
Michal Vaskode2946c2017-01-12 12:19:26 +0100617/**
618 * @brief Make a session not strict when sending RPCs and receiving RPC replies. In other words,
619 * it will silently skip unknown nodes without an error.
620 *
621 * Generally, no such data should be worked with, so use this function only when you know what you
622 * are doing and you understand the consequences.
623 *
624 * @param[in] session NETCONF client session.
625 */
626void nc_client_session_set_not_strict(struct nc_session *session);
627
Michal Vasko77367452021-02-16 16:32:18 +0100628/** @} Client Session */
Radek Krejci6799a052017-05-19 14:23:23 +0200629
Michal Vaskoc09730e2019-01-17 10:07:26 +0100630#ifdef __cplusplus
631}
632#endif
633
Michal Vasko086311b2016-01-08 09:53:11 +0100634#endif /* NC_SESSION_CLIENT_H_ */