blob: a61eaf2fc3d51041ea2b66dfd8c1488bca46f8b7 [file] [log] [blame]
Radek Krejcid0d19522015-09-02 13:49:25 +02001/**
2 * \file libnetconf.h
3 * \author Radek Krejci <rkrejci@cesnet.cz>
Michal Vaskofdfd9dd2016-02-29 10:18:46 +01004 * \author Michal Vasko <mvasko@cesnet.cz>
Radek Krejcid0d19522015-09-02 13:49:25 +02005 * \brief libnetconf2 main internal header.
6 *
7 * Copyright (c) 2015 CESNET, z.s.p.o.
8 *
Radek Krejci9b81f5b2016-02-24 13:14:49 +01009 * This source code is licensed under BSD 3-Clause License (the "License").
10 * You may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
Michal Vaskoafd416b2016-02-25 14:51:46 +010012 *
Radek Krejci9b81f5b2016-02-24 13:14:49 +010013 * https://opensource.org/licenses/BSD-3-Clause
Radek Krejcid0d19522015-09-02 13:49:25 +020014 */
15
16#ifndef NC_LIBNETCONF_H_
17#define NC_LIBNETCONF_H_
18
19#include "config.h"
Radek Krejci206fcd62015-10-07 15:42:48 +020020#include "netconf.h"
Radek Krejcid0d19522015-09-02 13:49:25 +020021#include "log_p.h"
Radek Krejciac6d3472015-10-22 15:47:18 +020022#include "session_p.h"
23#include "messages_p.h"
Radek Krejciac6d3472015-10-22 15:47:18 +020024
25/* Tests whether string is empty or non-empty. */
26#define strisempty(str) ((str)[0] == '\0')
27#define strnonempty(str) ((str)[0] != '\0')
Radek Krejcid0d19522015-09-02 13:49:25 +020028
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010029/**
30 * @mainpage About
31 *
32 * libnetconf2 is a NETCONF library in C handling NETCONF authentication and all NETCONF
Radek Krejcib62d5b42017-05-19 10:20:00 +020033 * RPC communication both server and client-side. Note that NETCONF datastore implementation
34 * is not a part of this library. The library supports both NETCONF 1.0
35 * ([RFC 4741](https://tools.ietf.org/html/rfc4741)) as well as NETCONF 1.1
36 * ([RFC 6241](https://tools.ietf.org/html/rfc6241)).
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010037 *
38 * @section about-features Main Features
39 *
Radek Krejcib62d5b42017-05-19 10:20:00 +020040 * - Creating SSH ([RFC 4742](https://tools.ietf.org/html/rfc4742), [RFC 6242](https://tools.ietf.org/html/rfc6242)),
41 * using [libssh](https://www.libssh.org/), or TLS ([RFC 7589](https://tools.ietf.org/html/rfc7589)),
42 * using [OpenSSL](https://www.openssl.org/), authenticated NETCONF sessions.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010043 * - Creating NETCONF sessions with a pre-established transport protocol
44 * (using this mechanism the communication can be tunneled through sshd(8), for instance).
Radek Krejcib62d5b42017-05-19 10:20:00 +020045 * - Creating NETCONF Call Home sessions ([RFC 8071](https://tools.ietf.org/html/rfc8071)).
46 * - Creating, sending, receiving, and replying to RPCs ([RFC 4741](https://tools.ietf.org/html/rfc4741),
47 * [RFC 6241](https://tools.ietf.org/html/rfc6241)).
48 * - Creating, sending and receiving NETCONF Event Notifications ([RFC 5277](https://tools.ietf.org/html/rfc5277)),
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010049 *
50 * @section about-license License
51 *
Michal Vaskoee087c62017-02-15 11:27:16 +010052 * Copyright (c) 2015-2017 CESNET, z.s.p.o.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010053 *
54 * (The BSD 3-Clause License)
55 *
56 * Redistribution and use in source and binary forms, with or without
57 * modification, are permitted provided that the following conditions
58 * are met:
59 * 1. Redistributions of source code must retain the above copyright
60 * notice, this list of conditions and the following disclaimer.
61 * 2. Redistributions in binary form must reproduce the above copyright
62 * notice, this list of conditions and the following disclaimer in
63 * the documentation and/or other materials provided with the
64 * distribution.
65 * 3. Neither the name of the Company nor the names of its contributors
66 * may be used to endorse or promote products derived from this
67 * software without specific prior written permission.
68 */
69
70/**
71 * @page howto How To ...
72 *
73 * - @subpage howtoinit
74 * - @subpage howtoclient
75 * - @subpage howtoserver
76 * - @subpage howtoclientcomm
77 * - @subpage howtoservercomm
Michal Vaskoee087c62017-02-15 11:27:16 +010078 * - @subpage howtotimeouts
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010079 */
80
81/**
82 * @page howtoinit Init and Thread-safety Information
83 *
Michal Vaskoa7b8ca52016-03-01 12:09:29 +010084 * Before working with the library, it must be initialized using nc_client_init()
Radek Krejci5cebc6b2017-05-26 13:24:38 +020085 * or nc_server_init(). Based on how the library was compiled, also _libssh_ and/or
86 * _libssh_/_libcrypto_ are initialized (for multi-threaded use) too. To prevent
87 * any reachable memory at the end of your application, there are complementary
88 * destroy functions (nc_server_destroy() and nc_client_destroy() available. If your
89 * application is multi-threaded, call the destroy functions in the main thread,
90 * after all the other threads have ended. In every other thread you should call
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010091 * nc_thread_destroy() just before it exits.
92 *
Michal Vasko15b7a982016-03-02 10:53:31 +010093 * If _libnetconf2_ is used in accordance with this information, there should
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010094 * not be memory leaks of any kind at program exit. For thread-safety details
Michal Vasko15b7a982016-03-02 10:53:31 +010095 * of _libssh_, _libssl_, and _libcrypto_, please refer to the corresponding project
96 * documentation. _libnetconf2_ thread-safety information is below.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +010097 *
Radek Krejci5cebc6b2017-05-26 13:24:38 +020098 * Client
99 * ------
100 *
Radek Krejcifd5b6682017-06-13 15:52:53 +0200101 * Optionally, a client can specify two alternative ways to get schemas needed when connecting
102 * with a server. The primary way is to read local files in searchpath (and its subdirectories)
103 * specified via nc_client_set_schema_searchpath(). Alternatively, _libnetconf2_ can use callback
104 * provided via nc_client_set_schema_callback(). If these ways do not succeed and the server
105 * implements NETCONF \<get-schema\> operation, the schema is retrieved from the server and stored
106 * localy into the searchpath (if specified) for a future use. If none of these methods succeed to
107 * load particular schema, the data from this schema are ignored during the communication with the
108 * server.
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200109 *
Radek Krejcifd5b6682017-06-13 15:52:53 +0200110 * Besides the mentioned setters, there are many other @ref howtoclientssh "SSH", @ref howtoclienttls "TLS"
111 * and @ref howtoclientch "Call Home" getter/setter functions to manipulate with various settings. All these
112 * settings are internally placed in a thread-specific context so they are independent and
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200113 * initialized to the default values within each new thread. However, the context can be shared among
114 * the threads using nc_client_get_thread_context() and nc_client_set_thread_context() functions. In such
115 * a case, be careful and avoid concurrent execution of the mentioned setters/getters and functions
116 * creating connection (no matter if it is a standard NETCONF connection or Call Home).
117 *
118 * In the client, it is thread-safe to work with distinguish NETCONF sessions since the client
119 * settings are thread-specific as described above.
120 *
121 * Server
122 * ------
123 *
124 * Server is __FULLY__ thread-safe meaning you can set all the (thread-shared in contrast to
125 * client) options simultaneously while listening for or accepting new sessions or
Michal Vaskoade892d2017-02-22 13:40:35 +0100126 * polling the existing ones. It is even safe to poll one session in several
127 * pollsession structures or one pollsession structure in several threads. Generally,
128 * servers can use more threads without any problems as long as they keep their workflow sane
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100129 * (behavior such as freeing sessions only after no thread uses them or similar).
130 *
131 * Functions List
132 * --------------
133 *
Michal Vaskoa7b8ca52016-03-01 12:09:29 +0100134 * Available in __nc_client.h__.
135 *
136 * - nc_client_init()
137 * - nc_client_destroy()
138 *
Michal Vasko26394692016-03-17 16:24:55 +0100139 * - nc_client_get_schema_searchpath()
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200140 * - nc_client_set_schema_searchpath()
Radek Krejcifd5b6682017-06-13 15:52:53 +0200141 * - nc_client_get_schema_callback()
142 * - nc_client_set_schema_callback()
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200143 *
144 * - nc_client_get_thread_context()
145 * - nc_client_set_thread_context()
Michal Vasko26394692016-03-17 16:24:55 +0100146 *
Michal Vaskoa7b8ca52016-03-01 12:09:29 +0100147 * Available in __nc_server.h__.
148 *
149 * - nc_server_init()
150 * - nc_server_destroy()
151 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100152 * Available in both __nc_client.h__ and __nc_server.h__.
153 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100154 * - nc_thread_destroy()
155 */
156
157/**
158 * @page howtoclient Client sessions
159 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100160 * To connect to a NETCONF server, a NETCONF session must be established,
161 * which requires a working transport session. It is possible to create
162 * NETCONF sessions with SSH (using _libssh_) or TLS (using _libssl/libcrypto_)
163 * as the underlying transport protocol. It is also possible to establish
164 * the transport protocol outside _libnetconf2_ and then provide these file
165 * descriptors (FD) for full NETCONF session creation.
166 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100167 * There are a lot of options for both an SSH and a TLS client. All of them
168 * have setters and getters so that there is no need to duplicate them in
169 * a client.
170 *
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200171 * @anchor howtoclientssh
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100172 * SSH
173 * ===
174 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100175 * Connecting to a server using SSH does not strictly require to set any
176 * options, there are sensible default values for all the basic ones.
177 * Except all the SSH options, optionally some authetication callbacks can be set,
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100178 * which are particulary useful in automated clients (passwords cannot be
179 * asked a user) or simply if any additional information is retrieved some
180 * other way than from standard terminal input.
181 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100182 * Having the default options or changing any unsuitable ones, there are 2 functions
183 * to use for a new server connection. nc_connect_ssh() is the standard function
184 * that creates sessions using the set options. If there are some options, which
185 * cannot be changed with the provided API, there is nc_connect_libssh() available.
186 * It requires a _libssh_ session, in which all the SSH options can be modified
187 * and even the connection established. This allows for full customization and
188 * should fit any specific situation.
189 *
190 * New NETCONF sessions can also be created on existing authenticated SSH sessions.
191 * There is a new SSH channel needed, on which the NETCONF session is then created.
192 * Use nc_connect_ssh_channel() for this purpose.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100193 *
194 * Functions List
195 * --------------
196 *
197 * Available in __nc_client.h__.
198 *
199 * - nc_client_ssh_set_auth_hostkey_check_clb()
200 * - nc_client_ssh_set_auth_password_clb()
201 * - nc_client_ssh_set_auth_interactive_clb()
202 * - nc_client_ssh_set_auth_privkey_passphrase_clb()
203 * - nc_client_ssh_add_keypair()
204 * - nc_client_ssh_del_keypair()
205 * - nc_client_ssh_get_keypair_count()
206 * - nc_client_ssh_get_keypair()
207 * - nc_client_ssh_set_auth_pref()
208 * - nc_client_ssh_get_auth_pref()
209 * - nc_client_ssh_set_username()
210 * - nc_client_ssh_get_username()
211 *
212 * - nc_connect_ssh()
213 * - nc_connect_libssh()
214 * - nc_connect_ssh_channel()
215 *
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200216 * @anchor howtoclienttls
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100217 * TLS
218 * ===
219 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100220 * To connect to a server using TLS, there must be some client identification
221 * options set. Client must specify its certificate with a private key using
222 * nc_client_tls_set_cert_key_paths(). Also, the Certificate Authority of
223 * a server certificate must be considered trusted. Paths to all the trusted
224 * CA certificates can be set by nc_client_tls_set_trusted_ca_paths().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100225 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100226 * Then there are again 2 functions for connecting, nc_connect_tls() being
227 * the standard way of connecting. nc_connect_libssl() again enables
228 * to customize the TLS session in every way _libssl_ allows.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100229 *
230 * Functions List
231 * --------------
232 *
233 * Available in __nc_client.h__.
234 *
235 * - nc_client_tls_set_cert_key_paths()
236 * - nc_client_tls_get_cert_key_paths()
237 * - nc_client_tls_set_trusted_ca_paths()
238 * - nc_client_tls_get_trusted_ca_paths()
239 * - nc_client_tls_set_crl_paths()
240 * - nc_client_tls_get_crl_paths()
241 *
242 * - nc_connect_tls()
243 * - nc_connect_libssl()
244 *
245 *
246 * FD
247 * ==
248 *
249 * If you authenticated the connection using some tunneling software, you
Michal Vasko15b7a982016-03-02 10:53:31 +0100250 * can pass its file descriptors to _libnetconf2_ using nc_connect_inout(),
251 * which will continue to establish a full NETCONF session.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100252 *
253 * Funtions List
254 * -------------
255 *
256 * Available in __nc_client.h__.
257 *
258 * - nc_connect_inout()
259 *
260 *
Radek Krejci5cebc6b2017-05-26 13:24:38 +0200261 * @anchor howtoclientch
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100262 * Call Home
263 * =========
264 *
265 * Call Home needs the same options set as standard SSH or TLS and the functions
266 * reflect it exactly. However, to accept a connection, the client must first
Michal Vasko15b7a982016-03-02 10:53:31 +0100267 * specify addresses and ports, which to listen on by nc_client_ssh_ch_add_bind_listen()
268 * and nc_client_tls_ch_add_bind_listen(). Then connections can be
269 * accepted using nc_accept_callhome().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100270 *
271 * Functions List
272 * --------------
273 *
274 * Available in __nc_client.h__.
275 *
276 * - nc_client_ssh_ch_set_auth_hostkey_check_clb()
277 * - nc_client_ssh_ch_set_auth_password_clb()
278 * - nc_client_ssh_ch_set_auth_interactive_clb()
279 * - nc_client_ssh_ch_set_auth_privkey_passphrase_clb()
280 * - nc_client_ssh_ch_add_bind_listen()
281 * - nc_client_ssh_ch_del_bind()
282 * - nc_client_ssh_ch_add_keypair()
283 * - nc_client_ssh_ch_del_keypair()
284 * - nc_client_ssh_ch_get_keypair_count()
285 * - nc_client_ssh_ch_get_keypair()
286 * - nc_client_ssh_ch_set_auth_pref()
287 * - nc_client_ssh_ch_get_auth_pref()
288 * - nc_client_ssh_ch_set_username()
289 * - nc_client_ssh_ch_get_username()
290 *
291 * - nc_client_tls_ch_add_bind_listen()
292 * - nc_client_tls_ch_del_bind()
293 * - nc_client_tls_ch_set_cert_key_paths()
294 * - nc_client_tls_ch_get_cert_key_paths()
295 * - nc_client_tls_ch_set_trusted_ca_paths()
296 * - nc_client_tls_ch_get_trusted_ca_paths()
297 * - nc_client_tls_ch_set_crl_paths()
298 * - nc_client_tls_ch_get_crl_paths()
299 *
300 * - nc_accept_callhome()
301 *
302 *
303 * Cleanup
304 * =======
305 *
306 * These options and the schema searchpath are stored in dynamically
Michal Vasko15b7a982016-03-02 10:53:31 +0100307 * allocated memory. They are freed as a part of [destroying the client](@ref howtoinit).
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100308 */
309
310/**
311 * @page howtoserver Server sessions
312 *
313 * Init
314 * ====
315 *
Michal Vaskoa7b8ca52016-03-01 12:09:29 +0100316 * Server takes an argument for its [initialization function](@ref howtoinit).
317 * In it, you set the server context, which determines what modules it
318 * supports and what capabilities to advertise. Few capabilities that
Michal Vasko15b7a982016-03-02 10:53:31 +0100319 * cannot be learnt from the context are set with separate functions
Michal Vaskod31b76e2017-02-15 12:18:06 +0100320 * nc_server_set_capab_withdefaults() and generally nc_server_set_capability().
Michal Vasko15b7a982016-03-02 10:53:31 +0100321 * Timeout for receiving the _hello_ message on a new session can be set
322 * by nc_server_set_hello_timeout() and the timeout for disconnecting
323 * an inactive session by nc_server_set_idle_timeout().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100324 *
325 * Context does not only determine server modules, but its overall
326 * functionality as well. For every RPC the server should support,
Michal Vasko3a889fd2016-09-30 12:16:37 +0200327 * an nc_rpc_clb callback should be set on that node in the context using nc_set_rpc_callback().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100328 * Server then calls these as appropriate [during poll](@ref howtoservercomm).
329 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100330 * Just like in the [client](@ref howtoclient), you can let _libnetconf2_
331 * establish SSH or TLS transport or do it yourself and only provide the file
332 * descriptors of the connection.
333 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100334 * Server options can be only set, there are no getters.
335 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100336 * To be able to accept any connections, endpoints must first be added
337 * with nc_server_add_endpt() and configured with nc_server_endpt_set_address()
Olivier Matzac7fa2f2018-10-11 10:02:04 +0200338 * and nc_server_endpt_set_port(). For unix sockets, nc_server_endpt_set_perms()
339 * is available to set the unix socket file permissions, and nc_server_endpt_set_port()
340 * is invalid.
Michal Vasko3a889fd2016-09-30 12:16:37 +0200341 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100342 * Functions List
343 * --------------
344 *
345 * Available in __nc_server.h__.
346 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100347 * - nc_server_set_capab_withdefaults()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100348 * - nc_server_set_capability()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100349 * - nc_server_set_hello_timeout()
350 * - nc_server_set_idle_timeout()
351 *
Michal Vasko3a889fd2016-09-30 12:16:37 +0200352 * - nc_server_add_endpt()
353 * - nc_server_del_endpt()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100354 * - nc_server_endpt_set_address()
355 * - nc_server_endpt_set_port()
Olivier Matzac7fa2f2018-10-11 10:02:04 +0200356 * - nc_server_endpt_set_perms()
Michal Vasko3a889fd2016-09-30 12:16:37 +0200357 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100358 *
359 * SSH
360 * ===
361 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100362 * To successfully accept an SSH session you must set at least the host key using
363 * nc_server_ssh_endpt_add_hostkey(), which are ordered. This way you simply add
364 * some hostkey identifier, but the key itself will be retrieved always when needed
365 * by calling the callback set by nc_server_ssh_set_hostkey_clb().
366 *
367 * There are also some other optional settings. Note that authorized
368 * public keys are set for the server as a whole, not endpoint-specifically.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100369 *
370 * Functions List
371 * --------------
372 *
373 * Available in __nc_server.h__.
374 *
Michal Vasko3a889fd2016-09-30 12:16:37 +0200375 * - nc_server_ssh_endpt_add_hostkey()
376 * - nc_server_ssh_endpt_del_hostkey()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100377 * - nc_server_ssh_endpt_mov_hostkey()
378 * - nc_server_ssh_endpt_mod_hostkey()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100379 * - nc_server_ssh_endpt_set_banner()
380 * - nc_server_ssh_endpt_set_auth_methods()
381 * - nc_server_ssh_endpt_set_auth_attempts()
382 * - nc_server_ssh_endpt_set_auth_timeout()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100383 *
384 * - nc_server_ssh_set_hostkey_clb()
385 *
386 * - nc_server_ssh_add_authkey()
387 * - nc_server_ssh_add_authkey_path()
388 * - nc_server_ssh_del_authkey()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100389 *
390 *
391 * TLS
392 * ===
393 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100394 * TLS works with endpoints too, but its options differ
395 * significantly from the SSH ones, especially in the _cert-to-name_
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100396 * options that TLS uses to derive usernames from client certificates.
Michal Vaskod31b76e2017-02-15 12:18:06 +0100397 * So, after starting listening on an endpoint you need to set the server
398 * certificate (nc_server_tls_endpt_set_server_cert()). Its actual content
399 * together with the matching private key will be loaded using a callback
Andrew Langefeld440b6c72018-08-27 16:26:20 -0500400 * from nc_server_tls_set_server_cert_clb(). Additional certificates needed
401 * for the client to verify the server's certificate chain can be loaded using
402 * a callback from nc_server_tls_set_server_cert_chain_clb().
Michal Vasko15b7a982016-03-02 10:53:31 +0100403 *
404 * To accept client certificates, they must first be considered trusted,
405 * which you have three ways of achieving. You can add each of their Certificate Authority
406 * certificates to the trusted ones or mark a specific client certificate
Michal Vaskod31b76e2017-02-15 12:18:06 +0100407 * as trusted. Lastly, you can set paths with all the trusted CA certificates
408 * with nc_server_tls_endpt_set_trusted_ca_paths(). Adding specific certificates
409 * is also performed only as an arbitrary identificator and later retrieved from
410 * callback set by nc_server_tls_set_trusted_cert_list_clb(). But, you can add
411 * certficates as whole lists, not one-by-one.
Michal Vasko15b7a982016-03-02 10:53:31 +0100412 *
413 * Then, from each trusted client certificate a username must be derived
414 * for the NETCONF session. This is accomplished by finding a matching
415 * _cert-to-name_ entry. They are added using nc_server_tls_endpt_add_ctn().
416 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100417 * If you need to remove trusted certificates, you can do so with nc_server_tls_endpt_del_trusted_cert_list().
Michal Vasko3a889fd2016-09-30 12:16:37 +0200418 * To clear all Certificate Revocation Lists use nc_server_tls_endpt_clear_crls().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100419 *
420 * Functions List
421 * --------------
422 *
423 * Available in __nc_server.h__.
424 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100425 * - nc_server_tls_endpt_set_server_cert()
426 * - nc_server_tls_endpt_add_trusted_cert_list()
427 * - nc_server_tls_endpt_del_trusted_cert_list()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100428 * - nc_server_tls_endpt_set_trusted_ca_paths()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100429 * - nc_server_tls_endpt_set_crl_paths()
430 * - nc_server_tls_endpt_clear_crls()
431 * - nc_server_tls_endpt_add_ctn()
432 * - nc_server_tls_endpt_del_ctn()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100433 * - nc_server_tls_endpt_get_ctn()
434 *
435 * - nc_server_tls_set_server_cert_clb()
Andrew Langefeld440b6c72018-08-27 16:26:20 -0500436 * - nc_server_tls_set_server_cert_chain_clb()
Michal Vaskod31b76e2017-02-15 12:18:06 +0100437 * - nc_server_tls_set_trusted_cert_list_clb()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100438 *
439 * FD
440 * ==
441 *
442 * If you used a tunneling software, which does its own authentication,
Michal Vasko15b7a982016-03-02 10:53:31 +0100443 * you can accept a NETCONF session on its file descriptors with
444 * nc_accept_inout().
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100445 *
446 * Functions List
447 * --------------
448 *
449 * Available in __nc_server.h__.
450 *
451 * - nc_accept_inout()
452 *
453 *
454 * Call Home
455 * =========
456 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100457 * _Call Home_ works with endpoints just like standard sessions, but
458 * the options are organized a bit differently and endpoints are added
459 * for CH clients. However, one important difference is that
460 * once all the mandatory options are set, _libnetconf2_ __will not__
461 * immediately start connecting to a client. It will do so only after
462 * calling nc_connect_ch_client_dispatch() in a separate thread.
463 *
464 * Lastly, monitoring of these sessions is up to the application.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100465 *
466 * Functions List
467 * --------------
468 *
469 * Available in __nc_server.h__.
470 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100471 * - nc_server_ch_add_client()
472 * - nc_server_ch_del_client()
473 * - nc_server_ch_client_add_endpt()
474 * - nc_server_ch_client_del_endpt()
475 * - nc_server_ch_client_endpt_set_address()
476 * - nc_server_ch_client_endpt_set_port()
477 * - nc_server_ch_client_set_conn_type()
478 * - nc_server_ch_client_persist_set_idle_timeout()
479 * - nc_server_ch_client_persist_set_keep_alive_max_wait()
480 * - nc_server_ch_client_persist_set_keep_alive_max_attempts()
481 * - nc_server_ch_client_period_set_idle_timeout()
482 * - nc_server_ch_client_period_set_reconnect_timeout()
483 * - nc_server_ch_client_set_start_with()
484 * - nc_server_ch_client_set_max_attempts()
485 * - nc_connect_ch_client_dispatch()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100486 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100487 * - nc_server_ssh_ch_client_add_hostkey()
488 * - nc_server_ssh_ch_client_del_hostkey()
489 * - nc_server_ssh_ch_client_mov_hostkey()
490 * - nc_server_ssh_ch_client_mod_hostkey()
491 * - nc_server_ssh_ch_client_set_banner()
492 * - nc_server_ssh_ch_client_set_auth_methods()
493 * - nc_server_ssh_ch_client_set_auth_attempts()
494 * - nc_server_ssh_ch_client_set_auth_timeout()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100495 *
Michal Vaskod31b76e2017-02-15 12:18:06 +0100496 * - nc_server_tls_ch_client_set_server_cert()
497 * - nc_server_tls_ch_client_add_trusted_cert_list()
498 * - nc_server_tls_ch_client_del_trusted_cert_list()
499 * - nc_server_tls_ch_client_set_trusted_ca_paths()
500 * - nc_server_tls_ch_client_set_crl_paths()
501 * - nc_server_tls_ch_client_clear_crls()
502 * - nc_server_tls_ch_client_add_ctn()
503 * - nc_server_tls_ch_client_del_ctn()
504 * - nc_server_tls_ch_client_get_ctn()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100505 *
506 *
507 * Connecting And Cleanup
508 * ======================
509 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100510 * When accepting connections with nc_accept(), all the endpoints are examined
Michal Vaskod31b76e2017-02-15 12:18:06 +0100511 * and the first with a pending connection is used. To remove all CH clients,
512 * endpoints, and free any used dynamic memory, [destroy](@ref howtoinit) the server.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100513 *
514 * Functions List
515 * --------------
516 *
517 * Available in __nc_server.h__.
518 *
519 * - nc_accept()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100520 */
521
522/**
523 * @page howtoclientcomm Client communication
524 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100525 * To send RPCs on a session, you simply create an RPC, send it using nc_send_rpc(),
526 * and then wait for a reply using nc_recv_reply(). If you are subscribed, there are 2 ways
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100527 * of receiving notifications. Either you wait for them the same way
Michal Vasko15b7a982016-03-02 10:53:31 +0100528 * as for standard replies with nc_recv_notif() or you create a dispatcher
529 * with nc_recv_notif_dispatch() that asynchronously (in a separate thread)
530 * reads notifications and passes them to your callback.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100531 *
532 * Functions List
533 * --------------
534 *
535 * Available in __nc_client.h__.
536 *
Michal Vasko3a889fd2016-09-30 12:16:37 +0200537 * - nc_rpc_act_generic()
538 * - nc_rpc_act_generic_xml()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100539 * - nc_rpc_getconfig()
540 * - nc_rpc_edit()
541 * - nc_rpc_copy()
542 * - nc_rpc_delete()
543 * - nc_rpc_lock()
544 * - nc_rpc_unlock()
545 * - nc_rpc_get()
546 * - nc_rpc_kill()
547 * - nc_rpc_commit()
548 * - nc_rpc_discard()
549 * - nc_rpc_cancel()
550 * - nc_rpc_validate()
551 * - nc_rpc_getschema()
552 * - nc_rpc_subscribe()
553 *
554 * - nc_send_rpc()
555 * - nc_recv_reply()
556 * - nc_recv_notif()
557 * - nc_recv_notif_dispatch()
558 */
559
560/**
561 * @page howtoservercomm Server communication
562 *
563 * Once at least one session is established, an nc_pollsession structure
Michal Vasko15b7a982016-03-02 10:53:31 +0100564 * should be created with nc_ps_new(), filled with the session using
565 * nc_ps_add_session() and finally polled with nc_ps_poll(). Based on
566 * the return value from the poll, further actions can be taken. More
567 * sessions can be polled at the same time and any requests received on
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100568 * the sessions are [handled internally](@ref howtoserver).
569 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100570 * If an SSH NETCONF session asks for a new channel, you can accept
Michal Vasko3a889fd2016-09-30 12:16:37 +0200571 * this request with nc_ps_accept_ssh_channel() or nc_session_accept_ssh_channel()
572 * depending on the structure you want to use as the argument.
Michal Vasko15b7a982016-03-02 10:53:31 +0100573 *
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100574 * Functions List
575 * --------------
576 *
Michal Vasko15b7a982016-03-02 10:53:31 +0100577 * Available in __nc_server.h__.
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100578 *
579 * - nc_ps_new()
580 * - nc_ps_add_session()
581 * - nc_ps_del_session()
Michal Vasko0fdb7ac2016-03-01 09:03:12 +0100582 * - nc_ps_session_count()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100583 * - nc_ps_free()
584 *
585 * - nc_ps_poll()
586 * - nc_ps_clear()
587 * - nc_ps_accept_ssh_channel()
Michal Vasko3a889fd2016-09-30 12:16:37 +0200588 * - nc_session_accept_ssh_channel()
Michal Vaskofdfd9dd2016-02-29 10:18:46 +0100589 */
590
Michal Vaskoee087c62017-02-15 11:27:16 +0100591/**
592 * @page howtotimeouts Timeouts
593 *
594 * There are several timeouts which are used throughout _libnetconf2_ to
595 * assure that it will never indefinitely hang on any operation. Normally,
596 * you should not need to worry about them much necause they are set by
597 * default to reasonable values for common systems. However, if your
598 * platform is not common (embedded, ...), adjusting these timeouts may
599 * save a lot of debugging and time.
600 *
601 * Compile Options
602 * ---------------
603 *
604 * You can adjust active and inactive read timeout using `cmake` variables.
605 * For details look into `README.md`.
606 *
607 * API Functions
608 * -------------
609 *
610 * Once a new connection is established including transport protocol negotiations,
611 * _hello_ message is exchanged. You can set how long will the server wait for
612 * receiving this message from a client before dropping it.
613 *
614 * Having a NETCONF session working, it may not communicate for a longer time.
615 * To free up some resources, it is possible to adjust the maximum idle period
616 * of a session before it is disconnected. In _Call Home_, for both a persistent
617 * and periodic connection can this idle timeout be specified separately for each
618 * client using corresponding functions.
619 *
620 * Lastly, SSH user authentication timeout can be also modified. It is the time
621 * a client has to successfully authenticate after connecting before it is disconnected.
622 *
623 * Functions List
624 * --------------
625 *
626 * Available in __nc_server.h__.
627 *
628 * - nc_server_set_hello_timeout()
629 * - nc_server_set_idle_timeout()
630 * - nc_server_ch_client_persist_set_idle_timeout()
631 * - nc_server_ch_client_period_set_idle_timeout()
632 * - nc_server_ch_client_period_set_reconnect_timeout()
633 * - nc_server_ssh_endpt_set_auth_timeout()
634 * - nc_server_ssh_ch_client_set_auth_timeout()
635 */
636
Radek Krejci6799a052017-05-19 14:23:23 +0200637/**
638 * @defgroup misc Miscellaneous
639 * @brief Miscellaneous macros, types, structure and functions for a generic use by both server and client applications.
640 */
641
642/**
643 * @defgroup client Client
644 * @brief NETCONF client functionality.
645 */
646
647/**
648 * @defgroup server Server
649 * @brief NETCONF server functionality.
650 */
651
Radek Krejcid0d19522015-09-02 13:49:25 +0200652#endif /* NC_LIBNETCONF_H_ */