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.
7 @var{tlist}: Location where to store the trust list.
9 Obtains the list of trusted certificates stored in @code{res} and writes a
10 pointer to it to the location @code{tlist} . The pointer will point to memory
11 internal to @code{res} , and must not be deinitialized. It will be automatically
12 deallocated when the @code{res} structure is deinitialized.
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.
22 @var{tlist}: is a @code{gnutls_x509_trust_list_t} type
24 @var{flags}: must be zero
26 This function sets a trust list in the gnutls_certificate_credentials_t type.
28 Note that the @code{tlist} will become part of the credentials
29 structure and must not be deallocated. It will be automatically deallocated
30 when the @code{res} structure is deinitialized.
32 @strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code.
37 @subheading gnutls_pkcs8_info
38 @anchor{gnutls_pkcs8_info}
39 @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})
40 @var{data}: Holds the PKCS @code{8} data
42 @var{format}: the format of the PKCS @code{8} data
44 @var{schema}: indicate the schema as one of @code{gnutls_pkcs_encrypt_flags_t}
46 @var{cipher}: the cipher used as @code{gnutls_cipher_algorithm_t}
48 @var{salt}: PBKDF2 salt (if non-NULL then @code{salt_size} initially holds its size)
50 @var{salt_size}: PBKDF2 salt size
52 @var{iter_count}: PBKDF2 iteration count
54 @var{oid}: if non-NULL it will contain an allocated null-terminated variable with the OID
56 This function will provide information on the algorithms used
57 in a particular PKCS @code{8} structure. If the structure algorithms
58 are unknown the code @code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} will be returned,
59 and only @code{oid} , will be set. That is, @code{oid} will be set on encrypted PKCS @code{8}
60 structures whether supported or not. It must be deinitialized using @code{gnutls_free()} .
61 The other variables are only set on supported structures.
63 @strong{Returns:} @code{GNUTLS_E_INVALID_REQUEST} if the provided structure isn't encrypted,
64 @code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} if the structure's encryption isn't supported, or
65 another negative error code in case of a failure. Zero on success.
68 @subheading gnutls_pkcs_schema_get_name
69 @anchor{gnutls_pkcs_schema_get_name}
70 @deftypefun {const char *} {gnutls_pkcs_schema_get_name} (unsigned int @var{schema})
71 @var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} )
73 This function will return a human readable description of the
74 PKCS12 or PBES2 schema.
76 @strong{Returns:} a constrant string or @code{NULL} on error.
81 @subheading gnutls_pkcs_schema_get_oid
82 @anchor{gnutls_pkcs_schema_get_oid}
83 @deftypefun {const char *} {gnutls_pkcs_schema_get_oid} (unsigned int @var{schema})
84 @var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} )
86 This function will return the object identifier of the
87 PKCS12 or PBES2 schema.
89 @strong{Returns:} a constrant string or @code{NULL} on error.
94 @subheading gnutls_subject_alt_names_deinit
95 @anchor{gnutls_subject_alt_names_deinit}
96 @deftypefun {void} {gnutls_subject_alt_names_deinit} (gnutls_subject_alt_names_t @var{sans})
97 @var{sans}: The alternative names
99 This function will deinitialize an alternative names structure.
101 @strong{Since:} 3.3.0
104 @subheading gnutls_subject_alt_names_get
105 @anchor{gnutls_subject_alt_names_get}
106 @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})
107 @var{sans}: The alternative names
109 @var{seq}: The index of the name to get
111 @var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} )
113 @var{san}: The alternative name data (should be treated as constant)
115 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} (should be treated as constant)
117 This function will return a specific alternative name as stored in
118 the @code{sans} type. The returned values should be treated as constant
119 and valid for the lifetime of @code{sans} .
121 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
122 if the index is out of bounds, otherwise a negative error value.
124 @strong{Since:} 3.3.0
127 @subheading gnutls_subject_alt_names_init
128 @anchor{gnutls_subject_alt_names_init}
129 @deftypefun {int} {gnutls_subject_alt_names_init} (gnutls_subject_alt_names_t * @var{sans})
130 @var{sans}: The alternative names
132 This function will initialize an alternative names structure.
134 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
136 @strong{Since:} 3.3.0
139 @subheading gnutls_subject_alt_names_set
140 @anchor{gnutls_subject_alt_names_set}
141 @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})
142 @var{sans}: The alternative names
144 @var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
146 @var{san}: The alternative name data
148 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
150 This function will store the specified alternative name in
153 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
155 @strong{Since:} 3.3.0
158 @subheading gnutls_x509_aia_deinit
159 @anchor{gnutls_x509_aia_deinit}
160 @deftypefun {void} {gnutls_x509_aia_deinit} (gnutls_x509_aia_t @var{aia})
161 @var{aia}: The authority info access
163 This function will deinitialize an authority info access type.
165 @strong{Since:} 3.3.0
168 @subheading gnutls_x509_aia_get
169 @anchor{gnutls_x509_aia_get}
170 @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})
171 @var{aia}: The authority info access
173 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
175 @var{oid}: the type of available data; to be treated as constant.
177 @var{san_type}: Will hold the type of the name of @code{gnutls_subject_alt_names_t} (may be null).
179 @var{san}: the access location name; to be treated as constant (may be null).
181 This function reads from the Authority Information Access type.
183 The @code{seq} input parameter is used to indicate which member of the
184 sequence the caller is interested in. The first member is 0, the
185 second member 1 and so on. When the @code{seq} value is out of bounds,
186 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
188 Typically @code{oid} is @code{GNUTLS_OID_AD_CAISSUERS} or @code{GNUTLS_OID_AD_OCSP} .
190 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
192 @strong{Since:} 3.3.0
195 @subheading gnutls_x509_aia_init
196 @anchor{gnutls_x509_aia_init}
197 @deftypefun {int} {gnutls_x509_aia_init} (gnutls_x509_aia_t * @var{aia})
198 @var{aia}: The authority info access
200 This function will initialize an authority info access type.
202 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
204 @strong{Since:} 3.3.0
207 @subheading gnutls_x509_aia_set
208 @anchor{gnutls_x509_aia_set}
209 @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})
210 @var{aia}: The authority info access
212 @var{oid}: the type of data.
214 @var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
216 @var{san}: The alternative name data
218 This function will store the specified alternative name in
221 Typically the value for @code{oid} should be @code{GNUTLS_OID_AD_OCSP} , or
222 @code{GNUTLS_OID_AD_CAISSUERS} .
224 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
226 @strong{Since:} 3.3.0
229 @subheading gnutls_x509_aki_deinit
230 @anchor{gnutls_x509_aki_deinit}
231 @deftypefun {void} {gnutls_x509_aki_deinit} (gnutls_x509_aki_t @var{aki})
232 @var{aki}: The authority key identifier type
234 This function will deinitialize an authority key identifier.
236 @strong{Since:} 3.3.0
239 @subheading gnutls_x509_aki_get_cert_issuer
240 @anchor{gnutls_x509_aki_get_cert_issuer}
241 @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})
242 @var{aki}: The authority key ID
244 @var{seq}: The index of the name to get
246 @var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} )
248 @var{san}: The alternative name data
250 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
252 @var{serial}: The authorityCertSerialNumber number
254 This function will return a specific authorityCertIssuer name as stored in
255 the @code{aki} type, as well as the authorityCertSerialNumber. All the returned
256 values should be treated as constant, and may be set to @code{NULL} when are not required.
258 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
259 if the index is out of bounds, otherwise a negative error value.
261 @strong{Since:} 3.3.0
264 @subheading gnutls_x509_aki_get_id
265 @anchor{gnutls_x509_aki_get_id}
266 @deftypefun {int} {gnutls_x509_aki_get_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{id})
267 @var{aki}: The authority key ID
269 @var{id}: Will hold the identifier
271 This function will return the key identifier as stored in
272 the @code{aki} type. The identifier should be treated as constant.
274 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
275 if the index is out of bounds, otherwise a negative error value.
277 @strong{Since:} 3.3.0
280 @subheading gnutls_x509_aki_init
281 @anchor{gnutls_x509_aki_init}
282 @deftypefun {int} {gnutls_x509_aki_init} (gnutls_x509_aki_t * @var{aki})
283 @var{aki}: The authority key ID type
285 This function will initialize an authority key ID.
287 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
289 @strong{Since:} 3.3.0
292 @subheading gnutls_x509_aki_set_cert_issuer
293 @anchor{gnutls_x509_aki_set_cert_issuer}
294 @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})
295 @var{aki}: The authority key ID
297 @var{san_type}: the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null
299 @var{san}: The alternative name data
301 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
303 @var{serial}: The authorityCertSerialNumber number (may be null)
305 This function will set the authorityCertIssuer name and the authorityCertSerialNumber
306 to be stored in the @code{aki} type. When storing multiple names, the serial
307 should be set on the first call, and subsequent calls should use a @code{NULL} serial.
309 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
311 @strong{Since:} 3.3.0
314 @subheading gnutls_x509_aki_set_id
315 @anchor{gnutls_x509_aki_set_id}
316 @deftypefun {int} {gnutls_x509_aki_set_id} (gnutls_x509_aki_t @var{aki}, const gnutls_datum_t * @var{id})
317 @var{aki}: The authority key ID
319 @var{id}: the key identifier
321 This function will set the keyIdentifier to be stored in the @code{aki} type.
323 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
325 @strong{Since:} 3.3.0
328 @subheading gnutls_x509_crl_check_issuer
329 @anchor{gnutls_x509_crl_check_issuer}
330 @deftypefun {int} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer})
331 @var{crl}: is the CRL to be checked
333 @var{issuer}: is the certificate of a possible issuer
335 This function will check if the given CRL was issued by the given
338 @strong{Returns:} true (1) if the given CRL was issued by the given issuer,
339 and false (0) if not.
342 @subheading gnutls_x509_crl_deinit
343 @anchor{gnutls_x509_crl_deinit}
344 @deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl})
345 @var{crl}: The data to be deinitialized
347 This function will deinitialize a CRL structure.
350 @subheading gnutls_x509_crl_dist_points_deinit
351 @anchor{gnutls_x509_crl_dist_points_deinit}
352 @deftypefun {void} {gnutls_x509_crl_dist_points_deinit} (gnutls_x509_crl_dist_points_t @var{cdp})
353 @var{cdp}: The CRL distribution points
355 This function will deinitialize a CRL distribution points type.
357 @strong{Since:} 3.3.0
360 @subheading gnutls_x509_crl_dist_points_get
361 @anchor{gnutls_x509_crl_dist_points_get}
362 @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})
363 @var{cdp}: The CRL distribution points
365 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
367 @var{type}: The name type of the corresponding name (gnutls_x509_subject_alt_name_t)
369 @var{san}: The distribution point names (to be treated as constant)
371 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
373 This function retrieves the individual CRL distribution points (2.5.29.31),
374 contained in provided type.
376 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
377 if the index is out of bounds, otherwise a negative error value.
380 @subheading gnutls_x509_crl_dist_points_init
381 @anchor{gnutls_x509_crl_dist_points_init}
382 @deftypefun {int} {gnutls_x509_crl_dist_points_init} (gnutls_x509_crl_dist_points_t * @var{cdp})
383 @var{cdp}: The CRL distribution points
385 This function will initialize a CRL distribution points type.
387 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
389 @strong{Since:} 3.3.0
392 @subheading gnutls_x509_crl_dist_points_set
393 @anchor{gnutls_x509_crl_dist_points_set}
394 @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})
395 @var{cdp}: The CRL distribution points
397 @var{type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
399 @var{san}: The point name data
401 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
403 This function will store the specified CRL distribution point value
406 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
408 @strong{Since:} 3.3.0
411 @subheading gnutls_x509_crl_export
412 @anchor{gnutls_x509_crl_export}
413 @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})
414 @var{crl}: Holds the revocation list
416 @var{format}: the format of output params. One of PEM or DER.
418 @var{output_data}: will contain a private key PEM or DER encoded
420 @var{output_data_size}: holds the size of output_data (and will
421 be replaced by the actual size of parameters)
423 This function will export the revocation list to DER or PEM format.
425 If the buffer provided is not long enough to hold the output, then
426 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
428 If the structure is PEM encoded, it will have a header
431 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
432 negative error value.
435 @subheading gnutls_x509_crl_export2
436 @anchor{gnutls_x509_crl_export2}
437 @deftypefun {int} {gnutls_x509_crl_export2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
438 @var{crl}: Holds the revocation list
440 @var{format}: the format of output params. One of PEM or DER.
442 @var{out}: will contain a private key PEM or DER encoded
444 This function will export the revocation list to DER or PEM format.
446 The output buffer is allocated using @code{gnutls_malloc()} .
448 If the structure is PEM encoded, it will have a header
451 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
452 negative error value.
457 @subheading gnutls_x509_crl_get_authority_key_gn_serial
458 @anchor{gnutls_x509_crl_get_authority_key_gn_serial}
459 @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})
460 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
462 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
464 @var{alt}: is the place where the alternative name will be copied to
466 @var{alt_size}: holds the size of alt.
468 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
470 @var{serial}: buffer to store the serial number (may be null)
472 @var{serial_size}: Holds the size of the serial field (may be null)
474 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
476 This function will return the X.509 authority key
477 identifier when stored as a general name (authorityCertIssuer)
480 Because more than one general names might be stored
481 @code{seq} can be used as a counter to request them all until
482 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
484 @strong{Returns:} Returns 0 on success, or an error code.
489 @subheading gnutls_x509_crl_get_authority_key_id
490 @anchor{gnutls_x509_crl_get_authority_key_id}
491 @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})
492 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
494 @var{id}: The place where the identifier will be copied
496 @var{id_size}: Holds the size of the result field.
498 @var{critical}: will be non-zero if the extension is marked as critical
501 This function will return the CRL authority's key identifier. This
502 is obtained by the X.509 Authority Key identifier extension field
503 (2.5.29.35). Note that this function
504 only returns the keyIdentifier field of the extension and
505 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
506 the name and serial number of the certificate. In that case
507 @code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used.
509 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
510 negative error code in case of an error.
512 @strong{Since:} 2.8.0
515 @subheading gnutls_x509_crl_get_crt_count
516 @anchor{gnutls_x509_crl_get_crt_count}
517 @deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl})
518 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
520 This function will return the number of revoked certificates in the
523 @strong{Returns:} number of certificates, a negative error code on failure.
526 @subheading gnutls_x509_crl_get_crt_serial
527 @anchor{gnutls_x509_crl_get_crt_serial}
528 @deftypefun {int} {gnutls_x509_crl_get_crt_serial} (gnutls_x509_crl_t @var{crl}, int @var{indx}, unsigned char * @var{serial}, size_t * @var{serial_size}, time_t * @var{t})
529 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
531 @var{indx}: the index of the certificate to extract (starting from 0)
533 @var{serial}: where the serial number will be copied
535 @var{serial_size}: initially holds the size of serial
537 @var{t}: if non null, will hold the time this certificate was revoked
539 This function will retrieve the serial number of the specified, by
540 the index, revoked certificate.
542 Note that this function will have performance issues in large sequences
543 of revoked certificates. In that case use @code{gnutls_x509_crl_iter_crt_serial()} .
545 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
546 negative error value.
549 @subheading gnutls_x509_crl_get_dn_oid
550 @anchor{gnutls_x509_crl_get_dn_oid}
551 @deftypefun {int} {gnutls_x509_crl_get_dn_oid} (gnutls_x509_crl_t @var{crl}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
552 @var{crl}: should contain a gnutls_x509_crl_t type
554 @var{indx}: Specifies which DN OID to send. Use (0) to get the first one.
556 @var{oid}: a pointer to store the OID (may be null)
558 @var{sizeof_oid}: initially holds the size of 'oid'
560 This function will extract the requested OID of the name of the CRL
561 issuer, specified by the given index.
563 If oid is null then only the size will be filled.
565 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
566 not long enough, and in that case the sizeof_oid will be updated
567 with the required size. On success 0 is returned.
570 @subheading gnutls_x509_crl_get_extension_data
571 @anchor{gnutls_x509_crl_get_extension_data}
572 @deftypefun {int} {gnutls_x509_crl_get_extension_data} (gnutls_x509_crl_t @var{crl}, int @var{indx}, void * @var{data}, size_t * @var{sizeof_data})
573 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
575 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
577 @var{data}: a pointer to a structure to hold the data (may be null)
579 @var{sizeof_data}: initially holds the size of @code{oid}
581 This function will return the requested extension data in the CRL.
582 The extension data will be stored as a string in the provided
585 Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and
586 critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead,
587 if you want to get data indexed by the extension OID rather than
590 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
591 negative error code in case of an error. If your have reached the
592 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
595 @strong{Since:} 2.8.0
598 @subheading gnutls_x509_crl_get_extension_data2
599 @anchor{gnutls_x509_crl_get_extension_data2}
600 @deftypefun {int} {gnutls_x509_crl_get_extension_data2} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, gnutls_datum_t * @var{data})
601 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
603 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
605 @var{data}: will contain the extension DER-encoded data
607 This function will return the requested by the index extension data in the
608 certificate revocation list. The extension data will be allocated using
609 @code{gnutls_malloc()} .
611 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
613 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
614 otherwise a negative error code is returned. If you have reached the
615 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
619 @subheading gnutls_x509_crl_get_extension_info
620 @anchor{gnutls_x509_crl_get_extension_info}
621 @deftypefun {int} {gnutls_x509_crl_get_extension_info} (gnutls_x509_crl_t @var{crl}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical})
622 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
624 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
626 @var{oid}: a pointer to store the OID
628 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
629 holds actual size of @code{oid} .
631 @var{critical}: output variable with critical flag, may be NULL.
633 This function will return the requested extension OID in the CRL,
634 and the critical flag for it. The extension OID will be stored as
635 a string in the provided buffer. Use
636 @code{gnutls_x509_crl_get_extension_data()} to extract the data.
638 If the buffer provided is not long enough to hold the output, then
639 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
642 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
643 negative error code in case of an error. If your have reached the
644 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
647 @strong{Since:} 2.8.0
650 @subheading gnutls_x509_crl_get_extension_oid
651 @anchor{gnutls_x509_crl_get_extension_oid}
652 @deftypefun {int} {gnutls_x509_crl_get_extension_oid} (gnutls_x509_crl_t @var{crl}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
653 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
655 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
657 @var{oid}: a pointer to store the OID (may be null)
659 @var{sizeof_oid}: initially holds the size of @code{oid}
661 This function will return the requested extension OID in the CRL.
662 The extension OID will be stored as a string in the provided
665 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
666 negative error code in case of an error. If your have reached the
667 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
670 @strong{Since:} 2.8.0
673 @subheading gnutls_x509_crl_get_issuer_dn
674 @anchor{gnutls_x509_crl_get_issuer_dn}
675 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (const gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf})
676 @var{crl}: should contain a gnutls_x509_crl_t type
678 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
680 @var{sizeof_buf}: initially holds the size of @code{buf}
682 This function will copy the name of the CRL issuer in the provided
683 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
684 described in RFC4514. The output string will be ASCII or UTF-8
685 encoded, depending on the certificate data.
687 If buf is @code{NULL} then only the size will be filled.
689 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
690 not long enough, and in that case the sizeof_buf will be updated
691 with the required size, and 0 on success.
694 @subheading gnutls_x509_crl_get_issuer_dn2
695 @anchor{gnutls_x509_crl_get_issuer_dn2}
696 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn2} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
697 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
699 @var{dn}: a pointer to a structure to hold the name
701 This function will allocate buffer and copy the name of the CRL issuer.
702 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
703 described in RFC4514. The output string will be ASCII or UTF-8
704 encoded, depending on the certificate data.
706 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
707 negative error value.
709 @strong{Since:} 3.1.10
712 @subheading gnutls_x509_crl_get_issuer_dn_by_oid
713 @anchor{gnutls_x509_crl_get_issuer_dn_by_oid}
714 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn_by_oid} (gnutls_x509_crl_t @var{crl}, const char * @var{oid}, int @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{sizeof_buf})
715 @var{crl}: should contain a gnutls_x509_crl_t type
717 @var{oid}: holds an Object Identified in null terminated string
719 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
721 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
723 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
725 @var{sizeof_buf}: initially holds the size of @code{buf}
727 This function will extract the part of the name of the CRL issuer
728 specified by the given OID. The output will be encoded as described
729 in RFC4514. The output string will be ASCII or UTF-8 encoded,
730 depending on the certificate data.
732 Some helper macros with popular OIDs can be found in gnutls/x509.h
733 If raw flag is (0), this function will only return known OIDs as
734 text. Other OIDs will be DER encoded, as described in RFC4514 -- in
735 hex format with a '#' prefix. You can check about known OIDs
736 using @code{gnutls_x509_dn_oid_known()} .
738 If buf is null then only the size will be filled.
740 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
741 not long enough, and in that case the sizeof_buf will be updated
742 with the required size, and 0 on success.
745 @subheading gnutls_x509_crl_get_next_update
746 @anchor{gnutls_x509_crl_get_next_update}
747 @deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl})
748 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
750 This function will return the time the next CRL will be issued.
751 This field is optional in a CRL so it might be normal to get an
754 @strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error.
757 @subheading gnutls_x509_crl_get_number
758 @anchor{gnutls_x509_crl_get_number}
759 @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})
760 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
762 @var{ret}: The place where the number will be copied
764 @var{ret_size}: Holds the size of the result field.
766 @var{critical}: will be non-zero if the extension is marked as critical
769 This function will return the CRL number extension. This is
770 obtained by the CRL Number extension field (2.5.29.20).
772 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
773 negative error code in case of an error.
775 @strong{Since:} 2.8.0
778 @subheading gnutls_x509_crl_get_raw_issuer_dn
779 @anchor{gnutls_x509_crl_get_raw_issuer_dn}
780 @deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
781 @var{crl}: should contain a gnutls_x509_crl_t type
783 @var{dn}: will hold the starting point of the DN
785 This function will return a pointer to the DER encoded DN structure
788 @strong{Returns:} a negative error code on error, and (0) on success.
790 @strong{Since:} 2.12.0
793 @subheading gnutls_x509_crl_get_signature
794 @anchor{gnutls_x509_crl_get_signature}
795 @deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig})
796 @var{crl}: should contain a gnutls_x509_crl_t type
798 @var{sig}: a pointer where the signature part will be copied (may be null).
800 @var{sizeof_sig}: initially holds the size of @code{sig}
802 This function will extract the signature field of a CRL.
804 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
805 negative error value.
808 @subheading gnutls_x509_crl_get_signature_algorithm
809 @anchor{gnutls_x509_crl_get_signature_algorithm}
810 @deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl})
811 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
813 This function will return a value of the @code{gnutls_sign_algorithm_t}
814 enumeration that is the signature algorithm.
816 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
817 negative error value.
820 @subheading gnutls_x509_crl_get_this_update
821 @anchor{gnutls_x509_crl_get_this_update}
822 @deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl})
823 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
825 This function will return the time this CRL was issued.
827 @strong{Returns:} when the CRL was issued, or (time_t)-1 on error.
830 @subheading gnutls_x509_crl_get_version
831 @anchor{gnutls_x509_crl_get_version}
832 @deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl})
833 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
835 This function will return the version of the specified CRL.
837 @strong{Returns:} The version number, or a negative error code on error.
840 @subheading gnutls_x509_crl_import
841 @anchor{gnutls_x509_crl_import}
842 @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})
843 @var{crl}: The data to store the parsed CRL.
845 @var{data}: The DER or PEM encoded CRL.
847 @var{format}: One of DER or PEM
849 This function will convert the given DER or PEM encoded CRL
850 to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'.
852 If the CRL is PEM encoded it should have a header of "X509 CRL".
854 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
855 negative error value.
858 @subheading gnutls_x509_crl_init
859 @anchor{gnutls_x509_crl_init}
860 @deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl})
861 @var{crl}: A pointer to the type to be initialized
863 This function will initialize a CRL structure. CRL stands for
864 Certificate Revocation List. A revocation list usually contains
865 lists of certificate serial numbers that have been revoked by an
866 Authority. The revocation lists are always signed with the
867 authority's private key.
869 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
870 negative error value.
873 @subheading gnutls_x509_crl_iter_crt_serial
874 @anchor{gnutls_x509_crl_iter_crt_serial}
875 @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})
876 @var{crl}: should contain a @code{gnutls_x509_crl_t} type
878 @var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} )
880 @var{serial}: where the serial number will be copied
882 @var{serial_size}: initially holds the size of serial
884 @var{t}: if non null, will hold the time this certificate was revoked
886 This function performs the same as @code{gnutls_x509_crl_get_crt_serial()} ,
887 but reads sequentially and keeps state in the iterator
888 between calls. That allows it to provide better performance in sequences
889 with many elements (50000+).
891 When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
892 is returned and the iterator is reset.
894 After use, the iterator must be deinitialized using @code{gnutls_x509_crl_iter_deinit()} .
896 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
897 negative error value.
900 @subheading gnutls_x509_crl_iter_deinit
901 @anchor{gnutls_x509_crl_iter_deinit}
902 @deftypefun {void} {gnutls_x509_crl_iter_deinit} (gnutls_x509_crl_iter_t @var{iter})
903 @var{iter}: The iterator to be deinitialized
905 This function will deinitialize an iterator type.
908 @subheading gnutls_x509_crl_list_import
909 @anchor{gnutls_x509_crl_list_import}
910 @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})
911 @var{crls}: Indicates where the parsed CRLs will be copied to. Must not be initialized.
913 @var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available.
915 @var{data}: The PEM encoded CRLs
917 @var{format}: One of DER or PEM.
919 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
921 This function will convert the given PEM encoded CRL list
922 to the native gnutls_x509_crl_t format. The output will be stored
923 in @code{crls} . They will be automatically initialized.
925 If the Certificate is PEM encoded it should have a header of "X509 CRL".
927 @strong{Returns:} the number of certificates read or a negative error value.
932 @subheading gnutls_x509_crl_list_import2
933 @anchor{gnutls_x509_crl_list_import2}
934 @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})
935 @var{crls}: Will contain the parsed crl list.
937 @var{size}: It will contain the size of the list.
939 @var{data}: The PEM encoded CRL.
941 @var{format}: One of DER or PEM.
943 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
945 This function will convert the given PEM encoded CRL list
946 to the native gnutls_x509_crl_t format. The output will be stored
947 in @code{crls} . They will be automatically initialized.
949 If the Certificate is PEM encoded it should have a header of "X509
952 @strong{Returns:} the number of certificates read or a negative error value.
957 @subheading gnutls_x509_crl_print
958 @anchor{gnutls_x509_crl_print}
959 @deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
960 @var{crl}: The data to be printed
962 @var{format}: Indicate the format to use
964 @var{out}: Newly allocated datum with null terminated string.
966 This function will pretty print a X.509 certificate revocation
967 list, suitable for display to a human.
969 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
971 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
972 negative error value.
975 @subheading gnutls_x509_crl_set_authority_key_id
976 @anchor{gnutls_x509_crl_set_authority_key_id}
977 @deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size})
978 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
982 @var{id_size}: Holds the size of the serial field.
984 This function will set the CRL's authority key ID extension. Only
985 the keyIdentifier field can be set with this function. This may
986 be used by an authority that holds multiple private keys, to distinguish
989 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
990 negative error value.
992 @strong{Since:} 2.8.0
995 @subheading gnutls_x509_crl_set_crt
996 @anchor{gnutls_x509_crl_set_crt}
997 @deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time})
998 @var{crl}: should contain a gnutls_x509_crl_t type
1000 @var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate
1002 @var{revocation_time}: The time this certificate was revoked
1004 This function will set a revoked certificate's serial number to the CRL.
1006 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1007 negative error value.
1010 @subheading gnutls_x509_crl_set_crt_serial
1011 @anchor{gnutls_x509_crl_set_crt_serial}
1012 @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})
1013 @var{crl}: should contain a gnutls_x509_crl_t type
1015 @var{serial}: The revoked certificate's serial number
1017 @var{serial_size}: Holds the size of the serial field.
1019 @var{revocation_time}: The time this certificate was revoked
1021 This function will set a revoked certificate's serial number to the CRL.
1023 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1024 negative error value.
1027 @subheading gnutls_x509_crl_set_next_update
1028 @anchor{gnutls_x509_crl_set_next_update}
1029 @deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time})
1030 @var{crl}: should contain a gnutls_x509_crl_t type
1032 @var{exp_time}: The actual time
1034 This function will set the time this CRL will be updated.
1036 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1037 negative error value.
1040 @subheading gnutls_x509_crl_set_number
1041 @anchor{gnutls_x509_crl_set_number}
1042 @deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size})
1043 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1045 @var{nr}: The CRL number
1047 @var{nr_size}: Holds the size of the nr field.
1049 This function will set the CRL's number extension. This
1050 is to be used as a unique and monotonic number assigned to
1051 the CRL by the authority.
1053 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1054 negative error value.
1056 @strong{Since:} 2.8.0
1059 @subheading gnutls_x509_crl_set_this_update
1060 @anchor{gnutls_x509_crl_set_this_update}
1061 @deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time})
1062 @var{crl}: should contain a gnutls_x509_crl_t type
1064 @var{act_time}: The actual time
1066 This function will set the time this CRL was issued.
1068 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1069 negative error value.
1072 @subheading gnutls_x509_crl_set_version
1073 @anchor{gnutls_x509_crl_set_version}
1074 @deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version})
1075 @var{crl}: should contain a gnutls_x509_crl_t type
1077 @var{version}: holds the version number. For CRLv1 crls must be 1.
1079 This function will set the version of the CRL. This
1080 must be one for CRL version 1, and so on. The CRLs generated
1081 by gnutls should have a version number of 2.
1083 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1084 negative error value.
1087 @subheading gnutls_x509_crl_sign2
1088 @anchor{gnutls_x509_crl_sign2}
1089 @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})
1090 @var{crl}: should contain a gnutls_x509_crl_t type
1092 @var{issuer}: is the certificate of the certificate issuer
1094 @var{issuer_key}: holds the issuer's private key
1096 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1098 @var{flags}: must be 0
1100 This function will sign the CRL with the issuer's private key, and
1101 will copy the issuer's information into the CRL.
1103 This must be the last step in a certificate CRL since all
1104 the previously set parameters are now signed.
1106 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1107 negative error value.
1110 @subheading gnutls_x509_crl_verify
1111 @anchor{gnutls_x509_crl_verify}
1112 @deftypefun {int} {gnutls_x509_crl_verify} (gnutls_x509_crl_t @var{crl}, const gnutls_x509_crt_t * @var{trusted_cas}, int @var{tcas_size}, unsigned int @var{flags}, unsigned int * @var{verify})
1113 @var{crl}: is the crl to be verified
1115 @var{trusted_cas}: is a certificate list that is considered to be trusted one
1117 @var{tcas_size}: holds the number of CA certificates in CA_list
1119 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1121 @var{verify}: will hold the crl verification output.
1123 This function will try to verify the given crl and return its verification status.
1124 See @code{gnutls_x509_crt_list_verify()} for a detailed description of
1125 return values. Note that since GnuTLS 3.1.4 this function includes
1128 Note that value in @code{verify} is set only when the return value of this
1129 function is success (i.e, failure to trust a CRL a certificate does not imply
1130 a negative return value).
1132 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1133 negative error value.
1136 @subheading gnutls_x509_crq_deinit
1137 @anchor{gnutls_x509_crq_deinit}
1138 @deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq})
1139 @var{crq}: the type to be deinitialized
1141 This function will deinitialize a PKCS@code{10} certificate request
1145 @subheading gnutls_x509_crq_export
1146 @anchor{gnutls_x509_crq_export}
1147 @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})
1148 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1150 @var{format}: the format of output params. One of PEM or DER.
1152 @var{output_data}: will contain a certificate request PEM or DER encoded
1154 @var{output_data_size}: holds the size of output_data (and will be
1155 replaced by the actual size of parameters)
1157 This function will export the certificate request to a PEM or DER
1158 encoded PKCS10 structure.
1160 If the buffer provided is not long enough to hold the output, then
1161 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and
1162 * @code{output_data_size} will be updated.
1164 If the structure is PEM encoded, it will have a header of "BEGIN
1165 NEW CERTIFICATE REQUEST".
1167 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1168 negative error value.
1171 @subheading gnutls_x509_crq_export2
1172 @anchor{gnutls_x509_crq_export2}
1173 @deftypefun {int} {gnutls_x509_crq_export2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
1174 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1176 @var{format}: the format of output params. One of PEM or DER.
1178 @var{out}: will contain a certificate request PEM or DER encoded
1180 This function will export the certificate request to a PEM or DER
1181 encoded PKCS10 structure.
1183 The output buffer is allocated using @code{gnutls_malloc()} .
1185 If the structure is PEM encoded, it will have a header of "BEGIN
1186 NEW CERTIFICATE REQUEST".
1188 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1189 negative error value.
1194 @subheading gnutls_x509_crq_get_attribute_by_oid
1195 @anchor{gnutls_x509_crq_get_attribute_by_oid}
1196 @deftypefun {int} {gnutls_x509_crq_get_attribute_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size})
1197 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1199 @var{oid}: holds an Object Identifier in null-terminated string
1201 @var{indx}: In case multiple same OIDs exist in the attribute list, this
1202 specifies which to get, use (0) to get the first one
1204 @var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} )
1206 @var{buf_size}: initially holds the size of @code{buf}
1208 This function will return the attribute in the certificate request
1209 specified by the given Object ID. The attribute will be DER
1212 Attributes in a certificate request is an optional set of data
1213 appended to the request. Their interpretation depends on the CA policy.
1215 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1216 negative error value.
1219 @subheading gnutls_x509_crq_get_attribute_data
1220 @anchor{gnutls_x509_crq_get_attribute_data}
1221 @deftypefun {int} {gnutls_x509_crq_get_attribute_data} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{data}, size_t * @var{sizeof_data})
1222 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1224 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1226 @var{data}: a pointer to a structure to hold the data (may be null)
1228 @var{sizeof_data}: initially holds the size of @code{oid}
1230 This function will return the requested attribute data in the
1231 certificate request. The attribute data will be stored as a string in the
1234 Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID.
1235 Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead,
1236 if you want to get data indexed by the attribute OID rather than
1239 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1240 negative error code in case of an error. If your have reached the
1241 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1244 @strong{Since:} 2.8.0
1247 @subheading gnutls_x509_crq_get_attribute_info
1248 @anchor{gnutls_x509_crq_get_attribute_info}
1249 @deftypefun {int} {gnutls_x509_crq_get_attribute_info} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
1250 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1252 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1254 @var{oid}: a pointer to a structure to hold the OID
1256 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1257 holds actual size of @code{oid} .
1259 This function will return the requested attribute OID in the
1260 certificate, and the critical flag for it. The attribute OID will
1261 be stored as a string in the provided buffer. Use
1262 @code{gnutls_x509_crq_get_attribute_data()} to extract the data.
1264 If the buffer provided is not long enough to hold the output, then
1265 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1268 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1269 negative error code in case of an error. If your have reached the
1270 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1273 @strong{Since:} 2.8.0
1276 @subheading gnutls_x509_crq_get_basic_constraints
1277 @anchor{gnutls_x509_crq_get_basic_constraints}
1278 @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})
1279 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1281 @var{critical}: will be non-zero if the extension is marked as critical
1283 @var{ca}: pointer to output integer indicating CA status, may be NULL,
1284 value is 1 if the certificate CA flag is set, 0 otherwise.
1286 @var{pathlen}: pointer to output integer indicating path length (may be
1287 NULL), non-negative error codes indicate a present pathLenConstraint
1288 field and the actual value, -1 indicate that the field is absent.
1290 This function will read the certificate's basic constraints, and
1291 return the certificates CA status. It reads the basicConstraints
1292 X.509 extension (2.5.29.19).
1294 @strong{Returns:} If the certificate is a CA a positive value will be
1295 returned, or (0) if the certificate does not have CA flag set.
1296 A negative error code may be returned in case of errors. If the
1297 certificate does not contain the basicConstraints extension
1298 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1300 @strong{Since:} 2.8.0
1303 @subheading gnutls_x509_crq_get_challenge_password
1304 @anchor{gnutls_x509_crq_get_challenge_password}
1305 @deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{pass_size})
1306 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1308 @var{pass}: will hold a (0)-terminated password string
1310 @var{pass_size}: Initially holds the size of @code{pass} .
1312 This function will return the challenge password in the request.
1313 The challenge password is intended to be used for requesting a
1314 revocation of the certificate.
1316 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1317 negative error value.
1320 @subheading gnutls_x509_crq_get_dn
1321 @anchor{gnutls_x509_crq_get_dn}
1322 @deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{buf_size})
1323 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1325 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1327 @var{buf_size}: initially holds the size of @code{buf}
1329 This function will copy the name of the Certificate request subject
1330 to the provided buffer. The name will be in the form
1331 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
1332 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate
1335 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
1336 long enough, and in that case the * @code{buf_size} will be updated with
1337 the required size. On success 0 is returned.
1340 @subheading gnutls_x509_crq_get_dn2
1341 @anchor{gnutls_x509_crq_get_dn2}
1342 @deftypefun {int} {gnutls_x509_crq_get_dn2} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn})
1343 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1345 @var{dn}: a pointer to a structure to hold the name
1347 This function will allocate buffer and copy the name of the Certificate
1348 request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
1349 described in RFC4514. The output string will be ASCII or UTF-8
1350 encoded, depending on the certificate data.
1352 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1353 negative error value. and a negative error code on error.
1355 @strong{Since:} 3.1.10
1358 @subheading gnutls_x509_crq_get_dn_by_oid
1359 @anchor{gnutls_x509_crq_get_dn_by_oid}
1360 @deftypefun {int} {gnutls_x509_crq_get_dn_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, int @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size})
1361 @var{crq}: should contain a gnutls_x509_crq_t type
1363 @var{oid}: holds an Object Identifier in a null terminated string
1365 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies
1366 which to get. Use (0) to get the first one.
1368 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
1370 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1372 @var{buf_size}: initially holds the size of @code{buf}
1374 This function will extract the part of the name of the Certificate
1375 request subject, specified by the given OID. The output will be
1376 encoded as described in RFC2253. The output string will be ASCII
1377 or UTF-8 encoded, depending on the certificate data.
1379 Some helper macros with popular OIDs can be found in gnutls/x509.h
1380 If raw flag is (0), this function will only return known OIDs as
1381 text. Other OIDs will be DER encoded, as described in RFC2253 --
1382 in hex format with a '\#' prefix. You can check about known OIDs
1383 using @code{gnutls_x509_dn_oid_known()} .
1385 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1386 not long enough, and in that case the * @code{buf_size} will be
1387 updated with the required size. On success 0 is returned.
1390 @subheading gnutls_x509_crq_get_dn_oid
1391 @anchor{gnutls_x509_crq_get_dn_oid}
1392 @deftypefun {int} {gnutls_x509_crq_get_dn_oid} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
1393 @var{crq}: should contain a gnutls_x509_crq_t type
1395 @var{indx}: Specifies which DN OID to get. Use (0) to get the first one.
1397 @var{oid}: a pointer to a structure to hold the name (may be @code{NULL} )
1399 @var{sizeof_oid}: initially holds the size of @code{oid}
1401 This function will extract the requested OID of the name of the
1402 certificate request subject, specified by the given index.
1404 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1405 not long enough, and in that case the * @code{sizeof_oid} will be
1406 updated with the required size. On success 0 is returned.
1409 @subheading gnutls_x509_crq_get_extension_by_oid
1410 @anchor{gnutls_x509_crq_get_extension_by_oid}
1411 @deftypefun {int} {gnutls_x509_crq_get_extension_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical})
1412 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1414 @var{oid}: holds an Object Identifier in a null terminated string
1416 @var{indx}: In case multiple same OIDs exist in the extensions, this
1417 specifies which to get. Use (0) to get the first one.
1419 @var{buf}: a pointer to a structure to hold the name (may be null)
1421 @var{buf_size}: initially holds the size of @code{buf}
1423 @var{critical}: will be non-zero if the extension is marked as critical
1425 This function will return the extension specified by the OID in
1426 the certificate. The extensions will be returned as binary data
1427 DER encoded, in the provided buffer.
1429 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1430 negative error code in case of an error. If the certificate does not
1431 contain the specified extension
1432 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1434 @strong{Since:} 2.8.0
1437 @subheading gnutls_x509_crq_get_extension_by_oid2
1438 @anchor{gnutls_x509_crq_get_extension_by_oid2}
1439 @deftypefun {int} {gnutls_x509_crq_get_extension_by_oid2} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, int @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical})
1440 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1442 @var{oid}: holds an Object Identifier in a null terminated string
1444 @var{indx}: In case multiple same OIDs exist in the extensions, this
1445 specifies which to get. Use (0) to get the first one.
1447 @var{output}: will hold the allocated extension data
1449 @var{critical}: will be non-zero if the extension is marked as critical
1451 This function will return the extension specified by the OID in
1452 the certificate. The extensions will be returned as binary data
1453 DER encoded, in the provided buffer.
1455 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1456 negative error code in case of an error. If the certificate does not
1457 contain the specified extension
1458 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1460 @strong{Since:} 3.3.8
1463 @subheading gnutls_x509_crq_get_extension_data
1464 @anchor{gnutls_x509_crq_get_extension_data}
1465 @deftypefun {int} {gnutls_x509_crq_get_extension_data} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{data}, size_t * @var{sizeof_data})
1466 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1468 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1470 @var{data}: a pointer to a structure to hold the data (may be null)
1472 @var{sizeof_data}: initially holds the size of @code{oid}
1474 This function will return the requested extension data in the
1475 certificate. The extension data will be stored as a string in the
1478 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and
1479 critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead,
1480 if you want to get data indexed by the extension OID rather than
1483 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1484 negative error code in case of an error. If your have reached the
1485 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1488 @strong{Since:} 2.8.0
1491 @subheading gnutls_x509_crq_get_extension_data2
1492 @anchor{gnutls_x509_crq_get_extension_data2}
1493 @deftypefun {int} {gnutls_x509_crq_get_extension_data2} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, gnutls_datum_t * @var{data})
1494 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1496 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
1498 @var{data}: will contain the extension DER-encoded data
1500 This function will return the requested extension data in the
1501 certificate request. The extension data will be allocated using
1502 @code{gnutls_malloc()} .
1504 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID.
1506 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
1507 otherwise a negative error code is returned. If you have reached the
1508 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1511 @strong{Since:} 3.3.0
1514 @subheading gnutls_x509_crq_get_extension_info
1515 @anchor{gnutls_x509_crq_get_extension_info}
1516 @deftypefun {int} {gnutls_x509_crq_get_extension_info} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical})
1517 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1519 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1521 @var{oid}: a pointer to store the OID
1523 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1524 holds actual size of @code{oid} .
1526 @var{critical}: output variable with critical flag, may be NULL.
1528 This function will return the requested extension OID in the
1529 certificate, and the critical flag for it. The extension OID will
1530 be stored as a string in the provided buffer. Use
1531 @code{gnutls_x509_crq_get_extension_data()} to extract the data.
1533 If the buffer provided is not long enough to hold the output, then
1534 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1537 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1538 negative error code in case of an error. If your have reached the
1539 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1542 @strong{Since:} 2.8.0
1545 @subheading gnutls_x509_crq_get_key_id
1546 @anchor{gnutls_x509_crq_get_key_id}
1547 @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})
1548 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1550 @var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t}
1552 @var{output_data}: will contain the key ID
1554 @var{output_data_size}: holds the size of output_data (and will be
1555 replaced by the actual size of parameters)
1557 This function will return a unique ID that depends on the public key
1558 parameters. This ID can be used in checking whether a certificate
1559 corresponds to the given private key.
1561 If the buffer provided is not long enough to hold the output, then
1562 * @code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1563 be returned. The output will normally be a SHA-1 hash output,
1566 @strong{Returns:} In case of failure a negative error code will be
1567 returned, and 0 on success.
1569 @strong{Since:} 2.8.0
1572 @subheading gnutls_x509_crq_get_key_purpose_oid
1573 @anchor{gnutls_x509_crq_get_key_purpose_oid}
1574 @deftypefun {int} {gnutls_x509_crq_get_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical})
1575 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1577 @var{indx}: This specifies which OID to return, use (0) to get the first one
1579 @var{oid}: a pointer to store the OID (may be @code{NULL} )
1581 @var{sizeof_oid}: initially holds the size of @code{oid}
1583 @var{critical}: output variable with critical flag, may be @code{NULL} .
1585 This function will extract the key purpose OIDs of the Certificate
1586 specified by the given index. These are stored in the Extended Key
1587 Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for
1588 human readable names.
1590 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1591 not long enough, and in that case the * @code{sizeof_oid} will be
1592 updated with the required size. On success 0 is returned.
1594 @strong{Since:} 2.8.0
1597 @subheading gnutls_x509_crq_get_key_rsa_raw
1598 @anchor{gnutls_x509_crq_get_key_rsa_raw}
1599 @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})
1600 @var{crq}: Holds the certificate
1602 @var{m}: will hold the modulus
1604 @var{e}: will hold the public exponent
1606 This function will export the RSA public key's parameters found in
1607 the given structure. The new parameters will be allocated using
1608 @code{gnutls_malloc()} and will be stored in the appropriate datum.
1610 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1611 negative error value.
1613 @strong{Since:} 2.8.0
1616 @subheading gnutls_x509_crq_get_key_usage
1617 @anchor{gnutls_x509_crq_get_key_usage}
1618 @deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
1619 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1621 @var{key_usage}: where the key usage bits will be stored
1623 @var{critical}: will be non-zero if the extension is marked as critical
1625 This function will return certificate's key usage, by reading the
1626 keyUsage X.509 extension (2.5.29.15). The key usage value will
1627 ORed values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
1628 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
1629 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
1630 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
1631 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
1633 @strong{Returns:} the certificate key usage, or a negative error code in case of
1634 parsing error. If the certificate does not contain the keyUsage
1635 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
1638 @strong{Since:} 2.8.0
1641 @subheading gnutls_x509_crq_get_pk_algorithm
1642 @anchor{gnutls_x509_crq_get_pk_algorithm}
1643 @deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits})
1644 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1646 @var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits
1648 This function will return the public key algorithm of a PKCS@code{10}
1649 certificate request.
1651 If bits is non-@code{NULL} , it should have enough size to hold the
1652 parameters size in bits. For RSA the bits returned is the modulus.
1653 For DSA the bits returned are of the public exponent.
1655 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1656 success, or a negative error code on error.
1659 @subheading gnutls_x509_crq_get_private_key_usage_period
1660 @anchor{gnutls_x509_crq_get_private_key_usage_period}
1661 @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})
1662 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1664 @var{activation}: The activation time
1666 @var{expiration}: The expiration time
1668 @var{critical}: the extension status
1670 This function will return the expiration and activation
1671 times of the private key of the certificate.
1673 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1674 if the extension is not present, otherwise a negative error value.
1677 @subheading gnutls_x509_crq_get_signature_algorithm
1678 @anchor{gnutls_x509_crq_get_signature_algorithm}
1679 @deftypefun {int} {gnutls_x509_crq_get_signature_algorithm} (gnutls_x509_crq_t @var{crq})
1680 @var{crq}: should contain a @code{gnutls_x509_cr_t} type
1682 This function will return a value of the @code{gnutls_sign_algorithm_t}
1683 enumeration that is the signature algorithm that has been used to
1684 sign this certificate request.
1686 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code on
1689 @strong{Since:} 3.4.0
1692 @subheading gnutls_x509_crq_get_subject_alt_name
1693 @anchor{gnutls_x509_crq_get_subject_alt_name}
1694 @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})
1695 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1697 @var{seq}: specifies the sequence number of the alt name, 0 for the
1698 first one, 1 for the second etc.
1700 @var{ret}: is the place where the alternative name will be copied to
1702 @var{ret_size}: holds the size of ret.
1704 @var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type
1706 @var{critical}: will be non-zero if the extension is marked as critical
1709 This function will return the alternative names, contained in the
1710 given certificate. It is the same as
1711 @code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it
1712 will return the type of the alternative name in @code{ret_type} even if
1713 the function fails for some reason (i.e. the buffer provided is
1716 @strong{Returns:} the alternative subject name type on success, one of the
1717 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
1718 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
1719 hold the value. In that case @code{ret_size} will be updated with the
1720 required size. If the certificate request does not have an
1721 Alternative name with the specified sequence number then
1722 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1724 @strong{Since:} 2.8.0
1727 @subheading gnutls_x509_crq_get_subject_alt_othername_oid
1728 @anchor{gnutls_x509_crq_get_subject_alt_othername_oid}
1729 @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})
1730 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1732 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1734 @var{ret}: is the place where the otherName OID will be copied to
1736 @var{ret_size}: holds the size of ret.
1738 This function will extract the type OID of an otherName Subject
1739 Alternative Name, contained in the given certificate, and return
1740 the type as an enumerated element.
1742 This function is only useful if
1743 @code{gnutls_x509_crq_get_subject_alt_name()} returned
1744 @code{GNUTLS_SAN_OTHERNAME} .
1746 @strong{Returns:} the alternative subject name type on success, one of the
1747 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs,
1748 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
1749 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
1750 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
1751 @code{ret_size} is not large enough to hold the value. In that case
1752 @code{ret_size} will be updated with the required size. If the
1753 certificate does not have an Alternative name with the specified
1754 sequence number and with the otherName type then
1755 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1757 @strong{Since:} 2.8.0
1760 @subheading gnutls_x509_crq_get_version
1761 @anchor{gnutls_x509_crq_get_version}
1762 @deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq})
1763 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1765 This function will return the version of the specified Certificate
1768 @strong{Returns:} version of certificate request, or a negative error code on
1772 @subheading gnutls_x509_crq_import
1773 @anchor{gnutls_x509_crq_import}
1774 @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})
1775 @var{crq}: The data to store the parsed certificate request.
1777 @var{data}: The DER or PEM encoded certificate.
1779 @var{format}: One of DER or PEM
1781 This function will convert the given DER or PEM encoded certificate
1782 request to a @code{gnutls_x509_crq_t} type. The output will be
1783 stored in @code{crq} .
1785 If the Certificate is PEM encoded it should have a header of "NEW
1786 CERTIFICATE REQUEST".
1788 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1789 negative error value.
1792 @subheading gnutls_x509_crq_init
1793 @anchor{gnutls_x509_crq_init}
1794 @deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq})
1795 @var{crq}: A pointer to the type to be initialized
1797 This function will initialize a PKCS@code{10} certificate request
1800 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1801 negative error value.
1804 @subheading gnutls_x509_crq_print
1805 @anchor{gnutls_x509_crq_print}
1806 @deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1807 @var{crq}: The data to be printed
1809 @var{format}: Indicate the format to use
1811 @var{out}: Newly allocated datum with null terminated string.
1813 This function will pretty print a certificate request, suitable for
1816 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
1818 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1819 negative error value.
1821 @strong{Since:} 2.8.0
1824 @subheading gnutls_x509_crq_set_attribute_by_oid
1825 @anchor{gnutls_x509_crq_set_attribute_by_oid}
1826 @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})
1827 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1829 @var{oid}: holds an Object Identifier in a null-terminated string
1831 @var{buf}: a pointer to a structure that holds the attribute data
1833 @var{buf_size}: holds the size of @code{buf}
1835 This function will set the attribute in the certificate request
1836 specified by the given Object ID. The provided attribute must be be DER
1839 Attributes in a certificate request is an optional set of data
1840 appended to the request. Their interpretation depends on the CA policy.
1842 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1843 negative error value.
1846 @subheading gnutls_x509_crq_set_basic_constraints
1847 @anchor{gnutls_x509_crq_set_basic_constraints}
1848 @deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint})
1849 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1851 @var{ca}: true(1) or false(0) depending on the Certificate authority status.
1853 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
1854 and negative error codes indicate that the pathLenConstraints field should
1857 This function will set the basicConstraints certificate extension.
1859 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1860 negative error value.
1862 @strong{Since:} 2.8.0
1865 @subheading gnutls_x509_crq_set_challenge_password
1866 @anchor{gnutls_x509_crq_set_challenge_password}
1867 @deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass})
1868 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1870 @var{pass}: holds a (0)-terminated password
1872 This function will set a challenge password to be used when
1873 revoking the request.
1875 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1876 negative error value.
1879 @subheading gnutls_x509_crq_set_dn
1880 @anchor{gnutls_x509_crq_set_dn}
1881 @deftypefun {int} {gnutls_x509_crq_set_dn} (gnutls_x509_crq_t @var{crq}, const char * @var{dn}, const char ** @var{err})
1882 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1884 @var{dn}: a comma separated DN string (RFC4514)
1886 @var{err}: indicates the error position (if any)
1888 This function will set the DN on the provided certificate.
1889 The input string should be plain ASCII or UTF-8 encoded.
1891 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1892 negative error value.
1895 @subheading gnutls_x509_crq_set_dn_by_oid
1896 @anchor{gnutls_x509_crq_set_dn_by_oid}
1897 @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})
1898 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1900 @var{oid}: holds an Object Identifier in a (0)-terminated string
1902 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
1904 @var{data}: a pointer to the input data
1906 @var{sizeof_data}: holds the size of @code{data}
1908 This function will set the part of the name of the Certificate
1909 request subject, specified by the given OID. The input string
1910 should be ASCII or UTF-8 encoded.
1912 Some helper macros with popular OIDs can be found in gnutls/x509.h
1913 With this function you can only set the known OIDs. You can test
1914 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
1915 not known (by gnutls) you should properly DER encode your data, and
1916 call this function with raw_flag set.
1918 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1919 negative error value.
1922 @subheading gnutls_x509_crq_set_key
1923 @anchor{gnutls_x509_crq_set_key}
1924 @deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
1925 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1927 @var{key}: holds a private key
1929 This function will set the public parameters from the given private
1932 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1933 negative error value.
1936 @subheading gnutls_x509_crq_set_key_purpose_oid
1937 @anchor{gnutls_x509_crq_set_key_purpose_oid}
1938 @deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical})
1939 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1941 @var{oid}: a pointer to a null-terminated string that holds the OID
1943 @var{critical}: Whether this extension will be critical or not
1945 This function will set the key purpose OIDs of the Certificate.
1946 These are stored in the Extended Key Usage extension (2.5.29.37)
1947 See the GNUTLS_KP_* definitions for human readable names.
1949 Subsequent calls to this function will append OIDs to the OID list.
1951 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1952 negative error value.
1954 @strong{Since:} 2.8.0
1957 @subheading gnutls_x509_crq_set_key_rsa_raw
1958 @anchor{gnutls_x509_crq_set_key_rsa_raw}
1959 @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})
1960 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
1962 @var{m}: holds the modulus
1964 @var{e}: holds the public exponent
1966 This function will set the public parameters from the given private
1967 key to the request. Only RSA keys are currently supported.
1969 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1970 negative error value.
1972 @strong{Since:} 2.6.0
1975 @subheading gnutls_x509_crq_set_key_usage
1976 @anchor{gnutls_x509_crq_set_key_usage}
1977 @deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage})
1978 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1980 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
1982 This function will set the keyUsage certificate extension.
1984 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1985 negative error value.
1987 @strong{Since:} 2.8.0
1990 @subheading gnutls_x509_crq_set_private_key_usage_period
1991 @anchor{gnutls_x509_crq_set_private_key_usage_period}
1992 @deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration})
1993 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1995 @var{activation}: The activation time
1997 @var{expiration}: The expiration time
1999 This function will set the private key usage period extension (2.5.29.16).
2001 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2002 negative error value.
2005 @subheading gnutls_x509_crq_set_subject_alt_name
2006 @anchor{gnutls_x509_crq_set_subject_alt_name}
2007 @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})
2008 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2010 @var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations
2012 @var{data}: The data to be set
2014 @var{data_size}: The size of data to be set
2016 @var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or
2017 @code{GNUTLS_FSAN_APPEND} to append.
2019 This function will set the subject alternative name certificate
2020 extension. It can set the following types:
2022 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2023 negative error value.
2025 @strong{Since:} 2.8.0
2028 @subheading gnutls_x509_crq_set_version
2029 @anchor{gnutls_x509_crq_set_version}
2030 @deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version})
2031 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
2033 @var{version}: holds the version number, for v1 Requests must be 1
2035 This function will set the version of the certificate request. For
2036 version 1 requests this must be one.
2038 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2039 negative error value.
2042 @subheading gnutls_x509_crq_sign2
2043 @anchor{gnutls_x509_crq_sign2}
2044 @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})
2045 @var{crq}: should contain a @code{gnutls_x509_crq_t} type
2047 @var{key}: holds a private key
2049 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
2051 @var{flags}: must be 0
2053 This function will sign the certificate request with a private key.
2054 This must be the same key as the one used in
2055 @code{gnutls_x509_crt_set_key()} since a certificate request is self
2058 This must be the last step in a certificate request generation
2059 since all the previously set parameters are now signed.
2061 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2062 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
2063 information in the certificate request (e.g., the version using
2064 @code{gnutls_x509_crq_set_version()} ).
2067 @subheading gnutls_x509_crq_verify
2068 @anchor{gnutls_x509_crq_verify}
2069 @deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
2070 @var{crq}: is the crq to be verified
2072 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2074 This function will verify self signature in the certificate
2075 request and return its status.
2077 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
2078 is returned, and zero or positive code on success.
2083 @subheading gnutls_x509_crt_check_email
2084 @anchor{gnutls_x509_crt_check_email}
2085 @deftypefun {int} {gnutls_x509_crt_check_email} (gnutls_x509_crt_t @var{cert}, const char * @var{email}, unsigned int @var{flags})
2086 @var{cert}: should contain an gnutls_x509_crt_t type
2088 @var{email}: A null terminated string that contains an email address (RFC822)
2090 @var{flags}: should be zero
2092 This function will check if the given certificate's subject matches
2093 the given email address.
2095 @strong{Returns:} non-zero for a successful match, and zero on failure.
2098 @subheading gnutls_x509_crt_check_hostname
2099 @anchor{gnutls_x509_crt_check_hostname}
2100 @deftypefun {int} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname})
2101 @var{cert}: should contain an gnutls_x509_crt_t type
2103 @var{hostname}: A null terminated string that contains a DNS name
2105 This function will check if the given certificate's subject matches
2106 the given hostname. This is a basic implementation of the matching
2107 described in RFC6125, and takes into account wildcards,
2108 and the DNSName/IPAddress subject alternative name PKIX extension.
2110 For details see also @code{gnutls_x509_crt_check_hostname2()} .
2112 @strong{Returns:} non-zero for a successful match, and zero on failure.
2115 @subheading gnutls_x509_crt_check_hostname2
2116 @anchor{gnutls_x509_crt_check_hostname2}
2117 @deftypefun {int} {gnutls_x509_crt_check_hostname2} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}, unsigned int @var{flags})
2118 @var{cert}: should contain an gnutls_x509_crt_t type
2120 @var{hostname}: A null terminated string that contains a DNS name
2122 @var{flags}: gnutls_certificate_verify_flags
2124 This function will check if the given certificate's subject matches
2125 the given hostname. This is a basic implementation of the matching
2126 described in RFC6125, and takes into account wildcards,
2127 and the DNSName/IPAddress subject alternative name PKIX extension.
2129 IPv4 addresses are accepted by this function in the dotted-decimal
2130 format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the hexadecimal
2131 x:x:x:x:x:x:x:x format. For them the IPAddress subject alternative
2132 name extension is consulted, as well as the DNSNames in case of a non-match.
2133 The latter fallback exists due to misconfiguration of many servers
2134 which place an IPAddress inside the DNSName extension.
2136 When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS} is specified no
2137 wildcards are considered. Otherwise they are only considered if the
2138 domain name consists of three components or more, and the wildcard
2139 starts at the leftmost position.
2141 @strong{Returns:} non-zero for a successful match, and zero on failure.
2144 @subheading gnutls_x509_crt_check_issuer
2145 @anchor{gnutls_x509_crt_check_issuer}
2146 @deftypefun {int} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer})
2147 @var{cert}: is the certificate to be checked
2149 @var{issuer}: is the certificate of a possible issuer
2151 This function will check if the given certificate was issued by the
2152 given issuer. It checks the DN fields and the authority
2153 key identifier and subject key identifier fields match.
2155 If the same certificate is provided at the @code{cert} and @code{issuer} fields,
2156 it will check whether the certificate is self-signed.
2158 @strong{Returns:} It will return true (1) if the given certificate is issued
2159 by the given issuer, and false (0) if not.
2162 @subheading gnutls_x509_crt_check_revocation
2163 @anchor{gnutls_x509_crt_check_revocation}
2164 @deftypefun {int} {gnutls_x509_crt_check_revocation} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crl_t * @var{crl_list}, int @var{crl_list_length})
2165 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2167 @var{crl_list}: should contain a list of gnutls_x509_crl_t types
2169 @var{crl_list_length}: the length of the crl_list
2171 This function will return check if the given certificate is
2172 revoked. It is assumed that the CRLs have been verified before.
2174 @strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A
2175 negative error code is returned on error.
2178 @subheading gnutls_x509_crt_cpy_crl_dist_points
2179 @anchor{gnutls_x509_crt_cpy_crl_dist_points}
2180 @deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src})
2181 @var{dst}: a certificate of type @code{gnutls_x509_crt_t}
2183 @var{src}: the certificate where the dist points will be copied from
2185 This function will copy the CRL distribution points certificate
2186 extension, from the source to the destination certificate.
2187 This may be useful to copy from a CA certificate to issued ones.
2189 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2190 negative error value.
2193 @subheading gnutls_x509_crt_deinit
2194 @anchor{gnutls_x509_crt_deinit}
2195 @deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert})
2196 @var{cert}: The data to be deinitialized
2198 This function will deinitialize a certificate structure.
2201 @subheading gnutls_x509_crt_export
2202 @anchor{gnutls_x509_crt_export}
2203 @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})
2204 @var{cert}: Holds the certificate
2206 @var{format}: the format of output params. One of PEM or DER.
2208 @var{output_data}: will contain a certificate PEM or DER encoded
2210 @var{output_data_size}: holds the size of output_data (and will be
2211 replaced by the actual size of parameters)
2213 This function will export the certificate to DER or PEM format.
2215 If the buffer provided is not long enough to hold the output, then
2216 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2219 If the structure is PEM encoded, it will have a header
2220 of "BEGIN CERTIFICATE".
2222 @strong{Returns:} In case of failure a negative error code will be
2223 returned, and 0 on success.
2226 @subheading gnutls_x509_crt_export2
2227 @anchor{gnutls_x509_crt_export2}
2228 @deftypefun {int} {gnutls_x509_crt_export2} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
2229 @var{cert}: Holds the certificate
2231 @var{format}: the format of output params. One of PEM or DER.
2233 @var{out}: will contain a certificate PEM or DER encoded
2235 This function will export the certificate to DER or PEM format.
2236 The output buffer is allocated using @code{gnutls_malloc()} .
2238 If the structure is PEM encoded, it will have a header
2239 of "BEGIN CERTIFICATE".
2241 @strong{Returns:} In case of failure a negative error code will be
2242 returned, and 0 on success.
2244 @strong{Since:} 3.1.3
2247 @subheading gnutls_x509_crt_get_activation_time
2248 @anchor{gnutls_x509_crt_get_activation_time}
2249 @deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert})
2250 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2252 This function will return the time this Certificate was or will be
2255 @strong{Returns:} activation time, or (time_t)-1 on error.
2258 @subheading gnutls_x509_crt_get_authority_info_access
2259 @anchor{gnutls_x509_crt_get_authority_info_access}
2260 @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})
2261 @var{crt}: Holds the certificate
2263 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
2265 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
2267 @var{data}: output data to be freed with @code{gnutls_free()} .
2269 @var{critical}: pointer to output integer that is set to non-zero if the extension is marked as critical (may be @code{NULL} )
2271 Note that a simpler API to access the authority info data is provided
2272 by @code{gnutls_x509_aia_get()} and @code{gnutls_x509_ext_import_aia()} .
2274 This function extracts the Authority Information Access (AIA)
2275 extension, see RFC 5280 section 4.2.2.1 for more information. The
2276 AIA extension holds a sequence of AccessDescription (AD) data.
2278 The @code{seq} input parameter is used to indicate which member of the
2279 sequence the caller is interested in. The first member is 0, the
2280 second member 1 and so on. When the @code{seq} value is out of bounds,
2281 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2283 The type of data returned in @code{data} is specified via @code{what} which
2284 should be @code{gnutls_info_access_what_t} values.
2286 If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the
2287 accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
2289 If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will
2290 hold the accessLocation GeneralName type (e.g.,
2291 "uniformResourceIdentifier").
2293 If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI
2294 data. Requesting this @code{what} value leads to an error if the
2295 accessLocation is not of the "uniformResourceIdentifier" type.
2297 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
2298 Requesting this @code{what} value leads to an error if the accessMethod
2299 is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
2300 the "uniformResourceIdentifier" type. In that case @code{GNUTLS_E_UNKNOWN_ALGORITHM}
2301 will be returned, and @code{seq} should be increased and this function
2304 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
2305 URI. Requesting this @code{what} value leads to an error if the
2306 accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
2307 accessLocation is not of the "uniformResourceIdentifier" type.
2308 In that case handle as in @code{GNUTLS_IA_OCSP_URI} .
2310 More @code{what} values may be allocated in the future as needed.
2312 If @code{data} is NULL, the function does the same without storing the
2313 output data, that is, it will set @code{critical} and do error checking
2316 The value of the critical flag is returned in * @code{critical} . Supply a
2317 NULL @code{critical} if you want the function to make sure the extension
2318 is non-critical, as required by RFC 5280.
2320 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on
2321 invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is
2322 incorrectly marked as critical (use a non-NULL @code{critical} to
2323 override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does
2324 not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a
2325 negative error code.
2330 @subheading gnutls_x509_crt_get_authority_key_gn_serial
2331 @anchor{gnutls_x509_crt_get_authority_key_gn_serial}
2332 @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})
2333 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2335 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2337 @var{alt}: is the place where the alternative name will be copied to
2339 @var{alt_size}: holds the size of alt.
2341 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2343 @var{serial}: buffer to store the serial number (may be null)
2345 @var{serial_size}: Holds the size of the serial field (may be null)
2347 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2349 This function will return the X.509 authority key
2350 identifier when stored as a general name (authorityCertIssuer)
2353 Because more than one general names might be stored
2354 @code{seq} can be used as a counter to request them all until
2355 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2357 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2358 if the extension is not present, otherwise a negative error value.
2363 @subheading gnutls_x509_crt_get_authority_key_id
2364 @anchor{gnutls_x509_crt_get_authority_key_id}
2365 @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})
2366 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2368 @var{id}: The place where the identifier will be copied
2370 @var{id_size}: Holds the size of the id field.
2372 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2374 This function will return the X.509v3 certificate authority's key
2375 identifier. This is obtained by the X.509 Authority Key
2376 identifier extension field (2.5.29.35). Note that this function
2377 only returns the keyIdentifier field of the extension and
2378 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
2379 the name and serial number of the certificate. In that case
2380 @code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used.
2382 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2383 if the extension is not present, otherwise a negative error value.
2386 @subheading gnutls_x509_crt_get_basic_constraints
2387 @anchor{gnutls_x509_crt_get_basic_constraints}
2388 @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})
2389 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2391 @var{critical}: will be non-zero if the extension is marked as critical
2393 @var{ca}: pointer to output integer indicating CA status, may be NULL,
2394 value is 1 if the certificate CA flag is set, 0 otherwise.
2396 @var{pathlen}: pointer to output integer indicating path length (may be
2397 NULL), non-negative error codes indicate a present pathLenConstraint
2398 field and the actual value, -1 indicate that the field is absent.
2400 This function will read the certificate's basic constraints, and
2401 return the certificates CA status. It reads the basicConstraints
2402 X.509 extension (2.5.29.19).
2404 @strong{Returns:} If the certificate is a CA a positive value will be
2405 returned, or (0) if the certificate does not have CA flag set. A
2406 negative error code may be returned in case of errors. If the
2407 certificate does not contain the basicConstraints extension
2408 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2411 @subheading gnutls_x509_crt_get_ca_status
2412 @anchor{gnutls_x509_crt_get_ca_status}
2413 @deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical})
2414 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2416 @var{critical}: will be non-zero if the extension is marked as critical
2418 This function will return certificates CA status, by reading the
2419 basicConstraints X.509 extension (2.5.29.19). If the certificate is
2420 a CA a positive value will be returned, or (0) if the certificate
2421 does not have CA flag set.
2423 Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the
2424 pathLenConstraint field too.
2426 @strong{Returns:} If the certificate is a CA a positive value will be
2427 returned, or (0) if the certificate does not have CA flag set. A
2428 negative error code may be returned in case of errors. If the
2429 certificate does not contain the basicConstraints extension
2430 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2433 @subheading gnutls_x509_crt_get_crl_dist_points
2434 @anchor{gnutls_x509_crt_get_crl_dist_points}
2435 @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})
2436 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2438 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
2440 @var{san}: is the place where the distribution point will be copied to
2442 @var{san_size}: holds the size of ret.
2444 @var{reason_flags}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
2446 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2448 This function retrieves the CRL distribution points (2.5.29.31),
2449 contained in the given certificate in the X509v3 Certificate
2452 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if
2453 @code{ret_size} is not enough to hold the distribution point, or the
2454 type of the distribution point if everything was ok. The type is
2455 one of the enumerated @code{gnutls_x509_subject_alt_name_t} . If the
2456 certificate does not have an Alternative name with the specified
2457 sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is
2461 @subheading gnutls_x509_crt_get_dn
2462 @anchor{gnutls_x509_crt_get_dn}
2463 @deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2464 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2466 @var{buf}: a pointer to a structure to hold the name (may be null)
2468 @var{buf_size}: initially holds the size of @code{buf}
2470 This function will copy the name of the Certificate in the provided
2471 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2472 described in RFC4514. The output string will be ASCII or UTF-8
2473 encoded, depending on the certificate data.
2475 If @code{buf} is null then only the size will be filled.
2477 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2478 long enough, and in that case the @code{buf_size} will be updated
2479 with the required size. On success 0 is returned.
2482 @subheading gnutls_x509_crt_get_dn2
2483 @anchor{gnutls_x509_crt_get_dn2}
2484 @deftypefun {int} {gnutls_x509_crt_get_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
2485 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2487 @var{dn}: a pointer to a structure to hold the name
2489 This function will allocate buffer and copy the name of the Certificate.
2490 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2491 described in RFC4514. The output string will be ASCII or UTF-8
2492 encoded, depending on the certificate data.
2494 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2495 negative error value.
2497 @strong{Since:} 3.1.10
2500 @subheading gnutls_x509_crt_get_dn_by_oid
2501 @anchor{gnutls_x509_crt_get_dn_by_oid}
2502 @deftypefun {int} {gnutls_x509_crt_get_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, int @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size})
2503 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2505 @var{oid}: holds an Object Identified in null terminated string
2507 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2509 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
2511 @var{buf}: a pointer where the DN part will be copied (may be null).
2513 @var{buf_size}: initially holds the size of @code{buf}
2515 This function will extract the part of the name of the Certificate
2516 subject specified by the given OID. The output, if the raw flag is
2517 not used, will be encoded as described in RFC4514. Thus a string
2518 that is ASCII or UTF-8 encoded, depending on the certificate data.
2520 Some helper macros with popular OIDs can be found in gnutls/x509.h
2521 If raw flag is (0), this function will only return known OIDs as
2522 text. Other OIDs will be DER encoded, as described in RFC4514 --
2523 in hex format with a '#' prefix. You can check about known OIDs
2524 using @code{gnutls_x509_dn_oid_known()} .
2526 If @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
2527 @code{buf_size} will not include the null character.
2529 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2530 long enough, and in that case the @code{buf_size} will be updated with
2531 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2532 are no data in the current index. On success 0 is returned.
2535 @subheading gnutls_x509_crt_get_dn_oid
2536 @anchor{gnutls_x509_crt_get_dn_oid}
2537 @deftypefun {int} {gnutls_x509_crt_get_dn_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{oid_size})
2538 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2540 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2542 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2544 @var{oid_size}: initially holds the size of @code{oid}
2546 This function will extract the OIDs of the name of the Certificate
2547 subject specified by the given index.
2549 If @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
2550 account for the trailing null.
2552 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2553 long enough, and in that case the @code{buf_size} will be updated with
2554 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2555 are no data in the current index. On success 0 is returned.
2558 @subheading gnutls_x509_crt_get_expiration_time
2559 @anchor{gnutls_x509_crt_get_expiration_time}
2560 @deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert})
2561 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2563 This function will return the time this Certificate was or will be
2566 The no well defined expiration time can be checked against with the
2567 @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION} macro.
2569 @strong{Returns:} expiration time, or (time_t)-1 on error.
2572 @subheading gnutls_x509_crt_get_extension_by_oid
2573 @anchor{gnutls_x509_crt_get_extension_by_oid}
2574 @deftypefun {int} {gnutls_x509_crt_get_extension_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical})
2575 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2577 @var{oid}: holds an Object Identified in null terminated string
2579 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2581 @var{buf}: a pointer to a structure to hold the name (may be null)
2583 @var{buf_size}: initially holds the size of @code{buf}
2585 @var{critical}: will be non-zero if the extension is marked as critical
2587 This function will return the extension specified by the OID in the
2588 certificate. The extensions will be returned as binary data DER
2589 encoded, in the provided buffer.
2591 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2592 otherwise a negative error code is returned. If the certificate does not
2593 contain the specified extension
2594 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2597 @subheading gnutls_x509_crt_get_extension_by_oid2
2598 @anchor{gnutls_x509_crt_get_extension_by_oid2}
2599 @deftypefun {int} {gnutls_x509_crt_get_extension_by_oid2} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, int @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical})
2600 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2602 @var{oid}: holds an Object Identified in null terminated string
2604 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2606 @var{output}: will hold the allocated extension data
2608 @var{critical}: will be non-zero if the extension is marked as critical
2610 This function will return the extension specified by the OID in the
2611 certificate. The extensions will be returned as binary data DER
2612 encoded, in the provided buffer.
2614 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2615 otherwise a negative error code is returned. If the certificate does not
2616 contain the specified extension
2617 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2619 @strong{Since:} 3.3.8
2622 @subheading gnutls_x509_crt_get_extension_data
2623 @anchor{gnutls_x509_crt_get_extension_data}
2624 @deftypefun {int} {gnutls_x509_crt_get_extension_data} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{data}, size_t * @var{sizeof_data})
2625 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2627 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2629 @var{data}: a pointer to a structure to hold the data (may be null)
2631 @var{sizeof_data}: initially holds the size of @code{data}
2633 This function will return the requested extension data in the
2634 certificate. The extension data will be stored in the
2637 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and
2638 critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead,
2639 if you want to get data indexed by the extension OID rather than
2642 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2643 otherwise a negative error code is returned. If you have reached the
2644 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2648 @subheading gnutls_x509_crt_get_extension_data2
2649 @anchor{gnutls_x509_crt_get_extension_data2}
2650 @deftypefun {int} {gnutls_x509_crt_get_extension_data2} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, gnutls_datum_t * @var{data})
2651 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2653 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
2655 @var{data}: will contain the extension DER-encoded data
2657 This function will return the requested by the index extension data in the
2658 certificate. The extension data will be allocated using
2659 @code{gnutls_malloc()} .
2661 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
2663 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2664 otherwise a negative error code is returned. If you have reached the
2665 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2669 @subheading gnutls_x509_crt_get_extension_info
2670 @anchor{gnutls_x509_crt_get_extension_info}
2671 @deftypefun {int} {gnutls_x509_crt_get_extension_info} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical})
2672 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2674 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2676 @var{oid}: a pointer to a structure to hold the OID
2678 @var{oid_size}: initially holds the maximum size of @code{oid} , on return
2679 holds actual size of @code{oid} .
2681 @var{critical}: output variable with critical flag, may be NULL.
2683 This function will return the requested extension OID in the
2684 certificate, and the critical flag for it. The extension OID will
2685 be stored as a string in the provided buffer. Use
2686 @code{gnutls_x509_crt_get_extension()} to extract the data.
2688 If the buffer provided is not long enough to hold the output, then
2689 @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
2690 returned. The @code{oid} returned will be null terminated, although
2691 @code{oid_size} will not account for the trailing null.
2693 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2694 otherwise a negative error code is returned. If you have reached the
2695 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2699 @subheading gnutls_x509_crt_get_extension_oid
2700 @anchor{gnutls_x509_crt_get_extension_oid}
2701 @deftypefun {int} {gnutls_x509_crt_get_extension_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{oid_size})
2702 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2704 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2706 @var{oid}: a pointer to a structure to hold the OID (may be null)
2708 @var{oid_size}: initially holds the size of @code{oid}
2710 This function will return the requested extension OID in the certificate.
2711 The extension OID will be stored as a string in the provided buffer.
2713 The @code{oid} returned will be null terminated, although @code{oid_size} will not
2714 account for the trailing null.
2716 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2717 otherwise a negative error code is returned. If you have reached the
2718 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2722 @subheading gnutls_x509_crt_get_fingerprint
2723 @anchor{gnutls_x509_crt_get_fingerprint}
2724 @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})
2725 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2727 @var{algo}: is a digest algorithm
2729 @var{buf}: a pointer to a structure to hold the fingerprint (may be null)
2731 @var{buf_size}: initially holds the size of @code{buf}
2733 This function will calculate and copy the certificate's fingerprint
2734 in the provided buffer. The fingerprint is a hash of the DER-encoded
2735 data of the certificate.
2737 If the buffer is null then only the size will be filled.
2739 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2740 not long enough, and in that case the *buf_size will be updated
2741 with the required size. On success 0 is returned.
2744 @subheading gnutls_x509_crt_get_issuer
2745 @anchor{gnutls_x509_crt_get_issuer}
2746 @deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2747 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2749 @var{dn}: output variable with pointer to uint8_t DN
2751 Return the Certificate's Issuer DN as a @code{gnutls_x509_dn_t} data type,
2752 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
2754 Note that @code{dn} should be treated as constant. Because it points
2755 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
2758 @strong{Returns:} Returns 0 on success, or an error code.
2761 @subheading gnutls_x509_crt_get_issuer_alt_name
2762 @anchor{gnutls_x509_crt_get_issuer_alt_name}
2763 @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})
2764 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2766 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2768 @var{ian}: is the place where the alternative name will be copied to
2770 @var{ian_size}: holds the size of ian.
2772 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2774 This function retrieves the Issuer Alternative Name (2.5.29.18),
2775 contained in the given certificate in the X509v3 Certificate
2778 When the SAN type is otherName, it will extract the data in the
2779 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2780 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2781 the corresponding OID and the "virtual" SAN types (e.g.,
2782 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
2784 If an otherName OID is known, the data will be decoded. Otherwise
2785 the returned data will be DER encoded, and you will have to decode
2786 it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer
2787 AltName is recognized.
2789 @strong{Returns:} the alternative issuer name type on success, one of the
2790 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2791 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2792 to hold the value. In that case @code{ian_size} will be updated with
2793 the required size. If the certificate does not have an
2794 Alternative name with the specified sequence number then
2795 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2797 @strong{Since:} 2.10.0
2800 @subheading gnutls_x509_crt_get_issuer_alt_name2
2801 @anchor{gnutls_x509_crt_get_issuer_alt_name2}
2802 @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})
2803 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2805 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2807 @var{ian}: is the place where the alternative name will be copied to
2809 @var{ian_size}: holds the size of ret.
2811 @var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2813 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2815 This function will return the alternative names, contained in the
2816 given certificate. It is the same as
2817 @code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it
2818 will return the type of the alternative name in @code{ian_type} even if
2819 the function fails for some reason (i.e. the buffer provided is
2822 @strong{Returns:} the alternative issuer name type on success, one of the
2823 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2824 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2825 to hold the value. In that case @code{ian_size} will be updated with
2826 the required size. If the certificate does not have an
2827 Alternative name with the specified sequence number then
2828 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2830 @strong{Since:} 2.10.0
2833 @subheading gnutls_x509_crt_get_issuer_alt_othername_oid
2834 @anchor{gnutls_x509_crt_get_issuer_alt_othername_oid}
2835 @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})
2836 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2838 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2840 @var{ret}: is the place where the otherName OID will be copied to
2842 @var{ret_size}: holds the size of ret.
2844 This function will extract the type OID of an otherName Subject
2845 Alternative Name, contained in the given certificate, and return
2846 the type as an enumerated element.
2848 If @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
2849 account for the trailing null.
2851 This function is only useful if
2852 @code{gnutls_x509_crt_get_issuer_alt_name()} returned
2853 @code{GNUTLS_SAN_OTHERNAME} .
2855 @strong{Returns:} the alternative issuer name type on success, one of the
2856 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2857 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2858 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
2859 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2860 @code{ret_size} is not large enough to hold the value. In that case
2861 @code{ret_size} will be updated with the required size. If the
2862 certificate does not have an Alternative name with the specified
2863 sequence number and with the otherName type then
2864 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2866 @strong{Since:} 2.10.0
2869 @subheading gnutls_x509_crt_get_issuer_dn
2870 @anchor{gnutls_x509_crt_get_issuer_dn}
2871 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2872 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2874 @var{buf}: a pointer to a structure to hold the name (may be null)
2876 @var{buf_size}: initially holds the size of @code{buf}
2878 This function will copy the name of the Certificate issuer in the
2879 provided buffer. The name will be in the form
2880 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
2881 will be ASCII or UTF-8 encoded, depending on the certificate data.
2883 If @code{buf} is null then only the size will be filled.
2885 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2886 long enough, and in that case the @code{buf_size} will be updated with
2887 the required size. On success 0 is returned.
2890 @subheading gnutls_x509_crt_get_issuer_dn2
2891 @anchor{gnutls_x509_crt_get_issuer_dn2}
2892 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
2893 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2895 @var{dn}: a pointer to a structure to hold the name
2897 This function will allocate buffer and copy the name of issuer of the Certificate.
2898 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2899 described in RFC4514. The output string will be ASCII or UTF-8
2900 encoded, depending on the certificate data.
2902 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2903 negative error value.
2905 @strong{Since:} 3.1.10
2908 @subheading gnutls_x509_crt_get_issuer_dn_by_oid
2909 @anchor{gnutls_x509_crt_get_issuer_dn_by_oid}
2910 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, int @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size})
2911 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2913 @var{oid}: holds an Object Identified in null terminated string
2915 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2917 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
2919 @var{buf}: a pointer to a structure to hold the name (may be null)
2921 @var{buf_size}: initially holds the size of @code{buf}
2923 This function will extract the part of the name of the Certificate
2924 issuer specified by the given OID. The output, if the raw flag is not
2925 used, will be encoded as described in RFC4514. Thus a string that is
2926 ASCII or UTF-8 encoded, depending on the certificate data.
2928 Some helper macros with popular OIDs can be found in gnutls/x509.h
2929 If raw flag is (0), this function will only return known OIDs as
2930 text. Other OIDs will be DER encoded, as described in RFC4514 --
2931 in hex format with a '#' prefix. You can check about known OIDs
2932 using @code{gnutls_x509_dn_oid_known()} .
2934 If @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
2935 @code{buf_size} will not include the null character.
2937 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2938 long enough, and in that case the @code{buf_size} will be updated with
2939 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2940 are no data in the current index. On success 0 is returned.
2943 @subheading gnutls_x509_crt_get_issuer_dn_oid
2944 @anchor{gnutls_x509_crt_get_issuer_dn_oid}
2945 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{oid_size})
2946 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
2948 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2950 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2952 @var{oid_size}: initially holds the size of @code{oid}
2954 This function will extract the OIDs of the name of the Certificate
2955 issuer specified by the given index.
2957 If @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
2958 account for the trailing null.
2960 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2961 long enough, and in that case the @code{buf_size} will be updated with
2962 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2963 are no data in the current index. On success 0 is returned.
2966 @subheading gnutls_x509_crt_get_issuer_unique_id
2967 @anchor{gnutls_x509_crt_get_issuer_unique_id}
2968 @deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
2969 @var{crt}: Holds the certificate
2971 @var{buf}: user allocated memory buffer, will hold the unique id
2973 @var{buf_size}: size of user allocated memory buffer (on input), will hold
2974 actual size of the unique ID on return.
2976 This function will extract the issuerUniqueID value (if present) for
2977 the given certificate.
2979 If the user allocated memory buffer is not large enough to hold the
2980 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
2981 returned, and buf_size will be set to the actual length.
2983 This function had a bug prior to 3.4.8 that prevented the setting
2984 of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely
2985 with the older versions the @code{buf} must be a valid buffer that can hold
2986 at least a single byte if @code{buf_size} is zero.
2988 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2990 @strong{Since:} 2.12.0
2993 @subheading gnutls_x509_crt_get_key_id
2994 @anchor{gnutls_x509_crt_get_key_id}
2995 @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})
2996 @var{crt}: Holds the certificate
2998 @var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t}
3000 @var{output_data}: will contain the key ID
3002 @var{output_data_size}: holds the size of output_data (and will be
3003 replaced by the actual size of parameters)
3005 This function will return a unique ID that depends on the public
3006 key parameters. This ID can be used in checking whether a
3007 certificate corresponds to the given private key.
3009 If the buffer provided is not long enough to hold the output, then
3010 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3011 be returned. The output will normally be a SHA-1 hash output,
3014 @strong{Returns:} In case of failure a negative error code will be
3015 returned, and 0 on success.
3018 @subheading gnutls_x509_crt_get_key_purpose_oid
3019 @anchor{gnutls_x509_crt_get_key_purpose_oid}
3020 @deftypefun {int} {gnutls_x509_crt_get_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical})
3021 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3023 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
3025 @var{oid}: a pointer to a buffer to hold the OID (may be null)
3027 @var{oid_size}: initially holds the size of @code{oid}
3029 @var{critical}: output flag to indicate criticality of extension
3031 This function will extract the key purpose OIDs of the Certificate
3032 specified by the given index. These are stored in the Extended Key
3033 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
3034 human readable names.
3036 If @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
3037 account for the trailing null.
3039 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
3040 not long enough, and in that case the *oid_size will be updated
3041 with the required size. On success 0 is returned.
3044 @subheading gnutls_x509_crt_get_key_usage
3045 @anchor{gnutls_x509_crt_get_key_usage}
3046 @deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
3047 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3049 @var{key_usage}: where the key usage bits will be stored
3051 @var{critical}: will be non-zero if the extension is marked as critical
3053 This function will return certificate's key usage, by reading the
3054 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
3055 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
3056 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
3057 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
3058 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
3059 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
3061 @strong{Returns:} the certificate key usage, or a negative error code in case of
3062 parsing error. If the certificate does not contain the keyUsage
3063 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
3067 @subheading gnutls_x509_crt_get_name_constraints
3068 @anchor{gnutls_x509_crt_get_name_constraints}
3069 @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})
3070 @var{crt}: should contain a @code{gnutls_x509_crt_t} type
3072 @var{nc}: The nameconstraints intermediate type
3074 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
3076 @var{critical}: the extension status
3078 This function will return an intermediate type containing
3079 the name constraints of the provided CA certificate. That
3080 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
3081 to verify whether a server's name is in accordance with the constraints.
3083 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
3084 the @code{nc} structure is empty
3085 this function will behave identically as if the flag was not set.
3086 Otherwise if there are elements in the @code{nc} structure then only the
3087 excluded constraints will be appended to the constraints.
3089 Note that @code{nc} must be initialized prior to calling this function.
3091 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3092 if the extension is not present, otherwise a negative error value.
3094 @strong{Since:} 3.3.0
3097 @subheading gnutls_x509_crt_get_pk_algorithm
3098 @anchor{gnutls_x509_crt_get_pk_algorithm}
3099 @deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits})
3100 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3102 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
3104 This function will return the public key algorithm of an X.509
3107 If bits is non null, it should have enough size to hold the parameters
3108 size in bits. For RSA the bits returned is the modulus.
3109 For DSA the bits returned are of the public
3112 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3113 success, or a negative error code on error.
3116 @subheading gnutls_x509_crt_get_pk_dsa_raw
3117 @anchor{gnutls_x509_crt_get_pk_dsa_raw}
3118 @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})
3119 @var{crt}: Holds the certificate
3121 @var{p}: will hold the p
3123 @var{q}: will hold the q
3125 @var{g}: will hold the g
3127 @var{y}: will hold the y
3129 This function will export the DSA public key's parameters found in
3130 the given certificate. The new parameters will be allocated using
3131 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3133 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3136 @subheading gnutls_x509_crt_get_pk_ecc_raw
3137 @anchor{gnutls_x509_crt_get_pk_ecc_raw}
3138 @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})
3139 @var{crt}: Holds the certificate
3141 @var{curve}: will hold the curve
3143 @var{x}: will hold x
3145 @var{y}: will hold y
3147 This function will export the ECC public key's parameters found in
3148 the given certificate. The new parameters will be allocated using
3149 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3151 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3153 @strong{Since:} 3.4.1
3156 @subheading gnutls_x509_crt_get_pk_rsa_raw
3157 @anchor{gnutls_x509_crt_get_pk_rsa_raw}
3158 @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})
3159 @var{crt}: Holds the certificate
3161 @var{m}: will hold the modulus
3163 @var{e}: will hold the public exponent
3165 This function will export the RSA public key's parameters found in
3166 the given structure. The new parameters will be allocated using
3167 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3169 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3172 @subheading gnutls_x509_crt_get_policy
3173 @anchor{gnutls_x509_crt_get_policy}
3174 @deftypefun {int} {gnutls_x509_crt_get_policy} (gnutls_x509_crt_t @var{crt}, int @var{indx}, struct gnutls_x509_policy_st * @var{policy}, unsigned int * @var{critical})
3175 @var{crt}: should contain a @code{gnutls_x509_crt_t} type
3177 @var{indx}: This specifies which policy to return. Use (0) to get the first one.
3179 @var{policy}: A pointer to a policy structure.
3181 @var{critical}: will be non-zero if the extension is marked as critical
3183 This function will extract the certificate policy (extension 2.5.29.32)
3184 specified by the given index.
3186 The policy returned by this function must be deinitialized by using
3187 @code{gnutls_x509_policy_release()} .
3189 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3190 if the extension is not present, otherwise a negative error value.
3192 @strong{Since:} 3.1.5
3195 @subheading gnutls_x509_crt_get_private_key_usage_period
3196 @anchor{gnutls_x509_crt_get_private_key_usage_period}
3197 @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})
3198 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3200 @var{activation}: The activation time
3202 @var{expiration}: The expiration time
3204 @var{critical}: the extension status
3206 This function will return the expiration and activation
3207 times of the private key of the certificate. It relies on
3208 the PKIX extension 2.5.29.16 being present.
3210 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3211 if the extension is not present, otherwise a negative error value.
3214 @subheading gnutls_x509_crt_get_proxy
3215 @anchor{gnutls_x509_crt_get_proxy}
3216 @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})
3217 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3219 @var{critical}: will be non-zero if the extension is marked as critical
3221 @var{pathlen}: pointer to output integer indicating path length (may be
3222 NULL), non-negative error codes indicate a present pCPathLenConstraint
3223 field and the actual value, -1 indicate that the field is absent.
3225 @var{policyLanguage}: output variable with OID of policy language
3227 @var{policy}: output variable with policy data
3229 @var{sizeof_policy}: output variable size of policy data
3231 This function will get information from a proxy certificate. It
3232 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
3234 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
3235 otherwise a negative error code is returned.
3238 @subheading gnutls_x509_crt_get_raw_dn
3239 @anchor{gnutls_x509_crt_get_raw_dn}
3240 @deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3241 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3243 @var{dn}: will hold the starting point of the DN
3245 This function will return a pointer to the DER encoded DN structure and
3246 the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3248 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3249 negative error value. or a negative error code on error.
3252 @subheading gnutls_x509_crt_get_raw_issuer_dn
3253 @anchor{gnutls_x509_crt_get_raw_issuer_dn}
3254 @deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3255 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3257 @var{dn}: will hold the starting point of the DN
3259 This function will return a pointer to the DER encoded DN structure
3260 and the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3262 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3263 negative error value.or a negative error code on error.
3266 @subheading gnutls_x509_crt_get_serial
3267 @anchor{gnutls_x509_crt_get_serial}
3268 @deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size})
3269 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3271 @var{result}: The place where the serial number will be copied
3273 @var{result_size}: Holds the size of the result field.
3275 This function will return the X.509 certificate's serial number.
3276 This is obtained by the X509 Certificate serialNumber field. Serial
3277 is not always a 32 or 64bit number. Some CAs use large serial
3278 numbers, thus it may be wise to handle it as something uint8_t.
3280 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3281 negative error value.
3284 @subheading gnutls_x509_crt_get_signature
3285 @anchor{gnutls_x509_crt_get_signature}
3286 @deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sig_size})
3287 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3289 @var{sig}: a pointer where the signature part will be copied (may be null).
3291 @var{sig_size}: initially holds the size of @code{sig}
3293 This function will extract the signature field of a certificate.
3295 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3296 negative error value.
3299 @subheading gnutls_x509_crt_get_signature_algorithm
3300 @anchor{gnutls_x509_crt_get_signature_algorithm}
3301 @deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert})
3302 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3304 This function will return a value of the @code{gnutls_sign_algorithm_t}
3305 enumeration that is the signature algorithm that has been used to
3306 sign this certificate.
3308 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code on
3312 @subheading gnutls_x509_crt_get_subject
3313 @anchor{gnutls_x509_crt_get_subject}
3314 @deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
3315 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3317 @var{dn}: output variable with pointer to uint8_t DN.
3319 Return the Certificate's Subject DN as a @code{gnutls_x509_dn_t} data type,
3320 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
3322 Note that @code{dn} should be treated as constant. Because it points
3323 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
3326 @strong{Returns:} Returns 0 on success, or an error code.
3329 @subheading gnutls_x509_crt_get_subject_alt_name
3330 @anchor{gnutls_x509_crt_get_subject_alt_name}
3331 @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})
3332 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3334 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3336 @var{san}: is the place where the alternative name will be copied to
3338 @var{san_size}: holds the size of san.
3340 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3342 This function retrieves the Alternative Name (2.5.29.17), contained
3343 in the given certificate in the X509v3 Certificate Extensions.
3345 When the SAN type is otherName, it will extract the data in the
3346 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
3347 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
3348 the corresponding OID and the "virtual" SAN types (e.g.,
3349 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
3351 If an otherName OID is known, the data will be decoded. Otherwise
3352 the returned data will be DER encoded, and you will have to decode
3353 it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is
3356 @strong{Returns:} the alternative subject name type on success, one of the
3357 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3358 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to
3359 hold the value. In that case @code{san_size} will be updated with the
3360 required size. If the certificate does not have an Alternative
3361 name with the specified sequence number then
3362 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3365 @subheading gnutls_x509_crt_get_subject_alt_name2
3366 @anchor{gnutls_x509_crt_get_subject_alt_name2}
3367 @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})
3368 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3370 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3372 @var{san}: is the place where the alternative name will be copied to
3374 @var{san_size}: holds the size of ret.
3376 @var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
3378 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3380 This function will return the alternative names, contained in the
3381 given certificate. It is the same as
3382 @code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it
3383 will return the type of the alternative name in @code{san_type} even if
3384 the function fails for some reason (i.e. the buffer provided is
3387 @strong{Returns:} the alternative subject name type on success, one of the
3388 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3389 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough
3390 to hold the value. In that case @code{san_size} will be updated with
3391 the required size. If the certificate does not have an
3392 Alternative name with the specified sequence number then
3393 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3396 @subheading gnutls_x509_crt_get_subject_alt_othername_oid
3397 @anchor{gnutls_x509_crt_get_subject_alt_othername_oid}
3398 @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})
3399 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3401 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3403 @var{oid}: is the place where the otherName OID will be copied to
3405 @var{oid_size}: holds the size of ret.
3407 This function will extract the type OID of an otherName Subject
3408 Alternative Name, contained in the given certificate, and return
3409 the type as an enumerated element.
3411 This function is only useful if
3412 @code{gnutls_x509_crt_get_subject_alt_name()} returned
3413 @code{GNUTLS_SAN_OTHERNAME} .
3415 If @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
3416 account for the trailing null.
3418 @strong{Returns:} the alternative subject name type on success, one of the
3419 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
3420 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
3421 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
3422 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
3423 @code{ian_size} is not large enough to hold the value. In that case
3424 @code{ian_size} will be updated with the required size. If the
3425 certificate does not have an Alternative name with the specified
3426 sequence number and with the otherName type then
3427 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3430 @subheading gnutls_x509_crt_get_subject_key_id
3431 @anchor{gnutls_x509_crt_get_subject_key_id}
3432 @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})
3433 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3435 @var{ret}: The place where the identifier will be copied
3437 @var{ret_size}: Holds the size of the result field.
3439 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3441 This function will return the X.509v3 certificate's subject key
3442 identifier. This is obtained by the X.509 Subject Key identifier
3443 extension field (2.5.29.14).
3445 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3446 if the extension is not present, otherwise a negative error value.
3449 @subheading gnutls_x509_crt_get_subject_unique_id
3450 @anchor{gnutls_x509_crt_get_subject_unique_id}
3451 @deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
3452 @var{crt}: Holds the certificate
3454 @var{buf}: user allocated memory buffer, will hold the unique id
3456 @var{buf_size}: size of user allocated memory buffer (on input), will hold
3457 actual size of the unique ID on return.
3459 This function will extract the subjectUniqueID value (if present) for
3460 the given certificate.
3462 If the user allocated memory buffer is not large enough to hold the
3463 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
3464 returned, and buf_size will be set to the actual length.
3466 This function had a bug prior to 3.4.8 that prevented the setting
3467 of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely
3468 with the older versions the @code{buf} must be a valid buffer that can hold
3469 at least a single byte if @code{buf_size} is zero.
3471 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3474 @subheading gnutls_x509_crt_get_version
3475 @anchor{gnutls_x509_crt_get_version}
3476 @deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert})
3477 @var{cert}: should contain a @code{gnutls_x509_crt_t} type
3479 This function will return the version of the specified Certificate.
3481 @strong{Returns:} version of certificate, or a negative error code on error.
3484 @subheading gnutls_x509_crt_import
3485 @anchor{gnutls_x509_crt_import}
3486 @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})
3487 @var{cert}: The data to store the parsed certificate.
3489 @var{data}: The DER or PEM encoded certificate.
3491 @var{format}: One of DER or PEM
3493 This function will convert the given DER or PEM encoded Certificate
3494 to the native gnutls_x509_crt_t format. The output will be stored
3497 If the Certificate is PEM encoded it should have a header of "X509
3498 CERTIFICATE", or "CERTIFICATE".
3500 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3501 negative error value.
3504 @subheading gnutls_x509_crt_import_url
3505 @anchor{gnutls_x509_crt_import_url}
3506 @deftypefun {int} {gnutls_x509_crt_import_url} (gnutls_x509_crt_t @var{crt}, const char * @var{url}, unsigned int @var{flags})
3507 @var{crt}: A certificate of type @code{gnutls_x509_crt_t}
3509 @var{url}: A PKCS 11 url
3511 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
3513 This function will import a PKCS 11 certificate directly from a token
3514 without involving the @code{gnutls_pkcs11_obj_t} type. This function will
3515 fail if the certificate stored is not of X.509 type.
3517 Despite its name this function will attempt to import any kind of
3518 URL to certificate. In previous versions of gnutls this function
3519 was named gnutls_x509_crt_import_pkcs11_url, and the old name is
3520 an alias to this one.
3522 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3523 negative error value.
3525 @strong{Since:} 3.4.0
3528 @subheading gnutls_x509_crt_init
3529 @anchor{gnutls_x509_crt_init}
3530 @deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert})
3531 @var{cert}: A pointer to the type to be initialized
3533 This function will initialize an X.509 certificate structure.
3535 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3536 negative error value.
3539 @subheading gnutls_x509_crt_list_import
3540 @anchor{gnutls_x509_crt_list_import}
3541 @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})
3542 @var{certs}: Indicates where the parsed list will be copied to. Must not be initialized.
3544 @var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
3546 @var{data}: The PEM encoded certificate.
3548 @var{format}: One of DER or PEM.
3550 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3552 This function will convert the given PEM encoded certificate list
3553 to the native gnutls_x509_crt_t format. The output will be stored
3554 in @code{certs} . They will be automatically initialized.
3556 The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause
3557 import to fail if the certificates in the provided buffer are more
3558 than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED}
3559 flag will cause the function to fail if the provided list is not
3560 sorted from subject to issuer.
3562 If the Certificate is PEM encoded it should have a header of "X509
3563 CERTIFICATE", or "CERTIFICATE".
3565 @strong{Returns:} the number of certificates read or a negative error value.
3568 @subheading gnutls_x509_crt_list_import2
3569 @anchor{gnutls_x509_crt_list_import2}
3570 @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})
3571 @var{certs}: Will hold the parsed certificate list.
3573 @var{size}: It will contain the size of the list.
3575 @var{data}: The PEM encoded certificate.
3577 @var{format}: One of DER or PEM.
3579 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3581 This function will convert the given PEM encoded certificate list
3582 to the native gnutls_x509_crt_t format. The output will be stored
3583 in @code{certs} which will allocated and initialized.
3585 If the Certificate is PEM encoded it should have a header of "X509
3586 CERTIFICATE", or "CERTIFICATE".
3588 To deinitialize @code{certs} , you need to deinitialize each crt structure
3589 independently, and use @code{gnutls_free()} at
3591 @strong{Returns:} the number of certificates read or a negative error value.
3596 @subheading gnutls_x509_crt_list_verify
3597 @anchor{gnutls_x509_crt_list_verify}
3598 @deftypefun {int} {gnutls_x509_crt_list_verify} (const gnutls_x509_crt_t * @var{cert_list}, int @var{cert_list_length}, const gnutls_x509_crt_t * @var{CA_list}, int @var{CA_list_length}, const gnutls_x509_crl_t * @var{CRL_list}, int @var{CRL_list_length}, unsigned int @var{flags}, unsigned int * @var{verify})
3599 @var{cert_list}: is the certificate list to be verified
3601 @var{cert_list_length}: holds the number of certificate in cert_list
3603 @var{CA_list}: is the CA list which will be used in verification
3605 @var{CA_list_length}: holds the number of CA certificate in CA_list
3607 @var{CRL_list}: holds a list of CRLs.
3609 @var{CRL_list_length}: the length of CRL list.
3611 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3613 @var{verify}: will hold the certificate verification output.
3616 This function will try to verify the given certificate list and
3617 return its status. The details of the verification are the same
3618 as in @code{gnutls_x509_trust_list_verify_crt2()} .
3620 You must check the peer's name in order to check if the verified
3621 certificate belongs to the actual peer.
3623 The certificate verification output will be put in @code{verify} and will
3624 be one or more of the gnutls_certificate_status_t enumerated
3625 elements bitwise or'd. For a more detailed verification status use
3626 @code{gnutls_x509_crt_verify()} per list element.
3628 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3629 negative error value.
3632 @subheading gnutls_x509_crt_print
3633 @anchor{gnutls_x509_crt_print}
3634 @deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
3635 @var{cert}: The data to be printed
3637 @var{format}: Indicate the format to use
3639 @var{out}: Newly allocated datum with null terminated string.
3641 This function will pretty print a X.509 certificate, suitable for
3644 If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the
3645 certificate will be output, on multiple lines. The
3646 @code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some
3647 selected fields, which is useful for logging purposes.
3649 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
3651 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3652 negative error value.
3655 @subheading gnutls_x509_crt_set_activation_time
3656 @anchor{gnutls_x509_crt_set_activation_time}
3657 @deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time})
3658 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3660 @var{act_time}: The actual time
3662 This function will set the time this Certificate was or will be
3665 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3666 negative error value.
3669 @subheading gnutls_x509_crt_set_authority_info_access
3670 @anchor{gnutls_x509_crt_set_authority_info_access}
3671 @deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data})
3672 @var{crt}: Holds the certificate
3674 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
3676 @var{data}: output data to be freed with @code{gnutls_free()} .
3678 This function sets the Authority Information Access (AIA)
3679 extension, see RFC 5280 section 4.2.2.1 for more information.
3681 The type of data stored in @code{data} is specified via @code{what} which
3682 should be @code{gnutls_info_access_what_t} values.
3684 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
3685 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
3688 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3689 negative error value.
3694 @subheading gnutls_x509_crt_set_authority_key_id
3695 @anchor{gnutls_x509_crt_set_authority_key_id}
3696 @deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3697 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3699 @var{id}: The key ID
3701 @var{id_size}: Holds the size of the key ID field.
3703 This function will set the X.509 certificate's authority key ID extension.
3704 Only the keyIdentifier field can be set with this function.
3706 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3707 negative error value.
3710 @subheading gnutls_x509_crt_set_basic_constraints
3711 @anchor{gnutls_x509_crt_set_basic_constraints}
3712 @deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint})
3713 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3715 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3717 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
3718 and negative error codes indicate that the pathLenConstraints field should
3721 This function will set the basicConstraints certificate extension.
3723 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3724 negative error value.
3727 @subheading gnutls_x509_crt_set_ca_status
3728 @anchor{gnutls_x509_crt_set_ca_status}
3729 @deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca})
3730 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3732 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3734 This function will set the basicConstraints certificate extension.
3735 Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control
3736 the pathLenConstraint field too.
3738 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3739 negative error value.
3742 @subheading gnutls_x509_crt_set_crl_dist_points
3743 @anchor{gnutls_x509_crt_set_crl_dist_points}
3744 @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})
3745 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3747 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3749 @var{data_string}: The data to be set
3751 @var{reason_flags}: revocation reasons
3753 This function will set the CRL distribution points certificate extension.
3755 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3756 negative error value.
3759 @subheading gnutls_x509_crt_set_crl_dist_points2
3760 @anchor{gnutls_x509_crt_set_crl_dist_points2}
3761 @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})
3762 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3764 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3766 @var{data}: The data to be set
3768 @var{data_size}: The data size
3770 @var{reason_flags}: revocation reasons
3772 This function will set the CRL distribution points certificate extension.
3774 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3775 negative error value.
3777 @strong{Since:} 2.6.0
3780 @subheading gnutls_x509_crt_set_crq
3781 @anchor{gnutls_x509_crt_set_crq}
3782 @deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3783 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3785 @var{crq}: holds a certificate request
3787 This function will set the name and public parameters as well as
3788 the extensions from the given certificate request to the certificate.
3789 Only RSA keys are currently supported.
3791 Note that this function will only set the @code{crq} if it is self
3792 signed and the signature is correct. See @code{gnutls_x509_crq_sign2()} .
3794 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3795 negative error value.
3798 @subheading gnutls_x509_crt_set_crq_extensions
3799 @anchor{gnutls_x509_crt_set_crq_extensions}
3800 @deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3801 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3803 @var{crq}: holds a certificate request
3805 This function will set extensions from the given request to the
3808 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3809 negative error value.
3811 @strong{Since:} 2.8.0
3814 @subheading gnutls_x509_crt_set_dn
3815 @anchor{gnutls_x509_crt_set_dn}
3816 @deftypefun {int} {gnutls_x509_crt_set_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
3817 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3819 @var{dn}: a comma separated DN string (RFC4514)
3821 @var{err}: indicates the error position (if any)
3823 This function will set the DN on the provided certificate.
3824 The input string should be plain ASCII or UTF-8 encoded.
3826 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3827 negative error value.
3830 @subheading gnutls_x509_crt_set_dn_by_oid
3831 @anchor{gnutls_x509_crt_set_dn_by_oid}
3832 @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})
3833 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3835 @var{oid}: holds an Object Identifier in a null terminated string
3837 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3839 @var{name}: a pointer to the name
3841 @var{sizeof_name}: holds the size of @code{name}
3843 This function will set the part of the name of the Certificate
3844 subject, specified by the given OID. The input string should be
3845 ASCII or UTF-8 encoded.
3847 Some helper macros with popular OIDs can be found in gnutls/x509.h
3848 With this function you can only set the known OIDs. You can test
3849 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3850 not known (by gnutls) you should properly DER encode your data,
3851 and call this function with @code{raw_flag} set.
3853 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3854 negative error value.
3857 @subheading gnutls_x509_crt_set_expiration_time
3858 @anchor{gnutls_x509_crt_set_expiration_time}
3859 @deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time})
3860 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3862 @var{exp_time}: The actual time
3864 This function will set the time this Certificate will expire.
3865 Setting an expiration time to (time_t)-1 or to @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION}
3866 will set to the no well-defined expiration date value.
3868 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3869 negative error value.
3872 @subheading gnutls_x509_crt_set_extension_by_oid
3873 @anchor{gnutls_x509_crt_set_extension_by_oid}
3874 @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})
3875 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3877 @var{oid}: holds an Object Identified in null terminated string
3879 @var{buf}: a pointer to a DER encoded data
3881 @var{sizeof_buf}: holds the size of @code{buf}
3883 @var{critical}: should be non-zero if the extension is to be marked as critical
3885 This function will set an the extension, by the specified OID, in
3886 the certificate. The extension data should be binary data DER
3889 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3890 negative error value.
3893 @subheading gnutls_x509_crt_set_issuer_alt_name
3894 @anchor{gnutls_x509_crt_set_issuer_alt_name}
3895 @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})
3896 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3898 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3900 @var{data}: The data to be set
3902 @var{data_size}: The size of data to be set
3904 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
3906 This function will set the issuer alternative name certificate
3907 extension. It can set the same types as @code{gnutls_x509_crt_set_subject_alt_name()} .
3909 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3910 negative error value.
3912 @strong{Since:} 3.3.0
3915 @subheading gnutls_x509_crt_set_issuer_dn
3916 @anchor{gnutls_x509_crt_set_issuer_dn}
3917 @deftypefun {int} {gnutls_x509_crt_set_issuer_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
3918 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3920 @var{dn}: a comma separated DN string (RFC4514)
3922 @var{err}: indicates the error position (if any)
3924 This function will set the DN on the provided certificate.
3925 The input string should be plain ASCII or UTF-8 encoded.
3927 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3928 negative error value.
3931 @subheading gnutls_x509_crt_set_issuer_dn_by_oid
3932 @anchor{gnutls_x509_crt_set_issuer_dn_by_oid}
3933 @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})
3934 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3936 @var{oid}: holds an Object Identifier in a null terminated string
3938 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3940 @var{name}: a pointer to the name
3942 @var{sizeof_name}: holds the size of @code{name}
3944 This function will set the part of the name of the Certificate
3945 issuer, specified by the given OID. The input string should be
3946 ASCII or UTF-8 encoded.
3948 Some helper macros with popular OIDs can be found in gnutls/x509.h
3949 With this function you can only set the known OIDs. You can test
3950 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3951 not known (by gnutls) you should properly DER encode your data,
3952 and call this function with @code{raw_flag} set.
3954 Normally you do not need to call this function, since the signing
3955 operation will copy the signer's name as the issuer of the
3958 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3959 negative error value.
3962 @subheading gnutls_x509_crt_set_issuer_unique_id
3963 @anchor{gnutls_x509_crt_set_issuer_unique_id}
3964 @deftypefun {int} {gnutls_x509_crt_set_issuer_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3965 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3967 @var{id}: The unique ID
3969 @var{id_size}: Holds the size of the unique ID.
3971 This function will set the X.509 certificate's issuer unique ID field.
3973 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3974 negative error value.
3976 @strong{Since:} 3.4.7
3979 @subheading gnutls_x509_crt_set_key
3980 @anchor{gnutls_x509_crt_set_key}
3981 @deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key})
3982 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3984 @var{key}: holds a private key
3986 This function will set the public parameters from the given
3987 private key to the certificate.
3989 To export the public key (i.e., the SubjectPublicKeyInfo part), check
3990 @code{gnutls_pubkey_import_x509()} .
3992 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3993 negative error value.
3996 @subheading gnutls_x509_crt_set_key_purpose_oid
3997 @anchor{gnutls_x509_crt_set_key_purpose_oid}
3998 @deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical})
3999 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4001 @var{oid}: a pointer to a null terminated string that holds the OID
4003 @var{critical}: Whether this extension will be critical or not
4005 This function will set the key purpose OIDs of the Certificate.
4006 These are stored in the Extended Key Usage extension (2.5.29.37)
4007 See the GNUTLS_KP_* definitions for human readable names.
4009 Subsequent calls to this function will append OIDs to the OID list.
4011 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
4012 otherwise a negative error code is returned.
4015 @subheading gnutls_x509_crt_set_key_usage
4016 @anchor{gnutls_x509_crt_set_key_usage}
4017 @deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage})
4018 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4020 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4022 This function will set the keyUsage certificate extension.
4024 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4025 negative error value.
4028 @subheading gnutls_x509_crt_set_name_constraints
4029 @anchor{gnutls_x509_crt_set_name_constraints}
4030 @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})
4031 @var{crt}: The certificate
4033 @var{nc}: The nameconstraints structure
4035 @var{critical}: whether this extension will be critical
4037 This function will set the provided name constraints to
4038 the certificate extension list. This extension is always
4041 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4043 @strong{Since:} 3.3.0
4046 @subheading gnutls_x509_crt_set_pin_function
4047 @anchor{gnutls_x509_crt_set_pin_function}
4048 @deftypefun {void} {gnutls_x509_crt_set_pin_function} (gnutls_x509_crt_t @var{crt}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
4049 @var{crt}: The certificate structure
4051 @var{fn}: the callback
4053 @var{userdata}: data associated with the callback
4055 This function will set a callback function to be used when
4056 it is required to access a protected object. This function overrides
4057 the global function set using @code{gnutls_pkcs11_set_pin_function()} .
4059 Note that this callback is currently used only during the import
4060 of a PKCS @code{11} certificate with @code{gnutls_x509_crt_import_url()} .
4062 @strong{Since:} 3.1.0
4065 @subheading gnutls_x509_crt_set_policy
4066 @anchor{gnutls_x509_crt_set_policy}
4067 @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})
4068 @var{crt}: should contain a @code{gnutls_x509_crt_t} type
4070 @var{policy}: A pointer to a policy
4072 @var{critical}: use non-zero if the extension is marked as critical
4074 This function will set the certificate policy extension (2.5.29.32).
4075 Multiple calls to this function append a new policy.
4077 Note the maximum text size for the qualifier @code{GNUTLS_X509_QUALIFIER_NOTICE}
4078 is 200 characters. This function will fail with @code{GNUTLS_E_INVALID_REQUEST}
4079 if this is exceeded.
4081 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4082 negative error value.
4084 @strong{Since:} 3.1.5
4087 @subheading gnutls_x509_crt_set_private_key_usage_period
4088 @anchor{gnutls_x509_crt_set_private_key_usage_period}
4089 @deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration})
4090 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4092 @var{activation}: The activation time
4094 @var{expiration}: The expiration time
4096 This function will set the private key usage period extension (2.5.29.16).
4098 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4099 negative error value.
4102 @subheading gnutls_x509_crt_set_proxy
4103 @anchor{gnutls_x509_crt_set_proxy}
4104 @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})
4105 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4107 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4108 and negative error codes indicate that the pathLenConstraints field should
4111 @var{policyLanguage}: OID describing the language of @code{policy} .
4113 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4115 @var{sizeof_policy}: size of @code{policy} .
4117 This function will set the proxyCertInfo extension.
4119 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4120 negative error value.
4123 @subheading gnutls_x509_crt_set_proxy_dn
4124 @anchor{gnutls_x509_crt_set_proxy_dn}
4125 @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})
4126 @var{crt}: a gnutls_x509_crt_t type with the new proxy cert
4128 @var{eecrt}: the end entity certificate that will be issuing the proxy
4130 @var{raw_flag}: must be 0, or 1 if the CN is DER encoded
4132 @var{name}: a pointer to the CN name, may be NULL (but MUST then be added later)
4134 @var{sizeof_name}: holds the size of @code{name}
4136 This function will set the subject in @code{crt} to the end entity's
4137 @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy
4138 certificate naming style. Note that if @code{name} is @code{NULL} , you MUST
4139 set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar.
4141 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4142 negative error value.
4145 @subheading gnutls_x509_crt_set_serial
4146 @anchor{gnutls_x509_crt_set_serial}
4147 @deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size})
4148 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4150 @var{serial}: The serial number
4152 @var{serial_size}: Holds the size of the serial field.
4154 This function will set the X.509 certificate's serial number.
4155 While the serial number is an integer, it is often handled
4156 as an opaque field by several CAs. For this reason this function
4157 accepts any kind of data as a serial number. To be consistent
4158 with the X.509/PKIX specifications the provided @code{serial} should be
4159 a big-endian positive number (i.e. it's leftmost bit should be zero).
4161 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4162 negative error value.
4165 @subheading gnutls_x509_crt_set_subject_alt_name
4166 @anchor{gnutls_x509_crt_set_subject_alt_name}
4167 @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})
4168 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4170 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4172 @var{data}: The data to be set
4174 @var{data_size}: The size of data to be set
4176 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
4178 This function will set the subject alternative name certificate
4179 extension. It can set the following types:
4181 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4182 negative error value.
4184 @strong{Since:} 2.6.0
4187 @subheading gnutls_x509_crt_set_subject_alternative_name
4188 @anchor{gnutls_x509_crt_set_subject_alternative_name}
4189 @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})
4190 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4192 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4194 @var{data_string}: The data to be set, a (0) terminated string
4196 This function will set the subject alternative name certificate
4197 extension. This function assumes that data can be expressed as a null
4200 The name of the function is unfortunate since it is incosistent with
4201 @code{gnutls_x509_crt_get_subject_alt_name()} .
4203 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4204 negative error value.
4207 @subheading gnutls_x509_crt_set_subject_key_id
4208 @anchor{gnutls_x509_crt_set_subject_key_id}
4209 @deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4210 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4212 @var{id}: The key ID
4214 @var{id_size}: Holds the size of the subject key ID field.
4216 This function will set the X.509 certificate's subject key ID
4219 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4220 negative error value.
4223 @subheading gnutls_x509_crt_set_subject_unique_id
4224 @anchor{gnutls_x509_crt_set_subject_unique_id}
4225 @deftypefun {int} {gnutls_x509_crt_set_subject_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4226 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4228 @var{id}: The unique ID
4230 @var{id_size}: Holds the size of the unique ID.
4232 This function will set the X.509 certificate's subject unique ID field.
4234 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4235 negative error value.
4237 @strong{Since:} 3.4.7
4240 @subheading gnutls_x509_crt_set_version
4241 @anchor{gnutls_x509_crt_set_version}
4242 @deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version})
4243 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4245 @var{version}: holds the version number. For X.509v1 certificates must be 1.
4247 This function will set the version of the certificate. This must
4248 be one for X.509 version 1, and so on. Plain certificates without
4249 extensions must have version set to one.
4251 To create well-formed certificates, you must specify version 3 if
4252 you use any certificate extensions. Extensions are created by
4253 functions such as @code{gnutls_x509_crt_set_subject_alt_name()}
4254 or @code{gnutls_x509_crt_set_key_usage()} .
4256 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4257 negative error value.
4260 @subheading gnutls_x509_crt_sign
4261 @anchor{gnutls_x509_crt_sign}
4262 @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})
4263 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4265 @var{issuer}: is the certificate of the certificate issuer
4267 @var{issuer_key}: holds the issuer's private key
4269 This function is the same a @code{gnutls_x509_crt_sign2()} with no flags,
4270 and SHA1 as the hash algorithm.
4272 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4273 negative error value.
4276 @subheading gnutls_x509_crt_sign2
4277 @anchor{gnutls_x509_crt_sign2}
4278 @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})
4279 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4281 @var{issuer}: is the certificate of the certificate issuer
4283 @var{issuer_key}: holds the issuer's private key
4285 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
4287 @var{flags}: must be 0
4289 This function will sign the certificate with the issuer's private key, and
4290 will copy the issuer's information into the certificate.
4292 This must be the last step in a certificate generation since all
4293 the previously set parameters are now signed.
4295 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4296 negative error value.
4299 @subheading gnutls_x509_crt_verify
4300 @anchor{gnutls_x509_crt_verify}
4301 @deftypefun {int} {gnutls_x509_crt_verify} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crt_t * @var{CA_list}, int @var{CA_list_length}, unsigned int @var{flags}, unsigned int * @var{verify})
4302 @var{cert}: is the certificate to be verified
4304 @var{CA_list}: is one certificate that is considered to be trusted one
4306 @var{CA_list_length}: holds the number of CA certificate in CA_list
4308 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
4310 @var{verify}: will hold the certificate verification output.
4312 This function will try to verify the given certificate and return
4313 its status. Note that a verification error does not imply a negative
4314 return status. In that case the @code{verify} status is set.
4316 The details of the verification are the same
4317 as in @code{gnutls_x509_trust_list_verify_crt2()} .
4319 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4320 negative error value.
4323 @subheading gnutls_x509_crt_verify_data2
4324 @anchor{gnutls_x509_crt_verify_data2}
4325 @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})
4326 @var{crt}: Holds the certificate to verify with
4328 @var{algo}: The signature algorithm used
4330 @var{flags}: Zero or an OR list of @code{gnutls_certificate_verify_flags}
4332 @var{data}: holds the signed data
4334 @var{signature}: contains the signature
4336 This function will verify the given signed data, using the
4337 parameters from the certificate.
4339 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
4340 is returned, and zero or positive code on success.
4342 @strong{Since:} 3.4.0
4345 @subheading gnutls_x509_dn_deinit
4346 @anchor{gnutls_x509_dn_deinit}
4347 @deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn})
4348 @var{dn}: a DN uint8_t object pointer.
4350 This function deallocates the DN object as returned by
4351 @code{gnutls_x509_dn_import()} .
4353 @strong{Since:} 2.4.0
4356 @subheading gnutls_x509_dn_export
4357 @anchor{gnutls_x509_dn_export}
4358 @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})
4359 @var{dn}: Holds the uint8_t DN object
4361 @var{format}: the format of output params. One of PEM or DER.
4363 @var{output_data}: will contain a DN PEM or DER encoded
4365 @var{output_data_size}: holds the size of output_data (and will be
4366 replaced by the actual size of parameters)
4368 This function will export the DN to DER or PEM format.
4370 If the buffer provided is not long enough to hold the output, then
4371 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
4374 If the structure is PEM encoded, it will have a header
4377 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4378 negative error value.
4381 @subheading gnutls_x509_dn_export2
4382 @anchor{gnutls_x509_dn_export2}
4383 @deftypefun {int} {gnutls_x509_dn_export2} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
4384 @var{dn}: Holds the uint8_t DN object
4386 @var{format}: the format of output params. One of PEM or DER.
4388 @var{out}: will contain a DN PEM or DER encoded
4390 This function will export the DN to DER or PEM format.
4392 The output buffer is allocated using @code{gnutls_malloc()} .
4394 If the structure is PEM encoded, it will have a header
4397 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4398 negative error value.
4400 @strong{Since:} 3.1.3
4403 @subheading gnutls_x509_dn_get_rdn_ava
4404 @anchor{gnutls_x509_dn_get_rdn_ava}
4405 @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})
4406 @var{dn}: a pointer to DN
4408 @var{irdn}: index of RDN
4410 @var{iava}: index of AVA.
4412 @var{ava}: Pointer to structure which will hold output information.
4414 Get pointers to data within the DN. The format of the @code{ava} structure
4417 struct gnutls_x509_ava_st @{
4419 gnutls_datum_t value;
4420 unsigned long value_tag;
4423 The X.509 distinguished name is a sequence of sequences of strings
4424 and this is what the @code{irdn} and @code{iava} indexes model.
4426 Note that @code{ava} will contain pointers into the @code{dn} structure which
4427 in turns points to the original certificate. Thus you should not
4428 modify any data or deallocate any of those.
4430 This is a low-level function that requires the caller to do the
4431 value conversions when necessary (e.g. from UCS-2).
4433 @strong{Returns:} Returns 0 on success, or an error code.
4436 @subheading gnutls_x509_dn_get_str
4437 @anchor{gnutls_x509_dn_get_str}
4438 @deftypefun {int} {gnutls_x509_dn_get_str} (gnutls_x509_dn_t @var{dn}, gnutls_datum_t * @var{str})
4439 @var{dn}: a pointer to DN
4441 @var{str}: a datum that will hold the name
4443 This function will allocate buffer and copy the name in the provided DN.
4444 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
4445 described in RFC4514. The output string will be ASCII or UTF-8
4446 encoded, depending on the certificate data.
4448 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4449 negative error value.
4451 @strong{Since:} 3.4.2
4454 @subheading gnutls_x509_dn_import
4455 @anchor{gnutls_x509_dn_import}
4456 @deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data})
4457 @var{dn}: the structure that will hold the imported DN
4459 @var{data}: should contain a DER encoded RDN sequence
4461 This function parses an RDN sequence and stores the result to a
4462 @code{gnutls_x509_dn_t} type. The data must have been initialized
4463 with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to
4466 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4467 negative error value.
4469 @strong{Since:} 2.4.0
4472 @subheading gnutls_x509_dn_init
4473 @anchor{gnutls_x509_dn_init}
4474 @deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn})
4475 @var{dn}: the object to be initialized
4477 This function initializes a @code{gnutls_x509_dn_t} type.
4479 The object returned must be deallocated using
4480 @code{gnutls_x509_dn_deinit()} .
4482 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4483 negative error value.
4485 @strong{Since:} 2.4.0
4488 @subheading gnutls_x509_dn_oid_known
4489 @anchor{gnutls_x509_dn_oid_known}
4490 @deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid})
4491 @var{oid}: holds an Object Identifier in a null terminated string
4493 This function will inform about known DN OIDs. This is useful since
4494 functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information
4495 on known OIDs to properly encode their input. Object Identifiers
4496 that are not known are not encoded by these functions, and their
4497 input is stored directly into the ASN.1 structure. In that case of
4498 unknown OIDs, you have the responsibility of DER encoding your
4501 @strong{Returns:} 1 on known OIDs and 0 otherwise.
4504 @subheading gnutls_x509_dn_oid_name
4505 @anchor{gnutls_x509_dn_oid_name}
4506 @deftypefun {const char *} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags})
4507 @var{oid}: holds an Object Identifier in a null terminated string
4509 @var{flags}: 0 or GNUTLS_X509_DN_OID_*
4511 This function will return the name of a known DN OID. If
4512 @code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function
4513 will return the given OID if no descriptive name has been
4516 @strong{Returns:} A null terminated string or NULL otherwise.
4521 @subheading gnutls_x509_ext_deinit
4522 @anchor{gnutls_x509_ext_deinit}
4523 @deftypefun {void} {gnutls_x509_ext_deinit} (gnutls_x509_ext_st * @var{ext})
4524 @var{ext}: The extensions structure
4526 This function will deinitialize an extensions structure.
4528 @strong{Since:} 3.3.8
4531 @subheading gnutls_x509_ext_export_aia
4532 @anchor{gnutls_x509_ext_export_aia}
4533 @deftypefun {int} {gnutls_x509_ext_export_aia} (gnutls_x509_aia_t @var{aia}, gnutls_datum_t * @var{ext})
4534 @var{aia}: The authority info access
4536 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4538 This function will DER encode the Authority Information Access (AIA)
4539 extension; see RFC 5280 section 4.2.2.1 for more information on the
4542 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4543 negative error value.
4545 @strong{Since:} 3.3.0
4548 @subheading gnutls_x509_ext_export_authority_key_id
4549 @anchor{gnutls_x509_ext_export_authority_key_id}
4550 @deftypefun {int} {gnutls_x509_ext_export_authority_key_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{ext})
4551 @var{aki}: An initialized authority key identifier
4553 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4555 This function will convert the provided key identifier to a
4556 DER-encoded PKIX AuthorityKeyIdentifier extension.
4557 The output data in @code{ext} will be allocated using
4558 @code{gnutls_malloc()} .
4560 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4562 @strong{Since:} 3.3.0
4565 @subheading gnutls_x509_ext_export_basic_constraints
4566 @anchor{gnutls_x509_ext_export_basic_constraints}
4567 @deftypefun {int} {gnutls_x509_ext_export_basic_constraints} (unsigned int @var{ca}, int @var{pathlen}, gnutls_datum_t * @var{ext})
4568 @var{ca}: non-zero for a CA
4570 @var{pathlen}: The path length constraint (set to -1 for no constraint)
4572 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4574 This function will convert the parameters provided to a basic constraints
4575 DER encoded extension (2.5.29.19).
4576 The @code{ext} data will be allocated using
4577 @code{gnutls_malloc()} .
4579 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4580 negative error value.
4582 @strong{Since:} 3.3.0
4585 @subheading gnutls_x509_ext_export_crl_dist_points
4586 @anchor{gnutls_x509_ext_export_crl_dist_points}
4587 @deftypefun {int} {gnutls_x509_ext_export_crl_dist_points} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_datum_t * @var{ext})
4588 @var{cdp}: A pointer to an initialized CRL distribution points.
4590 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4592 This function will convert the provided policies, to a certificate policy
4593 DER encoded extension (2.5.29.31).
4595 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4597 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4599 @strong{Since:} 3.3.0
4602 @subheading gnutls_x509_ext_export_key_purposes
4603 @anchor{gnutls_x509_ext_export_key_purposes}
4604 @deftypefun {int} {gnutls_x509_ext_export_key_purposes} (gnutls_x509_key_purposes_t @var{p}, gnutls_datum_t * @var{ext})
4605 @var{p}: The key purposes
4607 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4609 This function will convert the key purposes type to a
4610 DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in
4611 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4613 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4615 @strong{Since:} 3.3.0
4618 @subheading gnutls_x509_ext_export_key_usage
4619 @anchor{gnutls_x509_ext_export_key_usage}
4620 @deftypefun {int} {gnutls_x509_ext_export_key_usage} (unsigned int @var{usage}, gnutls_datum_t * @var{ext})
4621 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4623 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4625 This function will convert the keyUsage bit string to a DER
4626 encoded PKIX extension. The @code{ext} data will be allocated using
4627 @code{gnutls_malloc()} .
4629 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4630 negative error value.
4632 @strong{Since:} 3.3.0
4635 @subheading gnutls_x509_ext_export_name_constraints
4636 @anchor{gnutls_x509_ext_export_name_constraints}
4637 @deftypefun {int} {gnutls_x509_ext_export_name_constraints} (gnutls_x509_name_constraints_t @var{nc}, gnutls_datum_t * @var{ext})
4638 @var{nc}: The nameconstraints
4640 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4642 This function will convert the provided name constraints type to a
4643 DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in
4644 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4646 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4648 @strong{Since:} 3.3.0
4651 @subheading gnutls_x509_ext_export_policies
4652 @anchor{gnutls_x509_ext_export_policies}
4653 @deftypefun {int} {gnutls_x509_ext_export_policies} (gnutls_x509_policies_t @var{policies}, gnutls_datum_t * @var{ext})
4654 @var{policies}: A pointer to an initialized policies.
4656 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4658 This function will convert the provided policies, to a certificate policy
4659 DER encoded extension (2.5.29.32).
4661 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4663 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4665 @strong{Since:} 3.3.0
4668 @subheading gnutls_x509_ext_export_private_key_usage_period
4669 @anchor{gnutls_x509_ext_export_private_key_usage_period}
4670 @deftypefun {int} {gnutls_x509_ext_export_private_key_usage_period} (time_t @var{activation}, time_t @var{expiration}, gnutls_datum_t * @var{ext})
4671 @var{activation}: The activation time
4673 @var{expiration}: The expiration time
4675 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4677 This function will convert the periods provided to a private key
4678 usage DER encoded extension (2.5.29.16).
4679 The @code{ext} data will be allocated using
4680 @code{gnutls_malloc()} .
4682 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4683 negative error value.
4685 @strong{Since:} 3.3.0
4688 @subheading gnutls_x509_ext_export_proxy
4689 @anchor{gnutls_x509_ext_export_proxy}
4690 @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})
4691 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4692 and negative error codes indicate that the pathLenConstraints field should
4695 @var{policyLanguage}: OID describing the language of @code{policy} .
4697 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4699 @var{sizeof_policy}: size of @code{policy} .
4701 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4703 This function will convert the parameters provided to a proxyCertInfo extension.
4705 The @code{ext} data will be allocated using
4706 @code{gnutls_malloc()} .
4708 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4709 negative error value.
4711 @strong{Since:} 3.3.0
4714 @subheading gnutls_x509_ext_export_subject_alt_names
4715 @anchor{gnutls_x509_ext_export_subject_alt_names}
4716 @deftypefun {int} {gnutls_x509_ext_export_subject_alt_names} (gnutls_subject_alt_names_t @var{sans}, gnutls_datum_t * @var{ext})
4717 @var{sans}: The alternative names
4719 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4721 This function will convert the provided alternative names structure to a
4722 DER-encoded SubjectAltName PKIX extension. The output data in @code{ext} will be allocated using
4723 @code{gnutls_malloc()} .
4725 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4727 @strong{Since:} 3.3.0
4730 @subheading gnutls_x509_ext_export_subject_key_id
4731 @anchor{gnutls_x509_ext_export_subject_key_id}
4732 @deftypefun {int} {gnutls_x509_ext_export_subject_key_id} (const gnutls_datum_t * @var{id}, gnutls_datum_t * @var{ext})
4733 @var{id}: The key identifier
4735 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4737 This function will convert the provided key identifier to a
4738 DER-encoded PKIX SubjectKeyIdentifier extension.
4739 The output data in @code{ext} will be allocated using
4740 @code{gnutls_malloc()} .
4742 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4744 @strong{Since:} 3.3.0
4747 @subheading gnutls_x509_ext_import_aia
4748 @anchor{gnutls_x509_ext_import_aia}
4749 @deftypefun {int} {gnutls_x509_ext_import_aia} (const gnutls_datum_t * @var{ext}, gnutls_x509_aia_t @var{aia}, unsigned int @var{flags})
4750 @var{ext}: The DER-encoded extension data
4752 @var{aia}: The authority info access
4754 @var{flags}: should be zero
4756 This function extracts the Authority Information Access (AIA)
4757 extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1
4758 for more information on the extension. The
4759 AIA extension holds a sequence of AccessDescription (AD) data.
4761 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4763 @strong{Since:} 3.3.0
4766 @subheading gnutls_x509_ext_import_authority_key_id
4767 @anchor{gnutls_x509_ext_import_authority_key_id}
4768 @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})
4769 @var{ext}: a DER encoded extension
4771 @var{aki}: An initialized authority key identifier type
4773 @var{flags}: should be zero
4775 This function will return the subject key ID stored in the provided
4776 AuthorityKeyIdentifier extension.
4778 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4779 if the extension is not present, otherwise a negative error value.
4781 @strong{Since:} 3.3.0
4784 @subheading gnutls_x509_ext_import_basic_constraints
4785 @anchor{gnutls_x509_ext_import_basic_constraints}
4786 @deftypefun {int} {gnutls_x509_ext_import_basic_constraints} (const gnutls_datum_t * @var{ext}, unsigned int * @var{ca}, int * @var{pathlen})
4787 @var{ext}: the DER encoded extension data
4789 @var{ca}: will be non zero if the CA status is true
4791 @var{pathlen}: the path length constraint; will be set to -1 for no limit
4793 This function will return the CA status and path length constraint
4794 as written in the PKIX extension 2.5.29.19.
4796 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4797 negative error value.
4799 @strong{Since:} 3.3.0
4802 @subheading gnutls_x509_ext_import_crl_dist_points
4803 @anchor{gnutls_x509_ext_import_crl_dist_points}
4804 @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})
4805 @var{ext}: the DER encoded extension data
4807 @var{cdp}: A pointer to an initialized CRL distribution points.
4809 @var{flags}: should be zero
4811 This function will extract the CRL distribution points extension (2.5.29.31)
4812 and store it into the provided type.
4814 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4816 @strong{Since:} 3.3.0
4819 @subheading gnutls_x509_ext_import_key_purposes
4820 @anchor{gnutls_x509_ext_import_key_purposes}
4821 @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})
4822 @var{ext}: The DER-encoded extension data
4824 @var{p}: The key purposes
4826 @var{flags}: should be zero
4828 This function will extract the key purposes in the provided DER-encoded
4829 ExtKeyUsageSyntax PKIX extension, to a @code{gnutls_x509_key_purposes_t} type.
4830 The data must be initialized.
4832 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4834 @strong{Since:} 3.3.0
4837 @subheading gnutls_x509_ext_import_key_usage
4838 @anchor{gnutls_x509_ext_import_key_usage}
4839 @deftypefun {int} {gnutls_x509_ext_import_key_usage} (const gnutls_datum_t * @var{ext}, unsigned int * @var{key_usage})
4840 @var{ext}: the DER encoded extension data
4842 @var{key_usage}: where the key usage bits will be stored
4844 This function will return certificate's key usage, by reading the DER
4845 data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
4846 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
4847 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
4848 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
4849 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
4850 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
4852 @strong{Returns:} the certificate key usage, or a negative error code in case of
4853 parsing error. If the certificate does not contain the keyUsage
4854 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
4857 @strong{Since:} 3.3.0
4860 @subheading gnutls_x509_ext_import_name_constraints
4861 @anchor{gnutls_x509_ext_import_name_constraints}
4862 @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})
4863 @var{ext}: a DER encoded extension
4865 @var{nc}: The nameconstraints
4867 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
4869 This function will return an intermediate type containing
4870 the name constraints of the provided NameConstraints extension. That
4871 can be used in combination with @code{gnutls_x509_name_constraints_check()}
4872 to verify whether a server's name is in accordance with the constraints.
4874 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
4875 the @code{nc} type is empty this function will behave identically as if the flag was not set.
4876 Otherwise if there are elements in the @code{nc} type then only the
4877 excluded constraints will be appended to the constraints.
4879 Note that @code{nc} must be initialized prior to calling this function.
4881 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4882 if the extension is not present, otherwise a negative error value.
4884 @strong{Since:} 3.3.0
4887 @subheading gnutls_x509_ext_import_policies
4888 @anchor{gnutls_x509_ext_import_policies}
4889 @deftypefun {int} {gnutls_x509_ext_import_policies} (const gnutls_datum_t * @var{ext}, gnutls_x509_policies_t @var{policies}, unsigned int @var{flags})
4890 @var{ext}: the DER encoded extension data
4892 @var{policies}: A pointer to an initialized policies.
4894 @var{flags}: should be zero
4896 This function will extract the certificate policy extension (2.5.29.32)
4897 and store it the provided policies.
4899 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4901 @strong{Since:} 3.3.0
4904 @subheading gnutls_x509_ext_import_private_key_usage_period
4905 @anchor{gnutls_x509_ext_import_private_key_usage_period}
4906 @deftypefun {int} {gnutls_x509_ext_import_private_key_usage_period} (const gnutls_datum_t * @var{ext}, time_t * @var{activation}, time_t * @var{expiration})
4907 @var{ext}: the DER encoded extension data
4909 @var{activation}: Will hold the activation time
4911 @var{expiration}: Will hold the expiration time
4913 This function will return the expiration and activation
4914 times of the private key as written in the
4915 PKIX extension 2.5.29.16.
4917 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4918 negative error value.
4920 @strong{Since:} 3.3.0
4923 @subheading gnutls_x509_ext_import_proxy
4924 @anchor{gnutls_x509_ext_import_proxy}
4925 @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})
4926 @var{ext}: the DER encoded extension data
4928 @var{pathlen}: pointer to output integer indicating path length (may be
4929 NULL), non-negative error codes indicate a present pCPathLenConstraint
4930 field and the actual value, -1 indicate that the field is absent.
4932 @var{policyLanguage}: output variable with OID of policy language
4934 @var{policy}: output variable with policy data
4936 @var{sizeof_policy}: output variable size of policy data
4938 This function will return the information from a proxy certificate
4939 extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
4940 The @code{policyLanguage} and @code{policy} values must be deinitialized using @code{gnutls_free()} after use.
4942 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4943 negative error value.
4945 @strong{Since:} 3.3.0
4948 @subheading gnutls_x509_ext_import_subject_alt_names
4949 @anchor{gnutls_x509_ext_import_subject_alt_names}
4950 @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})
4951 @var{ext}: The DER-encoded extension data
4953 @var{sans}: The alternative names
4955 @var{flags}: should be zero
4957 This function will export the alternative names in the provided DER-encoded
4958 SubjectAltName PKIX extension, to a @code{gnutls_subject_alt_names_t} type. @code{sans} must be initialized.
4960 This function will succeed even if there no subject alternative names
4963 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4965 @strong{Since:} 3.3.0
4968 @subheading gnutls_x509_ext_import_subject_key_id
4969 @anchor{gnutls_x509_ext_import_subject_key_id}
4970 @deftypefun {int} {gnutls_x509_ext_import_subject_key_id} (const gnutls_datum_t * @var{ext}, gnutls_datum_t * @var{id})
4971 @var{ext}: a DER encoded extension
4973 @var{id}: will contain the subject key ID
4975 This function will return the subject key ID stored in the provided
4976 SubjectKeyIdentifier extension. The ID will be allocated using
4977 @code{gnutls_malloc()} .
4979 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4980 if the extension is not present, otherwise a negative error value.
4982 @strong{Since:} 3.3.0
4985 @subheading gnutls_x509_ext_print
4986 @anchor{gnutls_x509_ext_print}
4987 @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})
4988 @var{exts}: The data to be printed
4990 @var{exts_size}: the number of available structures
4992 @var{format}: Indicate the format to use
4994 @var{out}: Newly allocated datum with null terminated string.
4996 This function will pretty print X.509 certificate extensions,
4997 suitable for display to a human.
4999 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
5001 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5002 negative error value.
5005 @subheading gnutls_x509_key_purpose_deinit
5006 @anchor{gnutls_x509_key_purpose_deinit}
5007 @deftypefun {void} {gnutls_x509_key_purpose_deinit} (gnutls_x509_key_purposes_t @var{p})
5008 @var{p}: The key purposes
5010 This function will deinitialize a key purposes type.
5012 @strong{Since:} 3.3.0
5015 @subheading gnutls_x509_key_purpose_get
5016 @anchor{gnutls_x509_key_purpose_get}
5017 @deftypefun {int} {gnutls_x509_key_purpose_get} (gnutls_x509_key_purposes_t @var{p}, unsigned @var{idx}, gnutls_datum_t * @var{oid})
5018 @var{p}: The key purposes
5020 @var{idx}: The index of the key purpose to retrieve
5022 @var{oid}: Will hold the object identifier of the key purpose (to be treated as constant)
5024 This function will retrieve the specified by the index key purpose in the
5025 purposes type. The object identifier will be a null terminated string.
5027 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5028 if the index is out of bounds, otherwise a negative error value.
5030 @strong{Since:} 3.3.0
5033 @subheading gnutls_x509_key_purpose_init
5034 @anchor{gnutls_x509_key_purpose_init}
5035 @deftypefun {int} {gnutls_x509_key_purpose_init} (gnutls_x509_key_purposes_t * @var{p})
5036 @var{p}: The key purposes
5038 This function will initialize an alternative names type.
5040 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5042 @strong{Since:} 3.3.0
5045 @subheading gnutls_x509_key_purpose_set
5046 @anchor{gnutls_x509_key_purpose_set}
5047 @deftypefun {int} {gnutls_x509_key_purpose_set} (gnutls_x509_key_purposes_t @var{p}, const char * @var{oid})
5048 @var{p}: The key purposes
5050 @var{oid}: The object identifier of the key purpose
5052 This function will store the specified key purpose in the
5055 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
5057 @strong{Since:} 3.3.0
5060 @subheading gnutls_x509_name_constraints_add_excluded
5061 @anchor{gnutls_x509_name_constraints_add_excluded}
5062 @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})
5063 @var{nc}: The nameconstraints
5065 @var{type}: The type of the constraints
5067 @var{name}: The data of the constraints
5069 This function will add a name constraint to the list of excluded
5072 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5074 @strong{Since:} 3.3.0
5077 @subheading gnutls_x509_name_constraints_add_permitted
5078 @anchor{gnutls_x509_name_constraints_add_permitted}
5079 @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})
5080 @var{nc}: The nameconstraints
5082 @var{type}: The type of the constraints
5084 @var{name}: The data of the constraints
5086 This function will add a name constraint to the list of permitted
5089 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5091 @strong{Since:} 3.3.0
5094 @subheading gnutls_x509_name_constraints_check
5095 @anchor{gnutls_x509_name_constraints_check}
5096 @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})
5097 @var{nc}: the extracted name constraints
5099 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5101 @var{name}: the name to be checked
5103 This function will check the provided name against the constraints in
5104 @code{nc} using the RFC5280 rules. Currently this function is limited to DNS
5105 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5107 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5109 @strong{Since:} 3.3.0
5112 @subheading gnutls_x509_name_constraints_check_crt
5113 @anchor{gnutls_x509_name_constraints_check_crt}
5114 @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})
5115 @var{nc}: the extracted name constraints
5117 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5119 @var{cert}: the certificate to be checked
5121 This function will check the provided certificate names against the constraints in
5122 @code{nc} using the RFC5280 rules. It will traverse all the certificate's names and
5125 Currently this function is limited to DNS
5126 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5128 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5130 @strong{Since:} 3.3.0
5133 @subheading gnutls_x509_name_constraints_deinit
5134 @anchor{gnutls_x509_name_constraints_deinit}
5135 @deftypefun {void} {gnutls_x509_name_constraints_deinit} (gnutls_x509_name_constraints_t @var{nc})
5136 @var{nc}: The nameconstraints
5138 This function will deinitialize a name constraints type.
5140 @strong{Since:} 3.3.0
5143 @subheading gnutls_x509_name_constraints_get_excluded
5144 @anchor{gnutls_x509_name_constraints_get_excluded}
5145 @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})
5146 @var{nc}: the extracted name constraints
5148 @var{idx}: the index of the constraint
5150 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5152 @var{name}: the name in the constraint (of the specific type)
5154 This function will return an intermediate type containing
5155 the name constraints of the provided CA certificate. That
5156 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5157 to verify whether a server's name is in accordance with the constraints.
5159 The name should be treated as constant and valid for the lifetime of @code{nc} .
5161 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5162 if the extension is not present, otherwise a negative error value.
5164 @strong{Since:} 3.3.0
5167 @subheading gnutls_x509_name_constraints_get_permitted
5168 @anchor{gnutls_x509_name_constraints_get_permitted}
5169 @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})
5170 @var{nc}: the extracted name constraints
5172 @var{idx}: the index of the constraint
5174 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5176 @var{name}: the name in the constraint (of the specific type)
5178 This function will return an intermediate type containing
5179 the name constraints of the provided CA certificate. That
5180 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5181 to verify whether a server's name is in accordance with the constraints.
5183 The name should be treated as constant and valid for the lifetime of @code{nc} .
5185 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5186 if the extension is not present, otherwise a negative error value.
5188 @strong{Since:} 3.3.0
5191 @subheading gnutls_x509_name_constraints_init
5192 @anchor{gnutls_x509_name_constraints_init}
5193 @deftypefun {int} {gnutls_x509_name_constraints_init} (gnutls_x509_name_constraints_t * @var{nc})
5194 @var{nc}: The nameconstraints
5196 This function will initialize a name constraints type.
5198 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5200 @strong{Since:} 3.3.0
5203 @subheading gnutls_x509_othername_to_virtual
5204 @anchor{gnutls_x509_othername_to_virtual}
5205 @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})
5206 @var{oid}: The othername object identifier
5208 @var{othername}: The othername data
5210 @var{virt_type}: GNUTLS_SAN_OTHERNAME_XXX
5212 @var{virt}: allocated printable data
5214 This function will parse and convert the othername data to a virtual
5215 type supported by gnutls.
5217 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5219 @strong{Since:} 3.3.8
5222 @subheading gnutls_x509_policies_deinit
5223 @anchor{gnutls_x509_policies_deinit}
5224 @deftypefun {void} {gnutls_x509_policies_deinit} (gnutls_x509_policies_t @var{policies})
5225 @var{policies}: The authority key identifier
5227 This function will deinitialize an authority key identifier type.
5229 @strong{Since:} 3.3.0
5232 @subheading gnutls_x509_policies_get
5233 @anchor{gnutls_x509_policies_get}
5234 @deftypefun {int} {gnutls_x509_policies_get} (gnutls_x509_policies_t @var{policies}, unsigned int @var{seq}, struct gnutls_x509_policy_st * @var{policy})
5235 @var{policies}: The policies
5237 @var{seq}: The index of the name to get
5239 @var{policy}: Will hold the policy
5241 This function will return a specific policy as stored in
5242 the @code{policies} type. The returned values should be treated as constant
5243 and valid for the lifetime of @code{policies} .
5245 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5246 if the index is out of bounds, otherwise a negative error value.
5248 @strong{Since:} 3.3.0
5251 @subheading gnutls_x509_policies_init
5252 @anchor{gnutls_x509_policies_init}
5253 @deftypefun {int} {gnutls_x509_policies_init} (gnutls_x509_policies_t * @var{policies})
5254 @var{policies}: The authority key ID
5256 This function will initialize an authority key ID type.
5258 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5260 @strong{Since:} 3.3.0
5263 @subheading gnutls_x509_policies_set
5264 @anchor{gnutls_x509_policies_set}
5265 @deftypefun {int} {gnutls_x509_policies_set} (gnutls_x509_policies_t @var{policies}, const struct gnutls_x509_policy_st * @var{policy})
5266 @var{policies}: An initialized policies
5268 @var{policy}: Contains the policy to set
5270 This function will store the specified policy in
5271 the provided @code{policies} .
5273 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
5275 @strong{Since:} 3.3.0
5278 @subheading gnutls_x509_policy_release
5279 @anchor{gnutls_x509_policy_release}
5280 @deftypefun {void} {gnutls_x509_policy_release} (struct gnutls_x509_policy_st * @var{policy})
5281 @var{policy}: a certificate policy
5283 This function will deinitialize all memory associated with the provided
5284 @code{policy} . The policy is allocated using @code{gnutls_x509_crt_get_policy()} .
5286 @strong{Since:} 3.1.5
5289 @subheading gnutls_x509_privkey_cpy
5290 @anchor{gnutls_x509_privkey_cpy}
5291 @deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src})
5292 @var{dst}: The destination key, which should be initialized.
5294 @var{src}: The source key
5296 This function will copy a private key from source to destination
5297 key. Destination has to be initialized.
5299 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5300 negative error value.
5303 @subheading gnutls_x509_privkey_deinit
5304 @anchor{gnutls_x509_privkey_deinit}
5305 @deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key})
5306 @var{key}: The key to be deinitialized
5308 This function will deinitialize a private key structure.
5311 @subheading gnutls_x509_privkey_export
5312 @anchor{gnutls_x509_privkey_export}
5313 @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})
5314 @var{key}: Holds the key
5316 @var{format}: the format of output params. One of PEM or DER.
5318 @var{output_data}: will contain a private key PEM or DER encoded
5320 @var{output_data_size}: holds the size of output_data (and will be
5321 replaced by the actual size of parameters)
5323 This function will export the private key to a PKCS1 structure for
5324 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5325 the same format with the parameters used by openssl.
5327 If the buffer provided is not long enough to hold the output, then
5328 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
5331 If the structure is PEM encoded, it will have a header
5332 of "BEGIN RSA PRIVATE KEY".
5334 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5335 negative error value.
5338 @subheading gnutls_x509_privkey_export2
5339 @anchor{gnutls_x509_privkey_export2}
5340 @deftypefun {int} {gnutls_x509_privkey_export2} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
5341 @var{key}: Holds the key
5343 @var{format}: the format of output params. One of PEM or DER.
5345 @var{out}: will contain a private key PEM or DER encoded
5347 This function will export the private key to a PKCS1 structure for
5348 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5349 the same format with the parameters used by openssl.
5351 The output buffer is allocated using @code{gnutls_malloc()} .
5353 If the structure is PEM encoded, it will have a header
5354 of "BEGIN RSA PRIVATE KEY".
5356 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5357 negative error value.
5362 @subheading gnutls_x509_privkey_export2_pkcs8
5363 @anchor{gnutls_x509_privkey_export2_pkcs8}
5364 @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})
5365 @var{key}: Holds the key
5367 @var{format}: the format of output params. One of PEM or DER.
5369 @var{password}: the password that will be used to encrypt the key.
5371 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5373 @var{out}: will contain a private key PEM or DER encoded
5375 This function will export the private key to a PKCS8 structure.
5376 Both RSA and DSA keys can be exported. For DSA keys we use
5377 PKCS @code{11} definitions. If the flags do not specify the encryption
5378 cipher, then the default 3DES (PBES2) will be used.
5380 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5381 encryption schemas, or ASCII for the PKCS12 schemas.
5383 The output buffer is allocated using @code{gnutls_malloc()} .
5385 If the structure is PEM encoded, it will have a header
5386 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5387 encryption is not used.
5389 @strong{Returns:} In case of failure a negative error code will be
5390 returned, and 0 on success.
5395 @subheading gnutls_x509_privkey_export_dsa_raw
5396 @anchor{gnutls_x509_privkey_export_dsa_raw}
5397 @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})
5400 @var{p}: will hold the p
5402 @var{q}: will hold the q
5404 @var{g}: will hold the g
5406 @var{y}: will hold the y
5408 @var{x}: will hold the x
5410 This function will export the DSA private key's parameters found
5411 in the given structure. The new parameters will be allocated using
5412 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5414 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5415 negative error value.
5418 @subheading gnutls_x509_privkey_export_ecc_raw
5419 @anchor{gnutls_x509_privkey_export_ecc_raw}
5420 @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})
5423 @var{curve}: will hold the curve
5425 @var{x}: will hold the x coordinate
5427 @var{y}: will hold the y coordinate
5429 @var{k}: will hold the private key
5431 This function will export the ECC private key's parameters found
5432 in the given structure. The new parameters will be allocated using
5433 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5435 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5436 negative error value.
5441 @subheading gnutls_x509_privkey_export_pkcs8
5442 @anchor{gnutls_x509_privkey_export_pkcs8}
5443 @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})
5444 @var{key}: Holds the key
5446 @var{format}: the format of output params. One of PEM or DER.
5448 @var{password}: the password that will be used to encrypt the key.
5450 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5452 @var{output_data}: will contain a private key PEM or DER encoded
5454 @var{output_data_size}: holds the size of output_data (and will be
5455 replaced by the actual size of parameters)
5457 This function will export the private key to a PKCS8 structure.
5458 Both RSA and DSA keys can be exported. For DSA keys we use
5459 PKCS @code{11} definitions. If the flags do not specify the encryption
5460 cipher, then the default 3DES (PBES2) will be used.
5462 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5463 encryption schemas, or ASCII for the PKCS12 schemas.
5465 If the buffer provided is not long enough to hold the output, then
5466 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
5469 If the structure is PEM encoded, it will have a header
5470 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5471 encryption is not used.
5473 @strong{Returns:} In case of failure a negative error code will be
5474 returned, and 0 on success.
5477 @subheading gnutls_x509_privkey_export_rsa_raw
5478 @anchor{gnutls_x509_privkey_export_rsa_raw}
5479 @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})
5482 @var{m}: will hold the modulus
5484 @var{e}: will hold the public exponent
5486 @var{d}: will hold the private exponent
5488 @var{p}: will hold the first prime (p)
5490 @var{q}: will hold the second prime (q)
5492 @var{u}: will hold the coefficient
5494 This function will export the RSA private key's parameters found
5495 in the given structure. The new parameters will be allocated using
5496 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5498 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5499 negative error value.
5502 @subheading gnutls_x509_privkey_export_rsa_raw2
5503 @anchor{gnutls_x509_privkey_export_rsa_raw2}
5504 @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})
5507 @var{m}: will hold the modulus
5509 @var{e}: will hold the public exponent
5511 @var{d}: will hold the private exponent
5513 @var{p}: will hold the first prime (p)
5515 @var{q}: will hold the second prime (q)
5517 @var{u}: will hold the coefficient
5519 @var{e1}: will hold e1 = d mod (p-1)
5521 @var{e2}: will hold e2 = d mod (q-1)
5523 This function will export the RSA private key's parameters found
5524 in the given structure. The new parameters will be allocated using
5525 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5527 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5528 negative error value.
5530 @strong{Since:} 2.12.0
5533 @subheading gnutls_x509_privkey_fix
5534 @anchor{gnutls_x509_privkey_fix}
5535 @deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key})
5538 This function will recalculate the secondary parameters in a key.
5539 In RSA keys, this can be the coefficient and exponent1,2.
5541 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5542 negative error value.
5545 @subheading gnutls_x509_privkey_generate
5546 @anchor{gnutls_x509_privkey_generate}
5547 @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})
5550 @var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .
5552 @var{bits}: the size of the modulus
5554 @var{flags}: unused for now. Must be 0.
5556 This function will generate a random private key. Note that this
5557 function must be called on an empty private key.
5559 Note that when generating an elliptic curve key, the curve
5560 can be substituted in the place of the bits parameter using the
5561 @code{GNUTLS_CURVE_TO_BITS()} macro.
5563 For DSA keys, if the subgroup size needs to be specified check
5564 the @code{GNUTLS_SUBGROUP_TO_BITS()} macro.
5566 Do not set the number of bits directly, use @code{gnutls_sec_param_to_pk_bits()} .
5568 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5569 negative error value.
5572 @subheading gnutls_x509_privkey_get_key_id
5573 @anchor{gnutls_x509_privkey_get_key_id}
5574 @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})
5577 @var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t}
5579 @var{output_data}: will contain the key ID
5581 @var{output_data_size}: holds the size of output_data (and will be
5582 replaced by the actual size of parameters)
5584 This function will return a unique ID that depends on the public key
5585 parameters. This ID can be used in checking whether a certificate
5586 corresponds to the given key.
5588 If the buffer provided is not long enough to hold the output, then
5589 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
5590 be returned. The output will normally be a SHA-1 hash output,
5593 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5594 negative error value.
5597 @subheading gnutls_x509_privkey_get_pk_algorithm
5598 @anchor{gnutls_x509_privkey_get_pk_algorithm}
5599 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key})
5600 @var{key}: should contain a @code{gnutls_x509_privkey_t} type
5602 This function will return the public key algorithm of a private
5605 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5606 success, or a negative error code on error.
5609 @subheading gnutls_x509_privkey_get_pk_algorithm2
5610 @anchor{gnutls_x509_privkey_get_pk_algorithm2}
5611 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm2} (gnutls_x509_privkey_t @var{key}, unsigned int * @var{bits})
5612 @var{key}: should contain a @code{gnutls_x509_privkey_t} type
5614 @var{bits}: The number of bits in the public key algorithm
5616 This function will return the public key algorithm of a private
5619 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5620 success, or a negative error code on error.
5623 @subheading gnutls_x509_privkey_import
5624 @anchor{gnutls_x509_privkey_import}
5625 @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})
5626 @var{key}: The data to store the parsed key
5628 @var{data}: The DER or PEM encoded certificate.
5630 @var{format}: One of DER or PEM
5632 This function will convert the given DER or PEM encoded key to the
5633 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5636 If the key is PEM encoded it should have a header that contains "PRIVATE
5637 KEY". Note that this function falls back to PKCS @code{8} decoding without
5638 password, if the default format fails to import.
5640 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5641 negative error value.
5644 @subheading gnutls_x509_privkey_import2
5645 @anchor{gnutls_x509_privkey_import2}
5646 @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})
5647 @var{key}: The data to store the parsed key
5649 @var{data}: The DER or PEM encoded key.
5651 @var{format}: One of DER or PEM
5653 @var{password}: A password (optional)
5655 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5657 This function will import the given DER or PEM encoded key, to
5658 the native @code{gnutls_x509_privkey_t} format, irrespective of the
5659 input format. The input format is auto-detected.
5661 The supported formats are basic unencrypted key, PKCS8, PKCS12,
5662 and the openssl format.
5664 If the provided key is encrypted but no password was given, then
5665 @code{GNUTLS_E_DECRYPTION_FAILED} is returned. Since GnuTLS 3.4.0 this
5666 function will utilize the PIN callbacks if any.
5668 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5669 negative error value.
5672 @subheading gnutls_x509_privkey_import_dsa_raw
5673 @anchor{gnutls_x509_privkey_import_dsa_raw}
5674 @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})
5675 @var{key}: The data to store the parsed key
5677 @var{p}: holds the p
5679 @var{q}: holds the q
5681 @var{g}: holds the g
5683 @var{y}: holds the y
5685 @var{x}: holds the x
5687 This function will convert the given DSA raw parameters to the
5688 native @code{gnutls_x509_privkey_t} format. The output will be stored
5691 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5692 negative error value.
5695 @subheading gnutls_x509_privkey_import_ecc_raw
5696 @anchor{gnutls_x509_privkey_import_ecc_raw}
5697 @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})
5698 @var{key}: The data to store the parsed key
5700 @var{curve}: holds the curve
5702 @var{x}: holds the x
5704 @var{y}: holds the y
5706 @var{k}: holds the k
5708 This function will convert the given elliptic curve parameters to the
5709 native @code{gnutls_x509_privkey_t} format. The output will be stored
5712 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5713 negative error value.
5718 @subheading gnutls_x509_privkey_import_openssl
5719 @anchor{gnutls_x509_privkey_import_openssl}
5720 @deftypefun {int} {gnutls_x509_privkey_import_openssl} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, const char * @var{password})
5721 @var{key}: The data to store the parsed key
5723 @var{data}: The DER or PEM encoded key.
5725 @var{password}: the password to decrypt the key (if it is encrypted).
5727 This function will convert the given PEM encrypted to
5728 the native gnutls_x509_privkey_t format. The
5729 output will be stored in @code{key} .
5731 The @code{password} should be in ASCII. If the password is not provided
5732 or wrong then @code{GNUTLS_E_DECRYPTION_FAILED} will be returned.
5734 If the Certificate is PEM encoded it should have a header of
5735 "PRIVATE KEY" and the "DEK-Info" header.
5737 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5738 negative error value.
5741 @subheading gnutls_x509_privkey_import_pkcs8
5742 @anchor{gnutls_x509_privkey_import_pkcs8}
5743 @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})
5744 @var{key}: The data to store the parsed key
5746 @var{data}: The DER or PEM encoded key.
5748 @var{format}: One of DER or PEM
5750 @var{password}: the password to decrypt the key (if it is encrypted).
5752 @var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
5754 This function will convert the given DER or PEM encoded PKCS8 2.0
5755 encrypted key to the native gnutls_x509_privkey_t format. The
5756 output will be stored in @code{key} . Both RSA and DSA keys can be
5757 imported, and flags can only be used to indicate an unencrypted
5760 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5761 encryption schemas, or ASCII for the PKCS12 schemas.
5763 If the Certificate is PEM encoded it should have a header of
5764 "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to
5765 specify the flags if the key is DER encoded, since in that case
5766 the encryption status cannot be auto-detected.
5768 If the @code{GNUTLS_PKCS_PLAIN} flag is specified and the supplied data
5769 are encrypted then @code{GNUTLS_E_DECRYPTION_FAILED} is returned.
5771 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5772 negative error value.
5775 @subheading gnutls_x509_privkey_import_rsa_raw
5776 @anchor{gnutls_x509_privkey_import_rsa_raw}
5777 @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})
5778 @var{key}: The data to store the parsed key
5780 @var{m}: holds the modulus
5782 @var{e}: holds the public exponent
5784 @var{d}: holds the private exponent
5786 @var{p}: holds the first prime (p)
5788 @var{q}: holds the second prime (q)
5790 @var{u}: holds the coefficient
5792 This function will convert the given RSA raw parameters to the
5793 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5796 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5797 negative error value.
5800 @subheading gnutls_x509_privkey_import_rsa_raw2
5801 @anchor{gnutls_x509_privkey_import_rsa_raw2}
5802 @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})
5803 @var{key}: The data to store the parsed key
5805 @var{m}: holds the modulus
5807 @var{e}: holds the public exponent
5809 @var{d}: holds the private exponent
5811 @var{p}: holds the first prime (p)
5813 @var{q}: holds the second prime (q)
5815 @var{u}: holds the coefficient (optional)
5817 @var{e1}: holds e1 = d mod (p-1) (optional)
5819 @var{e2}: holds e2 = d mod (q-1) (optional)
5821 This function will convert the given RSA raw parameters to the
5822 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5825 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5826 negative error value.
5829 @subheading gnutls_x509_privkey_init
5830 @anchor{gnutls_x509_privkey_init}
5831 @deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key})
5832 @var{key}: A pointer to the type to be initialized
5834 This function will initialize a private key type.
5836 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5837 negative error value.
5840 @subheading gnutls_x509_privkey_sec_param
5841 @anchor{gnutls_x509_privkey_sec_param}
5842 @deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key})
5845 This function will return the security parameter appropriate with
5848 @strong{Returns:} On success, a valid security parameter is returned otherwise
5849 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
5851 @strong{Since:} 2.12.0
5854 @subheading gnutls_x509_privkey_set_pin_function
5855 @anchor{gnutls_x509_privkey_set_pin_function}
5856 @deftypefun {void} {gnutls_x509_privkey_set_pin_function} (gnutls_x509_privkey_t @var{privkey}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
5857 @var{privkey}: The certificate structure
5859 @var{fn}: the callback
5861 @var{userdata}: data associated with the callback
5863 This function will set a callback function to be used when
5864 it is required to access a protected object. This function overrides
5865 the global function set using @code{gnutls_pkcs11_set_pin_function()} .
5867 Note that this callback is used when decrypting a key.
5869 @strong{Since:} 3.4.0
5872 @subheading gnutls_x509_privkey_sign_data
5873 @anchor{gnutls_x509_privkey_sign_data}
5874 @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})
5877 @var{digest}: should be MD5 or SHA1
5879 @var{flags}: should be 0 for now
5881 @var{data}: holds the data to be signed
5883 @var{signature}: will contain the signature
5885 @var{signature_size}: holds the size of signature (and will be replaced
5888 This function will sign the given data using a signature algorithm
5889 supported by the private key. Signature algorithms are always used
5890 together with a hash functions. Different hash functions may be
5891 used for the RSA algorithm, but only SHA-1 for the DSA keys.
5893 If the buffer provided is not long enough to hold the output, then
5894 * @code{signature_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
5897 Use @code{gnutls_x509_crt_get_preferred_hash_algorithm()} to determine
5900 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5901 negative error value.
5904 @subheading gnutls_x509_privkey_verify_params
5905 @anchor{gnutls_x509_privkey_verify_params}
5906 @deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key})
5909 This function will verify the private key parameters.
5911 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5912 negative error value.
5915 @subheading gnutls_x509_rdn_get
5916 @anchor{gnutls_x509_rdn_get}
5917 @deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{buf_size})
5918 @var{idn}: should contain a DER encoded RDN sequence
5920 @var{buf}: a pointer to a structure to hold the peer's name
5922 @var{buf_size}: holds the size of @code{buf}
5924 This function will return the name of the given RDN sequence. The
5925 name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
5928 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5929 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5930 updated if the provided buffer is not long enough, otherwise a
5931 negative error value.
5934 @subheading gnutls_x509_rdn_get_by_oid
5935 @anchor{gnutls_x509_rdn_get_by_oid}
5936 @deftypefun {int} {gnutls_x509_rdn_get_by_oid} (const gnutls_datum_t * @var{idn}, const char * @var{oid}, int @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size})
5937 @var{idn}: should contain a DER encoded RDN sequence
5939 @var{oid}: an Object Identifier
5941 @var{indx}: In case multiple same OIDs exist in the RDN indicates which
5942 to send. Use 0 for the first one.
5944 @var{raw_flag}: If non-zero then the raw DER data are returned.
5946 @var{buf}: a pointer to a structure to hold the peer's name
5948 @var{buf_size}: holds the size of @code{buf}
5950 This function will return the name of the given Object identifier,
5951 of the RDN sequence. The name will be encoded using the rules
5954 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5955 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5956 updated if the provided buffer is not long enough, otherwise a
5957 negative error value.
5960 @subheading gnutls_x509_rdn_get_oid
5961 @anchor{gnutls_x509_rdn_get_oid}
5962 @deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size})
5963 @var{idn}: should contain a DER encoded RDN sequence
5965 @var{indx}: Indicates which OID to return. Use 0 for the first one.
5967 @var{buf}: a pointer to a structure to hold the peer's name OID
5969 @var{buf_size}: holds the size of @code{buf}
5971 This function will return the specified Object identifier, of the
5974 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5975 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5976 updated if the provided buffer is not long enough, otherwise a
5977 negative error value.
5979 @strong{Since:} 2.4.0
5982 @subheading gnutls_x509_trust_list_add_cas
5983 @anchor{gnutls_x509_trust_list_add_cas}
5984 @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})
5985 @var{list}: The list
5987 @var{clist}: A list of CAs
5989 @var{clist_size}: The length of the CA list
5991 @var{flags}: should be 0 or an or'ed sequence of @code{GNUTLS_TL} options.
5993 This function will add the given certificate authorities
5994 to the trusted list. The list of CAs must not be deinitialized
5995 during this structure's lifetime.
5997 If the flag @code{GNUTLS_TL_NO_DUPLICATES} is specified, then
5998 the provided @code{clist} entries that are duplicates will not be
5999 added to the list and will be deinitialized.
6001 @strong{Returns:} The number of added elements is returned.
6003 @strong{Since:} 3.0.0
6006 @subheading gnutls_x509_trust_list_add_crls
6007 @anchor{gnutls_x509_trust_list_add_crls}
6008 @deftypefun {int} {gnutls_x509_trust_list_add_crls} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crl_t * @var{crl_list}, int @var{crl_size}, unsigned int @var{flags}, unsigned int @var{verification_flags})
6009 @var{list}: The list
6011 @var{crl_list}: A list of CRLs
6013 @var{crl_size}: The length of the CRL list
6015 @var{flags}: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
6017 @var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6019 This function will add the given certificate revocation lists
6020 to the trusted list. The list of CRLs must not be deinitialized
6021 during this structure's lifetime.
6023 This function must be called after @code{gnutls_x509_trust_list_add_cas()}
6024 to allow verifying the CRLs for validity. If the flag @code{GNUTLS_TL_NO_DUPLICATES}
6025 is given, then any provided CRLs that are a duplicate, will be deinitialized
6026 and not added to the list (that assumes that @code{gnutls_x509_trust_list_deinit()}
6027 will be called with all=1).
6029 @strong{Returns:} The number of added elements is returned.
6034 @subheading gnutls_x509_trust_list_add_named_crt
6035 @anchor{gnutls_x509_trust_list_add_named_crt}
6036 @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})
6037 @var{list}: The list
6039 @var{cert}: A certificate
6041 @var{name}: An identifier for the certificate
6043 @var{name_size}: The size of the identifier
6045 @var{flags}: should be 0.
6047 This function will add the given certificate to the trusted
6048 list and associate it with a name. The certificate will not be
6049 be used for verification with @code{gnutls_x509_trust_list_verify_crt()}
6050 but with @code{gnutls_x509_trust_list_verify_named_crt()} or
6051 @code{gnutls_x509_trust_list_verify_crt2()} - the latter only since
6052 GnuTLS 3.4.0 and if a hostname is provided.
6054 In principle this function can be used to set individual "server"
6055 certificates that are trusted by the user for that specific server
6056 but for no other purposes.
6058 The certificate must not be deinitialized during the lifetime
6059 of the trusted list.
6061 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6062 negative error value.
6064 @strong{Since:} 3.0.0
6067 @subheading gnutls_x509_trust_list_add_system_trust
6068 @anchor{gnutls_x509_trust_list_add_system_trust}
6069 @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})
6070 @var{list}: The structure of the list
6072 @var{tl_flags}: GNUTLS_TL_*
6074 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6076 This function adds the system's default trusted certificate
6077 authorities to the trusted list. Note that on unsupported systems
6078 this function returns @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .
6080 This function implies the flag @code{GNUTLS_TL_NO_DUPLICATES} .
6082 @strong{Returns:} The number of added elements or a negative error code on error.
6087 @subheading gnutls_x509_trust_list_add_trust_dir
6088 @anchor{gnutls_x509_trust_list_add_trust_dir}
6089 @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})
6090 @var{list}: The list
6092 @var{ca_dir}: A directory containing the CAs (optional)
6094 @var{crl_dir}: A directory containing a list of CRLs (optional)
6096 @var{type}: The format of the certificates
6098 @var{tl_flags}: GNUTLS_TL_*
6100 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6102 This function will add the given certificate authorities
6103 to the trusted list. Only directories are accepted by
6106 @strong{Returns:} The number of added elements is returned.
6108 @strong{Since:} 3.3.6
6111 @subheading gnutls_x509_trust_list_add_trust_file
6112 @anchor{gnutls_x509_trust_list_add_trust_file}
6113 @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})
6114 @var{list}: The list
6116 @var{ca_file}: A file containing a list of CAs (optional)
6118 @var{crl_file}: A file containing a list of CRLs (optional)
6120 @var{type}: The format of the certificates
6122 @var{tl_flags}: GNUTLS_TL_*
6124 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6126 This function will add the given certificate authorities
6127 to the trusted list. PKCS @code{11} URLs are also accepted, instead
6128 of files, by this function. A PKCS @code{11} URL implies a trust
6129 database (a specially marked module in p11-kit); the URL "pkcs11:"
6130 implies all trust databases in the system. Only a single URL specifying
6131 trust databases can be set; they cannot be stacked with multiple calls.
6133 @strong{Returns:} The number of added elements is returned.
6138 @subheading gnutls_x509_trust_list_add_trust_mem
6139 @anchor{gnutls_x509_trust_list_add_trust_mem}
6140 @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})
6141 @var{list}: The list
6143 @var{cas}: A buffer containing a list of CAs (optional)
6145 @var{crls}: A buffer containing a list of CRLs (optional)
6147 @var{type}: The format of the certificates
6149 @var{tl_flags}: GNUTLS_TL_*
6151 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6153 This function will add the given certificate authorities
6154 to the trusted list.
6156 @strong{Returns:} The number of added elements is returned.
6161 @subheading gnutls_x509_trust_list_deinit
6162 @anchor{gnutls_x509_trust_list_deinit}
6163 @deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all})
6164 @var{list}: The list to be deinitialized
6166 @var{all}: if non-zero it will deinitialize all the certificates and CRLs contained in the structure.
6168 This function will deinitialize a trust list. Note that the
6169 @code{all} flag should be typically non-zero unless you have specified
6170 your certificates using @code{gnutls_x509_trust_list_add_cas()} and you
6171 want to prevent them from being deinitialized by this function.
6173 @strong{Since:} 3.0.0
6176 @subheading gnutls_x509_trust_list_get_issuer
6177 @anchor{gnutls_x509_trust_list_get_issuer}
6178 @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})
6179 @var{list}: The list
6181 @var{cert}: is the certificate to find issuer for
6183 @var{issuer}: Will hold the issuer if any. Should be treated as constant.
6185 @var{flags}: Use zero or @code{GNUTLS_TL_GET_COPY}
6187 This function will find the issuer of the given certificate.
6188 If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer
6189 will be returned which must be freed using @code{gnutls_x509_crt_deinit()} .
6190 Note that the flag @code{GNUTLS_TL_GET_COPY} is required for this function
6191 to work with PKCS @code{11} trust lists in a thread-safe way.
6193 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6194 negative error value.
6199 @subheading gnutls_x509_trust_list_get_issuer_by_dn
6200 @anchor{gnutls_x509_trust_list_get_issuer_by_dn}
6201 @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})
6202 @var{list}: The list
6204 @var{dn}: is the issuer's DN
6206 @var{issuer}: Will hold the issuer if any. Should be deallocated after use.
6208 @var{flags}: Use zero
6210 This function will find the issuer with the given name, and
6211 return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} .
6213 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6214 negative error value.
6216 @strong{Since:} 3.4.0
6219 @subheading gnutls_x509_trust_list_get_issuer_by_subject_key_id
6220 @anchor{gnutls_x509_trust_list_get_issuer_by_subject_key_id}
6221 @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})
6222 @var{list}: The list
6224 @var{dn}: is the issuer's DN (may be @code{NULL} )
6226 @var{spki}: is the subject key ID
6228 @var{issuer}: Will hold the issuer if any. Should be deallocated after use.
6230 @var{flags}: Use zero
6232 This function will find the issuer with the given name and subject key ID, and
6233 return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} .
6235 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6236 negative error value.
6238 @strong{Since:} 3.4.2
6241 @subheading gnutls_x509_trust_list_init
6242 @anchor{gnutls_x509_trust_list_init}
6243 @deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size})
6244 @var{list}: A pointer to the type to be initialized
6246 @var{size}: The size of the internal hash table. Use (0) for default size.
6248 This function will initialize an X.509 trust list structure.
6250 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6251 negative error value.
6253 @strong{Since:} 3.0.0
6256 @subheading gnutls_x509_trust_list_iter_deinit
6257 @anchor{gnutls_x509_trust_list_iter_deinit}
6258 @deftypefun {void} {gnutls_x509_trust_list_iter_deinit} (gnutls_x509_trust_list_iter_t @var{iter})
6259 @var{iter}: The iterator structure to be deinitialized
6261 This function will deinitialize an iterator structure.
6263 @strong{Since:} 3.4.0
6266 @subheading gnutls_x509_trust_list_iter_get_ca
6267 @anchor{gnutls_x509_trust_list_iter_get_ca}
6268 @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})
6269 @var{list}: The list
6271 @var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} )
6273 @var{crt}: where the certificate will be copied
6275 This function obtains a certificate in the trust list and advances the
6276 iterator to the next certificate. The certificate returned in @code{crt} must be
6277 deallocated with @code{gnutls_x509_crt_deinit()} .
6279 When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
6280 is returned and the iterator is reset.
6282 After use, the iterator must be deinitialized usin
6283 @code{gnutls_x509_trust_list_iter_deinit()} .
6285 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6286 negative error value.
6288 @strong{Since:} 3.4.0
6291 @subheading gnutls_x509_trust_list_remove_cas
6292 @anchor{gnutls_x509_trust_list_remove_cas}
6293 @deftypefun {int} {gnutls_x509_trust_list_remove_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, int @var{clist_size})
6294 @var{list}: The list
6296 @var{clist}: A list of CAs
6298 @var{clist_size}: The length of the CA list
6300 This function will remove the given certificate authorities
6301 from the trusted list.
6303 Note that this function can accept certificates and authorities
6304 not yet known. In that case they will be kept in a separate
6305 black list that will be used during certificate verification.
6306 Unlike @code{gnutls_x509_trust_list_add_cas()} there is no deinitialization
6307 restriction for certificate list provided in this function.
6309 @strong{Returns:} The number of removed elements is returned.
6311 @strong{Since:} 3.1.10
6314 @subheading gnutls_x509_trust_list_remove_trust_file
6315 @anchor{gnutls_x509_trust_list_remove_trust_file}
6316 @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})
6317 @var{list}: The list
6319 @var{ca_file}: A file containing a list of CAs
6321 @var{type}: The format of the certificates
6323 This function will remove the given certificate authorities
6324 from the trusted list, and add them into a black list when needed.
6325 PKCS 11 URLs are also accepted, instead
6326 of files, by this function.
6328 See also @code{gnutls_x509_trust_list_remove_cas()} .
6330 @strong{Returns:} The number of added elements is returned.
6332 @strong{Since:} 3.1.10
6335 @subheading gnutls_x509_trust_list_remove_trust_mem
6336 @anchor{gnutls_x509_trust_list_remove_trust_mem}
6337 @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})
6338 @var{list}: The list
6340 @var{cas}: A buffer containing a list of CAs (optional)
6342 @var{type}: The format of the certificates
6344 This function will remove the provided certificate authorities
6345 from the trusted list, and add them into a black list when needed.
6347 See also @code{gnutls_x509_trust_list_remove_cas()} .
6349 @strong{Returns:} The number of removed elements is returned.
6351 @strong{Since:} 3.1.10
6354 @subheading gnutls_x509_trust_list_verify_crt
6355 @anchor{gnutls_x509_trust_list_verify_crt}
6356 @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})
6357 @var{list}: The list
6359 @var{cert_list}: is the certificate list to be verified
6361 @var{cert_list_size}: is the certificate list size
6363 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6365 @var{voutput}: will hold the certificate verification output.
6367 @var{func}: If non-null will be called on each chain element verification with the output.
6369 This function will try to verify the given certificate and return
6370 its status. The @code{voutput} parameter will hold an OR'ed sequence of
6371 @code{gnutls_certificate_status_t} flags.
6373 The details of the verification are the same as in @code{gnutls_x509_trust_list_verify_crt2()} .
6375 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6376 negative error value.
6381 @subheading gnutls_x509_trust_list_verify_crt2
6382 @anchor{gnutls_x509_trust_list_verify_crt2}
6383 @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})
6384 @var{list}: The list
6386 @var{cert_list}: is the certificate list to be verified
6388 @var{cert_list_size}: is the certificate list size
6390 @var{data}: an array of typed data
6392 @var{elements}: the number of data elements
6394 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6396 @var{voutput}: will hold the certificate verification output.
6398 @var{func}: If non-null will be called on each chain element verification with the output.
6400 This function will attempt to verify the given certificate and return
6401 its status. The @code{voutput} parameter will hold an OR'ed sequence of
6402 @code{gnutls_certificate_status_t} flags. When a chain of @code{cert_list_size} with
6403 more than one certificates is provided, the verification status will apply
6404 to the first certificate in the chain that failed verification. The
6405 verification process starts from the end of the chain (from CA to end
6408 Additionally a certificate verification profile can be specified
6409 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6410 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6413 The acceptable @code{data} types are @code{GNUTLS_DT_DNS_HOSTNAME} and @code{GNUTLS_DT_KEY_PURPOSE_OID} .
6414 The former accepts as data a null-terminated hostname, and the latter a null-terminated
6415 object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ).
6416 If a DNS hostname is provided then this function will compare
6417 the hostname in the certificate against the given. If names do not match the
6418 @code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. In addition it
6419 will consider certificates provided with @code{gnutls_x509_trust_list_add_named_crt()} .
6421 If a key purpose OID is provided and the end-certificate contains the extended key
6422 usage PKIX extension, it will be required to match the provided OID
6423 or be marked for any purpose, otherwise verification will fail with
6424 @code{GNUTLS_CERT_PURPOSE_MISMATCH} status.
6426 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6427 negative error value. Note that verification failure will not result to an
6428 error code, only @code{voutput} will be updated.
6430 @strong{Since:} 3.3.8
6433 @subheading gnutls_x509_trust_list_verify_named_crt
6434 @anchor{gnutls_x509_trust_list_verify_named_crt}
6435 @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})
6436 @var{list}: The list
6438 @var{cert}: is the certificate to be verified
6440 @var{name}: is the certificate's name
6442 @var{name_size}: is the certificate's name size
6444 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6446 @var{voutput}: will hold the certificate verification output.
6448 @var{func}: If non-null will be called on each chain element verification with the output.
6450 This function will try to find a certificate that is associated with the provided
6451 name --see @code{gnutls_x509_trust_list_add_named_crt()} . If a match is found the
6452 certificate is considered valid. In addition to that this function will also
6453 check CRLs. The @code{voutput} parameter will hold an OR'ed sequence of
6454 @code{gnutls_certificate_status_t} flags.
6456 Additionally a certificate verification profile can be specified
6457 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6458 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6461 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6462 negative error value.
6464 @strong{Since:} 3.0.0