blob: 5aad7552568a1d4bfbc2371b1c7d525879545e05 [file] [log] [blame]
Michal Vasko086311b2016-01-08 09:53:11 +01001/**
Michal Vaskoc446a382021-06-18 08:54:05 +02002 * @file session_client.h
3 * @author Michal Vasko <mvasko@cesnet.cz>
4 * @brief libnetconf2 session client manipulation
Michal Vasko086311b2016-01-08 09:53:11 +01005 *
Michal Vaskoc446a382021-06-18 08:54:05 +02006 * Copyright (c) 2015 - 2021 CESNET, z.s.p.o.
Michal Vasko086311b2016-01-08 09:53:11 +01007 *
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 Vaskoc446a382021-06-18 08:54:05 +020025# include <libssh/libssh.h>
Michal Vasko086311b2016-01-08 09:53:11 +010026#endif
27
Radek Krejci53691be2016-02-22 13:58:37 +010028#ifdef NC_ENABLED_TLS
Michal Vaskoc446a382021-06-18 08:54:05 +020029# include <openssl/ssl.h>
Michal Vasko086311b2016-01-08 09:53:11 +010030#endif
31
Michal Vasko7bcb48e2016-01-15 10:28:54 +010032#include "messages_client.h"
Michal Vaskob83a3fa2021-05-26 09:53:42 +020033#include "netconf.h"
34#include "session.h"
Michal Vasko086311b2016-01-08 09:53:11 +010035
36/**
Radek Krejci6799a052017-05-19 14:23:23 +020037 * @addtogroup client
38 * @{
39 */
40
41/**
Michal Vasko086311b2016-01-08 09:53:11 +010042 * @brief Set location where libnetconf tries to search for YANG/YIN schemas.
43 *
Michal Vasko7f1c0ef2016-03-11 11:13:06 +010044 * The location is searched when connecting to a NETCONF server and building
Michal Vasko086311b2016-01-08 09:53:11 +010045 * YANG context for further processing of the NETCONF messages and data.
46 *
Radek Krejcifd5b6682017-06-13 15:52:53 +020047 * The searchpath is also used to store schemas retreived via \<get-schema\>
48 * operation - if the schema is not found in searchpath neither via schema
49 * callback provided via nc_client_set_schema_callback() and server supports
50 * the NETCONF \<get-schema\> operation, the schema is retrieved this way and
51 * stored into the searchpath (if specified).
52 *
Michal Vasko086311b2016-01-08 09:53:11 +010053 * @param[in] path Directory where to search for YANG/YIN schemas.
54 * @return 0 on success, 1 on (memory allocation) failure.
55 */
Michal Vasko7f1c0ef2016-03-11 11:13:06 +010056int nc_client_set_schema_searchpath(const char *path);
57
58/**
59 * @brief Get schema searchpath that was set by nc_client_set_schema_searchpath().
60 *
61 * @return Schema searchpath directory, NULL if not set.
62 */
63const char *nc_client_get_schema_searchpath(void);
Michal Vasko086311b2016-01-08 09:53:11 +010064
65/**
Radek Krejcifd5b6682017-06-13 15:52:53 +020066 * @brief Set callback function to get missing schemas.
67 *
68 * @param[in] clb Callback responsible for returning the missing model.
Michal Vaskoc446a382021-06-18 08:54:05 +020069 * @param[in] user_data Arbitrary data that will always be passed to the callback @p clb.
Radek Krejcifd5b6682017-06-13 15:52:53 +020070 * @return 0 on success, 1 on (memory allocation) failure.
71 */
72int nc_client_set_schema_callback(ly_module_imp_clb clb, void *user_data);
73
74/**
75 * @brief Get callback function used to get missing schemas.
76 *
77 * @param[out] user_data Optionally return the private data set with the callback.
78 * Note that the caller is responsible for freeing the private data, so before
79 * changing the callback, private data used for the previous callback should be
80 * freed.
81 * @return Pointer to the set callback, NULL if no such callback was set.
82 */
83ly_module_imp_clb nc_client_get_schema_callback(void **user_data);
84
85/**
Radek Krejci5cebc6b2017-05-26 13:24:38 +020086 * @brief Use the provided thread-specific client's context in the current thread.
87 *
88 * Note that from this point the context is shared with the thread from which the context was taken and any
89 * nc_client_*set* functions and functions creating connection in these threads should be protected from the
90 * concurrent execution.
91 *
Radek Krejcifd5b6682017-06-13 15:52:53 +020092 * Context contains schema searchpath/callback, call home binds, TLS and SSH authentication data (username, keys,
Radek Krejci5cebc6b2017-05-26 13:24:38 +020093 * various certificates and callbacks).
94 *
95 * @param[in] context Client's thread-specific context provided by nc_client_get_thread_context().
96 */
97void nc_client_set_thread_context(void *context);
98
99/**
100 * @brief Get thread-specific client context for sharing with some other thread using
101 * nc_client_set_thread_context().
102 *
103 * @return Pointer to the client's context of the current thread.
104 */
105void *nc_client_get_thread_context(void);
106
107/**
Michal Vaskoa7b8ca52016-03-01 12:09:29 +0100108 * @brief Initialize libssh and/or libssl/libcrypto for use in the client.
109 */
110void nc_client_init(void);
111
112/**
113 * @brief Destroy all libssh and/or libssl/libcrypto dynamic memory and
114 * the client options, for both SSH and TLS, and for Call Home too.
Michal Vaskob7558c52016-02-26 15:04:19 +0100115 */
116void nc_client_destroy(void);
117
Michal Vasko4e6d3242021-05-26 09:13:24 +0200118/** @} Client */
Radek Krejci6799a052017-05-19 14:23:23 +0200119
120/**
121 * @defgroup client_session Client Session
122 * @ingroup client
123 *
124 * @brief Client-side NETCONF session manipulation.
125 * @{
126 */
127
Michal Vaskob7558c52016-02-26 15:04:19 +0100128/**
Michal Vasko086311b2016-01-08 09:53:11 +0100129 * @brief Connect to the NETCONF server via proviaded input/output file descriptors.
130 *
131 * Transport layer is supposed to be already set. Function do not cover authentication
132 * or any other manipulation with the transport layer, it only establish NETCONF session
133 * by sending and processing NETCONF \<hello\> messages.
134 *
Michal Vasko086311b2016-01-08 09:53:11 +0100135 * @param[in] fdin Input file descriptor for reading (clear) data from NETCONF server.
136 * @param[in] fdout Output file descriptor for writing (clear) data for NETCONF server.
137 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
138 * (ignoring what is actually supported by the server side). If not set,
139 * YANG context is created for the session using \<get-schema\> (if supported
140 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100141 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100142 * to connect to a server supporting \<get-schema\> it is possible that
143 * the session context will not include all the models supported by the server.
144 * @return Created NETCONF session object or NULL in case of error.
145 */
146struct nc_session *nc_connect_inout(int fdin, int fdout, struct ly_ctx *ctx);
147
Olivier Matzac7fa2f2018-10-11 10:02:04 +0200148/**
149 * @brief Connect to the NETCONF server via unix socket.
150 *
151 * Connect to netconf server via an unix socket. Function do not cover authentication
152 * or any other manipulation with the transport layer, it only establish NETCONF session
153 * by sending and processing NETCONF \<hello\> messages.
154 *
155 * @param[in] address Path to the unix socket.
156 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
157 * (ignoring what is actually supported by the server side). If not set,
158 * YANG context is created for the session using \<get-schema\> (if supported
159 * by the server side) or/and by searching for YANG schemas in the searchpath
160 * (see nc_client_schema_searchpath()). In every case except not providing context
161 * to connect to a server supporting \<get-schema\> it is possible that
162 * the session context will not include all the models supported by the server.
163 * @return Created NETCONF session object or NULL in case of error.
164 */
165struct nc_session *nc_connect_unix(const char *address, struct ly_ctx *ctx);
166
Michal Vasko4e6d3242021-05-26 09:13:24 +0200167/** @} Client Session */
Radek Krejci6799a052017-05-19 14:23:23 +0200168
Radek Krejci53691be2016-02-22 13:58:37 +0100169#ifdef NC_ENABLED_SSH
Michal Vasko086311b2016-01-08 09:53:11 +0100170
171/**
Radek Krejci6799a052017-05-19 14:23:23 +0200172 * @defgroup client_ssh Client SSH
173 * @ingroup client
174 *
175 * @brief Client-side settings for SSH connections.
176 * @{
177 */
178
179/**
Michal Vaskoef112d72016-02-18 13:28:25 +0100180 * @brief Set SSH authentication hostkey check (knownhosts) callback.
181 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200182 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
183 * freeing the private data when necessary (the private data can be obtained by
184 * nc_client_ssh_get_auth_hostkey_check_clb()).
185 *
Michal Vaskoef112d72016-02-18 13:28:25 +0100186 * @param[in] auth_hostkey_check Function to call, returns 0 on success, non-zero in error.
187 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200188 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vaskoef112d72016-02-18 13:28:25 +0100189 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200190void 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 +0200191 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200192
193/**
194 * @brief Get currently set SSH authentication hostkey check (knownhosts) callback and its private data previously set
195 * by nc_client_ssh_set_auth_hostkey_check_clb().
196 *
197 * @param[out] auth_hostkey_check Currently set callback, NULL in case of the default callback.
198 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
199 */
200void 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 +0200201 void **priv);
Michal Vaskoef112d72016-02-18 13:28:25 +0100202
203/**
Michal Vasko30e2c872016-02-18 10:03:21 +0100204 * @brief Set SSH password authentication callback.
205 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200206 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
207 * freeing the private data when necessary (the private data can be obtained by
208 * nc_client_ssh_get_auth_password_clb()).
209 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100210 * @param[in] auth_password Function to call, returns the password for username\@hostname.
Michal Vasko30e2c872016-02-18 10:03:21 +0100211 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200212 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100213 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200214void 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 +0200215 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200216
217/**
218 * @brief Get currently set SSH password authentication callback and its private data previously set
219 * by nc_client_ssh_set_auth_password_clb().
220 *
221 * @param[out] auth_password Currently set callback, NULL in case of the default callback.
222 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
223 */
224void 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 +0200225 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100226
227/**
228 * @brief Set SSH interactive authentication callback.
229 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200230 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
231 * freeing the private data when necessary (the private data can be obtained by
232 * nc_client_ssh_get_auth_interactive_clb()).
233 *
Michal Vasko30e2c872016-02-18 10:03:21 +0100234 * @param[in] auth_interactive Function to call for every question, returns the answer for
235 * authentication name with instruction and echoing prompt.
236 * If NULL, the default callback is set.
Radek Krejci90a84a22017-05-25 13:53:00 +0200237 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100238 */
239void nc_client_ssh_set_auth_interactive_clb(char *(*auth_interactive)(const char *auth_name, const char *instruction,
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200240 const char *prompt, int echo, void *priv),
241 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200242
243/**
244 * @brief Get currently set SSH interactive authentication callback and its private data previously set
245 * by nc_client_ssh_set_auth_interactive_clb().
246 *
247 * @param[out] auth_interactive Currently set callback, NULL in case of the default callback.
248 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
249 */
250void nc_client_ssh_get_auth_interactive_clb(char *(**auth_interactive)(const char *auth_name, const char *instruction,
Michal Vaskob83a3fa2021-05-26 09:53:42 +0200251 const char *prompt, int echo, void *priv),
252 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100253
254/**
255 * @brief Set SSH publickey authentication encrypted private key passphrase callback.
256 *
Radek Krejci90a84a22017-05-25 13:53:00 +0200257 * Repetitive calling causes replacing of the previous callback and its private data. Caller is responsible for
258 * freeing the private data when necessary (the private data can be obtained by
259 * nc_client_ssh_get_auth_privkey_passphrase_clb()).
260 *
Michal Vasko30e2c872016-02-18 10:03:21 +0100261 * @param[in] auth_privkey_passphrase Function to call for every question, returns
262 * the passphrase for the specific private key.
Radek Krejci90a84a22017-05-25 13:53:00 +0200263 * @param[in] priv Optional private data to be passed to the callback function.
Michal Vasko30e2c872016-02-18 10:03:21 +0100264 */
Radek Krejci90a84a22017-05-25 13:53:00 +0200265void 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 +0200266 void *priv);
Radek Krejci90a84a22017-05-25 13:53:00 +0200267
268/**
269 * @brief Get currently set SSH publickey authentication encrypted private key passphrase callback and its private data
270 * previously set by nc_client_ssh_set_auth_privkey_passphrase_clb().
271 *
272 * @param[out] auth_privkey_passphrase Currently set callback, NULL in case of the default callback.
273 * @param[out] priv Currently set (optional) private data to be passed to the callback function.
274 */
275void 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 +0200276 void **priv);
Michal Vasko30e2c872016-02-18 10:03:21 +0100277
278/**
Michal Vasko3031aae2016-01-27 16:07:18 +0100279 * @brief Add an SSH public and private key pair to be used for client authentication.
280 *
281 * Private key can be encrypted, the passphrase will be asked for before using it.
282 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100283 * @param[in] pub_key Path to the public key.
284 * @param[in] priv_key Path to the private key.
Michal Vaskof0537d82016-01-29 14:42:38 +0100285 * @return 0 on success, -1 on error.
Michal Vasko3031aae2016-01-27 16:07:18 +0100286 */
287int nc_client_ssh_add_keypair(const char *pub_key, const char *priv_key);
288
289/**
290 * @brief Remove an SSH public and private key pair that was used for client authentication.
291 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100292 * @param[in] idx Index of the keypair starting with 0.
Michal Vasko3031aae2016-01-27 16:07:18 +0100293 * @return 0 on success, -1 on error.
294 */
295int nc_client_ssh_del_keypair(int idx);
296
297/**
298 * @brief Get the number of public an private key pairs set to be used for client authentication.
299 *
300 * @return Keypair count.
301 */
302int nc_client_ssh_get_keypair_count(void);
303
304/**
305 * @brief Get a specific keypair set to be used for client authentication.
306 *
307 * @param[in] idx Index of the specific keypair.
308 * @param[out] pub_key Path to the public key.
309 * @param[out] priv_key Path to the private key.
Michal Vasko3031aae2016-01-27 16:07:18 +0100310 * @return 0 on success, -1 on error.
311 */
312int nc_client_ssh_get_keypair(int idx, const char **pub_key, const char **priv_key);
313
314/**
315 * @brief Set SSH authentication method preference.
316 *
Radek Krejci62aa0642017-05-25 16:33:49 +0200317 * The default preference is as follows:
318 * - interactive authentication (3)
319 * - password authentication (2)
320 * - public key authentication (1)
321 *
322 * @param[in] auth_type Authentication method to modify the preference of.
Michal Vaskoc446a382021-06-18 08:54:05 +0200323 * @param[in] pref Preference of @p auth_type. Higher number increases priority, negative values disable the method.
Michal Vasko3031aae2016-01-27 16:07:18 +0100324 */
325void nc_client_ssh_set_auth_pref(NC_SSH_AUTH_TYPE auth_type, int16_t pref);
326
327/**
328 * @brief Get SSH authentication method preference.
329 *
Michal Vasko3031aae2016-01-27 16:07:18 +0100330 * @param[in] auth_type Authentication method to retrieve the prefrence of.
Michal Vaskoc446a382021-06-18 08:54:05 +0200331 * @return Preference of the @p auth_type.
Michal Vasko3031aae2016-01-27 16:07:18 +0100332 */
333int16_t nc_client_ssh_get_auth_pref(NC_SSH_AUTH_TYPE auth_type);
334
335/**
336 * @brief Set client SSH username used for authentication.
337 *
338 * @param[in] username Username to use.
339 * @return 0 on success, -1 on error.
340 */
341int nc_client_ssh_set_username(const char *username);
342
Michal Vasko3031aae2016-01-27 16:07:18 +0100343/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100344 * @brief Get client SSH username used for authentication.
345 *
346 * @return Username used.
347 */
348const char *nc_client_ssh_get_username(void);
349
350/**
Michal Vasko086311b2016-01-08 09:53:11 +0100351 * @brief Connect to the NETCONF server using SSH transport (via libssh).
352 *
353 * SSH session is created with default options. If the caller needs to use specific SSH session properties,
354 * they are supposed to use nc_connect_libssh().
355 *
Michal Vasko086311b2016-01-08 09:53:11 +0100356 * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
357 * 'localhost' is used by default if NULL is specified.
358 * @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 +0100359 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
360 * (ignoring what is actually supported by the server side). If not set,
361 * YANG context is created for the session using \<get-schema\> (if supported
362 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100363 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100364 * to connect to a server supporting \<get-schema\> it is possible that
365 * the session context will not include all the models supported by the server.
366 * @return Created NETCONF session object or NULL on error.
367 */
Michal Vasko3031aae2016-01-27 16:07:18 +0100368struct nc_session *nc_connect_ssh(const char *host, uint16_t port, struct ly_ctx *ctx);
Michal Vasko086311b2016-01-08 09:53:11 +0100369
370/**
371 * @brief Connect to the NETCONF server using the provided SSH (libssh) session.
372 *
373 * SSH session can have any options set, they will not be modified. If no options were set,
374 * host 'localhost', port 22, and the username detected from the EUID is used. If socket is
Michal Vaskoc446a382021-06-18 08:54:05 +0200375 * set and connected only the host and the username must be set/is detected. Or the @p ssh_session
Michal Vasko086311b2016-01-08 09:53:11 +0100376 * can already be authenticated in which case it is used directly.
377 *
Michal Vasko086311b2016-01-08 09:53:11 +0100378 * @param[in] ssh_session libssh structure representing SSH session object. After passing it
379 * to libnetconf2 this way, it is fully managed by it (including freeing!).
380 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
381 * (ignoring what is actually supported by the server side). If not set,
382 * YANG context is created for the session using \<get-schema\> (if supported
383 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100384 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100385 * to connect to a server supporting \<get-schema\> it is possible that
386 * the session context will not include all the models supported by the server.
387 * @return Created NETCONF session object or NULL on error.
388 */
389struct nc_session *nc_connect_libssh(ssh_session ssh_session, struct ly_ctx *ctx);
390
391/**
392 * @brief Create another NETCONF session on existing SSH session using separated SSH channel.
393 *
Michal Vasko086311b2016-01-08 09:53:11 +0100394 * @param[in] session Existing NETCONF session. The session has to be created on SSH transport layer using libssh -
395 * it has to be created by nc_connect_ssh(), nc_connect_libssh() or nc_connect_ssh_channel().
396 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
397 * (ignoring what is actually supported by the server side). If not set,
398 * YANG context is created for the session using \<get-schema\> (if supported
399 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100400 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100401 * to connect to a server supporting \<get-schema\> it is possible that
402 * the session context will not include all the models supported by the server.
403 * @return Created NETCONF session object or NULL on error.
404 */
405struct nc_session *nc_connect_ssh_channel(struct nc_session *session, struct ly_ctx *ctx);
406
Michal Vasko4e6d3242021-05-26 09:13:24 +0200407/** @} Client SSH */
Radek Krejci6799a052017-05-19 14:23:23 +0200408
Radek Krejci53691be2016-02-22 13:58:37 +0100409#endif /* NC_ENABLED_SSH */
Michal Vasko086311b2016-01-08 09:53:11 +0100410
Radek Krejci53691be2016-02-22 13:58:37 +0100411#ifdef NC_ENABLED_TLS
Michal Vasko086311b2016-01-08 09:53:11 +0100412
413/**
Radek Krejci6799a052017-05-19 14:23:23 +0200414 * @defgroup client_tls Client TLS
415 * @ingroup client
416 *
417 * @brief Client-side settings for TLS connections.
418 * @{
419 */
420
421/**
Michal Vasko3031aae2016-01-27 16:07:18 +0100422 * @brief Set client authentication identity - a certificate and a private key.
Michal Vasko086311b2016-01-08 09:53:11 +0100423 *
Michal Vaskoe22c6732016-01-29 11:03:02 +0100424 * @param[in] client_cert Path to the file containing the client certificate.
Michal Vaskoc446a382021-06-18 08:54:05 +0200425 * @param[in] client_key Path to the file containing the private key for the @p client_cert.
426 * If NULL, key is expected to be stored with @p client_cert.
Michal Vasko3031aae2016-01-27 16:07:18 +0100427 * @return 0 on success, -1 on error.
428 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100429int nc_client_tls_set_cert_key_paths(const char *client_cert, const char *client_key);
Michal Vasko3031aae2016-01-27 16:07:18 +0100430
431/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100432 * @brief Get client authentication identity - a certificate and a private key.
433 *
Michal Vaskoe22c6732016-01-29 11:03:02 +0100434 * @param[out] client_cert Path to the file containing the client certificate. Can be NULL.
Michal Vaskoc446a382021-06-18 08:54:05 +0200435 * @param[out] client_key Path to the file containing the private key for the @p client_cert. Can be NULL.
Michal Vaskoe22c6732016-01-29 11:03:02 +0100436 */
437void nc_client_tls_get_cert_key_paths(const char **client_cert, const char **client_key);
438
439/**
440 * @brief Set client trusted CA certificates paths.
Michal Vasko3031aae2016-01-27 16:07:18 +0100441 *
Michal Vasko086311b2016-01-08 09:53:11 +0100442 * @param[in] ca_file Location of the CA certificate file used to verify server certificates.
443 * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
444 * @param[in] ca_dir Location of the CA certificates directory used to verify the server certificates.
445 * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
Michal Vasko3031aae2016-01-27 16:07:18 +0100446 * @return 0 on success, -1 on error.
447 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100448int nc_client_tls_set_trusted_ca_paths(const char *ca_file, const char *ca_dir);
Michal Vasko3031aae2016-01-27 16:07:18 +0100449
450/**
Michal Vaskoe22c6732016-01-29 11:03:02 +0100451 * @brief Get client trusted CA certificates paths.
452 *
453 * @param[out] ca_file Location of the CA certificate file used to verify server certificates.
454 * Can be NULL.
455 * @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates.
456 * Can be NULL.
457 */
458void nc_client_tls_get_trusted_ca_paths(const char **ca_file, const char **ca_dir);
459
460/**
461 * @brief Set client Certificate Revocation List paths.
Michal Vasko3031aae2016-01-27 16:07:18 +0100462 *
Michal Vasko086311b2016-01-08 09:53:11 +0100463 * @param[in] crl_file Location of the CRL certificate file used to check for revocated certificates.
464 * @param[in] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
Michal Vasko3031aae2016-01-27 16:07:18 +0100465 * @return 0 on success, -1 on error.
466 */
Michal Vaskoe22c6732016-01-29 11:03:02 +0100467int nc_client_tls_set_crl_paths(const char *crl_file, const char *crl_dir);
468
469/**
470 * @brief Get client Certificate Revocation List paths.
471 *
472 * @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates.
473 * @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
474 */
475void nc_client_tls_get_crl_paths(const char **crl_file, const char **crl_dir);
Michal Vasko3031aae2016-01-27 16:07:18 +0100476
Michal Vasko3031aae2016-01-27 16:07:18 +0100477/**
Michal Vasko086311b2016-01-08 09:53:11 +0100478 * @brief Connect to the NETCONF server using TLS transport (via libssl)
479 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100480 * 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 +0100481 * If the caller needs to use specific TLS session properties, they are supposed to use nc_connect_libssl().
482 *
Michal Vasko086311b2016-01-08 09:53:11 +0100483 * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
484 * 'localhost' is used by default if NULL is specified.
485 * @param[in] port Port number of the target server. Default value 6513 is used if 0 is specified.
486 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
487 * (ignoring what is actually supported by the server side). If not set,
488 * YANG context is created for the session using \<get-schema\> (if supported
489 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100490 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100491 * to connect to a server supporting \<get-schema\> it is possible that
492 * the session context will not include all the models supported by the server.
493 * @return Created NETCONF session object or NULL on error.
494 */
495struct nc_session *nc_connect_tls(const char *host, uint16_t port, struct ly_ctx *ctx);
496
497/**
498 * @brief Connect to the NETCONF server using the provided TLS (libssl) session.
499 *
500 * The TLS session supplied is expected to be fully connected and authenticated!
501 *
Michal Vasko086311b2016-01-08 09:53:11 +0100502 * @param[in] tls libssl structure representing the TLS session object.
503 * @param[in] ctx Optional parameter. If set, provides strict YANG context for the session
504 * (ignoring what is actually supported by the server side). If not set,
505 * YANG context is created for the session using \<get-schema\> (if supported
506 * by the server side) or/and by searching for YANG schemas in the searchpath
Radek Krejcic9a6d252016-03-04 14:50:34 +0100507 * (see nc_client_schema_searchpath()). In every case except not providing context
Michal Vasko086311b2016-01-08 09:53:11 +0100508 * to connect to a server supporting \<get-schema\> it is possible that
509 * the session context will not include all the models supported by the server.
510 * @return Created NETCONF session object or NULL on error.
511 */
512struct nc_session *nc_connect_libssl(SSL *tls, struct ly_ctx *ctx);
513
Michal Vasko4e6d3242021-05-26 09:13:24 +0200514/** @} Client TLS */
Radek Krejci6799a052017-05-19 14:23:23 +0200515
Radek Krejci53691be2016-02-22 13:58:37 +0100516#endif /* NC_ENABLED_TLS */
Michal Vasko086311b2016-01-08 09:53:11 +0100517
518/**
Radek Krejci6799a052017-05-19 14:23:23 +0200519 * @addtogroup client_session
520 * @{
521 */
522
523/**
Michal Vaskobdfb5242016-05-24 09:11:01 +0200524 * @brief Get session capabilities.
525 *
526 * @param[in] session Session to get the information from.
Michal Vaskoc446a382021-06-18 08:54:05 +0200527 * @return NULL-terminated array of the @p session capabilities.
Michal Vaskobdfb5242016-05-24 09:11:01 +0200528 */
Michal Vasko1b2ddc92017-05-24 08:59:49 +0200529const char * const *nc_session_get_cpblts(const struct nc_session *session);
Michal Vaskobdfb5242016-05-24 09:11:01 +0200530
531/**
532 * @brief Check capability presence in a session.
533 *
534 * @param[in] session Session to check.
535 * @param[in] capab Capability to look for, capability with any additional suffix will match.
536 * @return Matching capability, NULL if none found.
537 */
538const char *nc_session_cpblt(const struct nc_session *session, const char *capab);
539
540/**
Michal Vasko9cd26a82016-05-31 08:58:48 +0200541 * @brief Check whether the session has a notification thread running.
542 *
543 * @param[in] session Session to check.
544 * @return 1 if notfication thread is running, 0 otherwise.
545 */
546int nc_session_ntf_thread_running(const struct nc_session *session);
547
548/**
Michal Vasko086311b2016-01-08 09:53:11 +0100549 * @brief Receive NETCONF RPC reply.
550 *
tadeas-vintrlik399af302021-08-25 10:32:21 +0200551 * @note This function can be called in a single thread only.
552 *
Michal Vasko086311b2016-01-08 09:53:11 +0100553 * @param[in] session NETCONF session from which the function gets data. It must be the
Michal Vasko77367452021-02-16 16:32:18 +0100554 * client side session object.
Michal Vasko086311b2016-01-08 09:53:11 +0100555 * @param[in] rpc Original RPC this should be the reply to.
556 * @param[in] msgid Expected message ID of the reply.
557 * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
Michal Vasko77367452021-02-16 16:32:18 +0100558 * waiting and 0 for immediate return if data are not available on the wire.
559 * @param[out] envp NETCONF rpc-reply XML envelopes.
560 * @param[out] op Parsed NETCONF reply data, if any (none for \<ok\> or error replies). Set only on #NC_MSG_REPLY
561 * and #NC_MSG_REPLY_ERR_MSGID return.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200562 * @return #NC_MSG_REPLY for success,
Michal Vaskoc446a382021-06-18 08:54:05 +0200563 * #NC_MSG_WOULDBLOCK if @p timeout has elapsed,
Michal Vasko71ba2da2016-05-04 10:53:16 +0200564 * #NC_MSG_ERROR if reading has failed,
565 * #NC_MSG_NOTIF if a notification was read instead (call this function again to get the reply), and
566 * #NC_MSG_REPLY_ERR_MSGID if a reply with missing or wrong message-id was received.
Michal Vasko086311b2016-01-08 09:53:11 +0100567 */
Michal Vaskod083db62016-01-19 10:31:29 +0100568NC_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 +0100569 struct lyd_node **envp, struct lyd_node **op);
Michal Vasko086311b2016-01-08 09:53:11 +0100570
571/**
572 * @brief Receive NETCONF Notification.
573 *
574 * @param[in] session NETCONF session from which the function gets data. It must be the
575 * client side session object.
576 * @param[in] timeout Timeout for reading in milliseconds. Use negative value for infinite
Michal Vasko71ba2da2016-05-04 10:53:16 +0200577 * waiting and 0 for immediate return if data are not available on the wire.
Michal Vasko77367452021-02-16 16:32:18 +0100578 * @param[out] envp NETCONF notification XML envelopes.
579 * @param[out] op Parsed NETCONF notification data.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200580 * @return #NC_MSG_NOTIF for success,
Michal Vaskoc446a382021-06-18 08:54:05 +0200581 * #NC_MSG_WOULDBLOCK if @p timeout has elapsed,
Michal Vasko71ba2da2016-05-04 10:53:16 +0200582 * #NC_MSG_ERROR if reading has failed, and
583 * #NC_MSG_REPLY if a reply was read instead (call this function again to get a notification).
Michal Vasko086311b2016-01-08 09:53:11 +0100584 */
Michal Vasko77367452021-02-16 16:32:18 +0100585NC_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 +0100586
587/**
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100588 * @brief Receive NETCONF Notifications in a separate thread until the session is terminated
589 * or \<notificationComplete\> is received.
590 *
591 * @param[in] session Netconf session to read notifications from.
592 * @param[in] notif_clb Function that is called for every received notification (including
593 * \<notificationComplete\>). Parameters are the session the notification was received on
Michal Vasko77367452021-02-16 16:32:18 +0100594 * and the notification data.
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100595 * @return 0 if the thread was successfully created, -1 on error.
596 */
597int nc_recv_notif_dispatch(struct nc_session *session,
Michal Vasko77367452021-02-16 16:32:18 +0100598 void (*notif_clb)(struct nc_session *session, const struct lyd_node *envp, const struct lyd_node *op));
Michal Vaskoa8ad4482016-01-28 14:25:54 +0100599
600/**
Michal Vasko086311b2016-01-08 09:53:11 +0100601 * @brief Send NETCONF RPC message via the session.
602 *
603 * @param[in] session NETCONF session where the RPC will be written.
604 * @param[in] rpc NETCOFN RPC object to send via specified session. Object can be created by
605 * nc_rpc_lock(), nc_rpc_unlock() and nc_rpc_generic() functions.
606 * @param[in] timeout Timeout for writing in milliseconds. Use negative value for infinite
607 * waiting and 0 for return if data cannot be sent immediately.
608 * @param[out] msgid If RPC was successfully sent, this is it's message ID.
Michal Vasko71ba2da2016-05-04 10:53:16 +0200609 * @return #NC_MSG_RPC on success,
610 * #NC_MSG_WOULDBLOCK in case of a busy session, and
611 * #NC_MSG_ERROR on error.
Michal Vasko086311b2016-01-08 09:53:11 +0100612 */
Michal Vaskod083db62016-01-19 10:31:29 +0100613NC_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 +0100614
Michal Vaskode2946c2017-01-12 12:19:26 +0100615/**
616 * @brief Make a session not strict when sending RPCs and receiving RPC replies. In other words,
617 * it will silently skip unknown nodes without an error.
618 *
619 * Generally, no such data should be worked with, so use this function only when you know what you
620 * are doing and you understand the consequences.
621 *
622 * @param[in] session NETCONF client session.
623 */
624void nc_client_session_set_not_strict(struct nc_session *session);
625
Michal Vasko77367452021-02-16 16:32:18 +0100626/** @} Client Session */
Radek Krejci6799a052017-05-19 14:23:23 +0200627
Michal Vaskoc09730e2019-01-17 10:07:26 +0100628#ifdef __cplusplus
629}
630#endif
631
Michal Vasko086311b2016-01-08 09:53:11 +0100632#endif /* NC_SESSION_CLIENT_H_ */