1 2@subheading gnutls_alert_get 3@anchor{gnutls_alert_get} 4@deftypefun {gnutls_alert_description_t} {gnutls_alert_get} (gnutls_session_t @var{session}) 5@var{session}: is a @code{gnutls_session_t} type. 6 7This function will return the last alert number received. This 8function should be called when @code{GNUTLS_E_WARNING_ALERT_RECEIVED} or 9@code{GNUTLS_E_FATAL_ALERT_RECEIVED} errors are returned by a gnutls 10function. The peer may send alerts if he encounters an error. 11If no alert has been received the returned value is undefined. 12 13@strong{Returns:} the last alert received, a 14@code{gnutls_alert_description_t} value. 15@end deftypefun 16 17@subheading gnutls_alert_get_name 18@anchor{gnutls_alert_get_name} 19@deftypefun {const char *} {gnutls_alert_get_name} (gnutls_alert_description_t @var{alert}) 20@var{alert}: is an alert number. 21 22This function will return a string that describes the given alert 23number, or @code{NULL} . See @code{gnutls_alert_get()} . 24 25@strong{Returns:} string corresponding to @code{gnutls_alert_description_t} value. 26@end deftypefun 27 28@subheading gnutls_alert_get_strname 29@anchor{gnutls_alert_get_strname} 30@deftypefun {const char *} {gnutls_alert_get_strname} (gnutls_alert_description_t @var{alert}) 31@var{alert}: is an alert number. 32 33This function will return a string of the name of the alert. 34 35@strong{Returns:} string corresponding to @code{gnutls_alert_description_t} value. 36 37@strong{Since:} 3.0 38@end deftypefun 39 40@subheading gnutls_alert_send 41@anchor{gnutls_alert_send} 42@deftypefun {int} {gnutls_alert_send} (gnutls_session_t @var{session}, gnutls_alert_level_t @var{level}, gnutls_alert_description_t @var{desc}) 43@var{session}: is a @code{gnutls_session_t} type. 44 45@var{level}: is the level of the alert 46 47@var{desc}: is the alert description 48 49This function will send an alert to the peer in order to inform 50him of something important (eg. his Certificate could not be verified). 51If the alert level is Fatal then the peer is expected to close the 52connection, otherwise he may ignore the alert and continue. 53 54The error code of the underlying record send function will be 55returned, so you may also receive @code{GNUTLS_E_INTERRUPTED} or 56@code{GNUTLS_E_AGAIN} as well. 57 58@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 59an error code is returned. 60@end deftypefun 61 62@subheading gnutls_alert_send_appropriate 63@anchor{gnutls_alert_send_appropriate} 64@deftypefun {int} {gnutls_alert_send_appropriate} (gnutls_session_t @var{session}, int @var{err}) 65@var{session}: is a @code{gnutls_session_t} type. 66 67@var{err}: is an error code returned by another GnuTLS function 68 69Sends an alert to the peer depending on the error code returned by 70a gnutls function. This function will call @code{gnutls_error_to_alert()} 71to determine the appropriate alert to send. 72 73This function may also return @code{GNUTLS_E_AGAIN} , or 74@code{GNUTLS_E_INTERRUPTED} . 75 76This function historically was always sending an alert to the 77peer, even if @code{err} was inappropriate to respond with an alert 78(e.g., @code{GNUTLS_E_SUCCESS} ). Since 3.6.6 this function returns 79success without transmitting any data on error codes that 80should not result to an alert. 81 82@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 83an error code is returned. 84@end deftypefun 85 86@subheading gnutls_alpn_get_selected_protocol 87@anchor{gnutls_alpn_get_selected_protocol} 88@deftypefun {int} {gnutls_alpn_get_selected_protocol} (gnutls_session_t @var{session}, gnutls_datum_t * @var{protocol}) 89@var{session}: is a @code{gnutls_session_t} type. 90 91@var{protocol}: will hold the protocol name 92 93This function allows you to get the negotiated protocol name. The 94returned protocol should be treated as opaque, constant value and 95only valid during the session life. 96 97The selected protocol is the first supported by the list sent 98by the client. 99 100@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 101otherwise a negative error code is returned. 102 103Since 3.2.0 104@end deftypefun 105 106@subheading gnutls_alpn_set_protocols 107@anchor{gnutls_alpn_set_protocols} 108@deftypefun {int} {gnutls_alpn_set_protocols} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{protocols}, unsigned @var{protocols_size}, unsigned int @var{flags}) 109@var{session}: is a @code{gnutls_session_t} type. 110 111@var{protocols}: is the protocol names to add. 112 113@var{protocols_size}: the number of protocols to add. 114 115@var{flags}: zero or a sequence of @code{gnutls_alpn_flags_t} 116 117This function is to be used by both clients and servers, to declare 118the supported ALPN protocols, which are used during negotiation with peer. 119 120See @code{gnutls_alpn_flags_t} description for the documentation of available 121flags. 122 123@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 124otherwise a negative error code is returned. 125 126Since 3.2.0 127@end deftypefun 128 129@subheading gnutls_anon_allocate_client_credentials 130@anchor{gnutls_anon_allocate_client_credentials} 131@deftypefun {int} {gnutls_anon_allocate_client_credentials} (gnutls_anon_client_credentials_t * @var{sc}) 132@var{sc}: is a pointer to a @code{gnutls_anon_client_credentials_t} type. 133 134Allocate a gnutls_anon_client_credentials_t structure. 135 136@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 137@end deftypefun 138 139@subheading gnutls_anon_allocate_server_credentials 140@anchor{gnutls_anon_allocate_server_credentials} 141@deftypefun {int} {gnutls_anon_allocate_server_credentials} (gnutls_anon_server_credentials_t * @var{sc}) 142@var{sc}: is a pointer to a @code{gnutls_anon_server_credentials_t} type. 143 144Allocate a gnutls_anon_server_credentials_t structure. 145 146@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 147@end deftypefun 148 149@subheading gnutls_anon_free_client_credentials 150@anchor{gnutls_anon_free_client_credentials} 151@deftypefun {void} {gnutls_anon_free_client_credentials} (gnutls_anon_client_credentials_t @var{sc}) 152@var{sc}: is a @code{gnutls_anon_client_credentials_t} type. 153 154Free a gnutls_anon_client_credentials_t structure. 155@end deftypefun 156 157@subheading gnutls_anon_free_server_credentials 158@anchor{gnutls_anon_free_server_credentials} 159@deftypefun {void} {gnutls_anon_free_server_credentials} (gnutls_anon_server_credentials_t @var{sc}) 160@var{sc}: is a @code{gnutls_anon_server_credentials_t} type. 161 162Free a gnutls_anon_server_credentials_t structure. 163@end deftypefun 164 165@subheading gnutls_anon_set_params_function 166@anchor{gnutls_anon_set_params_function} 167@deftypefun {void} {gnutls_anon_set_params_function} (gnutls_anon_server_credentials_t @var{res}, gnutls_params_function * @var{func}) 168@var{res}: is a gnutls_anon_server_credentials_t type 169 170@var{func}: is the function to be called 171 172This function will set a callback in order for the server to get 173the Diffie-Hellman or RSA parameters for anonymous authentication. 174The callback should return @code{GNUTLS_E_SUCCESS} (0) on success. 175 176@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 177or later. Since 3.6.0, DH parameters are negotiated 178following RFC7919. 179@end deftypefun 180 181@subheading gnutls_anon_set_server_dh_params 182@anchor{gnutls_anon_set_server_dh_params} 183@deftypefun {void} {gnutls_anon_set_server_dh_params} (gnutls_anon_server_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) 184@var{res}: is a gnutls_anon_server_credentials_t type 185 186@var{dh_params}: The Diffie-Hellman parameters. 187 188This function will set the Diffie-Hellman parameters for an 189anonymous server to use. These parameters will be used in 190Anonymous Diffie-Hellman cipher suites. 191 192@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 193or later. Since 3.6.0, DH parameters are negotiated 194following RFC7919. 195@end deftypefun 196 197@subheading gnutls_anon_set_server_known_dh_params 198@anchor{gnutls_anon_set_server_known_dh_params} 199@deftypefun {int} {gnutls_anon_set_server_known_dh_params} (gnutls_anon_server_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) 200@var{res}: is a gnutls_anon_server_credentials_t type 201 202@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration 203 204This function will set the Diffie-Hellman parameters for an 205anonymous server to use. These parameters will be used in 206Anonymous Diffie-Hellman cipher suites and will be selected from 207the FFDHE set of RFC7919 according to the security level provided. 208 209@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 210or later. Since 3.6.0, DH parameters are negotiated 211following RFC7919. 212 213@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 214negative error value. 215 216@strong{Since:} 3.5.6 217@end deftypefun 218 219@subheading gnutls_anon_set_server_params_function 220@anchor{gnutls_anon_set_server_params_function} 221@deftypefun {void} {gnutls_anon_set_server_params_function} (gnutls_anon_server_credentials_t @var{res}, gnutls_params_function * @var{func}) 222@var{res}: is a gnutls_certificate_credentials_t type 223 224@var{func}: is the function to be called 225 226This function will set a callback in order for the server to get 227the Diffie-Hellman parameters for anonymous authentication. The 228callback should return @code{GNUTLS_E_SUCCESS} (0) on success. 229 230@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 231or later. Since 3.6.0, DH parameters are negotiated 232following RFC7919. 233@end deftypefun 234 235@subheading gnutls_anti_replay_deinit 236@anchor{gnutls_anti_replay_deinit} 237@deftypefun {void} {gnutls_anti_replay_deinit} (gnutls_anti_replay_t @var{anti_replay}) 238@var{anti_replay}: is a @code{gnutls_anti_replay} type 239 240This function will deinitialize all resources occupied by the given 241anti-replay context. 242 243@strong{Since:} 3.6.5 244@end deftypefun 245 246@subheading gnutls_anti_replay_enable 247@anchor{gnutls_anti_replay_enable} 248@deftypefun {void} {gnutls_anti_replay_enable} (gnutls_session_t @var{session}, gnutls_anti_replay_t @var{anti_replay}) 249@var{session}: is a @code{gnutls_session_t} type. 250 251@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. 252 253Request that the server should use anti-replay mechanism. 254 255@strong{Since:} 3.6.5 256@end deftypefun 257 258@subheading gnutls_anti_replay_init 259@anchor{gnutls_anti_replay_init} 260@deftypefun {int} {gnutls_anti_replay_init} (gnutls_anti_replay_t * @var{anti_replay}) 261@var{anti_replay}: is a pointer to @code{gnutls_anti_replay_t} type 262 263This function will allocate and initialize the @code{anti_replay} context 264to be usable for detect replay attacks. The context can then be 265attached to a @code{gnutls_session_t} with 266@code{gnutls_anti_replay_enable()} . 267 268@strong{Returns:} Zero or a negative error code on error. 269 270@strong{Since:} 3.6.5 271@end deftypefun 272 273@subheading gnutls_anti_replay_set_add_function 274@anchor{gnutls_anti_replay_set_add_function} 275@deftypefun {void} {gnutls_anti_replay_set_add_function} (gnutls_anti_replay_t @var{anti_replay}, gnutls_db_add_func @var{add_func}) 276@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. 277 278@var{add_func}: is the function. 279 280Sets the function that will be used to store an entry if it is not 281already present in the resumed sessions database. This function returns 0 282if the entry is successfully stored, and a negative error code 283otherwise. In particular, if the entry is found in the database, 284it returns @code{GNUTLS_E_DB_ENTRY_EXISTS} . 285 286The arguments to the @code{add_func} are: 287- @code{ptr} : the pointer set with @code{gnutls_anti_replay_set_ptr()} 288- @code{exp_time} : the expiration time of the entry 289- @code{key} : a pointer to the key 290- @code{data} : a pointer to data to store 291 292The data set by this function can be examined using 293@code{gnutls_db_check_entry_expire_time()} and @code{gnutls_db_check_entry_time()} . 294 295@strong{Since:} 3.6.5 296@end deftypefun 297 298@subheading gnutls_anti_replay_set_ptr 299@anchor{gnutls_anti_replay_set_ptr} 300@deftypefun {void} {gnutls_anti_replay_set_ptr} (gnutls_anti_replay_t @var{anti_replay}, void * @var{ptr}) 301@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. 302 303@var{ptr}: is the pointer 304 305Sets the pointer that will be provided to db add function 306as the first argument. 307@end deftypefun 308 309@subheading gnutls_anti_replay_set_window 310@anchor{gnutls_anti_replay_set_window} 311@deftypefun {void} {gnutls_anti_replay_set_window} (gnutls_anti_replay_t @var{anti_replay}, unsigned int @var{window}) 312@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. 313 314@var{window}: is the time window recording ClientHello, in milliseconds 315 316Sets the time window used for ClientHello recording. In order to 317protect against replay attacks, the server records ClientHello 318messages within this time period from the last update, and 319considers it a replay when a ClientHello outside of the period; if 320a ClientHello arrives within this period, the server checks the 321database and detects duplicates. 322 323For the details of the algorithm, see RFC 8446, section 8.2. 324 325@strong{Since:} 3.6.5 326@end deftypefun 327 328@subheading gnutls_auth_client_get_type 329@anchor{gnutls_auth_client_get_type} 330@deftypefun {gnutls_credentials_type_t} {gnutls_auth_client_get_type} (gnutls_session_t @var{session}) 331@var{session}: is a @code{gnutls_session_t} type. 332 333Returns the type of credentials that were used for client authentication. 334The returned information is to be used to distinguish the function used 335to access authentication data. 336 337Note that on resumed sessions, this function returns the schema 338used in the original session authentication. 339 340@strong{Returns:} The type of credentials for the client authentication 341schema, a @code{gnutls_credentials_type_t} type. 342@end deftypefun 343 344@subheading gnutls_auth_get_type 345@anchor{gnutls_auth_get_type} 346@deftypefun {gnutls_credentials_type_t} {gnutls_auth_get_type} (gnutls_session_t @var{session}) 347@var{session}: is a @code{gnutls_session_t} type. 348 349Returns type of credentials for the current authentication schema. 350The returned information is to be used to distinguish the function used 351to access authentication data. 352 353Eg. for CERTIFICATE ciphersuites (key exchange algorithms: 354@code{GNUTLS_KX_RSA} , @code{GNUTLS_KX_DHE_RSA} ), the same function are to be 355used to access the authentication data. 356 357Note that on resumed sessions, this function returns the schema 358used in the original session authentication. 359 360@strong{Returns:} The type of credentials for the current authentication 361schema, a @code{gnutls_credentials_type_t} type. 362@end deftypefun 363 364@subheading gnutls_auth_server_get_type 365@anchor{gnutls_auth_server_get_type} 366@deftypefun {gnutls_credentials_type_t} {gnutls_auth_server_get_type} (gnutls_session_t @var{session}) 367@var{session}: is a @code{gnutls_session_t} type. 368 369Returns the type of credentials that were used for server authentication. 370The returned information is to be used to distinguish the function used 371to access authentication data. 372 373Note that on resumed sessions, this function returns the schema 374used in the original session authentication. 375 376@strong{Returns:} The type of credentials for the server authentication 377schema, a @code{gnutls_credentials_type_t} type. 378@end deftypefun 379 380@subheading gnutls_base64_decode2 381@anchor{gnutls_base64_decode2} 382@deftypefun {int} {gnutls_base64_decode2} (const gnutls_datum_t * @var{base64}, gnutls_datum_t * @var{result}) 383@var{base64}: contains the encoded data 384 385@var{result}: the location of decoded data 386 387This function will decode the given base64 encoded data. The decoded data 388will be allocated, and stored into result. 389 390You should use @code{gnutls_free()} to free the returned data. 391 392@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 393an error code is returned. 394 395@strong{Since:} 3.6.0 396@end deftypefun 397 398@subheading gnutls_base64_encode2 399@anchor{gnutls_base64_encode2} 400@deftypefun {int} {gnutls_base64_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) 401@var{data}: contains the raw data 402 403@var{result}: will hold the newly allocated encoded data 404 405This function will convert the given data to printable data, using 406the base64 encoding. This function will allocate the required 407memory to hold the encoded data. 408 409You should use @code{gnutls_free()} to free the returned data. 410 411@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 412an error code is returned. 413 414@strong{Since:} 3.6.0 415@end deftypefun 416 417@subheading gnutls_buffer_append_data 418@anchor{gnutls_buffer_append_data} 419@deftypefun {int} {gnutls_buffer_append_data} (gnutls_buffer_t @var{dest}, const void * @var{data}, size_t @var{data_size}) 420@var{dest}: the buffer to append to 421 422@var{data}: the data 423 424@var{data_size}: the size of @code{data} 425 426Appends the provided @code{data} to the destination buffer. 427 428@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 429 430@strong{Since:} 3.4.0 431@end deftypefun 432 433@subheading gnutls_bye 434@anchor{gnutls_bye} 435@deftypefun {int} {gnutls_bye} (gnutls_session_t @var{session}, gnutls_close_request_t @var{how}) 436@var{session}: is a @code{gnutls_session_t} type. 437 438@var{how}: is an integer 439 440Terminates the current TLS/SSL connection. The connection should 441have been initiated using @code{gnutls_handshake()} . @code{how} should be one 442of @code{GNUTLS_SHUT_RDWR} , @code{GNUTLS_SHUT_WR} . 443 444In case of @code{GNUTLS_SHUT_RDWR} the TLS session gets 445terminated and further receives and sends will be disallowed. If 446the return value is zero you may continue using the underlying 447transport layer. @code{GNUTLS_SHUT_RDWR} sends an alert containing a close 448request and waits for the peer to reply with the same message. 449 450In case of @code{GNUTLS_SHUT_WR} the TLS session gets terminated 451and further sends will be disallowed. In order to reuse the 452connection you should wait for an EOF from the peer. 453@code{GNUTLS_SHUT_WR} sends an alert containing a close request. 454 455Note that not all implementations will properly terminate a TLS 456connection. Some of them, usually for performance reasons, will 457terminate only the underlying transport layer, and thus not 458distinguishing between a malicious party prematurely terminating 459the connection and normal termination. 460 461This function may also return @code{GNUTLS_E_AGAIN} or 462@code{GNUTLS_E_INTERRUPTED} ; cf. @code{gnutls_record_get_direction()} . 463 464@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code, see 465function documentation for entire semantics. 466@end deftypefun 467 468@subheading gnutls_certificate_activation_time_peers 469@anchor{gnutls_certificate_activation_time_peers} 470@deftypefun {time_t} {gnutls_certificate_activation_time_peers} (gnutls_session_t @var{session}) 471@var{session}: is a gnutls session 472 473This function will return the peer's certificate activation time. 474 475@strong{Returns:} (time_t)-1 on error. 476 477@strong{Deprecated:} @code{gnutls_certificate_verify_peers2()} now verifies activation times. 478@end deftypefun 479 480@subheading gnutls_certificate_allocate_credentials 481@anchor{gnutls_certificate_allocate_credentials} 482@deftypefun {int} {gnutls_certificate_allocate_credentials} (gnutls_certificate_credentials_t * @var{res}) 483@var{res}: is a pointer to a @code{gnutls_certificate_credentials_t} type. 484 485Allocate a gnutls_certificate_credentials_t structure. 486 487@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 488@end deftypefun 489 490@subheading gnutls_certificate_client_get_request_status 491@anchor{gnutls_certificate_client_get_request_status} 492@deftypefun {unsigned} {gnutls_certificate_client_get_request_status} (gnutls_session_t @var{session}) 493@var{session}: is a gnutls session 494 495Get whether client certificate was requested on the last 496handshake or not. 497 498@strong{Returns:} 0 if the peer (server) did not request client 499authentication or 1 otherwise. 500@end deftypefun 501 502@subheading gnutls_certificate_expiration_time_peers 503@anchor{gnutls_certificate_expiration_time_peers} 504@deftypefun {time_t} {gnutls_certificate_expiration_time_peers} (gnutls_session_t @var{session}) 505@var{session}: is a gnutls session 506 507This function will return the peer's certificate expiration time. 508 509@strong{Returns:} (time_t)-1 on error. 510 511@strong{Deprecated:} @code{gnutls_certificate_verify_peers2()} now verifies expiration times. 512@end deftypefun 513 514@subheading gnutls_certificate_free_ca_names 515@anchor{gnutls_certificate_free_ca_names} 516@deftypefun {void} {gnutls_certificate_free_ca_names} (gnutls_certificate_credentials_t @var{sc}) 517@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 518 519This function will delete all the CA name in the given 520credentials. Clients may call this to save some memory since in 521client side the CA names are not used. Servers might want to use 522this function if a large list of trusted CAs is present and 523sending the names of it would just consume bandwidth without providing 524information to client. 525 526CA names are used by servers to advertise the CAs they support to 527clients. 528@end deftypefun 529 530@subheading gnutls_certificate_free_cas 531@anchor{gnutls_certificate_free_cas} 532@deftypefun {void} {gnutls_certificate_free_cas} (gnutls_certificate_credentials_t @var{sc}) 533@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 534 535This function was operational on very early versions of gnutls. 536Due to internal refactorings and the fact that this was hardly ever 537used, it is currently a no-op. 538@end deftypefun 539 540@subheading gnutls_certificate_free_credentials 541@anchor{gnutls_certificate_free_credentials} 542@deftypefun {void} {gnutls_certificate_free_credentials} (gnutls_certificate_credentials_t @var{sc}) 543@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 544 545Free a gnutls_certificate_credentials_t structure. 546 547This function does not free any temporary parameters associated 548with this structure (ie RSA and DH parameters are not freed by this 549function). 550@end deftypefun 551 552@subheading gnutls_certificate_free_crls 553@anchor{gnutls_certificate_free_crls} 554@deftypefun {void} {gnutls_certificate_free_crls} (gnutls_certificate_credentials_t @var{sc}) 555@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 556 557This function will delete all the CRLs associated 558with the given credentials. 559@end deftypefun 560 561@subheading gnutls_certificate_free_keys 562@anchor{gnutls_certificate_free_keys} 563@deftypefun {void} {gnutls_certificate_free_keys} (gnutls_certificate_credentials_t @var{sc}) 564@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 565 566This function will delete all the keys and the certificates associated 567with the given credentials. This function must not be called when a 568TLS negotiation that uses the credentials is in progress. 569@end deftypefun 570 571@subheading gnutls_certificate_get_crt_raw 572@anchor{gnutls_certificate_get_crt_raw} 573@deftypefun {int} {gnutls_certificate_get_crt_raw} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx1}, unsigned @var{idx2}, gnutls_datum_t * @var{cert}) 574@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 575 576@var{idx1}: the index of the certificate chain if multiple are present 577 578@var{idx2}: the index of the certificate in the chain. Zero gives the server's certificate. 579 580@var{cert}: Will hold the DER encoded certificate. 581 582This function will return the DER encoded certificate of the 583server or any other certificate on its certificate chain (based on @code{idx2} ). 584The returned data should be treated as constant and only accessible during the lifetime 585of @code{sc} . The @code{idx1} matches the value @code{gnutls_certificate_set_x509_key()} and friends 586functions. 587 588@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 589negative error value. In case the indexes are out of bounds @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 590is returned. 591 592@strong{Since:} 3.2.5 593@end deftypefun 594 595@subheading gnutls_certificate_get_issuer 596@anchor{gnutls_certificate_get_issuer} 597@deftypefun {int} {gnutls_certificate_get_issuer} (gnutls_certificate_credentials_t @var{sc}, gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) 598@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 599 600@var{cert}: is the certificate to find issuer for 601 602@var{issuer}: Will hold the issuer if any. Should be treated as constant. 603 604@var{flags}: Use zero or @code{GNUTLS_TL_GET_COPY} 605 606This function will return the issuer of a given certificate. 607If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer 608will be returned which must be freed using @code{gnutls_x509_crt_deinit()} . 609In that case the provided @code{issuer} must not be initialized. 610 611As with @code{gnutls_x509_trust_list_get_issuer()} this function requires 612the @code{GNUTLS_TL_GET_COPY} flag in order to operate with PKCS@code{11} trust 613lists in a thread-safe way. 614 615@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 616negative error value. 617 618@strong{Since:} 3.0 619@end deftypefun 620 621@subheading gnutls_certificate_get_ocsp_expiration 622@anchor{gnutls_certificate_get_ocsp_expiration} 623@deftypefun {time_t} {gnutls_certificate_get_ocsp_expiration} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx}, int @var{oidx}, unsigned @var{flags}) 624@var{sc}: is a credentials structure. 625 626@var{idx}: is a certificate chain index as returned by @code{gnutls_certificate_set_key()} and friends 627 628@var{oidx}: is an OCSP response index 629 630@var{flags}: should be zero 631 632This function returns the validity of the loaded OCSP responses, 633to provide information on when to reload/refresh them. 634 635Note that the credentials structure should be read-only when in 636use, thus when reloading, either the credentials structure must not 637be in use by any sessions, or a new credentials structure should be 638allocated for new sessions. 639 640When @code{oidx} is (-1) then the minimum refresh time for all responses 641is returned. Otherwise the index specifies the response corresponding 642to the @code{odix} certificate in the certificate chain. 643 644@strong{Returns:} On success, the expiration time of the OCSP response. Otherwise 645(time_t)(-1) on error, or (time_t)-2 on out of bounds. 646 647@strong{Since:} 3.6.3 648@end deftypefun 649 650@subheading gnutls_certificate_get_ours 651@anchor{gnutls_certificate_get_ours} 652@deftypefun {const gnutls_datum_t *} {gnutls_certificate_get_ours} (gnutls_session_t @var{session}) 653@var{session}: is a gnutls session 654 655Gets the certificate as sent to the peer in the last handshake. 656The certificate is in raw (DER) format. No certificate 657list is being returned. Only the first certificate. 658 659This function returns the certificate that was sent in the current 660handshake. In subsequent resumed sessions this function will return 661@code{NULL} . That differs from @code{gnutls_certificate_get_peers()} which always 662returns the peer's certificate used in the original session. 663 664@strong{Returns:} a pointer to a @code{gnutls_datum_t} containing our 665certificate, or @code{NULL} in case of an error or if no certificate 666was used. 667@end deftypefun 668 669@subheading gnutls_certificate_get_peers 670@anchor{gnutls_certificate_get_peers} 671@deftypefun {const gnutls_datum_t *} {gnutls_certificate_get_peers} (gnutls_session_t @var{session}, unsigned int * @var{list_size}) 672@var{session}: is a gnutls session 673 674@var{list_size}: is the length of the certificate list (may be @code{NULL} ) 675 676Get the peer's raw certificate (chain) as sent by the peer. These 677certificates are in raw format (DER encoded for X.509). In case of 678a X.509 then a certificate list may be present. The list 679is provided as sent by the server; the server must send as first 680certificate in the list its own certificate, following the 681issuer's certificate, then the issuer's issuer etc. However, there 682are servers which violate this principle and thus on certain 683occasions this may be an unsorted list. 684 685In resumed sessions, this function will return the peer's certificate 686list as used in the first/original session. 687 688@strong{Returns:} a pointer to a @code{gnutls_datum_t} containing the peer's 689certificates, or @code{NULL} in case of an error or if no certificate 690was used. 691@end deftypefun 692 693@subheading gnutls_certificate_get_peers_subkey_id 694@anchor{gnutls_certificate_get_peers_subkey_id} 695@deftypefun {int} {gnutls_certificate_get_peers_subkey_id} (gnutls_session_t @var{session}, gnutls_datum_t * @var{id}) 696@var{session}: is a gnutls session 697 698@var{id}: will contain the ID 699 700This function is no-op. 701 702@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . 703 704@strong{Since:} 3.1.3 705@end deftypefun 706 707@subheading gnutls_certificate_get_verify_flags 708@anchor{gnutls_certificate_get_verify_flags} 709@deftypefun {unsigned int} {gnutls_certificate_get_verify_flags} (gnutls_certificate_credentials_t @var{res}) 710@var{res}: is a gnutls_certificate_credentials_t type 711 712Returns the verification flags set with 713@code{gnutls_certificate_set_verify_flags()} . 714 715@strong{Returns:} The certificate verification flags used by @code{res} . 716 717@strong{Since:} 3.4.0 718@end deftypefun 719 720@subheading gnutls_certificate_get_x509_crt 721@anchor{gnutls_certificate_get_x509_crt} 722@deftypefun {int} {gnutls_certificate_get_x509_crt} (gnutls_certificate_credentials_t @var{res}, unsigned @var{index}, gnutls_x509_crt_t ** @var{crt_list}, unsigned * @var{crt_list_size}) 723@var{res}: is a @code{gnutls_certificate_credentials_t} type. 724 725@var{index}: The index of the certificate list to obtain. 726 727@var{crt_list}: Where to store the certificate list. 728 729@var{crt_list_size}: Will hold the number of certificates. 730 731Obtains a X.509 certificate list that has been stored in @code{res} with one of 732@code{gnutls_certificate_set_x509_key()} , @code{gnutls_certificate_set_key()} , 733@code{gnutls_certificate_set_x509_key_file()} , 734@code{gnutls_certificate_set_x509_key_file2()} , 735@code{gnutls_certificate_set_x509_key_mem()} , or 736@code{gnutls_certificate_set_x509_key_mem2()} . Each certificate in the returned 737certificate list must be deallocated with @code{gnutls_x509_crt_deinit()} , and the 738list itself must be freed with @code{gnutls_free()} . 739 740The @code{index} matches the return value of @code{gnutls_certificate_set_x509_key()} and friends 741functions, when the @code{GNUTLS_CERTIFICATE_API_V2} flag is set. 742 743If there is no certificate with the given index, 744@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the certificate 745with the given index is not a X.509 certificate, @code{GNUTLS_E_INVALID_REQUEST} 746is returned. The returned certificates must be deinitialized after 747use, and the @code{crt_list} pointer must be freed using @code{gnutls_free()} . 748 749@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code. 750 751@strong{Since:} 3.4.0 752@end deftypefun 753 754@subheading gnutls_certificate_get_x509_key 755@anchor{gnutls_certificate_get_x509_key} 756@deftypefun {int} {gnutls_certificate_get_x509_key} (gnutls_certificate_credentials_t @var{res}, unsigned @var{index}, gnutls_x509_privkey_t * @var{key}) 757@var{res}: is a @code{gnutls_certificate_credentials_t} type. 758 759@var{index}: The index of the key to obtain. 760 761@var{key}: Location to store the key. 762 763Obtains a X.509 private key that has been stored in @code{res} with one of 764@code{gnutls_certificate_set_x509_key()} , @code{gnutls_certificate_set_key()} , 765@code{gnutls_certificate_set_x509_key_file()} , 766@code{gnutls_certificate_set_x509_key_file2()} , 767@code{gnutls_certificate_set_x509_key_mem()} , or 768@code{gnutls_certificate_set_x509_key_mem2()} . The returned key must be deallocated 769with @code{gnutls_x509_privkey_deinit()} when no longer needed. 770 771The @code{index} matches the return value of @code{gnutls_certificate_set_x509_key()} and friends 772functions, when the @code{GNUTLS_CERTIFICATE_API_V2} flag is set. 773 774If there is no key with the given index, 775@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the key with the 776given index is not a X.509 key, @code{GNUTLS_E_INVALID_REQUEST} is returned. 777 778@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code. 779 780@strong{Since:} 3.4.0 781@end deftypefun 782 783@subheading gnutls_certificate_send_x509_rdn_sequence 784@anchor{gnutls_certificate_send_x509_rdn_sequence} 785@deftypefun {void} {gnutls_certificate_send_x509_rdn_sequence} (gnutls_session_t @var{session}, int @var{status}) 786@var{session}: a @code{gnutls_session_t} type. 787 788@var{status}: is 0 or 1 789 790If status is non zero, this function will order gnutls not to send 791the rdnSequence in the certificate request message. That is the 792server will not advertise its trusted CAs to the peer. If status 793is zero then the default behaviour will take effect, which is to 794advertise the server's trusted CAs. 795 796This function has no effect in clients, and in authentication 797methods other than certificate with X.509 certificates. 798@end deftypefun 799 800@subheading gnutls_certificate_server_set_request 801@anchor{gnutls_certificate_server_set_request} 802@deftypefun {void} {gnutls_certificate_server_set_request} (gnutls_session_t @var{session}, gnutls_certificate_request_t @var{req}) 803@var{session}: is a @code{gnutls_session_t} type. 804 805@var{req}: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE, GNUTLS_CERT_IGNORE 806 807This function specifies if we (in case of a server) are going to 808send a certificate request message to the client. If @code{req} is 809GNUTLS_CERT_REQUIRE then the server will return the @code{GNUTLS_E_NO_CERTIFICATE_FOUND} 810error if the peer does not provide a certificate. If you do not call this 811function then the client will not be asked to send a certificate. Invoking 812the function with @code{req} GNUTLS_CERT_IGNORE has the same effect. 813@end deftypefun 814 815@subheading gnutls_certificate_set_dh_params 816@anchor{gnutls_certificate_set_dh_params} 817@deftypefun {void} {gnutls_certificate_set_dh_params} (gnutls_certificate_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) 818@var{res}: is a gnutls_certificate_credentials_t type 819 820@var{dh_params}: the Diffie-Hellman parameters. 821 822This function will set the Diffie-Hellman parameters for a 823certificate server to use. These parameters will be used in 824Ephemeral Diffie-Hellman cipher suites. Note that only a pointer 825to the parameters are stored in the certificate handle, so you 826must not deallocate the parameters before the certificate is deallocated. 827 828@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 829or later. Since 3.6.0, DH parameters are negotiated 830following RFC7919. 831@end deftypefun 832 833@subheading gnutls_certificate_set_flags 834@anchor{gnutls_certificate_set_flags} 835@deftypefun {void} {gnutls_certificate_set_flags} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{flags}) 836@var{res}: is a gnutls_certificate_credentials_t type 837 838@var{flags}: are the flags of @code{gnutls_certificate_flags} type 839 840This function will set flags to tweak the operation of 841the credentials structure. See the @code{gnutls_certificate_flags} enumerations 842for more information on the available flags. 843 844@strong{Since:} 3.4.7 845@end deftypefun 846 847@subheading gnutls_certificate_set_known_dh_params 848@anchor{gnutls_certificate_set_known_dh_params} 849@deftypefun {int} {gnutls_certificate_set_known_dh_params} (gnutls_certificate_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) 850@var{res}: is a gnutls_certificate_credentials_t type 851 852@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration 853 854This function will set the Diffie-Hellman parameters for a 855certificate server to use. These parameters will be used in 856Ephemeral Diffie-Hellman cipher suites and will be selected from 857the FFDHE set of RFC7919 according to the security level provided. 858 859@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 860or later. Since 3.6.0, DH parameters are negotiated 861following RFC7919. 862 863@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 864negative error value. 865 866@strong{Since:} 3.5.6 867@end deftypefun 868 869@subheading gnutls_certificate_set_ocsp_status_request_file 870@anchor{gnutls_certificate_set_ocsp_status_request_file} 871@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_file} (gnutls_certificate_credentials_t @var{sc}, const char * @var{response_file}, unsigned @var{idx}) 872@var{sc}: is a credentials structure. 873 874@var{response_file}: a filename of the OCSP response 875 876@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends 877 878This function loads the provided OCSP response. It will be 879sent to the client if requests an OCSP certificate status for 880the certificate chain specified by @code{idx} . 881 882@strong{Note:} the ability to set multiple OCSP responses per credential 883structure via the index @code{idx} was added in version 3.5.6. To keep 884backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} 885with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate 886functions return an index usable by this function. 887 888This function can be called multiple times since GnuTLS 3.6.3 889when multiple responses which apply to the chain are available. 890If the response provided does not match any certificates present 891in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. 892To revert to the previous behavior set the flag @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} 893in the certificate credentials structure. In that case, only the 894end-certificate's OCSP response can be set. 895If the response is already expired at the time of loading the code 896@code{GNUTLS_E_EXPIRED} is returned. 897 898To revert to the previous behavior of this function which does not return 899any errors, set the flag @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} 900 901@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 902otherwise a negative error code is returned. 903 904@strong{Since:} 3.1.3 905@end deftypefun 906 907@subheading gnutls_certificate_set_ocsp_status_request_file2 908@anchor{gnutls_certificate_set_ocsp_status_request_file2} 909@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_file2} (gnutls_certificate_credentials_t @var{sc}, const char * @var{response_file}, unsigned @var{idx}, gnutls_x509_crt_fmt_t @var{fmt}) 910@var{sc}: is a credentials structure. 911 912@var{response_file}: a filename of the OCSP response 913 914@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends 915 916@var{fmt}: is PEM or DER 917 918This function loads the OCSP responses to be sent to the 919peer for the certificate chain specified by @code{idx} . When @code{fmt} is 920set to PEM, multiple responses can be loaded. 921 922This function must be called after setting any certificates, and 923cannot be used for certificates that are provided via a callback -- 924that is when @code{gnutls_certificate_set_retrieve_function()} is used. In 925that case consider using @code{gnutls_certificate_set_retrieve_function3()} . 926 927This function can be called multiple times when multiple responses 928applicable to the certificate chain are available. 929If the response provided does not match any certificates present 930in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. 931If the response is already expired at the time of loading the code 932@code{GNUTLS_E_EXPIRED} is returned. 933 934@strong{Returns:} On success, the number of loaded responses is returned, 935otherwise a negative error code. 936 937@strong{Since:} 3.1.3 938@end deftypefun 939 940@subheading gnutls_certificate_set_ocsp_status_request_function 941@anchor{gnutls_certificate_set_ocsp_status_request_function} 942@deftypefun {void} {gnutls_certificate_set_ocsp_status_request_function} (gnutls_certificate_credentials_t @var{sc}, gnutls_status_request_ocsp_func @var{ocsp_func}, void * @var{ptr}) 943@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 944 945@var{ocsp_func}: function pointer to OCSP status request callback. 946 947@var{ptr}: opaque pointer passed to callback function 948 949This function is to be used by server to register a callback to 950handle OCSP status requests from the client. The callback will be 951invoked if the client supplied a status-request OCSP extension. 952The callback function prototype is: 953 954typedef int (*gnutls_status_request_ocsp_func) 955(gnutls_session_t session, void *ptr, gnutls_datum_t *ocsp_response); 956 957The callback will be invoked if the client requests an OCSP certificate 958status. The callback may return @code{GNUTLS_E_NO_CERTIFICATE_STATUS} , if 959there is no recent OCSP response. If the callback returns @code{GNUTLS_E_SUCCESS} , 960it is expected to have the @code{ocsp_response} field set with a valid (DER-encoded) 961OCSP response. The response must be a value allocated using @code{gnutls_malloc()} , 962and will be deinitialized by the caller. 963 964It is possible to set a specific callback for each provided certificate 965using @code{gnutls_certificate_set_ocsp_status_request_function2()} . 966 967@strong{Since:} 3.1.3 968@end deftypefun 969 970@subheading gnutls_certificate_set_ocsp_status_request_function2 971@anchor{gnutls_certificate_set_ocsp_status_request_function2} 972@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_function2} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx}, gnutls_status_request_ocsp_func @var{ocsp_func}, void * @var{ptr}) 973@var{sc}: is a @code{gnutls_certificate_credentials_t} type. 974 975@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends 976 977@var{ocsp_func}: function pointer to OCSP status request callback. 978 979@var{ptr}: opaque pointer passed to callback function 980 981This function is to be used by server to register a callback to 982provide OCSP status requests that correspond to the indexed certificate chain 983from the client. The callback will be invoked if the client supplied a 984status-request OCSP extension. 985 986The callback function prototype is: 987 988typedef int (*gnutls_status_request_ocsp_func) 989(gnutls_session_t session, void *ptr, gnutls_datum_t *ocsp_response); 990 991The callback will be invoked if the client requests an OCSP certificate 992status. The callback may return @code{GNUTLS_E_NO_CERTIFICATE_STATUS} , if 993there is no recent OCSP response. If the callback returns @code{GNUTLS_E_SUCCESS} , 994it is expected to have the @code{ocsp_response} field set with a valid (DER-encoded) 995OCSP response. The response must be a value allocated using @code{gnutls_malloc()} , 996and will be deinitialized by the caller. 997 998@strong{Note:} the ability to set multiple OCSP responses per credential 999structure via the index @code{idx} was added in version 3.5.6. To keep 1000backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} 1001with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate 1002functions return an index usable by this function. 1003 1004@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 1005otherwise a negative error code is returned. 1006 1007@strong{Since:} 3.5.5 1008@end deftypefun 1009 1010@subheading gnutls_certificate_set_ocsp_status_request_mem 1011@anchor{gnutls_certificate_set_ocsp_status_request_mem} 1012@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_mem} (gnutls_certificate_credentials_t @var{sc}, const gnutls_datum_t * @var{resp_data}, unsigned @var{idx}, gnutls_x509_crt_fmt_t @var{fmt}) 1013@var{sc}: is a credentials structure. 1014 1015@var{resp_data}: a memory buffer holding an OCSP response 1016 1017@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends 1018 1019@var{fmt}: is PEM or DER 1020 1021This function sets the OCSP responses to be sent to the 1022peer for the certificate chain specified by @code{idx} . When @code{fmt} is set 1023to PEM, multiple responses can be loaded. 1024 1025@strong{Note:} the ability to set multiple OCSP responses per credential 1026structure via the index @code{idx} was added in version 3.5.6. To keep 1027backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} 1028with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate 1029functions return an index usable by this function. 1030 1031This function must be called after setting any certificates, and 1032cannot be used for certificates that are provided via a callback -- 1033that is when @code{gnutls_certificate_set_retrieve_function()} is used. 1034 1035This function can be called multiple times when multiple responses which 1036apply to the certificate chain are available. 1037If the response provided does not match any certificates present 1038in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. 1039If the response is already expired at the time of loading the code 1040@code{GNUTLS_E_EXPIRED} is returned. 1041 1042@strong{Returns:} On success, the number of loaded responses is returned, 1043otherwise a negative error code. 1044 1045@strong{Since:} 3.6.3 1046@end deftypefun 1047 1048@subheading gnutls_certificate_set_params_function 1049@anchor{gnutls_certificate_set_params_function} 1050@deftypefun {void} {gnutls_certificate_set_params_function} (gnutls_certificate_credentials_t @var{res}, gnutls_params_function * @var{func}) 1051@var{res}: is a gnutls_certificate_credentials_t type 1052 1053@var{func}: is the function to be called 1054 1055This function will set a callback in order for the server to get 1056the Diffie-Hellman or RSA parameters for certificate 1057authentication. The callback should return @code{GNUTLS_E_SUCCESS} (0) on success. 1058 1059@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 1060or later. Since 3.6.0, DH parameters are negotiated 1061following RFC7919. 1062@end deftypefun 1063 1064@subheading gnutls_certificate_set_pin_function 1065@anchor{gnutls_certificate_set_pin_function} 1066@deftypefun {void} {gnutls_certificate_set_pin_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 1067@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1068 1069@var{fn}: A PIN callback 1070 1071@var{userdata}: Data to be passed in the callback 1072 1073This function will set a callback function to be used when 1074required to access a protected object. This function overrides any other 1075global PIN functions. 1076 1077Note that this function must be called right after initialization 1078to have effect. 1079 1080@strong{Since:} 3.1.0 1081@end deftypefun 1082 1083@subheading gnutls_certificate_set_rawpk_key_file 1084@anchor{gnutls_certificate_set_rawpk_key_file} 1085@deftypefun {int} {gnutls_certificate_set_rawpk_key_file} (gnutls_certificate_credentials_t @var{cred}, const char* @var{rawpkfile}, const char* @var{privkeyfile}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{pass}, unsigned int @var{key_usage}, const char ** @var{names}, unsigned int @var{names_length}, unsigned int @var{privkey_flags}, unsigned int @var{pkcs11_flags}) 1086@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1087 1088@var{rawpkfile}: contains a raw public key in 1089PKIX.SubjectPublicKeyInfo format. 1090 1091@var{privkeyfile}: contains a file path to a private key. 1092 1093@var{format}: encoding of the keys. DER or PEM. 1094 1095@var{pass}: an optional password to unlock the private key privkeyfile. 1096 1097@var{key_usage}: an ORed sequence of @code{GNUTLS_KEY_} * flags. 1098 1099@var{names}: is an array of DNS names belonging to the public-key (NULL if none). 1100 1101@var{names_length}: holds the length of the names list. 1102 1103@var{privkey_flags}: an ORed sequence of @code{gnutls_pkcs_encrypt_flags_t} . 1104These apply to the private key pkey. 1105 1106@var{pkcs11_flags}: one of gnutls_pkcs11_obj_flags. These apply to URLs. 1107 1108This function sets a public/private keypair read from file in the 1109@code{gnutls_certificate_credentials_t} type to be used for authentication 1110and/or encryption. @code{spki} and @code{privkey} should match otherwise set 1111signatures cannot be validated. In case of no match this function 1112returns @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} . This function should 1113be called once for the client because there is currently no mechanism 1114to determine which raw public-key to select for the peer when there 1115are multiple present. Multiple raw public keys for the server can be 1116distinghuished by setting the @code{names} . 1117 1118Note here that @code{spki} is a raw public-key as defined 1119in RFC7250. It means that there is no surrounding certificate that 1120holds the public key and that there is therefore no direct mechanism 1121to prove the authenticity of this key. The keypair can be used during 1122a TLS handshake but its authenticity should be established via a 1123different mechanism (e.g. TOFU or known fingerprint). 1124 1125The supported formats are basic unencrypted key, PKCS8, PKCS12, 1126and the openssl format and will be autodetected. 1127 1128If the raw public-key and the private key are given in PEM encoding 1129then the strings that hold their values must be null terminated. 1130 1131Key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly 1132set because there is no certificate structure around the key to define 1133this value. See for more info @code{gnutls_x509_crt_get_key_usage()} . 1134 1135Note that, this function by default returns zero on success and a 1136negative value on error. Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} 1137is set using @code{gnutls_certificate_set_flags()} it returns an index 1138(greater or equal to zero). That index can be used in other functions 1139to refer to the added key-pair. 1140 1141@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, in case the 1142key pair does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} is returned, 1143in other erroneous cases a different negative error code is returned. 1144 1145@strong{Since:} 3.6.6 1146@end deftypefun 1147 1148@subheading gnutls_certificate_set_rawpk_key_mem 1149@anchor{gnutls_certificate_set_rawpk_key_mem} 1150@deftypefun {int} {gnutls_certificate_set_rawpk_key_mem} (gnutls_certificate_credentials_t @var{cred}, const gnutls_datum_t* @var{spki}, const gnutls_datum_t* @var{pkey}, gnutls_x509_crt_fmt_t @var{format}, const char* @var{pass}, unsigned int @var{key_usage}, const char ** @var{names}, unsigned int @var{names_length}, unsigned int @var{flags}) 1151@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1152 1153@var{spki}: contains a raw public key in 1154PKIX.SubjectPublicKeyInfo format. 1155 1156@var{pkey}: contains a raw private key. 1157 1158@var{format}: encoding of the keys. DER or PEM. 1159 1160@var{pass}: an optional password to unlock the private key pkey. 1161 1162@var{key_usage}: An ORed sequence of @code{GNUTLS_KEY_} * flags. 1163 1164@var{names}: is an array of DNS names belonging to the public-key (NULL if none). 1165 1166@var{names_length}: holds the length of the names list. 1167 1168@var{flags}: an ORed sequence of @code{gnutls_pkcs_encrypt_flags_t} . 1169These apply to the private key pkey. 1170 1171This function sets a public/private keypair in the 1172@code{gnutls_certificate_credentials_t} type to be used for authentication 1173and/or encryption. @code{spki} and @code{privkey} should match otherwise set 1174signatures cannot be validated. In case of no match this function 1175returns @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} . This function should 1176be called once for the client because there is currently no mechanism 1177to determine which raw public-key to select for the peer when there 1178are multiple present. Multiple raw public keys for the server can be 1179distinghuished by setting the @code{names} . 1180 1181Note here that @code{spki} is a raw public-key as defined 1182in RFC7250. It means that there is no surrounding certificate that 1183holds the public key and that there is therefore no direct mechanism 1184to prove the authenticity of this key. The keypair can be used during 1185a TLS handshake but its authenticity should be established via a 1186different mechanism (e.g. TOFU or known fingerprint). 1187 1188The supported formats are basic unencrypted key, PKCS8, PKCS12, 1189and the openssl format and will be autodetected. 1190 1191If the raw public-key and the private key are given in PEM encoding 1192then the strings that hold their values must be null terminated. 1193 1194Key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly 1195set because there is no certificate structure around the key to define 1196this value. See for more info @code{gnutls_x509_crt_get_key_usage()} . 1197 1198Note that, this function by default returns zero on success and a 1199negative value on error. Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} 1200is set using @code{gnutls_certificate_set_flags()} it returns an index 1201(greater or equal to zero). That index can be used in other functions 1202to refer to the added key-pair. 1203 1204@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, in case the 1205key pair does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} is returned, 1206in other erroneous cases a different negative error code is returned. 1207 1208@strong{Since:} 3.6.6 1209@end deftypefun 1210 1211@subheading gnutls_certificate_set_retrieve_function 1212@anchor{gnutls_certificate_set_retrieve_function} 1213@deftypefun {void} {gnutls_certificate_set_retrieve_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function * @var{func}) 1214@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1215 1216@var{func}: is the callback function 1217 1218This function sets a callback to be called in order to retrieve the 1219certificate to be used in the handshake. The callback will take control 1220only if a certificate is requested by the peer. You are advised 1221to use @code{gnutls_certificate_set_retrieve_function2()} because it 1222is much more efficient in the processing it requires from gnutls. 1223 1224The callback's function prototype is: 1225int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs, 1226const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr2_st* st); 1227 1228 @code{req_ca_dn} is only used in X.509 certificates. 1229Contains a list with the CA names that the server considers trusted. 1230This is a hint and typically the client should send a certificate that is signed 1231by one of these CAs. These names, when available, are DER encoded. To get a more 1232meaningful value use the function @code{gnutls_x509_rdn_get()} . 1233 1234 @code{pk_algos} contains a list with server's acceptable public key algorithms. 1235The certificate returned should support the server's given algorithms. 1236 1237 @code{st} should contain the certificates and private keys. 1238 1239If the callback function is provided then gnutls will call it, in the 1240handshake, after the certificate request message has been received. 1241 1242In server side pk_algos and req_ca_dn are NULL. 1243 1244The callback function should set the certificate list to be sent, 1245and return 0 on success. If no certificate was selected then the 1246number of certificates should be set to zero. The value (-1) 1247indicates error and the handshake will be terminated. If both certificates 1248are set in the credentials and a callback is available, the callback 1249takes predence. 1250 1251@strong{Since:} 3.0 1252@end deftypefun 1253 1254@subheading gnutls_certificate_set_verify_flags 1255@anchor{gnutls_certificate_set_verify_flags} 1256@deftypefun {void} {gnutls_certificate_set_verify_flags} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{flags}) 1257@var{res}: is a gnutls_certificate_credentials_t type 1258 1259@var{flags}: are the flags 1260 1261This function will set the flags to be used for verification 1262of certificates and override any defaults. The provided flags must be an OR of the 1263@code{gnutls_certificate_verify_flags} enumerations. 1264@end deftypefun 1265 1266@subheading gnutls_certificate_set_verify_function 1267@anchor{gnutls_certificate_set_verify_function} 1268@deftypefun {void} {gnutls_certificate_set_verify_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_verify_function * @var{func}) 1269@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1270 1271@var{func}: is the callback function 1272 1273This function sets a callback to be called when peer's certificate 1274has been received in order to verify it on receipt rather than 1275doing after the handshake is completed. 1276 1277The callback's function prototype is: 1278int (*callback)(gnutls_session_t); 1279 1280If the callback function is provided then gnutls will call it, in the 1281handshake, just after the certificate message has been received. 1282To verify or obtain the certificate the @code{gnutls_certificate_verify_peers2()} , 1283@code{gnutls_certificate_type_get()} , @code{gnutls_certificate_get_peers()} functions 1284can be used. 1285 1286The callback function should return 0 for the handshake to continue 1287or non-zero to terminate. 1288 1289@strong{Since:} 2.10.0 1290@end deftypefun 1291 1292@subheading gnutls_certificate_set_verify_limits 1293@anchor{gnutls_certificate_set_verify_limits} 1294@deftypefun {void} {gnutls_certificate_set_verify_limits} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{max_bits}, unsigned int @var{max_depth}) 1295@var{res}: is a gnutls_certificate_credentials type 1296 1297@var{max_bits}: is the number of bits of an acceptable certificate (default 8200) 1298 1299@var{max_depth}: is maximum depth of the verification of a certificate chain (default 5) 1300 1301This function will set some upper limits for the default 1302verification function, @code{gnutls_certificate_verify_peers2()} , to avoid 1303denial of service attacks. You can set them to zero to disable 1304limits. 1305@end deftypefun 1306 1307@subheading gnutls_certificate_set_x509_crl 1308@anchor{gnutls_certificate_set_x509_crl} 1309@deftypefun {int} {gnutls_certificate_set_x509_crl} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crl_t * @var{crl_list}, int @var{crl_list_size}) 1310@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1311 1312@var{crl_list}: is a list of trusted CRLs. They should have been verified before. 1313 1314@var{crl_list_size}: holds the size of the crl_list 1315 1316This function adds the trusted CRLs in order to verify client or 1317server certificates. In case of a client this is not required to 1318be called if the certificates are not verified using 1319@code{gnutls_certificate_verify_peers2()} . This function may be called 1320multiple times. 1321 1322@strong{Returns:} number of CRLs processed, or a negative error code on error. 1323 1324@strong{Since:} 2.4.0 1325@end deftypefun 1326 1327@subheading gnutls_certificate_set_x509_crl_file 1328@anchor{gnutls_certificate_set_x509_crl_file} 1329@deftypefun {int} {gnutls_certificate_set_x509_crl_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{crlfile}, gnutls_x509_crt_fmt_t @var{type}) 1330@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1331 1332@var{crlfile}: is a file containing the list of verified CRLs (DER or PEM list) 1333 1334@var{type}: is PEM or DER 1335 1336This function adds the trusted CRLs in order to verify client or server 1337certificates. In case of a client this is not required 1338to be called if the certificates are not verified using 1339@code{gnutls_certificate_verify_peers2()} . 1340This function may be called multiple times. 1341 1342@strong{Returns:} number of CRLs processed or a negative error code on error. 1343@end deftypefun 1344 1345@subheading gnutls_certificate_set_x509_crl_mem 1346@anchor{gnutls_certificate_set_x509_crl_mem} 1347@deftypefun {int} {gnutls_certificate_set_x509_crl_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{CRL}, gnutls_x509_crt_fmt_t @var{type}) 1348@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1349 1350@var{CRL}: is a list of trusted CRLs. They should have been verified before. 1351 1352@var{type}: is DER or PEM 1353 1354This function adds the trusted CRLs in order to verify client or 1355server certificates. In case of a client this is not required to 1356be called if the certificates are not verified using 1357@code{gnutls_certificate_verify_peers2()} . This function may be called 1358multiple times. 1359 1360@strong{Returns:} number of CRLs processed, or a negative error code on error. 1361@end deftypefun 1362 1363@subheading gnutls_certificate_set_x509_key 1364@anchor{gnutls_certificate_set_x509_key} 1365@deftypefun {int} {gnutls_certificate_set_x509_key} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crt_t * @var{cert_list}, int @var{cert_list_size}, gnutls_x509_privkey_t @var{key}) 1366@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1367 1368@var{cert_list}: contains a certificate list (path) for the specified private key 1369 1370@var{cert_list_size}: holds the size of the certificate list 1371 1372@var{key}: is a @code{gnutls_x509_privkey_t} key 1373 1374This function sets a certificate/private key pair in the 1375gnutls_certificate_credentials_t type. This function may be 1376called more than once, in case multiple keys/certificates exist for 1377the server. For clients that wants to send more than their own end 1378entity certificate (e.g., also an intermediate CA cert) then put 1379the certificate chain in @code{cert_list} . 1380 1381Note that the certificates and keys provided, can be safely deinitialized 1382after this function is called. 1383 1384If that function fails to load the @code{res} type is at an undefined state, it must 1385not be reused to load other keys or certificates. 1386 1387Note that, this function by default returns zero on success and a negative value on error. 1388Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1389it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1390 1391@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1392 1393@strong{Since:} 2.4.0 1394@end deftypefun 1395 1396@subheading gnutls_certificate_set_x509_key_file 1397@anchor{gnutls_certificate_set_x509_key_file} 1398@deftypefun {int} {gnutls_certificate_set_x509_key_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{certfile}, const char * @var{keyfile}, gnutls_x509_crt_fmt_t @var{type}) 1399@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1400 1401@var{certfile}: is a file that containing the certificate list (path) for 1402the specified private key, in PKCS7 format, or a list of certificates 1403 1404@var{keyfile}: is a file that contains the private key 1405 1406@var{type}: is PEM or DER 1407 1408This function sets a certificate/private key pair in the 1409gnutls_certificate_credentials_t type. This function may be 1410called more than once, in case multiple keys/certificates exist for 1411the server. For clients that need to send more than its own end 1412entity certificate, e.g., also an intermediate CA cert, then the 1413 @code{certfile} must contain the ordered certificate chain. 1414 1415Note that the names in the certificate provided will be considered 1416when selecting the appropriate certificate to use (in case of multiple 1417certificate/key pairs). 1418 1419This function can also accept URLs at @code{keyfile} and @code{certfile} . In that case it 1420will use the private key and certificate indicated by the URLs. Note 1421that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . 1422 1423In case the @code{certfile} is provided as a PKCS @code{11} URL, then the certificate, and its 1424present issuers in the token are imported (i.e., forming the required trust chain). 1425 1426If that function fails to load the @code{res} structure is at an undefined state, it must 1427not be reused to load other keys or certificates. 1428 1429Note that, this function by default returns zero on success and a negative value on error. 1430Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1431it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1432 1433@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1434 1435@strong{Since:} 3.1.11 1436@end deftypefun 1437 1438@subheading gnutls_certificate_set_x509_key_file2 1439@anchor{gnutls_certificate_set_x509_key_file2} 1440@deftypefun {int} {gnutls_certificate_set_x509_key_file2} (gnutls_certificate_credentials_t @var{res}, const char * @var{certfile}, const char * @var{keyfile}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{pass}, unsigned int @var{flags}) 1441@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1442 1443@var{certfile}: is a file that containing the certificate list (path) for 1444the specified private key, in PKCS7 format, or a list of certificates 1445 1446@var{keyfile}: is a file that contains the private key 1447 1448@var{type}: is PEM or DER 1449 1450@var{pass}: is the password of the key 1451 1452@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t 1453 1454This function sets a certificate/private key pair in the 1455gnutls_certificate_credentials_t type. This function may be 1456called more than once, in case multiple keys/certificates exist for 1457the server. For clients that need to send more than its own end 1458entity certificate, e.g., also an intermediate CA cert, then the 1459 @code{certfile} must contain the ordered certificate chain. 1460 1461Note that the names in the certificate provided will be considered 1462when selecting the appropriate certificate to use (in case of multiple 1463certificate/key pairs). 1464 1465This function can also accept URLs at @code{keyfile} and @code{certfile} . In that case it 1466will use the private key and certificate indicated by the URLs. Note 1467that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . 1468Before GnuTLS 3.4.0 when a URL was specified, the @code{pass} part was ignored and a 1469PIN callback had to be registered, this is no longer the case in current releases. 1470 1471In case the @code{certfile} is provided as a PKCS @code{11} URL, then the certificate, and its 1472present issuers in the token are imported (i.e., forming the required trust chain). 1473 1474If that function fails to load the @code{res} structure is at an undefined state, it must 1475not be reused to load other keys or certificates. 1476 1477Note that, this function by default returns zero on success and a negative value on error. 1478Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1479it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1480 1481@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1482@end deftypefun 1483 1484@subheading gnutls_certificate_set_x509_key_mem 1485@anchor{gnutls_certificate_set_x509_key_mem} 1486@deftypefun {int} {gnutls_certificate_set_x509_key_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, gnutls_x509_crt_fmt_t @var{type}) 1487@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1488 1489@var{cert}: contains a certificate list (path) for the specified private key 1490 1491@var{key}: is the private key, or @code{NULL} 1492 1493@var{type}: is PEM or DER 1494 1495This function sets a certificate/private key pair in the 1496gnutls_certificate_credentials_t type. This function may be called 1497more than once, in case multiple keys/certificates exist for the 1498server. 1499 1500Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates 1501is supported. This means that certificates intended for signing cannot 1502be used for ciphersuites that require encryption. 1503 1504If the certificate and the private key are given in PEM encoding 1505then the strings that hold their values must be null terminated. 1506 1507The @code{key} may be @code{NULL} if you are using a sign callback, see 1508@code{gnutls_sign_callback_set()} . 1509 1510Note that, this function by default returns zero on success and a negative value on error. 1511Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1512it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1513 1514@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1515@end deftypefun 1516 1517@subheading gnutls_certificate_set_x509_key_mem2 1518@anchor{gnutls_certificate_set_x509_key_mem2} 1519@deftypefun {int} {gnutls_certificate_set_x509_key_mem2} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{pass}, unsigned int @var{flags}) 1520@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1521 1522@var{cert}: contains a certificate list (path) for the specified private key 1523 1524@var{key}: is the private key, or @code{NULL} 1525 1526@var{type}: is PEM or DER 1527 1528@var{pass}: is the key's password 1529 1530@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t 1531 1532This function sets a certificate/private key pair in the 1533gnutls_certificate_credentials_t type. This function may be called 1534more than once, in case multiple keys/certificates exist for the 1535server. 1536 1537Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates 1538is supported. This means that certificates intended for signing cannot 1539be used for ciphersuites that require encryption. 1540 1541If the certificate and the private key are given in PEM encoding 1542then the strings that hold their values must be null terminated. 1543 1544The @code{key} may be @code{NULL} if you are using a sign callback, see 1545@code{gnutls_sign_callback_set()} . 1546 1547Note that, this function by default returns zero on success and a negative value on error. 1548Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1549it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1550 1551@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1552@end deftypefun 1553 1554@subheading gnutls_certificate_set_x509_simple_pkcs12_file 1555@anchor{gnutls_certificate_set_x509_simple_pkcs12_file} 1556@deftypefun {int} {gnutls_certificate_set_x509_simple_pkcs12_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{pkcs12file}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{password}) 1557@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1558 1559@var{pkcs12file}: filename of file containing PKCS@code{12} blob. 1560 1561@var{type}: is PEM or DER of the @code{pkcs12file} . 1562 1563@var{password}: optional password used to decrypt PKCS@code{12} file, bags and keys. 1564 1565This function sets a certificate/private key pair and/or a CRL in 1566the gnutls_certificate_credentials_t type. This function may 1567be called more than once (in case multiple keys/certificates exist 1568for the server). 1569 1570PKCS@code{12} files with a MAC, encrypted bags and PKCS @code{8} 1571private keys are supported. However, 1572only password based security, and the same password for all 1573operations, are supported. 1574 1575PKCS@code{12} file may contain many keys and/or certificates, and this 1576function will try to auto-detect based on the key ID the certificate 1577and key pair to use. If the PKCS@code{12} file contain the issuer of 1578the selected certificate, it will be appended to the certificate 1579to form a chain. 1580 1581If more than one private keys are stored in the PKCS@code{12} file, 1582then only one key will be read (and it is undefined which one). 1583 1584It is believed that the limitations of this function is acceptable 1585for most usage, and that any more flexibility would introduce 1586complexity that would make it harder to use this functionality at 1587all. 1588 1589Note that, this function by default returns zero on success and a negative value on error. 1590Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1591it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1592 1593@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1594@end deftypefun 1595 1596@subheading gnutls_certificate_set_x509_simple_pkcs12_mem 1597@anchor{gnutls_certificate_set_x509_simple_pkcs12_mem} 1598@deftypefun {int} {gnutls_certificate_set_x509_simple_pkcs12_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{p12blob}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{password}) 1599@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1600 1601@var{p12blob}: the PKCS@code{12} blob. 1602 1603@var{type}: is PEM or DER of the @code{pkcs12file} . 1604 1605@var{password}: optional password used to decrypt PKCS@code{12} file, bags and keys. 1606 1607This function sets a certificate/private key pair and/or a CRL in 1608the gnutls_certificate_credentials_t type. This function may 1609be called more than once (in case multiple keys/certificates exist 1610for the server). 1611 1612Encrypted PKCS@code{12} bags and PKCS@code{8} private keys are supported. However, 1613only password based security, and the same password for all 1614operations, are supported. 1615 1616PKCS@code{12} file may contain many keys and/or certificates, and this 1617function will try to auto-detect based on the key ID the certificate 1618and key pair to use. If the PKCS@code{12} file contain the issuer of 1619the selected certificate, it will be appended to the certificate 1620to form a chain. 1621 1622If more than one private keys are stored in the PKCS@code{12} file, 1623then only one key will be read (and it is undefined which one). 1624 1625It is believed that the limitations of this function is acceptable 1626for most usage, and that any more flexibility would introduce 1627complexity that would make it harder to use this functionality at 1628all. 1629 1630Note that, this function by default returns zero on success and a negative value on error. 1631Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} 1632it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. 1633 1634@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). 1635 1636@strong{Since:} 2.8.0 1637@end deftypefun 1638 1639@subheading gnutls_certificate_set_x509_system_trust 1640@anchor{gnutls_certificate_set_x509_system_trust} 1641@deftypefun {int} {gnutls_certificate_set_x509_system_trust} (gnutls_certificate_credentials_t @var{cred}) 1642@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1643 1644This function adds the system's default trusted CAs in order to 1645verify client or server certificates. 1646 1647In the case the system is currently unsupported @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} 1648is returned. 1649 1650@strong{Returns:} the number of certificates processed or a negative error code 1651on error. 1652 1653@strong{Since:} 3.0.20 1654@end deftypefun 1655 1656@subheading gnutls_certificate_set_x509_trust 1657@anchor{gnutls_certificate_set_x509_trust} 1658@deftypefun {int} {gnutls_certificate_set_x509_trust} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crt_t * @var{ca_list}, int @var{ca_list_size}) 1659@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1660 1661@var{ca_list}: is a list of trusted CAs 1662 1663@var{ca_list_size}: holds the size of the CA list 1664 1665This function adds the trusted CAs in order to verify client 1666or server certificates. In case of a client this is not required 1667to be called if the certificates are not verified using 1668@code{gnutls_certificate_verify_peers2()} . 1669This function may be called multiple times. 1670 1671In case of a server the CAs set here will be sent to the client if 1672a certificate request is sent. This can be disabled using 1673@code{gnutls_certificate_send_x509_rdn_sequence()} . 1674 1675@strong{Returns:} the number of certificates processed or a negative error code 1676on error. 1677 1678@strong{Since:} 2.4.0 1679@end deftypefun 1680 1681@subheading gnutls_certificate_set_x509_trust_dir 1682@anchor{gnutls_certificate_set_x509_trust_dir} 1683@deftypefun {int} {gnutls_certificate_set_x509_trust_dir} (gnutls_certificate_credentials_t @var{cred}, const char * @var{ca_dir}, gnutls_x509_crt_fmt_t @var{type}) 1684@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1685 1686@var{ca_dir}: is a directory containing the list of trusted CAs (DER or PEM list) 1687 1688@var{type}: is PEM or DER 1689 1690This function adds the trusted CAs present in the directory in order to 1691verify client or server certificates. This function is identical 1692to @code{gnutls_certificate_set_x509_trust_file()} but loads all certificates 1693in a directory. 1694 1695@strong{Returns:} the number of certificates processed 1696 1697@strong{Since:} 3.3.6 1698@end deftypefun 1699 1700@subheading gnutls_certificate_set_x509_trust_file 1701@anchor{gnutls_certificate_set_x509_trust_file} 1702@deftypefun {int} {gnutls_certificate_set_x509_trust_file} (gnutls_certificate_credentials_t @var{cred}, const char * @var{cafile}, gnutls_x509_crt_fmt_t @var{type}) 1703@var{cred}: is a @code{gnutls_certificate_credentials_t} type. 1704 1705@var{cafile}: is a file containing the list of trusted CAs (DER or PEM list) 1706 1707@var{type}: is PEM or DER 1708 1709This function adds the trusted CAs in order to verify client or 1710server certificates. In case of a client this is not required to 1711be called if the certificates are not verified using 1712@code{gnutls_certificate_verify_peers2()} . This function may be called 1713multiple times. 1714 1715In case of a server the names of the CAs set here will be sent to 1716the client if a certificate request is sent. This can be disabled 1717using @code{gnutls_certificate_send_x509_rdn_sequence()} . 1718 1719This function can also accept URLs. In that case it 1720will import all certificates that are marked as trusted. Note 1721that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . 1722 1723@strong{Returns:} the number of certificates processed 1724@end deftypefun 1725 1726@subheading gnutls_certificate_set_x509_trust_mem 1727@anchor{gnutls_certificate_set_x509_trust_mem} 1728@deftypefun {int} {gnutls_certificate_set_x509_trust_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{ca}, gnutls_x509_crt_fmt_t @var{type}) 1729@var{res}: is a @code{gnutls_certificate_credentials_t} type. 1730 1731@var{ca}: is a list of trusted CAs or a DER certificate 1732 1733@var{type}: is DER or PEM 1734 1735This function adds the trusted CAs in order to verify client or 1736server certificates. In case of a client this is not required to be 1737called if the certificates are not verified using 1738@code{gnutls_certificate_verify_peers2()} . This function may be called 1739multiple times. 1740 1741In case of a server the CAs set here will be sent to the client if 1742a certificate request is sent. This can be disabled using 1743@code{gnutls_certificate_send_x509_rdn_sequence()} . 1744 1745@strong{Returns:} the number of certificates processed or a negative error code 1746on error. 1747@end deftypefun 1748 1749@subheading gnutls_certificate_type_get 1750@anchor{gnutls_certificate_type_get} 1751@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get} (gnutls_session_t @var{session}) 1752@var{session}: is a @code{gnutls_session_t} type. 1753 1754This function returns the type of the certificate that is negotiated 1755for this side to send to the peer. The certificate type is by default 1756X.509, unless an alternative certificate type is enabled by 1757@code{gnutls_init()} and negotiated during the session. 1758 1759Resumed sessions will return the certificate type that was negotiated 1760and used in the original session. 1761 1762As of version 3.6.4 it is recommended to use 1763@code{gnutls_certificate_type_get2()} which is more fine-grained. 1764 1765@strong{Returns:} the currently used @code{gnutls_certificate_type_t} certificate 1766type as negotiated for 'our' side of the connection. 1767@end deftypefun 1768 1769@subheading gnutls_certificate_type_get2 1770@anchor{gnutls_certificate_type_get2} 1771@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get2} (gnutls_session_t @var{session}, gnutls_ctype_target_t @var{target}) 1772@var{session}: is a @code{gnutls_session_t} type. 1773 1774@var{target}: is a @code{gnutls_ctype_target_t} type. 1775 1776This function returns the type of the certificate that a side 1777is negotiated to use. The certificate type is by default X.509, 1778unless an alternative certificate type is enabled by @code{gnutls_init()} and 1779negotiated during the session. 1780 1781The @code{target} parameter specifies whether to request the negotiated 1782certificate type for the client (@code{GNUTLS_CTYPE_CLIENT} ), 1783or for the server (@code{GNUTLS_CTYPE_SERVER} ). Additionally, in P2P mode 1784connection set up where you don't know in advance who will be client 1785and who will be server you can use the flag (@code{GNUTLS_CTYPE_OURS} ) and 1786(@code{GNUTLS_CTYPE_PEERS} ) to retrieve the corresponding certificate types. 1787 1788Resumed sessions will return the certificate type that was negotiated 1789and used in the original session. That is, this function can be used 1790to reliably determine the type of the certificate returned by 1791@code{gnutls_certificate_get_peers()} . 1792 1793@strong{Returns:} the currently used @code{gnutls_certificate_type_t} certificate 1794type for the client or the server. 1795 1796@strong{Since:} 3.6.4 1797@end deftypefun 1798 1799@subheading gnutls_certificate_type_get_id 1800@anchor{gnutls_certificate_type_get_id} 1801@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get_id} (const char * @var{name}) 1802@var{name}: is a certificate type name 1803 1804The names are compared in a case insensitive way. 1805 1806@strong{Returns:} a @code{gnutls_certificate_type_t} for the specified in a 1807string certificate type, or @code{GNUTLS_CRT_UNKNOWN} on error. 1808@end deftypefun 1809 1810@subheading gnutls_certificate_type_get_name 1811@anchor{gnutls_certificate_type_get_name} 1812@deftypefun {const char *} {gnutls_certificate_type_get_name} (gnutls_certificate_type_t @var{type}) 1813@var{type}: is a certificate type 1814 1815Convert a @code{gnutls_certificate_type_t} type to a string. 1816 1817@strong{Returns:} a string that contains the name of the specified 1818certificate type, or @code{NULL} in case of unknown types. 1819@end deftypefun 1820 1821@subheading gnutls_certificate_type_list 1822@anchor{gnutls_certificate_type_list} 1823@deftypefun {const gnutls_certificate_type_t *} {gnutls_certificate_type_list} ( @var{void}) 1824 1825Get a list of certificate types. 1826 1827@strong{Returns:} a (0)-terminated list of @code{gnutls_certificate_type_t} 1828integers indicating the available certificate types. 1829@end deftypefun 1830 1831@subheading gnutls_certificate_verification_status_print 1832@anchor{gnutls_certificate_verification_status_print} 1833@deftypefun {int} {gnutls_certificate_verification_status_print} (unsigned int @var{status}, gnutls_certificate_type_t @var{type}, gnutls_datum_t * @var{out}, unsigned int @var{flags}) 1834@var{status}: The status flags to be printed 1835 1836@var{type}: The certificate type 1837 1838@var{out}: Newly allocated datum with (0) terminated string. 1839 1840@var{flags}: should be zero 1841 1842This function will pretty print the status of a verification 1843process -- eg. the one obtained by @code{gnutls_certificate_verify_peers3()} . 1844 1845The output @code{out} needs to be deallocated using @code{gnutls_free()} . 1846 1847@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1848negative error value. 1849 1850@strong{Since:} 3.1.4 1851@end deftypefun 1852 1853@subheading gnutls_certificate_verify_peers 1854@anchor{gnutls_certificate_verify_peers} 1855@deftypefun {int} {gnutls_certificate_verify_peers} (gnutls_session_t @var{session}, gnutls_typed_vdata_st * @var{data}, unsigned int @var{elements}, unsigned int * @var{status}) 1856@var{session}: is a gnutls session 1857 1858@var{data}: an array of typed data 1859 1860@var{elements}: the number of data elements 1861 1862@var{status}: is the output of the verification 1863 1864This function will verify the peer's certificate and store the 1865the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t 1866values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure 1867to trust a certificate does not imply a negative return value). 1868The default verification flags used by this function can be overridden 1869using @code{gnutls_certificate_set_verify_flags()} . See the documentation 1870of @code{gnutls_certificate_verify_peers2()} for details in the verification process. 1871 1872This function will take into account the stapled OCSP responses sent by the server, 1873as well as the following X.509 certificate extensions: Name Constraints, 1874Key Usage, and Basic Constraints (pathlen). 1875 1876The acceptable @code{data} types are @code{GNUTLS_DT_DNS_HOSTNAME} , @code{GNUTLS_DT_RFC822NAME} and @code{GNUTLS_DT_KEY_PURPOSE_OID} . 1877The former two accept as data a null-terminated hostname or email address, and the latter a null-terminated 1878object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ). 1879 1880If a DNS hostname is provided then this function will compare 1881the hostname in the certificate against the given. If names do not match the 1882@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. 1883If a key purpose OID is provided and the end-certificate contains the extended key 1884usage PKIX extension, it will be required to be have the provided key purpose 1885or be marked for any purpose, otherwise verification status will have the 1886@code{GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE} flag set. 1887 1888To avoid denial of service attacks some 1889default upper limits regarding the certificate key size and chain 1890size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . 1891 1892Note that when using raw public-keys verification will not work because there is 1893no corresponding certificate body belonging to the raw key that can be verified. In that 1894case this function will return @code{GNUTLS_E_INVALID_REQUEST} . 1895 1896@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. 1897A successful error code means that the @code{status} parameter must be checked to obtain the validation status. 1898 1899@strong{Since:} 3.3.0 1900@end deftypefun 1901 1902@subheading gnutls_certificate_verify_peers2 1903@anchor{gnutls_certificate_verify_peers2} 1904@deftypefun {int} {gnutls_certificate_verify_peers2} (gnutls_session_t @var{session}, unsigned int * @var{status}) 1905@var{session}: is a gnutls session 1906 1907@var{status}: is the output of the verification 1908 1909This function will verify the peer's certificate and store 1910the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t 1911values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure 1912to trust a certificate does not imply a negative return value). 1913The default verification flags used by this function can be overridden 1914using @code{gnutls_certificate_set_verify_flags()} . 1915 1916This function will take into account the stapled OCSP responses sent by the server, 1917as well as the following X.509 certificate extensions: Name Constraints, 1918Key Usage, and Basic Constraints (pathlen). 1919 1920Note that you must also check the peer's name in order to check if 1921the verified certificate belongs to the actual peer, see @code{gnutls_x509_crt_check_hostname()} , 1922or use @code{gnutls_certificate_verify_peers3()} . 1923 1924To avoid denial of service attacks some 1925default upper limits regarding the certificate key size and chain 1926size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . 1927 1928Note that when using raw public-keys verification will not work because there is 1929no corresponding certificate body belonging to the raw key that can be verified. In that 1930case this function will return @code{GNUTLS_E_INVALID_REQUEST} . 1931 1932@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. 1933A successful error code means that the @code{status} parameter must be checked to obtain the validation status. 1934@end deftypefun 1935 1936@subheading gnutls_certificate_verify_peers3 1937@anchor{gnutls_certificate_verify_peers3} 1938@deftypefun {int} {gnutls_certificate_verify_peers3} (gnutls_session_t @var{session}, const char * @var{hostname}, unsigned int * @var{status}) 1939@var{session}: is a gnutls session 1940 1941@var{hostname}: is the expected name of the peer; may be @code{NULL} 1942 1943@var{status}: is the output of the verification 1944 1945This function will verify the peer's certificate and store the 1946the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t 1947values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure 1948to trust a certificate does not imply a negative return value). 1949The default verification flags used by this function can be overridden 1950using @code{gnutls_certificate_set_verify_flags()} . See the documentation 1951of @code{gnutls_certificate_verify_peers2()} for details in the verification process. 1952 1953This function will take into account the stapled OCSP responses sent by the server, 1954as well as the following X.509 certificate extensions: Name Constraints, 1955Key Usage, and Basic Constraints (pathlen). 1956 1957If the @code{hostname} provided is non-NULL then this function will compare 1958the hostname in the certificate against it. The comparison will follow 1959the RFC6125 recommendations. If names do not match the 1960@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. 1961 1962In order to verify the purpose of the end-certificate (by checking the extended 1963key usage), use @code{gnutls_certificate_verify_peers()} . 1964 1965To avoid denial of service attacks some 1966default upper limits regarding the certificate key size and chain 1967size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . 1968 1969Note that when using raw public-keys verification will not work because there is 1970no corresponding certificate body belonging to the raw key that can be verified. In that 1971case this function will return @code{GNUTLS_E_INVALID_REQUEST} . 1972 1973@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. 1974A successful error code means that the @code{status} parameter must be checked to obtain the validation status. 1975 1976@strong{Since:} 3.1.4 1977@end deftypefun 1978 1979@subheading gnutls_check_version 1980@anchor{gnutls_check_version} 1981@deftypefun {const char *} {gnutls_check_version} (const char * @var{req_version}) 1982@var{req_version}: version string to compare with, or @code{NULL} . 1983 1984Check the GnuTLS Library version against the provided string. 1985See @code{GNUTLS_VERSION} for a suitable @code{req_version} string. 1986 1987See also @code{gnutls_check_version_numeric()} , which provides this 1988functionality as a macro. 1989 1990@strong{Returns:} Check that the version of the library is at 1991minimum the one given as a string in @code{req_version} and return the 1992actual version string of the library; return @code{NULL} if the 1993condition is not met. If @code{NULL} is passed to this function no 1994check is done and only the version string is returned. 1995@end deftypefun 1996 1997@subheading gnutls_cipher_get 1998@anchor{gnutls_cipher_get} 1999@deftypefun {gnutls_cipher_algorithm_t} {gnutls_cipher_get} (gnutls_session_t @var{session}) 2000@var{session}: is a @code{gnutls_session_t} type. 2001 2002Get the currently used cipher. 2003 2004@strong{Returns:} the currently used cipher, a @code{gnutls_cipher_algorithm_t} 2005type. 2006@end deftypefun 2007 2008@subheading gnutls_cipher_get_id 2009@anchor{gnutls_cipher_get_id} 2010@deftypefun {gnutls_cipher_algorithm_t} {gnutls_cipher_get_id} (const char * @var{name}) 2011@var{name}: is a cipher algorithm name 2012 2013The names are compared in a case insensitive way. 2014 2015@strong{Returns:} return a @code{gnutls_cipher_algorithm_t} value corresponding to 2016the specified cipher, or @code{GNUTLS_CIPHER_UNKNOWN} on error. 2017@end deftypefun 2018 2019@subheading gnutls_cipher_get_key_size 2020@anchor{gnutls_cipher_get_key_size} 2021@deftypefun {size_t} {gnutls_cipher_get_key_size} (gnutls_cipher_algorithm_t @var{algorithm}) 2022@var{algorithm}: is an encryption algorithm 2023 2024This function returns the key size of the provided algorithm. 2025 2026@strong{Returns:} length (in bytes) of the given cipher's key size, or 0 if 2027the given cipher is invalid. 2028@end deftypefun 2029 2030@subheading gnutls_cipher_get_name 2031@anchor{gnutls_cipher_get_name} 2032@deftypefun {const char *} {gnutls_cipher_get_name} (gnutls_cipher_algorithm_t @var{algorithm}) 2033@var{algorithm}: is an encryption algorithm 2034 2035Convert a @code{gnutls_cipher_algorithm_t} type to a string. 2036 2037@strong{Returns:} a pointer to a string that contains the name of the 2038specified cipher, or @code{NULL} . 2039@end deftypefun 2040 2041@subheading gnutls_cipher_list 2042@anchor{gnutls_cipher_list} 2043@deftypefun {const gnutls_cipher_algorithm_t *} {gnutls_cipher_list} ( @var{void}) 2044 2045Get a list of supported cipher algorithms. Note that not 2046necessarily all ciphers are supported as TLS cipher suites. For 2047example, DES is not supported as a cipher suite, but is supported 2048for other purposes (e.g., PKCS@code{8} or similar). 2049 2050This function is not thread safe. 2051 2052@strong{Returns:} a (0)-terminated list of @code{gnutls_cipher_algorithm_t} 2053integers indicating the available ciphers. 2054@end deftypefun 2055 2056@subheading gnutls_cipher_suite_get_name 2057@anchor{gnutls_cipher_suite_get_name} 2058@deftypefun {const char *} {gnutls_cipher_suite_get_name} (gnutls_kx_algorithm_t @var{kx_algorithm}, gnutls_cipher_algorithm_t @var{cipher_algorithm}, gnutls_mac_algorithm_t @var{mac_algorithm}) 2059@var{kx_algorithm}: is a Key exchange algorithm 2060 2061@var{cipher_algorithm}: is a cipher algorithm 2062 2063@var{mac_algorithm}: is a MAC algorithm 2064 2065This function returns the ciphersuite name under TLS1.2 or earlier 2066versions when provided with individual algorithms. The full cipher suite 2067name must be prepended by TLS or SSL depending of the protocol in use. 2068 2069To get a description of the current ciphersuite across versions, it 2070is recommended to use @code{gnutls_session_get_desc()} . 2071 2072@strong{Returns:} a string that contains the name of a TLS cipher suite, 2073specified by the given algorithms, or @code{NULL} . 2074@end deftypefun 2075 2076@subheading gnutls_cipher_suite_info 2077@anchor{gnutls_cipher_suite_info} 2078@deftypefun {const char *} {gnutls_cipher_suite_info} (size_t @var{idx}, unsigned char * @var{cs_id}, gnutls_kx_algorithm_t * @var{kx}, gnutls_cipher_algorithm_t * @var{cipher}, gnutls_mac_algorithm_t * @var{mac}, gnutls_protocol_t * @var{min_version}) 2079@var{idx}: index of cipher suite to get information about, starts on 0. 2080 2081@var{cs_id}: output buffer with room for 2 bytes, indicating cipher suite value 2082 2083@var{kx}: output variable indicating key exchange algorithm, or @code{NULL} . 2084 2085@var{cipher}: output variable indicating cipher, or @code{NULL} . 2086 2087@var{mac}: output variable indicating MAC algorithm, or @code{NULL} . 2088 2089@var{min_version}: output variable indicating TLS protocol version, or @code{NULL} . 2090 2091Get information about supported cipher suites. Use the function 2092iteratively to get information about all supported cipher suites. 2093Call with idx=0 to get information about first cipher suite, then 2094idx=1 and so on until the function returns NULL. 2095 2096@strong{Returns:} the name of @code{idx} cipher suite, and set the information 2097about the cipher suite in the output variables. If @code{idx} is out of 2098bounds, @code{NULL} is returned. 2099@end deftypefun 2100 2101@subheading gnutls_credentials_clear 2102@anchor{gnutls_credentials_clear} 2103@deftypefun {void} {gnutls_credentials_clear} (gnutls_session_t @var{session}) 2104@var{session}: is a @code{gnutls_session_t} type. 2105 2106Clears all the credentials previously set in this session. 2107@end deftypefun 2108 2109@subheading gnutls_credentials_get 2110@anchor{gnutls_credentials_get} 2111@deftypefun {int} {gnutls_credentials_get} (gnutls_session_t @var{session}, gnutls_credentials_type_t @var{type}, void ** @var{cred}) 2112@var{session}: is a @code{gnutls_session_t} type. 2113 2114@var{type}: is the type of the credentials to return 2115 2116@var{cred}: will contain the credentials. 2117 2118Returns the previously provided credentials structures. 2119 2120For @code{GNUTLS_CRD_ANON} , @code{cred} will be 2121@code{gnutls_anon_client_credentials_t} in case of a client. In case of 2122a server it should be @code{gnutls_anon_server_credentials_t} . 2123 2124For @code{GNUTLS_CRD_SRP} , @code{cred} will be @code{gnutls_srp_client_credentials_t} 2125in case of a client, and @code{gnutls_srp_server_credentials_t} , in case 2126of a server. 2127 2128For @code{GNUTLS_CRD_CERTIFICATE} , @code{cred} will be 2129@code{gnutls_certificate_credentials_t} . 2130 2131@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2132otherwise a negative error code is returned. 2133 2134@strong{Since:} 3.3.3 2135@end deftypefun 2136 2137@subheading gnutls_credentials_set 2138@anchor{gnutls_credentials_set} 2139@deftypefun {int} {gnutls_credentials_set} (gnutls_session_t @var{session}, gnutls_credentials_type_t @var{type}, void * @var{cred}) 2140@var{session}: is a @code{gnutls_session_t} type. 2141 2142@var{type}: is the type of the credentials 2143 2144@var{cred}: the credentials to set 2145 2146Sets the needed credentials for the specified type. E.g. username, 2147password - or public and private keys etc. The @code{cred} parameter is 2148a structure that depends on the specified type and on the current 2149session (client or server). 2150 2151In order to minimize memory usage, and share credentials between 2152several threads gnutls keeps a pointer to cred, and not the whole 2153cred structure. Thus you will have to keep the structure allocated 2154until you call @code{gnutls_deinit()} . 2155 2156For @code{GNUTLS_CRD_ANON} , @code{cred} should be 2157@code{gnutls_anon_client_credentials_t} in case of a client. In case of 2158a server it should be @code{gnutls_anon_server_credentials_t} . 2159 2160For @code{GNUTLS_CRD_SRP} , @code{cred} should be @code{gnutls_srp_client_credentials_t} 2161in case of a client, and @code{gnutls_srp_server_credentials_t} , in case 2162of a server. 2163 2164For @code{GNUTLS_CRD_CERTIFICATE} , @code{cred} should be 2165@code{gnutls_certificate_credentials_t} . 2166 2167@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2168otherwise a negative error code is returned. 2169@end deftypefun 2170 2171@subheading gnutls_db_check_entry 2172@anchor{gnutls_db_check_entry} 2173@deftypefun {int} {gnutls_db_check_entry} (gnutls_session_t @var{session}, gnutls_datum_t @var{session_entry}) 2174@var{session}: is a @code{gnutls_session_t} type. 2175 2176@var{session_entry}: is the session data (not key) 2177 2178This function has no effect. 2179 2180@strong{Returns:} Returns @code{GNUTLS_E_EXPIRED} , if the database entry has 2181expired or 0 otherwise. 2182 2183@strong{Deprecated:} This function is deprecated. 2184@end deftypefun 2185 2186@subheading gnutls_db_check_entry_expire_time 2187@anchor{gnutls_db_check_entry_expire_time} 2188@deftypefun {time_t} {gnutls_db_check_entry_expire_time} (gnutls_datum_t * @var{entry}) 2189@var{entry}: is a pointer to a @code{gnutls_datum_t} type. 2190 2191This function returns the time that this entry will expire. 2192It can be used for database entry expiration. 2193 2194@strong{Returns:} The time this entry will expire, or zero on error. 2195 2196@strong{Since:} 3.6.5 2197@end deftypefun 2198 2199@subheading gnutls_db_check_entry_time 2200@anchor{gnutls_db_check_entry_time} 2201@deftypefun {time_t} {gnutls_db_check_entry_time} (gnutls_datum_t * @var{entry}) 2202@var{entry}: is a pointer to a @code{gnutls_datum_t} type. 2203 2204This function returns the time that this entry was active. 2205It can be used for database entry expiration. 2206 2207@strong{Returns:} The time this entry was created, or zero on error. 2208@end deftypefun 2209 2210@subheading gnutls_db_get_default_cache_expiration 2211@anchor{gnutls_db_get_default_cache_expiration} 2212@deftypefun {unsigned} {gnutls_db_get_default_cache_expiration} ( @var{void}) 2213 2214Returns the expiration time (in seconds) of stored sessions for resumption. 2215@end deftypefun 2216 2217@subheading gnutls_db_get_ptr 2218@anchor{gnutls_db_get_ptr} 2219@deftypefun {void *} {gnutls_db_get_ptr} (gnutls_session_t @var{session}) 2220@var{session}: is a @code{gnutls_session_t} type. 2221 2222Get db function pointer. 2223 2224@strong{Returns:} the pointer that will be sent to db store, retrieve and 2225delete functions, as the first argument. 2226@end deftypefun 2227 2228@subheading gnutls_db_remove_session 2229@anchor{gnutls_db_remove_session} 2230@deftypefun {void} {gnutls_db_remove_session} (gnutls_session_t @var{session}) 2231@var{session}: is a @code{gnutls_session_t} type. 2232 2233This function will remove the current session data from the 2234session database. This will prevent future handshakes reusing 2235these session data. This function should be called if a session 2236was terminated abnormally, and before @code{gnutls_deinit()} is called. 2237 2238Normally @code{gnutls_deinit()} will remove abnormally terminated 2239sessions. 2240@end deftypefun 2241 2242@subheading gnutls_db_set_cache_expiration 2243@anchor{gnutls_db_set_cache_expiration} 2244@deftypefun {void} {gnutls_db_set_cache_expiration} (gnutls_session_t @var{session}, int @var{seconds}) 2245@var{session}: is a @code{gnutls_session_t} type. 2246 2247@var{seconds}: is the number of seconds. 2248 2249Set the expiration time for resumed sessions. The default is 21600 2250(6 hours) at the time of writing. 2251 2252The maximum value that can be set using this function is 604800 2253(7 days). 2254@end deftypefun 2255 2256@subheading gnutls_db_set_ptr 2257@anchor{gnutls_db_set_ptr} 2258@deftypefun {void} {gnutls_db_set_ptr} (gnutls_session_t @var{session}, void * @var{ptr}) 2259@var{session}: is a @code{gnutls_session_t} type. 2260 2261@var{ptr}: is the pointer 2262 2263Sets the pointer that will be provided to db store, retrieve and 2264delete functions, as the first argument. 2265@end deftypefun 2266 2267@subheading gnutls_db_set_remove_function 2268@anchor{gnutls_db_set_remove_function} 2269@deftypefun {void} {gnutls_db_set_remove_function} (gnutls_session_t @var{session}, gnutls_db_remove_func @var{rem_func}) 2270@var{session}: is a @code{gnutls_session_t} type. 2271 2272@var{rem_func}: is the function. 2273 2274Sets the function that will be used to remove data from the 2275resumed sessions database. This function must return 0 on success. 2276 2277The first argument to @code{rem_func} will be null unless 2278@code{gnutls_db_set_ptr()} has been called. 2279@end deftypefun 2280 2281@subheading gnutls_db_set_retrieve_function 2282@anchor{gnutls_db_set_retrieve_function} 2283@deftypefun {void} {gnutls_db_set_retrieve_function} (gnutls_session_t @var{session}, gnutls_db_retr_func @var{retr_func}) 2284@var{session}: is a @code{gnutls_session_t} type. 2285 2286@var{retr_func}: is the function. 2287 2288Sets the function that will be used to retrieve data from the 2289resumed sessions database. This function must return a 2290gnutls_datum_t containing the data on success, or a gnutls_datum_t 2291containing null and 0 on failure. 2292 2293The datum's data must be allocated using the function 2294@code{gnutls_malloc()} . 2295 2296The first argument to @code{retr_func} will be null unless 2297@code{gnutls_db_set_ptr()} has been called. 2298@end deftypefun 2299 2300@subheading gnutls_db_set_store_function 2301@anchor{gnutls_db_set_store_function} 2302@deftypefun {void} {gnutls_db_set_store_function} (gnutls_session_t @var{session}, gnutls_db_store_func @var{store_func}) 2303@var{session}: is a @code{gnutls_session_t} type. 2304 2305@var{store_func}: is the function 2306 2307Sets the function that will be used to store data in the resumed 2308sessions database. This function must return 0 on success. 2309 2310The first argument to @code{store_func} will be null unless 2311@code{gnutls_db_set_ptr()} has been called. 2312@end deftypefun 2313 2314@subheading gnutls_deinit 2315@anchor{gnutls_deinit} 2316@deftypefun {void} {gnutls_deinit} (gnutls_session_t @var{session}) 2317@var{session}: is a @code{gnutls_session_t} type. 2318 2319This function clears all buffers associated with the @code{session} . 2320This function will also remove session data from the session 2321database if the session was terminated abnormally. 2322@end deftypefun 2323 2324@subheading gnutls_dh_get_group 2325@anchor{gnutls_dh_get_group} 2326@deftypefun {int} {gnutls_dh_get_group} (gnutls_session_t @var{session}, gnutls_datum_t * @var{raw_gen}, gnutls_datum_t * @var{raw_prime}) 2327@var{session}: is a gnutls session 2328 2329@var{raw_gen}: will hold the generator. 2330 2331@var{raw_prime}: will hold the prime. 2332 2333This function will return the group parameters used in the last 2334Diffie-Hellman key exchange with the peer. These are the prime and 2335the generator used. This function should be used for both 2336anonymous and ephemeral Diffie-Hellman. The output parameters must 2337be freed with @code{gnutls_free()} . 2338 2339Note, that the prime and generator are exported as non-negative 2340integers and may include a leading zero byte. 2341 2342@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 2343an error code is returned. 2344@end deftypefun 2345 2346@subheading gnutls_dh_get_peers_public_bits 2347@anchor{gnutls_dh_get_peers_public_bits} 2348@deftypefun {int} {gnutls_dh_get_peers_public_bits} (gnutls_session_t @var{session}) 2349@var{session}: is a gnutls session 2350 2351Get the Diffie-Hellman public key bit size. Can be used for both 2352anonymous and ephemeral Diffie-Hellman. 2353 2354@strong{Returns:} The public key bit size used in the last Diffie-Hellman 2355key exchange with the peer, or a negative error code in case of error. 2356@end deftypefun 2357 2358@subheading gnutls_dh_get_prime_bits 2359@anchor{gnutls_dh_get_prime_bits} 2360@deftypefun {int} {gnutls_dh_get_prime_bits} (gnutls_session_t @var{session}) 2361@var{session}: is a gnutls session 2362 2363This function will return the bits of the prime used in the last 2364Diffie-Hellman key exchange with the peer. Should be used for both 2365anonymous and ephemeral Diffie-Hellman. Note that some ciphers, 2366like RSA and DSA without DHE, do not use a Diffie-Hellman key 2367exchange, and then this function will return 0. 2368 2369@strong{Returns:} The Diffie-Hellman bit strength is returned, or 0 if no 2370Diffie-Hellman key exchange was done, or a negative error code on 2371failure. 2372@end deftypefun 2373 2374@subheading gnutls_dh_get_pubkey 2375@anchor{gnutls_dh_get_pubkey} 2376@deftypefun {int} {gnutls_dh_get_pubkey} (gnutls_session_t @var{session}, gnutls_datum_t * @var{raw_key}) 2377@var{session}: is a gnutls session 2378 2379@var{raw_key}: will hold the public key. 2380 2381This function will return the peer's public key used in the last 2382Diffie-Hellman key exchange. This function should be used for both 2383anonymous and ephemeral Diffie-Hellman. The output parameters must 2384be freed with @code{gnutls_free()} . 2385 2386Note, that public key is exported as non-negative 2387integer and may include a leading zero byte. 2388 2389@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 2390an error code is returned. 2391@end deftypefun 2392 2393@subheading gnutls_dh_get_secret_bits 2394@anchor{gnutls_dh_get_secret_bits} 2395@deftypefun {int} {gnutls_dh_get_secret_bits} (gnutls_session_t @var{session}) 2396@var{session}: is a gnutls session 2397 2398This function will return the bits used in the last Diffie-Hellman 2399key exchange with the peer. Should be used for both anonymous and 2400ephemeral Diffie-Hellman. 2401 2402@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 2403an error code is returned. 2404@end deftypefun 2405 2406@subheading gnutls_dh_params_cpy 2407@anchor{gnutls_dh_params_cpy} 2408@deftypefun {int} {gnutls_dh_params_cpy} (gnutls_dh_params_t @var{dst}, gnutls_dh_params_t @var{src}) 2409@var{dst}: Is the destination parameters, which should be initialized. 2410 2411@var{src}: Is the source parameters 2412 2413This function will copy the DH parameters structure from source 2414to destination. The destination should be already initialized. 2415 2416@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2417otherwise a negative error code is returned. 2418@end deftypefun 2419 2420@subheading gnutls_dh_params_deinit 2421@anchor{gnutls_dh_params_deinit} 2422@deftypefun {void} {gnutls_dh_params_deinit} (gnutls_dh_params_t @var{dh_params}) 2423@var{dh_params}: The parameters 2424 2425This function will deinitialize the DH parameters type. 2426@end deftypefun 2427 2428@subheading gnutls_dh_params_export2_pkcs3 2429@anchor{gnutls_dh_params_export2_pkcs3} 2430@deftypefun {int} {gnutls_dh_params_export2_pkcs3} (gnutls_dh_params_t @var{params}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 2431@var{params}: Holds the DH parameters 2432 2433@var{format}: the format of output params. One of PEM or DER. 2434 2435@var{out}: will contain a PKCS3 DHParams structure PEM or DER encoded 2436 2437This function will export the given dh parameters to a PKCS3 2438DHParams structure. This is the format generated by "openssl dhparam" tool. 2439The data in @code{out} will be allocated using @code{gnutls_malloc()} . 2440 2441If the structure is PEM encoded, it will have a header 2442of "BEGIN DH PARAMETERS". 2443 2444@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2445otherwise a negative error code is returned. 2446 2447@strong{Since:} 3.1.3 2448@end deftypefun 2449 2450@subheading gnutls_dh_params_export_pkcs3 2451@anchor{gnutls_dh_params_export_pkcs3} 2452@deftypefun {int} {gnutls_dh_params_export_pkcs3} (gnutls_dh_params_t @var{params}, gnutls_x509_crt_fmt_t @var{format}, unsigned char * @var{params_data}, size_t * @var{params_data_size}) 2453@var{params}: Holds the DH parameters 2454 2455@var{format}: the format of output params. One of PEM or DER. 2456 2457@var{params_data}: will contain a PKCS3 DHParams structure PEM or DER encoded 2458 2459@var{params_data_size}: holds the size of params_data (and will be replaced by the actual size of parameters) 2460 2461This function will export the given dh parameters to a PKCS3 2462DHParams structure. This is the format generated by "openssl dhparam" tool. 2463If the buffer provided is not long enough to hold the output, then 2464GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. 2465 2466If the structure is PEM encoded, it will have a header 2467of "BEGIN DH PARAMETERS". 2468 2469@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2470otherwise a negative error code is returned. 2471@end deftypefun 2472 2473@subheading gnutls_dh_params_export_raw 2474@anchor{gnutls_dh_params_export_raw} 2475@deftypefun {int} {gnutls_dh_params_export_raw} (gnutls_dh_params_t @var{params}, gnutls_datum_t * @var{prime}, gnutls_datum_t * @var{generator}, unsigned int * @var{bits}) 2476@var{params}: Holds the DH parameters 2477 2478@var{prime}: will hold the new prime 2479 2480@var{generator}: will hold the new generator 2481 2482@var{bits}: if non null will hold the secret key's number of bits 2483 2484This function will export the pair of prime and generator for use 2485in the Diffie-Hellman key exchange. The new parameters will be 2486allocated using @code{gnutls_malloc()} and will be stored in the 2487appropriate datum. 2488 2489@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2490otherwise a negative error code is returned. 2491@end deftypefun 2492 2493@subheading gnutls_dh_params_generate2 2494@anchor{gnutls_dh_params_generate2} 2495@deftypefun {int} {gnutls_dh_params_generate2} (gnutls_dh_params_t @var{dparams}, unsigned int @var{bits}) 2496@var{dparams}: The parameters 2497 2498@var{bits}: is the prime's number of bits 2499 2500This function will generate a new pair of prime and generator for use in 2501the Diffie-Hellman key exchange. This may take long time. 2502 2503It is recommended not to set the number of bits directly, but 2504use @code{gnutls_sec_param_to_pk_bits()} instead. 2505Also note that the DH parameters are only useful to servers. 2506Since clients use the parameters sent by the server, it's of 2507no use to call this in client side. 2508 2509The parameters generated are of the DSA form. It also is possible 2510to generate provable parameters (following the Shawe-Taylor 2511algorithm), using @code{gnutls_x509_privkey_generate2()} with DSA option 2512and the @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} flag set. These can the 2513be imported with @code{gnutls_dh_params_import_dsa()} . 2514 2515It is no longer recommended for applications to generate parameters. 2516See the "Parameter generation" section in the manual. 2517 2518@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2519otherwise a negative error code is returned. 2520@end deftypefun 2521 2522@subheading gnutls_dh_params_import_dsa 2523@anchor{gnutls_dh_params_import_dsa} 2524@deftypefun {int} {gnutls_dh_params_import_dsa} (gnutls_dh_params_t @var{dh_params}, gnutls_x509_privkey_t @var{key}) 2525@var{dh_params}: The parameters 2526 2527@var{key}: holds a DSA private key 2528 2529This function will import the prime and generator of the DSA key for use 2530in the Diffie-Hellman key exchange. 2531 2532@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2533otherwise a negative error code is returned. 2534@end deftypefun 2535 2536@subheading gnutls_dh_params_import_pkcs3 2537@anchor{gnutls_dh_params_import_pkcs3} 2538@deftypefun {int} {gnutls_dh_params_import_pkcs3} (gnutls_dh_params_t @var{params}, const gnutls_datum_t * @var{pkcs3_params}, gnutls_x509_crt_fmt_t @var{format}) 2539@var{params}: The parameters 2540 2541@var{pkcs3_params}: should contain a PKCS3 DHParams structure PEM or DER encoded 2542 2543@var{format}: the format of params. PEM or DER. 2544 2545This function will extract the DHParams found in a PKCS3 formatted 2546structure. This is the format generated by "openssl dhparam" tool. 2547 2548If the structure is PEM encoded, it should have a header 2549of "BEGIN DH PARAMETERS". 2550 2551@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2552otherwise a negative error code is returned. 2553@end deftypefun 2554 2555@subheading gnutls_dh_params_import_raw 2556@anchor{gnutls_dh_params_import_raw} 2557@deftypefun {int} {gnutls_dh_params_import_raw} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{generator}) 2558@var{dh_params}: The parameters 2559 2560@var{prime}: holds the new prime 2561 2562@var{generator}: holds the new generator 2563 2564This function will replace the pair of prime and generator for use 2565in the Diffie-Hellman key exchange. The new parameters should be 2566stored in the appropriate gnutls_datum. 2567 2568@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2569otherwise a negative error code is returned. 2570@end deftypefun 2571 2572@subheading gnutls_dh_params_import_raw2 2573@anchor{gnutls_dh_params_import_raw2} 2574@deftypefun {int} {gnutls_dh_params_import_raw2} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{generator}, unsigned @var{key_bits}) 2575@var{dh_params}: The parameters 2576 2577@var{prime}: holds the new prime 2578 2579@var{generator}: holds the new generator 2580 2581@var{key_bits}: the private key bits (set to zero when unknown) 2582 2583This function will replace the pair of prime and generator for use 2584in the Diffie-Hellman key exchange. The new parameters should be 2585stored in the appropriate gnutls_datum. 2586 2587@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2588otherwise a negative error code is returned. 2589@end deftypefun 2590 2591@subheading gnutls_dh_params_import_raw3 2592@anchor{gnutls_dh_params_import_raw3} 2593@deftypefun {int} {gnutls_dh_params_import_raw3} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{generator}) 2594@var{dh_params}: The parameters 2595 2596@var{prime}: holds the new prime 2597 2598@var{q}: holds the subgroup if available, otherwise NULL 2599 2600@var{generator}: holds the new generator 2601 2602This function will replace the pair of prime and generator for use 2603in the Diffie-Hellman key exchange. The new parameters should be 2604stored in the appropriate gnutls_datum. 2605 2606@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2607otherwise a negative error code is returned. 2608@end deftypefun 2609 2610@subheading gnutls_dh_params_init 2611@anchor{gnutls_dh_params_init} 2612@deftypefun {int} {gnutls_dh_params_init} (gnutls_dh_params_t * @var{dh_params}) 2613@var{dh_params}: The parameters 2614 2615This function will initialize the DH parameters type. 2616 2617@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2618otherwise a negative error code is returned. 2619@end deftypefun 2620 2621@subheading gnutls_dh_set_prime_bits 2622@anchor{gnutls_dh_set_prime_bits} 2623@deftypefun {void} {gnutls_dh_set_prime_bits} (gnutls_session_t @var{session}, unsigned int @var{bits}) 2624@var{session}: is a @code{gnutls_session_t} type. 2625 2626@var{bits}: is the number of bits 2627 2628This function sets the number of bits, for use in a Diffie-Hellman 2629key exchange. This is used both in DH ephemeral and DH anonymous 2630cipher suites. This will set the minimum size of the prime that 2631will be used for the handshake. 2632 2633In the client side it sets the minimum accepted number of bits. If 2634a server sends a prime with less bits than that 2635@code{GNUTLS_E_DH_PRIME_UNACCEPTABLE} will be returned by the handshake. 2636 2637Note that this function will warn via the audit log for value that 2638are believed to be weak. 2639 2640The function has no effect in server side. 2641 2642Note that since 3.1.7 this function is deprecated. The minimum 2643number of bits is set by the priority string level. 2644Also this function must be called after @code{gnutls_priority_set_direct()} 2645or the set value may be overridden by the selected priority options. 2646@end deftypefun 2647 2648@subheading gnutls_digest_get_id 2649@anchor{gnutls_digest_get_id} 2650@deftypefun {gnutls_digest_algorithm_t} {gnutls_digest_get_id} (const char * @var{name}) 2651@var{name}: is a digest algorithm name 2652 2653Convert a string to a @code{gnutls_digest_algorithm_t} value. The names are 2654compared in a case insensitive way. 2655 2656@strong{Returns:} a @code{gnutls_digest_algorithm_t} id of the specified MAC 2657algorithm string, or @code{GNUTLS_DIG_UNKNOWN} on failure. 2658@end deftypefun 2659 2660@subheading gnutls_digest_get_name 2661@anchor{gnutls_digest_get_name} 2662@deftypefun {const char *} {gnutls_digest_get_name} (gnutls_digest_algorithm_t @var{algorithm}) 2663@var{algorithm}: is a digest algorithm 2664 2665Convert a @code{gnutls_digest_algorithm_t} value to a string. 2666 2667@strong{Returns:} a string that contains the name of the specified digest 2668algorithm, or @code{NULL} . 2669@end deftypefun 2670 2671@subheading gnutls_digest_get_oid 2672@anchor{gnutls_digest_get_oid} 2673@deftypefun {const char *} {gnutls_digest_get_oid} (gnutls_digest_algorithm_t @var{algorithm}) 2674@var{algorithm}: is a digest algorithm 2675 2676Convert a @code{gnutls_digest_algorithm_t} value to its object identifier. 2677 2678@strong{Returns:} a string that contains the object identifier of the specified digest 2679algorithm, or @code{NULL} . 2680 2681@strong{Since:} 3.4.3 2682@end deftypefun 2683 2684@subheading gnutls_digest_list 2685@anchor{gnutls_digest_list} 2686@deftypefun {const gnutls_digest_algorithm_t *} {gnutls_digest_list} ( @var{void}) 2687 2688Get a list of hash (digest) algorithms supported by GnuTLS. 2689 2690This function is not thread safe. 2691 2692@strong{Returns:} Return a (0)-terminated list of @code{gnutls_digest_algorithm_t} 2693integers indicating the available digests. 2694@end deftypefun 2695 2696@subheading gnutls_ecc_curve_get 2697@anchor{gnutls_ecc_curve_get} 2698@deftypefun {gnutls_ecc_curve_t} {gnutls_ecc_curve_get} (gnutls_session_t @var{session}) 2699@var{session}: is a @code{gnutls_session_t} type. 2700 2701Returns the currently used elliptic curve for key exchange. Only valid 2702when using an elliptic curve ciphersuite. 2703 2704@strong{Returns:} the currently used curve, a @code{gnutls_ecc_curve_t} 2705type. 2706 2707@strong{Since:} 3.0 2708@end deftypefun 2709 2710@subheading gnutls_ecc_curve_get_id 2711@anchor{gnutls_ecc_curve_get_id} 2712@deftypefun {gnutls_ecc_curve_t} {gnutls_ecc_curve_get_id} (const char * @var{name}) 2713@var{name}: is a curve name 2714 2715The names are compared in a case insensitive way. 2716 2717@strong{Returns:} return a @code{gnutls_ecc_curve_t} value corresponding to 2718the specified curve, or @code{GNUTLS_ECC_CURVE_INVALID} on error. 2719 2720@strong{Since:} 3.4.3 2721@end deftypefun 2722 2723@subheading gnutls_ecc_curve_get_name 2724@anchor{gnutls_ecc_curve_get_name} 2725@deftypefun {const char *} {gnutls_ecc_curve_get_name} (gnutls_ecc_curve_t @var{curve}) 2726@var{curve}: is an ECC curve 2727 2728Convert a @code{gnutls_ecc_curve_t} value to a string. 2729 2730@strong{Returns:} a string that contains the name of the specified 2731curve or @code{NULL} . 2732 2733@strong{Since:} 3.0 2734@end deftypefun 2735 2736@subheading gnutls_ecc_curve_get_oid 2737@anchor{gnutls_ecc_curve_get_oid} 2738@deftypefun {const char *} {gnutls_ecc_curve_get_oid} (gnutls_ecc_curve_t @var{curve}) 2739@var{curve}: is an ECC curve 2740 2741Convert a @code{gnutls_ecc_curve_t} value to its object identifier. 2742 2743@strong{Returns:} a string that contains the OID of the specified 2744curve or @code{NULL} . 2745 2746@strong{Since:} 3.4.3 2747@end deftypefun 2748 2749@subheading gnutls_ecc_curve_get_pk 2750@anchor{gnutls_ecc_curve_get_pk} 2751@deftypefun {gnutls_pk_algorithm_t} {gnutls_ecc_curve_get_pk} (gnutls_ecc_curve_t @var{curve}) 2752@var{curve}: is an ECC curve 2753 2754 2755@strong{Returns:} the public key algorithm associated with the named curve or @code{GNUTLS_PK_UNKNOWN} . 2756 2757@strong{Since:} 3.5.0 2758@end deftypefun 2759 2760@subheading gnutls_ecc_curve_get_size 2761@anchor{gnutls_ecc_curve_get_size} 2762@deftypefun {int} {gnutls_ecc_curve_get_size} (gnutls_ecc_curve_t @var{curve}) 2763@var{curve}: is an ECC curve 2764 2765 2766@strong{Returns:} the size in bytes of the curve or 0 on failure. 2767 2768@strong{Since:} 3.0 2769@end deftypefun 2770 2771@subheading gnutls_ecc_curve_list 2772@anchor{gnutls_ecc_curve_list} 2773@deftypefun {const gnutls_ecc_curve_t *} {gnutls_ecc_curve_list} ( @var{void}) 2774 2775Get the list of supported elliptic curves. 2776 2777This function is not thread safe. 2778 2779@strong{Returns:} Return a (0)-terminated list of @code{gnutls_ecc_curve_t} 2780integers indicating the available curves. 2781@end deftypefun 2782 2783@subheading gnutls_error_is_fatal 2784@anchor{gnutls_error_is_fatal} 2785@deftypefun {int} {gnutls_error_is_fatal} (int @var{error}) 2786@var{error}: is a GnuTLS error code, a negative error code 2787 2788If a GnuTLS function returns a negative error code you may feed that 2789value to this function to see if the error condition is fatal to 2790a TLS session (i.e., must be terminated). 2791 2792Note that you may also want to check the error code manually, since some 2793non-fatal errors to the protocol (such as a warning alert or 2794a rehandshake request) may be fatal for your program. 2795 2796This function is only useful if you are dealing with errors from 2797functions that relate to a TLS session (e.g., record layer or handshake 2798layer handling functions). 2799 2800@strong{Returns:} Non-zero value on fatal errors or zero on non-fatal. 2801@end deftypefun 2802 2803@subheading gnutls_error_to_alert 2804@anchor{gnutls_error_to_alert} 2805@deftypefun {int} {gnutls_error_to_alert} (int @var{err}, int * @var{level}) 2806@var{err}: is a negative integer 2807 2808@var{level}: the alert level will be stored there 2809 2810Get an alert depending on the error code returned by a gnutls 2811function. All alerts sent by this function should be considered 2812fatal. The only exception is when @code{err} is @code{GNUTLS_E_REHANDSHAKE} , 2813where a warning alert should be sent to the peer indicating that no 2814renegotiation will be performed. 2815 2816If there is no mapping to a valid alert the alert to indicate 2817internal error (@code{GNUTLS_A_INTERNAL_ERROR} ) is returned. 2818 2819@strong{Returns:} the alert code to use for a particular error code. 2820@end deftypefun 2821 2822@subheading gnutls_est_record_overhead_size 2823@anchor{gnutls_est_record_overhead_size} 2824@deftypefun {size_t} {gnutls_est_record_overhead_size} (gnutls_protocol_t @var{version}, gnutls_cipher_algorithm_t @var{cipher}, gnutls_mac_algorithm_t @var{mac}, gnutls_compression_method_t @var{comp}, unsigned int @var{flags}) 2825@var{version}: is a @code{gnutls_protocol_t} value 2826 2827@var{cipher}: is a @code{gnutls_cipher_algorithm_t} value 2828 2829@var{mac}: is a @code{gnutls_mac_algorithm_t} value 2830 2831@var{comp}: is a @code{gnutls_compression_method_t} value (ignored) 2832 2833@var{flags}: must be zero 2834 2835This function will return the set size in bytes of the overhead 2836due to TLS (or DTLS) per record. 2837 2838Note that this function may provide inaccurate values when TLS 2839extensions that modify the record format are negotiated. In these 2840cases a more accurate value can be obtained using @code{gnutls_record_overhead_size()} 2841after a completed handshake. 2842 2843@strong{Since:} 3.2.2 2844@end deftypefun 2845 2846@subheading gnutls_ext_get_current_msg 2847@anchor{gnutls_ext_get_current_msg} 2848@deftypefun {unsigned} {gnutls_ext_get_current_msg} (gnutls_session_t @var{session}) 2849@var{session}: a @code{gnutls_session_t} opaque pointer 2850 2851This function allows an extension handler to obtain the message 2852this extension is being called from. The returned value is a single 2853entry of the @code{gnutls_ext_flags_t} enumeration. That is, if an 2854extension was registered with the @code{GNUTLS_EXT_FLAG_HRR} and 2855@code{GNUTLS_EXT_FLAG_EE} flags, the value when called during parsing of the 2856encrypted extensions message will be @code{GNUTLS_EXT_FLAG_EE} . 2857 2858If not called under an extension handler, its value is undefined. 2859 2860@strong{Since:} 3.6.3 2861@end deftypefun 2862 2863@subheading gnutls_ext_get_data 2864@anchor{gnutls_ext_get_data} 2865@deftypefun {int} {gnutls_ext_get_data} (gnutls_session_t @var{session}, unsigned @var{tls_id}, gnutls_ext_priv_data_t * @var{data}) 2866@var{session}: a @code{gnutls_session_t} opaque pointer 2867 2868@var{tls_id}: the numeric id of the extension 2869 2870@var{data}: a pointer to the private data to retrieve 2871 2872This function retrieves any data previously stored with @code{gnutls_ext_set_data()} . 2873 2874@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 2875 2876@strong{Since:} 3.4.0 2877@end deftypefun 2878 2879@subheading gnutls_ext_get_name 2880@anchor{gnutls_ext_get_name} 2881@deftypefun {const char *} {gnutls_ext_get_name} (unsigned int @var{ext}) 2882@var{ext}: is a TLS extension numeric ID 2883 2884Convert a TLS extension numeric ID to a printable string. 2885 2886@strong{Returns:} a pointer to a string that contains the name of the 2887specified cipher, or @code{NULL} . 2888@end deftypefun 2889 2890@subheading gnutls_ext_get_name2 2891@anchor{gnutls_ext_get_name2} 2892@deftypefun {const char *} {gnutls_ext_get_name2} (gnutls_session_t @var{session}, unsigned int @var{tls_id}, gnutls_ext_parse_type_t @var{parse_point}) 2893@var{session}: a @code{gnutls_session_t} opaque pointer 2894 2895@var{tls_id}: is a TLS extension numeric ID 2896 2897@var{parse_point}: the parse type of the extension 2898 2899Convert a TLS extension numeric ID to a printable string. 2900 2901@strong{Returns:} a pointer to a string that contains the name of the 2902specified cipher, or @code{NULL} . 2903@end deftypefun 2904 2905@subheading gnutls_ext_raw_parse 2906@anchor{gnutls_ext_raw_parse} 2907@deftypefun {int} {gnutls_ext_raw_parse} (void * @var{ctx}, gnutls_ext_raw_process_func @var{cb}, const gnutls_datum_t * @var{data}, unsigned int @var{flags}) 2908@var{ctx}: a pointer to pass to callback function 2909 2910@var{cb}: callback function to process each extension found 2911 2912@var{data}: TLS extension data 2913 2914@var{flags}: should be zero or @code{GNUTLS_EXT_RAW_FLAG_TLS_CLIENT_HELLO} or @code{GNUTLS_EXT_RAW_FLAG_DTLS_CLIENT_HELLO} 2915 2916This function iterates through the TLS extensions as passed in 2917 @code{data} , passing the individual extension data to callback. The 2918 @code{data} must conform to Extension extensions<0..2^16-1> format. 2919 2920If flags is @code{GNUTLS_EXT_RAW_TLS_FLAG_CLIENT_HELLO} then this function 2921will parse the extension data from the position, as if the packet in 2922 @code{data} is a client hello (without record or handshake headers) - 2923as provided by @code{gnutls_handshake_set_hook_function()} . 2924 2925The return value of the callback will be propagated. 2926 2927@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. On unknown 2928flags it returns @code{GNUTLS_E_INVALID_REQUEST} . 2929 2930@strong{Since:} 3.6.3 2931@end deftypefun 2932 2933@subheading gnutls_ext_register 2934@anchor{gnutls_ext_register} 2935@deftypefun {int} {gnutls_ext_register} (const char * @var{name}, int @var{id}, gnutls_ext_parse_type_t @var{parse_point}, gnutls_ext_recv_func @var{recv_func}, gnutls_ext_send_func @var{send_func}, gnutls_ext_deinit_data_func @var{deinit_func}, gnutls_ext_pack_func @var{pack_func}, gnutls_ext_unpack_func @var{unpack_func}) 2936@var{name}: the name of the extension to register 2937 2938@var{id}: the numeric TLS id of the extension 2939 2940@var{parse_point}: the parse type of the extension (see gnutls_ext_parse_type_t) 2941 2942@var{recv_func}: a function to receive the data 2943 2944@var{send_func}: a function to send the data 2945 2946@var{deinit_func}: a function deinitialize any private data 2947 2948@var{pack_func}: a function which serializes the extension's private data (used on session packing for resumption) 2949 2950@var{unpack_func}: a function which will deserialize the extension's private data 2951 2952This function will register a new extension type. The extension will remain 2953registered until @code{gnutls_global_deinit()} is called. If the extension type 2954is already registered then @code{GNUTLS_E_ALREADY_REGISTERED} will be returned. 2955 2956Each registered extension can store temporary data into the gnutls_session_t 2957structure using @code{gnutls_ext_set_data()} , and they can be retrieved using 2958@code{gnutls_ext_get_data()} . 2959 2960Any extensions registered with this function are valid for the client 2961and TLS1.2 server hello (or encrypted extensions for TLS1.3). 2962 2963This function is not thread safe. 2964 2965@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 2966 2967@strong{Since:} 3.4.0 2968@end deftypefun 2969 2970@subheading gnutls_ext_set_data 2971@anchor{gnutls_ext_set_data} 2972@deftypefun {void} {gnutls_ext_set_data} (gnutls_session_t @var{session}, unsigned @var{tls_id}, gnutls_ext_priv_data_t @var{data}) 2973@var{session}: a @code{gnutls_session_t} opaque pointer 2974 2975@var{tls_id}: the numeric id of the extension 2976 2977@var{data}: the private data to set 2978 2979This function allows an extension handler to store data in the current session 2980and retrieve them later on. The set data will be deallocated using 2981the gnutls_ext_deinit_data_func. 2982 2983@strong{Since:} 3.4.0 2984@end deftypefun 2985 2986@subheading gnutls_fingerprint 2987@anchor{gnutls_fingerprint} 2988@deftypefun {int} {gnutls_fingerprint} (gnutls_digest_algorithm_t @var{algo}, const gnutls_datum_t * @var{data}, void * @var{result}, size_t * @var{result_size}) 2989@var{algo}: is a digest algorithm 2990 2991@var{data}: is the data 2992 2993@var{result}: is the place where the result will be copied (may be null). 2994 2995@var{result_size}: should hold the size of the result. The actual size 2996of the returned result will also be copied there. 2997 2998This function will calculate a fingerprint (actually a hash), of 2999the given data. The result is not printable data. You should 3000convert it to hex, or to something else printable. 3001 3002This is the usual way to calculate a fingerprint of an X.509 DER 3003encoded certificate. Note however that the fingerprint of an 3004OpenPGP certificate is not just a hash and cannot be calculated with this 3005function. 3006 3007@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 3008an error code is returned. 3009@end deftypefun 3010 3011@subheading gnutls_fips140_mode_enabled 3012@anchor{gnutls_fips140_mode_enabled} 3013@deftypefun {unsigned} {gnutls_fips140_mode_enabled} ( @var{void}) 3014 3015Checks whether this library is in FIPS140 mode. The returned 3016value corresponds to the library mode as set with 3017@code{gnutls_fips140_set_mode()} . 3018 3019If @code{gnutls_fips140_set_mode()} was called with @code{GNUTLS_FIPS140_SET_MODE_THREAD} 3020then this function will return the current thread's FIPS140 mode, otherwise 3021the global value is returned. 3022 3023@strong{Returns:} return non-zero if true or zero if false. 3024 3025@strong{Since:} 3.3.0 3026@end deftypefun 3027 3028@subheading gnutls_fips140_set_mode 3029@anchor{gnutls_fips140_set_mode} 3030@deftypefun {void} {gnutls_fips140_set_mode} (gnutls_fips_mode_t @var{mode}, unsigned @var{flags}) 3031@var{mode}: the FIPS140-2 mode to switch to 3032 3033@var{flags}: should be zero or @code{GNUTLS_FIPS140_SET_MODE_THREAD} 3034 3035That function is not thread-safe when changing the mode with no flags 3036(globally), and should be called prior to creating any threads. Its 3037behavior with no flags after threads are created is undefined. 3038 3039When the flag @code{GNUTLS_FIPS140_SET_MODE_THREAD} is specified 3040then this call will change the FIPS140-2 mode for this particular 3041thread and not for the whole process. That way an application 3042can utilize this function to set and reset mode for specific 3043operations. 3044 3045This function never fails but will be a no-op if used when 3046the library is not in FIPS140-2 mode. When asked to switch to unknown 3047values for @code{mode} or to @code{GNUTLS_FIPS140_SELFTESTS} mode, the library 3048switches to @code{GNUTLS_FIPS140_STRICT} mode. 3049 3050@strong{Since:} 3.6.2 3051@end deftypefun 3052 3053@subheading gnutls_get_system_config_file 3054@anchor{gnutls_get_system_config_file} 3055@deftypefun {const char *} {gnutls_get_system_config_file} ( @var{void}) 3056 3057Returns the filename of the system wide configuration 3058file loaded by the library. The returned pointer is valid 3059until the library is unloaded. 3060 3061@strong{Returns:} a constant pointer to the config file loaded, or @code{NULL} if none 3062 3063@strong{Since:} 3.6.9 3064@end deftypefun 3065 3066@subheading gnutls_global_deinit 3067@anchor{gnutls_global_deinit} 3068@deftypefun {void} {gnutls_global_deinit} ( @var{void}) 3069 3070This function deinitializes the global data, that were initialized 3071using @code{gnutls_global_init()} . 3072 3073Since GnuTLS 3.3.0 this function is no longer necessary to be explicitly 3074called. GnuTLS will automatically deinitialize on library destructor. See 3075@code{gnutls_global_init()} for disabling the implicit initialization/deinitialization. 3076@end deftypefun 3077 3078@subheading gnutls_global_init 3079@anchor{gnutls_global_init} 3080@deftypefun {int} {gnutls_global_init} ( @var{void}) 3081 3082Since GnuTLS 3.3.0 this function is no longer necessary to be explicitly 3083called. To disable the implicit call (in a library constructor) of this 3084function set the environment variable @code{GNUTLS_NO_EXPLICIT_INIT} to 1. 3085 3086This function performs any required precalculations, detects 3087the supported CPU capabilities and initializes the underlying 3088cryptographic backend. In order to free any resources 3089taken by this call you should @code{gnutls_global_deinit()} 3090when gnutls usage is no longer needed. 3091 3092This function increments a global counter, so that 3093@code{gnutls_global_deinit()} only releases resources when it has been 3094called as many times as @code{gnutls_global_init()} . This is useful when 3095GnuTLS is used by more than one library in an application. This 3096function can be called many times, but will only do something the 3097first time. It is thread safe since GnuTLS 3.3.0. 3098 3099A subsequent call of this function if the initial has failed will 3100return the same error code. 3101 3102@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3103otherwise a negative error code is returned. 3104@end deftypefun 3105 3106@subheading gnutls_global_set_audit_log_function 3107@anchor{gnutls_global_set_audit_log_function} 3108@deftypefun {void} {gnutls_global_set_audit_log_function} (gnutls_audit_log_func @var{log_func}) 3109@var{log_func}: it is the audit log function 3110 3111This is the function to set the audit logging function. This 3112is a function to report important issues, such as possible 3113attacks in the protocol. This is different from @code{gnutls_global_set_log_function()} 3114because it will report also session-specific events. The session 3115parameter will be null if there is no corresponding TLS session. 3116 3117 @code{gnutls_audit_log_func} is of the form, 3118void (*gnutls_audit_log_func)( gnutls_session_t, const char*); 3119 3120@strong{Since:} 3.0 3121@end deftypefun 3122 3123@subheading gnutls_global_set_log_function 3124@anchor{gnutls_global_set_log_function} 3125@deftypefun {void} {gnutls_global_set_log_function} (gnutls_log_func @var{log_func}) 3126@var{log_func}: it's a log function 3127 3128This is the function where you set the logging function gnutls is 3129going to use. This function only accepts a character array. 3130Normally you may not use this function since it is only used for 3131debugging purposes. 3132 3133 @code{gnutls_log_func} is of the form, 3134void (*gnutls_log_func)( int level, const char*); 3135@end deftypefun 3136 3137@subheading gnutls_global_set_log_level 3138@anchor{gnutls_global_set_log_level} 3139@deftypefun {void} {gnutls_global_set_log_level} (int @var{level}) 3140@var{level}: it's an integer from 0 to 99. 3141 3142This is the function that allows you to set the log level. The 3143level is an integer between 0 and 9. Higher values mean more 3144verbosity. The default value is 0. Larger values should only be 3145used with care, since they may reveal sensitive information. 3146 3147Use a log level over 10 to enable all debugging options. 3148@end deftypefun 3149 3150@subheading gnutls_global_set_mutex 3151@anchor{gnutls_global_set_mutex} 3152@deftypefun {void} {gnutls_global_set_mutex} (mutex_init_func @var{init}, mutex_deinit_func @var{deinit}, mutex_lock_func @var{lock}, mutex_unlock_func @var{unlock}) 3153@var{init}: mutex initialization function 3154 3155@var{deinit}: mutex deinitialization function 3156 3157@var{lock}: mutex locking function 3158 3159@var{unlock}: mutex unlocking function 3160 3161With this function you are allowed to override the default mutex 3162locks used in some parts of gnutls and dependent libraries. This function 3163should be used if you have complete control of your program and libraries. 3164Do not call this function from a library, or preferably from any application 3165unless really needed to. GnuTLS will use the appropriate locks for the running 3166system. 3167 3168Note that since the move to implicit initialization of GnuTLS on library 3169load, calling this function will deinitialize the library, and re-initialize 3170it after the new locking functions are set. 3171 3172This function must be called prior to any other gnutls function. 3173 3174@strong{Since:} 2.12.0 3175@end deftypefun 3176 3177@subheading gnutls_global_set_time_function 3178@anchor{gnutls_global_set_time_function} 3179@deftypefun {void} {gnutls_global_set_time_function} (gnutls_time_func @var{time_func}) 3180@var{time_func}: it's the system time function, a @code{gnutls_time_func()} callback. 3181 3182This is the function where you can override the default system time 3183function. The application provided function should behave the same 3184as the standard function. 3185 3186@strong{Since:} 2.12.0 3187@end deftypefun 3188 3189@subheading gnutls_gost_paramset_get_name 3190@anchor{gnutls_gost_paramset_get_name} 3191@deftypefun {const char *} {gnutls_gost_paramset_get_name} (gnutls_gost_paramset_t @var{param}) 3192@var{param}: is a GOST 28147 param set 3193 3194Convert a @code{gnutls_gost_paramset_t} value to a string. 3195 3196@strong{Returns:} a string that contains the name of the specified GOST param set, 3197or @code{NULL} . 3198 3199@strong{Since:} 3.6.3 3200@end deftypefun 3201 3202@subheading gnutls_gost_paramset_get_oid 3203@anchor{gnutls_gost_paramset_get_oid} 3204@deftypefun {const char *} {gnutls_gost_paramset_get_oid} (gnutls_gost_paramset_t @var{param}) 3205@var{param}: is a GOST 28147 param set 3206 3207Convert a @code{gnutls_gost_paramset_t} value to its object identifier. 3208 3209@strong{Returns:} a string that contains the object identifier of the specified GOST 3210param set, or @code{NULL} . 3211 3212@strong{Since:} 3.6.3 3213@end deftypefun 3214 3215@subheading gnutls_group_get 3216@anchor{gnutls_group_get} 3217@deftypefun {gnutls_group_t} {gnutls_group_get} (gnutls_session_t @var{session}) 3218@var{session}: is a @code{gnutls_session_t} type. 3219 3220Returns the currently used group for key exchange. Only valid 3221when using an elliptic curve or DH ciphersuite. 3222 3223@strong{Returns:} the currently used group, a @code{gnutls_group_t} 3224type. 3225 3226@strong{Since:} 3.6.0 3227@end deftypefun 3228 3229@subheading gnutls_group_get_id 3230@anchor{gnutls_group_get_id} 3231@deftypefun {gnutls_group_t} {gnutls_group_get_id} (const char * @var{name}) 3232@var{name}: is a group name 3233 3234The names are compared in a case insensitive way. 3235 3236@strong{Returns:} return a @code{gnutls_group_t} value corresponding to 3237the specified group, or @code{GNUTLS_GROUP_INVALID} on error. 3238 3239@strong{Since:} 3.6.0 3240@end deftypefun 3241 3242@subheading gnutls_group_get_name 3243@anchor{gnutls_group_get_name} 3244@deftypefun {const char *} {gnutls_group_get_name} (gnutls_group_t @var{group}) 3245@var{group}: is an element from @code{gnutls_group_t} 3246 3247Convert a @code{gnutls_group_t} value to a string. 3248 3249@strong{Returns:} a string that contains the name of the specified 3250group or @code{NULL} . 3251 3252@strong{Since:} 3.6.0 3253@end deftypefun 3254 3255@subheading gnutls_group_list 3256@anchor{gnutls_group_list} 3257@deftypefun {const gnutls_group_t *} {gnutls_group_list} ( @var{void}) 3258 3259Get the list of supported elliptic curves. 3260 3261This function is not thread safe. 3262 3263@strong{Returns:} Return a (0)-terminated list of @code{gnutls_group_t} 3264integers indicating the available groups. 3265 3266@strong{Since:} 3.6.0 3267@end deftypefun 3268 3269@subheading gnutls_handshake 3270@anchor{gnutls_handshake} 3271@deftypefun {int} {gnutls_handshake} (gnutls_session_t @var{session}) 3272@var{session}: is a @code{gnutls_session_t} type. 3273 3274This function performs the handshake of the TLS/SSL protocol, and 3275initializes the TLS session parameters. 3276 3277The non-fatal errors expected by this function are: 3278@code{GNUTLS_E_INTERRUPTED} , @code{GNUTLS_E_AGAIN} , 3279@code{GNUTLS_E_WARNING_ALERT_RECEIVED} . When this function is called 3280for re-handshake under TLS 1.2 or earlier, the non-fatal error code 3281@code{GNUTLS_E_GOT_APPLICATION_DATA} may also be returned. 3282 3283The former two interrupt the handshake procedure due to the transport 3284layer being interrupted, and the latter because of a "warning" alert that 3285was sent by the peer (it is always a good idea to check any 3286received alerts). On these non-fatal errors call this function again, 3287until it returns 0; cf. @code{gnutls_record_get_direction()} and 3288@code{gnutls_error_is_fatal()} . In DTLS sessions the non-fatal error 3289@code{GNUTLS_E_LARGE_PACKET} is also possible, and indicates that 3290the MTU should be adjusted. 3291 3292When this function is called by a server after a rehandshake request 3293under TLS 1.2 or earlier the @code{GNUTLS_E_GOT_APPLICATION_DATA} error code indicates 3294that some data were pending prior to peer initiating the handshake. 3295Under TLS 1.3 this function when called after a successful handshake, is a no-op 3296and always succeeds in server side; in client side this function is 3297equivalent to @code{gnutls_session_key_update()} with @code{GNUTLS_KU_PEER} flag. 3298 3299This function handles both full and abbreviated TLS handshakes (resumption). 3300For abbreviated handshakes, in client side, the @code{gnutls_session_set_data()} 3301should be called prior to this function to set parameters from a previous session. 3302In server side, resumption is handled by either setting a DB back-end, or setting 3303up keys for session tickets. 3304 3305@strong{Returns:} @code{GNUTLS_E_SUCCESS} on a successful handshake, otherwise a negative error code. 3306@end deftypefun 3307 3308@subheading gnutls_handshake_description_get_name 3309@anchor{gnutls_handshake_description_get_name} 3310@deftypefun {const char *} {gnutls_handshake_description_get_name} (gnutls_handshake_description_t @var{type}) 3311@var{type}: is a handshake message description 3312 3313Convert a @code{gnutls_handshake_description_t} value to a string. 3314 3315@strong{Returns:} a string that contains the name of the specified handshake 3316message or @code{NULL} . 3317@end deftypefun 3318 3319@subheading gnutls_handshake_get_last_in 3320@anchor{gnutls_handshake_get_last_in} 3321@deftypefun {gnutls_handshake_description_t} {gnutls_handshake_get_last_in} (gnutls_session_t @var{session}) 3322@var{session}: is a @code{gnutls_session_t} type. 3323 3324This function is only useful to check where the last performed 3325handshake failed. If the previous handshake succeed or was not 3326performed at all then no meaningful value will be returned. 3327 3328Check @code{gnutls_handshake_description_t} in gnutls.h for the 3329available handshake descriptions. 3330 3331@strong{Returns:} the last handshake message type received, a 3332@code{gnutls_handshake_description_t} . 3333@end deftypefun 3334 3335@subheading gnutls_handshake_get_last_out 3336@anchor{gnutls_handshake_get_last_out} 3337@deftypefun {gnutls_handshake_description_t} {gnutls_handshake_get_last_out} (gnutls_session_t @var{session}) 3338@var{session}: is a @code{gnutls_session_t} type. 3339 3340This function is only useful to check where the last performed 3341handshake failed. If the previous handshake succeed or was not 3342performed at all then no meaningful value will be returned. 3343 3344Check @code{gnutls_handshake_description_t} in gnutls.h for the 3345available handshake descriptions. 3346 3347@strong{Returns:} the last handshake message type sent, a 3348@code{gnutls_handshake_description_t} . 3349@end deftypefun 3350 3351@subheading gnutls_handshake_set_hook_function 3352@anchor{gnutls_handshake_set_hook_function} 3353@deftypefun {void} {gnutls_handshake_set_hook_function} (gnutls_session_t @var{session}, unsigned int @var{htype}, int @var{when}, gnutls_handshake_hook_func @var{func}) 3354@var{session}: is a @code{gnutls_session_t} type 3355 3356@var{htype}: the @code{gnutls_handshake_description_t} of the message to hook at 3357 3358@var{when}: @code{GNUTLS_HOOK_} * depending on when the hook function should be called 3359 3360@var{func}: is the function to be called 3361 3362This function will set a callback to be called after or before the specified 3363handshake message has been received or generated. This is a 3364generalization of @code{gnutls_handshake_set_post_client_hello_function()} . 3365 3366To call the hook function prior to the message being generated or processed 3367use @code{GNUTLS_HOOK_PRE} as @code{when} parameter, @code{GNUTLS_HOOK_POST} to call 3368after, and @code{GNUTLS_HOOK_BOTH} for both cases. 3369 3370This callback must return 0 on success or a gnutls error code to 3371terminate the handshake. 3372 3373To hook at all handshake messages use an @code{htype} of @code{GNUTLS_HANDSHAKE_ANY} . 3374 3375@strong{Warning:} You should not use this function to terminate the 3376handshake based on client input unless you know what you are 3377doing. Before the handshake is finished there is no way to know if 3378there is a man-in-the-middle attack being performed. 3379@end deftypefun 3380 3381@subheading gnutls_handshake_set_max_packet_length 3382@anchor{gnutls_handshake_set_max_packet_length} 3383@deftypefun {void} {gnutls_handshake_set_max_packet_length} (gnutls_session_t @var{session}, size_t @var{max}) 3384@var{session}: is a @code{gnutls_session_t} type. 3385 3386@var{max}: is the maximum number. 3387 3388This function will set the maximum size of all handshake messages. 3389Handshakes over this size are rejected with 3390@code{GNUTLS_E_HANDSHAKE_TOO_LARGE} error code. The default value is 3391128kb which is typically large enough. Set this to 0 if you do not 3392want to set an upper limit. 3393 3394The reason for restricting the handshake message sizes are to 3395limit Denial of Service attacks. 3396 3397Note that the maximum handshake size was increased to 128kb 3398from 48kb in GnuTLS 3.5.5. 3399@end deftypefun 3400 3401@subheading gnutls_handshake_set_post_client_hello_function 3402@anchor{gnutls_handshake_set_post_client_hello_function} 3403@deftypefun {void} {gnutls_handshake_set_post_client_hello_function} (gnutls_session_t @var{session}, gnutls_handshake_simple_hook_func @var{func}) 3404@var{session}: is a @code{gnutls_session_t} type. 3405 3406@var{func}: is the function to be called 3407 3408This function will set a callback to be called after the client 3409hello has been received (callback valid in server side only). This 3410allows the server to adjust settings based on received extensions. 3411 3412Those settings could be ciphersuites, requesting certificate, or 3413anything else except for version negotiation (this is done before 3414the hello message is parsed). 3415 3416This callback must return 0 on success or a gnutls error code to 3417terminate the handshake. 3418 3419Since GnuTLS 3.3.5 the callback is 3420allowed to return @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} to 3421put the handshake on hold. In that case @code{gnutls_handshake()} 3422will return @code{GNUTLS_E_INTERRUPTED} and can be resumed when needed. 3423 3424@strong{Warning:} You should not use this function to terminate the 3425handshake based on client input unless you know what you are 3426doing. Before the handshake is finished there is no way to know if 3427there is a man-in-the-middle attack being performed. 3428@end deftypefun 3429 3430@subheading gnutls_handshake_set_private_extensions 3431@anchor{gnutls_handshake_set_private_extensions} 3432@deftypefun {void} {gnutls_handshake_set_private_extensions} (gnutls_session_t @var{session}, int @var{allow}) 3433@var{session}: is a @code{gnutls_session_t} type. 3434 3435@var{allow}: is an integer (0 or 1) 3436 3437This function will enable or disable the use of private cipher 3438suites (the ones that start with 0xFF). By default or if @code{allow} is 0 then these cipher suites will not be advertised nor used. 3439 3440Currently GnuTLS does not include such cipher-suites or 3441compression algorithms. 3442 3443Enabling the private ciphersuites when talking to other than 3444gnutls servers and clients may cause interoperability problems. 3445@end deftypefun 3446 3447@subheading gnutls_handshake_set_random 3448@anchor{gnutls_handshake_set_random} 3449@deftypefun {int} {gnutls_handshake_set_random} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{random}) 3450@var{session}: is a @code{gnutls_session_t} type. 3451 3452@var{random}: a random value of 32-bytes 3453 3454This function will explicitly set the server or client hello 3455random value in the subsequent TLS handshake. The random value 3456should be a 32-byte value. 3457 3458Note that this function should not normally be used as gnutls 3459will select automatically a random value for the handshake. 3460 3461This function should not be used when resuming a session. 3462 3463@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 3464 3465Since 3.1.9 3466@end deftypefun 3467 3468@subheading gnutls_handshake_set_timeout 3469@anchor{gnutls_handshake_set_timeout} 3470@deftypefun {void} {gnutls_handshake_set_timeout} (gnutls_session_t @var{session}, unsigned int @var{ms}) 3471@var{session}: is a @code{gnutls_session_t} type. 3472 3473@var{ms}: is a timeout value in milliseconds 3474 3475This function sets the timeout for the TLS handshake process 3476to the provided value. Use an @code{ms} value of zero to disable 3477timeout, or @code{GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT} for a reasonable 3478default value. For the DTLS protocol, the more detailed 3479@code{gnutls_dtls_set_timeouts()} is provided. 3480 3481This function requires to set a pull timeout callback. See 3482@code{gnutls_transport_set_pull_timeout_function()} . 3483 3484@strong{Since:} 3.1.0 3485@end deftypefun 3486 3487@subheading gnutls_heartbeat_allowed 3488@anchor{gnutls_heartbeat_allowed} 3489@deftypefun {unsigned} {gnutls_heartbeat_allowed} (gnutls_session_t @var{session}, unsigned int @var{type}) 3490@var{session}: is a @code{gnutls_session_t} type. 3491 3492@var{type}: one of @code{GNUTLS_HB_LOCAL_ALLOWED_TO_SEND} and @code{GNUTLS_HB_PEER_ALLOWED_TO_SEND} 3493 3494This function will check whether heartbeats are allowed 3495to be sent or received in this session. 3496 3497@strong{Returns:} Non zero if heartbeats are allowed. 3498 3499@strong{Since:} 3.1.2 3500@end deftypefun 3501 3502@subheading gnutls_heartbeat_enable 3503@anchor{gnutls_heartbeat_enable} 3504@deftypefun {void} {gnutls_heartbeat_enable} (gnutls_session_t @var{session}, unsigned int @var{type}) 3505@var{session}: is a @code{gnutls_session_t} type. 3506 3507@var{type}: one of the GNUTLS_HB_* flags 3508 3509If this function is called with the @code{GNUTLS_HB_PEER_ALLOWED_TO_SEND} 3510 @code{type} , GnuTLS will allow heartbeat messages to be received. Moreover it also 3511request the peer to accept heartbeat messages. This function 3512must be called prior to TLS handshake. 3513 3514If the @code{type} used is @code{GNUTLS_HB_LOCAL_ALLOWED_TO_SEND} , then the peer 3515will be asked to accept heartbeat messages but not send ones. 3516 3517The function @code{gnutls_heartbeat_allowed()} can be used to test Whether 3518locally generated heartbeat messages can be accepted by the peer. 3519 3520@strong{Since:} 3.1.2 3521@end deftypefun 3522 3523@subheading gnutls_heartbeat_get_timeout 3524@anchor{gnutls_heartbeat_get_timeout} 3525@deftypefun {unsigned int} {gnutls_heartbeat_get_timeout} (gnutls_session_t @var{session}) 3526@var{session}: is a @code{gnutls_session_t} type. 3527 3528This function will return the milliseconds remaining 3529for a retransmission of the previously sent ping 3530message. This function is useful when ping is used in 3531non-blocking mode, to estimate when to call @code{gnutls_heartbeat_ping()} 3532if no packets have been received. 3533 3534@strong{Returns:} the remaining time in milliseconds. 3535 3536@strong{Since:} 3.1.2 3537@end deftypefun 3538 3539@subheading gnutls_heartbeat_ping 3540@anchor{gnutls_heartbeat_ping} 3541@deftypefun {int} {gnutls_heartbeat_ping} (gnutls_session_t @var{session}, size_t @var{data_size}, unsigned int @var{max_tries}, unsigned int @var{flags}) 3542@var{session}: is a @code{gnutls_session_t} type. 3543 3544@var{data_size}: is the length of the ping payload. 3545 3546@var{max_tries}: if flags is @code{GNUTLS_HEARTBEAT_WAIT} then this sets the number of retransmissions. Use zero for indefinite (until timeout). 3547 3548@var{flags}: if @code{GNUTLS_HEARTBEAT_WAIT} then wait for pong or timeout instead of returning immediately. 3549 3550This function sends a ping to the peer. If the @code{flags} is set 3551to @code{GNUTLS_HEARTBEAT_WAIT} then it waits for a reply from the peer. 3552 3553Note that it is highly recommended to use this function with the 3554flag @code{GNUTLS_HEARTBEAT_WAIT} , or you need to handle retransmissions 3555and timeouts manually. 3556 3557The total TLS data transmitted as part of the ping message are given by 3558the following formula: MAX(16, @code{data_size} )+@code{gnutls_record_overhead_size()} +3. 3559 3560@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3561 3562@strong{Since:} 3.1.2 3563@end deftypefun 3564 3565@subheading gnutls_heartbeat_pong 3566@anchor{gnutls_heartbeat_pong} 3567@deftypefun {int} {gnutls_heartbeat_pong} (gnutls_session_t @var{session}, unsigned int @var{flags}) 3568@var{session}: is a @code{gnutls_session_t} type. 3569 3570@var{flags}: should be zero 3571 3572This function replies to a ping by sending a pong to the peer. 3573 3574@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3575 3576@strong{Since:} 3.1.2 3577@end deftypefun 3578 3579@subheading gnutls_heartbeat_set_timeouts 3580@anchor{gnutls_heartbeat_set_timeouts} 3581@deftypefun {void} {gnutls_heartbeat_set_timeouts} (gnutls_session_t @var{session}, unsigned int @var{retrans_timeout}, unsigned int @var{total_timeout}) 3582@var{session}: is a @code{gnutls_session_t} type. 3583 3584@var{retrans_timeout}: The time at which a retransmission will occur in milliseconds 3585 3586@var{total_timeout}: The time at which the connection will be aborted, in milliseconds. 3587 3588This function will override the timeouts for the DTLS heartbeat 3589protocol. The retransmission timeout is the time after which a 3590message from the peer is not received, the previous request will 3591be retransmitted. The total timeout is the time after which the 3592handshake will be aborted with @code{GNUTLS_E_TIMEDOUT} . 3593 3594@strong{Since:} 3.1.2 3595@end deftypefun 3596 3597@subheading gnutls_hex2bin 3598@anchor{gnutls_hex2bin} 3599@deftypefun {int} {gnutls_hex2bin} (const char * @var{hex_data}, size_t @var{hex_size}, void * @var{bin_data}, size_t * @var{bin_size}) 3600@var{hex_data}: string with data in hex format 3601 3602@var{hex_size}: size of hex data 3603 3604@var{bin_data}: output array with binary data 3605 3606@var{bin_size}: when calling should hold maximum size of @code{bin_data} , 3607on return will hold actual length of @code{bin_data} . 3608 3609Convert a buffer with hex data to binary data. This function 3610unlike @code{gnutls_hex_decode()} can parse hex data with separators 3611between numbers. That is, it ignores any non-hex characters. 3612 3613@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3614 3615@strong{Since:} 2.4.0 3616@end deftypefun 3617 3618@subheading gnutls_hex_decode 3619@anchor{gnutls_hex_decode} 3620@deftypefun {int} {gnutls_hex_decode} (const gnutls_datum_t * @var{hex_data}, void * @var{result}, size_t * @var{result_size}) 3621@var{hex_data}: contain the encoded data 3622 3623@var{result}: the place where decoded data will be copied 3624 3625@var{result_size}: holds the size of the result 3626 3627This function will decode the given encoded data, using the hex 3628encoding used by PSK password files. 3629 3630Initially @code{result_size} must hold the maximum size available in 3631 @code{result} , and on return it will contain the number of bytes written. 3632 3633@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not 3634long enough, @code{GNUTLS_E_PARSING_ERROR} on invalid hex data, or 0 on success. 3635@end deftypefun 3636 3637@subheading gnutls_hex_decode2 3638@anchor{gnutls_hex_decode2} 3639@deftypefun {int} {gnutls_hex_decode2} (const gnutls_datum_t * @var{hex_data}, gnutls_datum_t * @var{result}) 3640@var{hex_data}: contain the encoded data 3641 3642@var{result}: the result in an allocated string 3643 3644This function will decode the given encoded data, using the hex 3645encoding used by PSK password files. 3646 3647@strong{Returns:} @code{GNUTLS_E_PARSING_ERROR} on invalid hex data, or 0 on success. 3648@end deftypefun 3649 3650@subheading gnutls_hex_encode 3651@anchor{gnutls_hex_encode} 3652@deftypefun {int} {gnutls_hex_encode} (const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) 3653@var{data}: contain the raw data 3654 3655@var{result}: the place where hex data will be copied 3656 3657@var{result_size}: holds the size of the result 3658 3659This function will convert the given data to printable data, using 3660the hex encoding, as used in the PSK password files. 3661 3662Note that the size of the result includes the null terminator. 3663 3664@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not 3665long enough, or 0 on success. 3666@end deftypefun 3667 3668@subheading gnutls_hex_encode2 3669@anchor{gnutls_hex_encode2} 3670@deftypefun {int} {gnutls_hex_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) 3671@var{data}: contain the raw data 3672 3673@var{result}: the result in an allocated string 3674 3675This function will convert the given data to printable data, using 3676the hex encoding, as used in the PSK password files. 3677 3678Note that the size of the result does NOT include the null terminator. 3679 3680@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3681@end deftypefun 3682 3683@subheading gnutls_idna_map 3684@anchor{gnutls_idna_map} 3685@deftypefun {int} {gnutls_idna_map} (const char * @var{input}, unsigned @var{ilen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) 3686@var{input}: contain the UTF-8 formatted domain name 3687 3688@var{ilen}: the length of the provided string 3689 3690@var{out}: the result in an null-terminated allocated string 3691 3692@var{flags}: should be zero 3693 3694This function will convert the provided UTF-8 domain name, to 3695its IDNA mapping in an allocated variable. Note that depending on the flags the used gnutls 3696library was compiled with, the output of this function may vary (i.e., 3697may be IDNA2008, or IDNA2003). 3698 3699To force IDNA2008 specify the flag @code{GNUTLS_IDNA_FORCE_2008} . In 3700the case GnuTLS is not compiled with the necessary dependencies, 3701@code{GNUTLS_E_UNIMPLEMENTED_FEATURE} will be returned to indicate that 3702gnutls is unable to perform the requested conversion. 3703 3704Note also, that this function will return an empty string if an 3705empty string is provided as input. 3706 3707@strong{Returns:} @code{GNUTLS_E_INVALID_UTF8_STRING} on invalid UTF-8 data, or 0 on success. 3708 3709@strong{Since:} 3.5.8 3710@end deftypefun 3711 3712@subheading gnutls_idna_reverse_map 3713@anchor{gnutls_idna_reverse_map} 3714@deftypefun {int} {gnutls_idna_reverse_map} (const char * @var{input}, unsigned @var{ilen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) 3715@var{input}: contain the ACE (IDNA) formatted domain name 3716 3717@var{ilen}: the length of the provided string 3718 3719@var{out}: the result in an null-terminated allocated UTF-8 string 3720 3721@var{flags}: should be zero 3722 3723This function will convert an ACE (ASCII-encoded) domain name to a UTF-8 domain name. 3724 3725If GnuTLS is compiled without IDNA support, then this function 3726will return @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . 3727 3728Note also, that this function will return an empty string if an 3729empty string is provided as input. 3730 3731@strong{Returns:} A negative error code on error, or 0 on success. 3732 3733@strong{Since:} 3.5.8 3734@end deftypefun 3735 3736@subheading gnutls_init 3737@anchor{gnutls_init} 3738@deftypefun {int} {gnutls_init} (gnutls_session_t * @var{session}, unsigned int @var{flags}) 3739@var{session}: is a pointer to a @code{gnutls_session_t} type. 3740 3741@var{flags}: indicate if this session is to be used for server or client. 3742 3743This function initializes the provided session. Every 3744session must be initialized before use, and must be deinitialized 3745after used by calling @code{gnutls_deinit()} . 3746 3747 @code{flags} can be any combination of flags from @code{gnutls_init_flags_t} . 3748 3749Note that since version 3.1.2 this function enables some common 3750TLS extensions such as session tickets and OCSP certificate status 3751request in client side by default. To prevent that use the @code{GNUTLS_NO_EXTENSIONS} 3752flag. 3753 3754@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 3755@end deftypefun 3756 3757@subheading gnutls_key_generate 3758@anchor{gnutls_key_generate} 3759@deftypefun {int} {gnutls_key_generate} (gnutls_datum_t * @var{key}, unsigned int @var{key_size}) 3760@var{key}: is a pointer to a @code{gnutls_datum_t} which will contain a newly 3761created key 3762 3763@var{key_size}: the number of bytes of the key 3764 3765Generates a random key of @code{key_size} bytes. 3766 3767@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 3768error code. 3769 3770@strong{Since:} 3.0 3771@end deftypefun 3772 3773@subheading gnutls_kx_get 3774@anchor{gnutls_kx_get} 3775@deftypefun {gnutls_kx_algorithm_t} {gnutls_kx_get} (gnutls_session_t @var{session}) 3776@var{session}: is a @code{gnutls_session_t} type. 3777 3778Get the currently used key exchange algorithm. 3779 3780This function will return @code{GNUTLS_KX_ECDHE_RSA} , or @code{GNUTLS_KX_DHE_RSA} 3781under TLS 1.3, to indicate an elliptic curve DH key exchange or 3782a finite field one. The precise group used is available 3783by calling @code{gnutls_group_get()} instead. 3784 3785@strong{Returns:} the key exchange algorithm used in the last handshake, a 3786@code{gnutls_kx_algorithm_t} value. 3787@end deftypefun 3788 3789@subheading gnutls_kx_get_id 3790@anchor{gnutls_kx_get_id} 3791@deftypefun {gnutls_kx_algorithm_t} {gnutls_kx_get_id} (const char * @var{name}) 3792@var{name}: is a KX name 3793 3794Convert a string to a @code{gnutls_kx_algorithm_t} value. The names are 3795compared in a case insensitive way. 3796 3797@strong{Returns:} an id of the specified KX algorithm, or @code{GNUTLS_KX_UNKNOWN} 3798on error. 3799@end deftypefun 3800 3801@subheading gnutls_kx_get_name 3802@anchor{gnutls_kx_get_name} 3803@deftypefun {const char *} {gnutls_kx_get_name} (gnutls_kx_algorithm_t @var{algorithm}) 3804@var{algorithm}: is a key exchange algorithm 3805 3806Convert a @code{gnutls_kx_algorithm_t} value to a string. 3807 3808@strong{Returns:} a pointer to a string that contains the name of the 3809specified key exchange algorithm, or @code{NULL} . 3810@end deftypefun 3811 3812@subheading gnutls_kx_list 3813@anchor{gnutls_kx_list} 3814@deftypefun {const gnutls_kx_algorithm_t *} {gnutls_kx_list} ( @var{void}) 3815 3816Get a list of supported key exchange algorithms. 3817 3818This function is not thread safe. 3819 3820@strong{Returns:} a (0)-terminated list of @code{gnutls_kx_algorithm_t} integers 3821indicating the available key exchange algorithms. 3822@end deftypefun 3823 3824@subheading gnutls_load_file 3825@anchor{gnutls_load_file} 3826@deftypefun {int} {gnutls_load_file} (const char * @var{filename}, gnutls_datum_t * @var{data}) 3827@var{filename}: the name of the file to load 3828 3829@var{data}: Where the file will be stored 3830 3831This function will load a file into a datum. The data are 3832zero terminated but the terminating null is not included in length. 3833The returned data are allocated using @code{gnutls_malloc()} . 3834 3835Note that this function is not designed for reading sensitive materials, 3836such as private keys, on practical applications. When the reading fails 3837in the middle, the partially loaded content might remain on memory. 3838 3839@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 3840an error code is returned. 3841 3842Since 3.1.0 3843@end deftypefun 3844 3845@subheading gnutls_mac_get 3846@anchor{gnutls_mac_get} 3847@deftypefun {gnutls_mac_algorithm_t} {gnutls_mac_get} (gnutls_session_t @var{session}) 3848@var{session}: is a @code{gnutls_session_t} type. 3849 3850Get the currently used MAC algorithm. 3851 3852@strong{Returns:} the currently used mac algorithm, a 3853@code{gnutls_mac_algorithm_t} value. 3854@end deftypefun 3855 3856@subheading gnutls_mac_get_id 3857@anchor{gnutls_mac_get_id} 3858@deftypefun {gnutls_mac_algorithm_t} {gnutls_mac_get_id} (const char * @var{name}) 3859@var{name}: is a MAC algorithm name 3860 3861Convert a string to a @code{gnutls_mac_algorithm_t} value. The names are 3862compared in a case insensitive way. 3863 3864@strong{Returns:} a @code{gnutls_mac_algorithm_t} id of the specified MAC 3865algorithm string, or @code{GNUTLS_MAC_UNKNOWN} on failure. 3866@end deftypefun 3867 3868@subheading gnutls_mac_get_key_size 3869@anchor{gnutls_mac_get_key_size} 3870@deftypefun {size_t} {gnutls_mac_get_key_size} (gnutls_mac_algorithm_t @var{algorithm}) 3871@var{algorithm}: is an encryption algorithm 3872 3873Returns the size of the MAC key used in TLS. 3874 3875@strong{Returns:} length (in bytes) of the given MAC key size, or 0 if the 3876given MAC algorithm is invalid. 3877@end deftypefun 3878 3879@subheading gnutls_mac_get_name 3880@anchor{gnutls_mac_get_name} 3881@deftypefun {const char *} {gnutls_mac_get_name} (gnutls_mac_algorithm_t @var{algorithm}) 3882@var{algorithm}: is a MAC algorithm 3883 3884Convert a @code{gnutls_mac_algorithm_t} value to a string. 3885 3886@strong{Returns:} a string that contains the name of the specified MAC 3887algorithm, or @code{NULL} . 3888@end deftypefun 3889 3890@subheading gnutls_mac_list 3891@anchor{gnutls_mac_list} 3892@deftypefun {const gnutls_mac_algorithm_t *} {gnutls_mac_list} ( @var{void}) 3893 3894Get a list of hash algorithms for use as MACs. Note that not 3895necessarily all MACs are supported in TLS cipher suites. 3896This function is not thread safe. 3897 3898@strong{Returns:} Return a (0)-terminated list of @code{gnutls_mac_algorithm_t} 3899integers indicating the available MACs. 3900@end deftypefun 3901 3902@subheading gnutls_memcmp 3903@anchor{gnutls_memcmp} 3904@deftypefun {int} {gnutls_memcmp} (const void * @var{s1}, const void * @var{s2}, size_t @var{n}) 3905@var{s1}: the first address to compare 3906 3907@var{s2}: the second address to compare 3908 3909@var{n}: the size of memory to compare 3910 3911This function will operate similarly to @code{memcmp()} , but will operate 3912on time that depends only on the size of the string. That is will 3913not return early if the strings don't match on the first byte. 3914 3915@strong{Returns:} non zero on difference and zero if the buffers are identical. 3916 3917@strong{Since:} 3.4.0 3918@end deftypefun 3919 3920@subheading gnutls_memset 3921@anchor{gnutls_memset} 3922@deftypefun {void} {gnutls_memset} (void * @var{data}, int @var{c}, size_t @var{size}) 3923@var{data}: the memory to set 3924 3925@var{c}: the constant byte to fill the memory with 3926 3927@var{size}: the size of memory 3928 3929This function will operate similarly to @code{memset()} , but will 3930not be optimized out by the compiler. 3931 3932@strong{Since:} 3.4.0 3933@end deftypefun 3934 3935@subheading gnutls_ocsp_status_request_enable_client 3936@anchor{gnutls_ocsp_status_request_enable_client} 3937@deftypefun {int} {gnutls_ocsp_status_request_enable_client} (gnutls_session_t @var{session}, gnutls_datum_t * @var{responder_id}, size_t @var{responder_id_size}, gnutls_datum_t * @var{extensions}) 3938@var{session}: is a @code{gnutls_session_t} type. 3939 3940@var{responder_id}: ignored, must be @code{NULL} 3941 3942@var{responder_id_size}: ignored, must be zero 3943 3944@var{extensions}: ignored, must be @code{NULL} 3945 3946This function is to be used by clients to request OCSP response 3947from the server, using the "status_request" TLS extension. Only 3948OCSP status type is supported. 3949 3950Previous versions of GnuTLS supported setting @code{responder_id} and 3951 @code{extensions} fields, but due to the difficult semantics of the 3952parameter usage, and other issues, this support was removed 3953since 3.6.0 and these parameters must be set to @code{NULL} . 3954 3955@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3956otherwise a negative error code is returned. 3957 3958@strong{Since:} 3.1.3 3959@end deftypefun 3960 3961@subheading gnutls_ocsp_status_request_get 3962@anchor{gnutls_ocsp_status_request_get} 3963@deftypefun {int} {gnutls_ocsp_status_request_get} (gnutls_session_t @var{session}, gnutls_datum_t * @var{response}) 3964@var{session}: is a @code{gnutls_session_t} type. 3965 3966@var{response}: a @code{gnutls_datum_t} with DER encoded OCSP response 3967 3968This function returns the OCSP status response received 3969from the TLS server. The @code{response} should be treated as 3970constant. If no OCSP response is available then 3971@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 3972 3973@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3974otherwise a negative error code is returned. 3975 3976@strong{Since:} 3.1.3 3977@end deftypefun 3978 3979@subheading gnutls_ocsp_status_request_get2 3980@anchor{gnutls_ocsp_status_request_get2} 3981@deftypefun {int} {gnutls_ocsp_status_request_get2} (gnutls_session_t @var{session}, unsigned @var{idx}, gnutls_datum_t * @var{response}) 3982@var{session}: is a @code{gnutls_session_t} type. 3983 3984@var{idx}: the index of peer's certificate 3985 3986@var{response}: a @code{gnutls_datum_t} with DER encoded OCSP response 3987 3988This function returns the OCSP status response received 3989from the TLS server for the certificate index provided. 3990The index corresponds to certificates as returned by 3991gnutls_certificate_get_peers. When index is zero this 3992function operates identically to @code{gnutls_ocsp_status_request_get()} . 3993 3994The returned @code{response} should be treated as 3995constant. If no OCSP response is available for the 3996given index then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3997is returned. 3998 3999@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 4000otherwise a negative error code is returned. 4001 4002@strong{Since:} 3.6.3 4003@end deftypefun 4004 4005@subheading gnutls_ocsp_status_request_is_checked 4006@anchor{gnutls_ocsp_status_request_is_checked} 4007@deftypefun {unsigned} {gnutls_ocsp_status_request_is_checked} (gnutls_session_t @var{session}, unsigned int @var{flags}) 4008@var{session}: is a gnutls session 4009 4010@var{flags}: should be zero or @code{GNUTLS_OCSP_SR_IS_AVAIL} 4011 4012When flags are zero this function returns non-zero if a valid OCSP status 4013response was included in the TLS handshake. That is, an OCSP status response 4014which is not too old, superseded or marks the certificate as revoked. 4015It returns zero otherwise. 4016 4017When the flag @code{GNUTLS_OCSP_SR_IS_AVAIL} is specified, the function 4018returns non-zero if an OCSP status response was included in the handshake 4019even if it was invalid. Otherwise, if no OCSP status response was included, 4020it returns zero. The @code{GNUTLS_OCSP_SR_IS_AVAIL} flag was introduced in GnuTLS 3.4.0. 4021 4022This is a helper function when needing to decide whether to perform an 4023explicit OCSP validity check on the peer's certificate. Should be called after 4024any of gnutls_certificate_verify_peers*() are called. 4025 4026This function is always usable on client side, but on server side only 4027under TLS 1.3, which is the first version of TLS that allows cliend-side OCSP 4028responses. 4029 4030@strong{Returns:} Non-zero if the response was valid, or a zero if it wasn't sent, 4031or sent and was invalid. 4032 4033@strong{Since:} 3.1.4 4034@end deftypefun 4035 4036@subheading gnutls_oid_to_digest 4037@anchor{gnutls_oid_to_digest} 4038@deftypefun {gnutls_digest_algorithm_t} {gnutls_oid_to_digest} (const char * @var{oid}) 4039@var{oid}: is an object identifier 4040 4041Converts a textual object identifier to a @code{gnutls_digest_algorithm_t} value. 4042 4043@strong{Returns:} a @code{gnutls_digest_algorithm_t} id of the specified digest 4044algorithm, or @code{GNUTLS_DIG_UNKNOWN} on failure. 4045 4046@strong{Since:} 3.4.3 4047@end deftypefun 4048 4049@subheading gnutls_oid_to_ecc_curve 4050@anchor{gnutls_oid_to_ecc_curve} 4051@deftypefun {gnutls_ecc_curve_t} {gnutls_oid_to_ecc_curve} (const char * @var{oid}) 4052@var{oid}: is a curve's OID 4053 4054 4055@strong{Returns:} return a @code{gnutls_ecc_curve_t} value corresponding to 4056the specified OID, or @code{GNUTLS_ECC_CURVE_INVALID} on error. 4057 4058@strong{Since:} 3.4.3 4059@end deftypefun 4060 4061@subheading gnutls_oid_to_gost_paramset 4062@anchor{gnutls_oid_to_gost_paramset} 4063@deftypefun {gnutls_gost_paramset_t} {gnutls_oid_to_gost_paramset} (const char * @var{oid}) 4064@var{oid}: is an object identifier 4065 4066Converts a textual object identifier to a @code{gnutls_gost_paramset_t} value. 4067 4068@strong{Returns:} a @code{gnutls_gost_paramset_get_oid} of the specified GOST 28147 4069param st, or @code{GNUTLS_GOST_PARAMSET_UNKNOWN} on failure. 4070 4071@strong{Since:} 3.6.3 4072@end deftypefun 4073 4074@subheading gnutls_oid_to_mac 4075@anchor{gnutls_oid_to_mac} 4076@deftypefun {gnutls_mac_algorithm_t} {gnutls_oid_to_mac} (const char * @var{oid}) 4077@var{oid}: is an object identifier 4078 4079Converts a textual object identifier typically from PKCS@code{5} values to a @code{gnutls_mac_algorithm_t} value. 4080 4081@strong{Returns:} a @code{gnutls_mac_algorithm_t} id of the specified digest 4082algorithm, or @code{GNUTLS_MAC_UNKNOWN} on failure. 4083 4084@strong{Since:} 3.5.4 4085@end deftypefun 4086 4087@subheading gnutls_oid_to_pk 4088@anchor{gnutls_oid_to_pk} 4089@deftypefun {gnutls_pk_algorithm_t} {gnutls_oid_to_pk} (const char * @var{oid}) 4090@var{oid}: is an object identifier 4091 4092Converts a textual object identifier to a @code{gnutls_pk_algorithm_t} value. 4093 4094@strong{Returns:} a @code{gnutls_pk_algorithm_t} id of the specified digest 4095algorithm, or @code{GNUTLS_PK_UNKNOWN} on failure. 4096 4097@strong{Since:} 3.4.3 4098@end deftypefun 4099 4100@subheading gnutls_oid_to_sign 4101@anchor{gnutls_oid_to_sign} 4102@deftypefun {gnutls_sign_algorithm_t} {gnutls_oid_to_sign} (const char * @var{oid}) 4103@var{oid}: is an object identifier 4104 4105Converts a textual object identifier to a @code{gnutls_sign_algorithm_t} value. 4106 4107@strong{Returns:} a @code{gnutls_sign_algorithm_t} id of the specified digest 4108algorithm, or @code{GNUTLS_SIGN_UNKNOWN} on failure. 4109 4110@strong{Since:} 3.4.3 4111@end deftypefun 4112 4113@subheading gnutls_openpgp_send_cert 4114@anchor{gnutls_openpgp_send_cert} 4115@deftypefun {void} {gnutls_openpgp_send_cert} (gnutls_session_t @var{session}, gnutls_openpgp_crt_status_t @var{status}) 4116@var{session}: is a gnutls session 4117 4118@var{status}: is ignored 4119 4120This function is no-op. 4121 4122@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . 4123@end deftypefun 4124 4125@subheading gnutls_packet_deinit 4126@anchor{gnutls_packet_deinit} 4127@deftypefun {void} {gnutls_packet_deinit} (gnutls_packet_t @var{packet}) 4128@var{packet}: is a pointer to a @code{gnutls_packet_st} structure. 4129 4130This function will deinitialize all data associated with 4131the received packet. 4132 4133@strong{Since:} 3.3.5 4134@end deftypefun 4135 4136@subheading gnutls_packet_get 4137@anchor{gnutls_packet_get} 4138@deftypefun {void} {gnutls_packet_get} (gnutls_packet_t @var{packet}, gnutls_datum_t * @var{data}, unsigned char * @var{sequence}) 4139@var{packet}: is a @code{gnutls_packet_t} type. 4140 4141@var{data}: will contain the data present in the @code{packet} structure (may be @code{NULL} ) 4142 4143@var{sequence}: the 8-bytes of the packet sequence number (may be @code{NULL} ) 4144 4145This function returns the data and sequence number associated with 4146the received packet. 4147 4148@strong{Since:} 3.3.5 4149@end deftypefun 4150 4151@subheading gnutls_pem_base64_decode 4152@anchor{gnutls_pem_base64_decode} 4153@deftypefun {int} {gnutls_pem_base64_decode} (const char * @var{header}, const gnutls_datum_t * @var{b64_data}, unsigned char * @var{result}, size_t * @var{result_size}) 4154@var{header}: A null terminated string with the PEM header (eg. CERTIFICATE) 4155 4156@var{b64_data}: contain the encoded data 4157 4158@var{result}: the place where decoded data will be copied 4159 4160@var{result_size}: holds the size of the result 4161 4162This function will decode the given encoded data. If the header 4163given is non @code{NULL} this function will search for "-----BEGIN header" 4164and decode only this part. Otherwise it will decode the first PEM 4165packet found. 4166 4167@strong{Returns:} On success @code{GNUTLS_E_SUCCESS} (0) is returned, 4168@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned if the buffer given is 4169not long enough, or 0 on success. 4170@end deftypefun 4171 4172@subheading gnutls_pem_base64_decode2 4173@anchor{gnutls_pem_base64_decode2} 4174@deftypefun {int} {gnutls_pem_base64_decode2} (const char * @var{header}, const gnutls_datum_t * @var{b64_data}, gnutls_datum_t * @var{result}) 4175@var{header}: The PEM header (eg. CERTIFICATE) 4176 4177@var{b64_data}: contains the encoded data 4178 4179@var{result}: the location of decoded data 4180 4181This function will decode the given encoded data. The decoded data 4182will be allocated, and stored into result. If the header given is 4183non null this function will search for "-----BEGIN header" and 4184decode only this part. Otherwise it will decode the first PEM 4185packet found. 4186 4187You should use @code{gnutls_free()} to free the returned data. 4188 4189Note, that prior to GnuTLS 3.4.0 this function was available 4190under the name @code{gnutls_pem_base64_decode_alloc()} . There is 4191compatibility macro pointing to this function. 4192 4193@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 4194an error code is returned. 4195 4196@strong{Since:} 3.4.0 4197@end deftypefun 4198 4199@subheading gnutls_pem_base64_encode 4200@anchor{gnutls_pem_base64_encode} 4201@deftypefun {int} {gnutls_pem_base64_encode} (const char * @var{msg}, const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) 4202@var{msg}: is a message to be put in the header (may be @code{NULL} ) 4203 4204@var{data}: contain the raw data 4205 4206@var{result}: the place where base64 data will be copied 4207 4208@var{result_size}: holds the size of the result 4209 4210This function will convert the given data to printable data, using 4211the base64 encoding. This is the encoding used in PEM messages. 4212 4213The output string will be null terminated, although the output size will 4214not include the terminating null. 4215 4216@strong{Returns:} On success @code{GNUTLS_E_SUCCESS} (0) is returned, 4217@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned if the buffer given is 4218not long enough, or 0 on success. 4219@end deftypefun 4220 4221@subheading gnutls_pem_base64_encode2 4222@anchor{gnutls_pem_base64_encode2} 4223@deftypefun {int} {gnutls_pem_base64_encode2} (const char * @var{header}, const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) 4224@var{header}: is a message to be put in the encoded header (may be @code{NULL} ) 4225 4226@var{data}: contains the raw data 4227 4228@var{result}: will hold the newly allocated encoded data 4229 4230This function will convert the given data to printable data, using 4231the base64 encoding. This is the encoding used in PEM messages. 4232This function will allocate the required memory to hold the encoded 4233data. 4234 4235You should use @code{gnutls_free()} to free the returned data. 4236 4237Note, that prior to GnuTLS 3.4.0 this function was available 4238under the name @code{gnutls_pem_base64_encode_alloc()} . There is 4239compatibility macro pointing to this function. 4240 4241@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 4242an error code is returned. 4243 4244@strong{Since:} 3.4.0 4245@end deftypefun 4246 4247@subheading gnutls_perror 4248@anchor{gnutls_perror} 4249@deftypefun {void} {gnutls_perror} (int @var{error}) 4250@var{error}: is a GnuTLS error code, a negative error code 4251 4252This function is like @code{perror()} . The only difference is that it 4253accepts an error number returned by a gnutls function. 4254@end deftypefun 4255 4256@subheading gnutls_pk_algorithm_get_name 4257@anchor{gnutls_pk_algorithm_get_name} 4258@deftypefun {const char *} {gnutls_pk_algorithm_get_name} (gnutls_pk_algorithm_t @var{algorithm}) 4259@var{algorithm}: is a pk algorithm 4260 4261Convert a @code{gnutls_pk_algorithm_t} value to a string. 4262 4263@strong{Returns:} a string that contains the name of the specified public 4264key algorithm, or @code{NULL} . 4265@end deftypefun 4266 4267@subheading gnutls_pk_bits_to_sec_param 4268@anchor{gnutls_pk_bits_to_sec_param} 4269@deftypefun {gnutls_sec_param_t} {gnutls_pk_bits_to_sec_param} (gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}) 4270@var{algo}: is a public key algorithm 4271 4272@var{bits}: is the number of bits 4273 4274This is the inverse of @code{gnutls_sec_param_to_pk_bits()} . Given an algorithm 4275and the number of bits, it will return the security parameter. This is 4276a rough indication. 4277 4278@strong{Returns:} The security parameter. 4279 4280@strong{Since:} 2.12.0 4281@end deftypefun 4282 4283@subheading gnutls_pk_get_id 4284@anchor{gnutls_pk_get_id} 4285@deftypefun {gnutls_pk_algorithm_t} {gnutls_pk_get_id} (const char * @var{name}) 4286@var{name}: is a string containing a public key algorithm name. 4287 4288Convert a string to a @code{gnutls_pk_algorithm_t} value. The names are 4289compared in a case insensitive way. For example, 4290gnutls_pk_get_id("RSA") will return @code{GNUTLS_PK_RSA} . 4291 4292@strong{Returns:} a @code{gnutls_pk_algorithm_t} id of the specified public key 4293algorithm string, or @code{GNUTLS_PK_UNKNOWN} on failures. 4294 4295@strong{Since:} 2.6.0 4296@end deftypefun 4297 4298@subheading gnutls_pk_get_name 4299@anchor{gnutls_pk_get_name} 4300@deftypefun {const char *} {gnutls_pk_get_name} (gnutls_pk_algorithm_t @var{algorithm}) 4301@var{algorithm}: is a public key algorithm 4302 4303Convert a @code{gnutls_pk_algorithm_t} value to a string. 4304 4305@strong{Returns:} a pointer to a string that contains the name of the 4306specified public key algorithm, or @code{NULL} . 4307 4308@strong{Since:} 2.6.0 4309@end deftypefun 4310 4311@subheading gnutls_pk_get_oid 4312@anchor{gnutls_pk_get_oid} 4313@deftypefun {const char *} {gnutls_pk_get_oid} (gnutls_pk_algorithm_t @var{algorithm}) 4314@var{algorithm}: is a public key algorithm 4315 4316Convert a @code{gnutls_pk_algorithm_t} value to its object identifier string. 4317 4318@strong{Returns:} a pointer to a string that contains the object identifier of the 4319specified public key algorithm, or @code{NULL} . 4320 4321@strong{Since:} 3.4.3 4322@end deftypefun 4323 4324@subheading gnutls_pk_list 4325@anchor{gnutls_pk_list} 4326@deftypefun {const gnutls_pk_algorithm_t *} {gnutls_pk_list} ( @var{void}) 4327 4328Get a list of supported public key algorithms. 4329 4330This function is not thread safe. 4331 4332@strong{Returns:} a (0)-terminated list of @code{gnutls_pk_algorithm_t} integers 4333indicating the available ciphers. 4334 4335@strong{Since:} 2.6.0 4336@end deftypefun 4337 4338@subheading gnutls_pk_to_sign 4339@anchor{gnutls_pk_to_sign} 4340@deftypefun {gnutls_sign_algorithm_t} {gnutls_pk_to_sign} (gnutls_pk_algorithm_t @var{pk}, gnutls_digest_algorithm_t @var{hash}) 4341@var{pk}: is a public key algorithm 4342 4343@var{hash}: a hash algorithm 4344 4345This function maps public key and hash algorithms combinations 4346to signature algorithms. 4347 4348@strong{Returns:} return a @code{gnutls_sign_algorithm_t} value, or @code{GNUTLS_SIGN_UNKNOWN} on error. 4349@end deftypefun 4350 4351@subheading gnutls_prf 4352@anchor{gnutls_prf} 4353@deftypefun {int} {gnutls_prf} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, int @var{server_random_first}, size_t @var{extra_size}, const char * @var{extra}, size_t @var{outsize}, char * @var{out}) 4354@var{session}: is a @code{gnutls_session_t} type. 4355 4356@var{label_size}: length of the @code{label} variable. 4357 4358@var{label}: label used in PRF computation, typically a short string. 4359 4360@var{server_random_first}: non-zero if server random field should be first in seed 4361 4362@var{extra_size}: length of the @code{extra} variable. 4363 4364@var{extra}: optional extra data to seed the PRF with. 4365 4366@var{outsize}: size of pre-allocated output buffer to hold the output. 4367 4368@var{out}: pre-allocated buffer to hold the generated data. 4369 4370Applies the TLS Pseudo-Random-Function (PRF) on the master secret 4371and the provided data, seeded with the client and server random fields. 4372For the key expansion specified in RFC5705 see @code{gnutls_prf_rfc5705()} . 4373 4374The @code{label} variable usually contains a string denoting the purpose 4375for the generated data. The @code{server_random_first} indicates whether 4376the client random field or the server random field should be first 4377in the seed. Non-zero indicates that the server random field is first, 43780 that the client random field is first. 4379 4380The @code{extra} variable can be used to add more data to the seed, after 4381the random variables. It can be used to make sure the 4382generated output is strongly connected to some additional data 4383(e.g., a string used in user authentication). 4384 4385The output is placed in @code{out} , which must be pre-allocated. 4386 4387@strong{Note:} This function produces identical output with @code{gnutls_prf_rfc5705()} 4388when @code{server_random_first} is set to 0 and @code{extra} is @code{NULL} . Under TLS1.3 4389this function will only operate when these conditions are true, or otherwise 4390return @code{GNUTLS_E_INVALID_REQUEST} . 4391 4392@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 4393@end deftypefun 4394 4395@subheading gnutls_prf_early 4396@anchor{gnutls_prf_early} 4397@deftypefun {int} {gnutls_prf_early} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) 4398@var{session}: is a @code{gnutls_session_t} type. 4399 4400@var{label_size}: length of the @code{label} variable. 4401 4402@var{label}: label used in PRF computation, typically a short string. 4403 4404@var{context_size}: length of the @code{extra} variable. 4405 4406@var{context}: optional extra data to seed the PRF with. 4407 4408@var{outsize}: size of pre-allocated output buffer to hold the output. 4409 4410@var{out}: pre-allocated buffer to hold the generated data. 4411 4412This function is similar to @code{gnutls_prf_rfc5705()} , but only works in 4413TLS 1.3 or later to export early keying material. 4414 4415Note that the keying material is only available after the 4416ClientHello message is processed and before the application traffic 4417keys are established. Therefore this function shall be called in a 4418handshake hook function for @code{GNUTLS_HANDSHAKE_CLIENT_HELLO} . 4419 4420The @code{label} variable usually contains a string denoting the purpose 4421for the generated data. 4422 4423The @code{context} variable can be used to add more data to the seed, after 4424the random variables. It can be used to make sure the 4425generated output is strongly connected to some additional data 4426(e.g., a string used in user authentication). 4427 4428The output is placed in @code{out} , which must be pre-allocated. 4429 4430Note that, to provide the RFC5705 context, the @code{context} variable 4431must be non-null. 4432 4433@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 4434 4435@strong{Since:} 3.6.8 4436@end deftypefun 4437 4438@subheading gnutls_prf_hash_get 4439@anchor{gnutls_prf_hash_get} 4440@deftypefun {gnutls_digest_algorithm_t} {gnutls_prf_hash_get} (const gnutls_session_t @var{session}) 4441@var{session}: is a @code{gnutls_session_t} type. 4442 4443Get the currently used hash algorithm. In TLS 1.3, the hash 4444algorithm is used for both the key derivation function and 4445handshake message authentication code. In TLS 1.2, it matches the 4446hash algorithm used for PRF. 4447 4448@strong{Returns:} the currently used hash algorithm, a 4449@code{gnutls_digest_algorithm_t} value. 4450 4451@strong{Since:} 3.6.13 4452@end deftypefun 4453 4454@subheading gnutls_prf_raw 4455@anchor{gnutls_prf_raw} 4456@deftypefun {int} {gnutls_prf_raw} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{seed_size}, const char * @var{seed}, size_t @var{outsize}, char * @var{out}) 4457@var{session}: is a @code{gnutls_session_t} type. 4458 4459@var{label_size}: length of the @code{label} variable. 4460 4461@var{label}: label used in PRF computation, typically a short string. 4462 4463@var{seed_size}: length of the @code{seed} variable. 4464 4465@var{seed}: optional extra data to seed the PRF with. 4466 4467@var{outsize}: size of pre-allocated output buffer to hold the output. 4468 4469@var{out}: pre-allocated buffer to hold the generated data. 4470 4471Apply the TLS Pseudo-Random-Function (PRF) on the master secret 4472and the provided data. 4473 4474The @code{label} variable usually contains a string denoting the purpose 4475for the generated data. The @code{seed} usually contains data such as the 4476client and server random, perhaps together with some additional 4477data that is added to guarantee uniqueness of the output for a 4478particular purpose. 4479 4480Because the output is not guaranteed to be unique for a particular 4481session unless @code{seed} includes the client random and server random 4482fields (the PRF would output the same data on another connection 4483resumed from the first one), it is not recommended to use this 4484function directly. The @code{gnutls_prf()} function seeds the PRF with the 4485client and server random fields directly, and is recommended if you 4486want to generate pseudo random data unique for each session. 4487 4488@strong{Note:} This function will only operate under TLS versions prior to 1.3. 4489In TLS1.3 the use of PRF is replaced with HKDF and the generic 4490exporters like @code{gnutls_prf_rfc5705()} should be used instead. Under 4491TLS1.3 this function returns @code{GNUTLS_E_INVALID_REQUEST} . 4492 4493@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 4494@end deftypefun 4495 4496@subheading gnutls_prf_rfc5705 4497@anchor{gnutls_prf_rfc5705} 4498@deftypefun {int} {gnutls_prf_rfc5705} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) 4499@var{session}: is a @code{gnutls_session_t} type. 4500 4501@var{label_size}: length of the @code{label} variable. 4502 4503@var{label}: label used in PRF computation, typically a short string. 4504 4505@var{context_size}: length of the @code{extra} variable. 4506 4507@var{context}: optional extra data to seed the PRF with. 4508 4509@var{outsize}: size of pre-allocated output buffer to hold the output. 4510 4511@var{out}: pre-allocated buffer to hold the generated data. 4512 4513Exports keying material from TLS/DTLS session to an application, as 4514specified in RFC5705. 4515 4516In the TLS versions prior to 1.3, it applies the TLS 4517Pseudo-Random-Function (PRF) on the master secret and the provided 4518data, seeded with the client and server random fields. 4519 4520In TLS 1.3, it applies HKDF on the exporter master secret derived 4521from the master secret. 4522 4523The @code{label} variable usually contains a string denoting the purpose 4524for the generated data. 4525 4526The @code{context} variable can be used to add more data to the seed, after 4527the random variables. It can be used to make sure the 4528generated output is strongly connected to some additional data 4529(e.g., a string used in user authentication). 4530 4531The output is placed in @code{out} , which must be pre-allocated. 4532 4533Note that, to provide the RFC5705 context, the @code{context} variable 4534must be non-null. 4535 4536@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 4537 4538@strong{Since:} 3.4.4 4539@end deftypefun 4540 4541@subheading gnutls_priority_certificate_type_list 4542@anchor{gnutls_priority_certificate_type_list} 4543@deftypefun {int} {gnutls_priority_certificate_type_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4544@var{pcache}: is a @code{gnutls_prioritity_t} type. 4545 4546@var{list}: will point to an integer list 4547 4548Get a list of available certificate types in the priority 4549structure. 4550 4551As of version 3.6.4 this function is an alias for 4552gnutls_priority_certificate_type_list2 with the target parameter 4553set to: 4554- GNUTLS_CTYPE_SERVER, if the @code{SERVER_PRECEDENCE} option is set 4555- GNUTLS_CTYPE_CLIENT, otherwise. 4556 4557@strong{Returns:} the number of certificate types, or an error code. 4558 4559@strong{Since:} 3.0 4560@end deftypefun 4561 4562@subheading gnutls_priority_certificate_type_list2 4563@anchor{gnutls_priority_certificate_type_list2} 4564@deftypefun {int} {gnutls_priority_certificate_type_list2} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}, gnutls_ctype_target_t @var{target}) 4565@var{pcache}: is a @code{gnutls_prioritity_t} type. 4566 4567@var{list}: will point to an integer list. 4568 4569@var{target}: is a @code{gnutls_ctype_target_t} type. Valid arguments are 4570GNUTLS_CTYPE_CLIENT and GNUTLS_CTYPE_SERVER 4571 4572Get a list of available certificate types for the given target 4573in the priority structure. 4574 4575@strong{Returns:} the number of certificate types, or an error code. 4576 4577@strong{Since:} 3.6.4 4578@end deftypefun 4579 4580@subheading gnutls_priority_cipher_list 4581@anchor{gnutls_priority_cipher_list} 4582@deftypefun {int} {gnutls_priority_cipher_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4583@var{pcache}: is a @code{gnutls_prioritity_t} type. 4584 4585@var{list}: will point to an integer list 4586 4587Get a list of available ciphers in the priority 4588structure. 4589 4590@strong{Returns:} the number of items, or an error code. 4591 4592@strong{Since:} 3.2.3 4593@end deftypefun 4594 4595@subheading gnutls_priority_deinit 4596@anchor{gnutls_priority_deinit} 4597@deftypefun {void} {gnutls_priority_deinit} (gnutls_priority_t @var{priority_cache}) 4598@var{priority_cache}: is a @code{gnutls_prioritity_t} type. 4599 4600Deinitializes the priority cache. 4601@end deftypefun 4602 4603@subheading gnutls_priority_ecc_curve_list 4604@anchor{gnutls_priority_ecc_curve_list} 4605@deftypefun {int} {gnutls_priority_ecc_curve_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4606@var{pcache}: is a @code{gnutls_prioritity_t} type. 4607 4608@var{list}: will point to an integer list 4609 4610Get a list of available elliptic curves in the priority 4611structure. 4612 4613@strong{Deprecated:} This function has been replaced by 4614@code{gnutls_priority_group_list()} since 3.6.0. 4615 4616@strong{Returns:} the number of items, or an error code. 4617 4618@strong{Since:} 3.0 4619@end deftypefun 4620 4621@subheading gnutls_priority_get_cipher_suite_index 4622@anchor{gnutls_priority_get_cipher_suite_index} 4623@deftypefun {int} {gnutls_priority_get_cipher_suite_index} (gnutls_priority_t @var{pcache}, unsigned int @var{idx}, unsigned int * @var{sidx}) 4624@var{pcache}: is a @code{gnutls_prioritity_t} type. 4625 4626@var{idx}: is an index number. 4627 4628@var{sidx}: internal index of cipher suite to get information about. 4629 4630Provides the internal ciphersuite index to be used with 4631@code{gnutls_cipher_suite_info()} . The index @code{idx} provided is an 4632index kept at the priorities structure. It might be that a valid 4633priorities index does not correspond to a ciphersuite and in 4634that case @code{GNUTLS_E_UNKNOWN_CIPHER_SUITE} will be returned. 4635Once the last available index is crossed then 4636@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. 4637 4638@strong{Returns:} On success it returns @code{GNUTLS_E_SUCCESS} (0), or a negative error value otherwise. 4639 4640@strong{Since:} 3.0.9 4641@end deftypefun 4642 4643@subheading gnutls_priority_group_list 4644@anchor{gnutls_priority_group_list} 4645@deftypefun {int} {gnutls_priority_group_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4646@var{pcache}: is a @code{gnutls_prioritity_t} type. 4647 4648@var{list}: will point to an integer list 4649 4650Get a list of available groups in the priority 4651structure. 4652 4653@strong{Returns:} the number of items, or an error code. 4654 4655@strong{Since:} 3.6.0 4656@end deftypefun 4657 4658@subheading gnutls_priority_init 4659@anchor{gnutls_priority_init} 4660@deftypefun {int} {gnutls_priority_init} (gnutls_priority_t * @var{priority_cache}, const char * @var{priorities}, const char ** @var{err_pos}) 4661@var{priority_cache}: is a @code{gnutls_prioritity_t} type. 4662 4663@var{priorities}: is a string describing priorities (may be @code{NULL} ) 4664 4665@var{err_pos}: In case of an error this will have the position in the string the error occurred 4666 4667For applications that do not modify their crypto settings per release, consider 4668using @code{gnutls_priority_init2()} with @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} flag 4669instead. We suggest to use centralized crypto settings handled by the GnuTLS 4670library, and applications modifying the default settings to their needs. 4671 4672This function is identical to @code{gnutls_priority_init2()} with zero 4673flags. 4674 4675A @code{NULL} @code{priorities} string indicates the default priorities to be 4676used (this is available since GnuTLS 3.3.0). 4677 4678@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, 4679@code{GNUTLS_E_SUCCESS} on success, or an error code. 4680@end deftypefun 4681 4682@subheading gnutls_priority_init2 4683@anchor{gnutls_priority_init2} 4684@deftypefun {int} {gnutls_priority_init2} (gnutls_priority_t * @var{priority_cache}, const char * @var{priorities}, const char ** @var{err_pos}, unsigned @var{flags}) 4685@var{priority_cache}: is a @code{gnutls_prioritity_t} type. 4686 4687@var{priorities}: is a string describing priorities (may be @code{NULL} ) 4688 4689@var{err_pos}: In case of an error this will have the position in the string the error occurred 4690 4691@var{flags}: zero or @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} 4692 4693Sets priorities for the ciphers, key exchange methods, and macs. 4694The @code{priority_cache} should be deinitialized 4695using @code{gnutls_priority_deinit()} . 4696 4697The @code{priorities} option allows you to specify a colon 4698separated list of the cipher priorities to enable. 4699Some keywords are defined to provide quick access 4700to common preferences. 4701 4702When @code{flags} is set to @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} then the @code{priorities} specified will be appended to the default options. 4703 4704Unless there is a special need, use the "NORMAL" keyword to 4705apply a reasonable security level, or "NORMAL:%COMPAT" for compatibility. 4706 4707"PERFORMANCE" means all the "secure" ciphersuites are enabled, 4708limited to 128 bit ciphers and sorted by terms of speed 4709performance. 4710 4711"LEGACY" the NORMAL settings for GnuTLS 3.2.x or earlier. There is 4712no verification profile set, and the allowed DH primes are considered 4713weak today. 4714 4715"NORMAL" means all "secure" ciphersuites. The 256-bit ciphers are 4716included as a fallback only. The ciphers are sorted by security 4717margin. 4718 4719"PFS" means all "secure" ciphersuites that support perfect forward secrecy. 4720The 256-bit ciphers are included as a fallback only. 4721The ciphers are sorted by security margin. 4722 4723"SECURE128" means all "secure" ciphersuites of security level 128-bit 4724or more. 4725 4726"SECURE192" means all "secure" ciphersuites of security level 192-bit 4727or more. 4728 4729"SUITEB128" means all the NSA SuiteB ciphersuites with security level 4730of 128. 4731 4732"SUITEB192" means all the NSA SuiteB ciphersuites with security level 4733of 192. 4734 4735"NONE" means nothing is enabled. This disables everything, including protocols. 4736 4737"@@KEYWORD1,KEYWORD2,..." The system administrator imposed settings. 4738The provided keyword(s) will be expanded from a configuration-time 4739provided file - default is: /usr/local/etc/gnutls/config. 4740Any attributes that follow it, will be appended to the expanded 4741string. If multiple keywords are provided, separated by commas, 4742then the first keyword that exists in the configuration file 4743will be used. At least one of the keywords must exist, or this 4744function will return an error. Typical usage would be to specify 4745an application specified keyword first, followed by "SYSTEM" as 4746a default fallback. e.g., " @code{LIBVIRT} ,SYSTEM:!-VERS-SSL3.0" will 4747first try to find a config file entry matching "LIBVIRT", but if 4748that does not exist will use the entry for "SYSTEM". If "SYSTEM" 4749does not exist either, an error will be returned. In all cases, 4750the SSL3.0 protocol will be disabled. The system priority file 4751entries should be formatted as "KEYWORD=VALUE", e.g., 4752"SYSTEM=NORMAL:+ARCFOUR-128". 4753 4754Special keywords are "!", "-" and "+". 4755"!" or "-" appended with an algorithm will remove this algorithm. 4756"+" appended with an algorithm will add this algorithm. 4757 4758Check the GnuTLS manual section "Priority strings" for detailed 4759information. 4760 4761@strong{Examples:} 4762"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL" 4763 4764"NORMAL:+ARCFOUR-128" means normal ciphers plus ARCFOUR-128. 4765 4766"SECURE128:-VERS-SSL3.0" means that only secure ciphers are 4767and enabled, SSL3.0 is disabled. 4768 4769"NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1", 4770 4771"NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1", 4772 4773"SECURE256:+SECURE128", 4774 4775Note that "NORMAL:%COMPAT" is the most compatible mode. 4776 4777A @code{NULL} @code{priorities} string indicates the default priorities to be 4778used (this is available since GnuTLS 3.3.0). 4779 4780@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, 4781@code{GNUTLS_E_SUCCESS} on success, or an error code. 4782 4783@strong{Since:} 3.6.3 4784@end deftypefun 4785 4786@subheading gnutls_priority_kx_list 4787@anchor{gnutls_priority_kx_list} 4788@deftypefun {int} {gnutls_priority_kx_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4789@var{pcache}: is a @code{gnutls_prioritity_t} type. 4790 4791@var{list}: will point to an integer list 4792 4793Get a list of available key exchange methods in the priority 4794structure. 4795 4796@strong{Returns:} the number of items, or an error code. 4797 4798@strong{Since:} 3.2.3 4799@end deftypefun 4800 4801@subheading gnutls_priority_mac_list 4802@anchor{gnutls_priority_mac_list} 4803@deftypefun {int} {gnutls_priority_mac_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4804@var{pcache}: is a @code{gnutls_prioritity_t} type. 4805 4806@var{list}: will point to an integer list 4807 4808Get a list of available MAC algorithms in the priority 4809structure. 4810 4811@strong{Returns:} the number of items, or an error code. 4812 4813@strong{Since:} 3.2.3 4814@end deftypefun 4815 4816@subheading gnutls_priority_protocol_list 4817@anchor{gnutls_priority_protocol_list} 4818@deftypefun {int} {gnutls_priority_protocol_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4819@var{pcache}: is a @code{gnutls_prioritity_t} type. 4820 4821@var{list}: will point to an integer list 4822 4823Get a list of available TLS version numbers in the priority 4824structure. 4825 4826@strong{Returns:} the number of protocols, or an error code. 4827 4828@strong{Since:} 3.0 4829@end deftypefun 4830 4831@subheading gnutls_priority_set 4832@anchor{gnutls_priority_set} 4833@deftypefun {int} {gnutls_priority_set} (gnutls_session_t @var{session}, gnutls_priority_t @var{priority}) 4834@var{session}: is a @code{gnutls_session_t} type. 4835 4836@var{priority}: is a @code{gnutls_priority_t} type. 4837 4838Sets the priorities to use on the ciphers, key exchange methods, 4839and macs. Note that this function is expected to be called once 4840per session; when called multiple times (e.g., before a re-handshake, 4841the caller should make sure that any new settings are not incompatible 4842with the original session). 4843 4844@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code on error. 4845@end deftypefun 4846 4847@subheading gnutls_priority_set_direct 4848@anchor{gnutls_priority_set_direct} 4849@deftypefun {int} {gnutls_priority_set_direct} (gnutls_session_t @var{session}, const char * @var{priorities}, const char ** @var{err_pos}) 4850@var{session}: is a @code{gnutls_session_t} type. 4851 4852@var{priorities}: is a string describing priorities 4853 4854@var{err_pos}: In case of an error this will have the position in the string the error occurred 4855 4856Sets the priorities to use on the ciphers, key exchange methods, 4857and macs. This function avoids keeping a 4858priority cache and is used to directly set string priorities to a 4859TLS session. For documentation check the @code{gnutls_priority_init()} . 4860 4861To use a reasonable default, consider using @code{gnutls_set_default_priority()} , 4862or @code{gnutls_set_default_priority_append()} instead of this function. 4863 4864@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, 4865@code{GNUTLS_E_SUCCESS} on success, or an error code. 4866@end deftypefun 4867 4868@subheading gnutls_priority_sign_list 4869@anchor{gnutls_priority_sign_list} 4870@deftypefun {int} {gnutls_priority_sign_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) 4871@var{pcache}: is a @code{gnutls_prioritity_t} type. 4872 4873@var{list}: will point to an integer list 4874 4875Get a list of available signature algorithms in the priority 4876structure. 4877 4878@strong{Returns:} the number of algorithms, or an error code. 4879 4880@strong{Since:} 3.0 4881@end deftypefun 4882 4883@subheading gnutls_priority_string_list 4884@anchor{gnutls_priority_string_list} 4885@deftypefun {const char *} {gnutls_priority_string_list} (unsigned @var{iter}, unsigned int @var{flags}) 4886@var{iter}: an integer counter starting from zero 4887 4888@var{flags}: one of @code{GNUTLS_PRIORITY_LIST_INIT_KEYWORDS} , @code{GNUTLS_PRIORITY_LIST_SPECIAL} 4889 4890Can be used to iterate all available priority strings. 4891Due to internal implementation details, there are cases where this 4892function can return the empty string. In that case that string should be ignored. 4893When no strings are available it returns @code{NULL} . 4894 4895@strong{Returns:} a priority string 4896 4897@strong{Since:} 3.4.0 4898@end deftypefun 4899 4900@subheading gnutls_protocol_get_id 4901@anchor{gnutls_protocol_get_id} 4902@deftypefun {gnutls_protocol_t} {gnutls_protocol_get_id} (const char * @var{name}) 4903@var{name}: is a protocol name 4904 4905The names are compared in a case insensitive way. 4906 4907@strong{Returns:} an id of the specified protocol, or 4908@code{GNUTLS_VERSION_UNKNOWN} on error. 4909@end deftypefun 4910 4911@subheading gnutls_protocol_get_name 4912@anchor{gnutls_protocol_get_name} 4913@deftypefun {const char *} {gnutls_protocol_get_name} (gnutls_protocol_t @var{version}) 4914@var{version}: is a (gnutls) version number 4915 4916Convert a @code{gnutls_protocol_t} value to a string. 4917 4918@strong{Returns:} a string that contains the name of the specified TLS 4919version (e.g., "TLS1.0"), or @code{NULL} . 4920@end deftypefun 4921 4922@subheading gnutls_protocol_get_version 4923@anchor{gnutls_protocol_get_version} 4924@deftypefun {gnutls_protocol_t} {gnutls_protocol_get_version} (gnutls_session_t @var{session}) 4925@var{session}: is a @code{gnutls_session_t} type. 4926 4927Get TLS version, a @code{gnutls_protocol_t} value. 4928 4929@strong{Returns:} The version of the currently used protocol. 4930@end deftypefun 4931 4932@subheading gnutls_protocol_list 4933@anchor{gnutls_protocol_list} 4934@deftypefun {const gnutls_protocol_t *} {gnutls_protocol_list} ( @var{void}) 4935 4936Get a list of supported protocols, e.g. SSL 3.0, TLS 1.0 etc. 4937 4938This function is not thread safe. 4939 4940@strong{Returns:} a (0)-terminated list of @code{gnutls_protocol_t} integers 4941indicating the available protocols. 4942@end deftypefun 4943 4944@subheading gnutls_psk_allocate_client_credentials 4945@anchor{gnutls_psk_allocate_client_credentials} 4946@deftypefun {int} {gnutls_psk_allocate_client_credentials} (gnutls_psk_client_credentials_t * @var{sc}) 4947@var{sc}: is a pointer to a @code{gnutls_psk_server_credentials_t} type. 4948 4949Allocate a gnutls_psk_client_credentials_t structure. 4950 4951@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 4952an error code is returned. 4953@end deftypefun 4954 4955@subheading gnutls_psk_allocate_server_credentials 4956@anchor{gnutls_psk_allocate_server_credentials} 4957@deftypefun {int} {gnutls_psk_allocate_server_credentials} (gnutls_psk_server_credentials_t * @var{sc}) 4958@var{sc}: is a pointer to a @code{gnutls_psk_server_credentials_t} type. 4959 4960Allocate a gnutls_psk_server_credentials_t structure. 4961 4962@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 4963an error code is returned. 4964@end deftypefun 4965 4966@subheading gnutls_psk_client_get_hint 4967@anchor{gnutls_psk_client_get_hint} 4968@deftypefun {const char *} {gnutls_psk_client_get_hint} (gnutls_session_t @var{session}) 4969@var{session}: is a gnutls session 4970 4971The PSK identity hint may give the client help in deciding which 4972username to use. This should only be called in case of PSK 4973authentication and in case of a client. 4974 4975@strong{Note:} there is no hint in TLS 1.3, so this function will return @code{NULL} 4976if TLS 1.3 has been negotiated. 4977 4978@strong{Returns:} the identity hint of the peer, or @code{NULL} in case of an error or if TLS 1.3 is being used. 4979 4980@strong{Since:} 2.4.0 4981@end deftypefun 4982 4983@subheading gnutls_psk_free_client_credentials 4984@anchor{gnutls_psk_free_client_credentials} 4985@deftypefun {void} {gnutls_psk_free_client_credentials} (gnutls_psk_client_credentials_t @var{sc}) 4986@var{sc}: is a @code{gnutls_psk_client_credentials_t} type. 4987 4988Free a gnutls_psk_client_credentials_t structure. 4989@end deftypefun 4990 4991@subheading gnutls_psk_free_server_credentials 4992@anchor{gnutls_psk_free_server_credentials} 4993@deftypefun {void} {gnutls_psk_free_server_credentials} (gnutls_psk_server_credentials_t @var{sc}) 4994@var{sc}: is a @code{gnutls_psk_server_credentials_t} type. 4995 4996Free a gnutls_psk_server_credentials_t structure. 4997@end deftypefun 4998 4999@subheading gnutls_psk_server_get_username 5000@anchor{gnutls_psk_server_get_username} 5001@deftypefun {const char *} {gnutls_psk_server_get_username} (gnutls_session_t @var{session}) 5002@var{session}: is a gnutls session 5003 5004This should only be called in case of PSK authentication and in 5005case of a server. 5006 5007The returned pointer should be considered constant (do not free) and valid 5008for the lifetime of the session. 5009 5010This function will return @code{NULL} if the username has embedded NULL bytes. 5011In that case, @code{gnutls_psk_server_get_username2()} should be used to retrieve the username. 5012 5013@strong{Returns:} the username of the peer, or @code{NULL} in case of an error, 5014or if the username has embedded NULLs. 5015@end deftypefun 5016 5017@subheading gnutls_psk_server_get_username2 5018@anchor{gnutls_psk_server_get_username2} 5019@deftypefun {int} {gnutls_psk_server_get_username2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{username}) 5020@var{session}: is a gnutls session 5021 5022@var{username}: a datum that will be filled in by this function 5023 5024Return a pointer to the username of the peer in the supplied datum. Does not 5025need to be null-terminated. 5026 5027This should only be called in case of PSK authentication and in 5028case of a server. 5029 5030The returned pointer should be considered constant (do not free) and valid 5031for the lifetime of the session. 5032 5033@strong{Returns:} @code{GNUTLS_E_SUCCESS} , or a negative value in case of an error. 5034@end deftypefun 5035 5036@subheading gnutls_psk_set_client_credentials 5037@anchor{gnutls_psk_set_client_credentials} 5038@deftypefun {int} {gnutls_psk_set_client_credentials} (gnutls_psk_client_credentials_t @var{res}, const char * @var{username}, const gnutls_datum_t * @var{key}, gnutls_psk_key_flags @var{flags}) 5039@var{res}: is a @code{gnutls_psk_client_credentials_t} type. 5040 5041@var{username}: is the user's zero-terminated userid 5042 5043@var{key}: is the user's key 5044 5045@var{flags}: indicate the format of the key, either 5046@code{GNUTLS_PSK_KEY_RAW} or @code{GNUTLS_PSK_KEY_HEX} . 5047 5048This function sets the username and password, in a 5049gnutls_psk_client_credentials_t type. Those will be used in 5050PSK authentication. @code{username} should be an ASCII string or UTF-8 5051string. In case of a UTF-8 string it is recommended to be following 5052the PRECIS framework for usernames (rfc8265). The key can be either 5053in raw byte format or in Hex format (without the 0x prefix). 5054 5055@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 5056an error code is returned. 5057@end deftypefun 5058 5059@subheading gnutls_psk_set_client_credentials2 5060@anchor{gnutls_psk_set_client_credentials2} 5061@deftypefun {int} {gnutls_psk_set_client_credentials2} (gnutls_psk_client_credentials_t @var{res}, const gnutls_datum_t * @var{username}, const gnutls_datum_t * @var{key}, gnutls_psk_key_flags @var{flags}) 5062@var{res}: is a @code{gnutls_psk_client_credentials_t} type. 5063 5064@var{username}: is the userid 5065 5066@var{key}: is the user's key 5067 5068@var{flags}: indicate the format of the key, either 5069@code{GNUTLS_PSK_KEY_RAW} or @code{GNUTLS_PSK_KEY_HEX} . 5070 5071This function is identical to @code{gnutls_psk_set_client_credentials()} , 5072except that it allows a non-null-terminated username to be introduced. 5073 5074@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 5075an error code is returned. 5076@end deftypefun 5077 5078@subheading gnutls_psk_set_client_credentials_function 5079@anchor{gnutls_psk_set_client_credentials_function} 5080@deftypefun {void} {gnutls_psk_set_client_credentials_function} (gnutls_psk_client_credentials_t @var{cred}, gnutls_psk_client_credentials_function * @var{func}) 5081@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. 5082 5083@var{func}: is the callback function 5084 5085This function can be used to set a callback to retrieve the username and 5086password for client PSK authentication. 5087The callback's function form is: 5088int (*callback)(gnutls_session_t, char** username, 5089gnutls_datum_t* key); 5090 5091The @code{username} and @code{key} ->data must be allocated using @code{gnutls_malloc()} . 5092The @code{username} should be an ASCII string or UTF-8 5093string. In case of a UTF-8 string it is recommended to be following 5094the PRECIS framework for usernames (rfc8265). 5095 5096The callback function will be called once per handshake. 5097 5098The callback function should return 0 on success. 5099-1 indicates an error. 5100@end deftypefun 5101 5102@subheading gnutls_psk_set_client_credentials_function2 5103@anchor{gnutls_psk_set_client_credentials_function2} 5104@deftypefun {void} {gnutls_psk_set_client_credentials_function2} (gnutls_psk_client_credentials_t @var{cred}, gnutls_psk_client_credentials_function2 * @var{func}) 5105@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. 5106 5107@var{func}: is the callback function 5108 5109This function can be used to set a callback to retrieve the username and 5110password for client PSK authentication. 5111The callback's function form is: 5112int (*callback)(gnutls_session_t, gnutls_datum_t* username, 5113gnutls_datum_t* key); 5114 5115This callback function has the same semantics as that of @code{gnutls_psk_set_client_credentials_function()} , 5116but it allows non-string usernames to be used. 5117 5118The @code{username} and @code{key} ->data must be allocated using @code{gnutls_malloc()} . 5119The @code{username} should be an ASCII string or UTF-8 5120string. In case of a UTF-8 string it is recommended to be following 5121the PRECIS framework for usernames (rfc8265). 5122 5123The callback function will be called once per handshake. 5124 5125The callback function should return 0 on success. 5126-1 indicates an error. 5127@end deftypefun 5128 5129@subheading gnutls_psk_set_params_function 5130@anchor{gnutls_psk_set_params_function} 5131@deftypefun {void} {gnutls_psk_set_params_function} (gnutls_psk_server_credentials_t @var{res}, gnutls_params_function * @var{func}) 5132@var{res}: is a gnutls_psk_server_credentials_t type 5133 5134@var{func}: is the function to be called 5135 5136This function will set a callback in order for the server to get 5137the Diffie-Hellman or RSA parameters for PSK authentication. The 5138callback should return @code{GNUTLS_E_SUCCESS} (0) on success. 5139 5140@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 5141or later. Since 3.6.0, DH parameters are negotiated 5142following RFC7919. 5143@end deftypefun 5144 5145@subheading gnutls_psk_set_server_credentials_file 5146@anchor{gnutls_psk_set_server_credentials_file} 5147@deftypefun {int} {gnutls_psk_set_server_credentials_file} (gnutls_psk_server_credentials_t @var{res}, const char * @var{password_file}) 5148@var{res}: is a @code{gnutls_psk_server_credentials_t} type. 5149 5150@var{password_file}: is the PSK password file (passwd.psk) 5151 5152This function sets the password file, in a 5153@code{gnutls_psk_server_credentials_t} type. This password file 5154holds usernames and keys and will be used for PSK authentication. 5155 5156@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 5157an error code is returned. 5158@end deftypefun 5159 5160@subheading gnutls_psk_set_server_credentials_function 5161@anchor{gnutls_psk_set_server_credentials_function} 5162@deftypefun {void} {gnutls_psk_set_server_credentials_function} (gnutls_psk_server_credentials_t @var{cred}, gnutls_psk_server_credentials_function * @var{func}) 5163@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. 5164 5165@var{func}: is the callback function 5166 5167This function can be used to set a callback to retrieve the user's PSK credentials. 5168The callback's function form is: 5169int (*callback)(gnutls_session_t, const char* username, 5170gnutls_datum_t* key); 5171 5172 @code{username} contains the actual username. 5173The @code{key} must be filled in using the @code{gnutls_malloc()} . 5174 5175In case the callback returned a negative number then gnutls will 5176assume that the username does not exist. 5177 5178The callback function will only be called once per handshake. The 5179callback function should return 0 on success, while -1 indicates 5180an error. 5181@end deftypefun 5182 5183@subheading gnutls_psk_set_server_credentials_function2 5184@anchor{gnutls_psk_set_server_credentials_function2} 5185@deftypefun {void} {gnutls_psk_set_server_credentials_function2} (gnutls_psk_server_credentials_t @var{cred}, gnutls_psk_server_credentials_function2 @var{func}) 5186@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. 5187 5188@var{func}: is the callback function 5189 5190This function can be used to set a callback to retrieve the user's PSK credentials. 5191The callback's function form is: 5192int (*callback)(gnutls_session_t, const gnutls_datum_t* username, 5193gnutls_datum_t* key); 5194 5195This callback function has the same semantics as that of @code{gnutls_psk_set_server_credentials_function()} , 5196but it allows non-string usernames to be used. 5197 5198 @code{username} contains the actual username. 5199The @code{key} must be filled in using the @code{gnutls_malloc()} . 5200 5201In case the callback returned a negative number then gnutls will 5202assume that the username does not exist. 5203 5204The callback function will only be called once per handshake. The 5205callback function should return 0 on success, while -1 indicates 5206an error. 5207@end deftypefun 5208 5209@subheading gnutls_psk_set_server_credentials_hint 5210@anchor{gnutls_psk_set_server_credentials_hint} 5211@deftypefun {int} {gnutls_psk_set_server_credentials_hint} (gnutls_psk_server_credentials_t @var{res}, const char * @var{hint}) 5212@var{res}: is a @code{gnutls_psk_server_credentials_t} type. 5213 5214@var{hint}: is the PSK identity hint string 5215 5216This function sets the identity hint, in a 5217@code{gnutls_psk_server_credentials_t} type. This hint is sent to 5218the client to help it chose a good PSK credential (i.e., username 5219and password). 5220 5221@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 5222an error code is returned. 5223 5224@strong{Since:} 2.4.0 5225@end deftypefun 5226 5227@subheading gnutls_psk_set_server_dh_params 5228@anchor{gnutls_psk_set_server_dh_params} 5229@deftypefun {void} {gnutls_psk_set_server_dh_params} (gnutls_psk_server_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) 5230@var{res}: is a gnutls_psk_server_credentials_t type 5231 5232@var{dh_params}: is a structure that holds Diffie-Hellman parameters. 5233 5234This function will set the Diffie-Hellman parameters for an 5235anonymous server to use. These parameters will be used in 5236Diffie-Hellman exchange with PSK cipher suites. 5237 5238@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 5239or later. Since 3.6.0, DH parameters are negotiated 5240following RFC7919. 5241@end deftypefun 5242 5243@subheading gnutls_psk_set_server_known_dh_params 5244@anchor{gnutls_psk_set_server_known_dh_params} 5245@deftypefun {int} {gnutls_psk_set_server_known_dh_params} (gnutls_psk_server_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) 5246@var{res}: is a gnutls_psk_server_credentials_t type 5247 5248@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration 5249 5250This function will set the Diffie-Hellman parameters for a 5251PSK server to use. These parameters will be used in 5252Ephemeral Diffie-Hellman cipher suites and will be selected from 5253the FFDHE set of RFC7919 according to the security level provided. 5254 5255@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 5256or later. Since 3.6.0, DH parameters are negotiated 5257following RFC7919. 5258 5259@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5260negative error value. 5261 5262@strong{Since:} 3.5.6 5263@end deftypefun 5264 5265@subheading gnutls_psk_set_server_params_function 5266@anchor{gnutls_psk_set_server_params_function} 5267@deftypefun {void} {gnutls_psk_set_server_params_function} (gnutls_psk_server_credentials_t @var{res}, gnutls_params_function * @var{func}) 5268@var{res}: is a @code{gnutls_certificate_credentials_t} type 5269 5270@var{func}: is the function to be called 5271 5272This function will set a callback in order for the server to get 5273the Diffie-Hellman parameters for PSK authentication. The callback 5274should return @code{GNUTLS_E_SUCCESS} (0) on success. 5275 5276@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 5277or later. Since 3.6.0, DH parameters are negotiated 5278following RFC7919. 5279@end deftypefun 5280 5281@subheading gnutls_random_art 5282@anchor{gnutls_random_art} 5283@deftypefun {int} {gnutls_random_art} (gnutls_random_art_t @var{type}, const char * @var{key_type}, unsigned int @var{key_size}, void * @var{fpr}, size_t @var{fpr_size}, gnutls_datum_t * @var{art}) 5284@var{type}: The type of the random art (for now only @code{GNUTLS_RANDOM_ART_OPENSSH} is supported) 5285 5286@var{key_type}: The type of the key (RSA, DSA etc.) 5287 5288@var{key_size}: The size of the key in bits 5289 5290@var{fpr}: The fingerprint of the key 5291 5292@var{fpr_size}: The size of the fingerprint 5293 5294@var{art}: The returned random art 5295 5296This function will convert a given fingerprint to an "artistic" 5297image. The returned image is allocated using @code{gnutls_malloc()} , is 5298null-terminated but art->size will not account the terminating null. 5299 5300@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 5301an error code is returned. 5302@end deftypefun 5303 5304@subheading gnutls_range_split 5305@anchor{gnutls_range_split} 5306@deftypefun {int} {gnutls_range_split} (gnutls_session_t @var{session}, const gnutls_range_st * @var{orig}, gnutls_range_st * @var{next}, gnutls_range_st * @var{remainder}) 5307@var{session}: is a @code{gnutls_session_t} type 5308 5309@var{orig}: is the original range provided by the user 5310 5311@var{next}: is the returned range that can be conveyed in a TLS record 5312 5313@var{remainder}: is the returned remaining range 5314 5315This function should be used when it is required to hide the length 5316of very long data that cannot be directly provided to @code{gnutls_record_send_range()} . 5317In that case this function should be called with the desired length 5318hiding range in @code{orig} . The returned @code{next} value should then be used in 5319the next call to @code{gnutls_record_send_range()} with the partial data. 5320That process should be repeated until @code{remainder} is (0,0). 5321 5322@strong{Returns:} 0 in case splitting succeeds, non zero in case of error. 5323Note that @code{orig} is not changed, while the values of @code{next} and @code{remainder} are modified to store the resulting values. 5324@end deftypefun 5325 5326@subheading gnutls_reauth 5327@anchor{gnutls_reauth} 5328@deftypefun {int} {gnutls_reauth} (gnutls_session_t @var{session}, unsigned int @var{flags}) 5329@var{session}: is a @code{gnutls_session_t} type. 5330 5331@var{flags}: must be zero 5332 5333This function performs the post-handshake authentication 5334for TLS 1.3. The post-handshake authentication is initiated by the server 5335by calling this function. Clients respond when @code{GNUTLS_E_REAUTH_REQUEST} 5336has been seen while receiving data. 5337 5338The non-fatal errors expected by this function are: 5339@code{GNUTLS_E_INTERRUPTED} , @code{GNUTLS_E_AGAIN} , as well as 5340@code{GNUTLS_E_GOT_APPLICATION_DATA} when called on server side. 5341 5342The former two interrupt the authentication procedure due to the transport 5343layer being interrupted, and the latter because there were pending data prior 5344to peer initiating the re-authentication. The server should read/process that 5345data as unauthenticated and retry calling @code{gnutls_reauth()} . 5346 5347When this function is called under TLS1.2 or earlier or the peer didn't 5348advertise post-handshake auth, it always fails with 5349@code{GNUTLS_E_INVALID_REQUEST} . The verification of the received peers certificate 5350is delegated to the session or credentials verification callbacks. A 5351server can check whether post handshake authentication is supported 5352by the client by checking the session flags with @code{gnutls_session_get_flags()} . 5353 5354Prior to calling this function in server side, the function 5355@code{gnutls_certificate_server_set_request()} must be called setting expectations 5356for the received certificate (request or require). If none are set 5357this function will return with @code{GNUTLS_E_INVALID_REQUEST} . 5358 5359Note that post handshake authentication is available irrespective 5360of the initial negotiation type (PSK or certificate). In all cases 5361however, certificate credentials must be set to the session prior 5362to calling this function. 5363 5364@strong{Returns:} @code{GNUTLS_E_SUCCESS} on a successful authentication, otherwise a negative error code. 5365@end deftypefun 5366 5367@subheading gnutls_record_can_use_length_hiding 5368@anchor{gnutls_record_can_use_length_hiding} 5369@deftypefun {unsigned} {gnutls_record_can_use_length_hiding} (gnutls_session_t @var{session}) 5370@var{session}: is a @code{gnutls_session_t} type. 5371 5372If the session supports length-hiding padding, you can 5373invoke @code{gnutls_record_send_range()} to send a message whose 5374length is hidden in the given range. If the session does not 5375support length hiding padding, you can use the standard 5376@code{gnutls_record_send()} function, or @code{gnutls_record_send_range()} 5377making sure that the range is the same as the length of the 5378message you are trying to send. 5379 5380@strong{Returns:} true (1) if the current session supports length-hiding 5381padding, false (0) if the current session does not. 5382@end deftypefun 5383 5384@subheading gnutls_record_check_corked 5385@anchor{gnutls_record_check_corked} 5386@deftypefun {size_t} {gnutls_record_check_corked} (gnutls_session_t @var{session}) 5387@var{session}: is a @code{gnutls_session_t} type. 5388 5389This function checks if there pending corked 5390data in the gnutls buffers --see @code{gnutls_record_cork()} . 5391 5392@strong{Returns:} Returns the size of the corked data or zero. 5393 5394@strong{Since:} 3.2.8 5395@end deftypefun 5396 5397@subheading gnutls_record_check_pending 5398@anchor{gnutls_record_check_pending} 5399@deftypefun {size_t} {gnutls_record_check_pending} (gnutls_session_t @var{session}) 5400@var{session}: is a @code{gnutls_session_t} type. 5401 5402This function checks if there are unread data 5403in the gnutls buffers. If the return value is 5404non-zero the next call to @code{gnutls_record_recv()} 5405is guaranteed not to block. 5406 5407@strong{Returns:} Returns the size of the data or zero. 5408@end deftypefun 5409 5410@subheading gnutls_record_cork 5411@anchor{gnutls_record_cork} 5412@deftypefun {void} {gnutls_record_cork} (gnutls_session_t @var{session}) 5413@var{session}: is a @code{gnutls_session_t} type. 5414 5415If called, @code{gnutls_record_send()} will no longer send any records. 5416Any sent records will be cached until @code{gnutls_record_uncork()} is called. 5417 5418This function is safe to use with DTLS after GnuTLS 3.3.0. 5419 5420@strong{Since:} 3.1.9 5421@end deftypefun 5422 5423@subheading gnutls_record_disable_padding 5424@anchor{gnutls_record_disable_padding} 5425@deftypefun {void} {gnutls_record_disable_padding} (gnutls_session_t @var{session}) 5426@var{session}: is a @code{gnutls_session_t} type. 5427 5428Used to disabled padding in TLS 1.0 and above. Normally you do not 5429need to use this function, but there are buggy clients that 5430complain if a server pads the encrypted data. This of course will 5431disable protection against statistical attacks on the data. 5432 5433This function is defunct since 3.1.7. Random padding is disabled 5434by default unless requested using @code{gnutls_record_send_range()} . 5435@end deftypefun 5436 5437@subheading gnutls_record_discard_queued 5438@anchor{gnutls_record_discard_queued} 5439@deftypefun {size_t} {gnutls_record_discard_queued} (gnutls_session_t @var{session}) 5440@var{session}: is a @code{gnutls_session_t} type. 5441 5442This function discards all queued to be sent packets in a DTLS session. 5443These are the packets queued after an interrupted @code{gnutls_record_send()} . 5444 5445This function can only be used with transports where @code{send()} is 5446an all-or-nothing operation (e.g., UDP). When partial writes are allowed 5447this function will cause session errors. 5448 5449@strong{Returns:} The number of bytes discarded. 5450 5451@strong{Since:} 3.4.0 5452@end deftypefun 5453 5454@subheading gnutls_record_get_direction 5455@anchor{gnutls_record_get_direction} 5456@deftypefun {int} {gnutls_record_get_direction} (gnutls_session_t @var{session}) 5457@var{session}: is a @code{gnutls_session_t} type. 5458 5459This function is useful to determine whether a GnuTLS function was interrupted 5460while sending or receiving, so that @code{select()} or @code{poll()} may be called appropriately. 5461 5462It provides information about the internals of the record 5463protocol and is only useful if a prior gnutls function call, 5464e.g. @code{gnutls_handshake()} , was interrupted and returned 5465@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} . After such an interrupt 5466applications may call @code{select()} or @code{poll()} before restoring the 5467interrupted GnuTLS function. 5468 5469This function's output is unreliable if you are using the same 5470 @code{session} in different threads for sending and receiving. 5471 5472@strong{Returns:} 0 if interrupted while trying to read data, or 1 while trying to write data. 5473@end deftypefun 5474 5475@subheading gnutls_record_get_max_early_data_size 5476@anchor{gnutls_record_get_max_early_data_size} 5477@deftypefun {size_t} {gnutls_record_get_max_early_data_size} (gnutls_session_t @var{session}) 5478@var{session}: is a @code{gnutls_session_t} type. 5479 5480This function returns the maximum early data size in this connection. 5481This property can only be set to servers. The client may be 5482provided with the maximum allowed size through the "early_data" 5483extension of the NewSessionTicket handshake message. 5484 5485@strong{Returns:} The maximum early data size in this connection. 5486 5487@strong{Since:} 3.6.5 5488@end deftypefun 5489 5490@subheading gnutls_record_get_max_size 5491@anchor{gnutls_record_get_max_size} 5492@deftypefun {size_t} {gnutls_record_get_max_size} (gnutls_session_t @var{session}) 5493@var{session}: is a @code{gnutls_session_t} type. 5494 5495Get the record size. The maximum record size is negotiated by the 5496client after the first handshake message. 5497 5498@strong{Returns:} The maximum record packet size in this connection. 5499@end deftypefun 5500 5501@subheading gnutls_record_get_state 5502@anchor{gnutls_record_get_state} 5503@deftypefun {int} {gnutls_record_get_state} (gnutls_session_t @var{session}, unsigned @var{read}, gnutls_datum_t * @var{mac_key}, gnutls_datum_t * @var{IV}, gnutls_datum_t * @var{cipher_key}, unsigned char [8] @var{seq_number}) 5504@var{session}: is a @code{gnutls_session_t} type 5505 5506@var{read}: if non-zero the read parameters are returned, otherwise the write 5507 5508@var{mac_key}: the key used for MAC (if a MAC is used) 5509 5510@var{IV}: the initialization vector or nonce used 5511 5512@var{cipher_key}: the cipher key 5513 5514@var{seq_number}: A 64-bit sequence number 5515 5516This function will return the parameters of the current record state. 5517These are only useful to be provided to an external off-loading device 5518or subsystem. The returned values should be considered constant 5519and valid for the lifetime of the session. 5520 5521In that case, to sync the state back you must call @code{gnutls_record_set_state()} . 5522 5523@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 5524 5525Since 3.4.0 5526@end deftypefun 5527 5528@subheading gnutls_record_overhead_size 5529@anchor{gnutls_record_overhead_size} 5530@deftypefun {size_t} {gnutls_record_overhead_size} (gnutls_session_t @var{session}) 5531@var{session}: is @code{gnutls_session_t} 5532 5533This function will return the size in bytes of the overhead 5534due to TLS (or DTLS) per record. On certain occasions 5535(e.g., CBC ciphers) the returned value is the maximum 5536possible overhead. 5537 5538@strong{Since:} 3.2.2 5539@end deftypefun 5540 5541@subheading gnutls_record_recv 5542@anchor{gnutls_record_recv} 5543@deftypefun {ssize_t} {gnutls_record_recv} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}) 5544@var{session}: is a @code{gnutls_session_t} type. 5545 5546@var{data}: the buffer that the data will be read into 5547 5548@var{data_size}: the number of requested bytes 5549 5550This function has the similar semantics with @code{recv()} . The only 5551difference is that it accepts a GnuTLS session, and uses different 5552error codes. 5553In the special case that the peer requests a renegotiation, the 5554caller will receive an error code of @code{GNUTLS_E_REHANDSHAKE} . In case 5555of a client, this message may be simply ignored, replied with an alert 5556@code{GNUTLS_A_NO_RENEGOTIATION} , or replied with a new handshake, 5557depending on the client's will. A server receiving this error code 5558can only initiate a new handshake or terminate the session. 5559 5560If @code{EINTR} is returned by the internal pull function (the default 5561is @code{recv()} ) then @code{GNUTLS_E_INTERRUPTED} will be returned. If 5562@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} is returned, you must 5563call this function again to get the data. See also 5564@code{gnutls_record_get_direction()} . 5565 5566@strong{Returns:} The number of bytes received and zero on EOF (for stream 5567connections). A negative error code is returned in case of an error. 5568The number of bytes received might be less than the requested @code{data_size} . 5569@end deftypefun 5570 5571@subheading gnutls_record_recv_early_data 5572@anchor{gnutls_record_recv_early_data} 5573@deftypefun {ssize_t} {gnutls_record_recv_early_data} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}) 5574@var{session}: is a @code{gnutls_session_t} type. 5575 5576@var{data}: the buffer that the data will be read into 5577 5578@var{data_size}: the number of requested bytes 5579 5580This function can be used by a searver to retrieve data sent early 5581in the handshake processes when resuming a session. This is used 5582to implement a zero-roundtrip (0-RTT) mode. It has the same 5583semantics as @code{gnutls_record_recv()} . 5584 5585This function can be called either in a handshake hook, or after 5586the handshake is complete. 5587 5588@strong{Returns:} The number of bytes received and zero when early data 5589reading is complete. A negative error code is returned in case of 5590an error. If no early data is received during the handshake, this 5591function returns @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . The 5592number of bytes received might be less than the requested 5593 @code{data_size} . 5594 5595@strong{Since:} 3.6.5 5596@end deftypefun 5597 5598@subheading gnutls_record_recv_packet 5599@anchor{gnutls_record_recv_packet} 5600@deftypefun {ssize_t} {gnutls_record_recv_packet} (gnutls_session_t @var{session}, gnutls_packet_t * @var{packet}) 5601@var{session}: is a @code{gnutls_session_t} type. 5602 5603@var{packet}: the structure that will hold the packet data 5604 5605This is a lower-level function than @code{gnutls_record_recv()} and allows 5606to directly receive the whole decrypted packet. That avoids a 5607memory copy, and is intended to be used by applications seeking high 5608performance. 5609 5610The received packet is accessed using @code{gnutls_packet_get()} and 5611must be deinitialized using @code{gnutls_packet_deinit()} . The returned 5612packet will be @code{NULL} if the return value is zero (EOF). 5613 5614@strong{Returns:} The number of bytes received and zero on EOF (for stream 5615connections). A negative error code is returned in case of an error. 5616 5617@strong{Since:} 3.3.5 5618@end deftypefun 5619 5620@subheading gnutls_record_recv_seq 5621@anchor{gnutls_record_recv_seq} 5622@deftypefun {ssize_t} {gnutls_record_recv_seq} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}, unsigned char * @var{seq}) 5623@var{session}: is a @code{gnutls_session_t} type. 5624 5625@var{data}: the buffer that the data will be read into 5626 5627@var{data_size}: the number of requested bytes 5628 5629@var{seq}: is the packet's 64-bit sequence number. Should have space for 8 bytes. 5630 5631This function is the same as @code{gnutls_record_recv()} , except that 5632it returns in addition to data, the sequence number of the data. 5633This is useful in DTLS where record packets might be received 5634out-of-order. The returned 8-byte sequence number is an 5635integer in big-endian format and should be 5636treated as a unique message identification. 5637 5638@strong{Returns:} The number of bytes received and zero on EOF. A negative 5639error code is returned in case of an error. The number of bytes 5640received might be less than @code{data_size} . 5641 5642@strong{Since:} 3.0 5643@end deftypefun 5644 5645@subheading gnutls_record_send 5646@anchor{gnutls_record_send} 5647@deftypefun {ssize_t} {gnutls_record_send} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}) 5648@var{session}: is a @code{gnutls_session_t} type. 5649 5650@var{data}: contains the data to send 5651 5652@var{data_size}: is the length of the data 5653 5654This function has the similar semantics with @code{send()} . The only 5655difference is that it accepts a GnuTLS session, and uses different 5656error codes. 5657Note that if the send buffer is full, @code{send()} will block this 5658function. See the @code{send()} documentation for more information. 5659 5660You can replace the default push function which is @code{send()} , by using 5661@code{gnutls_transport_set_push_function()} . 5662 5663If the EINTR is returned by the internal push function 5664then @code{GNUTLS_E_INTERRUPTED} will be returned. If 5665@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} is returned, you must 5666call this function again with the exact same parameters, or provide a 5667@code{NULL} pointer for @code{data} and 0 for @code{data_size} , in order to write the 5668same data as before. If you wish to discard the previous data instead 5669of retrying, you must call @code{gnutls_record_discard_queued()} before 5670calling this function with different parameters. Note that the latter 5671works only on special transports (e.g., UDP). 5672cf. @code{gnutls_record_get_direction()} . 5673 5674Note that in DTLS this function will return the @code{GNUTLS_E_LARGE_PACKET} 5675error code if the send data exceed the data MTU value - as returned 5676by @code{gnutls_dtls_get_data_mtu()} . The errno value EMSGSIZE 5677also maps to @code{GNUTLS_E_LARGE_PACKET} . 5678Note that since 3.2.13 this function can be called under cork in DTLS 5679mode, and will refuse to send data over the MTU size by returning 5680@code{GNUTLS_E_LARGE_PACKET} . 5681 5682@strong{Returns:} The number of bytes sent, or a negative error code. The 5683number of bytes sent might be less than @code{data_size} . The maximum 5684number of bytes this function can send in a single call depends 5685on the negotiated maximum record size. 5686@end deftypefun 5687 5688@subheading gnutls_record_send2 5689@anchor{gnutls_record_send2} 5690@deftypefun {ssize_t} {gnutls_record_send2} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}, size_t @var{pad}, unsigned @var{flags}) 5691@var{session}: is a @code{gnutls_session_t} type. 5692 5693@var{data}: contains the data to send 5694 5695@var{data_size}: is the length of the data 5696 5697@var{pad}: padding to be added to the record 5698 5699@var{flags}: must be zero 5700 5701This function is identical to @code{gnutls_record_send()} except that it 5702takes an extra argument to specify padding to be added the record. 5703To determine the maximum size of padding, use 5704@code{gnutls_record_get_max_size()} and @code{gnutls_record_overhead_size()} . 5705 5706Note that in order for GnuTLS to provide constant time processing 5707of padding and data in TLS1.3, the flag @code{GNUTLS_SAFE_PADDING_CHECK} 5708must be used in @code{gnutls_init()} . 5709 5710@strong{Returns:} The number of bytes sent, or a negative error code. The 5711number of bytes sent might be less than @code{data_size} . The maximum 5712number of bytes this function can send in a single call depends 5713on the negotiated maximum record size. 5714 5715@strong{Since:} 3.6.3 5716@end deftypefun 5717 5718@subheading gnutls_record_send_early_data 5719@anchor{gnutls_record_send_early_data} 5720@deftypefun {ssize_t} {gnutls_record_send_early_data} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}) 5721@var{session}: is a @code{gnutls_session_t} type. 5722 5723@var{data}: contains the data to send 5724 5725@var{data_size}: is the length of the data 5726 5727This function can be used by a client to send data early in the 5728handshake processes when resuming a session. This is used to 5729implement a zero-roundtrip (0-RTT) mode. It has the same semantics 5730as @code{gnutls_record_send()} . 5731 5732There may be a limit to the amount of data sent as early data. Use 5733@code{gnutls_record_get_max_early_data_size()} to check the limit. If the 5734limit exceeds, this function returns 5735@code{GNUTLS_E_RECORD_LIMIT_REACHED} . 5736 5737@strong{Returns:} The number of bytes sent, or a negative error code. The 5738number of bytes sent might be less than @code{data_size} . The maximum 5739number of bytes this function can send in a single call depends 5740on the negotiated maximum record size. 5741 5742@strong{Since:} 3.6.5 5743@end deftypefun 5744 5745@subheading gnutls_record_send_range 5746@anchor{gnutls_record_send_range} 5747@deftypefun {ssize_t} {gnutls_record_send_range} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}, const gnutls_range_st * @var{range}) 5748@var{session}: is a @code{gnutls_session_t} type. 5749 5750@var{data}: contains the data to send. 5751 5752@var{data_size}: is the length of the data. 5753 5754@var{range}: is the range of lengths in which the real data length must be hidden. 5755 5756This function operates like @code{gnutls_record_send()} but, while 5757@code{gnutls_record_send()} adds minimal padding to each TLS record, 5758this function uses the TLS extra-padding feature to conceal the real 5759data size within the range of lengths provided. 5760Some TLS sessions do not support extra padding (e.g. stream ciphers in standard 5761TLS or SSL3 sessions). To know whether the current session supports extra 5762padding, and hence length hiding, use the @code{gnutls_record_can_use_length_hiding()} 5763function. 5764 5765@strong{Note:} This function currently is limited to blocking sockets. 5766 5767@strong{Returns:} The number of bytes sent (that is data_size in a successful invocation), 5768or a negative error code. 5769@end deftypefun 5770 5771@subheading gnutls_record_set_max_early_data_size 5772@anchor{gnutls_record_set_max_early_data_size} 5773@deftypefun {int} {gnutls_record_set_max_early_data_size} (gnutls_session_t @var{session}, size_t @var{size}) 5774@var{session}: is a @code{gnutls_session_t} type. 5775 5776@var{size}: is the new size 5777 5778This function sets the maximum early data size in this connection. 5779This property can only be set to servers. The client may be 5780provided with the maximum allowed size through the "early_data" 5781extension of the NewSessionTicket handshake message. 5782 5783@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 5784otherwise a negative error code is returned. 5785 5786@strong{Since:} 3.6.4 5787@end deftypefun 5788 5789@subheading gnutls_record_set_max_recv_size 5790@anchor{gnutls_record_set_max_recv_size} 5791@deftypefun {ssize_t} {gnutls_record_set_max_recv_size} (gnutls_session_t @var{session}, size_t @var{size}) 5792@var{session}: is a @code{gnutls_session_t} type. 5793 5794@var{size}: is the new size 5795 5796This function sets the maximum amount of plaintext received in a 5797record in this connection. 5798 5799The limit is also negotiated through a TLS extension called 'record 5800size limit'. Note that while the 'record size limit' extension is 5801preferred, not all TLS implementations use or even understand the 5802extension. 5803 5804@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 5805otherwise a negative error code is returned. 5806 5807@strong{Since:} 3.6.8 5808@end deftypefun 5809 5810@subheading gnutls_record_set_max_size 5811@anchor{gnutls_record_set_max_size} 5812@deftypefun {ssize_t} {gnutls_record_set_max_size} (gnutls_session_t @var{session}, size_t @var{size}) 5813@var{session}: is a @code{gnutls_session_t} type. 5814 5815@var{size}: is the new size 5816 5817This function sets the maximum amount of plaintext sent and 5818received in a record in this connection. 5819 5820Prior to 3.6.4, this function was implemented using a TLS extension 5821called 'max fragment length', which limits the acceptable values to 5822512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12). 5823 5824Since 3.6.4, the limit is also negotiated through a new TLS 5825extension called 'record size limit', which doesn't have the 5826limitation, as long as the value ranges between 512 and 16384. 5827Note that while the 'record size limit' extension is preferred, not 5828all TLS implementations use or even understand the extension. 5829 5830@strong{Deprecated:} if the client can assume that the 'record size limit' 5831extension is supported by the server, we recommend using 5832@code{gnutls_record_set_max_recv_size()} instead. 5833 5834@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 5835otherwise a negative error code is returned. 5836@end deftypefun 5837 5838@subheading gnutls_record_set_state 5839@anchor{gnutls_record_set_state} 5840@deftypefun {int} {gnutls_record_set_state} (gnutls_session_t @var{session}, unsigned @var{read}, const unsigned char [8] @var{seq_number}) 5841@var{session}: is a @code{gnutls_session_t} type 5842 5843@var{read}: if non-zero the read parameters are returned, otherwise the write 5844 5845@var{seq_number}: A 64-bit sequence number 5846 5847This function will set the sequence number in the current record state. 5848This function is useful if sending and receiving are offloaded from 5849gnutls. That is, if @code{gnutls_record_get_state()} was used. 5850 5851@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 5852 5853Since 3.4.0 5854@end deftypefun 5855 5856@subheading gnutls_record_set_timeout 5857@anchor{gnutls_record_set_timeout} 5858@deftypefun {void} {gnutls_record_set_timeout} (gnutls_session_t @var{session}, unsigned int @var{ms}) 5859@var{session}: is a @code{gnutls_session_t} type. 5860 5861@var{ms}: is a timeout value in milliseconds 5862 5863This function sets the receive timeout for the record layer 5864to the provided value. Use an @code{ms} value of zero to disable 5865timeout (the default), or @code{GNUTLS_INDEFINITE_TIMEOUT} , to 5866set an indefinite timeout. 5867 5868This function requires to set a pull timeout callback. See 5869@code{gnutls_transport_set_pull_timeout_function()} . 5870 5871@strong{Since:} 3.1.7 5872@end deftypefun 5873 5874@subheading gnutls_record_uncork 5875@anchor{gnutls_record_uncork} 5876@deftypefun {int} {gnutls_record_uncork} (gnutls_session_t @var{session}, unsigned int @var{flags}) 5877@var{session}: is a @code{gnutls_session_t} type. 5878 5879@var{flags}: Could be zero or @code{GNUTLS_RECORD_WAIT} 5880 5881This resets the effect of @code{gnutls_record_cork()} , and flushes any pending 5882data. If the @code{GNUTLS_RECORD_WAIT} flag is specified then this 5883function will block until the data is sent or a fatal error 5884occurs (i.e., the function will retry on @code{GNUTLS_E_AGAIN} and 5885@code{GNUTLS_E_INTERRUPTED} ). 5886 5887If the flag @code{GNUTLS_RECORD_WAIT} is not specified and the function 5888is interrupted then the @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} 5889errors will be returned. To obtain the data left in the corked 5890buffer use @code{gnutls_record_check_corked()} . 5891 5892@strong{Returns:} On success the number of transmitted data is returned, or 5893otherwise a negative error code. 5894 5895@strong{Since:} 3.1.9 5896@end deftypefun 5897 5898@subheading gnutls_rehandshake 5899@anchor{gnutls_rehandshake} 5900@deftypefun {int} {gnutls_rehandshake} (gnutls_session_t @var{session}) 5901@var{session}: is a @code{gnutls_session_t} type. 5902 5903This function can only be called in server side, and 5904instructs a TLS 1.2 or earlier client to renegotiate 5905parameters (perform a handshake), by sending a 5906hello request message. 5907 5908If this function succeeds, the calling application 5909should call @code{gnutls_record_recv()} until @code{GNUTLS_E_REHANDSHAKE} 5910is returned to clear any pending data. If the @code{GNUTLS_E_REHANDSHAKE} 5911error code is not seen, then the handshake request was 5912not followed by the peer (the TLS protocol does not require 5913the client to do, and such compliance should be handled 5914by the application protocol). 5915 5916Once the @code{GNUTLS_E_REHANDSHAKE} error code is seen, the 5917calling application should proceed to calling 5918@code{gnutls_handshake()} to negotiate the new 5919parameters. 5920 5921If the client does not wish to renegotiate parameters he 5922may reply with an alert message, and in that case the return code seen 5923by subsequent @code{gnutls_record_recv()} will be 5924@code{GNUTLS_E_WARNING_ALERT_RECEIVED} with the specific alert being 5925@code{GNUTLS_A_NO_RENEGOTIATION} . A client may also choose to ignore 5926this request. 5927 5928Under TLS 1.3 this function is equivalent to @code{gnutls_session_key_update()} 5929with the @code{GNUTLS_KU_PEER} flag. In that case subsequent calls to 5930@code{gnutls_record_recv()} will not return @code{GNUTLS_E_REHANDSHAKE} , and 5931calls to @code{gnutls_handshake()} in server side are a no-op. 5932 5933This function always fails with @code{GNUTLS_E_INVALID_REQUEST} when 5934called in client side. 5935 5936@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 5937@end deftypefun 5938 5939@subheading gnutls_safe_renegotiation_status 5940@anchor{gnutls_safe_renegotiation_status} 5941@deftypefun {unsigned} {gnutls_safe_renegotiation_status} (gnutls_session_t @var{session}) 5942@var{session}: is a @code{gnutls_session_t} type. 5943 5944Can be used to check whether safe renegotiation is being used 5945in the current session. 5946 5947@strong{Returns:} 0 when safe renegotiation is not used and non (0) when 5948safe renegotiation is used. 5949 5950@strong{Since:} 2.10.0 5951@end deftypefun 5952 5953@subheading gnutls_sec_param_get_name 5954@anchor{gnutls_sec_param_get_name} 5955@deftypefun {const char *} {gnutls_sec_param_get_name} (gnutls_sec_param_t @var{param}) 5956@var{param}: is a security parameter 5957 5958Convert a @code{gnutls_sec_param_t} value to a string. 5959 5960@strong{Returns:} a pointer to a string that contains the name of the 5961specified security level, or @code{NULL} . 5962 5963@strong{Since:} 2.12.0 5964@end deftypefun 5965 5966@subheading gnutls_sec_param_to_pk_bits 5967@anchor{gnutls_sec_param_to_pk_bits} 5968@deftypefun {unsigned int} {gnutls_sec_param_to_pk_bits} (gnutls_pk_algorithm_t @var{algo}, gnutls_sec_param_t @var{param}) 5969@var{algo}: is a public key algorithm 5970 5971@var{param}: is a security parameter 5972 5973When generating private and public key pairs a difficult question 5974is which size of "bits" the modulus will be in RSA and the group size 5975in DSA. The easy answer is 1024, which is also wrong. This function 5976will convert a human understandable security parameter to an 5977appropriate size for the specific algorithm. 5978 5979@strong{Returns:} The number of bits, or (0). 5980 5981@strong{Since:} 2.12.0 5982@end deftypefun 5983 5984@subheading gnutls_sec_param_to_symmetric_bits 5985@anchor{gnutls_sec_param_to_symmetric_bits} 5986@deftypefun {unsigned int} {gnutls_sec_param_to_symmetric_bits} (gnutls_sec_param_t @var{param}) 5987@var{param}: is a security parameter 5988 5989This function will return the number of bits that correspond to 5990symmetric cipher strength for the given security parameter. 5991 5992@strong{Returns:} The number of bits, or (0). 5993 5994@strong{Since:} 3.3.0 5995@end deftypefun 5996 5997@subheading gnutls_server_name_get 5998@anchor{gnutls_server_name_get} 5999@deftypefun {int} {gnutls_server_name_get} (gnutls_session_t @var{session}, void * @var{data}, size_t * @var{data_length}, unsigned int * @var{type}, unsigned int @var{indx}) 6000@var{session}: is a @code{gnutls_session_t} type. 6001 6002@var{data}: will hold the data 6003 6004@var{data_length}: will hold the data length. Must hold the maximum size of data. 6005 6006@var{type}: will hold the server name indicator type 6007 6008@var{indx}: is the index of the server_name 6009 6010This function will allow you to get the name indication (if any), a 6011client has sent. The name indication may be any of the enumeration 6012gnutls_server_name_type_t. 6013 6014If @code{type} is GNUTLS_NAME_DNS, then this function is to be used by 6015servers that support virtual hosting, and the data will be a null 6016terminated IDNA ACE string (prior to GnuTLS 3.4.0 it was a UTF-8 string). 6017 6018If @code{data} has not enough size to hold the server name 6019GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and @code{data_length} will 6020hold the required size. 6021 6022 @code{indx} is used to retrieve more than one server names (if sent by 6023the client). The first server name has an index of 0, the second 1 6024and so on. If no name with the given index exists 6025GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned. 6026 6027@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, on UTF-8 6028decoding error @code{GNUTLS_E_IDNA_ERROR} is returned, otherwise a negative 6029error code is returned. 6030@end deftypefun 6031 6032@subheading gnutls_server_name_set 6033@anchor{gnutls_server_name_set} 6034@deftypefun {int} {gnutls_server_name_set} (gnutls_session_t @var{session}, gnutls_server_name_type_t @var{type}, const void * @var{name}, size_t @var{name_length}) 6035@var{session}: is a @code{gnutls_session_t} type. 6036 6037@var{type}: specifies the indicator type 6038 6039@var{name}: is a string that contains the server name. 6040 6041@var{name_length}: holds the length of name excluding the terminating null byte 6042 6043This function is to be used by clients that want to inform (via a 6044TLS extension mechanism) the server of the name they connected to. 6045This should be used by clients that connect to servers that do 6046virtual hosting. 6047 6048The value of @code{name} depends on the @code{type} type. In case of 6049@code{GNUTLS_NAME_DNS} , a UTF-8 null-terminated domain name string, 6050without the trailing dot, is expected. 6051 6052IPv4 or IPv6 addresses are not permitted to be set by this function. 6053If the function is called with a name of @code{name_length} zero it will clear 6054all server names set. 6055 6056@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 6057otherwise a negative error code is returned. 6058@end deftypefun 6059 6060@subheading gnutls_session_channel_binding 6061@anchor{gnutls_session_channel_binding} 6062@deftypefun {int} {gnutls_session_channel_binding} (gnutls_session_t @var{session}, gnutls_channel_binding_t @var{cbtype}, gnutls_datum_t * @var{cb}) 6063@var{session}: is a @code{gnutls_session_t} type. 6064 6065@var{cbtype}: an @code{gnutls_channel_binding_t} enumeration type 6066 6067@var{cb}: output buffer array with data 6068 6069Extract given channel binding data of the @code{cbtype} (e.g., 6070@code{GNUTLS_CB_TLS_UNIQUE} ) type. 6071 6072@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, 6073@code{GNUTLS_E_UNIMPLEMENTED_FEATURE} if the @code{cbtype} is unsupported, 6074@code{GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE} if the data is not 6075currently available, or an error code. 6076 6077@strong{Since:} 2.12.0 6078@end deftypefun 6079 6080@subheading gnutls_session_enable_compatibility_mode 6081@anchor{gnutls_session_enable_compatibility_mode} 6082@deftypefun {void} {gnutls_session_enable_compatibility_mode} (gnutls_session_t @var{session}) 6083@var{session}: is a @code{gnutls_session_t} type. 6084 6085This function can be used to disable certain (security) features in 6086TLS in order to maintain maximum compatibility with buggy 6087clients. Because several trade-offs with security are enabled, 6088if required they will be reported through the audit subsystem. 6089 6090Normally only servers that require maximum compatibility with 6091everything out there, need to call this function. 6092 6093Note that this function must be called after any call to gnutls_priority 6094functions. 6095 6096@strong{Since:} 2.1.4 6097@end deftypefun 6098 6099@subheading gnutls_session_etm_status 6100@anchor{gnutls_session_etm_status} 6101@deftypefun {unsigned} {gnutls_session_etm_status} (gnutls_session_t @var{session}) 6102@var{session}: is a @code{gnutls_session_t} type. 6103 6104Get the status of the encrypt-then-mac extension negotiation. 6105This is in accordance to rfc7366 6106 6107@strong{Returns:} Non-zero if the negotiation was successful or zero otherwise. 6108@end deftypefun 6109 6110@subheading gnutls_session_ext_master_secret_status 6111@anchor{gnutls_session_ext_master_secret_status} 6112@deftypefun {unsigned} {gnutls_session_ext_master_secret_status} (gnutls_session_t @var{session}) 6113@var{session}: is a @code{gnutls_session_t} type. 6114 6115Get the status of the extended master secret extension negotiation. 6116This is in accordance to RFC7627. That information is also 6117available to the more generic @code{gnutls_session_get_flags()} . 6118 6119@strong{Returns:} Non-zero if the negotiation was successful or zero otherwise. 6120@end deftypefun 6121 6122@subheading gnutls_session_ext_register 6123@anchor{gnutls_session_ext_register} 6124@deftypefun {int} {gnutls_session_ext_register} (gnutls_session_t @var{session}, const char * @var{name}, int @var{id}, gnutls_ext_parse_type_t @var{parse_point}, gnutls_ext_recv_func @var{recv_func}, gnutls_ext_send_func @var{send_func}, gnutls_ext_deinit_data_func @var{deinit_func}, gnutls_ext_pack_func @var{pack_func}, gnutls_ext_unpack_func @var{unpack_func}, unsigned @var{flags}) 6125@var{session}: the session for which this extension will be set 6126 6127@var{name}: the name of the extension to register 6128 6129@var{id}: the numeric id of the extension 6130 6131@var{parse_point}: the parse type of the extension (see gnutls_ext_parse_type_t) 6132 6133@var{recv_func}: a function to receive the data 6134 6135@var{send_func}: a function to send the data 6136 6137@var{deinit_func}: a function deinitialize any private data 6138 6139@var{pack_func}: a function which serializes the extension's private data (used on session packing for resumption) 6140 6141@var{unpack_func}: a function which will deserialize the extension's private data 6142 6143@var{flags}: must be zero or flags from @code{gnutls_ext_flags_t} 6144 6145This function will register a new extension type. The extension will be 6146only usable within the registered session. If the extension type 6147is already registered then @code{GNUTLS_E_ALREADY_REGISTERED} will be returned, 6148unless the flag @code{GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL} is specified. The latter 6149flag when specified can be used to override certain extensions introduced 6150after 3.6.0. It is expected to be used by applications which handle 6151custom extensions that are not currently supported in GnuTLS, but direct 6152support for them may be added in the future. 6153 6154Each registered extension can store temporary data into the gnutls_session_t 6155structure using @code{gnutls_ext_set_data()} , and they can be retrieved using 6156@code{gnutls_ext_get_data()} . 6157 6158The validity of the extension registered can be given by the appropriate flags 6159of @code{gnutls_ext_flags_t} . If no validity is given, then the registered extension 6160will be valid for client and TLS1.2 server hello (or encrypted extensions for TLS1.3). 6161 6162@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 6163 6164@strong{Since:} 3.5.5 6165@end deftypefun 6166 6167@subheading gnutls_session_force_valid 6168@anchor{gnutls_session_force_valid} 6169@deftypefun {void} {gnutls_session_force_valid} (gnutls_session_t @var{session}) 6170@var{session}: is a @code{gnutls_session_t} type. 6171 6172Clears the invalid flag in a session. That means 6173that sessions were corrupt or invalid data were received 6174can be re-used. Use only when debugging or experimenting 6175with the TLS protocol. Should not be used in typical 6176applications. 6177@end deftypefun 6178 6179@subheading gnutls_session_get_data 6180@anchor{gnutls_session_get_data} 6181@deftypefun {int} {gnutls_session_get_data} (gnutls_session_t @var{session}, void * @var{session_data}, size_t * @var{session_data_size}) 6182@var{session}: is a @code{gnutls_session_t} type. 6183 6184@var{session_data}: is a pointer to space to hold the session. 6185 6186@var{session_data_size}: is the session_data's size, or it will be set by the function. 6187 6188Returns all session parameters needed to be stored to support resumption, 6189in a pre-allocated buffer. 6190 6191See @code{gnutls_session_get_data2()} for more information. 6192 6193@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6194an error code is returned. 6195@end deftypefun 6196 6197@subheading gnutls_session_get_data2 6198@anchor{gnutls_session_get_data2} 6199@deftypefun {int} {gnutls_session_get_data2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{data}) 6200@var{session}: is a @code{gnutls_session_t} type. 6201 6202@var{data}: is a pointer to a datum that will hold the session. 6203 6204Returns necessary parameters to support resumption. The client 6205should call this function and store the returned session data. A session 6206can be resumed later by calling @code{gnutls_session_set_data()} with the returned 6207data. Note that under TLS 1.3, it is recommended for clients to use 6208session parameters only once, to prevent passive-observers from correlating 6209the different connections. 6210 6211The returned @code{data} are allocated and must be released using @code{gnutls_free()} . 6212 6213This function will fail if called prior to handshake completion. In 6214case of false start TLS, the handshake completes only after data have 6215been successfully received from the peer. 6216 6217Under TLS1.3 session resumption is possible only after a session ticket 6218is received by the client. To ensure that such a ticket has been received use 6219@code{gnutls_session_get_flags()} and check for flag @code{GNUTLS_SFLAGS_SESSION_TICKET} ; 6220if this flag is not set, this function will wait for a new ticket within 6221an estimated roundtrip, and if not received will return dummy data which 6222cannot lead to resumption. 6223 6224To get notified when new tickets are received by the server 6225use @code{gnutls_handshake_set_hook_function()} to wait for @code{GNUTLS_HANDSHAKE_NEW_SESSION_TICKET} 6226messages. Each call of @code{gnutls_session_get_data2()} after a ticket is 6227received, will return session resumption data corresponding to the last 6228received ticket. 6229 6230Note that this function under TLS1.3 requires a callback to be set with 6231@code{gnutls_transport_set_pull_timeout_function()} for successful operation. There 6232was a bug before 3.6.10 which could make this function fail if that callback 6233was not set. On later versions if not set, the function will return a successful 6234error code, but will return dummy data that cannot lead to a resumption. 6235 6236@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6237an error code is returned. 6238@end deftypefun 6239 6240@subheading gnutls_session_get_desc 6241@anchor{gnutls_session_get_desc} 6242@deftypefun {char *} {gnutls_session_get_desc} (gnutls_session_t @var{session}) 6243@var{session}: is a gnutls session 6244 6245This function returns a string describing the current session. 6246The string is null terminated and allocated using @code{gnutls_malloc()} . 6247 6248If initial negotiation is not complete when this function is called, 6249@code{NULL} will be returned. 6250 6251@strong{Returns:} a description of the protocols and algorithms in the current session. 6252 6253@strong{Since:} 3.1.10 6254@end deftypefun 6255 6256@subheading gnutls_session_get_flags 6257@anchor{gnutls_session_get_flags} 6258@deftypefun {unsigned} {gnutls_session_get_flags} (gnutls_session_t @var{session}) 6259@var{session}: is a @code{gnutls_session_t} type. 6260 6261This function will return a series (ORed) of flags, applicable 6262for the current session. 6263 6264This replaces individual informational functions such as 6265@code{gnutls_safe_renegotiation_status()} , @code{gnutls_session_ext_master_secret_status()} , 6266etc. 6267 6268@strong{Returns:} An ORed sequence of flags (see @code{gnutls_session_flags_t} ) 6269 6270@strong{Since:} 3.5.0 6271@end deftypefun 6272 6273@subheading gnutls_session_get_id 6274@anchor{gnutls_session_get_id} 6275@deftypefun {int} {gnutls_session_get_id} (gnutls_session_t @var{session}, void * @var{session_id}, size_t * @var{session_id_size}) 6276@var{session}: is a @code{gnutls_session_t} type. 6277 6278@var{session_id}: is a pointer to space to hold the session id. 6279 6280@var{session_id_size}: initially should contain the maximum @code{session_id} size and will be updated. 6281 6282Returns the TLS session identifier. The session ID is selected by the 6283server, and in older versions of TLS was a unique identifier shared 6284between client and server which was persistent across resumption. 6285In the latest version of TLS (1.3) or TLS with session tickets, the 6286notion of session identifiers is undefined and cannot be relied for uniquely 6287identifying sessions across client and server. 6288 6289In client side this function returns the identifier returned by the 6290server, and cannot be assumed to have any relation to session resumption. 6291In server side this function is guaranteed to return a persistent 6292identifier of the session since GnuTLS 3.6.4, which may not necessarily 6293map into the TLS session ID value. Prior to that version the value 6294could only be considered a persistent identifier, under TLS1.2 or earlier 6295and when no session tickets were in use. 6296 6297The session identifier value returned is always less than 6298@code{GNUTLS_MAX_SESSION_ID_SIZE} . 6299 6300@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6301an error code is returned. 6302@end deftypefun 6303 6304@subheading gnutls_session_get_id2 6305@anchor{gnutls_session_get_id2} 6306@deftypefun {int} {gnutls_session_get_id2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{session_id}) 6307@var{session}: is a @code{gnutls_session_t} type. 6308 6309@var{session_id}: will point to the session ID. 6310 6311Returns the TLS session identifier. The session ID is selected by the 6312server, and in older versions of TLS was a unique identifier shared 6313between client and server which was persistent across resumption. 6314In the latest version of TLS (1.3) or TLS 1.2 with session tickets, the 6315notion of session identifiers is undefined and cannot be relied for uniquely 6316identifying sessions across client and server. 6317 6318In client side this function returns the identifier returned by the 6319server, and cannot be assumed to have any relation to session resumption. 6320In server side this function is guaranteed to return a persistent 6321identifier of the session since GnuTLS 3.6.4, which may not necessarily 6322map into the TLS session ID value. Prior to that version the value 6323could only be considered a persistent identifier, under TLS1.2 or earlier 6324and when no session tickets were in use. 6325 6326The session identifier value returned is always less than 6327@code{GNUTLS_MAX_SESSION_ID_SIZE} and should be treated as constant. 6328 6329@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6330an error code is returned. 6331 6332@strong{Since:} 3.1.4 6333@end deftypefun 6334 6335@subheading gnutls_session_get_keylog_function 6336@anchor{gnutls_session_get_keylog_function} 6337@deftypefun {gnutls_keylog_func} {gnutls_session_get_keylog_function} (const gnutls_session_t @var{session}) 6338@var{session}: is @code{gnutls_session_t} type 6339 6340This function will return the callback function set using 6341@code{gnutls_session_set_keylog_function()} . 6342 6343@strong{Returns:} The function set or @code{NULL} otherwise. 6344 6345@strong{Since:} 3.6.13 6346@end deftypefun 6347 6348@subheading gnutls_session_get_master_secret 6349@anchor{gnutls_session_get_master_secret} 6350@deftypefun {void} {gnutls_session_get_master_secret} (gnutls_session_t @var{session}, gnutls_datum_t * @var{secret}) 6351@var{session}: is a @code{gnutls_session_t} type. 6352 6353@var{secret}: the session's master secret 6354 6355This function returns pointers to the master secret 6356used in the TLS session. The pointers are not to be modified or deallocated. 6357 6358This function is only applicable under TLS 1.2 or earlier versions. 6359 6360@strong{Since:} 3.5.0 6361@end deftypefun 6362 6363@subheading gnutls_session_get_ptr 6364@anchor{gnutls_session_get_ptr} 6365@deftypefun {void *} {gnutls_session_get_ptr} (gnutls_session_t @var{session}) 6366@var{session}: is a @code{gnutls_session_t} type. 6367 6368Get user pointer for session. Useful in callbacks. This is the 6369pointer set with @code{gnutls_session_set_ptr()} . 6370 6371@strong{Returns:} the user given pointer from the session structure, or 6372@code{NULL} if it was never set. 6373@end deftypefun 6374 6375@subheading gnutls_session_get_random 6376@anchor{gnutls_session_get_random} 6377@deftypefun {void} {gnutls_session_get_random} (gnutls_session_t @var{session}, gnutls_datum_t * @var{client}, gnutls_datum_t * @var{server}) 6378@var{session}: is a @code{gnutls_session_t} type. 6379 6380@var{client}: the client part of the random 6381 6382@var{server}: the server part of the random 6383 6384This function returns pointers to the client and server 6385random fields used in the TLS handshake. The pointers are 6386not to be modified or deallocated. 6387 6388If a client random value has not yet been established, the output 6389will be garbage. 6390 6391@strong{Since:} 3.0 6392@end deftypefun 6393 6394@subheading gnutls_session_get_verify_cert_status 6395@anchor{gnutls_session_get_verify_cert_status} 6396@deftypefun {unsigned int} {gnutls_session_get_verify_cert_status} (gnutls_session_t @var{session}) 6397@var{session}: is a gnutls session 6398 6399This function returns the status of the verification when initiated 6400via auto-verification, i.e., by @code{gnutls_session_set_verify_cert2()} or 6401@code{gnutls_session_set_verify_cert()} . If no certificate verification 6402was occurred then the return value would be set to ((unsigned int)-1). 6403 6404The certificate verification status is the same as in @code{gnutls_certificate_verify_peers()} . 6405 6406@strong{Returns:} the certificate verification status. 6407 6408@strong{Since:} 3.4.6 6409@end deftypefun 6410 6411@subheading gnutls_session_is_resumed 6412@anchor{gnutls_session_is_resumed} 6413@deftypefun {int} {gnutls_session_is_resumed} (gnutls_session_t @var{session}) 6414@var{session}: is a @code{gnutls_session_t} type. 6415 6416Checks whether session is resumed or not. This is functional 6417for both server and client side. 6418 6419@strong{Returns:} non zero if this session is resumed, or a zero if this is 6420a new session. 6421@end deftypefun 6422 6423@subheading gnutls_session_key_update 6424@anchor{gnutls_session_key_update} 6425@deftypefun {int} {gnutls_session_key_update} (gnutls_session_t @var{session}, unsigned @var{flags}) 6426@var{session}: is a @code{gnutls_session_t} type. 6427 6428@var{flags}: zero of @code{GNUTLS_KU_PEER} 6429 6430This function will update/refresh the session keys when the 6431TLS protocol is 1.3 or better. The peer is notified of the 6432update by sending a message, so this function should be 6433treated similarly to @code{gnutls_record_send()} --i.e., it may 6434return @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} . 6435 6436When this flag @code{GNUTLS_KU_PEER} is specified, this function 6437in addition to updating the local keys, will ask the peer to 6438refresh its keys too. 6439 6440If the negotiated version is not TLS 1.3 or better this 6441function will return @code{GNUTLS_E_INVALID_REQUEST} . 6442 6443@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 6444 6445@strong{Since:} 3.6.3 6446@end deftypefun 6447 6448@subheading gnutls_session_resumption_requested 6449@anchor{gnutls_session_resumption_requested} 6450@deftypefun {int} {gnutls_session_resumption_requested} (gnutls_session_t @var{session}) 6451@var{session}: is a @code{gnutls_session_t} type. 6452 6453Check whether the client has asked for session resumption. 6454This function is valid only on server side. 6455 6456@strong{Returns:} non zero if session resumption was asked, or a zero if not. 6457@end deftypefun 6458 6459@subheading gnutls_session_set_data 6460@anchor{gnutls_session_set_data} 6461@deftypefun {int} {gnutls_session_set_data} (gnutls_session_t @var{session}, const void * @var{session_data}, size_t @var{session_data_size}) 6462@var{session}: is a @code{gnutls_session_t} type. 6463 6464@var{session_data}: is a pointer to space to hold the session. 6465 6466@var{session_data_size}: is the session's size 6467 6468Sets all session parameters, in order to resume a previously 6469established session. The session data given must be the one 6470returned by @code{gnutls_session_get_data()} . This function should be 6471called before @code{gnutls_handshake()} . 6472 6473Keep in mind that session resuming is advisory. The server may 6474choose not to resume the session, thus a full handshake will be 6475performed. 6476 6477@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6478an error code is returned. 6479@end deftypefun 6480 6481@subheading gnutls_session_set_id 6482@anchor{gnutls_session_set_id} 6483@deftypefun {int} {gnutls_session_set_id} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{sid}) 6484@var{session}: is a @code{gnutls_session_t} type. 6485 6486@var{sid}: the session identifier 6487 6488This function sets the session ID to be used in a client hello. 6489This is a function intended for exceptional uses. Do not use this 6490function unless you are implementing a custom protocol. 6491 6492To set session resumption parameters use @code{gnutls_session_set_data()} instead. 6493 6494@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6495an error code is returned. 6496 6497@strong{Since:} 3.2.1 6498@end deftypefun 6499 6500@subheading gnutls_session_set_keylog_function 6501@anchor{gnutls_session_set_keylog_function} 6502@deftypefun {void} {gnutls_session_set_keylog_function} (gnutls_session_t @var{session}, gnutls_keylog_func @var{func}) 6503@var{session}: is @code{gnutls_session_t} type 6504 6505@var{func}: is the function to be called 6506 6507This function will set a callback to be called when a new secret is 6508derived and installed during handshake. 6509 6510@strong{Since:} 3.6.13 6511@end deftypefun 6512 6513@subheading gnutls_session_set_premaster 6514@anchor{gnutls_session_set_premaster} 6515@deftypefun {int} {gnutls_session_set_premaster} (gnutls_session_t @var{session}, unsigned int @var{entity}, gnutls_protocol_t @var{version}, gnutls_kx_algorithm_t @var{kx}, gnutls_cipher_algorithm_t @var{cipher}, gnutls_mac_algorithm_t @var{mac}, gnutls_compression_method_t @var{comp}, const gnutls_datum_t * @var{master}, const gnutls_datum_t * @var{session_id}) 6516@var{session}: is a @code{gnutls_session_t} type. 6517 6518@var{entity}: GNUTLS_SERVER or GNUTLS_CLIENT 6519 6520@var{version}: the TLS protocol version 6521 6522@var{kx}: the key exchange method 6523 6524@var{cipher}: the cipher 6525 6526@var{mac}: the MAC algorithm 6527 6528@var{comp}: the compression method (ignored) 6529 6530@var{master}: the master key to use 6531 6532@var{session_id}: the session identifier 6533 6534This function sets the premaster secret in a session. This is 6535a function intended for exceptional uses. Do not use this 6536function unless you are implementing a legacy protocol. 6537Use @code{gnutls_session_set_data()} instead. 6538 6539@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6540an error code is returned. 6541@end deftypefun 6542 6543@subheading gnutls_session_set_ptr 6544@anchor{gnutls_session_set_ptr} 6545@deftypefun {void} {gnutls_session_set_ptr} (gnutls_session_t @var{session}, void * @var{ptr}) 6546@var{session}: is a @code{gnutls_session_t} type. 6547 6548@var{ptr}: is the user pointer 6549 6550This function will set (associate) the user given pointer @code{ptr} to 6551the session structure. This pointer can be accessed with 6552@code{gnutls_session_get_ptr()} . 6553@end deftypefun 6554 6555@subheading gnutls_session_set_verify_cert 6556@anchor{gnutls_session_set_verify_cert} 6557@deftypefun {void} {gnutls_session_set_verify_cert} (gnutls_session_t @var{session}, const char * @var{hostname}, unsigned @var{flags}) 6558@var{session}: is a gnutls session 6559 6560@var{hostname}: is the expected name of the peer; may be @code{NULL} 6561 6562@var{flags}: flags for certificate verification -- @code{gnutls_certificate_verify_flags} 6563 6564This function instructs GnuTLS to verify the peer's certificate 6565using the provided hostname. If the verification fails the handshake 6566will also fail with @code{GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR} . In that 6567case the verification result can be obtained using @code{gnutls_session_get_verify_cert_status()} . 6568 6569The @code{hostname} pointer provided must remain valid for the lifetime 6570of the session. More precisely it should be available during any subsequent 6571handshakes. If no hostname is provided, no hostname verification 6572will be performed. For a more advanced verification function check 6573@code{gnutls_session_set_verify_cert2()} . 6574 6575If @code{flags} is provided which contain a profile, this function should be 6576called after any session priority setting functions. 6577 6578The @code{gnutls_session_set_verify_cert()} function is intended to be used by TLS 6579clients to verify the server's certificate. 6580 6581@strong{Since:} 3.4.6 6582@end deftypefun 6583 6584@subheading gnutls_session_set_verify_cert2 6585@anchor{gnutls_session_set_verify_cert2} 6586@deftypefun {void} {gnutls_session_set_verify_cert2} (gnutls_session_t @var{session}, gnutls_typed_vdata_st * @var{data}, unsigned @var{elements}, unsigned @var{flags}) 6587@var{session}: is a gnutls session 6588 6589@var{data}: an array of typed data 6590 6591@var{elements}: the number of data elements 6592 6593@var{flags}: flags for certificate verification -- @code{gnutls_certificate_verify_flags} 6594 6595This function instructs GnuTLS to verify the peer's certificate 6596using the provided typed data information. If the verification fails the handshake 6597will also fail with @code{GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR} . In that 6598case the verification result can be obtained using @code{gnutls_session_get_verify_cert_status()} . 6599 6600The acceptable typed data are the same as in @code{gnutls_certificate_verify_peers()} , 6601and once set must remain valid for the lifetime of the session. More precisely 6602they should be available during any subsequent handshakes. 6603 6604If @code{flags} is provided which contain a profile, this function should be 6605called after any session priority setting functions. 6606 6607@strong{Since:} 3.4.6 6608@end deftypefun 6609 6610@subheading gnutls_session_set_verify_function 6611@anchor{gnutls_session_set_verify_function} 6612@deftypefun {void} {gnutls_session_set_verify_function} (gnutls_session_t @var{session}, gnutls_certificate_verify_function * @var{func}) 6613@var{session}: is a @code{gnutls_session_t} type. 6614 6615@var{func}: is the callback function 6616 6617This function sets a callback to be called when peer's certificate 6618has been received in order to verify it on receipt rather than 6619doing after the handshake is completed. This overrides any callback 6620set using @code{gnutls_certificate_set_verify_function()} . 6621 6622The callback's function prototype is: 6623int (*callback)(gnutls_session_t); 6624 6625If the callback function is provided then gnutls will call it, in the 6626handshake, just after the certificate message has been received. 6627To verify or obtain the certificate the @code{gnutls_certificate_verify_peers2()} , 6628@code{gnutls_certificate_type_get()} , @code{gnutls_certificate_get_peers()} functions 6629can be used. 6630 6631The callback function should return 0 for the handshake to continue 6632or non-zero to terminate. 6633 6634@strong{Since:} 3.4.6 6635@end deftypefun 6636 6637@subheading gnutls_session_supplemental_register 6638@anchor{gnutls_session_supplemental_register} 6639@deftypefun {int} {gnutls_session_supplemental_register} (gnutls_session_t @var{session}, const char * @var{name}, gnutls_supplemental_data_format_type_t @var{type}, gnutls_supp_recv_func @var{recv_func}, gnutls_supp_send_func @var{send_func}, unsigned @var{flags}) 6640@var{session}: the session for which this will be registered 6641 6642@var{name}: the name of the supplemental data to register 6643 6644@var{type}: the type of the supplemental data format 6645 6646@var{recv_func}: the function to receive the data 6647 6648@var{send_func}: the function to send the data 6649 6650@var{flags}: must be zero 6651 6652This function will register a new supplemental data type (rfc4680). 6653The registered supplemental functions will be used for that specific 6654session. The provided @code{type} must be an unassigned type in 6655@code{gnutls_supplemental_data_format_type_t} . 6656 6657If the type is already registered or handled by GnuTLS internally 6658@code{GNUTLS_E_ALREADY_REGISTERED} will be returned. 6659 6660As supplemental data are not defined under TLS 1.3, this function will 6661disable TLS 1.3 support for the given session. 6662 6663@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 6664 6665@strong{Since:} 3.5.5 6666@end deftypefun 6667 6668@subheading gnutls_session_ticket_enable_client 6669@anchor{gnutls_session_ticket_enable_client} 6670@deftypefun {int} {gnutls_session_ticket_enable_client} (gnutls_session_t @var{session}) 6671@var{session}: is a @code{gnutls_session_t} type. 6672 6673Request that the client should attempt session resumption using 6674SessionTicket. This call is typically unnecessary as session 6675tickets are enabled by default. 6676 6677@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 6678error code. 6679 6680@strong{Since:} 2.10.0 6681@end deftypefun 6682 6683@subheading gnutls_session_ticket_enable_server 6684@anchor{gnutls_session_ticket_enable_server} 6685@deftypefun {int} {gnutls_session_ticket_enable_server} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{key}) 6686@var{session}: is a @code{gnutls_session_t} type. 6687 6688@var{key}: key to encrypt session parameters. 6689 6690Request that the server should attempt session resumption using 6691session tickets, i.e., by delegating storage to the client. 6692 @code{key} must be initialized using @code{gnutls_session_ticket_key_generate()} . 6693To avoid leaking that key, use @code{gnutls_memset()} prior to 6694releasing it. 6695 6696The default ticket expiration time can be overridden using 6697@code{gnutls_db_set_cache_expiration()} . 6698 6699@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 6700error code. 6701 6702@strong{Since:} 2.10.0 6703@end deftypefun 6704 6705@subheading gnutls_session_ticket_key_generate 6706@anchor{gnutls_session_ticket_key_generate} 6707@deftypefun {int} {gnutls_session_ticket_key_generate} (gnutls_datum_t * @var{key}) 6708@var{key}: is a pointer to a @code{gnutls_datum_t} which will contain a newly 6709created key. 6710 6711Generate a random key to encrypt security parameters within 6712SessionTicket. 6713 6714@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 6715error code. 6716 6717@strong{Since:} 2.10.0 6718@end deftypefun 6719 6720@subheading gnutls_session_ticket_send 6721@anchor{gnutls_session_ticket_send} 6722@deftypefun {int} {gnutls_session_ticket_send} (gnutls_session_t @var{session}, unsigned @var{nr}, unsigned @var{flags}) 6723@var{session}: is a @code{gnutls_session_t} type. 6724 6725@var{nr}: the number of tickets to send 6726 6727@var{flags}: must be zero 6728 6729Sends a fresh session ticket to the peer. This is relevant only 6730in server side under TLS1.3. This function may also return @code{GNUTLS_E_AGAIN} 6731or @code{GNUTLS_E_INTERRUPTED} and in that case it must be called again. 6732 6733@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or a negative error code. 6734@end deftypefun 6735 6736@subheading gnutls_set_default_priority 6737@anchor{gnutls_set_default_priority} 6738@deftypefun {int} {gnutls_set_default_priority} (gnutls_session_t @var{session}) 6739@var{session}: is a @code{gnutls_session_t} type. 6740 6741Sets the default priority on the ciphers, key exchange methods, 6742and macs. This is the recommended method of 6743setting the defaults, in order to promote consistency between applications 6744using GnuTLS, and to allow GnuTLS using applications to update settings 6745in par with the library. For client applications which require 6746maximum compatibility consider calling @code{gnutls_session_enable_compatibility_mode()} 6747after this function. 6748 6749For an application to specify additional options to priority string 6750consider using @code{gnutls_set_default_priority_append()} . 6751 6752To allow a user to override the defaults (e.g., when a user interface 6753or configuration file is available), the functions 6754@code{gnutls_priority_set_direct()} or @code{gnutls_priority_set()} can 6755be used. 6756 6757@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 6758 6759@strong{Since:} 2.1.4 6760@end deftypefun 6761 6762@subheading gnutls_set_default_priority_append 6763@anchor{gnutls_set_default_priority_append} 6764@deftypefun {int} {gnutls_set_default_priority_append} (gnutls_session_t @var{session}, const char * @var{add_prio}, const char ** @var{err_pos}, unsigned @var{flags}) 6765@var{session}: is a @code{gnutls_session_t} type. 6766 6767@var{add_prio}: is a string describing priorities to be appended to default 6768 6769@var{err_pos}: In case of an error this will have the position in the string the error occurred 6770 6771@var{flags}: must be zero 6772 6773Sets the default priority on the ciphers, key exchange methods, 6774and macs with the additional options in @code{add_prio} . This is the recommended method of 6775setting the defaults when only few additional options are to be added. This promotes 6776consistency between applications using GnuTLS, and allows GnuTLS using applications 6777to update settings in par with the library. 6778 6779The @code{add_prio} string should start as a normal priority string, e.g., 6780'-VERS-TLS-ALL:+VERS-TLS1.3:%COMPAT' or '%FORCE_ETM'. That is, it must not start 6781with ':'. 6782 6783To allow a user to override the defaults (e.g., when a user interface 6784or configuration file is available), the functions 6785@code{gnutls_priority_set_direct()} or @code{gnutls_priority_set()} can 6786be used. 6787 6788@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. 6789 6790@strong{Since:} 3.6.3 6791@end deftypefun 6792 6793@subheading gnutls_sign_algorithm_get 6794@anchor{gnutls_sign_algorithm_get} 6795@deftypefun {int} {gnutls_sign_algorithm_get} (gnutls_session_t @var{session}) 6796@var{session}: is a @code{gnutls_session_t} type. 6797 6798Returns the signature algorithm that is (or will be) used in this 6799session by the server to sign data. This function should be 6800used only with TLS 1.2 or later. 6801 6802@strong{Returns:} The sign algorithm or @code{GNUTLS_SIGN_UNKNOWN} . 6803 6804@strong{Since:} 3.1.1 6805@end deftypefun 6806 6807@subheading gnutls_sign_algorithm_get_client 6808@anchor{gnutls_sign_algorithm_get_client} 6809@deftypefun {int} {gnutls_sign_algorithm_get_client} (gnutls_session_t @var{session}) 6810@var{session}: is a @code{gnutls_session_t} type. 6811 6812Returns the signature algorithm that is (or will be) used in this 6813session by the client to sign data. This function should be 6814used only with TLS 1.2 or later. 6815 6816@strong{Returns:} The sign algorithm or @code{GNUTLS_SIGN_UNKNOWN} . 6817 6818@strong{Since:} 3.1.11 6819@end deftypefun 6820 6821@subheading gnutls_sign_algorithm_get_requested 6822@anchor{gnutls_sign_algorithm_get_requested} 6823@deftypefun {int} {gnutls_sign_algorithm_get_requested} (gnutls_session_t @var{session}, size_t @var{indx}, gnutls_sign_algorithm_t * @var{algo}) 6824@var{session}: is a @code{gnutls_session_t} type. 6825 6826@var{indx}: is an index of the signature algorithm to return 6827 6828@var{algo}: the returned certificate type will be stored there 6829 6830Returns the signature algorithm specified by index that was 6831requested by the peer. If the specified index has no data available 6832this function returns @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . If 6833the negotiated TLS version does not support signature algorithms 6834then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned even 6835for the first index. The first index is 0. 6836 6837This function is useful in the certificate callback functions 6838to assist in selecting the correct certificate. 6839 6840@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise 6841an error code is returned. 6842 6843@strong{Since:} 2.10.0 6844@end deftypefun 6845 6846@subheading gnutls_sign_get_hash_algorithm 6847@anchor{gnutls_sign_get_hash_algorithm} 6848@deftypefun {gnutls_digest_algorithm_t} {gnutls_sign_get_hash_algorithm} (gnutls_sign_algorithm_t @var{sign}) 6849@var{sign}: is a signature algorithm 6850 6851This function returns the digest algorithm corresponding to 6852the given signature algorithms. 6853 6854@strong{Since:} 3.1.1 6855 6856@strong{Returns:} return a @code{gnutls_digest_algorithm_t} value, or @code{GNUTLS_DIG_UNKNOWN} on error. 6857@end deftypefun 6858 6859@subheading gnutls_sign_get_id 6860@anchor{gnutls_sign_get_id} 6861@deftypefun {gnutls_sign_algorithm_t} {gnutls_sign_get_id} (const char * @var{name}) 6862@var{name}: is a sign algorithm name 6863 6864The names are compared in a case insensitive way. 6865 6866@strong{Returns:} return a @code{gnutls_sign_algorithm_t} value corresponding to 6867the specified algorithm, or @code{GNUTLS_SIGN_UNKNOWN} on error. 6868@end deftypefun 6869 6870@subheading gnutls_sign_get_name 6871@anchor{gnutls_sign_get_name} 6872@deftypefun {const char *} {gnutls_sign_get_name} (gnutls_sign_algorithm_t @var{algorithm}) 6873@var{algorithm}: is a sign algorithm 6874 6875Convert a @code{gnutls_sign_algorithm_t} value to a string. 6876 6877@strong{Returns:} a string that contains the name of the specified sign 6878algorithm, or @code{NULL} . 6879@end deftypefun 6880 6881@subheading gnutls_sign_get_oid 6882@anchor{gnutls_sign_get_oid} 6883@deftypefun {const char *} {gnutls_sign_get_oid} (gnutls_sign_algorithm_t @var{sign}) 6884@var{sign}: is a sign algorithm 6885 6886Convert a @code{gnutls_sign_algorithm_t} value to its object identifier. 6887 6888@strong{Returns:} a string that contains the object identifier of the specified sign 6889algorithm, or @code{NULL} . 6890 6891@strong{Since:} 3.4.3 6892@end deftypefun 6893 6894@subheading gnutls_sign_get_pk_algorithm 6895@anchor{gnutls_sign_get_pk_algorithm} 6896@deftypefun {gnutls_pk_algorithm_t} {gnutls_sign_get_pk_algorithm} (gnutls_sign_algorithm_t @var{sign}) 6897@var{sign}: is a signature algorithm 6898 6899This function returns the public key algorithm corresponding to 6900the given signature algorithms. Note that there may be multiple 6901public key algorithms supporting a particular signature type; 6902when dealing with such algorithms use instead @code{gnutls_sign_supports_pk_algorithm()} . 6903 6904@strong{Since:} 3.1.1 6905 6906@strong{Returns:} return a @code{gnutls_pk_algorithm_t} value, or @code{GNUTLS_PK_UNKNOWN} on error. 6907@end deftypefun 6908 6909@subheading gnutls_sign_is_secure 6910@anchor{gnutls_sign_is_secure} 6911@deftypefun {unsigned} {gnutls_sign_is_secure} (gnutls_sign_algorithm_t @var{algorithm}) 6912@var{algorithm}: is a sign algorithm 6913 6914 6915@strong{Returns:} Non-zero if the provided signature algorithm is considered to be secure. 6916@end deftypefun 6917 6918@subheading gnutls_sign_is_secure2 6919@anchor{gnutls_sign_is_secure2} 6920@deftypefun {unsigned} {gnutls_sign_is_secure2} (gnutls_sign_algorithm_t @var{algorithm}, unsigned int @var{flags}) 6921@var{algorithm}: is a sign algorithm 6922 6923@var{flags}: zero or @code{GNUTLS_SIGN_FLAG_SECURE_FOR_CERTS} 6924 6925 6926@strong{Returns:} Non-zero if the provided signature algorithm is considered to be secure. 6927@end deftypefun 6928 6929@subheading gnutls_sign_list 6930@anchor{gnutls_sign_list} 6931@deftypefun {const gnutls_sign_algorithm_t *} {gnutls_sign_list} ( @var{void}) 6932 6933Get a list of supported public key signature algorithms. 6934This function is not thread safe. 6935 6936@strong{Returns:} a (0)-terminated list of @code{gnutls_sign_algorithm_t} 6937integers indicating the available ciphers. 6938@end deftypefun 6939 6940@subheading gnutls_sign_supports_pk_algorithm 6941@anchor{gnutls_sign_supports_pk_algorithm} 6942@deftypefun {unsigned} {gnutls_sign_supports_pk_algorithm} (gnutls_sign_algorithm_t @var{sign}, gnutls_pk_algorithm_t @var{pk}) 6943@var{sign}: is a signature algorithm 6944 6945@var{pk}: is a public key algorithm 6946 6947This function returns non-zero if the public key algorithm corresponds to 6948the given signature algorithm. That is, if that signature can be generated 6949from the given private key algorithm. 6950 6951@strong{Since:} 3.6.0 6952 6953@strong{Returns:} return non-zero when the provided algorithms are compatible. 6954@end deftypefun 6955 6956@subheading gnutls_srp_allocate_client_credentials 6957@anchor{gnutls_srp_allocate_client_credentials} 6958@deftypefun {int} {gnutls_srp_allocate_client_credentials} (gnutls_srp_client_credentials_t * @var{sc}) 6959@var{sc}: is a pointer to a @code{gnutls_srp_server_credentials_t} type. 6960 6961Allocate a gnutls_srp_client_credentials_t structure. 6962 6963@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 6964error code. 6965@end deftypefun 6966 6967@subheading gnutls_srp_allocate_server_credentials 6968@anchor{gnutls_srp_allocate_server_credentials} 6969@deftypefun {int} {gnutls_srp_allocate_server_credentials} (gnutls_srp_server_credentials_t * @var{sc}) 6970@var{sc}: is a pointer to a @code{gnutls_srp_server_credentials_t} type. 6971 6972Allocate a gnutls_srp_server_credentials_t structure. 6973 6974@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 6975error code. 6976@end deftypefun 6977 6978@subheading gnutls_srp_base64_decode 6979@anchor{gnutls_srp_base64_decode} 6980@deftypefun {int} {gnutls_srp_base64_decode} (const gnutls_datum_t * @var{b64_data}, char * @var{result}, size_t * @var{result_size}) 6981@var{b64_data}: contain the encoded data 6982 6983@var{result}: the place where decoded data will be copied 6984 6985@var{result_size}: holds the size of the result 6986 6987This function will decode the given encoded data, using the base64 6988encoding found in libsrp. 6989 6990Note that @code{b64_data} should be null terminated. 6991 6992Warning! This base64 encoding is not the "standard" encoding, so 6993do not use it for non-SRP purposes. 6994 6995@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not 6996long enough, or 0 on success. 6997@end deftypefun 6998 6999@subheading gnutls_srp_base64_decode2 7000@anchor{gnutls_srp_base64_decode2} 7001@deftypefun {int} {gnutls_srp_base64_decode2} (const gnutls_datum_t * @var{b64_data}, gnutls_datum_t * @var{result}) 7002@var{b64_data}: contains the encoded data 7003 7004@var{result}: the place where decoded data lie 7005 7006This function will decode the given encoded data. The decoded data 7007will be allocated, and stored into result. It will decode using 7008the base64 algorithm as used in libsrp. 7009 7010You should use @code{gnutls_free()} to free the returned data. 7011 7012Warning! This base64 encoding is not the "standard" encoding, so 7013do not use it for non-SRP purposes. 7014 7015@strong{Returns:} 0 on success, or an error code. 7016@end deftypefun 7017 7018@subheading gnutls_srp_base64_encode 7019@anchor{gnutls_srp_base64_encode} 7020@deftypefun {int} {gnutls_srp_base64_encode} (const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) 7021@var{data}: contain the raw data 7022 7023@var{result}: the place where base64 data will be copied 7024 7025@var{result_size}: holds the size of the result 7026 7027This function will convert the given data to printable data, using 7028the base64 encoding, as used in the libsrp. This is the encoding 7029used in SRP password files. If the provided buffer is not long 7030enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned. 7031 7032Warning! This base64 encoding is not the "standard" encoding, so 7033do not use it for non-SRP purposes. 7034 7035@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not 7036long enough, or 0 on success. 7037@end deftypefun 7038 7039@subheading gnutls_srp_base64_encode2 7040@anchor{gnutls_srp_base64_encode2} 7041@deftypefun {int} {gnutls_srp_base64_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) 7042@var{data}: contains the raw data 7043 7044@var{result}: will hold the newly allocated encoded data 7045 7046This function will convert the given data to printable data, using 7047the base64 encoding. This is the encoding used in SRP password 7048files. This function will allocate the required memory to hold 7049the encoded data. 7050 7051You should use @code{gnutls_free()} to free the returned data. 7052 7053Warning! This base64 encoding is not the "standard" encoding, so 7054do not use it for non-SRP purposes. 7055 7056@strong{Returns:} 0 on success, or an error code. 7057@end deftypefun 7058 7059@subheading gnutls_srp_free_client_credentials 7060@anchor{gnutls_srp_free_client_credentials} 7061@deftypefun {void} {gnutls_srp_free_client_credentials} (gnutls_srp_client_credentials_t @var{sc}) 7062@var{sc}: is a @code{gnutls_srp_client_credentials_t} type. 7063 7064Free a gnutls_srp_client_credentials_t structure. 7065@end deftypefun 7066 7067@subheading gnutls_srp_free_server_credentials 7068@anchor{gnutls_srp_free_server_credentials} 7069@deftypefun {void} {gnutls_srp_free_server_credentials} (gnutls_srp_server_credentials_t @var{sc}) 7070@var{sc}: is a @code{gnutls_srp_server_credentials_t} type. 7071 7072Free a gnutls_srp_server_credentials_t structure. 7073@end deftypefun 7074 7075@subheading gnutls_srp_server_get_username 7076@anchor{gnutls_srp_server_get_username} 7077@deftypefun {const char *} {gnutls_srp_server_get_username} (gnutls_session_t @var{session}) 7078@var{session}: is a gnutls session 7079 7080This function will return the username of the peer. This should 7081only be called in case of SRP authentication and in case of a 7082server. Returns NULL in case of an error. 7083 7084@strong{Returns:} SRP username of the peer, or NULL in case of error. 7085@end deftypefun 7086 7087@subheading gnutls_srp_set_client_credentials 7088@anchor{gnutls_srp_set_client_credentials} 7089@deftypefun {int} {gnutls_srp_set_client_credentials} (gnutls_srp_client_credentials_t @var{res}, const char * @var{username}, const char * @var{password}) 7090@var{res}: is a @code{gnutls_srp_client_credentials_t} type. 7091 7092@var{username}: is the user's userid 7093 7094@var{password}: is the user's password 7095 7096This function sets the username and password, in a 7097@code{gnutls_srp_client_credentials_t} type. Those will be used in 7098SRP authentication. @code{username} should be an ASCII string or UTF-8 7099string. In case of a UTF-8 string it is recommended to be following 7100the PRECIS framework for usernames (rfc8265). The password can 7101be in ASCII format, or normalized using @code{gnutls_utf8_password_normalize()} . 7102 7103@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 7104error code. 7105@end deftypefun 7106 7107@subheading gnutls_srp_set_client_credentials_function 7108@anchor{gnutls_srp_set_client_credentials_function} 7109@deftypefun {void} {gnutls_srp_set_client_credentials_function} (gnutls_srp_client_credentials_t @var{cred}, gnutls_srp_client_credentials_function * @var{func}) 7110@var{cred}: is a @code{gnutls_srp_server_credentials_t} type. 7111 7112@var{func}: is the callback function 7113 7114This function can be used to set a callback to retrieve the 7115username and password for client SRP authentication. The 7116callback's function form is: 7117 7118int (*callback)(gnutls_session_t, char** username, char**password); 7119 7120The @code{username} and @code{password} must be allocated using 7121@code{gnutls_malloc()} . 7122 7123The @code{username} should be an ASCII string or UTF-8 7124string. In case of a UTF-8 string it is recommended to be following 7125the PRECIS framework for usernames (rfc8265). The password can 7126be in ASCII format, or normalized using @code{gnutls_utf8_password_normalize()} . 7127 7128The callback function will be called once per handshake before the 7129initial hello message is sent. 7130 7131The callback should not return a negative error code the second 7132time called, since the handshake procedure will be aborted. 7133 7134The callback function should return 0 on success. 7135-1 indicates an error. 7136@end deftypefun 7137 7138@subheading gnutls_srp_set_prime_bits 7139@anchor{gnutls_srp_set_prime_bits} 7140@deftypefun {void} {gnutls_srp_set_prime_bits} (gnutls_session_t @var{session}, unsigned int @var{bits}) 7141@var{session}: is a @code{gnutls_session_t} type. 7142 7143@var{bits}: is the number of bits 7144 7145This function sets the minimum accepted number of bits, for use in 7146an SRP key exchange. If zero, the default 2048 bits will be used. 7147 7148In the client side it sets the minimum accepted number of bits. If 7149a server sends a prime with less bits than that 7150@code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER} will be returned by the 7151handshake. 7152 7153This function has no effect in server side. 7154 7155@strong{Since:} 2.6.0 7156@end deftypefun 7157 7158@subheading gnutls_srp_set_server_credentials_file 7159@anchor{gnutls_srp_set_server_credentials_file} 7160@deftypefun {int} {gnutls_srp_set_server_credentials_file} (gnutls_srp_server_credentials_t @var{res}, const char * @var{password_file}, const char * @var{password_conf_file}) 7161@var{res}: is a @code{gnutls_srp_server_credentials_t} type. 7162 7163@var{password_file}: is the SRP password file (tpasswd) 7164 7165@var{password_conf_file}: is the SRP password conf file (tpasswd.conf) 7166 7167This function sets the password files, in a 7168@code{gnutls_srp_server_credentials_t} type. Those password files 7169hold usernames and verifiers and will be used for SRP 7170authentication. 7171 7172@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 7173error code. 7174@end deftypefun 7175 7176@subheading gnutls_srp_set_server_credentials_function 7177@anchor{gnutls_srp_set_server_credentials_function} 7178@deftypefun {void} {gnutls_srp_set_server_credentials_function} (gnutls_srp_server_credentials_t @var{cred}, gnutls_srp_server_credentials_function * @var{func}) 7179@var{cred}: is a @code{gnutls_srp_server_credentials_t} type. 7180 7181@var{func}: is the callback function 7182 7183This function can be used to set a callback to retrieve the user's 7184SRP credentials. The callback's function form is: 7185 7186int (*callback)(gnutls_session_t, const char* username, 7187gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t *generator, 7188gnutls_datum_t *prime); 7189 7190 @code{username} contains the actual username. 7191The @code{salt} , @code{verifier} , @code{generator} and @code{prime} must be filled 7192in using the @code{gnutls_malloc()} . For convenience @code{prime} and @code{generator} may also be one of the static parameters defined in gnutls.h. 7193 7194Initially, the data field is NULL in every @code{gnutls_datum_t} 7195structure that the callback has to fill in. When the 7196callback is done GnuTLS deallocates all of those buffers 7197which are non-NULL, regardless of the return value. 7198 7199In order to prevent attackers from guessing valid usernames, 7200if a user does not exist, g and n values should be filled in 7201using a random user's parameters. In that case the callback must 7202return the special value (1). 7203See @code{gnutls_srp_set_server_fake_salt_seed} too. 7204If this is not required for your application, return a negative 7205number from the callback to abort the handshake. 7206 7207The callback function will only be called once per handshake. 7208The callback function should return 0 on success, while 7209-1 indicates an error. 7210@end deftypefun 7211 7212@subheading gnutls_srp_set_server_fake_salt_seed 7213@anchor{gnutls_srp_set_server_fake_salt_seed} 7214@deftypefun {void} {gnutls_srp_set_server_fake_salt_seed} (gnutls_srp_server_credentials_t @var{cred}, const gnutls_datum_t * @var{seed}, unsigned int @var{salt_length}) 7215@var{cred}: is a @code{gnutls_srp_server_credentials_t} type 7216 7217@var{seed}: is the seed data, only needs to be valid until the function 7218returns; size of the seed must be greater than zero 7219 7220@var{salt_length}: is the length of the generated fake salts 7221 7222This function sets the seed that is used to generate salts for 7223invalid (non-existent) usernames. 7224 7225In order to prevent attackers from guessing valid usernames, 7226when a user does not exist gnutls generates a salt and a verifier 7227and proceeds with the protocol as usual. 7228The authentication will ultimately fail, but the client cannot tell 7229whether the username is valid (exists) or invalid. 7230 7231If an attacker learns the seed, given a salt (which is part of the 7232handshake) which was generated when the seed was in use, it can tell 7233whether or not the authentication failed because of an unknown username. 7234This seed cannot be used to reveal application data or passwords. 7235 7236 @code{salt_length} should represent the salt length your application uses. 7237Generating fake salts longer than 20 bytes is not supported. 7238 7239By default the seed is a random value, different each time a 7240@code{gnutls_srp_server_credentials_t} is allocated and fake salts are 724116 bytes long. 7242 7243@strong{Since:} 3.3.0 7244@end deftypefun 7245 7246@subheading gnutls_srp_verifier 7247@anchor{gnutls_srp_verifier} 7248@deftypefun {int} {gnutls_srp_verifier} (const char * @var{username}, const char * @var{password}, const gnutls_datum_t * @var{salt}, const gnutls_datum_t * @var{generator}, const gnutls_datum_t * @var{prime}, gnutls_datum_t * @var{res}) 7249@var{username}: is the user's name 7250 7251@var{password}: is the user's password 7252 7253@var{salt}: should be some randomly generated bytes 7254 7255@var{generator}: is the generator of the group 7256 7257@var{prime}: is the group's prime 7258 7259@var{res}: where the verifier will be stored. 7260 7261This function will create an SRP verifier, as specified in 7262RFC2945. The @code{prime} and @code{generator} should be one of the static 7263parameters defined in gnutls/gnutls.h or may be generated. 7264 7265The verifier will be allocated with @code{gnutls_malloc} () and will be stored in 7266 @code{res} using binary format. 7267 7268@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an 7269error code. 7270@end deftypefun 7271 7272@subheading gnutls_srtp_get_keys 7273@anchor{gnutls_srtp_get_keys} 7274@deftypefun {int} {gnutls_srtp_get_keys} (gnutls_session_t @var{session}, void * @var{key_material}, unsigned int @var{key_material_size}, gnutls_datum_t * @var{client_key}, gnutls_datum_t * @var{client_salt}, gnutls_datum_t * @var{server_key}, gnutls_datum_t * @var{server_salt}) 7275@var{session}: is a @code{gnutls_session_t} type. 7276 7277@var{key_material}: Space to hold the generated key material 7278 7279@var{key_material_size}: The maximum size of the key material 7280 7281@var{client_key}: The master client write key, pointing inside the key material 7282 7283@var{client_salt}: The master client write salt, pointing inside the key material 7284 7285@var{server_key}: The master server write key, pointing inside the key material 7286 7287@var{server_salt}: The master server write salt, pointing inside the key material 7288 7289This is a helper function to generate the keying material for SRTP. 7290It requires the space of the key material to be pre-allocated (should be at least 72912x the maximum key size and salt size). The @code{client_key} , @code{client_salt} , @code{server_key} and @code{server_salt} are convenience datums that point inside the key material. They may 7292be @code{NULL} . 7293 7294@strong{Returns:} On success the size of the key material is returned, 7295otherwise, @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not 7296sufficient, or a negative error code. 7297 7298Since 3.1.4 7299@end deftypefun 7300 7301@subheading gnutls_srtp_get_mki 7302@anchor{gnutls_srtp_get_mki} 7303@deftypefun {int} {gnutls_srtp_get_mki} (gnutls_session_t @var{session}, gnutls_datum_t * @var{mki}) 7304@var{session}: is a @code{gnutls_session_t} type. 7305 7306@var{mki}: will hold the MKI 7307 7308This function exports the negotiated Master Key Identifier, 7309received by the peer if any. The returned value in @code{mki} should be 7310treated as constant and valid only during the session's lifetime. 7311 7312@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7313otherwise a negative error code is returned. 7314 7315Since 3.1.4 7316@end deftypefun 7317 7318@subheading gnutls_srtp_get_profile_id 7319@anchor{gnutls_srtp_get_profile_id} 7320@deftypefun {int} {gnutls_srtp_get_profile_id} (const char * @var{name}, gnutls_srtp_profile_t * @var{profile}) 7321@var{name}: The name of the profile to look up 7322 7323@var{profile}: Will hold the profile id 7324 7325This function allows you to look up a profile based on a string. 7326 7327@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7328otherwise a negative error code is returned. 7329 7330Since 3.1.4 7331@end deftypefun 7332 7333@subheading gnutls_srtp_get_profile_name 7334@anchor{gnutls_srtp_get_profile_name} 7335@deftypefun {const char *} {gnutls_srtp_get_profile_name} (gnutls_srtp_profile_t @var{profile}) 7336@var{profile}: The profile to look up a string for 7337 7338This function allows you to get the corresponding name for a 7339SRTP protection profile. 7340 7341@strong{Returns:} On success, the name of a SRTP profile as a string, 7342otherwise NULL. 7343 7344Since 3.1.4 7345@end deftypefun 7346 7347@subheading gnutls_srtp_get_selected_profile 7348@anchor{gnutls_srtp_get_selected_profile} 7349@deftypefun {int} {gnutls_srtp_get_selected_profile} (gnutls_session_t @var{session}, gnutls_srtp_profile_t * @var{profile}) 7350@var{session}: is a @code{gnutls_session_t} type. 7351 7352@var{profile}: will hold the profile 7353 7354This function allows you to get the negotiated SRTP profile. 7355 7356@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7357otherwise a negative error code is returned. 7358 7359Since 3.1.4 7360@end deftypefun 7361 7362@subheading gnutls_srtp_set_mki 7363@anchor{gnutls_srtp_set_mki} 7364@deftypefun {int} {gnutls_srtp_set_mki} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{mki}) 7365@var{session}: is a @code{gnutls_session_t} type. 7366 7367@var{mki}: holds the MKI 7368 7369This function sets the Master Key Identifier, to be 7370used by this session (if any). 7371 7372@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7373otherwise a negative error code is returned. 7374 7375Since 3.1.4 7376@end deftypefun 7377 7378@subheading gnutls_srtp_set_profile 7379@anchor{gnutls_srtp_set_profile} 7380@deftypefun {int} {gnutls_srtp_set_profile} (gnutls_session_t @var{session}, gnutls_srtp_profile_t @var{profile}) 7381@var{session}: is a @code{gnutls_session_t} type. 7382 7383@var{profile}: is the profile id to add. 7384 7385This function is to be used by both clients and servers, to declare 7386what SRTP profiles they support, to negotiate with the peer. 7387 7388@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7389otherwise a negative error code is returned. 7390 7391Since 3.1.4 7392@end deftypefun 7393 7394@subheading gnutls_srtp_set_profile_direct 7395@anchor{gnutls_srtp_set_profile_direct} 7396@deftypefun {int} {gnutls_srtp_set_profile_direct} (gnutls_session_t @var{session}, const char * @var{profiles}, const char ** @var{err_pos}) 7397@var{session}: is a @code{gnutls_session_t} type. 7398 7399@var{profiles}: is a string that contains the supported SRTP profiles, 7400separated by colons. 7401 7402@var{err_pos}: In case of an error this will have the position in the string the error occurred, may be NULL. 7403 7404This function is to be used by both clients and servers, to declare 7405what SRTP profiles they support, to negotiate with the peer. 7406 7407@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, 7408@code{GNUTLS_E_SUCCESS} on success, or an error code. 7409 7410Since 3.1.4 7411@end deftypefun 7412 7413@subheading gnutls_store_commitment 7414@anchor{gnutls_store_commitment} 7415@deftypefun {int} {gnutls_store_commitment} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_digest_algorithm_t @var{hash_algo}, const gnutls_datum_t * @var{hash}, time_t @var{expiration}, unsigned int @var{flags}) 7416@var{db_name}: A file specifying the stored keys (use NULL for the default) 7417 7418@var{tdb}: A storage structure or NULL to use the default 7419 7420@var{host}: The peer's name 7421 7422@var{service}: non-NULL if this key is specific to a service (e.g. http) 7423 7424@var{hash_algo}: The hash algorithm type 7425 7426@var{hash}: The raw hash 7427 7428@var{expiration}: The expiration time (use 0 to disable expiration) 7429 7430@var{flags}: should be 0 or @code{GNUTLS_SCOMMIT_FLAG_ALLOW_BROKEN} . 7431 7432This function will store the provided hash commitment to 7433the list of stored public keys. The key with the given 7434hash will be considered valid until the provided expiration time. 7435 7436The @code{tdb} variable if non-null specifies a custom backend for 7437the storage of entries. If it is NULL then the 7438default file backend will be used. 7439 7440Note that this function is not thread safe with the default backend. 7441 7442@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7443negative error value. 7444 7445@strong{Since:} 3.0 7446@end deftypefun 7447 7448@subheading gnutls_store_pubkey 7449@anchor{gnutls_store_pubkey} 7450@deftypefun {int} {gnutls_store_pubkey} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_certificate_type_t @var{cert_type}, const gnutls_datum_t * @var{cert}, time_t @var{expiration}, unsigned int @var{flags}) 7451@var{db_name}: A file specifying the stored keys (use NULL for the default) 7452 7453@var{tdb}: A storage structure or NULL to use the default 7454 7455@var{host}: The peer's name 7456 7457@var{service}: non-NULL if this key is specific to a service (e.g. http) 7458 7459@var{cert_type}: The type of the certificate 7460 7461@var{cert}: The data of the certificate 7462 7463@var{expiration}: The expiration time (use 0 to disable expiration) 7464 7465@var{flags}: should be 0. 7466 7467This function will store a raw public-key or a public-key provided via 7468a raw (DER-encoded) certificate to the list of stored public keys. The key 7469will be considered valid until the provided expiration time. 7470 7471The @code{tdb} variable if non-null specifies a custom backend for 7472the storage of entries. If it is NULL then the 7473default file backend will be used. 7474 7475Unless an alternative @code{tdb} is provided, the storage format is a textual format 7476consisting of a line for each host with fields separated by '|'. The contents of 7477the fields are a format-identifier which is set to 'g0', the hostname that the 7478rest of the data applies to, the numeric port or host name, the expiration 7479time in seconds since the epoch (0 for no expiration), and a base64 7480encoding of the raw (DER) public key information (SPKI) of the peer. 7481 7482As of GnuTLS 3.6.6 this function also accepts raw public keys. 7483 7484@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7485negative error value. 7486 7487@strong{Since:} 3.0.13 7488@end deftypefun 7489 7490@subheading gnutls_strerror 7491@anchor{gnutls_strerror} 7492@deftypefun {const char *} {gnutls_strerror} (int @var{error}) 7493@var{error}: is a GnuTLS error code, a negative error code 7494 7495This function is similar to strerror. The difference is that it 7496accepts an error number returned by a gnutls function; In case of 7497an unknown error a descriptive string is sent instead of @code{NULL} . 7498 7499Error codes are always a negative error code. 7500 7501@strong{Returns:} A string explaining the GnuTLS error message. 7502@end deftypefun 7503 7504@subheading gnutls_strerror_name 7505@anchor{gnutls_strerror_name} 7506@deftypefun {const char *} {gnutls_strerror_name} (int @var{error}) 7507@var{error}: is an error returned by a gnutls function. 7508 7509Return the GnuTLS error code define as a string. For example, 7510gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return 7511the string "GNUTLS_E_DH_PRIME_UNACCEPTABLE". 7512 7513@strong{Returns:} A string corresponding to the symbol name of the error 7514code. 7515 7516@strong{Since:} 2.6.0 7517@end deftypefun 7518 7519@subheading gnutls_supplemental_get_name 7520@anchor{gnutls_supplemental_get_name} 7521@deftypefun {const char *} {gnutls_supplemental_get_name} (gnutls_supplemental_data_format_type_t @var{type}) 7522@var{type}: is a supplemental data format type 7523 7524Convert a @code{gnutls_supplemental_data_format_type_t} value to a 7525string. 7526 7527@strong{Returns:} a string that contains the name of the specified 7528supplemental data format type, or @code{NULL} for unknown types. 7529@end deftypefun 7530 7531@subheading gnutls_supplemental_recv 7532@anchor{gnutls_supplemental_recv} 7533@deftypefun {void} {gnutls_supplemental_recv} (gnutls_session_t @var{session}, unsigned @var{do_recv_supplemental}) 7534@var{session}: is a @code{gnutls_session_t} type. 7535 7536@var{do_recv_supplemental}: non-zero in order to expect supplemental data 7537 7538This function is to be called by an extension handler to 7539instruct gnutls to attempt to receive supplemental data 7540during the handshake process. 7541 7542@strong{Since:} 3.4.0 7543@end deftypefun 7544 7545@subheading gnutls_supplemental_register 7546@anchor{gnutls_supplemental_register} 7547@deftypefun {int} {gnutls_supplemental_register} (const char * @var{name}, gnutls_supplemental_data_format_type_t @var{type}, gnutls_supp_recv_func @var{recv_func}, gnutls_supp_send_func @var{send_func}) 7548@var{name}: the name of the supplemental data to register 7549 7550@var{type}: the type of the supplemental data format 7551 7552@var{recv_func}: the function to receive the data 7553 7554@var{send_func}: the function to send the data 7555 7556This function will register a new supplemental data type (rfc4680). 7557The registered data will remain until @code{gnutls_global_deinit()} 7558is called. The provided @code{type} must be an unassigned type in 7559@code{gnutls_supplemental_data_format_type_t} . If the type is already 7560registered or handled by GnuTLS internally @code{GNUTLS_E_ALREADY_REGISTERED} 7561will be returned. 7562 7563This function is not thread safe. As supplemental data are not defined under 7564TLS 1.3, this function will disable TLS 1.3 support globally. 7565 7566@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 7567 7568@strong{Since:} 3.4.0 7569@end deftypefun 7570 7571@subheading gnutls_supplemental_send 7572@anchor{gnutls_supplemental_send} 7573@deftypefun {void} {gnutls_supplemental_send} (gnutls_session_t @var{session}, unsigned @var{do_send_supplemental}) 7574@var{session}: is a @code{gnutls_session_t} type. 7575 7576@var{do_send_supplemental}: non-zero in order to send supplemental data 7577 7578This function is to be called by an extension handler to 7579instruct gnutls to send supplemental data during the handshake process. 7580 7581@strong{Since:} 3.4.0 7582@end deftypefun 7583 7584@subheading gnutls_system_recv_timeout 7585@anchor{gnutls_system_recv_timeout} 7586@deftypefun {int} {gnutls_system_recv_timeout} (gnutls_transport_ptr_t @var{ptr}, unsigned int @var{ms}) 7587@var{ptr}: A file descriptor (wrapped in a gnutls_transport_ptr_t pointer) 7588 7589@var{ms}: The number of milliseconds to wait. 7590 7591Wait for data to be received from the provided socket ( @code{ptr} ) within a 7592timeout period in milliseconds, using @code{select()} on the provided @code{ptr} . 7593 7594This function is provided as a helper for constructing custom 7595callbacks for @code{gnutls_transport_set_pull_timeout_function()} , 7596which can be used if you rely on socket file descriptors. 7597 7598Returns -1 on error, 0 on timeout, positive value if data are available for reading. 7599 7600@strong{Since:} 3.4.0 7601@end deftypefun 7602 7603@subheading gnutls_tdb_deinit 7604@anchor{gnutls_tdb_deinit} 7605@deftypefun {void} {gnutls_tdb_deinit} (gnutls_tdb_t @var{tdb}) 7606@var{tdb}: The structure to be deinitialized 7607 7608This function will deinitialize a public key trust storage structure. 7609@end deftypefun 7610 7611@subheading gnutls_tdb_init 7612@anchor{gnutls_tdb_init} 7613@deftypefun {int} {gnutls_tdb_init} (gnutls_tdb_t * @var{tdb}) 7614@var{tdb}: A pointer to the type to be initialized 7615 7616This function will initialize a public key trust storage structure. 7617 7618@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7619negative error value. 7620@end deftypefun 7621 7622@subheading gnutls_tdb_set_store_commitment_func 7623@anchor{gnutls_tdb_set_store_commitment_func} 7624@deftypefun {void} {gnutls_tdb_set_store_commitment_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_store_commitment_func @var{cstore}) 7625@var{tdb}: The trust storage 7626 7627@var{cstore}: The commitment storage function 7628 7629This function will associate a commitment (hash) storage function with the 7630trust storage structure. The function is of the following form. 7631 7632int gnutls_tdb_store_commitment_func(const char* db_name, const char* host, 7633const char* service, time_t expiration, 7634gnutls_digest_algorithm_t, const gnutls_datum_t* hash); 7635 7636The @code{db_name} should be used to pass any private data to this function. 7637@end deftypefun 7638 7639@subheading gnutls_tdb_set_store_func 7640@anchor{gnutls_tdb_set_store_func} 7641@deftypefun {void} {gnutls_tdb_set_store_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_store_func @var{store}) 7642@var{tdb}: The trust storage 7643 7644@var{store}: The storage function 7645 7646This function will associate a storage function with the 7647trust storage structure. The function is of the following form. 7648 7649int gnutls_tdb_store_func(const char* db_name, const char* host, 7650const char* service, time_t expiration, 7651const gnutls_datum_t* pubkey); 7652 7653The @code{db_name} should be used to pass any private data to this function. 7654@end deftypefun 7655 7656@subheading gnutls_tdb_set_verify_func 7657@anchor{gnutls_tdb_set_verify_func} 7658@deftypefun {void} {gnutls_tdb_set_verify_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_verify_func @var{verify}) 7659@var{tdb}: The trust storage 7660 7661@var{verify}: The verification function 7662 7663This function will associate a retrieval function with the 7664trust storage structure. The function is of the following form. 7665 7666int gnutls_tdb_verify_func(const char* db_name, const char* host, 7667const char* service, const gnutls_datum_t* pubkey); 7668 7669The verify function should return zero on a match, @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} 7670if there is a mismatch and any other negative error code otherwise. 7671 7672The @code{db_name} should be used to pass any private data to this function. 7673@end deftypefun 7674 7675@subheading gnutls_transport_get_int 7676@anchor{gnutls_transport_get_int} 7677@deftypefun {int} {gnutls_transport_get_int} (gnutls_session_t @var{session}) 7678@var{session}: is a @code{gnutls_session_t} type. 7679 7680Used to get the first argument of the transport function (like 7681PUSH and PULL). This must have been set using 7682@code{gnutls_transport_set_int()} . 7683 7684@strong{Returns:} The first argument of the transport function. 7685 7686@strong{Since:} 3.1.9 7687@end deftypefun 7688 7689@subheading gnutls_transport_get_int2 7690@anchor{gnutls_transport_get_int2} 7691@deftypefun {void} {gnutls_transport_get_int2} (gnutls_session_t @var{session}, int * @var{recv_int}, int * @var{send_int}) 7692@var{session}: is a @code{gnutls_session_t} type. 7693 7694@var{recv_int}: will hold the value for the pull function 7695 7696@var{send_int}: will hold the value for the push function 7697 7698Used to get the arguments of the transport functions (like PUSH 7699and PULL). These should have been set using 7700@code{gnutls_transport_set_int2()} . 7701 7702@strong{Since:} 3.1.9 7703@end deftypefun 7704 7705@subheading gnutls_transport_get_ptr 7706@anchor{gnutls_transport_get_ptr} 7707@deftypefun {gnutls_transport_ptr_t} {gnutls_transport_get_ptr} (gnutls_session_t @var{session}) 7708@var{session}: is a @code{gnutls_session_t} type. 7709 7710Used to get the first argument of the transport function (like 7711PUSH and PULL). This must have been set using 7712@code{gnutls_transport_set_ptr()} . 7713 7714@strong{Returns:} The first argument of the transport function. 7715@end deftypefun 7716 7717@subheading gnutls_transport_get_ptr2 7718@anchor{gnutls_transport_get_ptr2} 7719@deftypefun {void} {gnutls_transport_get_ptr2} (gnutls_session_t @var{session}, gnutls_transport_ptr_t * @var{recv_ptr}, gnutls_transport_ptr_t * @var{send_ptr}) 7720@var{session}: is a @code{gnutls_session_t} type. 7721 7722@var{recv_ptr}: will hold the value for the pull function 7723 7724@var{send_ptr}: will hold the value for the push function 7725 7726Used to get the arguments of the transport functions (like PUSH 7727and PULL). These should have been set using 7728@code{gnutls_transport_set_ptr2()} . 7729@end deftypefun 7730 7731@subheading gnutls_transport_set_errno 7732@anchor{gnutls_transport_set_errno} 7733@deftypefun {void} {gnutls_transport_set_errno} (gnutls_session_t @var{session}, int @var{err}) 7734@var{session}: is a @code{gnutls_session_t} type. 7735 7736@var{err}: error value to store in session-specific errno variable. 7737 7738Store @code{err} in the session-specific errno variable. Useful values 7739for @code{err} are EINTR, EAGAIN and EMSGSIZE, other values are treated will be 7740treated as real errors in the push/pull function. 7741 7742This function is useful in replacement push and pull functions set by 7743@code{gnutls_transport_set_push_function()} and 7744@code{gnutls_transport_set_pull_function()} under Windows, where the 7745replacements may not have access to the same @code{errno} variable that is used by GnuTLS (e.g., the application is linked to 7746msvcr71.dll and gnutls is linked to msvcrt.dll). 7747 7748This function is unreliable if you are using the same 7749 @code{session} in different threads for sending and receiving. 7750@end deftypefun 7751 7752@subheading gnutls_transport_set_errno_function 7753@anchor{gnutls_transport_set_errno_function} 7754@deftypefun {void} {gnutls_transport_set_errno_function} (gnutls_session_t @var{session}, gnutls_errno_func @var{errno_func}) 7755@var{session}: is a @code{gnutls_session_t} type. 7756 7757@var{errno_func}: a callback function similar to @code{write()} 7758 7759This is the function where you set a function to retrieve errno 7760after a failed push or pull operation. 7761 7762 @code{errno_func} is of the form, 7763int (*gnutls_errno_func)(gnutls_transport_ptr_t); 7764and should return the errno. 7765 7766@strong{Since:} 2.12.0 7767@end deftypefun 7768 7769@subheading gnutls_transport_set_int 7770@anchor{gnutls_transport_set_int} 7771@deftypefun {void} {gnutls_transport_set_int} (gnutls_session_t @var{session}, int @var{fd}) 7772@var{session}: is a @code{gnutls_session_t} type. 7773 7774@var{fd}: is the socket descriptor for the connection. 7775 7776This function sets the first argument of the transport function, such 7777as @code{send()} and @code{recv()} for the default callbacks using the 7778system's socket API. 7779 7780This function is equivalent to calling @code{gnutls_transport_set_ptr()} 7781with the descriptor, but requires no casts. 7782 7783@strong{Since:} 3.1.9 7784@end deftypefun 7785 7786@subheading gnutls_transport_set_int2 7787@anchor{gnutls_transport_set_int2} 7788@deftypefun {void} {gnutls_transport_set_int2} (gnutls_session_t @var{session}, int @var{recv_fd}, int @var{send_fd}) 7789@var{session}: is a @code{gnutls_session_t} type. 7790 7791@var{recv_fd}: is socket descriptor for the pull function 7792 7793@var{send_fd}: is socket descriptor for the push function 7794 7795This function sets the first argument of the transport functions, 7796such as @code{send()} and @code{recv()} for the default callbacks using the 7797system's socket API. With this function you can set two different 7798descriptors for receiving and sending. 7799 7800This function is equivalent to calling @code{gnutls_transport_set_ptr2()} 7801with the descriptors, but requires no casts. 7802 7803@strong{Since:} 3.1.9 7804@end deftypefun 7805 7806@subheading gnutls_transport_set_ptr 7807@anchor{gnutls_transport_set_ptr} 7808@deftypefun {void} {gnutls_transport_set_ptr} (gnutls_session_t @var{session}, gnutls_transport_ptr_t @var{ptr}) 7809@var{session}: is a @code{gnutls_session_t} type. 7810 7811@var{ptr}: is the value. 7812 7813Used to set the first argument of the transport function (for push 7814and pull callbacks). In berkeley style sockets this function will set the 7815connection descriptor. 7816@end deftypefun 7817 7818@subheading gnutls_transport_set_ptr2 7819@anchor{gnutls_transport_set_ptr2} 7820@deftypefun {void} {gnutls_transport_set_ptr2} (gnutls_session_t @var{session}, gnutls_transport_ptr_t @var{recv_ptr}, gnutls_transport_ptr_t @var{send_ptr}) 7821@var{session}: is a @code{gnutls_session_t} type. 7822 7823@var{recv_ptr}: is the value for the pull function 7824 7825@var{send_ptr}: is the value for the push function 7826 7827Used to set the first argument of the transport function (for push 7828and pull callbacks). In berkeley style sockets this function will set the 7829connection descriptor. With this function you can use two different 7830pointers for receiving and sending. 7831@end deftypefun 7832 7833@subheading gnutls_transport_set_pull_function 7834@anchor{gnutls_transport_set_pull_function} 7835@deftypefun {void} {gnutls_transport_set_pull_function} (gnutls_session_t @var{session}, gnutls_pull_func @var{pull_func}) 7836@var{session}: is a @code{gnutls_session_t} type. 7837 7838@var{pull_func}: a callback function similar to @code{read()} 7839 7840This is the function where you set a function for gnutls to receive 7841data. Normally, if you use berkeley style sockets, do not need to 7842use this function since the default recv(2) will probably be ok. 7843The callback should return 0 on connection termination, a positive 7844number indicating the number of bytes received, and -1 on error. 7845 7846 @code{gnutls_pull_func} is of the form, 7847ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t); 7848@end deftypefun 7849 7850@subheading gnutls_transport_set_pull_timeout_function 7851@anchor{gnutls_transport_set_pull_timeout_function} 7852@deftypefun {void} {gnutls_transport_set_pull_timeout_function} (gnutls_session_t @var{session}, gnutls_pull_timeout_func @var{func}) 7853@var{session}: is a @code{gnutls_session_t} type. 7854 7855@var{func}: a callback function 7856 7857This is the function where you set a function for gnutls to know 7858whether data are ready to be received. It should wait for data a 7859given time frame in milliseconds. The callback should return 0 on 7860timeout, a positive number if data can be received, and -1 on error. 7861You'll need to override this function if @code{select()} is not suitable 7862for the provided transport calls. 7863 7864As with @code{select()} , if the timeout value is zero the callback should return 7865zero if no data are immediately available. The special value 7866@code{GNUTLS_INDEFINITE_TIMEOUT} indicates that the callback should wait indefinitely 7867for data. 7868 7869 @code{gnutls_pull_timeout_func} is of the form, 7870int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms); 7871 7872This callback is necessary when @code{gnutls_handshake_set_timeout()} or 7873@code{gnutls_record_set_timeout()} are set, under TLS1.3 and for enforcing the DTLS 7874mode timeouts when in blocking mode. 7875 7876For compatibility with future GnuTLS versions this callback must be set when 7877a custom pull function is registered. The callback will not be used when the 7878session is in TLS mode with non-blocking sockets. That is, when @code{GNUTLS_NONBLOCK} 7879is specified for a TLS session in @code{gnutls_init()} . 7880 7881The helper function @code{gnutls_system_recv_timeout()} is provided to 7882simplify writing callbacks. 7883 7884@strong{Since:} 3.0 7885@end deftypefun 7886 7887@subheading gnutls_transport_set_push_function 7888@anchor{gnutls_transport_set_push_function} 7889@deftypefun {void} {gnutls_transport_set_push_function} (gnutls_session_t @var{session}, gnutls_push_func @var{push_func}) 7890@var{session}: is a @code{gnutls_session_t} type. 7891 7892@var{push_func}: a callback function similar to @code{write()} 7893 7894This is the function where you set a push function for gnutls to 7895use in order to send data. If you are going to use berkeley style 7896sockets, you do not need to use this function since the default 7897send(2) will probably be ok. Otherwise you should specify this 7898function for gnutls to be able to send data. 7899The callback should return a positive number indicating the 7900bytes sent, and -1 on error. 7901 7902 @code{push_func} is of the form, 7903ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t); 7904@end deftypefun 7905 7906@subheading gnutls_transport_set_vec_push_function 7907@anchor{gnutls_transport_set_vec_push_function} 7908@deftypefun {void} {gnutls_transport_set_vec_push_function} (gnutls_session_t @var{session}, gnutls_vec_push_func @var{vec_func}) 7909@var{session}: is a @code{gnutls_session_t} type. 7910 7911@var{vec_func}: a callback function similar to @code{writev()} 7912 7913Using this function you can override the default writev(2) 7914function for gnutls to send data. Setting this callback 7915instead of @code{gnutls_transport_set_push_function()} is recommended 7916since it introduces less overhead in the TLS handshake process. 7917 7918 @code{vec_func} is of the form, 7919ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt); 7920 7921@strong{Since:} 2.12.0 7922@end deftypefun 7923 7924@subheading gnutls_url_is_supported 7925@anchor{gnutls_url_is_supported} 7926@deftypefun {unsigned} {gnutls_url_is_supported} (const char * @var{url}) 7927@var{url}: A URI to be tested 7928 7929Check whether the provided @code{url} is supported. Depending on the system libraries 7930GnuTLS may support pkcs11, tpmkey or other URLs. 7931 7932@strong{Returns:} return non-zero if the given URL is supported, and zero if 7933it is not known. 7934 7935@strong{Since:} 3.1.0 7936@end deftypefun 7937 7938@subheading gnutls_utf8_password_normalize 7939@anchor{gnutls_utf8_password_normalize} 7940@deftypefun {int} {gnutls_utf8_password_normalize} (const unsigned char * @var{password}, unsigned @var{plen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) 7941@var{password}: contain the UTF-8 formatted password 7942 7943@var{plen}: the length of the provided password 7944 7945@var{out}: the result in an null-terminated allocated string 7946 7947@var{flags}: should be zero 7948 7949This function will convert the provided UTF-8 password according 7950to the normalization rules in RFC7613. 7951 7952If the flag @code{GNUTLS_UTF8_IGNORE_ERRS} is specified, any UTF-8 encoding 7953errors will be ignored, and in that case the output will be a copy of the input. 7954 7955@strong{Returns:} @code{GNUTLS_E_INVALID_UTF8_STRING} on invalid UTF-8 data, or 0 on success. 7956 7957@strong{Since:} 3.5.7 7958@end deftypefun 7959 7960@subheading gnutls_verify_stored_pubkey 7961@anchor{gnutls_verify_stored_pubkey} 7962@deftypefun {int} {gnutls_verify_stored_pubkey} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_certificate_type_t @var{cert_type}, const gnutls_datum_t * @var{cert}, unsigned int @var{flags}) 7963@var{db_name}: A file specifying the stored keys (use NULL for the default) 7964 7965@var{tdb}: A storage structure or NULL to use the default 7966 7967@var{host}: The peer's name 7968 7969@var{service}: non-NULL if this key is specific to a service (e.g. http) 7970 7971@var{cert_type}: The type of the certificate 7972 7973@var{cert}: The raw (der) data of the certificate 7974 7975@var{flags}: should be 0. 7976 7977This function will try to verify a raw public-key or a public-key provided via 7978a raw (DER-encoded) certificate using a list of stored public keys. 7979The @code{service} field if non-NULL should be a port number. 7980 7981The @code{db_name} variable if non-null specifies a custom backend for 7982the retrieval of entries. If it is NULL then the 7983default file backend will be used. In POSIX-like systems the 7984file backend uses the $HOME/.gnutls/known_hosts file. 7985 7986Note that if the custom storage backend is provided the 7987retrieval function should return @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} 7988if the host/service pair is found but key doesn't match, 7989@code{GNUTLS_E_NO_CERTIFICATE_FOUND} if no such host/service with 7990the given key is found, and 0 if it was found. The storage 7991function should return 0 on success. 7992 7993As of GnuTLS 3.6.6 this function also verifies raw public keys. 7994 7995@strong{Returns:} If no associated public key is found 7996then @code{GNUTLS_E_NO_CERTIFICATE_FOUND} will be returned. If a key 7997is found but does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} 7998is returned. On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7999or a negative error value on other errors. 8000 8001@strong{Since:} 3.0.13 8002@end deftypefun 8003 8004