1 2@subheading gnutls_certificate_get_trust_list 3@anchor{gnutls_certificate_get_trust_list} 4@deftypefun {void} {gnutls_certificate_get_trust_list} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_trust_list_t * @var{tlist}) 5@var{res}: is a @code{gnutls_certificate_credentials_t} type. 6 7@var{tlist}: Location where to store the trust list. 8 9Obtains the list of trusted certificates stored in @code{res} and writes a 10pointer to it to the location @code{tlist} . The pointer will point to memory 11internal to @code{res} , and must not be deinitialized. It will be automatically 12deallocated when the @code{res} structure is deinitialized. 13 14@strong{Since:} 3.4.0 15@end deftypefun 16 17@subheading gnutls_certificate_set_trust_list 18@anchor{gnutls_certificate_set_trust_list} 19@deftypefun {void} {gnutls_certificate_set_trust_list} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_trust_list_t @var{tlist}, unsigned @var{flags}) 20@var{res}: is a @code{gnutls_certificate_credentials_t} type. 21 22@var{tlist}: is a @code{gnutls_x509_trust_list_t} type 23 24@var{flags}: must be zero 25 26This function sets a trust list in the gnutls_certificate_credentials_t type. 27 28Note that the @code{tlist} will become part of the credentials 29structure and must not be deallocated. It will be automatically deallocated 30when the @code{res} structure is deinitialized. 31 32@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code. 33 34@strong{Since:} 3.2.2 35@end deftypefun 36 37@subheading gnutls_certificate_verification_profile_get_id 38@anchor{gnutls_certificate_verification_profile_get_id} 39@deftypefun {gnutls_certificate_verification_profiles_t} {gnutls_certificate_verification_profile_get_id} (const char * @var{name}) 40@var{name}: is a profile name 41 42Convert a string to a @code{gnutls_certificate_verification_profiles_t} value. The names are 43compared in a case insensitive way. 44 45@strong{Returns:} a @code{gnutls_certificate_verification_profiles_t} id of the specified profile, 46or @code{GNUTLS_PROFILE_UNKNOWN} on failure. 47@end deftypefun 48 49@subheading gnutls_certificate_verification_profile_get_name 50@anchor{gnutls_certificate_verification_profile_get_name} 51@deftypefun {const char *} {gnutls_certificate_verification_profile_get_name} (gnutls_certificate_verification_profiles_t @var{id}) 52@var{id}: is a profile ID 53 54Convert a @code{gnutls_certificate_verification_profiles_t} value to a string. 55 56@strong{Returns:} a string that contains the name of the specified profile or @code{NULL} . 57@end deftypefun 58 59@subheading gnutls_pkcs8_info 60@anchor{gnutls_pkcs8_info} 61@deftypefun {int} {gnutls_pkcs8_info} (const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int * @var{schema}, unsigned int * @var{cipher}, void * @var{salt}, unsigned int * @var{salt_size}, unsigned int * @var{iter_count}, char ** @var{oid}) 62@var{data}: Holds the PKCS @code{8} data 63 64@var{format}: the format of the PKCS @code{8} data 65 66@var{schema}: indicate the schema as one of @code{gnutls_pkcs_encrypt_flags_t} 67 68@var{cipher}: the cipher used as @code{gnutls_cipher_algorithm_t} 69 70@var{salt}: PBKDF2 salt (if non-NULL then @code{salt_size} initially holds its size) 71 72@var{salt_size}: PBKDF2 salt size 73 74@var{iter_count}: PBKDF2 iteration count 75 76@var{oid}: if non-NULL it will contain an allocated null-terminated variable with the OID 77 78This function will provide information on the algorithms used 79in a particular PKCS @code{8} structure. If the structure algorithms 80are unknown the code @code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} will be returned, 81and only @code{oid} , will be set. That is, @code{oid} will be set on encrypted PKCS @code{8} 82structures whether supported or not. It must be deinitialized using @code{gnutls_free()} . 83The other variables are only set on supported structures. 84 85@strong{Returns:} @code{GNUTLS_E_INVALID_REQUEST} if the provided structure isn't an encrypted key, 86@code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} if the structure's encryption isn't supported, or 87another negative error code in case of a failure. Zero on success. 88 89@strong{Since:} 3.4.0 90@end deftypefun 91 92@subheading gnutls_pkcs_schema_get_name 93@anchor{gnutls_pkcs_schema_get_name} 94@deftypefun {const char *} {gnutls_pkcs_schema_get_name} (unsigned int @var{schema}) 95@var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} ) 96 97This function will return a human readable description of the 98PKCS12 or PBES2 schema. 99 100@strong{Returns:} a constraint string or @code{NULL} on error. 101 102@strong{Since:} 3.4.0 103@end deftypefun 104 105@subheading gnutls_pkcs_schema_get_oid 106@anchor{gnutls_pkcs_schema_get_oid} 107@deftypefun {const char *} {gnutls_pkcs_schema_get_oid} (unsigned int @var{schema}) 108@var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} ) 109 110This function will return the object identifier of the 111PKCS12 or PBES2 schema. 112 113@strong{Returns:} a constraint string or @code{NULL} on error. 114 115@strong{Since:} 3.4.0 116@end deftypefun 117 118@subheading gnutls_subject_alt_names_deinit 119@anchor{gnutls_subject_alt_names_deinit} 120@deftypefun {void} {gnutls_subject_alt_names_deinit} (gnutls_subject_alt_names_t @var{sans}) 121@var{sans}: The alternative names 122 123This function will deinitialize an alternative names structure. 124 125@strong{Since:} 3.3.0 126@end deftypefun 127 128@subheading gnutls_subject_alt_names_get 129@anchor{gnutls_subject_alt_names_get} 130@deftypefun {int} {gnutls_subject_alt_names_get} (gnutls_subject_alt_names_t @var{sans}, unsigned int @var{seq}, unsigned int * @var{san_type}, gnutls_datum_t * @var{san}, gnutls_datum_t * @var{othername_oid}) 131@var{sans}: The alternative names 132 133@var{seq}: The index of the name to get 134 135@var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} ) 136 137@var{san}: The alternative name data (should be treated as constant) 138 139@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} (should be treated as constant) 140 141This function will return a specific alternative name as stored in 142the @code{sans} type. The returned values should be treated as constant 143and valid for the lifetime of @code{sans} . 144 145@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 146if the index is out of bounds, otherwise a negative error value. 147 148@strong{Since:} 3.3.0 149@end deftypefun 150 151@subheading gnutls_subject_alt_names_init 152@anchor{gnutls_subject_alt_names_init} 153@deftypefun {int} {gnutls_subject_alt_names_init} (gnutls_subject_alt_names_t * @var{sans}) 154@var{sans}: The alternative names 155 156This function will initialize an alternative names structure. 157 158@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 159 160@strong{Since:} 3.3.0 161@end deftypefun 162 163@subheading gnutls_subject_alt_names_set 164@anchor{gnutls_subject_alt_names_set} 165@deftypefun {int} {gnutls_subject_alt_names_set} (gnutls_subject_alt_names_t @var{sans}, unsigned int @var{san_type}, const gnutls_datum_t * @var{san}, const char * @var{othername_oid}) 166@var{sans}: The alternative names 167 168@var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) 169 170@var{san}: The alternative name data 171 172@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} 173 174This function will store the specified alternative name in 175the @code{sans} . 176 177Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and 178@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. 179 180@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. 181 182@strong{Since:} 3.3.0 183@end deftypefun 184 185@subheading gnutls_x509_aia_deinit 186@anchor{gnutls_x509_aia_deinit} 187@deftypefun {void} {gnutls_x509_aia_deinit} (gnutls_x509_aia_t @var{aia}) 188@var{aia}: The authority info access 189 190This function will deinitialize an authority info access type. 191 192@strong{Since:} 3.3.0 193@end deftypefun 194 195@subheading gnutls_x509_aia_get 196@anchor{gnutls_x509_aia_get} 197@deftypefun {int} {gnutls_x509_aia_get} (gnutls_x509_aia_t @var{aia}, unsigned int @var{seq}, gnutls_datum_t * @var{oid}, unsigned * @var{san_type}, gnutls_datum_t * @var{san}) 198@var{aia}: The authority info access 199 200@var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.) 201 202@var{oid}: the type of available data; to be treated as constant. 203 204@var{san_type}: Will hold the type of the name of @code{gnutls_subject_alt_names_t} (may be null). 205 206@var{san}: the access location name; to be treated as constant (may be null). 207 208This function reads from the Authority Information Access type. 209 210The @code{seq} input parameter is used to indicate which member of the 211sequence the caller is interested in. The first member is 0, the 212second member 1 and so on. When the @code{seq} value is out of bounds, 213@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 214 215Typically @code{oid} is @code{GNUTLS_OID_AD_CAISSUERS} or @code{GNUTLS_OID_AD_OCSP} . 216 217@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 218 219@strong{Since:} 3.3.0 220@end deftypefun 221 222@subheading gnutls_x509_aia_init 223@anchor{gnutls_x509_aia_init} 224@deftypefun {int} {gnutls_x509_aia_init} (gnutls_x509_aia_t * @var{aia}) 225@var{aia}: The authority info access 226 227This function will initialize an authority info access type. 228 229@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 230 231@strong{Since:} 3.3.0 232@end deftypefun 233 234@subheading gnutls_x509_aia_set 235@anchor{gnutls_x509_aia_set} 236@deftypefun {int} {gnutls_x509_aia_set} (gnutls_x509_aia_t @var{aia}, const char * @var{oid}, unsigned @var{san_type}, const gnutls_datum_t * @var{san}) 237@var{aia}: The authority info access 238 239@var{oid}: the type of data. 240 241@var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) 242 243@var{san}: The alternative name data 244 245This function will store the specified alternative name in 246the @code{aia} type. 247 248Typically the value for @code{oid} should be @code{GNUTLS_OID_AD_OCSP} , or 249@code{GNUTLS_OID_AD_CAISSUERS} . 250 251Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , and @code{GNUTLS_SAN_DNSNAME} , 252are converted to ACE format when necessary. 253 254@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. 255 256@strong{Since:} 3.3.0 257@end deftypefun 258 259@subheading gnutls_x509_aki_deinit 260@anchor{gnutls_x509_aki_deinit} 261@deftypefun {void} {gnutls_x509_aki_deinit} (gnutls_x509_aki_t @var{aki}) 262@var{aki}: The authority key identifier type 263 264This function will deinitialize an authority key identifier. 265 266@strong{Since:} 3.3.0 267@end deftypefun 268 269@subheading gnutls_x509_aki_get_cert_issuer 270@anchor{gnutls_x509_aki_get_cert_issuer} 271@deftypefun {int} {gnutls_x509_aki_get_cert_issuer} (gnutls_x509_aki_t @var{aki}, unsigned int @var{seq}, unsigned int * @var{san_type}, gnutls_datum_t * @var{san}, gnutls_datum_t * @var{othername_oid}, gnutls_datum_t * @var{serial}) 272@var{aki}: The authority key ID 273 274@var{seq}: The index of the name to get 275 276@var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} ) 277 278@var{san}: The alternative name data 279 280@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} 281 282@var{serial}: The authorityCertSerialNumber number 283 284This function will return a specific authorityCertIssuer name as stored in 285the @code{aki} type, as well as the authorityCertSerialNumber. All the returned 286values should be treated as constant, and may be set to @code{NULL} when are not required. 287 288@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 289if the index is out of bounds, otherwise a negative error value. 290 291@strong{Since:} 3.3.0 292@end deftypefun 293 294@subheading gnutls_x509_aki_get_id 295@anchor{gnutls_x509_aki_get_id} 296@deftypefun {int} {gnutls_x509_aki_get_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{id}) 297@var{aki}: The authority key ID 298 299@var{id}: Will hold the identifier 300 301This function will return the key identifier as stored in 302the @code{aki} type. The identifier should be treated as constant. 303 304@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 305if the index is out of bounds, otherwise a negative error value. 306 307@strong{Since:} 3.3.0 308@end deftypefun 309 310@subheading gnutls_x509_aki_init 311@anchor{gnutls_x509_aki_init} 312@deftypefun {int} {gnutls_x509_aki_init} (gnutls_x509_aki_t * @var{aki}) 313@var{aki}: The authority key ID type 314 315This function will initialize an authority key ID. 316 317@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 318 319@strong{Since:} 3.3.0 320@end deftypefun 321 322@subheading gnutls_x509_aki_set_cert_issuer 323@anchor{gnutls_x509_aki_set_cert_issuer} 324@deftypefun {int} {gnutls_x509_aki_set_cert_issuer} (gnutls_x509_aki_t @var{aki}, unsigned int @var{san_type}, const gnutls_datum_t * @var{san}, const char * @var{othername_oid}, const gnutls_datum_t * @var{serial}) 325@var{aki}: The authority key ID 326 327@var{san_type}: the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null 328 329@var{san}: The alternative name data 330 331@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} 332 333@var{serial}: The authorityCertSerialNumber number (may be null) 334 335This function will set the authorityCertIssuer name and the authorityCertSerialNumber 336to be stored in the @code{aki} type. When storing multiple names, the serial 337should be set on the first call, and subsequent calls should use a @code{NULL} serial. 338 339Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and 340@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. 341 342@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 343 344@strong{Since:} 3.3.0 345@end deftypefun 346 347@subheading gnutls_x509_aki_set_id 348@anchor{gnutls_x509_aki_set_id} 349@deftypefun {int} {gnutls_x509_aki_set_id} (gnutls_x509_aki_t @var{aki}, const gnutls_datum_t * @var{id}) 350@var{aki}: The authority key ID 351 352@var{id}: the key identifier 353 354This function will set the keyIdentifier to be stored in the @code{aki} type. 355 356@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 357 358@strong{Since:} 3.3.0 359@end deftypefun 360 361@subheading gnutls_x509_cidr_to_rfc5280 362@anchor{gnutls_x509_cidr_to_rfc5280} 363@deftypefun {int} {gnutls_x509_cidr_to_rfc5280} (const char * @var{cidr}, gnutls_datum_t * @var{cidr_rfc5280}) 364@var{cidr}: CIDR in RFC4632 format (IP/prefix), null-terminated 365 366@var{cidr_rfc5280}: CIDR range converted to RFC5280 format 367 368This function will convert text CIDR range with prefix (such as '10.0.0.0/8') 369to RFC5280 (IP address in network byte order followed by its network mask). 370Works for both IPv4 and IPv6. 371 372The resulting object is directly usable for IP name constraints usage, 373for example in functions @code{gnutls_x509_name_constraints_add_permitted} 374or @code{gnutls_x509_name_constraints_add_excluded} . 375 376The data in datum needs to be deallocated using @code{gnutls_free()} . 377 378@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 379 380@strong{Since:} 3.5.4 381@end deftypefun 382 383@subheading gnutls_x509_crl_check_issuer 384@anchor{gnutls_x509_crl_check_issuer} 385@deftypefun {unsigned} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}) 386@var{crl}: is the CRL to be checked 387 388@var{issuer}: is the certificate of a possible issuer 389 390This function will check if the given CRL was issued by the given 391issuer certificate. 392 393@strong{Returns:} true (1) if the given CRL was issued by the given issuer, 394and false (0) if not. 395@end deftypefun 396 397@subheading gnutls_x509_crl_deinit 398@anchor{gnutls_x509_crl_deinit} 399@deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl}) 400@var{crl}: The data to be deinitialized 401 402This function will deinitialize a CRL structure. 403@end deftypefun 404 405@subheading gnutls_x509_crl_dist_points_deinit 406@anchor{gnutls_x509_crl_dist_points_deinit} 407@deftypefun {void} {gnutls_x509_crl_dist_points_deinit} (gnutls_x509_crl_dist_points_t @var{cdp}) 408@var{cdp}: The CRL distribution points 409 410This function will deinitialize a CRL distribution points type. 411 412@strong{Since:} 3.3.0 413@end deftypefun 414 415@subheading gnutls_x509_crl_dist_points_get 416@anchor{gnutls_x509_crl_dist_points_get} 417@deftypefun {int} {gnutls_x509_crl_dist_points_get} (gnutls_x509_crl_dist_points_t @var{cdp}, unsigned int @var{seq}, unsigned int * @var{type}, gnutls_datum_t * @var{san}, unsigned int * @var{reasons}) 418@var{cdp}: The CRL distribution points 419 420@var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.) 421 422@var{type}: The name type of the corresponding name (gnutls_x509_subject_alt_name_t) 423 424@var{san}: The distribution point names (to be treated as constant) 425 426@var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . 427 428This function retrieves the individual CRL distribution points (2.5.29.31), 429contained in provided type. 430 431@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 432if the index is out of bounds, otherwise a negative error value. 433@end deftypefun 434 435@subheading gnutls_x509_crl_dist_points_init 436@anchor{gnutls_x509_crl_dist_points_init} 437@deftypefun {int} {gnutls_x509_crl_dist_points_init} (gnutls_x509_crl_dist_points_t * @var{cdp}) 438@var{cdp}: The CRL distribution points 439 440This function will initialize a CRL distribution points type. 441 442@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 443 444@strong{Since:} 3.3.0 445@end deftypefun 446 447@subheading gnutls_x509_crl_dist_points_set 448@anchor{gnutls_x509_crl_dist_points_set} 449@deftypefun {int} {gnutls_x509_crl_dist_points_set} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{san}, unsigned int @var{reasons}) 450@var{cdp}: The CRL distribution points 451 452@var{type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) 453 454@var{san}: The point name data 455 456@var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . 457 458This function will store the specified CRL distribution point value 459the @code{cdp} type. 460 461@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. 462 463@strong{Since:} 3.3.0 464@end deftypefun 465 466@subheading gnutls_x509_crl_export 467@anchor{gnutls_x509_crl_export} 468@deftypefun {int} {gnutls_x509_crl_export} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) 469@var{crl}: Holds the revocation list 470 471@var{format}: the format of output params. One of PEM or DER. 472 473@var{output_data}: will contain a private key PEM or DER encoded 474 475@var{output_data_size}: holds the size of output_data (and will 476be replaced by the actual size of parameters) 477 478This function will export the revocation list to DER or PEM format. 479 480If the buffer provided is not long enough to hold the output, then 481@code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned. 482 483If the structure is PEM encoded, it will have a header 484of "BEGIN X509 CRL". 485 486@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 487negative error value. 488@end deftypefun 489 490@subheading gnutls_x509_crl_export2 491@anchor{gnutls_x509_crl_export2} 492@deftypefun {int} {gnutls_x509_crl_export2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 493@var{crl}: Holds the revocation list 494 495@var{format}: the format of output params. One of PEM or DER. 496 497@var{out}: will contain a private key PEM or DER encoded 498 499This function will export the revocation list to DER or PEM format. 500 501The output buffer is allocated using @code{gnutls_malloc()} . 502 503If the structure is PEM encoded, it will have a header 504of "BEGIN X509 CRL". 505 506@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 507negative error value. 508 509Since 3.1.3 510@end deftypefun 511 512@subheading gnutls_x509_crl_get_authority_key_gn_serial 513@anchor{gnutls_x509_crl_get_authority_key_gn_serial} 514@deftypefun {int} {gnutls_x509_crl_get_authority_key_gn_serial} (gnutls_x509_crl_t @var{crl}, unsigned int @var{seq}, void * @var{alt}, size_t * @var{alt_size}, unsigned int * @var{alt_type}, void * @var{serial}, size_t * @var{serial_size}, unsigned int * @var{critical}) 515@var{crl}: should contain a @code{gnutls_x509_crl_t} type 516 517@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 518 519@var{alt}: is the place where the alternative name will be copied to 520 521@var{alt_size}: holds the size of alt. 522 523@var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). 524 525@var{serial}: buffer to store the serial number (may be null) 526 527@var{serial_size}: Holds the size of the serial field (may be null) 528 529@var{critical}: will be non-zero if the extension is marked as critical (may be null) 530 531This function will return the X.509 authority key 532identifier when stored as a general name (authorityCertIssuer) 533and serial number. 534 535Because more than one general names might be stored 536 @code{seq} can be used as a counter to request them all until 537@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 538 539@strong{Returns:} Returns 0 on success, or an error code. 540 541@strong{Since:} 3.0 542@end deftypefun 543 544@subheading gnutls_x509_crl_get_authority_key_id 545@anchor{gnutls_x509_crl_get_authority_key_id} 546@deftypefun {int} {gnutls_x509_crl_get_authority_key_id} (gnutls_x509_crl_t @var{crl}, void * @var{id}, size_t * @var{id_size}, unsigned int * @var{critical}) 547@var{crl}: should contain a @code{gnutls_x509_crl_t} type 548 549@var{id}: The place where the identifier will be copied 550 551@var{id_size}: Holds the size of the result field. 552 553@var{critical}: will be non-zero if the extension is marked as critical 554(may be null) 555 556This function will return the CRL authority's key identifier. This 557is obtained by the X.509 Authority Key identifier extension field 558(2.5.29.35). Note that this function 559only returns the keyIdentifier field of the extension and 560@code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains 561the name and serial number of the certificate. In that case 562@code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used. 563 564@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 565negative error code in case of an error. 566 567@strong{Since:} 2.8.0 568@end deftypefun 569 570@subheading gnutls_x509_crl_get_crt_count 571@anchor{gnutls_x509_crl_get_crt_count} 572@deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl}) 573@var{crl}: should contain a @code{gnutls_x509_crl_t} type 574 575This function will return the number of revoked certificates in the 576given CRL. 577 578@strong{Returns:} number of certificates, a negative error code on failure. 579@end deftypefun 580 581@subheading gnutls_x509_crl_get_crt_serial 582@anchor{gnutls_x509_crl_get_crt_serial} 583@deftypefun {int} {gnutls_x509_crl_get_crt_serial} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, unsigned char * @var{serial}, size_t * @var{serial_size}, time_t * @var{t}) 584@var{crl}: should contain a @code{gnutls_x509_crl_t} type 585 586@var{indx}: the index of the certificate to extract (starting from 0) 587 588@var{serial}: where the serial number will be copied 589 590@var{serial_size}: initially holds the size of serial 591 592@var{t}: if non null, will hold the time this certificate was revoked 593 594This function will retrieve the serial number of the specified, by 595the index, revoked certificate. 596 597Note that this function will have performance issues in large sequences 598of revoked certificates. In that case use @code{gnutls_x509_crl_iter_crt_serial()} . 599 600@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 601negative error value. 602@end deftypefun 603 604@subheading gnutls_x509_crl_get_dn_oid 605@anchor{gnutls_x509_crl_get_dn_oid} 606@deftypefun {int} {gnutls_x509_crl_get_dn_oid} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) 607@var{crl}: should contain a gnutls_x509_crl_t type 608 609@var{indx}: Specifies which DN OID to send. Use (0) to get the first one. 610 611@var{oid}: a pointer to store the OID (may be null) 612 613@var{sizeof_oid}: initially holds the size of 'oid' 614 615This function will extract the requested OID of the name of the CRL 616issuer, specified by the given index. 617 618If oid is null then only the size will be filled. 619 620@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 621not long enough, and in that case the sizeof_oid will be updated 622with the required size. On success 0 is returned. 623@end deftypefun 624 625@subheading gnutls_x509_crl_get_extension_data 626@anchor{gnutls_x509_crl_get_extension_data} 627@deftypefun {int} {gnutls_x509_crl_get_extension_data} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) 628@var{crl}: should contain a @code{gnutls_x509_crl_t} type 629 630@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. 631 632@var{data}: a pointer to a structure to hold the data (may be null) 633 634@var{sizeof_data}: initially holds the size of @code{oid} 635 636This function will return the requested extension data in the CRL. 637The extension data will be stored as a string in the provided 638buffer. 639 640Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and 641critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead, 642if you want to get data indexed by the extension OID rather than 643sequence. 644 645@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 646negative error code in case of an error. If your have reached the 647last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 648will be returned. 649 650@strong{Since:} 2.8.0 651@end deftypefun 652 653@subheading gnutls_x509_crl_get_extension_data2 654@anchor{gnutls_x509_crl_get_extension_data2} 655@deftypefun {int} {gnutls_x509_crl_get_extension_data2} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, gnutls_datum_t * @var{data}) 656@var{crl}: should contain a @code{gnutls_x509_crl_t} type 657 658@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. 659 660@var{data}: will contain the extension DER-encoded data 661 662This function will return the requested by the index extension data in the 663certificate revocation list. The extension data will be allocated using 664@code{gnutls_malloc()} . 665 666Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID. 667 668@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 669otherwise a negative error code is returned. If you have reached the 670last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 671will be returned. 672@end deftypefun 673 674@subheading gnutls_x509_crl_get_extension_info 675@anchor{gnutls_x509_crl_get_extension_info} 676@deftypefun {int} {gnutls_x509_crl_get_extension_info} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) 677@var{crl}: should contain a @code{gnutls_x509_crl_t} type 678 679@var{indx}: Specifies which extension OID to send, use (0) to get the first one. 680 681@var{oid}: a pointer to store the OID 682 683@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return 684holds actual size of @code{oid} . 685 686@var{critical}: output variable with critical flag, may be NULL. 687 688This function will return the requested extension OID in the CRL, 689and the critical flag for it. The extension OID will be stored as 690a string in the provided buffer. Use 691@code{gnutls_x509_crl_get_extension_data()} to extract the data. 692 693If the buffer provided is not long enough to hold the output, then 694* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be 695returned. 696 697@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 698negative error code in case of an error. If your have reached the 699last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 700will be returned. 701 702@strong{Since:} 2.8.0 703@end deftypefun 704 705@subheading gnutls_x509_crl_get_extension_oid 706@anchor{gnutls_x509_crl_get_extension_oid} 707@deftypefun {int} {gnutls_x509_crl_get_extension_oid} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) 708@var{crl}: should contain a @code{gnutls_x509_crl_t} type 709 710@var{indx}: Specifies which extension OID to send, use (0) to get the first one. 711 712@var{oid}: a pointer to store the OID (may be null) 713 714@var{sizeof_oid}: initially holds the size of @code{oid} 715 716This function will return the requested extension OID in the CRL. 717The extension OID will be stored as a string in the provided 718buffer. 719 720@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 721negative error code in case of an error. If your have reached the 722last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 723will be returned. 724 725@strong{Since:} 2.8.0 726@end deftypefun 727 728@subheading gnutls_x509_crl_get_issuer_dn 729@anchor{gnutls_x509_crl_get_issuer_dn} 730@deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf}) 731@var{crl}: should contain a gnutls_x509_crl_t type 732 733@var{buf}: a pointer to a structure to hold the peer's name (may be null) 734 735@var{sizeof_buf}: initially holds the size of @code{buf} 736 737This function will copy the name of the CRL issuer in the provided 738buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 739described in RFC4514. The output string will be ASCII or UTF-8 740encoded, depending on the certificate data. 741 742If buf is @code{NULL} then only the size will be filled. 743 744This function does not output a fully RFC4514 compliant string, if 745that is required see @code{gnutls_x509_crl_get_issuer_dn3()} . 746 747@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 748not long enough, and in that case the sizeof_buf will be updated 749with the required size, and 0 on success. 750@end deftypefun 751 752@subheading gnutls_x509_crl_get_issuer_dn2 753@anchor{gnutls_x509_crl_get_issuer_dn2} 754@deftypefun {int} {gnutls_x509_crl_get_issuer_dn2} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}) 755@var{crl}: should contain a @code{gnutls_x509_crl_t} type 756 757@var{dn}: a pointer to a structure to hold the name 758 759This function will allocate buffer and copy the name of the CRL issuer. 760The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 761described in RFC4514. The output string will be ASCII or UTF-8 762encoded, depending on the certificate data. 763 764This function does not output a fully RFC4514 compliant string, if 765that is required see @code{gnutls_x509_crl_get_issuer_dn3()} . 766 767@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 768negative error value. 769 770@strong{Since:} 3.1.10 771@end deftypefun 772 773@subheading gnutls_x509_crl_get_issuer_dn3 774@anchor{gnutls_x509_crl_get_issuer_dn3} 775@deftypefun {int} {gnutls_x509_crl_get_issuer_dn3} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) 776@var{crl}: should contain a @code{gnutls_x509_crl_t} type 777 778@var{dn}: a pointer to a structure to hold the name 779 780@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} 781 782This function will allocate buffer and copy the name of the CRL issuer. 783The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 784described in RFC4514. The output string will be ASCII or UTF-8 785encoded, depending on the certificate data. 786 787When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 788format will match the format output by previous to 3.5.6 versions of GnuTLS 789which was not not fully RFC4514-compliant. 790 791@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 792negative error value. 793 794@strong{Since:} 3.5.7 795@end deftypefun 796 797@subheading gnutls_x509_crl_get_issuer_dn_by_oid 798@anchor{gnutls_x509_crl_get_issuer_dn_by_oid} 799@deftypefun {int} {gnutls_x509_crl_get_issuer_dn_by_oid} (gnutls_x509_crl_t @var{crl}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{sizeof_buf}) 800@var{crl}: should contain a gnutls_x509_crl_t type 801 802@var{oid}: holds an Object Identified in null terminated string 803 804@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. 805 806@var{raw_flag}: If non-zero returns the raw DER data of the DN part. 807 808@var{buf}: a pointer to a structure to hold the peer's name (may be null) 809 810@var{sizeof_buf}: initially holds the size of @code{buf} 811 812This function will extract the part of the name of the CRL issuer 813specified by the given OID. The output will be encoded as described 814in RFC4514. The output string will be ASCII or UTF-8 encoded, 815depending on the certificate data. 816 817Some helper macros with popular OIDs can be found in gnutls/x509.h 818If raw flag is (0), this function will only return known OIDs as 819text. Other OIDs will be DER encoded, as described in RFC4514 -- in 820hex format with a '#' prefix. You can check about known OIDs 821using @code{gnutls_x509_dn_oid_known()} . 822 823If buf is null then only the size will be filled. 824 825@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 826not long enough, and in that case the sizeof_buf will be updated 827with the required size, and 0 on success. 828@end deftypefun 829 830@subheading gnutls_x509_crl_get_next_update 831@anchor{gnutls_x509_crl_get_next_update} 832@deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl}) 833@var{crl}: should contain a @code{gnutls_x509_crl_t} type 834 835This function will return the time the next CRL will be issued. 836This field is optional in a CRL so it might be normal to get an 837error instead. 838 839@strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error. 840@end deftypefun 841 842@subheading gnutls_x509_crl_get_number 843@anchor{gnutls_x509_crl_get_number} 844@deftypefun {int} {gnutls_x509_crl_get_number} (gnutls_x509_crl_t @var{crl}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical}) 845@var{crl}: should contain a @code{gnutls_x509_crl_t} type 846 847@var{ret}: The place where the number will be copied 848 849@var{ret_size}: Holds the size of the result field. 850 851@var{critical}: will be non-zero if the extension is marked as critical 852(may be null) 853 854This function will return the CRL number extension. This is 855obtained by the CRL Number extension field (2.5.29.20). 856 857@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 858negative error code in case of an error. 859 860@strong{Since:} 2.8.0 861@end deftypefun 862 863@subheading gnutls_x509_crl_get_raw_issuer_dn 864@anchor{gnutls_x509_crl_get_raw_issuer_dn} 865@deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}) 866@var{crl}: should contain a gnutls_x509_crl_t type 867 868@var{dn}: will hold the starting point of the DN 869 870This function will return a pointer to the DER encoded DN structure 871and the length. 872 873@strong{Returns:} a negative error code on error, and (0) on success. 874 875@strong{Since:} 2.12.0 876@end deftypefun 877 878@subheading gnutls_x509_crl_get_signature 879@anchor{gnutls_x509_crl_get_signature} 880@deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig}) 881@var{crl}: should contain a gnutls_x509_crl_t type 882 883@var{sig}: a pointer where the signature part will be copied (may be null). 884 885@var{sizeof_sig}: initially holds the size of @code{sig} 886 887This function will extract the signature field of a CRL. 888 889@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 890negative error value. 891@end deftypefun 892 893@subheading gnutls_x509_crl_get_signature_algorithm 894@anchor{gnutls_x509_crl_get_signature_algorithm} 895@deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl}) 896@var{crl}: should contain a @code{gnutls_x509_crl_t} type 897 898This function will return a value of the @code{gnutls_sign_algorithm_t} 899enumeration that is the signature algorithm. 900 901Since 3.6.0 this function never returns a negative error code. 902Error cases and unknown/unsupported signature algorithms are 903mapped to @code{GNUTLS_SIGN_UNKNOWN} . 904 905@strong{Returns:} a @code{gnutls_sign_algorithm_t} value 906@end deftypefun 907 908@subheading gnutls_x509_crl_get_signature_oid 909@anchor{gnutls_x509_crl_get_signature_oid} 910@deftypefun {int} {gnutls_x509_crl_get_signature_oid} (gnutls_x509_crl_t @var{crl}, char * @var{oid}, size_t * @var{oid_size}) 911@var{crl}: should contain a @code{gnutls_x509_crl_t} type 912 913@var{oid}: a pointer to a buffer to hold the OID (may be null) 914 915@var{oid_size}: initially holds the size of @code{oid} 916 917This function will return the OID of the signature algorithm 918that has been used to sign this CRL. This is function 919is useful in the case @code{gnutls_x509_crl_get_signature_algorithm()} 920returned @code{GNUTLS_SIGN_UNKNOWN} . 921 922@strong{Returns:} zero or a negative error code on error. 923 924@strong{Since:} 3.5.0 925@end deftypefun 926 927@subheading gnutls_x509_crl_get_this_update 928@anchor{gnutls_x509_crl_get_this_update} 929@deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl}) 930@var{crl}: should contain a @code{gnutls_x509_crl_t} type 931 932This function will return the time this CRL was issued. 933 934@strong{Returns:} when the CRL was issued, or (time_t)-1 on error. 935@end deftypefun 936 937@subheading gnutls_x509_crl_get_version 938@anchor{gnutls_x509_crl_get_version} 939@deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl}) 940@var{crl}: should contain a @code{gnutls_x509_crl_t} type 941 942This function will return the version of the specified CRL. 943 944@strong{Returns:} The version number, or a negative error code on error. 945@end deftypefun 946 947@subheading gnutls_x509_crl_import 948@anchor{gnutls_x509_crl_import} 949@deftypefun {int} {gnutls_x509_crl_import} (gnutls_x509_crl_t @var{crl}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) 950@var{crl}: The data to store the parsed CRL. 951 952@var{data}: The DER or PEM encoded CRL. 953 954@var{format}: One of DER or PEM 955 956This function will convert the given DER or PEM encoded CRL 957to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'. 958 959If the CRL is PEM encoded it should have a header of "X509 CRL". 960 961@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 962negative error value. 963@end deftypefun 964 965@subheading gnutls_x509_crl_init 966@anchor{gnutls_x509_crl_init} 967@deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl}) 968@var{crl}: A pointer to the type to be initialized 969 970This function will initialize a CRL structure. CRL stands for 971Certificate Revocation List. A revocation list usually contains 972lists of certificate serial numbers that have been revoked by an 973Authority. The revocation lists are always signed with the 974authority's private key. 975 976@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 977negative error value. 978@end deftypefun 979 980@subheading gnutls_x509_crl_iter_crt_serial 981@anchor{gnutls_x509_crl_iter_crt_serial} 982@deftypefun {int} {gnutls_x509_crl_iter_crt_serial} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crl_iter_t * @var{iter}, unsigned char * @var{serial}, size_t * @var{serial_size}, time_t * @var{t}) 983@var{crl}: should contain a @code{gnutls_x509_crl_t} type 984 985@var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} ) 986 987@var{serial}: where the serial number will be copied 988 989@var{serial_size}: initially holds the size of serial 990 991@var{t}: if non null, will hold the time this certificate was revoked 992 993This function performs the same as @code{gnutls_x509_crl_get_crt_serial()} , 994but reads sequentially and keeps state in the iterator 995between calls. That allows it to provide better performance in sequences 996with many elements (50000+). 997 998When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 999is returned and the iterator is reset. 1000 1001After use, the iterator must be deinitialized using @code{gnutls_x509_crl_iter_deinit()} . 1002 1003@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1004negative error value. 1005@end deftypefun 1006 1007@subheading gnutls_x509_crl_iter_deinit 1008@anchor{gnutls_x509_crl_iter_deinit} 1009@deftypefun {void} {gnutls_x509_crl_iter_deinit} (gnutls_x509_crl_iter_t @var{iter}) 1010@var{iter}: The iterator to be deinitialized 1011 1012This function will deinitialize an iterator type. 1013@end deftypefun 1014 1015@subheading gnutls_x509_crl_list_import 1016@anchor{gnutls_x509_crl_list_import} 1017@deftypefun {int} {gnutls_x509_crl_list_import} (gnutls_x509_crl_t * @var{crls}, unsigned int * @var{crl_max}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) 1018@var{crls}: Indicates where the parsed CRLs will be copied to. Must not be initialized. 1019 1020@var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available. 1021 1022@var{data}: The PEM encoded CRLs 1023 1024@var{format}: One of DER or PEM. 1025 1026@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. 1027 1028This function will convert the given PEM encoded CRL list 1029to the native gnutls_x509_crl_t format. The output will be stored 1030in @code{crls} . They will be automatically initialized. 1031 1032If the Certificate is PEM encoded it should have a header of "X509 CRL". 1033 1034@strong{Returns:} the number of certificates read or a negative error value. 1035 1036@strong{Since:} 3.0 1037@end deftypefun 1038 1039@subheading gnutls_x509_crl_list_import2 1040@anchor{gnutls_x509_crl_list_import2} 1041@deftypefun {int} {gnutls_x509_crl_list_import2} (gnutls_x509_crl_t ** @var{crls}, unsigned int * @var{size}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) 1042@var{crls}: Will contain the parsed crl list. 1043 1044@var{size}: It will contain the size of the list. 1045 1046@var{data}: The PEM encoded CRL. 1047 1048@var{format}: One of DER or PEM. 1049 1050@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. 1051 1052This function will convert the given PEM encoded CRL list 1053to the native gnutls_x509_crl_t format. The output will be stored 1054in @code{crls} . They will be automatically initialized. 1055 1056If the Certificate is PEM encoded it should have a header of "X509 1057CRL". 1058 1059@strong{Returns:} the number of certificates read or a negative error value. 1060 1061@strong{Since:} 3.0 1062@end deftypefun 1063 1064@subheading gnutls_x509_crl_print 1065@anchor{gnutls_x509_crl_print} 1066@deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) 1067@var{crl}: The data to be printed 1068 1069@var{format}: Indicate the format to use 1070 1071@var{out}: Newly allocated datum with null terminated string. 1072 1073This function will pretty print a X.509 certificate revocation 1074list, suitable for display to a human. 1075 1076The output @code{out} needs to be deallocated using @code{gnutls_free()} . 1077 1078@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1079negative error value. 1080@end deftypefun 1081 1082@subheading gnutls_x509_crl_set_authority_key_id 1083@anchor{gnutls_x509_crl_set_authority_key_id} 1084@deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size}) 1085@var{crl}: a CRL of type @code{gnutls_x509_crl_t} 1086 1087@var{id}: The key ID 1088 1089@var{id_size}: Holds the size of the serial field. 1090 1091This function will set the CRL's authority key ID extension. Only 1092the keyIdentifier field can be set with this function. This may 1093be used by an authority that holds multiple private keys, to distinguish 1094the used key. 1095 1096@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1097negative error value. 1098 1099@strong{Since:} 2.8.0 1100@end deftypefun 1101 1102@subheading gnutls_x509_crl_set_crt 1103@anchor{gnutls_x509_crl_set_crt} 1104@deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time}) 1105@var{crl}: should contain a gnutls_x509_crl_t type 1106 1107@var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate 1108 1109@var{revocation_time}: The time this certificate was revoked 1110 1111This function will set a revoked certificate's serial number to the CRL. 1112 1113@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1114negative error value. 1115@end deftypefun 1116 1117@subheading gnutls_x509_crl_set_crt_serial 1118@anchor{gnutls_x509_crl_set_crt_serial} 1119@deftypefun {int} {gnutls_x509_crl_set_crt_serial} (gnutls_x509_crl_t @var{crl}, const void * @var{serial}, size_t @var{serial_size}, time_t @var{revocation_time}) 1120@var{crl}: should contain a gnutls_x509_crl_t type 1121 1122@var{serial}: The revoked certificate's serial number 1123 1124@var{serial_size}: Holds the size of the serial field. 1125 1126@var{revocation_time}: The time this certificate was revoked 1127 1128This function will set a revoked certificate's serial number to the CRL. 1129 1130@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1131negative error value. 1132@end deftypefun 1133 1134@subheading gnutls_x509_crl_set_next_update 1135@anchor{gnutls_x509_crl_set_next_update} 1136@deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time}) 1137@var{crl}: should contain a gnutls_x509_crl_t type 1138 1139@var{exp_time}: The actual time 1140 1141This function will set the time this CRL will be updated. 1142This is an optional value to be set on a CRL and this call 1143can be omitted when generating a CRL. 1144 1145Prior to GnuTLS 3.5.7, setting a nextUpdate field was required 1146in order to generate a CRL. 1147 1148@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1149negative error value. 1150@end deftypefun 1151 1152@subheading gnutls_x509_crl_set_number 1153@anchor{gnutls_x509_crl_set_number} 1154@deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size}) 1155@var{crl}: a CRL of type @code{gnutls_x509_crl_t} 1156 1157@var{nr}: The CRL number 1158 1159@var{nr_size}: Holds the size of the nr field. 1160 1161This function will set the CRL's number extension. This 1162is to be used as a unique and monotonic number assigned to 1163the CRL by the authority. 1164 1165@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1166negative error value. 1167 1168@strong{Since:} 2.8.0 1169@end deftypefun 1170 1171@subheading gnutls_x509_crl_set_this_update 1172@anchor{gnutls_x509_crl_set_this_update} 1173@deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time}) 1174@var{crl}: should contain a gnutls_x509_crl_t type 1175 1176@var{act_time}: The actual time 1177 1178This function will set the time this CRL was issued. 1179 1180@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1181negative error value. 1182@end deftypefun 1183 1184@subheading gnutls_x509_crl_set_version 1185@anchor{gnutls_x509_crl_set_version} 1186@deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version}) 1187@var{crl}: should contain a gnutls_x509_crl_t type 1188 1189@var{version}: holds the version number. For CRLv1 crls must be 1. 1190 1191This function will set the version of the CRL. This 1192must be one for CRL version 1, and so on. The CRLs generated 1193by gnutls should have a version number of 2. 1194 1195@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1196negative error value. 1197@end deftypefun 1198 1199@subheading gnutls_x509_crl_sign 1200@anchor{gnutls_x509_crl_sign} 1201@deftypefun {int} {gnutls_x509_crl_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}) 1202@var{crl}: should contain a gnutls_x509_crl_t type 1203 1204@var{issuer}: is the certificate of the certificate issuer 1205 1206@var{issuer_key}: holds the issuer's private key 1207 1208This function is the same a @code{gnutls_x509_crl_sign2()} with no flags, 1209and an appropriate hash algorithm. The hash algorithm used may 1210vary between versions of GnuTLS, and it is tied to the security 1211level of the issuer's public key. 1212 1213@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1214negative error value. 1215@end deftypefun 1216 1217@subheading gnutls_x509_crl_sign2 1218@anchor{gnutls_x509_crl_sign2} 1219@deftypefun {int} {gnutls_x509_crl_sign2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) 1220@var{crl}: should contain a gnutls_x509_crl_t type 1221 1222@var{issuer}: is the certificate of the certificate issuer 1223 1224@var{issuer_key}: holds the issuer's private key 1225 1226@var{dig}: The message digest to use. GNUTLS_DIG_SHA256 is the safe choice unless you know what you're doing. 1227 1228@var{flags}: must be 0 1229 1230This function will sign the CRL with the issuer's private key, and 1231will copy the issuer's information into the CRL. 1232 1233This must be the last step in a certificate CRL since all 1234the previously set parameters are now signed. 1235 1236A known limitation of this function is, that a newly-signed CRL will not 1237be fully functional (e.g., for signature verification), until it 1238is exported an re-imported. 1239 1240After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , 1241and in that case, a suitable but reasonable for the key algorithm will be selected. 1242 1243@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1244negative error value. 1245@end deftypefun 1246 1247@subheading gnutls_x509_crl_verify 1248@anchor{gnutls_x509_crl_verify} 1249@deftypefun {int} {gnutls_x509_crl_verify} (gnutls_x509_crl_t @var{crl}, const gnutls_x509_crt_t * @var{trusted_cas}, unsigned @var{tcas_size}, unsigned int @var{flags}, unsigned int * @var{verify}) 1250@var{crl}: is the crl to be verified 1251 1252@var{trusted_cas}: is a certificate list that is considered to be trusted one 1253 1254@var{tcas_size}: holds the number of CA certificates in CA_list 1255 1256@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 1257 1258@var{verify}: will hold the crl verification output. 1259 1260This function will try to verify the given crl and return its verification status. 1261See @code{gnutls_x509_crt_list_verify()} for a detailed description of 1262return values. Note that since GnuTLS 3.1.4 this function includes 1263the time checks. 1264 1265Note that value in @code{verify} is set only when the return value of this 1266function is success (i.e, failure to trust a CRL a certificate does not imply 1267a negative return value). 1268 1269Before GnuTLS 3.5.7 this function would return zero or a positive 1270number on success. 1271 1272@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a 1273negative error value. 1274@end deftypefun 1275 1276@subheading gnutls_x509_crq_deinit 1277@anchor{gnutls_x509_crq_deinit} 1278@deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq}) 1279@var{crq}: the type to be deinitialized 1280 1281This function will deinitialize a PKCS@code{10} certificate request 1282structure. 1283@end deftypefun 1284 1285@subheading gnutls_x509_crq_export 1286@anchor{gnutls_x509_crq_export} 1287@deftypefun {int} {gnutls_x509_crq_export} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) 1288@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1289 1290@var{format}: the format of output params. One of PEM or DER. 1291 1292@var{output_data}: will contain a certificate request PEM or DER encoded 1293 1294@var{output_data_size}: holds the size of output_data (and will be 1295replaced by the actual size of parameters) 1296 1297This function will export the certificate request to a PEM or DER 1298encoded PKCS10 structure. 1299 1300If the buffer provided is not long enough to hold the output, then 1301@code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and 1302* @code{output_data_size} will be updated. 1303 1304If the structure is PEM encoded, it will have a header of "BEGIN 1305NEW CERTIFICATE REQUEST". 1306 1307@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1308negative error value. 1309@end deftypefun 1310 1311@subheading gnutls_x509_crq_export2 1312@anchor{gnutls_x509_crq_export2} 1313@deftypefun {int} {gnutls_x509_crq_export2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 1314@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1315 1316@var{format}: the format of output params. One of PEM or DER. 1317 1318@var{out}: will contain a certificate request PEM or DER encoded 1319 1320This function will export the certificate request to a PEM or DER 1321encoded PKCS10 structure. 1322 1323The output buffer is allocated using @code{gnutls_malloc()} . 1324 1325If the structure is PEM encoded, it will have a header of "BEGIN 1326NEW CERTIFICATE REQUEST". 1327 1328@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1329negative error value. 1330 1331Since 3.1.3 1332@end deftypefun 1333 1334@subheading gnutls_x509_crq_get_attribute_by_oid 1335@anchor{gnutls_x509_crq_get_attribute_by_oid} 1336@deftypefun {int} {gnutls_x509_crq_get_attribute_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}) 1337@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1338 1339@var{oid}: holds an Object Identifier in null-terminated string 1340 1341@var{indx}: In case multiple same OIDs exist in the attribute list, this 1342specifies which to get, use (0) to get the first one 1343 1344@var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} ) 1345 1346@var{buf_size}: initially holds the size of @code{buf} 1347 1348This function will return the attribute in the certificate request 1349specified by the given Object ID. The attribute will be DER 1350encoded. 1351 1352Attributes in a certificate request is an optional set of data 1353appended to the request. Their interpretation depends on the CA policy. 1354 1355@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1356negative error value. 1357@end deftypefun 1358 1359@subheading gnutls_x509_crq_get_attribute_data 1360@anchor{gnutls_x509_crq_get_attribute_data} 1361@deftypefun {int} {gnutls_x509_crq_get_attribute_data} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) 1362@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1363 1364@var{indx}: Specifies which attribute number to get. Use (0) to get the first one. 1365 1366@var{data}: a pointer to a structure to hold the data (may be null) 1367 1368@var{sizeof_data}: initially holds the size of @code{oid} 1369 1370This function will return the requested attribute data in the 1371certificate request. The attribute data will be stored as a string in the 1372provided buffer. 1373 1374Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID. 1375Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead, 1376if you want to get data indexed by the attribute OID rather than 1377sequence. 1378 1379@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1380negative error code in case of an error. If your have reached the 1381last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1382will be returned. 1383 1384@strong{Since:} 2.8.0 1385@end deftypefun 1386 1387@subheading gnutls_x509_crq_get_attribute_info 1388@anchor{gnutls_x509_crq_get_attribute_info} 1389@deftypefun {int} {gnutls_x509_crq_get_attribute_info} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) 1390@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1391 1392@var{indx}: Specifies which attribute number to get. Use (0) to get the first one. 1393 1394@var{oid}: a pointer to a structure to hold the OID 1395 1396@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return 1397holds actual size of @code{oid} . 1398 1399This function will return the requested attribute OID in the 1400certificate, and the critical flag for it. The attribute OID will 1401be stored as a string in the provided buffer. Use 1402@code{gnutls_x509_crq_get_attribute_data()} to extract the data. 1403 1404If the buffer provided is not long enough to hold the output, then 1405* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be 1406returned. 1407 1408@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1409negative error code in case of an error. If your have reached the 1410last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1411will be returned. 1412 1413@strong{Since:} 2.8.0 1414@end deftypefun 1415 1416@subheading gnutls_x509_crq_get_basic_constraints 1417@anchor{gnutls_x509_crq_get_basic_constraints} 1418@deftypefun {int} {gnutls_x509_crq_get_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{critical}, unsigned int * @var{ca}, int * @var{pathlen}) 1419@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1420 1421@var{critical}: will be non-zero if the extension is marked as critical 1422 1423@var{ca}: pointer to output integer indicating CA status, may be NULL, 1424value is 1 if the certificate CA flag is set, 0 otherwise. 1425 1426@var{pathlen}: pointer to output integer indicating path length (may be 1427NULL), non-negative error codes indicate a present pathLenConstraint 1428field and the actual value, -1 indicate that the field is absent. 1429 1430This function will read the certificate's basic constraints, and 1431return the certificates CA status. It reads the basicConstraints 1432X.509 extension (2.5.29.19). 1433 1434@strong{Returns:} If the certificate is a CA a positive value will be 1435returned, or (0) if the certificate does not have CA flag set. 1436A negative error code may be returned in case of errors. If the 1437certificate does not contain the basicConstraints extension 1438@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. 1439 1440@strong{Since:} 2.8.0 1441@end deftypefun 1442 1443@subheading gnutls_x509_crq_get_challenge_password 1444@anchor{gnutls_x509_crq_get_challenge_password} 1445@deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{pass_size}) 1446@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1447 1448@var{pass}: will hold a (0)-terminated password string 1449 1450@var{pass_size}: Initially holds the size of @code{pass} . 1451 1452This function will return the challenge password in the request. 1453The challenge password is intended to be used for requesting a 1454revocation of the certificate. 1455 1456@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1457negative error value. 1458@end deftypefun 1459 1460@subheading gnutls_x509_crq_get_dn 1461@anchor{gnutls_x509_crq_get_dn} 1462@deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{buf_size}) 1463@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1464 1465@var{buf}: a pointer to a structure to hold the name (may be @code{NULL} ) 1466 1467@var{buf_size}: initially holds the size of @code{buf} 1468 1469This function will copy the name of the Certificate request subject 1470to the provided buffer. The name will be in the form 1471"C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string 1472 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate 1473data. 1474 1475This function does not output a fully RFC4514 compliant string, if 1476that is required see @code{gnutls_x509_crq_get_dn3()} . 1477 1478@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 1479long enough, and in that case the * @code{buf_size} will be updated with 1480the required size. On success 0 is returned. 1481@end deftypefun 1482 1483@subheading gnutls_x509_crq_get_dn2 1484@anchor{gnutls_x509_crq_get_dn2} 1485@deftypefun {int} {gnutls_x509_crq_get_dn2} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn}) 1486@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1487 1488@var{dn}: a pointer to a structure to hold the name 1489 1490This function will allocate buffer and copy the name of the Certificate 1491request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 1492described in RFC4514. The output string will be ASCII or UTF-8 1493encoded, depending on the certificate data. 1494 1495This function does not output a fully RFC4514 compliant string, if 1496that is required see @code{gnutls_x509_crq_get_dn3()} . 1497 1498@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1499negative error value. and a negative error code on error. 1500 1501@strong{Since:} 3.1.10 1502@end deftypefun 1503 1504@subheading gnutls_x509_crq_get_dn3 1505@anchor{gnutls_x509_crq_get_dn3} 1506@deftypefun {int} {gnutls_x509_crq_get_dn3} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) 1507@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1508 1509@var{dn}: a pointer to a structure to hold the name 1510 1511@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} 1512 1513This function will allocate buffer and copy the name of the Certificate 1514request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 1515described in RFC4514. The output string will be ASCII or UTF-8 1516encoded, depending on the certificate data. 1517 1518When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 1519format will match the format output by previous to 3.5.6 versions of GnuTLS 1520which was not not fully RFC4514-compliant. 1521 1522@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1523negative error value. and a negative error code on error. 1524 1525@strong{Since:} 3.5.7 1526@end deftypefun 1527 1528@subheading gnutls_x509_crq_get_dn_by_oid 1529@anchor{gnutls_x509_crq_get_dn_by_oid} 1530@deftypefun {int} {gnutls_x509_crq_get_dn_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) 1531@var{crq}: should contain a gnutls_x509_crq_t type 1532 1533@var{oid}: holds an Object Identifier in a null terminated string 1534 1535@var{indx}: In case multiple same OIDs exist in the RDN, this specifies 1536which to get. Use (0) to get the first one. 1537 1538@var{raw_flag}: If non-zero returns the raw DER data of the DN part. 1539 1540@var{buf}: a pointer to a structure to hold the name (may be @code{NULL} ) 1541 1542@var{buf_size}: initially holds the size of @code{buf} 1543 1544This function will extract the part of the name of the Certificate 1545request subject, specified by the given OID. The output will be 1546encoded as described in RFC2253. The output string will be ASCII 1547or UTF-8 encoded, depending on the certificate data. 1548 1549Some helper macros with popular OIDs can be found in gnutls/x509.h 1550If raw flag is (0), this function will only return known OIDs as 1551text. Other OIDs will be DER encoded, as described in RFC2253 -- 1552in hex format with a '\#' prefix. You can check about known OIDs 1553using @code{gnutls_x509_dn_oid_known()} . 1554 1555@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 1556not long enough, and in that case the * @code{buf_size} will be 1557updated with the required size. On success 0 is returned. 1558@end deftypefun 1559 1560@subheading gnutls_x509_crq_get_dn_oid 1561@anchor{gnutls_x509_crq_get_dn_oid} 1562@deftypefun {int} {gnutls_x509_crq_get_dn_oid} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) 1563@var{crq}: should contain a gnutls_x509_crq_t type 1564 1565@var{indx}: Specifies which DN OID to get. Use (0) to get the first one. 1566 1567@var{oid}: a pointer to a structure to hold the name (may be @code{NULL} ) 1568 1569@var{sizeof_oid}: initially holds the size of @code{oid} 1570 1571This function will extract the requested OID of the name of the 1572certificate request subject, specified by the given index. 1573 1574@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 1575not long enough, and in that case the * @code{sizeof_oid} will be 1576updated with the required size. On success 0 is returned. 1577@end deftypefun 1578 1579@subheading gnutls_x509_crq_get_extension_by_oid 1580@anchor{gnutls_x509_crq_get_extension_by_oid} 1581@deftypefun {int} {gnutls_x509_crq_get_extension_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical}) 1582@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1583 1584@var{oid}: holds an Object Identifier in a null terminated string 1585 1586@var{indx}: In case multiple same OIDs exist in the extensions, this 1587specifies which to get. Use (0) to get the first one. 1588 1589@var{buf}: a pointer to a structure to hold the name (may be null) 1590 1591@var{buf_size}: initially holds the size of @code{buf} 1592 1593@var{critical}: will be non-zero if the extension is marked as critical 1594 1595This function will return the extension specified by the OID in 1596the certificate. The extensions will be returned as binary data 1597DER encoded, in the provided buffer. 1598 1599@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1600negative error code in case of an error. If the certificate does not 1601contain the specified extension 1602@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. 1603 1604@strong{Since:} 2.8.0 1605@end deftypefun 1606 1607@subheading gnutls_x509_crq_get_extension_by_oid2 1608@anchor{gnutls_x509_crq_get_extension_by_oid2} 1609@deftypefun {int} {gnutls_x509_crq_get_extension_by_oid2} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical}) 1610@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1611 1612@var{oid}: holds an Object Identifier in a null terminated string 1613 1614@var{indx}: In case multiple same OIDs exist in the extensions, this 1615specifies which to get. Use (0) to get the first one. 1616 1617@var{output}: will hold the allocated extension data 1618 1619@var{critical}: will be non-zero if the extension is marked as critical 1620 1621This function will return the extension specified by the OID in 1622the certificate. The extensions will be returned as binary data 1623DER encoded, in the provided buffer. 1624 1625@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1626negative error code in case of an error. If the certificate does not 1627contain the specified extension 1628@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. 1629 1630@strong{Since:} 3.3.8 1631@end deftypefun 1632 1633@subheading gnutls_x509_crq_get_extension_data 1634@anchor{gnutls_x509_crq_get_extension_data} 1635@deftypefun {int} {gnutls_x509_crq_get_extension_data} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) 1636@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1637 1638@var{indx}: Specifies which extension number to get. Use (0) to get the first one. 1639 1640@var{data}: a pointer to a structure to hold the data (may be null) 1641 1642@var{sizeof_data}: initially holds the size of @code{oid} 1643 1644This function will return the requested extension data in the 1645certificate. The extension data will be stored as a string in the 1646provided buffer. 1647 1648Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and 1649critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead, 1650if you want to get data indexed by the extension OID rather than 1651sequence. 1652 1653@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1654negative error code in case of an error. If your have reached the 1655last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1656will be returned. 1657 1658@strong{Since:} 2.8.0 1659@end deftypefun 1660 1661@subheading gnutls_x509_crq_get_extension_data2 1662@anchor{gnutls_x509_crq_get_extension_data2} 1663@deftypefun {int} {gnutls_x509_crq_get_extension_data2} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, gnutls_datum_t * @var{data}) 1664@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1665 1666@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. 1667 1668@var{data}: will contain the extension DER-encoded data 1669 1670This function will return the requested extension data in the 1671certificate request. The extension data will be allocated using 1672@code{gnutls_malloc()} . 1673 1674Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID. 1675 1676@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 1677otherwise a negative error code is returned. If you have reached the 1678last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1679will be returned. 1680 1681@strong{Since:} 3.3.0 1682@end deftypefun 1683 1684@subheading gnutls_x509_crq_get_extension_info 1685@anchor{gnutls_x509_crq_get_extension_info} 1686@deftypefun {int} {gnutls_x509_crq_get_extension_info} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) 1687@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1688 1689@var{indx}: Specifies which extension number to get. Use (0) to get the first one. 1690 1691@var{oid}: a pointer to store the OID 1692 1693@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return 1694holds actual size of @code{oid} . 1695 1696@var{critical}: output variable with critical flag, may be NULL. 1697 1698This function will return the requested extension OID in the 1699certificate, and the critical flag for it. The extension OID will 1700be stored as a string in the provided buffer. Use 1701@code{gnutls_x509_crq_get_extension_data()} to extract the data. 1702 1703If the buffer provided is not long enough to hold the output, then 1704* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be 1705returned. 1706 1707@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1708negative error code in case of an error. If your have reached the 1709last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1710will be returned. 1711 1712@strong{Since:} 2.8.0 1713@end deftypefun 1714 1715@subheading gnutls_x509_crq_get_key_id 1716@anchor{gnutls_x509_crq_get_key_id} 1717@deftypefun {int} {gnutls_x509_crq_get_key_id} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) 1718@var{crq}: a certificate of type @code{gnutls_x509_crq_t} 1719 1720@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} 1721 1722@var{output_data}: will contain the key ID 1723 1724@var{output_data_size}: holds the size of output_data (and will be 1725replaced by the actual size of parameters) 1726 1727This function will return a unique ID that depends on the public key 1728parameters. This ID can be used in checking whether a certificate 1729corresponds to the given private key. 1730 1731If the buffer provided is not long enough to hold the output, then 1732* @code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will 1733be returned. The output will normally be a SHA-1 hash output, 1734which is 20 bytes. 1735 1736@strong{Returns:} In case of failure a negative error code will be 1737returned, and 0 on success. 1738 1739@strong{Since:} 2.8.0 1740@end deftypefun 1741 1742@subheading gnutls_x509_crq_get_key_purpose_oid 1743@anchor{gnutls_x509_crq_get_key_purpose_oid} 1744@deftypefun {int} {gnutls_x509_crq_get_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) 1745@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1746 1747@var{indx}: This specifies which OID to return, use (0) to get the first one 1748 1749@var{oid}: a pointer to store the OID (may be @code{NULL} ) 1750 1751@var{sizeof_oid}: initially holds the size of @code{oid} 1752 1753@var{critical}: output variable with critical flag, may be @code{NULL} . 1754 1755This function will extract the key purpose OIDs of the Certificate 1756specified by the given index. These are stored in the Extended Key 1757Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for 1758human readable names. 1759 1760@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 1761not long enough, and in that case the * @code{sizeof_oid} will be 1762updated with the required size. On success 0 is returned. 1763 1764@strong{Since:} 2.8.0 1765@end deftypefun 1766 1767@subheading gnutls_x509_crq_get_key_rsa_raw 1768@anchor{gnutls_x509_crq_get_key_rsa_raw} 1769@deftypefun {int} {gnutls_x509_crq_get_key_rsa_raw} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}) 1770@var{crq}: Holds the certificate 1771 1772@var{m}: will hold the modulus 1773 1774@var{e}: will hold the public exponent 1775 1776This function will export the RSA public key's parameters found in 1777the given structure. The new parameters will be allocated using 1778@code{gnutls_malloc()} and will be stored in the appropriate datum. 1779 1780@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1781negative error value. 1782 1783@strong{Since:} 2.8.0 1784@end deftypefun 1785 1786@subheading gnutls_x509_crq_get_key_usage 1787@anchor{gnutls_x509_crq_get_key_usage} 1788@deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical}) 1789@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1790 1791@var{key_usage}: where the key usage bits will be stored 1792 1793@var{critical}: will be non-zero if the extension is marked as critical 1794 1795This function will return certificate's key usage, by reading the 1796keyUsage X.509 extension (2.5.29.15). The key usage value will 1797ORed values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , 1798@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , 1799@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , 1800@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , 1801@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . 1802 1803@strong{Returns:} the certificate key usage, or a negative error code in case of 1804parsing error. If the certificate does not contain the keyUsage 1805extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be 1806returned. 1807 1808@strong{Since:} 2.8.0 1809@end deftypefun 1810 1811@subheading gnutls_x509_crq_get_pk_algorithm 1812@anchor{gnutls_x509_crq_get_pk_algorithm} 1813@deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits}) 1814@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1815 1816@var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits 1817 1818This function will return the public key algorithm of a PKCS@code{10} 1819certificate request. 1820 1821If bits is non-@code{NULL} , it should have enough size to hold the 1822parameters size in bits. For RSA the bits returned is the modulus. 1823For DSA the bits returned are of the public exponent. 1824 1825@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on 1826success, or a negative error code on error. 1827@end deftypefun 1828 1829@subheading gnutls_x509_crq_get_pk_oid 1830@anchor{gnutls_x509_crq_get_pk_oid} 1831@deftypefun {int} {gnutls_x509_crq_get_pk_oid} (gnutls_x509_crq_t @var{crq}, char * @var{oid}, size_t * @var{oid_size}) 1832@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1833 1834@var{oid}: a pointer to a buffer to hold the OID (may be null) 1835 1836@var{oid_size}: initially holds the size of @code{oid} 1837 1838This function will return the OID of the public key algorithm 1839on that certificate request. This function 1840is useful in the case @code{gnutls_x509_crq_get_pk_algorithm()} 1841returned @code{GNUTLS_PK_UNKNOWN} . 1842 1843@strong{Returns:} zero or a negative error code on error. 1844 1845@strong{Since:} 3.5.0 1846@end deftypefun 1847 1848@subheading gnutls_x509_crq_get_private_key_usage_period 1849@anchor{gnutls_x509_crq_get_private_key_usage_period} 1850@deftypefun {int} {gnutls_x509_crq_get_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t * @var{activation}, time_t * @var{expiration}, unsigned int * @var{critical}) 1851@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1852 1853@var{activation}: The activation time 1854 1855@var{expiration}: The expiration time 1856 1857@var{critical}: the extension status 1858 1859This function will return the expiration and activation 1860times of the private key of the certificate. 1861 1862@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 1863if the extension is not present, otherwise a negative error value. 1864@end deftypefun 1865 1866@subheading gnutls_x509_crq_get_signature_algorithm 1867@anchor{gnutls_x509_crq_get_signature_algorithm} 1868@deftypefun {int} {gnutls_x509_crq_get_signature_algorithm} (gnutls_x509_crq_t @var{crq}) 1869@var{crq}: should contain a @code{gnutls_x509_cr_t} type 1870 1871This function will return a value of the @code{gnutls_sign_algorithm_t} 1872enumeration that is the signature algorithm that has been used to 1873sign this certificate request. 1874 1875Since 3.6.0 this function never returns a negative error code. 1876Error cases and unknown/unsupported signature algorithms are 1877mapped to @code{GNUTLS_SIGN_UNKNOWN} . 1878 1879@strong{Returns:} a @code{gnutls_sign_algorithm_t} value 1880 1881@strong{Since:} 3.4.0 1882@end deftypefun 1883 1884@subheading gnutls_x509_crq_get_signature_oid 1885@anchor{gnutls_x509_crq_get_signature_oid} 1886@deftypefun {int} {gnutls_x509_crq_get_signature_oid} (gnutls_x509_crq_t @var{crq}, char * @var{oid}, size_t * @var{oid_size}) 1887@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1888 1889@var{oid}: a pointer to a buffer to hold the OID (may be null) 1890 1891@var{oid_size}: initially holds the size of @code{oid} 1892 1893This function will return the OID of the signature algorithm 1894that has been used to sign this certificate request. This function 1895is useful in the case @code{gnutls_x509_crq_get_signature_algorithm()} 1896returned @code{GNUTLS_SIGN_UNKNOWN} . 1897 1898@strong{Returns:} zero or a negative error code on error. 1899 1900@strong{Since:} 3.5.0 1901@end deftypefun 1902 1903@subheading gnutls_x509_crq_get_spki 1904@anchor{gnutls_x509_crq_get_spki} 1905@deftypefun {int} {gnutls_x509_crq_get_spki} (gnutls_x509_crq_t @var{crq}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 1906@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1907 1908@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 1909 1910@var{flags}: must be zero 1911 1912This function will return the public key information of a PKCS@code{10} 1913certificate request. The provided @code{spki} must be initialized. 1914 1915@strong{Returns:} Zero on success, or a negative error code on error. 1916@end deftypefun 1917 1918@subheading gnutls_x509_crq_get_subject_alt_name 1919@anchor{gnutls_x509_crq_get_subject_alt_name} 1920@deftypefun {int} {gnutls_x509_crq_get_subject_alt_name} (gnutls_x509_crq_t @var{crq}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{ret_type}, unsigned int * @var{critical}) 1921@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1922 1923@var{seq}: specifies the sequence number of the alt name, 0 for the 1924first one, 1 for the second etc. 1925 1926@var{ret}: is the place where the alternative name will be copied to 1927 1928@var{ret_size}: holds the size of ret. 1929 1930@var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type 1931 1932@var{critical}: will be non-zero if the extension is marked as critical 1933(may be null) 1934 1935This function will return the alternative names, contained in the 1936given certificate. It is the same as 1937@code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it 1938will return the type of the alternative name in @code{ret_type} even if 1939the function fails for some reason (i.e. the buffer provided is 1940not enough). 1941 1942@strong{Returns:} the alternative subject name type on success, one of the 1943enumerated @code{gnutls_x509_subject_alt_name_t} . It will return 1944@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to 1945hold the value. In that case @code{ret_size} will be updated with the 1946required size. If the certificate request does not have an 1947Alternative name with the specified sequence number then 1948@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 1949 1950@strong{Since:} 2.8.0 1951@end deftypefun 1952 1953@subheading gnutls_x509_crq_get_subject_alt_othername_oid 1954@anchor{gnutls_x509_crq_get_subject_alt_othername_oid} 1955@deftypefun {int} {gnutls_x509_crq_get_subject_alt_othername_oid} (gnutls_x509_crq_t @var{crq}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}) 1956@var{crq}: should contain a @code{gnutls_x509_crq_t} type 1957 1958@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 1959 1960@var{ret}: is the place where the otherName OID will be copied to 1961 1962@var{ret_size}: holds the size of ret. 1963 1964This function will extract the type OID of an otherName Subject 1965Alternative Name, contained in the given certificate, and return 1966the type as an enumerated element. 1967 1968This function is only useful if 1969@code{gnutls_x509_crq_get_subject_alt_name()} returned 1970@code{GNUTLS_SAN_OTHERNAME} . 1971 1972@strong{Returns:} the alternative subject name type on success, one of the 1973enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, 1974it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, 1975e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for 1976unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if 1977 @code{ret_size} is not large enough to hold the value. In that case 1978 @code{ret_size} will be updated with the required size. If the 1979certificate does not have an Alternative name with the specified 1980sequence number and with the otherName type then 1981@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 1982 1983@strong{Since:} 2.8.0 1984@end deftypefun 1985 1986@subheading gnutls_x509_crq_get_tlsfeatures 1987@anchor{gnutls_x509_crq_get_tlsfeatures} 1988@deftypefun {int} {gnutls_x509_crq_get_tlsfeatures} (gnutls_x509_crq_t @var{crq}, gnutls_x509_tlsfeatures_t @var{features}, unsigned int @var{flags}, unsigned int * @var{critical}) 1989@var{crq}: An X.509 certificate request 1990 1991@var{features}: If the function succeeds, the 1992features will be stored in this variable. 1993 1994@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} 1995 1996@var{critical}: the extension status 1997 1998This function will get the X.509 TLS features 1999extension structure from the certificate request. 2000The returned structure needs to be freed using 2001@code{gnutls_x509_tlsfeatures_deinit()} . 2002 2003When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , 2004then if the @code{features} structure is empty this function will behave 2005identically as if the flag was not set. Otherwise if there are elements 2006in the @code{features} structure then they will be merged with. 2007 2008Note that @code{features} must be initialized prior to calling this function. 2009 2010@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2011otherwise a negative error value. 2012 2013@strong{Since:} 3.5.1 2014@end deftypefun 2015 2016@subheading gnutls_x509_crq_get_version 2017@anchor{gnutls_x509_crq_get_version} 2018@deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq}) 2019@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2020 2021This function will return the version of the specified Certificate 2022request. 2023 2024@strong{Returns:} version of certificate request, or a negative error code on 2025error. 2026@end deftypefun 2027 2028@subheading gnutls_x509_crq_import 2029@anchor{gnutls_x509_crq_import} 2030@deftypefun {int} {gnutls_x509_crq_import} (gnutls_x509_crq_t @var{crq}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) 2031@var{crq}: The data to store the parsed certificate request. 2032 2033@var{data}: The DER or PEM encoded certificate. 2034 2035@var{format}: One of DER or PEM 2036 2037This function will convert the given DER or PEM encoded certificate 2038request to a @code{gnutls_x509_crq_t} type. The output will be 2039stored in @code{crq} . 2040 2041If the Certificate is PEM encoded it should have a header of "NEW 2042CERTIFICATE REQUEST". 2043 2044@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2045negative error value. 2046@end deftypefun 2047 2048@subheading gnutls_x509_crq_init 2049@anchor{gnutls_x509_crq_init} 2050@deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq}) 2051@var{crq}: A pointer to the type to be initialized 2052 2053This function will initialize a PKCS@code{10} certificate request 2054structure. 2055 2056@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2057negative error value. 2058@end deftypefun 2059 2060@subheading gnutls_x509_crq_print 2061@anchor{gnutls_x509_crq_print} 2062@deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) 2063@var{crq}: The data to be printed 2064 2065@var{format}: Indicate the format to use 2066 2067@var{out}: Newly allocated datum with null terminated string. 2068 2069This function will pretty print a certificate request, suitable for 2070display to a human. 2071 2072The output @code{out} needs to be deallocated using @code{gnutls_free()} . 2073 2074@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2075negative error value. 2076 2077@strong{Since:} 2.8.0 2078@end deftypefun 2079 2080@subheading gnutls_x509_crq_set_attribute_by_oid 2081@anchor{gnutls_x509_crq_set_attribute_by_oid} 2082@deftypefun {int} {gnutls_x509_crq_set_attribute_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, void * @var{buf}, size_t @var{buf_size}) 2083@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2084 2085@var{oid}: holds an Object Identifier in a null-terminated string 2086 2087@var{buf}: a pointer to a structure that holds the attribute data 2088 2089@var{buf_size}: holds the size of @code{buf} 2090 2091This function will set the attribute in the certificate request 2092specified by the given Object ID. The provided attribute must be be DER 2093encoded. 2094 2095Attributes in a certificate request is an optional set of data 2096appended to the request. Their interpretation depends on the CA policy. 2097 2098@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2099negative error value. 2100@end deftypefun 2101 2102@subheading gnutls_x509_crq_set_basic_constraints 2103@anchor{gnutls_x509_crq_set_basic_constraints} 2104@deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint}) 2105@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} 2106 2107@var{ca}: true(1) or false(0) depending on the Certificate authority status. 2108 2109@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, 2110and negative error codes indicate that the pathLenConstraints field should 2111not be present. 2112 2113This function will set the basicConstraints certificate extension. 2114 2115@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2116negative error value. 2117 2118@strong{Since:} 2.8.0 2119@end deftypefun 2120 2121@subheading gnutls_x509_crq_set_challenge_password 2122@anchor{gnutls_x509_crq_set_challenge_password} 2123@deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass}) 2124@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2125 2126@var{pass}: holds a (0)-terminated password 2127 2128This function will set a challenge password to be used when 2129revoking the request. 2130 2131@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2132negative error value. 2133@end deftypefun 2134 2135@subheading gnutls_x509_crq_set_dn 2136@anchor{gnutls_x509_crq_set_dn} 2137@deftypefun {int} {gnutls_x509_crq_set_dn} (gnutls_x509_crq_t @var{crq}, const char * @var{dn}, const char ** @var{err}) 2138@var{crq}: a certificate of type @code{gnutls_x509_crq_t} 2139 2140@var{dn}: a comma separated DN string (RFC4514) 2141 2142@var{err}: indicates the error position (if any) 2143 2144This function will set the DN on the provided certificate. 2145The input string should be plain ASCII or UTF-8 encoded. On 2146DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. 2147 2148@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2149negative error value. 2150@end deftypefun 2151 2152@subheading gnutls_x509_crq_set_dn_by_oid 2153@anchor{gnutls_x509_crq_set_dn_by_oid} 2154@deftypefun {int} {gnutls_x509_crq_set_dn_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{data}, unsigned int @var{sizeof_data}) 2155@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2156 2157@var{oid}: holds an Object Identifier in a (0)-terminated string 2158 2159@var{raw_flag}: must be 0, or 1 if the data are DER encoded 2160 2161@var{data}: a pointer to the input data 2162 2163@var{sizeof_data}: holds the size of @code{data} 2164 2165This function will set the part of the name of the Certificate 2166request subject, specified by the given OID. The input string 2167should be ASCII or UTF-8 encoded. 2168 2169Some helper macros with popular OIDs can be found in gnutls/x509.h 2170With this function you can only set the known OIDs. You can test 2171for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are 2172not known (by gnutls) you should properly DER encode your data, and 2173call this function with raw_flag set. 2174 2175@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2176negative error value. 2177@end deftypefun 2178 2179@subheading gnutls_x509_crq_set_extension_by_oid 2180@anchor{gnutls_x509_crq_set_extension_by_oid} 2181@deftypefun {int} {gnutls_x509_crq_set_extension_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, const void * @var{buf}, size_t @var{sizeof_buf}, unsigned int @var{critical}) 2182@var{crq}: a certificate of type @code{gnutls_x509_crq_t} 2183 2184@var{oid}: holds an Object Identifier in null terminated string 2185 2186@var{buf}: a pointer to a DER encoded data 2187 2188@var{sizeof_buf}: holds the size of @code{buf} 2189 2190@var{critical}: should be non-zero if the extension is to be marked as critical 2191 2192This function will set an the extension, by the specified OID, in 2193the certificate request. The extension data should be binary data DER 2194encoded. 2195 2196@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2197negative error value. 2198@end deftypefun 2199 2200@subheading gnutls_x509_crq_set_key 2201@anchor{gnutls_x509_crq_set_key} 2202@deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}) 2203@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2204 2205@var{key}: holds a private key 2206 2207This function will set the public parameters from the given private 2208key to the request. 2209 2210@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2211negative error value. 2212@end deftypefun 2213 2214@subheading gnutls_x509_crq_set_key_purpose_oid 2215@anchor{gnutls_x509_crq_set_key_purpose_oid} 2216@deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical}) 2217@var{crq}: a certificate of type @code{gnutls_x509_crq_t} 2218 2219@var{oid}: a pointer to a null-terminated string that holds the OID 2220 2221@var{critical}: Whether this extension will be critical or not 2222 2223This function will set the key purpose OIDs of the Certificate. 2224These are stored in the Extended Key Usage extension (2.5.29.37) 2225See the GNUTLS_KP_* definitions for human readable names. 2226 2227Subsequent calls to this function will append OIDs to the OID list. 2228 2229@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2230negative error value. 2231 2232@strong{Since:} 2.8.0 2233@end deftypefun 2234 2235@subheading gnutls_x509_crq_set_key_rsa_raw 2236@anchor{gnutls_x509_crq_set_key_rsa_raw} 2237@deftypefun {int} {gnutls_x509_crq_set_key_rsa_raw} (gnutls_x509_crq_t @var{crq}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}) 2238@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2239 2240@var{m}: holds the modulus 2241 2242@var{e}: holds the public exponent 2243 2244This function will set the public parameters from the given private 2245key to the request. Only RSA keys are currently supported. 2246 2247@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2248negative error value. 2249 2250@strong{Since:} 2.6.0 2251@end deftypefun 2252 2253@subheading gnutls_x509_crq_set_key_usage 2254@anchor{gnutls_x509_crq_set_key_usage} 2255@deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage}) 2256@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} 2257 2258@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. 2259 2260This function will set the keyUsage certificate extension. 2261 2262@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2263negative error value. 2264 2265@strong{Since:} 2.8.0 2266@end deftypefun 2267 2268@subheading gnutls_x509_crq_set_private_key_usage_period 2269@anchor{gnutls_x509_crq_set_private_key_usage_period} 2270@deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration}) 2271@var{crq}: a certificate of type @code{gnutls_x509_crq_t} 2272 2273@var{activation}: The activation time 2274 2275@var{expiration}: The expiration time 2276 2277This function will set the private key usage period extension (2.5.29.16). 2278 2279@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2280negative error value. 2281@end deftypefun 2282 2283@subheading gnutls_x509_crq_set_spki 2284@anchor{gnutls_x509_crq_set_spki} 2285@deftypefun {int} {gnutls_x509_crq_set_spki} (gnutls_x509_crq_t @var{crq}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 2286@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} 2287 2288@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 2289 2290@var{flags}: must be zero 2291 2292This function will set the certificate request's subject public key 2293information explicitly. This is intended to be used in the cases 2294where a single public key (e.g., RSA) can be used for multiple 2295signature algorithms (RSA PKCS1-1.5, and RSA-PSS). 2296 2297To export the public key (i.e., the SubjectPublicKeyInfo part), check 2298@code{gnutls_pubkey_import_x509()} . 2299 2300@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2301negative error value. 2302 2303@strong{Since:} 3.6.0 2304@end deftypefun 2305 2306@subheading gnutls_x509_crq_set_subject_alt_name 2307@anchor{gnutls_x509_crq_set_subject_alt_name} 2308@deftypefun {int} {gnutls_x509_crq_set_subject_alt_name} (gnutls_x509_crq_t @var{crq}, gnutls_x509_subject_alt_name_t @var{nt}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 2309@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} 2310 2311@var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations 2312 2313@var{data}: The data to be set 2314 2315@var{data_size}: The size of data to be set 2316 2317@var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or 2318@code{GNUTLS_FSAN_APPEND} to append. 2319 2320This function will set the subject alternative name certificate 2321extension. It can set the following types: 2322 2323@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2324negative error value. 2325 2326@strong{Since:} 2.8.0 2327@end deftypefun 2328 2329@subheading gnutls_x509_crq_set_subject_alt_othername 2330@anchor{gnutls_x509_crq_set_subject_alt_othername} 2331@deftypefun {int} {gnutls_x509_crq_set_subject_alt_othername} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 2332@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} 2333 2334@var{oid}: is the othername OID 2335 2336@var{data}: The data to be set 2337 2338@var{data_size}: The size of data to be set 2339 2340@var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or 2341@code{GNUTLS_FSAN_APPEND} to append. 2342 2343This function will set the subject alternative name certificate 2344extension. It can set the following types: 2345 2346The values set must be binary values and must be properly DER encoded. 2347 2348@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2349negative error value. 2350 2351@strong{Since:} 3.5.0 2352@end deftypefun 2353 2354@subheading gnutls_x509_crq_set_tlsfeatures 2355@anchor{gnutls_x509_crq_set_tlsfeatures} 2356@deftypefun {int} {gnutls_x509_crq_set_tlsfeatures} (gnutls_x509_crq_t @var{crq}, gnutls_x509_tlsfeatures_t @var{features}) 2357@var{crq}: An X.509 certificate request 2358 2359@var{features}: If the function succeeds, the 2360features will be added to the certificate 2361request. 2362 2363This function will set the certificate request's 2364X.509 TLS extension from the given structure. 2365 2366@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 2367otherwise a negative error value. 2368 2369@strong{Since:} 3.5.1 2370@end deftypefun 2371 2372@subheading gnutls_x509_crq_set_version 2373@anchor{gnutls_x509_crq_set_version} 2374@deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version}) 2375@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2376 2377@var{version}: holds the version number, for v1 Requests must be 1 2378 2379This function will set the version of the certificate request. For 2380version 1 requests this must be one. 2381 2382@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2383negative error value. 2384@end deftypefun 2385 2386@subheading gnutls_x509_crq_sign 2387@anchor{gnutls_x509_crq_sign} 2388@deftypefun {int} {gnutls_x509_crq_sign} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}) 2389@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2390 2391@var{key}: holds a private key 2392 2393This function is the same a @code{gnutls_x509_crq_sign2()} with no flags, 2394and an appropriate hash algorithm. The hash algorithm used may 2395vary between versions of GnuTLS, and it is tied to the security 2396level of the issuer's public key. 2397 2398A known limitation of this function is, that a newly-signed request will not 2399be fully functional (e.g., for signature verification), until it 2400is exported an re-imported. 2401 2402@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2403negative error value. 2404@end deftypefun 2405 2406@subheading gnutls_x509_crq_sign2 2407@anchor{gnutls_x509_crq_sign2} 2408@deftypefun {int} {gnutls_x509_crq_sign2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) 2409@var{crq}: should contain a @code{gnutls_x509_crq_t} type 2410 2411@var{key}: holds a private key 2412 2413@var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA256} 2414 2415@var{flags}: must be 0 2416 2417This function will sign the certificate request with a private key. 2418This must be the same key as the one used in 2419@code{gnutls_x509_crt_set_key()} since a certificate request is self 2420signed. 2421 2422This must be the last step in a certificate request generation 2423since all the previously set parameters are now signed. 2424 2425A known limitation of this function is, that a newly-signed request will not 2426be fully functional (e.g., for signature verification), until it 2427is exported an re-imported. 2428 2429After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , 2430and in that case, a suitable but reasonable for the key algorithm will be selected. 2431 2432@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 2433@code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all 2434information in the certificate request (e.g., the version using 2435@code{gnutls_x509_crq_set_version()} ). 2436@end deftypefun 2437 2438@subheading gnutls_x509_crq_verify 2439@anchor{gnutls_x509_crq_verify} 2440@deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags}) 2441@var{crq}: is the crq to be verified 2442 2443@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 2444 2445This function will verify self signature in the certificate 2446request and return its status. 2447 2448@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED} 2449is returned, and zero or positive code on success. 2450 2451Since 2.12.0 2452@end deftypefun 2453 2454@subheading gnutls_x509_crt_check_email 2455@anchor{gnutls_x509_crt_check_email} 2456@deftypefun {unsigned} {gnutls_x509_crt_check_email} (gnutls_x509_crt_t @var{cert}, const char * @var{email}, unsigned int @var{flags}) 2457@var{cert}: should contain an gnutls_x509_crt_t type 2458 2459@var{email}: A null terminated string that contains an email address (RFC822) 2460 2461@var{flags}: should be zero 2462 2463This function will check if the given certificate's subject matches 2464the given email address. 2465 2466@strong{Returns:} non-zero for a successful match, and zero on failure. 2467@end deftypefun 2468 2469@subheading gnutls_x509_crt_check_hostname 2470@anchor{gnutls_x509_crt_check_hostname} 2471@deftypefun {unsigned} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}) 2472@var{cert}: should contain an gnutls_x509_crt_t type 2473 2474@var{hostname}: A null terminated string that contains a DNS name 2475 2476This function will check if the given certificate's subject matches 2477the given hostname. This is a basic implementation of the matching 2478described in RFC6125, and takes into account wildcards, 2479and the DNSName/IPAddress subject alternative name PKIX extension. 2480 2481For details see also @code{gnutls_x509_crt_check_hostname2()} . 2482 2483@strong{Returns:} non-zero for a successful match, and zero on failure. 2484@end deftypefun 2485 2486@subheading gnutls_x509_crt_check_hostname2 2487@anchor{gnutls_x509_crt_check_hostname2} 2488@deftypefun {unsigned} {gnutls_x509_crt_check_hostname2} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}, unsigned int @var{flags}) 2489@var{cert}: should contain an gnutls_x509_crt_t type 2490 2491@var{hostname}: A null terminated string that contains a DNS name 2492 2493@var{flags}: gnutls_certificate_verify_flags 2494 2495This function will check if the given certificate's subject matches 2496the given hostname. This is a basic implementation of the matching 2497described in RFC6125, and takes into account wildcards, 2498and the DNSName/IPAddress subject alternative name PKIX extension. 2499 2500IPv4 addresses are accepted by this function in the dotted-decimal 2501format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the hexadecimal 2502x:x:x:x:x:x:x:x format. For them the IPAddress subject alternative 2503name extension is consulted. Previous versions to 3.6.0 of GnuTLS 2504in case of a non-match would consult (in a non-standard extension) 2505the DNSname and CN fields. This is no longer the case. 2506 2507When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS} is specified no 2508wildcards are considered. Otherwise they are only considered if the 2509domain name consists of three components or more, and the wildcard 2510starts at the leftmost position. 2511When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_IP_MATCHES} is specified, 2512the input will be treated as a DNS name, and matching of textual IP addresses 2513against the IPAddress part of the alternative name will not be allowed. 2514 2515The function @code{gnutls_x509_crt_check_ip()} is available for matching 2516IP addresses. 2517 2518@strong{Returns:} non-zero for a successful match, and zero on failure. 2519 2520@strong{Since:} 3.3.0 2521@end deftypefun 2522 2523@subheading gnutls_x509_crt_check_ip 2524@anchor{gnutls_x509_crt_check_ip} 2525@deftypefun {unsigned} {gnutls_x509_crt_check_ip} (gnutls_x509_crt_t @var{cert}, const unsigned char * @var{ip}, unsigned int @var{ip_size}, unsigned int @var{flags}) 2526@var{cert}: should contain an gnutls_x509_crt_t type 2527 2528@var{ip}: A pointer to the raw IP address 2529 2530@var{ip_size}: the number of bytes in ip (4 or 16) 2531 2532@var{flags}: should be zero 2533 2534This function will check if the IP allowed IP addresses in 2535the certificate's subject alternative name match the provided 2536IP address. 2537 2538@strong{Returns:} non-zero for a successful match, and zero on failure. 2539@end deftypefun 2540 2541@subheading gnutls_x509_crt_check_issuer 2542@anchor{gnutls_x509_crt_check_issuer} 2543@deftypefun {unsigned} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer}) 2544@var{cert}: is the certificate to be checked 2545 2546@var{issuer}: is the certificate of a possible issuer 2547 2548This function will check if the given certificate was issued by the 2549given issuer. It checks the DN fields and the authority 2550key identifier and subject key identifier fields match. 2551 2552If the same certificate is provided at the @code{cert} and @code{issuer} fields, 2553it will check whether the certificate is self-signed. 2554 2555@strong{Returns:} It will return true (1) if the given certificate is issued 2556by the given issuer, and false (0) if not. 2557@end deftypefun 2558 2559@subheading gnutls_x509_crt_check_key_purpose 2560@anchor{gnutls_x509_crt_check_key_purpose} 2561@deftypefun {unsigned} {gnutls_x509_crt_check_key_purpose} (gnutls_x509_crt_t @var{cert}, const char * @var{purpose}, unsigned @var{flags}) 2562@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2563 2564@var{purpose}: a key purpose OID (e.g., @code{GNUTLS_KP_CODE_SIGNING} ) 2565 2566@var{flags}: zero or @code{GNUTLS_KP_FLAG_DISALLOW_ANY} 2567 2568This function will check whether the given certificate matches 2569the provided key purpose. If @code{flags} contains @code{GNUTLS_KP_FLAG_ALLOW_ANY} then 2570it a certificate marked for any purpose will not match. 2571 2572@strong{Returns:} zero if the key purpose doesn't match, and non-zero otherwise. 2573 2574@strong{Since:} 3.5.6 2575@end deftypefun 2576 2577@subheading gnutls_x509_crt_check_revocation 2578@anchor{gnutls_x509_crt_check_revocation} 2579@deftypefun {int} {gnutls_x509_crt_check_revocation} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crl_t * @var{crl_list}, unsigned @var{crl_list_length}) 2580@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2581 2582@var{crl_list}: should contain a list of gnutls_x509_crl_t types 2583 2584@var{crl_list_length}: the length of the crl_list 2585 2586This function will check if the given certificate is 2587revoked. It is assumed that the CRLs have been verified before. 2588 2589@strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A 2590negative error code is returned on error. 2591@end deftypefun 2592 2593@subheading gnutls_x509_crt_cpy_crl_dist_points 2594@anchor{gnutls_x509_crt_cpy_crl_dist_points} 2595@deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src}) 2596@var{dst}: a certificate of type @code{gnutls_x509_crt_t} 2597 2598@var{src}: the certificate where the dist points will be copied from 2599 2600This function will copy the CRL distribution points certificate 2601extension, from the source to the destination certificate. 2602This may be useful to copy from a CA certificate to issued ones. 2603 2604@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2605negative error value. 2606@end deftypefun 2607 2608@subheading gnutls_x509_crt_deinit 2609@anchor{gnutls_x509_crt_deinit} 2610@deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert}) 2611@var{cert}: The data to be deinitialized 2612 2613This function will deinitialize a certificate structure. 2614@end deftypefun 2615 2616@subheading gnutls_x509_crt_equals 2617@anchor{gnutls_x509_crt_equals} 2618@deftypefun {unsigned} {gnutls_x509_crt_equals} (gnutls_x509_crt_t @var{cert1}, gnutls_x509_crt_t @var{cert2}) 2619@var{cert1}: The first certificate 2620 2621@var{cert2}: The second certificate 2622 2623This function will compare two X.509 certificate structures. 2624 2625@strong{Returns:} On equality non-zero is returned, otherwise zero. 2626 2627@strong{Since:} 3.5.0 2628@end deftypefun 2629 2630@subheading gnutls_x509_crt_equals2 2631@anchor{gnutls_x509_crt_equals2} 2632@deftypefun {unsigned} {gnutls_x509_crt_equals2} (gnutls_x509_crt_t @var{cert1}, const gnutls_datum_t * @var{der}) 2633@var{cert1}: The first certificate 2634 2635@var{der}: A DER encoded certificate 2636 2637This function will compare an X.509 certificate structures, with DER 2638encoded certificate data. 2639 2640@strong{Returns:} On equality non-zero is returned, otherwise zero. 2641 2642@strong{Since:} 3.5.0 2643@end deftypefun 2644 2645@subheading gnutls_x509_crt_export 2646@anchor{gnutls_x509_crt_export} 2647@deftypefun {int} {gnutls_x509_crt_export} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) 2648@var{cert}: Holds the certificate 2649 2650@var{format}: the format of output params. One of PEM or DER. 2651 2652@var{output_data}: will contain a certificate PEM or DER encoded 2653 2654@var{output_data_size}: holds the size of output_data (and will be 2655replaced by the actual size of parameters) 2656 2657This function will export the certificate to DER or PEM format. 2658 2659If the buffer provided is not long enough to hold the output, then 2660*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will 2661be returned. 2662 2663If the structure is PEM encoded, it will have a header 2664of "BEGIN CERTIFICATE". 2665 2666@strong{Returns:} In case of failure a negative error code will be 2667returned, and 0 on success. 2668@end deftypefun 2669 2670@subheading gnutls_x509_crt_export2 2671@anchor{gnutls_x509_crt_export2} 2672@deftypefun {int} {gnutls_x509_crt_export2} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 2673@var{cert}: Holds the certificate 2674 2675@var{format}: the format of output params. One of PEM or DER. 2676 2677@var{out}: will contain a certificate PEM or DER encoded 2678 2679This function will export the certificate to DER or PEM format. 2680The output buffer is allocated using @code{gnutls_malloc()} . 2681 2682If the structure is PEM encoded, it will have a header 2683of "BEGIN CERTIFICATE". 2684 2685@strong{Returns:} In case of failure a negative error code will be 2686returned, and 0 on success. 2687 2688@strong{Since:} 3.1.3 2689@end deftypefun 2690 2691@subheading gnutls_x509_crt_get_activation_time 2692@anchor{gnutls_x509_crt_get_activation_time} 2693@deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert}) 2694@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2695 2696This function will return the time this Certificate was or will be 2697activated. 2698 2699@strong{Returns:} activation time, or (time_t)-1 on error. 2700@end deftypefun 2701 2702@subheading gnutls_x509_crt_get_authority_info_access 2703@anchor{gnutls_x509_crt_get_authority_info_access} 2704@deftypefun {int} {gnutls_x509_crt_get_authority_info_access} (gnutls_x509_crt_t @var{crt}, unsigned int @var{seq}, int @var{what}, gnutls_datum_t * @var{data}, unsigned int * @var{critical}) 2705@var{crt}: Holds the certificate 2706 2707@var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.) 2708 2709@var{what}: what data to get, a @code{gnutls_info_access_what_t} type. 2710 2711@var{data}: output data to be freed with @code{gnutls_free()} . 2712 2713@var{critical}: pointer to output integer that is set to non-zero if the extension is marked as critical (may be @code{NULL} ) 2714 2715Note that a simpler API to access the authority info data is provided 2716by @code{gnutls_x509_aia_get()} and @code{gnutls_x509_ext_import_aia()} . 2717 2718This function extracts the Authority Information Access (AIA) 2719extension, see RFC 5280 section 4.2.2.1 for more information. The 2720AIA extension holds a sequence of AccessDescription (AD) data. 2721 2722The @code{seq} input parameter is used to indicate which member of the 2723sequence the caller is interested in. The first member is 0, the 2724second member 1 and so on. When the @code{seq} value is out of bounds, 2725@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 2726 2727The type of data returned in @code{data} is specified via @code{what} which 2728should be @code{gnutls_info_access_what_t} values. 2729 2730If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the 2731accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1"). 2732 2733If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will 2734hold the accessLocation GeneralName type (e.g., 2735"uniformResourceIdentifier"). 2736 2737If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI 2738data. Requesting this @code{what} value leads to an error if the 2739accessLocation is not of the "uniformResourceIdentifier" type. 2740 2741If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI. 2742Requesting this @code{what} value leads to an error if the accessMethod 2743is not 1.3.6.1.5.5.7.48.1 aka OCSP, or if accessLocation is not of 2744the "uniformResourceIdentifier" type. In that case @code{GNUTLS_E_UNKNOWN_ALGORITHM} 2745will be returned, and @code{seq} should be increased and this function 2746called again. 2747 2748If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers 2749URI. Requesting this @code{what} value leads to an error if the 2750accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if 2751accessLocation is not of the "uniformResourceIdentifier" type. 2752In that case handle as in @code{GNUTLS_IA_OCSP_URI} . 2753 2754More @code{what} values may be allocated in the future as needed. 2755 2756If @code{data} is NULL, the function does the same without storing the 2757output data, that is, it will set @code{critical} and do error checking 2758as usual. 2759 2760The value of the critical flag is returned in * @code{critical} . Supply a 2761NULL @code{critical} if you want the function to make sure the extension 2762is non-critical, as required by RFC 5280. 2763 2764@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on 2765invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is 2766incorrectly marked as critical (use a non-NULL @code{critical} to 2767override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does 2768not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a 2769negative error code. 2770 2771@strong{Since:} 3.0 2772@end deftypefun 2773 2774@subheading gnutls_x509_crt_get_authority_key_gn_serial 2775@anchor{gnutls_x509_crt_get_authority_key_gn_serial} 2776@deftypefun {int} {gnutls_x509_crt_get_authority_key_gn_serial} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{alt}, size_t * @var{alt_size}, unsigned int * @var{alt_type}, void * @var{serial}, size_t * @var{serial_size}, unsigned int * @var{critical}) 2777@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2778 2779@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 2780 2781@var{alt}: is the place where the alternative name will be copied to 2782 2783@var{alt_size}: holds the size of alt. 2784 2785@var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). 2786 2787@var{serial}: buffer to store the serial number (may be null) 2788 2789@var{serial_size}: Holds the size of the serial field (may be null) 2790 2791@var{critical}: will be non-zero if the extension is marked as critical (may be null) 2792 2793This function will return the X.509 authority key 2794identifier when stored as a general name (authorityCertIssuer) 2795and serial number. 2796 2797Because more than one general names might be stored 2798 @code{seq} can be used as a counter to request them all until 2799@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 2800 2801@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 2802if the extension is not present, otherwise a negative error value. 2803 2804@strong{Since:} 3.0 2805@end deftypefun 2806 2807@subheading gnutls_x509_crt_get_authority_key_id 2808@anchor{gnutls_x509_crt_get_authority_key_id} 2809@deftypefun {int} {gnutls_x509_crt_get_authority_key_id} (gnutls_x509_crt_t @var{cert}, void * @var{id}, size_t * @var{id_size}, unsigned int * @var{critical}) 2810@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2811 2812@var{id}: The place where the identifier will be copied 2813 2814@var{id_size}: Holds the size of the id field. 2815 2816@var{critical}: will be non-zero if the extension is marked as critical (may be null) 2817 2818This function will return the X.509v3 certificate authority's key 2819identifier. This is obtained by the X.509 Authority Key 2820identifier extension field (2.5.29.35). Note that this function 2821only returns the keyIdentifier field of the extension and 2822@code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains 2823the name and serial number of the certificate. In that case 2824@code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used. 2825 2826@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 2827if the extension is not present, otherwise a negative error value. 2828@end deftypefun 2829 2830@subheading gnutls_x509_crt_get_basic_constraints 2831@anchor{gnutls_x509_crt_get_basic_constraints} 2832@deftypefun {int} {gnutls_x509_crt_get_basic_constraints} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}, unsigned int * @var{ca}, int * @var{pathlen}) 2833@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2834 2835@var{critical}: will be non-zero if the extension is marked as critical 2836 2837@var{ca}: pointer to output integer indicating CA status, may be NULL, 2838value is 1 if the certificate CA flag is set, 0 otherwise. 2839 2840@var{pathlen}: pointer to output integer indicating path length (may be 2841NULL), non-negative error codes indicate a present pathLenConstraint 2842field and the actual value, -1 indicate that the field is absent. 2843 2844This function will read the certificate's basic constraints, and 2845return the certificates CA status. It reads the basicConstraints 2846X.509 extension (2.5.29.19). 2847 2848@strong{Returns:} If the certificate is a CA a positive value will be 2849returned, or (0) if the certificate does not have CA flag set. A 2850negative error code may be returned in case of errors. If the 2851certificate does not contain the basicConstraints extension 2852GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. 2853@end deftypefun 2854 2855@subheading gnutls_x509_crt_get_ca_status 2856@anchor{gnutls_x509_crt_get_ca_status} 2857@deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}) 2858@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2859 2860@var{critical}: will be non-zero if the extension is marked as critical 2861 2862This function will return certificates CA status, by reading the 2863basicConstraints X.509 extension (2.5.29.19). If the certificate is 2864a CA a positive value will be returned, or (0) if the certificate 2865does not have CA flag set. 2866 2867Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the 2868pathLenConstraint field too. 2869 2870@strong{Returns:} If the certificate is a CA a positive value will be 2871returned, or (0) if the certificate does not have CA flag set. A 2872negative error code may be returned in case of errors. If the 2873certificate does not contain the basicConstraints extension 2874GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. 2875@end deftypefun 2876 2877@subheading gnutls_x509_crt_get_crl_dist_points 2878@anchor{gnutls_x509_crt_get_crl_dist_points} 2879@deftypefun {int} {gnutls_x509_crt_get_crl_dist_points} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{reason_flags}, unsigned int * @var{critical}) 2880@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2881 2882@var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.) 2883 2884@var{san}: is the place where the distribution point will be copied to 2885 2886@var{san_size}: holds the size of ret. 2887 2888@var{reason_flags}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . 2889 2890@var{critical}: will be non-zero if the extension is marked as critical (may be null) 2891 2892This function retrieves the CRL distribution points (2.5.29.31), 2893contained in the given certificate in the X509v3 Certificate 2894Extensions. 2895 2896@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if 2897 @code{ret_size} is not enough to hold the distribution point, or the 2898type of the distribution point if everything was ok. The type is 2899one of the enumerated @code{gnutls_x509_subject_alt_name_t} . If the 2900certificate does not have an Alternative name with the specified 2901sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is 2902returned. 2903@end deftypefun 2904 2905@subheading gnutls_x509_crt_get_dn 2906@anchor{gnutls_x509_crt_get_dn} 2907@deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size}) 2908@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2909 2910@var{buf}: a pointer to a structure to hold the name (may be null) 2911 2912@var{buf_size}: initially holds the size of @code{buf} 2913 2914This function will copy the name of the Certificate in the provided 2915buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 2916described in RFC4514. The output string will be ASCII or UTF-8 2917encoded, depending on the certificate data. 2918 2919If @code{buf} is null then only the size will be filled. 2920 2921This function does not output a fully RFC4514 compliant string, if 2922that is required see @code{gnutls_x509_crt_get_dn3()} . 2923 2924@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 2925long enough, and in that case the @code{buf_size} will be updated 2926with the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if 2927the DN does not exist, or another error value on error. On success 0 is returned. 2928@end deftypefun 2929 2930@subheading gnutls_x509_crt_get_dn2 2931@anchor{gnutls_x509_crt_get_dn2} 2932@deftypefun {int} {gnutls_x509_crt_get_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) 2933@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2934 2935@var{dn}: a pointer to a structure to hold the name 2936 2937This function will allocate buffer and copy the name of the Certificate. 2938The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 2939described in RFC4514. The output string will be ASCII or UTF-8 2940encoded, depending on the certificate data. 2941 2942This function does not output a fully RFC4514 compliant string, if 2943that is required see @code{gnutls_x509_crt_get_dn3()} . 2944 2945@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2946negative error value. 2947 2948@strong{Since:} 3.1.10 2949@end deftypefun 2950 2951@subheading gnutls_x509_crt_get_dn3 2952@anchor{gnutls_x509_crt_get_dn3} 2953@deftypefun {int} {gnutls_x509_crt_get_dn3} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) 2954@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2955 2956@var{dn}: a pointer to a structure to hold the name 2957 2958@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} 2959 2960This function will allocate buffer and copy the name of the Certificate. 2961The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 2962described in RFC4514. The output string will be ASCII or UTF-8 2963encoded, depending on the certificate data. 2964 2965When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 2966format will match the format output by previous to 3.5.6 versions of GnuTLS 2967which was not not fully RFC4514-compliant. 2968 2969@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 2970negative error value. 2971 2972@strong{Since:} 3.5.7 2973@end deftypefun 2974 2975@subheading gnutls_x509_crt_get_dn_by_oid 2976@anchor{gnutls_x509_crt_get_dn_by_oid} 2977@deftypefun {int} {gnutls_x509_crt_get_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) 2978@var{cert}: should contain a @code{gnutls_x509_crt_t} type 2979 2980@var{oid}: holds an Object Identified in null terminated string 2981 2982@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. 2983 2984@var{raw_flag}: If non-zero returns the raw DER data of the DN part. 2985 2986@var{buf}: a pointer where the DN part will be copied (may be null). 2987 2988@var{buf_size}: initially holds the size of @code{buf} 2989 2990This function will extract the part of the name of the Certificate 2991subject specified by the given OID. The output, if the raw flag is 2992not used, will be encoded as described in RFC4514. Thus a string 2993that is ASCII or UTF-8 encoded, depending on the certificate data. 2994 2995Some helper macros with popular OIDs can be found in gnutls/x509.h 2996If raw flag is (0), this function will only return known OIDs as 2997text. Other OIDs will be DER encoded, as described in RFC4514 -- 2998in hex format with a '#' prefix. You can check about known OIDs 2999using @code{gnutls_x509_dn_oid_known()} . 3000 3001If @code{buf} is null then only the size will be filled. If the @code{raw_flag} is not specified the output is always null terminated, although the 3002 @code{buf_size} will not include the null character. 3003 3004@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 3005long enough, and in that case the @code{buf_size} will be updated with 3006the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there 3007are no data in the current index. On success 0 is returned. 3008@end deftypefun 3009 3010@subheading gnutls_x509_crt_get_dn_oid 3011@anchor{gnutls_x509_crt_get_dn_oid} 3012@deftypefun {int} {gnutls_x509_crt_get_dn_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) 3013@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3014 3015@var{indx}: This specifies which OID to return. Use (0) to get the first one. 3016 3017@var{oid}: a pointer to a buffer to hold the OID (may be null) 3018 3019@var{oid_size}: initially holds the size of @code{oid} 3020 3021This function will extract the OIDs of the name of the Certificate 3022subject specified by the given index. 3023 3024If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not 3025account for the trailing null. 3026 3027@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 3028long enough, and in that case the @code{buf_size} will be updated with 3029the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there 3030are no data in the current index. On success 0 is returned. 3031@end deftypefun 3032 3033@subheading gnutls_x509_crt_get_expiration_time 3034@anchor{gnutls_x509_crt_get_expiration_time} 3035@deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert}) 3036@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3037 3038This function will return the time this certificate was or will be 3039expired. 3040 3041@strong{Returns:} expiration time, or (time_t)-1 on error. 3042@end deftypefun 3043 3044@subheading gnutls_x509_crt_get_extension_by_oid 3045@anchor{gnutls_x509_crt_get_extension_by_oid} 3046@deftypefun {int} {gnutls_x509_crt_get_extension_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical}) 3047@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3048 3049@var{oid}: holds an Object Identified in null terminated string 3050 3051@var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one. 3052 3053@var{buf}: a pointer to a structure to hold the name (may be null) 3054 3055@var{buf_size}: initially holds the size of @code{buf} 3056 3057@var{critical}: will be non-zero if the extension is marked as critical 3058 3059This function will return the extension specified by the OID in the 3060certificate. The extensions will be returned as binary data DER 3061encoded, in the provided buffer. 3062 3063@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3064otherwise a negative error code is returned. If the certificate does not 3065contain the specified extension 3066GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. 3067@end deftypefun 3068 3069@subheading gnutls_x509_crt_get_extension_by_oid2 3070@anchor{gnutls_x509_crt_get_extension_by_oid2} 3071@deftypefun {int} {gnutls_x509_crt_get_extension_by_oid2} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical}) 3072@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3073 3074@var{oid}: holds an Object Identified in null terminated string 3075 3076@var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one. 3077 3078@var{output}: will hold the allocated extension data 3079 3080@var{critical}: will be non-zero if the extension is marked as critical 3081 3082This function will return the extension specified by the OID in the 3083certificate. The extensions will be returned as binary data DER 3084encoded, in the provided buffer. 3085 3086@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3087otherwise a negative error code is returned. If the certificate does not 3088contain the specified extension 3089GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. 3090 3091@strong{Since:} 3.3.8 3092@end deftypefun 3093 3094@subheading gnutls_x509_crt_get_extension_data 3095@anchor{gnutls_x509_crt_get_extension_data} 3096@deftypefun {int} {gnutls_x509_crt_get_extension_data} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) 3097@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3098 3099@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. 3100 3101@var{data}: a pointer to a structure to hold the data (may be null) 3102 3103@var{sizeof_data}: initially holds the size of @code{data} 3104 3105This function will return the requested extension data in the 3106certificate. The extension data will be stored in the 3107provided buffer. 3108 3109Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and 3110critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead, 3111if you want to get data indexed by the extension OID rather than 3112sequence. 3113 3114@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3115otherwise a negative error code is returned. If you have reached the 3116last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3117will be returned. 3118@end deftypefun 3119 3120@subheading gnutls_x509_crt_get_extension_data2 3121@anchor{gnutls_x509_crt_get_extension_data2} 3122@deftypefun {int} {gnutls_x509_crt_get_extension_data2} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, gnutls_datum_t * @var{data}) 3123@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3124 3125@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. 3126 3127@var{data}: will contain the extension DER-encoded data 3128 3129This function will return the requested by the index extension data in the 3130certificate. The extension data will be allocated using 3131@code{gnutls_malloc()} . 3132 3133Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID. 3134 3135@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3136otherwise a negative error code is returned. If you have reached the 3137last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3138will be returned. 3139@end deftypefun 3140 3141@subheading gnutls_x509_crt_get_extension_info 3142@anchor{gnutls_x509_crt_get_extension_info} 3143@deftypefun {int} {gnutls_x509_crt_get_extension_info} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical}) 3144@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3145 3146@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. 3147 3148@var{oid}: a pointer to a structure to hold the OID 3149 3150@var{oid_size}: initially holds the maximum size of @code{oid} , on return 3151holds actual size of @code{oid} . 3152 3153@var{critical}: output variable with critical flag, may be NULL. 3154 3155This function will return the requested extension OID in the 3156certificate, and the critical flag for it. The extension OID will 3157be stored as a string in the provided buffer. Use 3158@code{gnutls_x509_crt_get_extension()} to extract the data. 3159 3160If the buffer provided is not long enough to hold the output, then 3161 @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be 3162returned. The @code{oid} returned will be null terminated, although 3163 @code{oid_size} will not account for the trailing null (the latter is not 3164true for GnuTLS prior to 3.6.0). 3165 3166@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3167otherwise a negative error code is returned. If you have reached the 3168last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3169will be returned. 3170@end deftypefun 3171 3172@subheading gnutls_x509_crt_get_extension_oid 3173@anchor{gnutls_x509_crt_get_extension_oid} 3174@deftypefun {int} {gnutls_x509_crt_get_extension_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) 3175@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3176 3177@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. 3178 3179@var{oid}: a pointer to a structure to hold the OID (may be null) 3180 3181@var{oid_size}: initially holds the size of @code{oid} 3182 3183This function will return the requested extension OID in the certificate. 3184The extension OID will be stored as a string in the provided buffer. 3185 3186The @code{oid} returned will be null terminated, although @code{oid_size} will not 3187account for the trailing null. 3188 3189@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3190otherwise a negative error code is returned. If you have reached the 3191last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3192will be returned. 3193@end deftypefun 3194 3195@subheading gnutls_x509_crt_get_fingerprint 3196@anchor{gnutls_x509_crt_get_fingerprint} 3197@deftypefun {int} {gnutls_x509_crt_get_fingerprint} (gnutls_x509_crt_t @var{cert}, gnutls_digest_algorithm_t @var{algo}, void * @var{buf}, size_t * @var{buf_size}) 3198@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3199 3200@var{algo}: is a digest algorithm 3201 3202@var{buf}: a pointer to a structure to hold the fingerprint (may be null) 3203 3204@var{buf_size}: initially holds the size of @code{buf} 3205 3206This function will calculate and copy the certificate's fingerprint 3207in the provided buffer. The fingerprint is a hash of the DER-encoded 3208data of the certificate. 3209 3210If the buffer is null then only the size will be filled. 3211 3212@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 3213not long enough, and in that case the *buf_size will be updated 3214with the required size. On success 0 is returned. 3215@end deftypefun 3216 3217@subheading gnutls_x509_crt_get_inhibit_anypolicy 3218@anchor{gnutls_x509_crt_get_inhibit_anypolicy} 3219@deftypefun {int} {gnutls_x509_crt_get_inhibit_anypolicy} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{skipcerts}, unsigned int * @var{critical}) 3220@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3221 3222@var{skipcerts}: will hold the number of certificates after which anypolicy is no longer acceptable. 3223 3224@var{critical}: will be non-zero if the extension is marked as critical 3225 3226This function will return certificate's value of the SkipCerts, i.e., 3227the Inhibit anyPolicy X.509 extension (2.5.29.54). 3228 3229The returned value is the number of additional certificates that 3230may appear in the path before the anyPolicy is no longer acceptable. 3231 3232@strong{Returns:} zero on success, or a negative error code in case of 3233parsing error. If the certificate does not contain the Inhibit anyPolicy 3234extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be 3235returned. 3236 3237@strong{Since:} 3.6.0 3238@end deftypefun 3239 3240@subheading gnutls_x509_crt_get_issuer 3241@anchor{gnutls_x509_crt_get_issuer} 3242@deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn}) 3243@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3244 3245@var{dn}: output variable with pointer to uint8_t DN 3246 3247Return the Certificate's Issuer DN as a @code{gnutls_x509_dn_t} data type, 3248that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} . 3249 3250Note that @code{dn} should be treated as constant. Because it points 3251into the @code{cert} object, you should not use @code{dn} after @code{cert} is 3252deallocated. 3253 3254@strong{Returns:} Returns 0 on success, or an error code. 3255@end deftypefun 3256 3257@subheading gnutls_x509_crt_get_issuer_alt_name 3258@anchor{gnutls_x509_crt_get_issuer_alt_name} 3259@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ian}, size_t * @var{ian_size}, unsigned int * @var{critical}) 3260@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3261 3262@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 3263 3264@var{ian}: is the place where the alternative name will be copied to 3265 3266@var{ian_size}: holds the size of ian. 3267 3268@var{critical}: will be non-zero if the extension is marked as critical (may be null) 3269 3270This function retrieves the Issuer Alternative Name (2.5.29.18), 3271contained in the given certificate in the X509v3 Certificate 3272Extensions. 3273 3274When the SAN type is otherName, it will extract the data in the 3275otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned. 3276You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get 3277the corresponding OID and the "virtual" SAN types (e.g., 3278@code{GNUTLS_SAN_OTHERNAME_XMPP} ). 3279 3280If an otherName OID is known, the data will be decoded. Otherwise 3281the returned data will be DER encoded, and you will have to decode 3282it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer 3283AltName is recognized. 3284 3285@strong{Returns:} the alternative issuer name type on success, one of the 3286enumerated @code{gnutls_x509_subject_alt_name_t} . It will return 3287@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough 3288to hold the value. In that case @code{ian_size} will be updated with 3289the required size. If the certificate does not have an 3290Alternative name with the specified sequence number then 3291@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 3292 3293@strong{Since:} 2.10.0 3294@end deftypefun 3295 3296@subheading gnutls_x509_crt_get_issuer_alt_name2 3297@anchor{gnutls_x509_crt_get_issuer_alt_name2} 3298@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ian}, size_t * @var{ian_size}, unsigned int * @var{ian_type}, unsigned int * @var{critical}) 3299@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3300 3301@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 3302 3303@var{ian}: is the place where the alternative name will be copied to 3304 3305@var{ian_size}: holds the size of ret. 3306 3307@var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). 3308 3309@var{critical}: will be non-zero if the extension is marked as critical (may be null) 3310 3311This function will return the alternative names, contained in the 3312given certificate. It is the same as 3313@code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it 3314will return the type of the alternative name in @code{ian_type} even if 3315the function fails for some reason (i.e. the buffer provided is 3316not enough). 3317 3318@strong{Returns:} the alternative issuer name type on success, one of the 3319enumerated @code{gnutls_x509_subject_alt_name_t} . It will return 3320@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough 3321to hold the value. In that case @code{ian_size} will be updated with 3322the required size. If the certificate does not have an 3323Alternative name with the specified sequence number then 3324@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 3325 3326@strong{Since:} 2.10.0 3327@end deftypefun 3328 3329@subheading gnutls_x509_crt_get_issuer_alt_othername_oid 3330@anchor{gnutls_x509_crt_get_issuer_alt_othername_oid} 3331@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_othername_oid} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}) 3332@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3333 3334@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 3335 3336@var{ret}: is the place where the otherName OID will be copied to 3337 3338@var{ret_size}: holds the size of ret. 3339 3340This function will extract the type OID of an otherName Subject 3341Alternative Name, contained in the given certificate, and return 3342the type as an enumerated element. 3343 3344If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not 3345account for the trailing null. 3346 3347This function is only useful if 3348@code{gnutls_x509_crt_get_issuer_alt_name()} returned 3349@code{GNUTLS_SAN_OTHERNAME} . 3350 3351@strong{Returns:} the alternative issuer name type on success, one of the 3352enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it 3353will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, 3354e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for 3355unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if 3356 @code{ret_size} is not large enough to hold the value. In that case 3357 @code{ret_size} will be updated with the required size. If the 3358certificate does not have an Alternative name with the specified 3359sequence number and with the otherName type then 3360@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 3361 3362@strong{Since:} 2.10.0 3363@end deftypefun 3364 3365@subheading gnutls_x509_crt_get_issuer_dn 3366@anchor{gnutls_x509_crt_get_issuer_dn} 3367@deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size}) 3368@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3369 3370@var{buf}: a pointer to a structure to hold the name (may be null) 3371 3372@var{buf_size}: initially holds the size of @code{buf} 3373 3374This function will copy the name of the Certificate issuer in the 3375provided buffer. The name will be in the form 3376"C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string 3377will be ASCII or UTF-8 encoded, depending on the certificate data. 3378 3379If @code{buf} is null then only the size will be filled. 3380 3381This function does not output a fully RFC4514 compliant string, if 3382that is required see @code{gnutls_x509_crt_get_issuer_dn3()} . 3383 3384@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 3385long enough, and in that case the @code{buf_size} will be updated 3386with the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if 3387the DN does not exist, or another error value on error. On success 0 is returned. 3388@end deftypefun 3389 3390@subheading gnutls_x509_crt_get_issuer_dn2 3391@anchor{gnutls_x509_crt_get_issuer_dn2} 3392@deftypefun {int} {gnutls_x509_crt_get_issuer_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) 3393@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3394 3395@var{dn}: a pointer to a structure to hold the name 3396 3397This function will allocate buffer and copy the name of issuer of the Certificate. 3398The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 3399described in RFC4514. The output string will be ASCII or UTF-8 3400encoded, depending on the certificate data. 3401 3402This function does not output a fully RFC4514 compliant string, if 3403that is required see @code{gnutls_x509_crt_get_issuer_dn3()} . 3404 3405@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3406negative error value. 3407 3408@strong{Since:} 3.1.10 3409@end deftypefun 3410 3411@subheading gnutls_x509_crt_get_issuer_dn3 3412@anchor{gnutls_x509_crt_get_issuer_dn3} 3413@deftypefun {int} {gnutls_x509_crt_get_issuer_dn3} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) 3414@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3415 3416@var{dn}: a pointer to a structure to hold the name 3417 3418@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} 3419 3420This function will allocate buffer and copy the name of issuer of the Certificate. 3421The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 3422described in RFC4514. The output string will be ASCII or UTF-8 3423encoded, depending on the certificate data. 3424 3425When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 3426format will match the format output by previous to 3.5.6 versions of GnuTLS 3427which was not not fully RFC4514-compliant. 3428 3429@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3430negative error value. 3431 3432@strong{Since:} 3.5.7 3433@end deftypefun 3434 3435@subheading gnutls_x509_crt_get_issuer_dn_by_oid 3436@anchor{gnutls_x509_crt_get_issuer_dn_by_oid} 3437@deftypefun {int} {gnutls_x509_crt_get_issuer_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) 3438@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3439 3440@var{oid}: holds an Object Identified in null terminated string 3441 3442@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. 3443 3444@var{raw_flag}: If non-zero returns the raw DER data of the DN part. 3445 3446@var{buf}: a pointer to a structure to hold the name (may be null) 3447 3448@var{buf_size}: initially holds the size of @code{buf} 3449 3450This function will extract the part of the name of the Certificate 3451issuer specified by the given OID. The output, if the raw flag is not 3452used, will be encoded as described in RFC4514. Thus a string that is 3453ASCII or UTF-8 encoded, depending on the certificate data. 3454 3455Some helper macros with popular OIDs can be found in gnutls/x509.h 3456If raw flag is (0), this function will only return known OIDs as 3457text. Other OIDs will be DER encoded, as described in RFC4514 -- 3458in hex format with a '#' prefix. You can check about known OIDs 3459using @code{gnutls_x509_dn_oid_known()} . 3460 3461If @code{buf} is null then only the size will be filled. If the @code{raw_flag} is not specified the output is always null terminated, although the 3462 @code{buf_size} will not include the null character. 3463 3464@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 3465long enough, and in that case the @code{buf_size} will be updated with 3466the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there 3467are no data in the current index. On success 0 is returned. 3468@end deftypefun 3469 3470@subheading gnutls_x509_crt_get_issuer_dn_oid 3471@anchor{gnutls_x509_crt_get_issuer_dn_oid} 3472@deftypefun {int} {gnutls_x509_crt_get_issuer_dn_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) 3473@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3474 3475@var{indx}: This specifies which OID to return. Use (0) to get the first one. 3476 3477@var{oid}: a pointer to a buffer to hold the OID (may be null) 3478 3479@var{oid_size}: initially holds the size of @code{oid} 3480 3481This function will extract the OIDs of the name of the Certificate 3482issuer specified by the given index. 3483 3484If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not 3485account for the trailing null. 3486 3487@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not 3488long enough, and in that case the @code{buf_size} will be updated with 3489the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there 3490are no data in the current index. On success 0 is returned. 3491@end deftypefun 3492 3493@subheading gnutls_x509_crt_get_issuer_unique_id 3494@anchor{gnutls_x509_crt_get_issuer_unique_id} 3495@deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size}) 3496@var{crt}: Holds the certificate 3497 3498@var{buf}: user allocated memory buffer, will hold the unique id 3499 3500@var{buf_size}: size of user allocated memory buffer (on input), will hold 3501actual size of the unique ID on return. 3502 3503This function will extract the issuerUniqueID value (if present) for 3504the given certificate. 3505 3506If the user allocated memory buffer is not large enough to hold the 3507full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be 3508returned, and buf_size will be set to the actual length. 3509 3510This function had a bug prior to 3.4.8 that prevented the setting 3511of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely 3512with the older versions the @code{buf} must be a valid buffer that can hold 3513at least a single byte if @code{buf_size} is zero. 3514 3515@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3516 3517@strong{Since:} 2.12.0 3518@end deftypefun 3519 3520@subheading gnutls_x509_crt_get_key_id 3521@anchor{gnutls_x509_crt_get_key_id} 3522@deftypefun {int} {gnutls_x509_crt_get_key_id} (gnutls_x509_crt_t @var{crt}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) 3523@var{crt}: Holds the certificate 3524 3525@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} 3526 3527@var{output_data}: will contain the key ID 3528 3529@var{output_data_size}: holds the size of output_data (and will be 3530replaced by the actual size of parameters) 3531 3532This function will return a unique ID that depends on the public 3533key parameters. This ID can be used in checking whether a 3534certificate corresponds to the given private key. 3535 3536If the buffer provided is not long enough to hold the output, then 3537*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will 3538be returned. The output will normally be a SHA-1 hash output, 3539which is 20 bytes. 3540 3541@strong{Returns:} In case of failure a negative error code will be 3542returned, and 0 on success. 3543@end deftypefun 3544 3545@subheading gnutls_x509_crt_get_key_purpose_oid 3546@anchor{gnutls_x509_crt_get_key_purpose_oid} 3547@deftypefun {int} {gnutls_x509_crt_get_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical}) 3548@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3549 3550@var{indx}: This specifies which OID to return. Use (0) to get the first one. 3551 3552@var{oid}: a pointer to a buffer to hold the OID (may be null) 3553 3554@var{oid_size}: initially holds the size of @code{oid} 3555 3556@var{critical}: output flag to indicate criticality of extension 3557 3558This function will extract the key purpose OIDs of the Certificate 3559specified by the given index. These are stored in the Extended Key 3560Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for 3561human readable names. 3562 3563If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not 3564account for the trailing null. 3565 3566@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is 3567not long enough, and in that case the *oid_size will be updated 3568with the required size. On success 0 is returned. 3569@end deftypefun 3570 3571@subheading gnutls_x509_crt_get_key_usage 3572@anchor{gnutls_x509_crt_get_key_usage} 3573@deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical}) 3574@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3575 3576@var{key_usage}: where the key usage bits will be stored 3577 3578@var{critical}: will be non-zero if the extension is marked as critical 3579 3580This function will return certificate's key usage, by reading the 3581keyUsage X.509 extension (2.5.29.15). The key usage value will ORed 3582values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , 3583@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , 3584@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , 3585@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , 3586@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . 3587 3588@strong{Returns:} zero on success, or a negative error code in case of 3589parsing error. If the certificate does not contain the keyUsage 3590extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be 3591returned. 3592@end deftypefun 3593 3594@subheading gnutls_x509_crt_get_name_constraints 3595@anchor{gnutls_x509_crt_get_name_constraints} 3596@deftypefun {int} {gnutls_x509_crt_get_name_constraints} (gnutls_x509_crt_t @var{crt}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{flags}, unsigned int * @var{critical}) 3597@var{crt}: should contain a @code{gnutls_x509_crt_t} type 3598 3599@var{nc}: The nameconstraints intermediate type 3600 3601@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} 3602 3603@var{critical}: the extension status 3604 3605This function will return an intermediate type containing 3606the name constraints of the provided CA certificate. That 3607structure can be used in combination with @code{gnutls_x509_name_constraints_check()} 3608to verify whether a server's name is in accordance with the constraints. 3609 3610When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , 3611then if the @code{nc} structure is empty this function will behave 3612identically as if the flag was not set. 3613Otherwise if there are elements in the @code{nc} structure then the 3614constraints will be merged with the existing constraints following 3615RFC5280 p6.1.4 (excluded constraints will be appended, permitted 3616will be intersected). 3617 3618Note that @code{nc} must be initialized prior to calling this function. 3619 3620@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3621if the extension is not present, otherwise a negative error value. 3622 3623@strong{Since:} 3.3.0 3624@end deftypefun 3625 3626@subheading gnutls_x509_crt_get_pk_algorithm 3627@anchor{gnutls_x509_crt_get_pk_algorithm} 3628@deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits}) 3629@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3630 3631@var{bits}: if bits is non null it will hold the size of the parameters' in bits 3632 3633This function will return the public key algorithm of an X.509 3634certificate. 3635 3636If bits is non null, it should have enough size to hold the parameters 3637size in bits. For RSA the bits returned is the modulus. 3638For DSA the bits returned are of the public 3639exponent. 3640 3641Unknown/unsupported algorithms are mapped to @code{GNUTLS_PK_UNKNOWN} . 3642 3643@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on 3644success, or a negative error code on error. 3645@end deftypefun 3646 3647@subheading gnutls_x509_crt_get_pk_dsa_raw 3648@anchor{gnutls_x509_crt_get_pk_dsa_raw} 3649@deftypefun {int} {gnutls_x509_crt_get_pk_dsa_raw} (gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}) 3650@var{crt}: Holds the certificate 3651 3652@var{p}: will hold the p 3653 3654@var{q}: will hold the q 3655 3656@var{g}: will hold the g 3657 3658@var{y}: will hold the y 3659 3660This function will export the DSA public key's parameters found in 3661the given certificate. The new parameters will be allocated using 3662@code{gnutls_malloc()} and will be stored in the appropriate datum. 3663 3664@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3665@end deftypefun 3666 3667@subheading gnutls_x509_crt_get_pk_ecc_raw 3668@anchor{gnutls_x509_crt_get_pk_ecc_raw} 3669@deftypefun {int} {gnutls_x509_crt_get_pk_ecc_raw} (gnutls_x509_crt_t @var{crt}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}) 3670@var{crt}: Holds the certificate 3671 3672@var{curve}: will hold the curve 3673 3674@var{x}: will hold the x-coordinate 3675 3676@var{y}: will hold the y-coordinate 3677 3678This function will export the ECC public key's parameters found in 3679the given certificate. The new parameters will be allocated using 3680@code{gnutls_malloc()} and will be stored in the appropriate datum. 3681 3682In EdDSA curves the @code{y} parameter will be @code{NULL} and the other parameters 3683will be in the native format for the curve. 3684 3685@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3686 3687@strong{Since:} 3.4.1 3688@end deftypefun 3689 3690@subheading gnutls_x509_crt_get_pk_gost_raw 3691@anchor{gnutls_x509_crt_get_pk_gost_raw} 3692@deftypefun {int} {gnutls_x509_crt_get_pk_gost_raw} (gnutls_x509_crt_t @var{crt}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}) 3693@var{crt}: Holds the certificate 3694 3695@var{curve}: will hold the curve 3696 3697@var{digest}: will hold the digest 3698 3699@var{paramset}: will hold the GOST parameter set ID 3700 3701@var{x}: will hold the x-coordinate 3702 3703@var{y}: will hold the y-coordinate 3704 3705This function will export the GOST public key's parameters found in 3706the given certificate. The new parameters will be allocated using 3707@code{gnutls_malloc()} and will be stored in the appropriate datum. 3708 3709@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3710 3711@strong{Since:} 3.6.3 3712@end deftypefun 3713 3714@subheading gnutls_x509_crt_get_pk_oid 3715@anchor{gnutls_x509_crt_get_pk_oid} 3716@deftypefun {int} {gnutls_x509_crt_get_pk_oid} (gnutls_x509_crt_t @var{cert}, char * @var{oid}, size_t * @var{oid_size}) 3717@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3718 3719@var{oid}: a pointer to a buffer to hold the OID (may be null) 3720 3721@var{oid_size}: initially holds the size of @code{oid} 3722 3723This function will return the OID of the public key algorithm 3724on that certificate. This is function 3725is useful in the case @code{gnutls_x509_crt_get_pk_algorithm()} 3726returned @code{GNUTLS_PK_UNKNOWN} . 3727 3728@strong{Returns:} zero or a negative error code on error. 3729 3730@strong{Since:} 3.5.0 3731@end deftypefun 3732 3733@subheading gnutls_x509_crt_get_pk_rsa_raw 3734@anchor{gnutls_x509_crt_get_pk_rsa_raw} 3735@deftypefun {int} {gnutls_x509_crt_get_pk_rsa_raw} (gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}) 3736@var{crt}: Holds the certificate 3737 3738@var{m}: will hold the modulus 3739 3740@var{e}: will hold the public exponent 3741 3742This function will export the RSA public key's parameters found in 3743the given structure. The new parameters will be allocated using 3744@code{gnutls_malloc()} and will be stored in the appropriate datum. 3745 3746@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 3747@end deftypefun 3748 3749@subheading gnutls_x509_crt_get_policy 3750@anchor{gnutls_x509_crt_get_policy} 3751@deftypefun {int} {gnutls_x509_crt_get_policy} (gnutls_x509_crt_t @var{crt}, unsigned @var{indx}, struct gnutls_x509_policy_st * @var{policy}, unsigned int * @var{critical}) 3752@var{crt}: should contain a @code{gnutls_x509_crt_t} type 3753 3754@var{indx}: This specifies which policy to return. Use (0) to get the first one. 3755 3756@var{policy}: A pointer to a policy structure. 3757 3758@var{critical}: will be non-zero if the extension is marked as critical 3759 3760This function will extract the certificate policy (extension 2.5.29.32) 3761specified by the given index. 3762 3763The policy returned by this function must be deinitialized by using 3764@code{gnutls_x509_policy_release()} . 3765 3766@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3767if the extension is not present, otherwise a negative error value. 3768 3769@strong{Since:} 3.1.5 3770@end deftypefun 3771 3772@subheading gnutls_x509_crt_get_private_key_usage_period 3773@anchor{gnutls_x509_crt_get_private_key_usage_period} 3774@deftypefun {int} {gnutls_x509_crt_get_private_key_usage_period} (gnutls_x509_crt_t @var{cert}, time_t * @var{activation}, time_t * @var{expiration}, unsigned int * @var{critical}) 3775@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3776 3777@var{activation}: The activation time 3778 3779@var{expiration}: The expiration time 3780 3781@var{critical}: the extension status 3782 3783This function will return the expiration and activation 3784times of the private key of the certificate. It relies on 3785the PKIX extension 2.5.29.16 being present. 3786 3787@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 3788if the extension is not present, otherwise a negative error value. 3789@end deftypefun 3790 3791@subheading gnutls_x509_crt_get_proxy 3792@anchor{gnutls_x509_crt_get_proxy} 3793@deftypefun {int} {gnutls_x509_crt_get_proxy} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}, int * @var{pathlen}, char ** @var{policyLanguage}, char ** @var{policy}, size_t * @var{sizeof_policy}) 3794@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3795 3796@var{critical}: will be non-zero if the extension is marked as critical 3797 3798@var{pathlen}: pointer to output integer indicating path length (may be 3799NULL), non-negative error codes indicate a present pCPathLenConstraint 3800field and the actual value, -1 indicate that the field is absent. 3801 3802@var{policyLanguage}: output variable with OID of policy language 3803 3804@var{policy}: output variable with policy data 3805 3806@var{sizeof_policy}: output variable size of policy data 3807 3808This function will get information from a proxy certificate. It 3809reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14). 3810 3811@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 3812otherwise a negative error code is returned. 3813@end deftypefun 3814 3815@subheading gnutls_x509_crt_get_raw_dn 3816@anchor{gnutls_x509_crt_get_raw_dn} 3817@deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) 3818@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3819 3820@var{dn}: will hold the starting point of the DN 3821 3822This function will return a pointer to the DER encoded DN structure and 3823the length. This points to allocated data that must be free'd using @code{gnutls_free()} . 3824 3825@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3826negative error value. or a negative error code on error. 3827@end deftypefun 3828 3829@subheading gnutls_x509_crt_get_raw_issuer_dn 3830@anchor{gnutls_x509_crt_get_raw_issuer_dn} 3831@deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) 3832@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3833 3834@var{dn}: will hold the starting point of the DN 3835 3836This function will return a pointer to the DER encoded DN structure 3837and the length. This points to allocated data that must be free'd using @code{gnutls_free()} . 3838 3839@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3840negative error value.or a negative error code on error. 3841@end deftypefun 3842 3843@subheading gnutls_x509_crt_get_serial 3844@anchor{gnutls_x509_crt_get_serial} 3845@deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size}) 3846@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3847 3848@var{result}: The place where the serial number will be copied 3849 3850@var{result_size}: Holds the size of the result field. 3851 3852This function will return the X.509 certificate's serial number. 3853This is obtained by the X509 Certificate serialNumber field. Serial 3854is not always a 32 or 64bit number. Some CAs use large serial 3855numbers, thus it may be wise to handle it as something uint8_t. 3856 3857@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3858negative error value. 3859@end deftypefun 3860 3861@subheading gnutls_x509_crt_get_signature 3862@anchor{gnutls_x509_crt_get_signature} 3863@deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sig_size}) 3864@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3865 3866@var{sig}: a pointer where the signature part will be copied (may be null). 3867 3868@var{sig_size}: initially holds the size of @code{sig} 3869 3870This function will extract the signature field of a certificate. 3871 3872@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 3873negative error value. 3874@end deftypefun 3875 3876@subheading gnutls_x509_crt_get_signature_algorithm 3877@anchor{gnutls_x509_crt_get_signature_algorithm} 3878@deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert}) 3879@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3880 3881This function will return a value of the @code{gnutls_sign_algorithm_t} 3882enumeration that is the signature algorithm that has been used to 3883sign this certificate. 3884 3885Since 3.6.0 this function never returns a negative error code. 3886Error cases and unknown/unsupported signature algorithms are 3887mapped to @code{GNUTLS_SIGN_UNKNOWN} . 3888 3889@strong{Returns:} a @code{gnutls_sign_algorithm_t} value 3890@end deftypefun 3891 3892@subheading gnutls_x509_crt_get_signature_oid 3893@anchor{gnutls_x509_crt_get_signature_oid} 3894@deftypefun {int} {gnutls_x509_crt_get_signature_oid} (gnutls_x509_crt_t @var{cert}, char * @var{oid}, size_t * @var{oid_size}) 3895@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3896 3897@var{oid}: a pointer to a buffer to hold the OID (may be null) 3898 3899@var{oid_size}: initially holds the size of @code{oid} 3900 3901This function will return the OID of the signature algorithm 3902that has been used to sign this certificate. This is function 3903is useful in the case @code{gnutls_x509_crt_get_signature_algorithm()} 3904returned @code{GNUTLS_SIGN_UNKNOWN} . 3905 3906@strong{Returns:} zero or a negative error code on error. 3907 3908@strong{Since:} 3.5.0 3909@end deftypefun 3910 3911@subheading gnutls_x509_crt_get_spki 3912@anchor{gnutls_x509_crt_get_spki} 3913@deftypefun {int} {gnutls_x509_crt_get_spki} (gnutls_x509_crt_t @var{cert}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 3914@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 3915 3916@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 3917 3918@var{flags}: must be zero 3919 3920This function will return the public key information of an X.509 3921certificate. The provided @code{spki} must be initialized. 3922 3923@strong{Since:} 3.6.0 3924@end deftypefun 3925 3926@subheading gnutls_x509_crt_get_subject 3927@anchor{gnutls_x509_crt_get_subject} 3928@deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn}) 3929@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3930 3931@var{dn}: output variable with pointer to uint8_t DN. 3932 3933Return the Certificate's Subject DN as a @code{gnutls_x509_dn_t} data type, 3934that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} . 3935 3936Note that @code{dn} should be treated as constant. Because it points 3937into the @code{cert} object, you should not use @code{dn} after @code{cert} is 3938deallocated. 3939 3940@strong{Returns:} Returns 0 on success, or an error code. 3941@end deftypefun 3942 3943@subheading gnutls_x509_crt_get_subject_alt_name 3944@anchor{gnutls_x509_crt_get_subject_alt_name} 3945@deftypefun {int} {gnutls_x509_crt_get_subject_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{critical}) 3946@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3947 3948@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 3949 3950@var{san}: is the place where the alternative name will be copied to 3951 3952@var{san_size}: holds the size of san. 3953 3954@var{critical}: will be non-zero if the extension is marked as critical (may be null) 3955 3956This function retrieves the Alternative Name (2.5.29.17), contained 3957in the given certificate in the X509v3 Certificate Extensions. 3958 3959When the SAN type is otherName, it will extract the data in the 3960otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned. 3961You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get 3962the corresponding OID and the "virtual" SAN types (e.g., 3963@code{GNUTLS_SAN_OTHERNAME_XMPP} ). 3964 3965If an otherName OID is known, the data will be decoded. Otherwise 3966the returned data will be DER encoded, and you will have to decode 3967it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is 3968recognized. 3969 3970@strong{Returns:} the alternative subject name type on success, one of the 3971enumerated @code{gnutls_x509_subject_alt_name_t} . It will return 3972@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to 3973hold the value. In that case @code{san_size} will be updated with the 3974required size. If the certificate does not have an Alternative 3975name with the specified sequence number then 3976@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 3977@end deftypefun 3978 3979@subheading gnutls_x509_crt_get_subject_alt_name2 3980@anchor{gnutls_x509_crt_get_subject_alt_name2} 3981@deftypefun {int} {gnutls_x509_crt_get_subject_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{san_type}, unsigned int * @var{critical}) 3982@var{cert}: should contain a @code{gnutls_x509_crt_t} type 3983 3984@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 3985 3986@var{san}: is the place where the alternative name will be copied to 3987 3988@var{san_size}: holds the size of ret. 3989 3990@var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). 3991 3992@var{critical}: will be non-zero if the extension is marked as critical (may be null) 3993 3994This function will return the alternative names, contained in the 3995given certificate. It is the same as 3996@code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it 3997will return the type of the alternative name in @code{san_type} even if 3998the function fails for some reason (i.e. the buffer provided is 3999not enough). 4000 4001@strong{Returns:} the alternative subject name type on success, one of the 4002enumerated @code{gnutls_x509_subject_alt_name_t} . It will return 4003@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough 4004to hold the value. In that case @code{san_size} will be updated with 4005the required size. If the certificate does not have an 4006Alternative name with the specified sequence number then 4007@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 4008@end deftypefun 4009 4010@subheading gnutls_x509_crt_get_subject_alt_othername_oid 4011@anchor{gnutls_x509_crt_get_subject_alt_othername_oid} 4012@deftypefun {int} {gnutls_x509_crt_get_subject_alt_othername_oid} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{oid}, size_t * @var{oid_size}) 4013@var{cert}: should contain a @code{gnutls_x509_crt_t} type 4014 4015@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) 4016 4017@var{oid}: is the place where the otherName OID will be copied to 4018 4019@var{oid_size}: holds the size of ret. 4020 4021This function will extract the type OID of an otherName Subject 4022Alternative Name, contained in the given certificate, and return 4023the type as an enumerated element. 4024 4025This function is only useful if 4026@code{gnutls_x509_crt_get_subject_alt_name()} returned 4027@code{GNUTLS_SAN_OTHERNAME} . 4028 4029If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not 4030account for the trailing null. 4031 4032@strong{Returns:} the alternative subject name type on success, one of the 4033enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it 4034will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, 4035e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for 4036unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if 4037 @code{ian_size} is not large enough to hold the value. In that case 4038 @code{ian_size} will be updated with the required size. If the 4039certificate does not have an Alternative name with the specified 4040sequence number and with the otherName type then 4041@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. 4042@end deftypefun 4043 4044@subheading gnutls_x509_crt_get_subject_key_id 4045@anchor{gnutls_x509_crt_get_subject_key_id} 4046@deftypefun {int} {gnutls_x509_crt_get_subject_key_id} (gnutls_x509_crt_t @var{cert}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical}) 4047@var{cert}: should contain a @code{gnutls_x509_crt_t} type 4048 4049@var{ret}: The place where the identifier will be copied 4050 4051@var{ret_size}: Holds the size of the result field. 4052 4053@var{critical}: will be non-zero if the extension is marked as critical (may be null) 4054 4055This function will return the X.509v3 certificate's subject key 4056identifier. This is obtained by the X.509 Subject Key identifier 4057extension field (2.5.29.14). 4058 4059@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 4060if the extension is not present, otherwise a negative error value. 4061@end deftypefun 4062 4063@subheading gnutls_x509_crt_get_subject_unique_id 4064@anchor{gnutls_x509_crt_get_subject_unique_id} 4065@deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size}) 4066@var{crt}: Holds the certificate 4067 4068@var{buf}: user allocated memory buffer, will hold the unique id 4069 4070@var{buf_size}: size of user allocated memory buffer (on input), will hold 4071actual size of the unique ID on return. 4072 4073This function will extract the subjectUniqueID value (if present) for 4074the given certificate. 4075 4076If the user allocated memory buffer is not large enough to hold the 4077full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be 4078returned, and buf_size will be set to the actual length. 4079 4080This function had a bug prior to 3.4.8 that prevented the setting 4081of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely 4082with the older versions the @code{buf} must be a valid buffer that can hold 4083at least a single byte if @code{buf_size} is zero. 4084 4085@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 4086@end deftypefun 4087 4088@subheading gnutls_x509_crt_get_tlsfeatures 4089@anchor{gnutls_x509_crt_get_tlsfeatures} 4090@deftypefun {int} {gnutls_x509_crt_get_tlsfeatures} (gnutls_x509_crt_t @var{crt}, gnutls_x509_tlsfeatures_t @var{features}, unsigned int @var{flags}, unsigned int * @var{critical}) 4091@var{crt}: A X.509 certificate 4092 4093@var{features}: If the function succeeds, the 4094features will be stored in this variable. 4095 4096@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} 4097 4098@var{critical}: the extension status 4099 4100This function will get the X.509 TLS features 4101extension structure from the certificate. The 4102returned structure needs to be freed using 4103@code{gnutls_x509_tlsfeatures_deinit()} . 4104 4105When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , 4106then if the @code{features} structure is empty this function will behave 4107identically as if the flag was not set. Otherwise if there are elements 4108in the @code{features} structure then they will be merged with. 4109 4110Note that @code{features} must be initialized prior to calling this function. 4111 4112@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 4113otherwise a negative error value. 4114 4115@strong{Since:} 3.5.1 4116@end deftypefun 4117 4118@subheading gnutls_x509_crt_get_version 4119@anchor{gnutls_x509_crt_get_version} 4120@deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert}) 4121@var{cert}: should contain a @code{gnutls_x509_crt_t} type 4122 4123This function will return the version of the specified Certificate. 4124 4125@strong{Returns:} version of certificate, or a negative error code on error. 4126@end deftypefun 4127 4128@subheading gnutls_x509_crt_import 4129@anchor{gnutls_x509_crt_import} 4130@deftypefun {int} {gnutls_x509_crt_import} (gnutls_x509_crt_t @var{cert}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) 4131@var{cert}: The data to store the parsed certificate. 4132 4133@var{data}: The DER or PEM encoded certificate. 4134 4135@var{format}: One of DER or PEM 4136 4137This function will convert the given DER or PEM encoded Certificate 4138to the native gnutls_x509_crt_t format. The output will be stored 4139in @code{cert} . 4140 4141If the Certificate is PEM encoded it should have a header of "X509 4142CERTIFICATE", or "CERTIFICATE". 4143 4144@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4145negative error value. 4146@end deftypefun 4147 4148@subheading gnutls_x509_crt_import_url 4149@anchor{gnutls_x509_crt_import_url} 4150@deftypefun {int} {gnutls_x509_crt_import_url} (gnutls_x509_crt_t @var{crt}, const char * @var{url}, unsigned int @var{flags}) 4151@var{crt}: A certificate of type @code{gnutls_x509_crt_t} 4152 4153@var{url}: A PKCS 11 url 4154 4155@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags for PKCS@code{11} URLs or zero otherwise 4156 4157This function will import a certificate present in a PKCS@code{11} token 4158or any type of back-end that supports URLs. 4159 4160In previous versions of gnutls this function was named 4161gnutls_x509_crt_import_pkcs11_url, and the old name is 4162an alias to this one. 4163 4164@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4165negative error value. 4166 4167@strong{Since:} 3.4.0 4168@end deftypefun 4169 4170@subheading gnutls_x509_crt_init 4171@anchor{gnutls_x509_crt_init} 4172@deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert}) 4173@var{cert}: A pointer to the type to be initialized 4174 4175This function will initialize an X.509 certificate structure. 4176 4177@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4178negative error value. 4179@end deftypefun 4180 4181@subheading gnutls_x509_crt_list_import 4182@anchor{gnutls_x509_crt_list_import} 4183@deftypefun {int} {gnutls_x509_crt_list_import} (gnutls_x509_crt_t * @var{certs}, unsigned int * @var{cert_max}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) 4184@var{certs}: Indicates where the parsed list will be copied to. Must not be initialized. 4185 4186@var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available. 4187 4188@var{data}: The PEM encoded certificate. 4189 4190@var{format}: One of DER or PEM. 4191 4192@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. 4193 4194This function will convert the given PEM encoded certificate list 4195to the native gnutls_x509_crt_t format. The output will be stored 4196in @code{certs} . They will be automatically initialized. 4197 4198The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause 4199import to fail if the certificates in the provided buffer are more 4200than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED} 4201flag will cause the function to fail if the provided list is not 4202sorted from subject to issuer. 4203 4204If the Certificate is PEM encoded it should have a header of "X509 4205CERTIFICATE", or "CERTIFICATE". 4206 4207@strong{Returns:} the number of certificates read or a negative error value. 4208@end deftypefun 4209 4210@subheading gnutls_x509_crt_list_import2 4211@anchor{gnutls_x509_crt_list_import2} 4212@deftypefun {int} {gnutls_x509_crt_list_import2} (gnutls_x509_crt_t ** @var{certs}, unsigned int * @var{size}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) 4213@var{certs}: Will hold the parsed certificate list. 4214 4215@var{size}: It will contain the size of the list. 4216 4217@var{data}: The PEM encoded certificate. 4218 4219@var{format}: One of DER or PEM. 4220 4221@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. 4222 4223This function will convert the given PEM encoded certificate list 4224to the native gnutls_x509_crt_t format. The output will be stored 4225in @code{certs} which will be allocated and initialized. 4226 4227If the Certificate is PEM encoded it should have a header of "X509 4228CERTIFICATE", or "CERTIFICATE". 4229 4230To deinitialize @code{certs} , you need to deinitialize each crt structure 4231independently, and use @code{gnutls_free()} at @code{certs} . 4232 4233@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. 4234 4235@strong{Since:} 3.0 4236@end deftypefun 4237 4238@subheading gnutls_x509_crt_list_import_url 4239@anchor{gnutls_x509_crt_list_import_url} 4240@deftypefun {int} {gnutls_x509_crt_list_import_url} (gnutls_x509_crt_t ** @var{certs}, unsigned int * @var{size}, const char * @var{url}, gnutls_pin_callback_t @var{pin_fn}, void * @var{pin_fn_userdata}, unsigned int @var{flags}) 4241@var{certs}: Will hold the allocated certificate list. 4242 4243@var{size}: It will contain the size of the list. 4244 4245@var{url}: A PKCS 11 url 4246 4247@var{pin_fn}: a PIN callback if not globally set 4248 4249@var{pin_fn_userdata}: parameter for the PIN callback 4250 4251@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags for PKCS@code{11} URLs or zero otherwise 4252 4253This function will import a certificate chain present in a PKCS@code{11} token 4254or any type of back-end that supports URLs. The certificates 4255must be deinitialized afterwards using @code{gnutls_x509_crt_deinit()} 4256and the returned pointer must be freed using @code{gnutls_free()} . 4257 4258The URI provided must be the first certificate in the chain; subsequent 4259certificates will be retrieved using @code{gnutls_pkcs11_get_raw_issuer()} or 4260equivalent functionality for the supported URI. 4261 4262@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4263negative error value. 4264 4265@strong{Since:} 3.6.3 4266@end deftypefun 4267 4268@subheading gnutls_x509_crt_list_verify 4269@anchor{gnutls_x509_crt_list_verify} 4270@deftypefun {int} {gnutls_x509_crt_list_verify} (const gnutls_x509_crt_t * @var{cert_list}, unsigned @var{cert_list_length}, const gnutls_x509_crt_t * @var{CA_list}, unsigned @var{CA_list_length}, const gnutls_x509_crl_t * @var{CRL_list}, unsigned @var{CRL_list_length}, unsigned int @var{flags}, unsigned int * @var{verify}) 4271@var{cert_list}: is the certificate list to be verified 4272 4273@var{cert_list_length}: holds the number of certificate in cert_list 4274 4275@var{CA_list}: is the CA list which will be used in verification 4276 4277@var{CA_list_length}: holds the number of CA certificate in CA_list 4278 4279@var{CRL_list}: holds a list of CRLs. 4280 4281@var{CRL_list_length}: the length of CRL list. 4282 4283@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 4284 4285@var{verify}: will hold the certificate verification output. 4286 4287 4288This function will try to verify the given certificate list and 4289return its status. The details of the verification are the same 4290as in @code{gnutls_x509_trust_list_verify_crt2()} . 4291 4292You must check the peer's name in order to check if the verified 4293certificate belongs to the actual peer. 4294 4295The certificate verification output will be put in @code{verify} and will 4296be one or more of the gnutls_certificate_status_t enumerated 4297elements bitwise or'd. For a more detailed verification status use 4298@code{gnutls_x509_crt_verify()} per list element. 4299 4300@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4301negative error value. 4302@end deftypefun 4303 4304@subheading gnutls_x509_crt_print 4305@anchor{gnutls_x509_crt_print} 4306@deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) 4307@var{cert}: The data to be printed 4308 4309@var{format}: Indicate the format to use 4310 4311@var{out}: Newly allocated datum with null terminated string. 4312 4313This function will pretty print a X.509 certificate, suitable for 4314display to a human. 4315 4316If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the 4317certificate will be output, on multiple lines. The 4318@code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some 4319selected fields, which is useful for logging purposes. 4320 4321The output @code{out} needs to be deallocated using @code{gnutls_free()} . 4322 4323@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4324negative error value. 4325@end deftypefun 4326 4327@subheading gnutls_x509_crt_set_activation_time 4328@anchor{gnutls_x509_crt_set_activation_time} 4329@deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time}) 4330@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4331 4332@var{act_time}: The actual time 4333 4334This function will set the time this certificate was or will be 4335activated. 4336 4337@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4338negative error value. 4339@end deftypefun 4340 4341@subheading gnutls_x509_crt_set_authority_info_access 4342@anchor{gnutls_x509_crt_set_authority_info_access} 4343@deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data}) 4344@var{crt}: Holds the certificate 4345 4346@var{what}: what data to get, a @code{gnutls_info_access_what_t} type. 4347 4348@var{data}: output data to be freed with @code{gnutls_free()} . 4349 4350This function sets the Authority Information Access (AIA) 4351extension, see RFC 5280 section 4.2.2.1 for more information. 4352 4353The type of data stored in @code{data} is specified via @code{what} which 4354should be @code{gnutls_info_access_what_t} values. 4355 4356If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI. 4357If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers 4358URI. 4359 4360@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4361negative error value. 4362 4363@strong{Since:} 3.0 4364@end deftypefun 4365 4366@subheading gnutls_x509_crt_set_authority_key_id 4367@anchor{gnutls_x509_crt_set_authority_key_id} 4368@deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) 4369@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4370 4371@var{id}: The key ID 4372 4373@var{id_size}: Holds the size of the key ID field. 4374 4375This function will set the X.509 certificate's authority key ID extension. 4376Only the keyIdentifier field can be set with this function. 4377 4378@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4379negative error value. 4380@end deftypefun 4381 4382@subheading gnutls_x509_crt_set_basic_constraints 4383@anchor{gnutls_x509_crt_set_basic_constraints} 4384@deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint}) 4385@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4386 4387@var{ca}: true(1) or false(0). Depending on the Certificate authority status. 4388 4389@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, 4390and negative error codes indicate that the pathLenConstraints field should 4391not be present. 4392 4393This function will set the basicConstraints certificate extension. 4394 4395@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4396negative error value. 4397@end deftypefun 4398 4399@subheading gnutls_x509_crt_set_ca_status 4400@anchor{gnutls_x509_crt_set_ca_status} 4401@deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}) 4402@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4403 4404@var{ca}: true(1) or false(0). Depending on the Certificate authority status. 4405 4406This function will set the basicConstraints certificate extension. 4407Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control 4408the pathLenConstraint field too. 4409 4410@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4411negative error value. 4412@end deftypefun 4413 4414@subheading gnutls_x509_crt_set_crl_dist_points 4415@anchor{gnutls_x509_crt_set_crl_dist_points} 4416@deftypefun {int} {gnutls_x509_crt_set_crl_dist_points} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data_string}, unsigned int @var{reason_flags}) 4417@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4418 4419@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations 4420 4421@var{data_string}: The data to be set 4422 4423@var{reason_flags}: revocation reasons 4424 4425This function will set the CRL distribution points certificate extension. 4426 4427@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4428negative error value. 4429@end deftypefun 4430 4431@subheading gnutls_x509_crt_set_crl_dist_points2 4432@anchor{gnutls_x509_crt_set_crl_dist_points2} 4433@deftypefun {int} {gnutls_x509_crt_set_crl_dist_points2} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{reason_flags}) 4434@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4435 4436@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations 4437 4438@var{data}: The data to be set 4439 4440@var{data_size}: The data size 4441 4442@var{reason_flags}: revocation reasons 4443 4444This function will set the CRL distribution points certificate extension. 4445 4446@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4447negative error value. 4448 4449@strong{Since:} 2.6.0 4450@end deftypefun 4451 4452@subheading gnutls_x509_crt_set_crq 4453@anchor{gnutls_x509_crt_set_crq} 4454@deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}) 4455@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4456 4457@var{crq}: holds a certificate request 4458 4459This function will set the name and public parameters as well as 4460the extensions from the given certificate request to the certificate. 4461Only RSA keys are currently supported. 4462 4463Note that this function will only set the @code{crq} if it is self 4464signed and the signature is correct. See @code{gnutls_x509_crq_sign2()} . 4465 4466@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4467negative error value. 4468@end deftypefun 4469 4470@subheading gnutls_x509_crt_set_crq_extension_by_oid 4471@anchor{gnutls_x509_crt_set_crq_extension_by_oid} 4472@deftypefun {int} {gnutls_x509_crt_set_crq_extension_by_oid} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{flags}) 4473@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4474 4475@var{crq}: holds a certificate request 4476 4477@var{oid}: the object identifier of the OID to copy 4478 4479@var{flags}: should be zero 4480 4481This function will set the extension specify by @code{oid} from the given request to the 4482certificate. 4483 4484@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4485negative error value. 4486 4487@strong{Since:} 3.5.1 4488@end deftypefun 4489 4490@subheading gnutls_x509_crt_set_crq_extensions 4491@anchor{gnutls_x509_crt_set_crq_extensions} 4492@deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}) 4493@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4494 4495@var{crq}: holds a certificate request 4496 4497This function will set the extensions from the given request to the 4498certificate. 4499 4500@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4501negative error value. 4502 4503@strong{Since:} 2.8.0 4504@end deftypefun 4505 4506@subheading gnutls_x509_crt_set_dn 4507@anchor{gnutls_x509_crt_set_dn} 4508@deftypefun {int} {gnutls_x509_crt_set_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err}) 4509@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4510 4511@var{dn}: a comma separated DN string (RFC4514) 4512 4513@var{err}: indicates the error position (if any) 4514 4515This function will set the DN on the provided certificate. 4516The input string should be plain ASCII or UTF-8 encoded. On 4517DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. 4518 4519Note that DNs are not expected to hold DNS information, and thus 4520no automatic IDNA conversions are attempted when using this function. 4521If that is required (e.g., store a domain in CN), process the corresponding 4522input with @code{gnutls_idna_map()} . 4523 4524@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4525negative error value. 4526@end deftypefun 4527 4528@subheading gnutls_x509_crt_set_dn_by_oid 4529@anchor{gnutls_x509_crt_set_dn_by_oid} 4530@deftypefun {int} {gnutls_x509_crt_set_dn_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) 4531@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4532 4533@var{oid}: holds an Object Identifier in a null terminated string 4534 4535@var{raw_flag}: must be 0, or 1 if the data are DER encoded 4536 4537@var{name}: a pointer to the name 4538 4539@var{sizeof_name}: holds the size of @code{name} 4540 4541This function will set the part of the name of the Certificate 4542subject, specified by the given OID. The input string should be 4543ASCII or UTF-8 encoded. 4544 4545Some helper macros with popular OIDs can be found in gnutls/x509.h 4546With this function you can only set the known OIDs. You can test 4547for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are 4548not known (by gnutls) you should properly DER encode your data, 4549and call this function with @code{raw_flag} set. 4550 4551@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4552negative error value. 4553@end deftypefun 4554 4555@subheading gnutls_x509_crt_set_expiration_time 4556@anchor{gnutls_x509_crt_set_expiration_time} 4557@deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time}) 4558@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4559 4560@var{exp_time}: The actual time 4561 4562This function will set the time this Certificate will expire. 4563Setting an expiration time to (time_t)-1 will set 4564to the no well-defined expiration date value. 4565 4566@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4567negative error value. 4568@end deftypefun 4569 4570@subheading gnutls_x509_crt_set_extension_by_oid 4571@anchor{gnutls_x509_crt_set_extension_by_oid} 4572@deftypefun {int} {gnutls_x509_crt_set_extension_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{buf}, size_t @var{sizeof_buf}, unsigned int @var{critical}) 4573@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4574 4575@var{oid}: holds an Object Identifier in null terminated string 4576 4577@var{buf}: a pointer to a DER encoded data 4578 4579@var{sizeof_buf}: holds the size of @code{buf} 4580 4581@var{critical}: should be non-zero if the extension is to be marked as critical 4582 4583This function will set an the extension, by the specified OID, in 4584the certificate. The extension data should be binary data DER 4585encoded. 4586 4587@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4588negative error value. 4589@end deftypefun 4590 4591@subheading gnutls_x509_crt_set_flags 4592@anchor{gnutls_x509_crt_set_flags} 4593@deftypefun {void} {gnutls_x509_crt_set_flags} (gnutls_x509_crt_t @var{cert}, unsigned int @var{flags}) 4594@var{cert}: A type @code{gnutls_x509_crt_t} 4595 4596@var{flags}: flags from the @code{gnutls_x509_crt_flags} 4597 4598This function will set flags for the specified certificate. 4599Currently this is useful for the @code{GNUTLS_X509_CRT_FLAG_IGNORE_SANITY} 4600which allows importing certificates even if they have known issues. 4601 4602@strong{Since:} 3.6.0 4603@end deftypefun 4604 4605@subheading gnutls_x509_crt_set_inhibit_anypolicy 4606@anchor{gnutls_x509_crt_set_inhibit_anypolicy} 4607@deftypefun {int} {gnutls_x509_crt_set_inhibit_anypolicy} (gnutls_x509_crt_t @var{crt}, unsigned int @var{skipcerts}) 4608@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4609 4610@var{skipcerts}: number of certificates after which anypolicy is no longer acceptable. 4611 4612This function will set the Inhibit anyPolicy certificate extension. 4613 4614@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4615negative error value. 4616@end deftypefun 4617 4618@subheading gnutls_x509_crt_set_issuer_alt_name 4619@anchor{gnutls_x509_crt_set_issuer_alt_name} 4620@deftypefun {int} {gnutls_x509_crt_set_issuer_alt_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 4621@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4622 4623@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations 4624 4625@var{data}: The data to be set 4626 4627@var{data_size}: The size of data to be set 4628 4629@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. 4630 4631This function will set the issuer alternative name certificate 4632extension. It can set the same types as @code{gnutls_x509_crt_set_subject_alt_name()} . 4633 4634Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and 4635@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. 4636 4637@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4638negative error value. 4639 4640@strong{Since:} 3.3.0 4641@end deftypefun 4642 4643@subheading gnutls_x509_crt_set_issuer_alt_othername 4644@anchor{gnutls_x509_crt_set_issuer_alt_othername} 4645@deftypefun {int} {gnutls_x509_crt_set_issuer_alt_othername} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 4646@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4647 4648@var{oid}: The other name OID 4649 4650@var{data}: The data to be set 4651 4652@var{data_size}: The size of data to be set 4653 4654@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. 4655 4656This function will set an "othername" to the issuer alternative name certificate 4657extension. 4658 4659The values set are set as binary values and are expected to have the proper DER encoding. 4660For convenience the flags @code{GNUTLS_FSAN_ENCODE_OCTET_STRING} and @code{GNUTLS_FSAN_ENCODE_UTF8_STRING} 4661can be used to encode the provided data. 4662 4663@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4664negative error value. 4665 4666@strong{Since:} 3.5.0 4667@end deftypefun 4668 4669@subheading gnutls_x509_crt_set_issuer_dn 4670@anchor{gnutls_x509_crt_set_issuer_dn} 4671@deftypefun {int} {gnutls_x509_crt_set_issuer_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err}) 4672@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4673 4674@var{dn}: a comma separated DN string (RFC4514) 4675 4676@var{err}: indicates the error position (if any) 4677 4678This function will set the DN on the provided certificate. 4679The input string should be plain ASCII or UTF-8 encoded. On 4680DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. 4681 4682@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4683negative error value. 4684@end deftypefun 4685 4686@subheading gnutls_x509_crt_set_issuer_dn_by_oid 4687@anchor{gnutls_x509_crt_set_issuer_dn_by_oid} 4688@deftypefun {int} {gnutls_x509_crt_set_issuer_dn_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) 4689@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4690 4691@var{oid}: holds an Object Identifier in a null terminated string 4692 4693@var{raw_flag}: must be 0, or 1 if the data are DER encoded 4694 4695@var{name}: a pointer to the name 4696 4697@var{sizeof_name}: holds the size of @code{name} 4698 4699This function will set the part of the name of the Certificate 4700issuer, specified by the given OID. The input string should be 4701ASCII or UTF-8 encoded. 4702 4703Some helper macros with popular OIDs can be found in gnutls/x509.h 4704With this function you can only set the known OIDs. You can test 4705for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are 4706not known (by gnutls) you should properly DER encode your data, 4707and call this function with @code{raw_flag} set. 4708 4709Normally you do not need to call this function, since the signing 4710operation will copy the signer's name as the issuer of the 4711certificate. 4712 4713@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4714negative error value. 4715@end deftypefun 4716 4717@subheading gnutls_x509_crt_set_issuer_unique_id 4718@anchor{gnutls_x509_crt_set_issuer_unique_id} 4719@deftypefun {int} {gnutls_x509_crt_set_issuer_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) 4720@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4721 4722@var{id}: The unique ID 4723 4724@var{id_size}: Holds the size of the unique ID. 4725 4726This function will set the X.509 certificate's issuer unique ID field. 4727 4728@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4729negative error value. 4730 4731@strong{Since:} 3.4.7 4732@end deftypefun 4733 4734@subheading gnutls_x509_crt_set_key 4735@anchor{gnutls_x509_crt_set_key} 4736@deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key}) 4737@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4738 4739@var{key}: holds a private key 4740 4741This function will set the public parameters from the given 4742private key to the certificate. 4743 4744To export the public key (i.e., the SubjectPublicKeyInfo part), check 4745@code{gnutls_pubkey_import_x509()} . 4746 4747@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4748negative error value. 4749@end deftypefun 4750 4751@subheading gnutls_x509_crt_set_key_purpose_oid 4752@anchor{gnutls_x509_crt_set_key_purpose_oid} 4753@deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical}) 4754@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4755 4756@var{oid}: a pointer to a null terminated string that holds the OID 4757 4758@var{critical}: Whether this extension will be critical or not 4759 4760This function will set the key purpose OIDs of the Certificate. 4761These are stored in the Extended Key Usage extension (2.5.29.37) 4762See the GNUTLS_KP_* definitions for human readable names. 4763 4764Subsequent calls to this function will append OIDs to the OID list. 4765 4766@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 4767otherwise a negative error code is returned. 4768@end deftypefun 4769 4770@subheading gnutls_x509_crt_set_key_usage 4771@anchor{gnutls_x509_crt_set_key_usage} 4772@deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage}) 4773@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4774 4775@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. 4776 4777This function will set the keyUsage certificate extension. 4778 4779@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4780negative error value. 4781@end deftypefun 4782 4783@subheading gnutls_x509_crt_set_name_constraints 4784@anchor{gnutls_x509_crt_set_name_constraints} 4785@deftypefun {int} {gnutls_x509_crt_set_name_constraints} (gnutls_x509_crt_t @var{crt}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{critical}) 4786@var{crt}: The certificate 4787 4788@var{nc}: The nameconstraints structure 4789 4790@var{critical}: whether this extension will be critical 4791 4792This function will set the provided name constraints to 4793the certificate extension list. This extension is always 4794marked as critical. 4795 4796@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 4797 4798@strong{Since:} 3.3.0 4799@end deftypefun 4800 4801@subheading gnutls_x509_crt_set_pin_function 4802@anchor{gnutls_x509_crt_set_pin_function} 4803@deftypefun {void} {gnutls_x509_crt_set_pin_function} (gnutls_x509_crt_t @var{crt}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 4804@var{crt}: The certificate structure 4805 4806@var{fn}: the callback 4807 4808@var{userdata}: data associated with the callback 4809 4810This function will set a callback function to be used when 4811it is required to access a protected object. This function overrides 4812the global function set using @code{gnutls_pkcs11_set_pin_function()} . 4813 4814Note that this callback is currently used only during the import 4815of a PKCS @code{11} certificate with @code{gnutls_x509_crt_import_url()} . 4816 4817@strong{Since:} 3.1.0 4818@end deftypefun 4819 4820@subheading gnutls_x509_crt_set_policy 4821@anchor{gnutls_x509_crt_set_policy} 4822@deftypefun {int} {gnutls_x509_crt_set_policy} (gnutls_x509_crt_t @var{crt}, const struct gnutls_x509_policy_st * @var{policy}, unsigned int @var{critical}) 4823@var{crt}: should contain a @code{gnutls_x509_crt_t} type 4824 4825@var{policy}: A pointer to a policy 4826 4827@var{critical}: use non-zero if the extension is marked as critical 4828 4829This function will set the certificate policy extension (2.5.29.32). 4830Multiple calls to this function append a new policy. 4831 4832Note the maximum text size for the qualifier @code{GNUTLS_X509_QUALIFIER_NOTICE} 4833is 200 characters. This function will fail with @code{GNUTLS_E_INVALID_REQUEST} 4834if this is exceeded. 4835 4836@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4837negative error value. 4838 4839@strong{Since:} 3.1.5 4840@end deftypefun 4841 4842@subheading gnutls_x509_crt_set_private_key_usage_period 4843@anchor{gnutls_x509_crt_set_private_key_usage_period} 4844@deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration}) 4845@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4846 4847@var{activation}: The activation time 4848 4849@var{expiration}: The expiration time 4850 4851This function will set the private key usage period extension (2.5.29.16). 4852 4853@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4854negative error value. 4855@end deftypefun 4856 4857@subheading gnutls_x509_crt_set_proxy 4858@anchor{gnutls_x509_crt_set_proxy} 4859@deftypefun {int} {gnutls_x509_crt_set_proxy} (gnutls_x509_crt_t @var{crt}, int @var{pathLenConstraint}, const char * @var{policyLanguage}, const char * @var{policy}, size_t @var{sizeof_policy}) 4860@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4861 4862@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, 4863and negative error codes indicate that the pathLenConstraints field should 4864not be present. 4865 4866@var{policyLanguage}: OID describing the language of @code{policy} . 4867 4868@var{policy}: uint8_t byte array with policy language, can be @code{NULL} 4869 4870@var{sizeof_policy}: size of @code{policy} . 4871 4872This function will set the proxyCertInfo extension. 4873 4874@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4875negative error value. 4876@end deftypefun 4877 4878@subheading gnutls_x509_crt_set_proxy_dn 4879@anchor{gnutls_x509_crt_set_proxy_dn} 4880@deftypefun {int} {gnutls_x509_crt_set_proxy_dn} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{eecrt}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) 4881@var{crt}: a gnutls_x509_crt_t type with the new proxy cert 4882 4883@var{eecrt}: the end entity certificate that will be issuing the proxy 4884 4885@var{raw_flag}: must be 0, or 1 if the CN is DER encoded 4886 4887@var{name}: a pointer to the CN name, may be NULL (but MUST then be added later) 4888 4889@var{sizeof_name}: holds the size of @code{name} 4890 4891This function will set the subject in @code{crt} to the end entity's 4892 @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy 4893certificate naming style. Note that if @code{name} is @code{NULL} , you MUST 4894set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar. 4895 4896@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4897negative error value. 4898@end deftypefun 4899 4900@subheading gnutls_x509_crt_set_serial 4901@anchor{gnutls_x509_crt_set_serial} 4902@deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size}) 4903@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 4904 4905@var{serial}: The serial number 4906 4907@var{serial_size}: Holds the size of the serial field. 4908 4909This function will set the X.509 certificate's serial number. 4910While the serial number is an integer, it is often handled 4911as an opaque field by several CAs. For this reason this function 4912accepts any kind of data as a serial number. To be consistent 4913with the X.509/PKIX specifications the provided @code{serial} should be 4914a big-endian positive number (i.e. it's leftmost bit should be zero). 4915 4916The size of the serial is restricted to 20 bytes maximum by RFC5280. 4917This function allows writing more than 20 bytes but the generated 4918certificates in that case may be rejected by other implementations. 4919 4920@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4921negative error value. 4922@end deftypefun 4923 4924@subheading gnutls_x509_crt_set_spki 4925@anchor{gnutls_x509_crt_set_spki} 4926@deftypefun {int} {gnutls_x509_crt_set_spki} (gnutls_x509_crt_t @var{crt}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 4927@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4928 4929@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 4930 4931@var{flags}: must be zero 4932 4933This function will set the certificate's subject public key 4934information explicitly. This is intended to be used in the cases 4935where a single public key (e.g., RSA) can be used for multiple 4936signature algorithms (RSA PKCS1-1.5, and RSA-PSS). 4937 4938To export the public key (i.e., the SubjectPublicKeyInfo part), check 4939@code{gnutls_pubkey_import_x509()} . 4940 4941@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4942negative error value. 4943 4944@strong{Since:} 3.6.0 4945@end deftypefun 4946 4947@subheading gnutls_x509_crt_set_subject_alt_name 4948@anchor{gnutls_x509_crt_set_subject_alt_name} 4949@deftypefun {int} {gnutls_x509_crt_set_subject_alt_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 4950@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4951 4952@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations 4953 4954@var{data}: The data to be set 4955 4956@var{data_size}: The size of data to be set 4957 4958@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. 4959 4960This function will set the subject alternative name certificate 4961extension. It can set the following types: @code{GNUTLS_SAN_DNSNAME} as a text string, 4962@code{GNUTLS_SAN_RFC822NAME} as a text string, @code{GNUTLS_SAN_URI} as a text string, 4963@code{GNUTLS_SAN_IPADDRESS} as a binary IP address (4 or 16 bytes), 4964@code{GNUTLS_SAN_OTHERNAME_XMPP} as a UTF8 string (since 3.5.0). 4965 4966Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and 4967@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. 4968 4969@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4970negative error value. 4971 4972@strong{Since:} 2.6.0 4973@end deftypefun 4974 4975@subheading gnutls_x509_crt_set_subject_alt_othername 4976@anchor{gnutls_x509_crt_set_subject_alt_othername} 4977@deftypefun {int} {gnutls_x509_crt_set_subject_alt_othername} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) 4978@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 4979 4980@var{oid}: The other name OID 4981 4982@var{data}: The data to be set 4983 4984@var{data_size}: The size of data to be set 4985 4986@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. 4987 4988This function will set an "othername" to the subject alternative name certificate 4989extension. 4990 4991The values set are set as binary values and are expected to have the proper DER encoding. 4992For convenience the flags @code{GNUTLS_FSAN_ENCODE_OCTET_STRING} and @code{GNUTLS_FSAN_ENCODE_UTF8_STRING} 4993can be used to encode the provided data. 4994 4995@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 4996negative error value. 4997 4998@strong{Since:} 3.5.0 4999@end deftypefun 5000 5001@subheading gnutls_x509_crt_set_subject_alternative_name 5002@anchor{gnutls_x509_crt_set_subject_alternative_name} 5003@deftypefun {int} {gnutls_x509_crt_set_subject_alternative_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const char * @var{data_string}) 5004@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 5005 5006@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations 5007 5008@var{data_string}: The data to be set, a (0) terminated string 5009 5010This function will set the subject alternative name certificate 5011extension. This function assumes that data can be expressed as a null 5012terminated string. 5013 5014The name of the function is unfortunate since it is inconsistent with 5015@code{gnutls_x509_crt_get_subject_alt_name()} . 5016 5017See @code{gnutls_x509_crt_set_subject_alt_name()} for more information. 5018 5019@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5020negative error value. 5021@end deftypefun 5022 5023@subheading gnutls_x509_crt_set_subject_key_id 5024@anchor{gnutls_x509_crt_set_subject_key_id} 5025@deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) 5026@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 5027 5028@var{id}: The key ID 5029 5030@var{id_size}: Holds the size of the subject key ID field. 5031 5032This function will set the X.509 certificate's subject key ID 5033extension. 5034 5035@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5036negative error value. 5037@end deftypefun 5038 5039@subheading gnutls_x509_crt_set_subject_unique_id 5040@anchor{gnutls_x509_crt_set_subject_unique_id} 5041@deftypefun {int} {gnutls_x509_crt_set_subject_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) 5042@var{cert}: a certificate of type @code{gnutls_x509_crt_t} 5043 5044@var{id}: The unique ID 5045 5046@var{id_size}: Holds the size of the unique ID. 5047 5048This function will set the X.509 certificate's subject unique ID field. 5049 5050@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5051negative error value. 5052 5053@strong{Since:} 3.4.7 5054@end deftypefun 5055 5056@subheading gnutls_x509_crt_set_tlsfeatures 5057@anchor{gnutls_x509_crt_set_tlsfeatures} 5058@deftypefun {int} {gnutls_x509_crt_set_tlsfeatures} (gnutls_x509_crt_t @var{crt}, gnutls_x509_tlsfeatures_t @var{features}) 5059@var{crt}: A X.509 certificate 5060 5061@var{features}: If the function succeeds, the 5062features will be added to the certificate. 5063 5064This function will set the certificates 5065X.509 TLS extension from the given structure. 5066 5067@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 5068otherwise a negative error value. 5069 5070@strong{Since:} 3.5.1 5071@end deftypefun 5072 5073@subheading gnutls_x509_crt_set_version 5074@anchor{gnutls_x509_crt_set_version} 5075@deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version}) 5076@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 5077 5078@var{version}: holds the version number. For X.509v1 certificates must be 1. 5079 5080This function will set the version of the certificate. This must 5081be one for X.509 version 1, and so on. Plain certificates without 5082extensions must have version set to one. 5083 5084To create well-formed certificates, you must specify version 3 if 5085you use any certificate extensions. Extensions are created by 5086functions such as @code{gnutls_x509_crt_set_subject_alt_name()} 5087or @code{gnutls_x509_crt_set_key_usage()} . 5088 5089@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5090negative error value. 5091@end deftypefun 5092 5093@subheading gnutls_x509_crt_sign 5094@anchor{gnutls_x509_crt_sign} 5095@deftypefun {int} {gnutls_x509_crt_sign} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}) 5096@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 5097 5098@var{issuer}: is the certificate of the certificate issuer 5099 5100@var{issuer_key}: holds the issuer's private key 5101 5102This function is the same a @code{gnutls_x509_crt_sign2()} with no flags, 5103and an appropriate hash algorithm. The hash algorithm used may 5104vary between versions of GnuTLS, and it is tied to the security 5105level of the issuer's public key. 5106 5107@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5108negative error value. 5109@end deftypefun 5110 5111@subheading gnutls_x509_crt_sign2 5112@anchor{gnutls_x509_crt_sign2} 5113@deftypefun {int} {gnutls_x509_crt_sign2} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) 5114@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 5115 5116@var{issuer}: is the certificate of the certificate issuer 5117 5118@var{issuer_key}: holds the issuer's private key 5119 5120@var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA256} is a safe choice 5121 5122@var{flags}: must be 0 5123 5124This function will sign the certificate with the issuer's private key, and 5125will copy the issuer's information into the certificate. 5126 5127This must be the last step in a certificate generation since all 5128the previously set parameters are now signed. 5129 5130A known limitation of this function is, that a newly-signed certificate will not 5131be fully functional (e.g., for signature verification), until it 5132is exported an re-imported. 5133 5134After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , 5135and in that case, a suitable but reasonable for the key algorithm will be selected. 5136 5137@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5138negative error value. 5139@end deftypefun 5140 5141@subheading gnutls_x509_crt_verify 5142@anchor{gnutls_x509_crt_verify} 5143@deftypefun {int} {gnutls_x509_crt_verify} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crt_t * @var{CA_list}, unsigned @var{CA_list_length}, unsigned int @var{flags}, unsigned int * @var{verify}) 5144@var{cert}: is the certificate to be verified 5145 5146@var{CA_list}: is one certificate that is considered to be trusted one 5147 5148@var{CA_list_length}: holds the number of CA certificate in CA_list 5149 5150@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 5151 5152@var{verify}: will hold the certificate verification output. 5153 5154This function will try to verify the given certificate and return 5155its status. Note that a verification error does not imply a negative 5156return status. In that case the @code{verify} status is set. 5157 5158The details of the verification are the same 5159as in @code{gnutls_x509_trust_list_verify_crt2()} . 5160 5161@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5162negative error value. 5163@end deftypefun 5164 5165@subheading gnutls_x509_crt_verify_data2 5166@anchor{gnutls_x509_crt_verify_data2} 5167@deftypefun {int} {gnutls_x509_crt_verify_data2} (gnutls_x509_crt_t @var{crt}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature}) 5168@var{crt}: Holds the certificate to verify with 5169 5170@var{algo}: The signature algorithm used 5171 5172@var{flags}: Zero or an OR list of @code{gnutls_certificate_verify_flags} 5173 5174@var{data}: holds the signed data 5175 5176@var{signature}: contains the signature 5177 5178This function will verify the given signed data, using the 5179parameters from the certificate. 5180 5181@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED} 5182is returned, @code{GNUTLS_E_EXPIRED} or @code{GNUTLS_E_NOT_YET_ACTIVATED} on expired 5183or not yet activated certificate and zero or positive code on success. 5184 5185Note that since GnuTLS 3.5.6 this function introduces checks in the 5186end certificate ( @code{crt} ), including time checks and key usage checks. 5187 5188@strong{Since:} 3.4.0 5189@end deftypefun 5190 5191@subheading gnutls_x509_dn_deinit 5192@anchor{gnutls_x509_dn_deinit} 5193@deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn}) 5194@var{dn}: a DN uint8_t object pointer. 5195 5196This function deallocates the DN object as returned by 5197@code{gnutls_x509_dn_import()} . 5198 5199@strong{Since:} 2.4.0 5200@end deftypefun 5201 5202@subheading gnutls_x509_dn_export 5203@anchor{gnutls_x509_dn_export} 5204@deftypefun {int} {gnutls_x509_dn_export} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) 5205@var{dn}: Holds the uint8_t DN object 5206 5207@var{format}: the format of output params. One of PEM or DER. 5208 5209@var{output_data}: will contain a DN PEM or DER encoded 5210 5211@var{output_data_size}: holds the size of output_data (and will be 5212replaced by the actual size of parameters) 5213 5214This function will export the DN to DER or PEM format. 5215 5216If the buffer provided is not long enough to hold the output, then 5217* @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} 5218will be returned. 5219 5220If the structure is PEM encoded, it will have a header 5221of "BEGIN NAME". 5222 5223@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5224negative error value. 5225@end deftypefun 5226 5227@subheading gnutls_x509_dn_export2 5228@anchor{gnutls_x509_dn_export2} 5229@deftypefun {int} {gnutls_x509_dn_export2} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 5230@var{dn}: Holds the uint8_t DN object 5231 5232@var{format}: the format of output params. One of PEM or DER. 5233 5234@var{out}: will contain a DN PEM or DER encoded 5235 5236This function will export the DN to DER or PEM format. 5237 5238The output buffer is allocated using @code{gnutls_malloc()} . 5239 5240If the structure is PEM encoded, it will have a header 5241of "BEGIN NAME". 5242 5243@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5244negative error value. 5245 5246@strong{Since:} 3.1.3 5247@end deftypefun 5248 5249@subheading gnutls_x509_dn_get_rdn_ava 5250@anchor{gnutls_x509_dn_get_rdn_ava} 5251@deftypefun {int} {gnutls_x509_dn_get_rdn_ava} (gnutls_x509_dn_t @var{dn}, int @var{irdn}, int @var{iava}, gnutls_x509_ava_st * @var{ava}) 5252@var{dn}: a pointer to DN 5253 5254@var{irdn}: index of RDN 5255 5256@var{iava}: index of AVA. 5257 5258@var{ava}: Pointer to structure which will hold output information. 5259 5260Get pointers to data within the DN. The format of the @code{ava} structure 5261is shown below. 5262 5263struct gnutls_x509_ava_st @{ 5264gnutls_datum_t oid; 5265gnutls_datum_t value; 5266unsigned long value_tag; 5267@}; 5268 5269The X.509 distinguished name is a sequence of sequences of strings 5270and this is what the @code{irdn} and @code{iava} indexes model. 5271 5272Note that @code{ava} will contain pointers into the @code{dn} structure which 5273in turns points to the original certificate. Thus you should not 5274modify any data or deallocate any of those. 5275 5276This is a low-level function that requires the caller to do the 5277value conversions when necessary (e.g. from UCS-2). 5278 5279@strong{Returns:} Returns 0 on success, or an error code. 5280@end deftypefun 5281 5282@subheading gnutls_x509_dn_get_str 5283@anchor{gnutls_x509_dn_get_str} 5284@deftypefun {int} {gnutls_x509_dn_get_str} (gnutls_x509_dn_t @var{dn}, gnutls_datum_t * @var{str}) 5285@var{dn}: a pointer to DN 5286 5287@var{str}: a datum that will hold the name 5288 5289This function will allocate buffer and copy the name in the provided DN. 5290The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 5291described in RFC4514. The output string will be ASCII or UTF-8 5292encoded, depending on the certificate data. 5293 5294@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5295negative error value. 5296 5297@strong{Since:} 3.4.2 5298@end deftypefun 5299 5300@subheading gnutls_x509_dn_get_str2 5301@anchor{gnutls_x509_dn_get_str2} 5302@deftypefun {int} {gnutls_x509_dn_get_str2} (gnutls_x509_dn_t @var{dn}, gnutls_datum_t * @var{str}, unsigned @var{flags}) 5303@var{dn}: a pointer to DN 5304 5305@var{str}: a datum that will hold the name 5306 5307@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} 5308 5309This function will allocate buffer and copy the name in the provided DN. 5310The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as 5311described in RFC4514. The output string will be ASCII or UTF-8 5312encoded, depending on the certificate data. 5313 5314When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 5315format will match the format output by previous to 3.5.6 versions of GnuTLS 5316which was not not fully RFC4514-compliant. 5317 5318@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5319negative error value. 5320 5321@strong{Since:} 3.5.7 5322@end deftypefun 5323 5324@subheading gnutls_x509_dn_import 5325@anchor{gnutls_x509_dn_import} 5326@deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data}) 5327@var{dn}: the structure that will hold the imported DN 5328 5329@var{data}: should contain a DER encoded RDN sequence 5330 5331This function parses an RDN sequence and stores the result to a 5332@code{gnutls_x509_dn_t} type. The data must have been initialized 5333with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to 5334decode the DN. 5335 5336@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5337negative error value. 5338 5339@strong{Since:} 2.4.0 5340@end deftypefun 5341 5342@subheading gnutls_x509_dn_init 5343@anchor{gnutls_x509_dn_init} 5344@deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn}) 5345@var{dn}: the object to be initialized 5346 5347This function initializes a @code{gnutls_x509_dn_t} type. 5348 5349The object returned must be deallocated using 5350@code{gnutls_x509_dn_deinit()} . 5351 5352@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5353negative error value. 5354 5355@strong{Since:} 2.4.0 5356@end deftypefun 5357 5358@subheading gnutls_x509_dn_oid_known 5359@anchor{gnutls_x509_dn_oid_known} 5360@deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid}) 5361@var{oid}: holds an Object Identifier in a null terminated string 5362 5363This function will inform about known DN OIDs. This is useful since 5364functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information 5365on known OIDs to properly encode their input. Object Identifiers 5366that are not known are not encoded by these functions, and their 5367input is stored directly into the ASN.1 structure. In that case of 5368unknown OIDs, you have the responsibility of DER encoding your 5369data. 5370 5371@strong{Returns:} 1 on known OIDs and 0 otherwise. 5372@end deftypefun 5373 5374@subheading gnutls_x509_dn_oid_name 5375@anchor{gnutls_x509_dn_oid_name} 5376@deftypefun {const char *} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags}) 5377@var{oid}: holds an Object Identifier in a null terminated string 5378 5379@var{flags}: 0 or GNUTLS_X509_DN_OID_* 5380 5381This function will return the name of a known DN OID. If 5382@code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function 5383will return the given OID if no descriptive name has been 5384found. 5385 5386@strong{Returns:} A null terminated string or NULL otherwise. 5387 5388@strong{Since:} 3.0 5389@end deftypefun 5390 5391@subheading gnutls_x509_dn_set_str 5392@anchor{gnutls_x509_dn_set_str} 5393@deftypefun {int} {gnutls_x509_dn_set_str} (gnutls_x509_dn_t @var{dn}, const char * @var{str}, const char ** @var{err}) 5394@var{dn}: a pointer to DN 5395 5396@var{str}: a comma separated DN string (RFC4514) 5397 5398@var{err}: indicates the error position (if any) 5399 5400This function will set the DN on the provided DN structure. 5401The input string should be plain ASCII or UTF-8 encoded. On 5402DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. 5403 5404@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5405negative error value. 5406 5407@strong{Since:} 3.5.3 5408@end deftypefun 5409 5410@subheading gnutls_x509_ext_deinit 5411@anchor{gnutls_x509_ext_deinit} 5412@deftypefun {void} {gnutls_x509_ext_deinit} (gnutls_x509_ext_st * @var{ext}) 5413@var{ext}: The extensions structure 5414 5415This function will deinitialize an extensions structure. 5416 5417@strong{Since:} 3.3.8 5418@end deftypefun 5419 5420@subheading gnutls_x509_ext_export_aia 5421@anchor{gnutls_x509_ext_export_aia} 5422@deftypefun {int} {gnutls_x509_ext_export_aia} (gnutls_x509_aia_t @var{aia}, gnutls_datum_t * @var{ext}) 5423@var{aia}: The authority info access 5424 5425@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5426 5427This function will DER encode the Authority Information Access (AIA) 5428extension; see RFC 5280 section 4.2.2.1 for more information on the 5429extension. 5430 5431@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5432negative error value. 5433 5434@strong{Since:} 3.3.0 5435@end deftypefun 5436 5437@subheading gnutls_x509_ext_export_authority_key_id 5438@anchor{gnutls_x509_ext_export_authority_key_id} 5439@deftypefun {int} {gnutls_x509_ext_export_authority_key_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{ext}) 5440@var{aki}: An initialized authority key identifier 5441 5442@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5443 5444This function will convert the provided key identifier to a 5445DER-encoded PKIX AuthorityKeyIdentifier extension. 5446The output data in @code{ext} will be allocated using 5447@code{gnutls_malloc()} . 5448 5449@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5450 5451@strong{Since:} 3.3.0 5452@end deftypefun 5453 5454@subheading gnutls_x509_ext_export_basic_constraints 5455@anchor{gnutls_x509_ext_export_basic_constraints} 5456@deftypefun {int} {gnutls_x509_ext_export_basic_constraints} (unsigned int @var{ca}, int @var{pathlen}, gnutls_datum_t * @var{ext}) 5457@var{ca}: non-zero for a CA 5458 5459@var{pathlen}: The path length constraint (set to -1 for no constraint) 5460 5461@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5462 5463This function will convert the parameters provided to a basic constraints 5464DER encoded extension (2.5.29.19). 5465The @code{ext} data will be allocated using 5466@code{gnutls_malloc()} . 5467 5468@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5469negative error value. 5470 5471@strong{Since:} 3.3.0 5472@end deftypefun 5473 5474@subheading gnutls_x509_ext_export_crl_dist_points 5475@anchor{gnutls_x509_ext_export_crl_dist_points} 5476@deftypefun {int} {gnutls_x509_ext_export_crl_dist_points} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_datum_t * @var{ext}) 5477@var{cdp}: A pointer to an initialized CRL distribution points. 5478 5479@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5480 5481This function will convert the provided policies, to a certificate policy 5482DER encoded extension (2.5.29.31). 5483 5484The @code{ext} data will be allocated using @code{gnutls_malloc()} . 5485 5486@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5487 5488@strong{Since:} 3.3.0 5489@end deftypefun 5490 5491@subheading gnutls_x509_ext_export_inhibit_anypolicy 5492@anchor{gnutls_x509_ext_export_inhibit_anypolicy} 5493@deftypefun {int} {gnutls_x509_ext_export_inhibit_anypolicy} (unsigned int @var{skipcerts}, gnutls_datum_t * @var{ext}) 5494@var{skipcerts}: number of certificates after which anypolicy is no longer acceptable. 5495 5496@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5497 5498This function will convert the @code{skipcerts} value to a DER 5499encoded Inhibit AnyPolicy PKIX extension. The @code{ext} data will be allocated using 5500@code{gnutls_malloc()} . 5501 5502@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5503negative error value. 5504 5505@strong{Since:} 3.6.0 5506@end deftypefun 5507 5508@subheading gnutls_x509_ext_export_key_purposes 5509@anchor{gnutls_x509_ext_export_key_purposes} 5510@deftypefun {int} {gnutls_x509_ext_export_key_purposes} (gnutls_x509_key_purposes_t @var{p}, gnutls_datum_t * @var{ext}) 5511@var{p}: The key purposes 5512 5513@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5514 5515This function will convert the key purposes type to a 5516DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in 5517 @code{ext} will be allocated using @code{gnutls_malloc()} . 5518 5519@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5520 5521@strong{Since:} 3.3.0 5522@end deftypefun 5523 5524@subheading gnutls_x509_ext_export_key_usage 5525@anchor{gnutls_x509_ext_export_key_usage} 5526@deftypefun {int} {gnutls_x509_ext_export_key_usage} (unsigned int @var{usage}, gnutls_datum_t * @var{ext}) 5527@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. 5528 5529@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5530 5531This function will convert the keyUsage bit string to a DER 5532encoded PKIX extension. The @code{ext} data will be allocated using 5533@code{gnutls_malloc()} . 5534 5535@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5536negative error value. 5537 5538@strong{Since:} 3.3.0 5539@end deftypefun 5540 5541@subheading gnutls_x509_ext_export_name_constraints 5542@anchor{gnutls_x509_ext_export_name_constraints} 5543@deftypefun {int} {gnutls_x509_ext_export_name_constraints} (gnutls_x509_name_constraints_t @var{nc}, gnutls_datum_t * @var{ext}) 5544@var{nc}: The nameconstraints 5545 5546@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5547 5548This function will convert the provided name constraints type to a 5549DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in 5550 @code{ext} will be allocated using @code{gnutls_malloc()} . 5551 5552@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5553 5554@strong{Since:} 3.3.0 5555@end deftypefun 5556 5557@subheading gnutls_x509_ext_export_policies 5558@anchor{gnutls_x509_ext_export_policies} 5559@deftypefun {int} {gnutls_x509_ext_export_policies} (gnutls_x509_policies_t @var{policies}, gnutls_datum_t * @var{ext}) 5560@var{policies}: A pointer to an initialized policies. 5561 5562@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5563 5564This function will convert the provided policies, to a certificate policy 5565DER encoded extension (2.5.29.32). 5566 5567The @code{ext} data will be allocated using @code{gnutls_malloc()} . 5568 5569@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5570 5571@strong{Since:} 3.3.0 5572@end deftypefun 5573 5574@subheading gnutls_x509_ext_export_private_key_usage_period 5575@anchor{gnutls_x509_ext_export_private_key_usage_period} 5576@deftypefun {int} {gnutls_x509_ext_export_private_key_usage_period} (time_t @var{activation}, time_t @var{expiration}, gnutls_datum_t * @var{ext}) 5577@var{activation}: The activation time 5578 5579@var{expiration}: The expiration time 5580 5581@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5582 5583This function will convert the periods provided to a private key 5584usage DER encoded extension (2.5.29.16). 5585The @code{ext} data will be allocated using 5586@code{gnutls_malloc()} . 5587 5588@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5589negative error value. 5590 5591@strong{Since:} 3.3.0 5592@end deftypefun 5593 5594@subheading gnutls_x509_ext_export_proxy 5595@anchor{gnutls_x509_ext_export_proxy} 5596@deftypefun {int} {gnutls_x509_ext_export_proxy} (int @var{pathLenConstraint}, const char * @var{policyLanguage}, const char * @var{policy}, size_t @var{sizeof_policy}, gnutls_datum_t * @var{ext}) 5597@var{pathLenConstraint}: A negative value will remove the path length constraint, 5598while non-negative values will be set as the length of the pathLenConstraints field. 5599 5600@var{policyLanguage}: OID describing the language of @code{policy} . 5601 5602@var{policy}: uint8_t byte array with policy language, can be @code{NULL} 5603 5604@var{sizeof_policy}: size of @code{policy} . 5605 5606@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5607 5608This function will convert the parameters provided to a proxyCertInfo extension. 5609 5610The @code{ext} data will be allocated using @code{gnutls_malloc()} . 5611 5612@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5613negative error value. 5614 5615@strong{Since:} 3.3.0 5616@end deftypefun 5617 5618@subheading gnutls_x509_ext_export_subject_alt_names 5619@anchor{gnutls_x509_ext_export_subject_alt_names} 5620@deftypefun {int} {gnutls_x509_ext_export_subject_alt_names} (gnutls_subject_alt_names_t @var{sans}, gnutls_datum_t * @var{ext}) 5621@var{sans}: The alternative names 5622 5623@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5624 5625This function will convert the provided alternative names structure to a 5626DER-encoded SubjectAltName PKIX extension. The output data in @code{ext} will be allocated using 5627@code{gnutls_malloc()} . 5628 5629@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5630 5631@strong{Since:} 3.3.0 5632@end deftypefun 5633 5634@subheading gnutls_x509_ext_export_subject_key_id 5635@anchor{gnutls_x509_ext_export_subject_key_id} 5636@deftypefun {int} {gnutls_x509_ext_export_subject_key_id} (const gnutls_datum_t * @var{id}, gnutls_datum_t * @var{ext}) 5637@var{id}: The key identifier 5638 5639@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5640 5641This function will convert the provided key identifier to a 5642DER-encoded PKIX SubjectKeyIdentifier extension. 5643The output data in @code{ext} will be allocated using 5644@code{gnutls_malloc()} . 5645 5646@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5647 5648@strong{Since:} 3.3.0 5649@end deftypefun 5650 5651@subheading gnutls_x509_ext_export_tlsfeatures 5652@anchor{gnutls_x509_ext_export_tlsfeatures} 5653@deftypefun {int} {gnutls_x509_ext_export_tlsfeatures} (gnutls_x509_tlsfeatures_t @var{f}, gnutls_datum_t * @var{ext}) 5654@var{f}: The features structure 5655 5656@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . 5657 5658This function will convert the provided TLS features structure structure to a 5659DER-encoded TLS features PKIX extension. The output data in @code{ext} will be allocated using 5660@code{gnutls_malloc()} . 5661 5662@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5663 5664@strong{Since:} 3.5.1 5665@end deftypefun 5666 5667@subheading gnutls_x509_ext_import_aia 5668@anchor{gnutls_x509_ext_import_aia} 5669@deftypefun {int} {gnutls_x509_ext_import_aia} (const gnutls_datum_t * @var{ext}, gnutls_x509_aia_t @var{aia}, unsigned int @var{flags}) 5670@var{ext}: The DER-encoded extension data 5671 5672@var{aia}: The authority info access 5673 5674@var{flags}: should be zero 5675 5676This function extracts the Authority Information Access (AIA) 5677extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1 5678for more information on the extension. The 5679AIA extension holds a sequence of AccessDescription (AD) data. 5680 5681@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5682 5683@strong{Since:} 3.3.0 5684@end deftypefun 5685 5686@subheading gnutls_x509_ext_import_authority_key_id 5687@anchor{gnutls_x509_ext_import_authority_key_id} 5688@deftypefun {int} {gnutls_x509_ext_import_authority_key_id} (const gnutls_datum_t * @var{ext}, gnutls_x509_aki_t @var{aki}, unsigned int @var{flags}) 5689@var{ext}: a DER encoded extension 5690 5691@var{aki}: An initialized authority key identifier type 5692 5693@var{flags}: should be zero 5694 5695This function will return the subject key ID stored in the provided 5696AuthorityKeyIdentifier extension. 5697 5698@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 5699if the extension is not present, otherwise a negative error value. 5700 5701@strong{Since:} 3.3.0 5702@end deftypefun 5703 5704@subheading gnutls_x509_ext_import_basic_constraints 5705@anchor{gnutls_x509_ext_import_basic_constraints} 5706@deftypefun {int} {gnutls_x509_ext_import_basic_constraints} (const gnutls_datum_t * @var{ext}, unsigned int * @var{ca}, int * @var{pathlen}) 5707@var{ext}: the DER encoded extension data 5708 5709@var{ca}: will be non zero if the CA status is true 5710 5711@var{pathlen}: the path length constraint; will be set to -1 for no limit 5712 5713This function will return the CA status and path length constraint 5714as written in the PKIX extension 2.5.29.19. 5715 5716@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5717negative error value. 5718 5719@strong{Since:} 3.3.0 5720@end deftypefun 5721 5722@subheading gnutls_x509_ext_import_crl_dist_points 5723@anchor{gnutls_x509_ext_import_crl_dist_points} 5724@deftypefun {int} {gnutls_x509_ext_import_crl_dist_points} (const gnutls_datum_t * @var{ext}, gnutls_x509_crl_dist_points_t @var{cdp}, unsigned int @var{flags}) 5725@var{ext}: the DER encoded extension data 5726 5727@var{cdp}: A pointer to an initialized CRL distribution points. 5728 5729@var{flags}: should be zero 5730 5731This function will extract the CRL distribution points extension (2.5.29.31) 5732and store it into the provided type. 5733 5734@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5735 5736@strong{Since:} 3.3.0 5737@end deftypefun 5738 5739@subheading gnutls_x509_ext_import_inhibit_anypolicy 5740@anchor{gnutls_x509_ext_import_inhibit_anypolicy} 5741@deftypefun {int} {gnutls_x509_ext_import_inhibit_anypolicy} (const gnutls_datum_t * @var{ext}, unsigned int * @var{skipcerts}) 5742@var{ext}: the DER encoded extension data 5743 5744@var{skipcerts}: will hold the number of certificates after which anypolicy is no longer acceptable. 5745 5746This function will return certificate's value of SkipCerts, 5747by reading the DER data of the Inhibit anyPolicy X.509 extension (2.5.29.54). 5748 5749The @code{skipcerts} value is the number of additional certificates that 5750may appear in the path before the anyPolicy (@code{GNUTLS_X509_OID_POLICY_ANY} ) 5751is no longer acceptable. 5752 5753@strong{Returns:} zero, or a negative error code in case of 5754parsing error. If the certificate does not contain the Inhibit anyPolicy 5755extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be 5756returned. 5757 5758@strong{Since:} 3.6.0 5759@end deftypefun 5760 5761@subheading gnutls_x509_ext_import_key_purposes 5762@anchor{gnutls_x509_ext_import_key_purposes} 5763@deftypefun {int} {gnutls_x509_ext_import_key_purposes} (const gnutls_datum_t * @var{ext}, gnutls_x509_key_purposes_t @var{p}, unsigned int @var{flags}) 5764@var{ext}: The DER-encoded extension data 5765 5766@var{p}: The key purposes 5767 5768@var{flags}: should be zero 5769 5770This function will extract the key purposes in the provided DER-encoded 5771ExtKeyUsageSyntax PKIX extension, to a @code{gnutls_x509_key_purposes_t} type. 5772The data must be initialized. 5773 5774@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5775 5776@strong{Since:} 3.3.0 5777@end deftypefun 5778 5779@subheading gnutls_x509_ext_import_key_usage 5780@anchor{gnutls_x509_ext_import_key_usage} 5781@deftypefun {int} {gnutls_x509_ext_import_key_usage} (const gnutls_datum_t * @var{ext}, unsigned int * @var{key_usage}) 5782@var{ext}: the DER encoded extension data 5783 5784@var{key_usage}: where the key usage bits will be stored 5785 5786This function will return certificate's key usage, by reading the DER 5787data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed 5788values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , 5789@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , 5790@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , 5791@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , 5792@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . 5793 5794@strong{Returns:} the certificate key usage, or a negative error code in case of 5795parsing error. If the certificate does not contain the keyUsage 5796extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be 5797returned. 5798 5799@strong{Since:} 3.3.0 5800@end deftypefun 5801 5802@subheading gnutls_x509_ext_import_name_constraints 5803@anchor{gnutls_x509_ext_import_name_constraints} 5804@deftypefun {int} {gnutls_x509_ext_import_name_constraints} (const gnutls_datum_t * @var{ext}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{flags}) 5805@var{ext}: a DER encoded extension 5806 5807@var{nc}: The nameconstraints 5808 5809@var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} 5810 5811This function will return an intermediate type containing 5812the name constraints of the provided NameConstraints extension. That 5813can be used in combination with @code{gnutls_x509_name_constraints_check()} 5814to verify whether a server's name is in accordance with the constraints. 5815 5816When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if 5817the @code{nc} type is empty this function will behave identically as if the flag was not set. 5818Otherwise if there are elements in the @code{nc} structure then the 5819constraints will be merged with the existing constraints following 5820RFC5280 p6.1.4 (excluded constraints will be appended, permitted 5821will be intersected). 5822 5823Note that @code{nc} must be initialized prior to calling this function. 5824 5825@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 5826if the extension is not present, otherwise a negative error value. 5827 5828@strong{Since:} 3.3.0 5829@end deftypefun 5830 5831@subheading gnutls_x509_ext_import_policies 5832@anchor{gnutls_x509_ext_import_policies} 5833@deftypefun {int} {gnutls_x509_ext_import_policies} (const gnutls_datum_t * @var{ext}, gnutls_x509_policies_t @var{policies}, unsigned int @var{flags}) 5834@var{ext}: the DER encoded extension data 5835 5836@var{policies}: A pointer to an initialized policies. 5837 5838@var{flags}: should be zero 5839 5840This function will extract the certificate policy extension (2.5.29.32) 5841and store it the provided policies. 5842 5843@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5844 5845@strong{Since:} 3.3.0 5846@end deftypefun 5847 5848@subheading gnutls_x509_ext_import_private_key_usage_period 5849@anchor{gnutls_x509_ext_import_private_key_usage_period} 5850@deftypefun {int} {gnutls_x509_ext_import_private_key_usage_period} (const gnutls_datum_t * @var{ext}, time_t * @var{activation}, time_t * @var{expiration}) 5851@var{ext}: the DER encoded extension data 5852 5853@var{activation}: Will hold the activation time 5854 5855@var{expiration}: Will hold the expiration time 5856 5857This function will return the expiration and activation 5858times of the private key as written in the 5859PKIX extension 2.5.29.16. 5860 5861@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5862negative error value. 5863 5864@strong{Since:} 3.3.0 5865@end deftypefun 5866 5867@subheading gnutls_x509_ext_import_proxy 5868@anchor{gnutls_x509_ext_import_proxy} 5869@deftypefun {int} {gnutls_x509_ext_import_proxy} (const gnutls_datum_t * @var{ext}, int * @var{pathlen}, char ** @var{policyLanguage}, char ** @var{policy}, size_t * @var{sizeof_policy}) 5870@var{ext}: the DER encoded extension data 5871 5872@var{pathlen}: pointer to output integer indicating path length (may be 5873NULL), non-negative error codes indicate a present pCPathLenConstraint 5874field and the actual value, -1 indicate that the field is absent. 5875 5876@var{policyLanguage}: output variable with OID of policy language 5877 5878@var{policy}: output variable with policy data 5879 5880@var{sizeof_policy}: output variable with size of policy data 5881 5882This function will return the information from a proxy certificate 5883extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14). 5884The @code{policyLanguage} and @code{policy} values must be deinitialized using @code{gnutls_free()} after use. 5885 5886@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5887negative error value. 5888 5889@strong{Since:} 3.3.0 5890@end deftypefun 5891 5892@subheading gnutls_x509_ext_import_subject_alt_names 5893@anchor{gnutls_x509_ext_import_subject_alt_names} 5894@deftypefun {int} {gnutls_x509_ext_import_subject_alt_names} (const gnutls_datum_t * @var{ext}, gnutls_subject_alt_names_t @var{sans}, unsigned int @var{flags}) 5895@var{ext}: The DER-encoded extension data 5896 5897@var{sans}: The alternative names 5898 5899@var{flags}: should be zero 5900 5901This function will export the alternative names in the provided DER-encoded 5902SubjectAltName PKIX extension, to a @code{gnutls_subject_alt_names_t} type. @code{sans} must be initialized. 5903 5904This function will succeed even if there no subject alternative names 5905in the structure. 5906 5907@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5908 5909@strong{Since:} 3.3.0 5910@end deftypefun 5911 5912@subheading gnutls_x509_ext_import_subject_key_id 5913@anchor{gnutls_x509_ext_import_subject_key_id} 5914@deftypefun {int} {gnutls_x509_ext_import_subject_key_id} (const gnutls_datum_t * @var{ext}, gnutls_datum_t * @var{id}) 5915@var{ext}: a DER encoded extension 5916 5917@var{id}: will contain the subject key ID 5918 5919This function will return the subject key ID stored in the provided 5920SubjectKeyIdentifier extension. The ID will be allocated using 5921@code{gnutls_malloc()} . 5922 5923@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 5924if the extension is not present, otherwise a negative error value. 5925 5926@strong{Since:} 3.3.0 5927@end deftypefun 5928 5929@subheading gnutls_x509_ext_import_tlsfeatures 5930@anchor{gnutls_x509_ext_import_tlsfeatures} 5931@deftypefun {int} {gnutls_x509_ext_import_tlsfeatures} (const gnutls_datum_t * @var{ext}, gnutls_x509_tlsfeatures_t @var{f}, unsigned int @var{flags}) 5932@var{ext}: The DER-encoded extension data 5933 5934@var{f}: The features structure 5935 5936@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} 5937 5938This function will export the features in the provided DER-encoded 5939TLS Features PKIX extension, to a @code{gnutls_x509_tlsfeatures_t} type. @code{f} must be initialized. 5940 5941When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , 5942then if the @code{features} structure is empty this function will behave 5943identically as if the flag was not set. Otherwise if there are elements 5944in the @code{features} structure then they will be merged with. 5945 5946@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 5947 5948@strong{Since:} 3.5.1 5949@end deftypefun 5950 5951@subheading gnutls_x509_ext_print 5952@anchor{gnutls_x509_ext_print} 5953@deftypefun {int} {gnutls_x509_ext_print} (gnutls_x509_ext_st * @var{exts}, unsigned int @var{exts_size}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) 5954@var{exts}: The data to be printed 5955 5956@var{exts_size}: the number of available structures 5957 5958@var{format}: Indicate the format to use 5959 5960@var{out}: Newly allocated datum with null terminated string. 5961 5962This function will pretty print X.509 certificate extensions, 5963suitable for display to a human. 5964 5965The output @code{out} needs to be deallocated using @code{gnutls_free()} . 5966 5967@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 5968negative error value. 5969@end deftypefun 5970 5971@subheading gnutls_x509_key_purpose_deinit 5972@anchor{gnutls_x509_key_purpose_deinit} 5973@deftypefun {void} {gnutls_x509_key_purpose_deinit} (gnutls_x509_key_purposes_t @var{p}) 5974@var{p}: The key purposes 5975 5976This function will deinitialize a key purposes type. 5977 5978@strong{Since:} 3.3.0 5979@end deftypefun 5980 5981@subheading gnutls_x509_key_purpose_get 5982@anchor{gnutls_x509_key_purpose_get} 5983@deftypefun {int} {gnutls_x509_key_purpose_get} (gnutls_x509_key_purposes_t @var{p}, unsigned @var{idx}, gnutls_datum_t * @var{oid}) 5984@var{p}: The key purposes 5985 5986@var{idx}: The index of the key purpose to retrieve 5987 5988@var{oid}: Will hold the object identifier of the key purpose (to be treated as constant) 5989 5990This function will retrieve the specified by the index key purpose in the 5991purposes type. The object identifier will be a null terminated string. 5992 5993@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 5994if the index is out of bounds, otherwise a negative error value. 5995 5996@strong{Since:} 3.3.0 5997@end deftypefun 5998 5999@subheading gnutls_x509_key_purpose_init 6000@anchor{gnutls_x509_key_purpose_init} 6001@deftypefun {int} {gnutls_x509_key_purpose_init} (gnutls_x509_key_purposes_t * @var{p}) 6002@var{p}: The key purposes 6003 6004This function will initialize an alternative names type. 6005 6006@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6007 6008@strong{Since:} 3.3.0 6009@end deftypefun 6010 6011@subheading gnutls_x509_key_purpose_set 6012@anchor{gnutls_x509_key_purpose_set} 6013@deftypefun {int} {gnutls_x509_key_purpose_set} (gnutls_x509_key_purposes_t @var{p}, const char * @var{oid}) 6014@var{p}: The key purposes 6015 6016@var{oid}: The object identifier of the key purpose 6017 6018This function will store the specified key purpose in the 6019purposes. 6020 6021@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. 6022 6023@strong{Since:} 3.3.0 6024@end deftypefun 6025 6026@subheading gnutls_x509_name_constraints_add_excluded 6027@anchor{gnutls_x509_name_constraints_add_excluded} 6028@deftypefun {int} {gnutls_x509_name_constraints_add_excluded} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) 6029@var{nc}: The nameconstraints 6030 6031@var{type}: The type of the constraints 6032 6033@var{name}: The data of the constraints 6034 6035This function will add a name constraint to the list of excluded 6036constraints. The constraints @code{type} can be any of the following types: 6037@code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} , 6038@code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address 6039in network byte order is expected, followed by its network mask (which is 60404 bytes in IPv4 or 16-bytes in IPv6). 6041 6042@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6043 6044@strong{Since:} 3.3.0 6045@end deftypefun 6046 6047@subheading gnutls_x509_name_constraints_add_permitted 6048@anchor{gnutls_x509_name_constraints_add_permitted} 6049@deftypefun {int} {gnutls_x509_name_constraints_add_permitted} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) 6050@var{nc}: The nameconstraints 6051 6052@var{type}: The type of the constraints 6053 6054@var{name}: The data of the constraints 6055 6056This function will add a name constraint to the list of permitted 6057constraints. The constraints @code{type} can be any of the following types: 6058@code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} , 6059@code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address 6060in network byte order is expected, followed by its network mask. 6061 6062@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6063 6064@strong{Since:} 3.3.0 6065@end deftypefun 6066 6067@subheading gnutls_x509_name_constraints_check 6068@anchor{gnutls_x509_name_constraints_check} 6069@deftypefun {unsigned} {gnutls_x509_name_constraints_check} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) 6070@var{nc}: the extracted name constraints 6071 6072@var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t) 6073 6074@var{name}: the name to be checked 6075 6076This function will check the provided name against the constraints in 6077 @code{nc} using the RFC5280 rules. Currently this function is limited to DNS 6078names, emails and IP addresses (of type @code{GNUTLS_SAN_DNSNAME} , 6079@code{GNUTLS_SAN_RFC822NAME} and @code{GNUTLS_SAN_IPADDRESS} ). 6080 6081@strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise. 6082 6083@strong{Since:} 3.3.0 6084@end deftypefun 6085 6086@subheading gnutls_x509_name_constraints_check_crt 6087@anchor{gnutls_x509_name_constraints_check_crt} 6088@deftypefun {unsigned} {gnutls_x509_name_constraints_check_crt} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, gnutls_x509_crt_t @var{cert}) 6089@var{nc}: the extracted name constraints 6090 6091@var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t) 6092 6093@var{cert}: the certificate to be checked 6094 6095This function will check the provided certificate names against the constraints in 6096 @code{nc} using the RFC5280 rules. It will traverse all the certificate's names and 6097alternative names. 6098 6099Currently this function is limited to DNS 6100names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ). 6101 6102@strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise. 6103 6104@strong{Since:} 3.3.0 6105@end deftypefun 6106 6107@subheading gnutls_x509_name_constraints_deinit 6108@anchor{gnutls_x509_name_constraints_deinit} 6109@deftypefun {void} {gnutls_x509_name_constraints_deinit} (gnutls_x509_name_constraints_t @var{nc}) 6110@var{nc}: The nameconstraints 6111 6112This function will deinitialize a name constraints type. 6113 6114@strong{Since:} 3.3.0 6115@end deftypefun 6116 6117@subheading gnutls_x509_name_constraints_get_excluded 6118@anchor{gnutls_x509_name_constraints_get_excluded} 6119@deftypefun {int} {gnutls_x509_name_constraints_get_excluded} (gnutls_x509_name_constraints_t @var{nc}, unsigned @var{idx}, unsigned * @var{type}, gnutls_datum_t * @var{name}) 6120@var{nc}: the extracted name constraints 6121 6122@var{idx}: the index of the constraint 6123 6124@var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t) 6125 6126@var{name}: the name in the constraint (of the specific type) 6127 6128This function will return an intermediate type containing 6129the name constraints of the provided CA certificate. That 6130structure can be used in combination with @code{gnutls_x509_name_constraints_check()} 6131to verify whether a server's name is in accordance with the constraints. 6132 6133The name should be treated as constant and valid for the lifetime of @code{nc} . 6134 6135@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 6136if the extension is not present, otherwise a negative error value. 6137 6138@strong{Since:} 3.3.0 6139@end deftypefun 6140 6141@subheading gnutls_x509_name_constraints_get_permitted 6142@anchor{gnutls_x509_name_constraints_get_permitted} 6143@deftypefun {int} {gnutls_x509_name_constraints_get_permitted} (gnutls_x509_name_constraints_t @var{nc}, unsigned @var{idx}, unsigned * @var{type}, gnutls_datum_t * @var{name}) 6144@var{nc}: the extracted name constraints 6145 6146@var{idx}: the index of the constraint 6147 6148@var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t) 6149 6150@var{name}: the name in the constraint (of the specific type) 6151 6152This function will return an intermediate type containing 6153the name constraints of the provided CA certificate. That 6154structure can be used in combination with @code{gnutls_x509_name_constraints_check()} 6155to verify whether a server's name is in accordance with the constraints. 6156 6157The name should be treated as constant and valid for the lifetime of @code{nc} . 6158 6159@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 6160if the extension is not present, otherwise a negative error value. 6161 6162@strong{Since:} 3.3.0 6163@end deftypefun 6164 6165@subheading gnutls_x509_name_constraints_init 6166@anchor{gnutls_x509_name_constraints_init} 6167@deftypefun {int} {gnutls_x509_name_constraints_init} (gnutls_x509_name_constraints_t * @var{nc}) 6168@var{nc}: The nameconstraints 6169 6170This function will initialize a name constraints type. 6171 6172@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6173 6174@strong{Since:} 3.3.0 6175@end deftypefun 6176 6177@subheading gnutls_x509_othername_to_virtual 6178@anchor{gnutls_x509_othername_to_virtual} 6179@deftypefun {int} {gnutls_x509_othername_to_virtual} (const char * @var{oid}, const gnutls_datum_t * @var{othername}, unsigned int * @var{virt_type}, gnutls_datum_t * @var{virt}) 6180@var{oid}: The othername object identifier 6181 6182@var{othername}: The othername data 6183 6184@var{virt_type}: GNUTLS_SAN_OTHERNAME_XXX 6185 6186@var{virt}: allocated printable data 6187 6188This function will parse and convert the othername data to a virtual 6189type supported by gnutls. 6190 6191@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6192 6193@strong{Since:} 3.3.8 6194@end deftypefun 6195 6196@subheading gnutls_x509_policies_deinit 6197@anchor{gnutls_x509_policies_deinit} 6198@deftypefun {void} {gnutls_x509_policies_deinit} (gnutls_x509_policies_t @var{policies}) 6199@var{policies}: The authority key identifier 6200 6201This function will deinitialize an authority key identifier type. 6202 6203@strong{Since:} 3.3.0 6204@end deftypefun 6205 6206@subheading gnutls_x509_policies_get 6207@anchor{gnutls_x509_policies_get} 6208@deftypefun {int} {gnutls_x509_policies_get} (gnutls_x509_policies_t @var{policies}, unsigned int @var{seq}, struct gnutls_x509_policy_st * @var{policy}) 6209@var{policies}: The policies 6210 6211@var{seq}: The index of the name to get 6212 6213@var{policy}: Will hold the policy 6214 6215This function will return a specific policy as stored in 6216the @code{policies} type. The returned values should be treated as constant 6217and valid for the lifetime of @code{policies} . 6218 6219The any policy OID is available as the @code{GNUTLS_X509_OID_POLICY_ANY} macro. 6220 6221@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 6222if the index is out of bounds, otherwise a negative error value. 6223 6224@strong{Since:} 3.3.0 6225@end deftypefun 6226 6227@subheading gnutls_x509_policies_init 6228@anchor{gnutls_x509_policies_init} 6229@deftypefun {int} {gnutls_x509_policies_init} (gnutls_x509_policies_t * @var{policies}) 6230@var{policies}: The authority key ID 6231 6232This function will initialize an authority key ID type. 6233 6234@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. 6235 6236@strong{Since:} 3.3.0 6237@end deftypefun 6238 6239@subheading gnutls_x509_policies_set 6240@anchor{gnutls_x509_policies_set} 6241@deftypefun {int} {gnutls_x509_policies_set} (gnutls_x509_policies_t @var{policies}, const struct gnutls_x509_policy_st * @var{policy}) 6242@var{policies}: An initialized policies 6243 6244@var{policy}: Contains the policy to set 6245 6246This function will store the specified policy in 6247the provided @code{policies} . 6248 6249@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. 6250 6251@strong{Since:} 3.3.0 6252@end deftypefun 6253 6254@subheading gnutls_x509_policy_release 6255@anchor{gnutls_x509_policy_release} 6256@deftypefun {void} {gnutls_x509_policy_release} (struct gnutls_x509_policy_st * @var{policy}) 6257@var{policy}: a certificate policy 6258 6259This function will deinitialize all memory associated with the provided 6260 @code{policy} . The policy is allocated using @code{gnutls_x509_crt_get_policy()} . 6261 6262@strong{Since:} 3.1.5 6263@end deftypefun 6264 6265@subheading gnutls_x509_privkey_cpy 6266@anchor{gnutls_x509_privkey_cpy} 6267@deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src}) 6268@var{dst}: The destination key, which should be initialized. 6269 6270@var{src}: The source key 6271 6272This function will copy a private key from source to destination 6273key. Destination has to be initialized. 6274 6275@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6276negative error value. 6277@end deftypefun 6278 6279@subheading gnutls_x509_privkey_deinit 6280@anchor{gnutls_x509_privkey_deinit} 6281@deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key}) 6282@var{key}: The key to be deinitialized 6283 6284This function will deinitialize a private key structure. 6285@end deftypefun 6286 6287@subheading gnutls_x509_privkey_export 6288@anchor{gnutls_x509_privkey_export} 6289@deftypefun {int} {gnutls_x509_privkey_export} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) 6290@var{key}: Holds the key 6291 6292@var{format}: the format of output params. One of PEM or DER. 6293 6294@var{output_data}: will contain a private key PEM or DER encoded 6295 6296@var{output_data_size}: holds the size of output_data (and will be 6297replaced by the actual size of parameters) 6298 6299This function will export the private key to a PKCS@code{1} structure for 6300RSA or RSA-PSS keys, and integer sequence for DSA keys. Other keys types 6301will be exported in PKCS@code{8} form. 6302 6303If the structure is PEM encoded, it will have a header 6304of "BEGIN RSA PRIVATE KEY". 6305 6306It is recommended to use @code{gnutls_x509_privkey_export_pkcs8()} instead 6307of this function, when a consistent output format is required. 6308 6309@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6310negative error value. 6311@end deftypefun 6312 6313@subheading gnutls_x509_privkey_export2 6314@anchor{gnutls_x509_privkey_export2} 6315@deftypefun {int} {gnutls_x509_privkey_export2} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) 6316@var{key}: Holds the key 6317 6318@var{format}: the format of output params. One of PEM or DER. 6319 6320@var{out}: will contain a private key PEM or DER encoded 6321 6322This function will export the private key to a PKCS@code{1} structure for 6323RSA or RSA-PSS keys, and integer sequence for DSA keys. Other keys types 6324will be exported in PKCS@code{8} form. 6325 6326The output buffer is allocated using @code{gnutls_malloc()} . 6327 6328It is recommended to use @code{gnutls_x509_privkey_export2_pkcs8()} instead 6329of this function, when a consistent output format is required. 6330 6331@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6332negative error value. 6333 6334Since 3.1.3 6335@end deftypefun 6336 6337@subheading gnutls_x509_privkey_export2_pkcs8 6338@anchor{gnutls_x509_privkey_export2_pkcs8} 6339@deftypefun {int} {gnutls_x509_privkey_export2_pkcs8} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}, gnutls_datum_t * @var{out}) 6340@var{key}: Holds the key 6341 6342@var{format}: the format of output params. One of PEM or DER. 6343 6344@var{password}: the password that will be used to encrypt the key. 6345 6346@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t 6347 6348@var{out}: will contain a private key PEM or DER encoded 6349 6350This function will export the private key to a PKCS8 structure. 6351Both RSA and DSA keys can be exported. For DSA keys we use 6352PKCS @code{11} definitions. If the flags do not specify the encryption 6353cipher, then the default 3DES (PBES2) will be used. 6354 6355The @code{password} can be either ASCII or UTF-8 in the default PBES2 6356encryption schemas, or ASCII for the PKCS12 schemas. 6357 6358The output buffer is allocated using @code{gnutls_malloc()} . 6359 6360If the structure is PEM encoded, it will have a header 6361of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if 6362encryption is not used. 6363 6364@strong{Returns:} In case of failure a negative error code will be 6365returned, and 0 on success. 6366 6367Since 3.1.3 6368@end deftypefun 6369 6370@subheading gnutls_x509_privkey_export_dsa_raw 6371@anchor{gnutls_x509_privkey_export_dsa_raw} 6372@deftypefun {int} {gnutls_x509_privkey_export_dsa_raw} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x}) 6373@var{key}: a key 6374 6375@var{p}: will hold the p 6376 6377@var{q}: will hold the q 6378 6379@var{g}: will hold the g 6380 6381@var{y}: will hold the y 6382 6383@var{x}: will hold the x 6384 6385This function will export the DSA private key's parameters found 6386in the given structure. The new parameters will be allocated using 6387@code{gnutls_malloc()} and will be stored in the appropriate datum. 6388 6389@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6390negative error value. 6391@end deftypefun 6392 6393@subheading gnutls_x509_privkey_export_ecc_raw 6394@anchor{gnutls_x509_privkey_export_ecc_raw} 6395@deftypefun {int} {gnutls_x509_privkey_export_ecc_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}) 6396@var{key}: a key 6397 6398@var{curve}: will hold the curve 6399 6400@var{x}: will hold the x-coordinate 6401 6402@var{y}: will hold the y-coordinate 6403 6404@var{k}: will hold the private key 6405 6406This function will export the ECC private key's parameters found 6407in the given structure. The new parameters will be allocated using 6408@code{gnutls_malloc()} and will be stored in the appropriate datum. 6409 6410In EdDSA curves the @code{y} parameter will be @code{NULL} and the other parameters 6411will be in the native format for the curve. 6412 6413@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6414negative error value. 6415 6416@strong{Since:} 3.0 6417@end deftypefun 6418 6419@subheading gnutls_x509_privkey_export_gost_raw 6420@anchor{gnutls_x509_privkey_export_gost_raw} 6421@deftypefun {int} {gnutls_x509_privkey_export_gost_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}) 6422@var{key}: a key 6423 6424@var{curve}: will hold the curve 6425 6426@var{digest}: will hold the digest 6427 6428@var{paramset}: will hold the GOST parameter set ID 6429 6430@var{x}: will hold the x-coordinate 6431 6432@var{y}: will hold the y-coordinate 6433 6434@var{k}: will hold the private key 6435 6436This function will export the GOST private key's parameters found 6437in the given structure. The new parameters will be allocated using 6438@code{gnutls_malloc()} and will be stored in the appropriate datum. 6439 6440@strong{Note:} parameters will be stored with least significant byte first. On 6441version 3.6.3 this was incorrectly returned in big-endian format. 6442 6443@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6444negative error value. 6445 6446@strong{Since:} 3.6.3 6447@end deftypefun 6448 6449@subheading gnutls_x509_privkey_export_pkcs8 6450@anchor{gnutls_x509_privkey_export_pkcs8} 6451@deftypefun {int} {gnutls_x509_privkey_export_pkcs8} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}, void * @var{output_data}, size_t * @var{output_data_size}) 6452@var{key}: Holds the key 6453 6454@var{format}: the format of output params. One of PEM or DER. 6455 6456@var{password}: the password that will be used to encrypt the key. 6457 6458@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t 6459 6460@var{output_data}: will contain a private key PEM or DER encoded 6461 6462@var{output_data_size}: holds the size of output_data (and will be 6463replaced by the actual size of parameters) 6464 6465This function will export the private key to a PKCS8 structure. 6466Both RSA and DSA keys can be exported. For DSA keys we use 6467PKCS @code{11} definitions. If the flags do not specify the encryption 6468cipher, then the default 3DES (PBES2) will be used. 6469 6470The @code{password} can be either ASCII or UTF-8 in the default PBES2 6471encryption schemas, or ASCII for the PKCS12 schemas. 6472 6473If the buffer provided is not long enough to hold the output, then 6474*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will 6475be returned. 6476 6477If the structure is PEM encoded, it will have a header 6478of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if 6479encryption is not used. 6480 6481@strong{Returns:} In case of failure a negative error code will be 6482returned, and 0 on success. 6483@end deftypefun 6484 6485@subheading gnutls_x509_privkey_export_rsa_raw 6486@anchor{gnutls_x509_privkey_export_rsa_raw} 6487@deftypefun {int} {gnutls_x509_privkey_export_rsa_raw} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}) 6488@var{key}: a key 6489 6490@var{m}: will hold the modulus 6491 6492@var{e}: will hold the public exponent 6493 6494@var{d}: will hold the private exponent 6495 6496@var{p}: will hold the first prime (p) 6497 6498@var{q}: will hold the second prime (q) 6499 6500@var{u}: will hold the coefficient 6501 6502This function will export the RSA private key's parameters found 6503in the given structure. The new parameters will be allocated using 6504@code{gnutls_malloc()} and will be stored in the appropriate datum. 6505 6506@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6507negative error value. 6508@end deftypefun 6509 6510@subheading gnutls_x509_privkey_export_rsa_raw2 6511@anchor{gnutls_x509_privkey_export_rsa_raw2} 6512@deftypefun {int} {gnutls_x509_privkey_export_rsa_raw2} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}, gnutls_datum_t * @var{e1}, gnutls_datum_t * @var{e2}) 6513@var{key}: a key 6514 6515@var{m}: will hold the modulus 6516 6517@var{e}: will hold the public exponent 6518 6519@var{d}: will hold the private exponent 6520 6521@var{p}: will hold the first prime (p) 6522 6523@var{q}: will hold the second prime (q) 6524 6525@var{u}: will hold the coefficient 6526 6527@var{e1}: will hold e1 = d mod (p-1) 6528 6529@var{e2}: will hold e2 = d mod (q-1) 6530 6531This function will export the RSA private key's parameters found 6532in the given structure. The new parameters will be allocated using 6533@code{gnutls_malloc()} and will be stored in the appropriate datum. 6534 6535@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6536negative error value. 6537 6538@strong{Since:} 2.12.0 6539@end deftypefun 6540 6541@subheading gnutls_x509_privkey_fix 6542@anchor{gnutls_x509_privkey_fix} 6543@deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key}) 6544@var{key}: a key 6545 6546This function will recalculate the secondary parameters in a key. 6547In RSA keys, this can be the coefficient and exponent1,2. 6548 6549@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6550negative error value. 6551@end deftypefun 6552 6553@subheading gnutls_x509_privkey_generate 6554@anchor{gnutls_x509_privkey_generate} 6555@deftypefun {int} {gnutls_x509_privkey_generate} (gnutls_x509_privkey_t @var{key}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags}) 6556@var{key}: an initialized key 6557 6558@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} . 6559 6560@var{bits}: the size of the parameters to generate 6561 6562@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} . 6563 6564This function will generate a random private key. Note that this 6565function must be called on an initialized private key. 6566 6567The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} 6568instructs the key generation process to use algorithms like Shawe-Taylor 6569(from FIPS PUB186-4) which generate provable parameters out of a seed 6570for RSA and DSA keys. See @code{gnutls_x509_privkey_generate2()} for more 6571information. 6572 6573Note that when generating an elliptic curve key, the curve 6574can be substituted in the place of the bits parameter using the 6575@code{GNUTLS_CURVE_TO_BITS()} macro. The input to the macro is any curve from 6576@code{gnutls_ecc_curve_t} . 6577 6578For DSA keys, if the subgroup size needs to be specified check 6579the @code{GNUTLS_SUBGROUP_TO_BITS()} macro. 6580 6581It is recommended to do not set the number of @code{bits} directly, use @code{gnutls_sec_param_to_pk_bits()} instead . 6582 6583See also @code{gnutls_privkey_generate()} , @code{gnutls_x509_privkey_generate2()} . 6584 6585@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6586negative error value. 6587@end deftypefun 6588 6589@subheading gnutls_x509_privkey_generate2 6590@anchor{gnutls_x509_privkey_generate2} 6591@deftypefun {int} {gnutls_x509_privkey_generate2} (gnutls_x509_privkey_t @var{key}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags}, const gnutls_keygen_data_st * @var{data}, unsigned @var{data_size}) 6592@var{key}: a key 6593 6594@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} . 6595 6596@var{bits}: the size of the modulus 6597 6598@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} . 6599 6600@var{data}: Allow specifying @code{gnutls_keygen_data_st} types such as the seed to be used. 6601 6602@var{data_size}: The number of @code{data} available. 6603 6604This function will generate a random private key. Note that this 6605function must be called on an initialized private key. 6606 6607The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} 6608instructs the key generation process to use algorithms like Shawe-Taylor 6609(from FIPS PUB186-4) which generate provable parameters out of a seed 6610for RSA and DSA keys. On DSA keys the PQG parameters are generated using the 6611seed, while on RSA the two primes. To specify an explicit seed 6612(by default a random seed is used), use the @code{data} with a @code{GNUTLS_KEYGEN_SEED} 6613type. 6614 6615Note that when generating an elliptic curve key, the curve 6616can be substituted in the place of the bits parameter using the 6617@code{GNUTLS_CURVE_TO_BITS()} macro. 6618 6619To export the generated keys in memory or in files it is recommended to use the 6620PKCS@code{8} form as it can handle all key types, and can store additional parameters 6621such as the seed, in case of provable RSA or DSA keys. 6622Generated keys can be exported in memory using @code{gnutls_privkey_export_x509()} , 6623and then with @code{gnutls_x509_privkey_export2_pkcs8()} . 6624 6625If key generation is part of your application, avoid setting the number 6626of bits directly, and instead use @code{gnutls_sec_param_to_pk_bits()} . 6627That way the generated keys will adapt to the security levels 6628of the underlying GnuTLS library. 6629 6630See also @code{gnutls_privkey_generate2()} . 6631 6632@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6633negative error value. 6634@end deftypefun 6635 6636@subheading gnutls_x509_privkey_get_key_id 6637@anchor{gnutls_x509_privkey_get_key_id} 6638@deftypefun {int} {gnutls_x509_privkey_get_key_id} (gnutls_x509_privkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) 6639@var{key}: a key 6640 6641@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} 6642 6643@var{output_data}: will contain the key ID 6644 6645@var{output_data_size}: holds the size of output_data (and will be 6646replaced by the actual size of parameters) 6647 6648This function will return a unique ID that depends on the public key 6649parameters. This ID can be used in checking whether a certificate 6650corresponds to the given key. 6651 6652If the buffer provided is not long enough to hold the output, then 6653* @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will 6654be returned. The output will normally be a SHA-1 hash output, 6655which is 20 bytes. 6656 6657@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6658negative error value. 6659@end deftypefun 6660 6661@subheading gnutls_x509_privkey_get_pk_algorithm 6662@anchor{gnutls_x509_privkey_get_pk_algorithm} 6663@deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key}) 6664@var{key}: should contain a @code{gnutls_x509_privkey_t} type 6665 6666This function will return the public key algorithm of a private 6667key. 6668 6669@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on 6670success, or a negative error code on error. 6671@end deftypefun 6672 6673@subheading gnutls_x509_privkey_get_pk_algorithm2 6674@anchor{gnutls_x509_privkey_get_pk_algorithm2} 6675@deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm2} (gnutls_x509_privkey_t @var{key}, unsigned int * @var{bits}) 6676@var{key}: should contain a @code{gnutls_x509_privkey_t} type 6677 6678@var{bits}: The number of bits in the public key algorithm 6679 6680This function will return the public key algorithm of a private 6681key. 6682 6683@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on 6684success, or a negative error code on error. 6685@end deftypefun 6686 6687@subheading gnutls_x509_privkey_get_seed 6688@anchor{gnutls_x509_privkey_get_seed} 6689@deftypefun {int} {gnutls_x509_privkey_get_seed} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t * @var{digest}, void * @var{seed}, size_t * @var{seed_size}) 6690@var{key}: should contain a @code{gnutls_x509_privkey_t} type 6691 6692@var{digest}: if non-NULL it will contain the digest algorithm used for key generation (if applicable) 6693 6694@var{seed}: where seed will be copied to 6695 6696@var{seed_size}: originally holds the size of @code{seed} , will be updated with actual size 6697 6698This function will return the seed that was used to generate the 6699given private key. That function will succeed only if the key was generated 6700as a provable key. 6701 6702@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6703negative error value. 6704 6705@strong{Since:} 3.5.0 6706@end deftypefun 6707 6708@subheading gnutls_x509_privkey_get_spki 6709@anchor{gnutls_x509_privkey_get_spki} 6710@deftypefun {int} {gnutls_x509_privkey_get_spki} (gnutls_x509_privkey_t @var{key}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 6711@var{key}: should contain a @code{gnutls_x509_privkey_t} type 6712 6713@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 6714 6715@var{flags}: must be zero 6716 6717This function will return the public key information of a private 6718key. The provided @code{spki} must be initialized. 6719 6720@strong{Returns:} Zero on success, or a negative error code on error. 6721@end deftypefun 6722 6723@subheading gnutls_x509_privkey_import 6724@anchor{gnutls_x509_privkey_import} 6725@deftypefun {int} {gnutls_x509_privkey_import} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) 6726@var{key}: The data to store the parsed key 6727 6728@var{data}: The DER or PEM encoded certificate. 6729 6730@var{format}: One of DER or PEM 6731 6732This function will convert the given DER or PEM encoded key to the 6733native @code{gnutls_x509_privkey_t} format. The output will be stored in 6734 @code{key} . 6735 6736If the key is PEM encoded it should have a header that contains "PRIVATE 6737KEY". Note that this function falls back to PKCS @code{8} decoding without 6738password, if the default format fails to import. 6739 6740@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6741negative error value. 6742@end deftypefun 6743 6744@subheading gnutls_x509_privkey_import2 6745@anchor{gnutls_x509_privkey_import2} 6746@deftypefun {int} {gnutls_x509_privkey_import2} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}) 6747@var{key}: The data to store the parsed key 6748 6749@var{data}: The DER or PEM encoded key. 6750 6751@var{format}: One of DER or PEM 6752 6753@var{password}: A password (optional) 6754 6755@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t 6756 6757This function will import the given DER or PEM encoded key, to 6758the native @code{gnutls_x509_privkey_t} format, irrespective of the 6759input format. The input format is auto-detected. 6760 6761The supported formats are basic unencrypted key, PKCS8, PKCS12, 6762and the openssl format. 6763 6764If the provided key is encrypted but no password was given, then 6765@code{GNUTLS_E_DECRYPTION_FAILED} is returned. Since GnuTLS 3.4.0 this 6766function will utilize the PIN callbacks if any. 6767 6768@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6769negative error value. 6770@end deftypefun 6771 6772@subheading gnutls_x509_privkey_import_dsa_raw 6773@anchor{gnutls_x509_privkey_import_dsa_raw} 6774@deftypefun {int} {gnutls_x509_privkey_import_dsa_raw} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{g}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{x}) 6775@var{key}: The data to store the parsed key 6776 6777@var{p}: holds the p 6778 6779@var{q}: holds the q 6780 6781@var{g}: holds the g 6782 6783@var{y}: holds the y 6784 6785@var{x}: holds the x 6786 6787This function will convert the given DSA raw parameters to the 6788native @code{gnutls_x509_privkey_t} format. The output will be stored 6789in @code{key} . 6790 6791@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6792negative error value. 6793@end deftypefun 6794 6795@subheading gnutls_x509_privkey_import_ecc_raw 6796@anchor{gnutls_x509_privkey_import_ecc_raw} 6797@deftypefun {int} {gnutls_x509_privkey_import_ecc_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k}) 6798@var{key}: The data to store the parsed key 6799 6800@var{curve}: holds the curve 6801 6802@var{x}: holds the x-coordinate 6803 6804@var{y}: holds the y-coordinate 6805 6806@var{k}: holds the k 6807 6808This function will convert the given elliptic curve parameters to the 6809native @code{gnutls_x509_privkey_t} format. The output will be stored 6810in @code{key} . For EdDSA keys, the @code{x} and @code{k} values must be in the 6811native to curve format. 6812 6813@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6814negative error value. 6815 6816@strong{Since:} 3.0 6817@end deftypefun 6818 6819@subheading gnutls_x509_privkey_import_gost_raw 6820@anchor{gnutls_x509_privkey_import_gost_raw} 6821@deftypefun {int} {gnutls_x509_privkey_import_gost_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, gnutls_digest_algorithm_t @var{digest}, gnutls_gost_paramset_t @var{paramset}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k}) 6822@var{key}: The data to store the parsed key 6823 6824@var{curve}: holds the curve 6825 6826@var{digest}: will hold the digest 6827 6828@var{paramset}: will hold the GOST parameter set ID 6829 6830@var{x}: holds the x-coordinate 6831 6832@var{y}: holds the y-coordinate 6833 6834@var{k}: holds the k (private key) 6835 6836This function will convert the given GOST private key's parameters to the 6837native @code{gnutls_x509_privkey_t} format. The output will be stored 6838in @code{key} . @code{digest} should be one of GNUTLS_DIG_GOSR_94, 6839GNUTLS_DIG_STREEBOG_256 or GNUTLS_DIG_STREEBOG_512. If @code{paramset} is set to 6840GNUTLS_GOST_PARAMSET_UNKNOWN default one will be selected depending on 6841 @code{digest} . 6842 6843@strong{Note:} parameters should be stored with least significant byte first. On 6844version 3.6.3 big-endian format was used incorrectly. 6845 6846@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6847negative error value. 6848 6849@strong{Since:} 3.6.3 6850@end deftypefun 6851 6852@subheading gnutls_x509_privkey_import_openssl 6853@anchor{gnutls_x509_privkey_import_openssl} 6854@deftypefun {int} {gnutls_x509_privkey_import_openssl} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, const char * @var{password}) 6855@var{key}: The data to store the parsed key 6856 6857@var{data}: The DER or PEM encoded key. 6858 6859@var{password}: the password to decrypt the key (if it is encrypted). 6860 6861This function will convert the given PEM encrypted to 6862the native gnutls_x509_privkey_t format. The 6863output will be stored in @code{key} . 6864 6865The @code{password} should be in ASCII. If the password is not provided 6866or wrong then @code{GNUTLS_E_DECRYPTION_FAILED} will be returned. 6867 6868If the Certificate is PEM encoded it should have a header of 6869"PRIVATE KEY" and the "DEK-Info" header. 6870 6871@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6872negative error value. 6873@end deftypefun 6874 6875@subheading gnutls_x509_privkey_import_pkcs8 6876@anchor{gnutls_x509_privkey_import_pkcs8} 6877@deftypefun {int} {gnutls_x509_privkey_import_pkcs8} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}) 6878@var{key}: The data to store the parsed key 6879 6880@var{data}: The DER or PEM encoded key. 6881 6882@var{format}: One of DER or PEM 6883 6884@var{password}: the password to decrypt the key (if it is encrypted). 6885 6886@var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted. 6887 6888This function will convert the given DER or PEM encoded PKCS8 2.0 6889encrypted key to the native gnutls_x509_privkey_t format. The 6890output will be stored in @code{key} . Both RSA and DSA keys can be 6891imported, and flags can only be used to indicate an unencrypted 6892key. 6893 6894The @code{password} can be either ASCII or UTF-8 in the default PBES2 6895encryption schemas, or ASCII for the PKCS12 schemas. 6896 6897If the Certificate is PEM encoded it should have a header of 6898"ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to 6899specify the flags if the key is DER encoded, since in that case 6900the encryption status cannot be auto-detected. 6901 6902If the @code{GNUTLS_PKCS_PLAIN} flag is specified and the supplied data 6903are encrypted then @code{GNUTLS_E_DECRYPTION_FAILED} is returned. 6904 6905@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6906negative error value. 6907@end deftypefun 6908 6909@subheading gnutls_x509_privkey_import_rsa_raw 6910@anchor{gnutls_x509_privkey_import_rsa_raw} 6911@deftypefun {int} {gnutls_x509_privkey_import_rsa_raw} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}, const gnutls_datum_t * @var{d}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{u}) 6912@var{key}: The data to store the parsed key 6913 6914@var{m}: holds the modulus 6915 6916@var{e}: holds the public exponent 6917 6918@var{d}: holds the private exponent 6919 6920@var{p}: holds the first prime (p) 6921 6922@var{q}: holds the second prime (q) 6923 6924@var{u}: holds the coefficient 6925 6926This function will convert the given RSA raw parameters to the 6927native @code{gnutls_x509_privkey_t} format. The output will be stored in 6928 @code{key} . 6929 6930@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6931negative error value. 6932@end deftypefun 6933 6934@subheading gnutls_x509_privkey_import_rsa_raw2 6935@anchor{gnutls_x509_privkey_import_rsa_raw2} 6936@deftypefun {int} {gnutls_x509_privkey_import_rsa_raw2} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}, const gnutls_datum_t * @var{d}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{u}, const gnutls_datum_t * @var{e1}, const gnutls_datum_t * @var{e2}) 6937@var{key}: The data to store the parsed key 6938 6939@var{m}: holds the modulus 6940 6941@var{e}: holds the public exponent 6942 6943@var{d}: holds the private exponent 6944 6945@var{p}: holds the first prime (p) 6946 6947@var{q}: holds the second prime (q) 6948 6949@var{u}: holds the coefficient (optional) 6950 6951@var{e1}: holds e1 = d mod (p-1) (optional) 6952 6953@var{e2}: holds e2 = d mod (q-1) (optional) 6954 6955This function will convert the given RSA raw parameters to the 6956native @code{gnutls_x509_privkey_t} format. The output will be stored in 6957 @code{key} . 6958 6959@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6960negative error value. 6961@end deftypefun 6962 6963@subheading gnutls_x509_privkey_init 6964@anchor{gnutls_x509_privkey_init} 6965@deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key}) 6966@var{key}: A pointer to the type to be initialized 6967 6968This function will initialize a private key type. 6969 6970@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 6971negative error value. 6972@end deftypefun 6973 6974@subheading gnutls_x509_privkey_sec_param 6975@anchor{gnutls_x509_privkey_sec_param} 6976@deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key}) 6977@var{key}: a key 6978 6979This function will return the security parameter appropriate with 6980this private key. 6981 6982@strong{Returns:} On success, a valid security parameter is returned otherwise 6983@code{GNUTLS_SEC_PARAM_UNKNOWN} is returned. 6984 6985@strong{Since:} 2.12.0 6986@end deftypefun 6987 6988@subheading gnutls_x509_privkey_set_flags 6989@anchor{gnutls_x509_privkey_set_flags} 6990@deftypefun {void} {gnutls_x509_privkey_set_flags} (gnutls_x509_privkey_t @var{key}, unsigned int @var{flags}) 6991@var{key}: A key of type @code{gnutls_x509_privkey_t} 6992 6993@var{flags}: flags from the @code{gnutls_privkey_flags} 6994 6995This function will set flags for the specified private key, after 6996it is generated. Currently this is useful for the @code{GNUTLS_PRIVKEY_FLAG_EXPORT_COMPAT} 6997to allow exporting a "provable" private key in backwards compatible way. 6998 6999@strong{Since:} 3.5.0 7000@end deftypefun 7001 7002@subheading gnutls_x509_privkey_set_pin_function 7003@anchor{gnutls_x509_privkey_set_pin_function} 7004@deftypefun {void} {gnutls_x509_privkey_set_pin_function} (gnutls_x509_privkey_t @var{privkey}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 7005@var{privkey}: The certificate structure 7006 7007@var{fn}: the callback 7008 7009@var{userdata}: data associated with the callback 7010 7011This function will set a callback function to be used when 7012it is required to access a protected object. This function overrides 7013the global function set using @code{gnutls_pkcs11_set_pin_function()} . 7014 7015Note that this callback is used when decrypting a key. 7016 7017@strong{Since:} 3.4.0 7018@end deftypefun 7019 7020@subheading gnutls_x509_privkey_set_spki 7021@anchor{gnutls_x509_privkey_set_spki} 7022@deftypefun {int} {gnutls_x509_privkey_set_spki} (gnutls_x509_privkey_t @var{key}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) 7023@var{key}: should contain a @code{gnutls_x509_privkey_t} type 7024 7025@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} 7026 7027@var{flags}: must be zero 7028 7029This function will return the public key information of a private 7030key. The provided @code{spki} must be initialized. 7031 7032@strong{Returns:} Zero on success, or a negative error code on error. 7033@end deftypefun 7034 7035@subheading gnutls_x509_privkey_sign_data 7036@anchor{gnutls_x509_privkey_sign_data} 7037@deftypefun {int} {gnutls_x509_privkey_sign_data} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, void * @var{signature}, size_t * @var{signature_size}) 7038@var{key}: a key 7039 7040@var{digest}: should be a digest algorithm 7041 7042@var{flags}: should be 0 for now 7043 7044@var{data}: holds the data to be signed 7045 7046@var{signature}: will contain the signature 7047 7048@var{signature_size}: holds the size of signature (and will be replaced 7049by the new size) 7050 7051This function will sign the given data using a signature algorithm 7052supported by the private key. Signature algorithms are always used 7053together with a hash functions. Different hash functions may be 7054used for the RSA algorithm, but only SHA-1 for the DSA keys. 7055 7056If the buffer provided is not long enough to hold the output, then 7057* @code{signature_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will 7058be returned. 7059 7060Use @code{gnutls_x509_crt_get_preferred_hash_algorithm()} to determine 7061the hash algorithm. 7062 7063@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7064negative error value. 7065@end deftypefun 7066 7067@subheading gnutls_x509_privkey_verify_params 7068@anchor{gnutls_x509_privkey_verify_params} 7069@deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key}) 7070@var{key}: a key 7071 7072This function will verify the private key parameters. 7073 7074@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7075negative error value. 7076@end deftypefun 7077 7078@subheading gnutls_x509_privkey_verify_seed 7079@anchor{gnutls_x509_privkey_verify_seed} 7080@deftypefun {int} {gnutls_x509_privkey_verify_seed} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, const void * @var{seed}, size_t @var{seed_size}) 7081@var{key}: should contain a @code{gnutls_x509_privkey_t} type 7082 7083@var{digest}: it contains the digest algorithm used for key generation (if applicable) 7084 7085@var{seed}: the seed of the key to be checked with 7086 7087@var{seed_size}: holds the size of @code{seed} 7088 7089This function will verify that the given private key was generated from 7090the provided seed. If @code{seed} is @code{NULL} then the seed stored in the @code{key} 's structure 7091will be used for verification. 7092 7093@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PRIVKEY_VERIFICATION_ERROR} 7094is returned, and zero or positive code on success. 7095 7096@strong{Since:} 3.5.0 7097@end deftypefun 7098 7099@subheading gnutls_x509_rdn_get 7100@anchor{gnutls_x509_rdn_get} 7101@deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{buf_size}) 7102@var{idn}: should contain a DER encoded RDN sequence 7103 7104@var{buf}: a pointer to a structure to hold the peer's name 7105 7106@var{buf_size}: holds the size of @code{buf} 7107 7108This function will return the name of the given RDN sequence. The 7109name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in 7110RFC4514. 7111 7112This function does not output a fully RFC4514 compliant string, if 7113that is required see @code{gnutls_x509_rdn_get2()} . 7114 7115@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or 7116@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is 7117updated if the provided buffer is not long enough, otherwise a 7118negative error value. 7119@end deftypefun 7120 7121@subheading gnutls_x509_rdn_get2 7122@anchor{gnutls_x509_rdn_get2} 7123@deftypefun {int} {gnutls_x509_rdn_get2} (const gnutls_datum_t * @var{idn}, gnutls_datum_t * @var{str}, unsigned @var{flags}) 7124@var{idn}: should contain a DER encoded RDN sequence 7125 7126@var{str}: a datum that will hold the name 7127 7128@var{flags}: zero of @code{GNUTLS_X509_DN_FLAG_COMPAT} 7129 7130This function will return the name of the given RDN sequence. The 7131name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in 7132RFC4514. 7133 7134When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output 7135format will match the format output by previous to 3.5.6 versions of GnuTLS 7136which was not not fully RFC4514-compliant. 7137 7138@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or 7139@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is 7140updated if the provided buffer is not long enough, otherwise a 7141negative error value. 7142@end deftypefun 7143 7144@subheading gnutls_x509_rdn_get_by_oid 7145@anchor{gnutls_x509_rdn_get_by_oid} 7146@deftypefun {int} {gnutls_x509_rdn_get_by_oid} (const gnutls_datum_t * @var{idn}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) 7147@var{idn}: should contain a DER encoded RDN sequence 7148 7149@var{oid}: an Object Identifier 7150 7151@var{indx}: In case multiple same OIDs exist in the RDN indicates which 7152to send. Use 0 for the first one. 7153 7154@var{raw_flag}: If non-zero then the raw DER data are returned. 7155 7156@var{buf}: a pointer to a structure to hold the peer's name 7157 7158@var{buf_size}: holds the size of @code{buf} 7159 7160This function will return the name of the given Object identifier, 7161of the RDN sequence. The name will be encoded using the rules 7162from RFC4514. 7163 7164@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or 7165@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is 7166updated if the provided buffer is not long enough, otherwise a 7167negative error value. 7168@end deftypefun 7169 7170@subheading gnutls_x509_rdn_get_oid 7171@anchor{gnutls_x509_rdn_get_oid} 7172@deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}) 7173@var{idn}: should contain a DER encoded RDN sequence 7174 7175@var{indx}: Indicates which OID to return. Use 0 for the first one. 7176 7177@var{buf}: a pointer to a structure to hold the peer's name OID 7178 7179@var{buf_size}: holds the size of @code{buf} 7180 7181This function will return the specified Object identifier, of the 7182RDN sequence. 7183 7184@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or 7185@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is 7186updated if the provided buffer is not long enough, otherwise a 7187negative error value. 7188 7189@strong{Since:} 2.4.0 7190@end deftypefun 7191 7192@subheading gnutls_x509_spki_deinit 7193@anchor{gnutls_x509_spki_deinit} 7194@deftypefun {void} {gnutls_x509_spki_deinit} (gnutls_x509_spki_t @var{spki}) 7195@var{spki}: the SubjectPublicKeyInfo structure 7196 7197This function will deinitialize a SubjectPublicKeyInfo structure. 7198 7199@strong{Since:} 3.6.0 7200@end deftypefun 7201 7202@subheading gnutls_x509_spki_get_rsa_pss_params 7203@anchor{gnutls_x509_spki_get_rsa_pss_params} 7204@deftypefun {int} {gnutls_x509_spki_get_rsa_pss_params} (gnutls_x509_spki_t @var{spki}, gnutls_digest_algorithm_t * @var{dig}, unsigned int * @var{salt_size}) 7205@var{spki}: the SubjectPublicKeyInfo structure 7206 7207@var{dig}: if non-NULL, it will hold the digest algorithm 7208 7209@var{salt_size}: if non-NULL, it will hold the salt size 7210 7211This function will get the public key algorithm parameters 7212of RSA-PSS type. 7213 7214@strong{Returns:} zero if the parameters are present or a negative 7215value on error. 7216 7217@strong{Since:} 3.6.0 7218@end deftypefun 7219 7220@subheading gnutls_x509_spki_init 7221@anchor{gnutls_x509_spki_init} 7222@deftypefun {int} {gnutls_x509_spki_init} (gnutls_x509_spki_t * @var{spki}) 7223@var{spki}: A pointer to the type to be initialized 7224 7225This function will initialize a SubjectPublicKeyInfo structure used 7226in PKIX. The structure is used to set additional parameters 7227in the public key information field of a certificate. 7228 7229@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7230negative error value. 7231 7232@strong{Since:} 3.6.0 7233@end deftypefun 7234 7235@subheading gnutls_x509_spki_set_rsa_pss_params 7236@anchor{gnutls_x509_spki_set_rsa_pss_params} 7237@deftypefun {void} {gnutls_x509_spki_set_rsa_pss_params} (gnutls_x509_spki_t @var{spki}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{salt_size}) 7238@var{spki}: the SubjectPublicKeyInfo structure 7239 7240@var{dig}: a digest algorithm of type @code{gnutls_digest_algorithm_t} 7241 7242@var{salt_size}: the size of salt string 7243 7244This function will set the public key parameters for 7245an RSA-PSS algorithm, in the SubjectPublicKeyInfo structure. 7246 7247@strong{Since:} 3.6.0 7248@end deftypefun 7249 7250@subheading gnutls_x509_tlsfeatures_add 7251@anchor{gnutls_x509_tlsfeatures_add} 7252@deftypefun {int} {gnutls_x509_tlsfeatures_add} (gnutls_x509_tlsfeatures_t @var{f}, unsigned int @var{feature}) 7253@var{f}: The TLS features 7254 7255@var{feature}: The feature to add 7256 7257This function will append a feature to the X.509 TLS features 7258extension structure. 7259 7260@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7261otherwise a negative error value. 7262 7263@strong{Since:} 3.5.1 7264@end deftypefun 7265 7266@subheading gnutls_x509_tlsfeatures_check_crt 7267@anchor{gnutls_x509_tlsfeatures_check_crt} 7268@deftypefun {unsigned} {gnutls_x509_tlsfeatures_check_crt} (gnutls_x509_tlsfeatures_t @var{feat}, gnutls_x509_crt_t @var{cert}) 7269@var{feat}: a set of TLSFeatures 7270 7271@var{cert}: the certificate to be checked 7272 7273This function will check the provided certificate against the TLSFeatures 7274set in @code{feat} using the RFC7633 p.4.2.2 rules. It will check whether the certificate 7275contains the features in @code{feat} or a superset. 7276 7277@strong{Returns:} non-zero if the provided certificate complies, and zero otherwise. 7278 7279@strong{Since:} 3.5.1 7280@end deftypefun 7281 7282@subheading gnutls_x509_tlsfeatures_deinit 7283@anchor{gnutls_x509_tlsfeatures_deinit} 7284@deftypefun {void} {gnutls_x509_tlsfeatures_deinit} (gnutls_x509_tlsfeatures_t @var{f}) 7285@var{f}: The TLS features 7286 7287This function will deinitialize a X.509 TLS features extension structure 7288 7289@strong{Since:} 3.5.1 7290@end deftypefun 7291 7292@subheading gnutls_x509_tlsfeatures_get 7293@anchor{gnutls_x509_tlsfeatures_get} 7294@deftypefun {int} {gnutls_x509_tlsfeatures_get} (gnutls_x509_tlsfeatures_t @var{f}, unsigned @var{idx}, unsigned int * @var{feature}) 7295@var{f}: The TLS features 7296 7297@var{idx}: The index of the feature to get 7298 7299@var{feature}: If the function succeeds, the feature will be stored in this variable 7300 7301This function will get a feature from the X.509 TLS features 7302extension structure. 7303 7304@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7305otherwise a negative error value. 7306 7307@strong{Since:} 3.5.1 7308@end deftypefun 7309 7310@subheading gnutls_x509_tlsfeatures_init 7311@anchor{gnutls_x509_tlsfeatures_init} 7312@deftypefun {int} {gnutls_x509_tlsfeatures_init} (gnutls_x509_tlsfeatures_t * @var{f}) 7313@var{f}: The TLS features 7314 7315This function will initialize a X.509 TLS features extension structure 7316 7317@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 7318otherwise a negative error value. 7319 7320@strong{Since:} 3.5.1 7321@end deftypefun 7322 7323@subheading gnutls_x509_trust_list_add_cas 7324@anchor{gnutls_x509_trust_list_add_cas} 7325@deftypefun {int} {gnutls_x509_trust_list_add_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, unsigned @var{clist_size}, unsigned int @var{flags}) 7326@var{list}: The list 7327 7328@var{clist}: A list of CAs 7329 7330@var{clist_size}: The length of the CA list 7331 7332@var{flags}: flags from @code{gnutls_trust_list_flags_t} 7333 7334This function will add the given certificate authorities 7335to the trusted list. The CAs in @code{clist} must not be deinitialized 7336during the lifetime of @code{list} . 7337 7338If the flag @code{GNUTLS_TL_NO_DUPLICATES} is specified, then 7339this function will ensure that no duplicates will be 7340present in the final trust list. 7341 7342If the flag @code{GNUTLS_TL_NO_DUPLICATE_KEY} is specified, then 7343this function will ensure that no certificates with the 7344same key are present in the final trust list. 7345 7346If either @code{GNUTLS_TL_NO_DUPLICATE_KEY} or @code{GNUTLS_TL_NO_DUPLICATES} 7347are given, @code{gnutls_x509_trust_list_deinit()} must be called with parameter 7348 @code{all} being 1. 7349 7350@strong{Returns:} The number of added elements is returned; that includes 7351duplicate entries. 7352 7353@strong{Since:} 3.0.0 7354@end deftypefun 7355 7356@subheading gnutls_x509_trust_list_add_crls 7357@anchor{gnutls_x509_trust_list_add_crls} 7358@deftypefun {int} {gnutls_x509_trust_list_add_crls} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crl_t * @var{crl_list}, unsigned @var{crl_size}, unsigned int @var{flags}, unsigned int @var{verification_flags}) 7359@var{list}: The list 7360 7361@var{crl_list}: A list of CRLs 7362 7363@var{crl_size}: The length of the CRL list 7364 7365@var{flags}: flags from @code{gnutls_trust_list_flags_t} 7366 7367@var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL 7368 7369This function will add the given certificate revocation lists 7370to the trusted list. The CRLs in @code{crl_list} must not be deinitialized 7371during the lifetime of @code{list} . 7372 7373This function must be called after @code{gnutls_x509_trust_list_add_cas()} 7374to allow verifying the CRLs for validity. If the flag @code{GNUTLS_TL_NO_DUPLICATES} 7375is given, then the final CRL list will not contain duplicate entries. 7376 7377If the flag @code{GNUTLS_TL_NO_DUPLICATES} is given, @code{gnutls_x509_trust_list_deinit()} must be 7378called with parameter @code{all} being 1. 7379 7380If flag @code{GNUTLS_TL_VERIFY_CRL} is given the CRLs will be verified before being added, 7381and if verification fails, they will be skipped. 7382 7383@strong{Returns:} The number of added elements is returned; that includes 7384duplicate entries. 7385 7386@strong{Since:} 3.0 7387@end deftypefun 7388 7389@subheading gnutls_x509_trust_list_add_named_crt 7390@anchor{gnutls_x509_trust_list_add_named_crt} 7391@deftypefun {int} {gnutls_x509_trust_list_add_named_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, const void * @var{name}, size_t @var{name_size}, unsigned int @var{flags}) 7392@var{list}: The list 7393 7394@var{cert}: A certificate 7395 7396@var{name}: An identifier for the certificate 7397 7398@var{name_size}: The size of the identifier 7399 7400@var{flags}: should be 0. 7401 7402This function will add the given certificate to the trusted 7403list and associate it with a name. The certificate will not be 7404be used for verification with @code{gnutls_x509_trust_list_verify_crt()} 7405but with @code{gnutls_x509_trust_list_verify_named_crt()} or 7406@code{gnutls_x509_trust_list_verify_crt2()} - the latter only since 7407GnuTLS 3.4.0 and if a hostname is provided. 7408 7409In principle this function can be used to set individual "server" 7410certificates that are trusted by the user for that specific server 7411but for no other purposes. 7412 7413The certificate @code{cert} must not be deinitialized during the lifetime 7414of the @code{list} . 7415 7416@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7417negative error value. 7418 7419@strong{Since:} 3.0.0 7420@end deftypefun 7421 7422@subheading gnutls_x509_trust_list_add_system_trust 7423@anchor{gnutls_x509_trust_list_add_system_trust} 7424@deftypefun {int} {gnutls_x509_trust_list_add_system_trust} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) 7425@var{list}: The structure of the list 7426 7427@var{tl_flags}: GNUTLS_TL_* 7428 7429@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL 7430 7431This function adds the system's default trusted certificate 7432authorities to the trusted list. Note that on unsupported systems 7433this function returns @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . 7434 7435This function implies the flag @code{GNUTLS_TL_NO_DUPLICATES} . 7436 7437@strong{Returns:} The number of added elements or a negative error code on error. 7438 7439@strong{Since:} 3.1 7440@end deftypefun 7441 7442@subheading gnutls_x509_trust_list_add_trust_dir 7443@anchor{gnutls_x509_trust_list_add_trust_dir} 7444@deftypefun {int} {gnutls_x509_trust_list_add_trust_dir} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_dir}, const char * @var{crl_dir}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) 7445@var{list}: The list 7446 7447@var{ca_dir}: A directory containing the CAs (optional) 7448 7449@var{crl_dir}: A directory containing a list of CRLs (optional) 7450 7451@var{type}: The format of the certificates 7452 7453@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} 7454 7455@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL 7456 7457This function will add the given certificate authorities 7458to the trusted list. Only directories are accepted by 7459this function. 7460 7461@strong{Returns:} The number of added elements is returned. 7462 7463@strong{Since:} 3.3.6 7464@end deftypefun 7465 7466@subheading gnutls_x509_trust_list_add_trust_file 7467@anchor{gnutls_x509_trust_list_add_trust_file} 7468@deftypefun {int} {gnutls_x509_trust_list_add_trust_file} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_file}, const char * @var{crl_file}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) 7469@var{list}: The list 7470 7471@var{ca_file}: A file containing a list of CAs (optional) 7472 7473@var{crl_file}: A file containing a list of CRLs (optional) 7474 7475@var{type}: The format of the certificates 7476 7477@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} 7478 7479@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL 7480 7481This function will add the given certificate authorities 7482to the trusted list. PKCS @code{11} URLs are also accepted, instead 7483of files, by this function. A PKCS @code{11} URL implies a trust 7484database (a specially marked module in p11-kit); the URL "pkcs11:" 7485implies all trust databases in the system. Only a single URL specifying 7486trust databases can be set; they cannot be stacked with multiple calls. 7487 7488@strong{Returns:} The number of added elements is returned. 7489 7490@strong{Since:} 3.1 7491@end deftypefun 7492 7493@subheading gnutls_x509_trust_list_add_trust_mem 7494@anchor{gnutls_x509_trust_list_add_trust_mem} 7495@deftypefun {int} {gnutls_x509_trust_list_add_trust_mem} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{cas}, const gnutls_datum_t * @var{crls}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) 7496@var{list}: The list 7497 7498@var{cas}: A buffer containing a list of CAs (optional) 7499 7500@var{crls}: A buffer containing a list of CRLs (optional) 7501 7502@var{type}: The format of the certificates 7503 7504@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} 7505 7506@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL 7507 7508This function will add the given certificate authorities 7509to the trusted list. 7510 7511If this function is used @code{gnutls_x509_trust_list_deinit()} must be called 7512with parameter @code{all} being 1. 7513 7514@strong{Returns:} The number of added elements is returned. 7515 7516@strong{Since:} 3.1 7517@end deftypefun 7518 7519@subheading gnutls_x509_trust_list_deinit 7520@anchor{gnutls_x509_trust_list_deinit} 7521@deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all}) 7522@var{list}: The list to be deinitialized 7523 7524@var{all}: if non-zero it will deinitialize all the certificates and CRLs contained in the structure. 7525 7526This function will deinitialize a trust list. Note that the 7527 @code{all} flag should be typically non-zero unless you have specified 7528your certificates using @code{gnutls_x509_trust_list_add_cas()} and you 7529want to prevent them from being deinitialized by this function. 7530 7531@strong{Since:} 3.0.0 7532@end deftypefun 7533 7534@subheading gnutls_x509_trust_list_get_issuer 7535@anchor{gnutls_x509_trust_list_get_issuer} 7536@deftypefun {int} {gnutls_x509_trust_list_get_issuer} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) 7537@var{list}: The list 7538 7539@var{cert}: is the certificate to find issuer for 7540 7541@var{issuer}: Will hold the issuer if any. Should be treated as constant. 7542 7543@var{flags}: flags from @code{gnutls_trust_list_flags_t} (@code{GNUTLS_TL_GET_COPY} is applicable) 7544 7545This function will find the issuer of the given certificate. 7546If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer 7547will be returned which must be freed using @code{gnutls_x509_crt_deinit()} . 7548In that case the provided @code{issuer} must not be initialized. 7549 7550Note that the flag @code{GNUTLS_TL_GET_COPY} is required for this function 7551to work with PKCS@code{11} trust lists in a thread-safe way. 7552 7553@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7554negative error value. 7555 7556@strong{Since:} 3.0 7557@end deftypefun 7558 7559@subheading gnutls_x509_trust_list_get_issuer_by_dn 7560@anchor{gnutls_x509_trust_list_get_issuer_by_dn} 7561@deftypefun {int} {gnutls_x509_trust_list_get_issuer_by_dn} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{dn}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) 7562@var{list}: The list 7563 7564@var{dn}: is the issuer's DN 7565 7566@var{issuer}: Will hold the issuer if any. Should be deallocated after use. 7567 7568@var{flags}: Use zero 7569 7570This function will find the issuer with the given name, and 7571return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} . 7572 7573@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7574negative error value. 7575 7576@strong{Since:} 3.4.0 7577@end deftypefun 7578 7579@subheading gnutls_x509_trust_list_get_issuer_by_subject_key_id 7580@anchor{gnutls_x509_trust_list_get_issuer_by_subject_key_id} 7581@deftypefun {int} {gnutls_x509_trust_list_get_issuer_by_subject_key_id} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{dn}, const gnutls_datum_t * @var{spki}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) 7582@var{list}: The list 7583 7584@var{dn}: is the issuer's DN (may be @code{NULL} ) 7585 7586@var{spki}: is the subject key ID 7587 7588@var{issuer}: Will hold the issuer if any. Should be deallocated after use. 7589 7590@var{flags}: Use zero 7591 7592This function will find the issuer with the given name and subject key ID, and 7593return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} . 7594 7595@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7596negative error value. 7597 7598@strong{Since:} 3.4.2 7599@end deftypefun 7600 7601@subheading gnutls_x509_trust_list_init 7602@anchor{gnutls_x509_trust_list_init} 7603@deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size}) 7604@var{list}: A pointer to the type to be initialized 7605 7606@var{size}: The size of the internal hash table. Use (0) for default size. 7607 7608This function will initialize an X.509 trust list structure. 7609 7610@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7611negative error value. 7612 7613@strong{Since:} 3.0.0 7614@end deftypefun 7615 7616@subheading gnutls_x509_trust_list_iter_deinit 7617@anchor{gnutls_x509_trust_list_iter_deinit} 7618@deftypefun {void} {gnutls_x509_trust_list_iter_deinit} (gnutls_x509_trust_list_iter_t @var{iter}) 7619@var{iter}: The iterator structure to be deinitialized 7620 7621This function will deinitialize an iterator structure. 7622 7623@strong{Since:} 3.4.0 7624@end deftypefun 7625 7626@subheading gnutls_x509_trust_list_iter_get_ca 7627@anchor{gnutls_x509_trust_list_iter_get_ca} 7628@deftypefun {int} {gnutls_x509_trust_list_iter_get_ca} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_trust_list_iter_t * @var{iter}, gnutls_x509_crt_t * @var{crt}) 7629@var{list}: The list 7630 7631@var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} ) 7632 7633@var{crt}: where the certificate will be copied 7634 7635This function obtains a certificate in the trust list and advances the 7636iterator to the next certificate. The certificate returned in @code{crt} must be 7637deallocated with @code{gnutls_x509_crt_deinit()} . 7638 7639When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} 7640is returned and the iterator is reset. 7641 7642The iterator is deinitialized and reset to @code{NULL} automatically by this 7643function after iterating through all elements until 7644@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the iteration is 7645aborted early, it must be manually deinitialized using 7646@code{gnutls_x509_trust_list_iter_deinit()} . 7647 7648@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7649negative error value. 7650 7651@strong{Since:} 3.4.0 7652@end deftypefun 7653 7654@subheading gnutls_x509_trust_list_remove_cas 7655@anchor{gnutls_x509_trust_list_remove_cas} 7656@deftypefun {int} {gnutls_x509_trust_list_remove_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, unsigned @var{clist_size}) 7657@var{list}: The list 7658 7659@var{clist}: A list of CAs 7660 7661@var{clist_size}: The length of the CA list 7662 7663This function will remove the given certificate authorities 7664from the trusted list. 7665 7666Note that this function can accept certificates and authorities 7667not yet known. In that case they will be kept in a separate 7668black list that will be used during certificate verification. 7669Unlike @code{gnutls_x509_trust_list_add_cas()} there is no deinitialization 7670restriction for certificate list provided in this function. 7671 7672@strong{Returns:} The number of removed elements is returned. 7673 7674@strong{Since:} 3.1.10 7675@end deftypefun 7676 7677@subheading gnutls_x509_trust_list_remove_trust_file 7678@anchor{gnutls_x509_trust_list_remove_trust_file} 7679@deftypefun {int} {gnutls_x509_trust_list_remove_trust_file} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_file}, gnutls_x509_crt_fmt_t @var{type}) 7680@var{list}: The list 7681 7682@var{ca_file}: A file containing a list of CAs 7683 7684@var{type}: The format of the certificates 7685 7686This function will remove the given certificate authorities 7687from the trusted list, and add them into a black list when needed. 7688PKCS 11 URLs are also accepted, instead 7689of files, by this function. 7690 7691See also @code{gnutls_x509_trust_list_remove_cas()} . 7692 7693@strong{Returns:} The number of added elements is returned. 7694 7695@strong{Since:} 3.1.10 7696@end deftypefun 7697 7698@subheading gnutls_x509_trust_list_remove_trust_mem 7699@anchor{gnutls_x509_trust_list_remove_trust_mem} 7700@deftypefun {int} {gnutls_x509_trust_list_remove_trust_mem} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{cas}, gnutls_x509_crt_fmt_t @var{type}) 7701@var{list}: The list 7702 7703@var{cas}: A buffer containing a list of CAs (optional) 7704 7705@var{type}: The format of the certificates 7706 7707This function will remove the provided certificate authorities 7708from the trusted list, and add them into a black list when needed. 7709 7710See also @code{gnutls_x509_trust_list_remove_cas()} . 7711 7712@strong{Returns:} The number of removed elements is returned. 7713 7714@strong{Since:} 3.1.10 7715@end deftypefun 7716 7717@subheading gnutls_x509_trust_list_verify_crt 7718@anchor{gnutls_x509_trust_list_verify_crt} 7719@deftypefun {int} {gnutls_x509_trust_list_verify_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t * @var{cert_list}, unsigned int @var{cert_list_size}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) 7720@var{list}: The list 7721 7722@var{cert_list}: is the certificate list to be verified 7723 7724@var{cert_list_size}: is the certificate list size 7725 7726@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 7727 7728@var{voutput}: will hold the certificate verification output. 7729 7730@var{func}: If non-null will be called on each chain element verification with the output. 7731 7732This function will try to verify the given certificate and return 7733its status. The @code{voutput} parameter will hold an OR'ed sequence of 7734@code{gnutls_certificate_status_t} flags. 7735 7736The details of the verification are the same as in @code{gnutls_x509_trust_list_verify_crt2()} . 7737 7738@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7739negative error value. 7740 7741@strong{Since:} 3.0 7742@end deftypefun 7743 7744@subheading gnutls_x509_trust_list_verify_crt2 7745@anchor{gnutls_x509_trust_list_verify_crt2} 7746@deftypefun {int} {gnutls_x509_trust_list_verify_crt2} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t * @var{cert_list}, unsigned int @var{cert_list_size}, gnutls_typed_vdata_st * @var{data}, unsigned int @var{elements}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) 7747@var{list}: The list 7748 7749@var{cert_list}: is the certificate list to be verified 7750 7751@var{cert_list_size}: is the certificate list size 7752 7753@var{data}: an array of typed data 7754 7755@var{elements}: the number of data elements 7756 7757@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 7758 7759@var{voutput}: will hold the certificate verification output. 7760 7761@var{func}: If non-null will be called on each chain element verification with the output. 7762 7763This function will attempt to verify the given certificate chain and return 7764its status. The @code{voutput} parameter will hold an OR'ed sequence of 7765@code{gnutls_certificate_status_t} flags. 7766 7767When a certificate chain of @code{cert_list_size} with more than one certificates is 7768provided, the verification status will apply to the first certificate in the chain 7769that failed verification. The verification process starts from the end of the chain 7770(from CA to end certificate). The first certificate in the chain must be the end-certificate 7771while the rest of the members may be sorted or not. 7772 7773Additionally a certificate verification profile can be specified 7774from the ones in @code{gnutls_certificate_verification_profiles_t} by 7775ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification 7776flags. 7777 7778Additional verification parameters are possible via the @code{data} types; the 7779acceptable types are @code{GNUTLS_DT_DNS_HOSTNAME} , @code{GNUTLS_DT_IP_ADDRESS} and @code{GNUTLS_DT_KEY_PURPOSE_OID} . 7780The former accepts as data a null-terminated hostname, and the latter a null-terminated 7781object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ). 7782If a DNS hostname is provided then this function will compare 7783the hostname in the end certificate against the given. If names do not match the 7784@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. In addition it 7785will consider certificates provided with @code{gnutls_x509_trust_list_add_named_crt()} . 7786 7787If a key purpose OID is provided and the end-certificate contains the extended key 7788usage PKIX extension, it will be required to match the provided OID 7789or be marked for any purpose, otherwise verification will fail with 7790@code{GNUTLS_CERT_PURPOSE_MISMATCH} status. 7791 7792@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7793negative error value. Note that verification failure will not result to an 7794error code, only @code{voutput} will be updated. 7795 7796@strong{Since:} 3.3.8 7797@end deftypefun 7798 7799@subheading gnutls_x509_trust_list_verify_named_crt 7800@anchor{gnutls_x509_trust_list_verify_named_crt} 7801@deftypefun {int} {gnutls_x509_trust_list_verify_named_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, const void * @var{name}, size_t @var{name_size}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) 7802@var{list}: The list 7803 7804@var{cert}: is the certificate to be verified 7805 7806@var{name}: is the certificate's name 7807 7808@var{name_size}: is the certificate's name size 7809 7810@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. 7811 7812@var{voutput}: will hold the certificate verification output. 7813 7814@var{func}: If non-null will be called on each chain element verification with the output. 7815 7816This function will try to find a certificate that is associated with the provided 7817name --see @code{gnutls_x509_trust_list_add_named_crt()} . If a match is found the 7818certificate is considered valid. In addition to that this function will also 7819check CRLs. The @code{voutput} parameter will hold an OR'ed sequence of 7820@code{gnutls_certificate_status_t} flags. 7821 7822Additionally a certificate verification profile can be specified 7823from the ones in @code{gnutls_certificate_verification_profiles_t} by 7824ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification 7825flags. 7826 7827@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 7828negative error value. 7829 7830@strong{Since:} 3.0.0 7831@end deftypefun 7832 7833