2 @subheading gnutls_certificate_set_trust_list
3 @anchor{gnutls_certificate_set_trust_list}
4 @deftypefun {void} {gnutls_certificate_set_trust_list} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_trust_list_t @var{tlist}, unsigned @var{flags})
5 @var{res}: is a @code{gnutls_certificate_credentials_t} structure.
7 @var{tlist}: is a @code{gnutls_x509_trust_list_t} structure
9 @var{flags}: must be zero
11 This function sets a trust list in the gnutls_certificate_credentials_t structure.
13 Note that the @code{tlist} will become part of the credentials
14 structure and must not be deallocated. It will be automatically deallocated
15 when the @code{res} structure is deinitialized.
17 @strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code.
22 @subheading gnutls_pkcs7_deinit
23 @anchor{gnutls_pkcs7_deinit}
24 @deftypefun {void} {gnutls_pkcs7_deinit} (gnutls_pkcs7_t @var{pkcs7})
25 @var{pkcs7}: The structure to be initialized
27 This function will deinitialize a PKCS7 structure.
30 @subheading gnutls_pkcs7_delete_crl
31 @anchor{gnutls_pkcs7_delete_crl}
32 @deftypefun {int} {gnutls_pkcs7_delete_crl} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
33 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
35 @var{indx}: the index of the crl to delete
37 This function will delete a crl from a PKCS7 or RFC2630 crl set.
38 Index starts from 0. Returns 0 on success.
40 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
44 @subheading gnutls_pkcs7_delete_crt
45 @anchor{gnutls_pkcs7_delete_crt}
46 @deftypefun {int} {gnutls_pkcs7_delete_crt} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
47 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
49 @var{indx}: the index of the certificate to delete
51 This function will delete a certificate from a PKCS7 or RFC2630
52 certificate set. Index starts from 0. Returns 0 on success.
54 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
58 @subheading gnutls_pkcs7_export
59 @anchor{gnutls_pkcs7_export}
60 @deftypefun {int} {gnutls_pkcs7_export} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
61 @var{pkcs7}: Holds the pkcs7 structure
63 @var{format}: the format of output params. One of PEM or DER.
65 @var{output_data}: will contain a structure PEM or DER encoded
67 @var{output_data_size}: holds the size of output_data (and will be
68 replaced by the actual size of parameters)
70 This function will export the pkcs7 structure to DER or PEM format.
72 If the buffer provided is not long enough to hold the output, then
73 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
76 If the structure is PEM encoded, it will have a header
79 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
83 @subheading gnutls_pkcs7_export2
84 @anchor{gnutls_pkcs7_export2}
85 @deftypefun {int} {gnutls_pkcs7_export2} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
86 @var{pkcs7}: Holds the pkcs7 structure
88 @var{format}: the format of output params. One of PEM or DER.
90 @var{out}: will contain a structure PEM or DER encoded
92 This function will export the pkcs7 structure to DER or PEM format.
94 The output buffer is allocated using @code{gnutls_malloc()} .
96 If the structure is PEM encoded, it will have a header
99 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
100 negative error value.
102 @strong{Since:} 3.1.3
105 @subheading gnutls_pkcs7_get_crl_count
106 @anchor{gnutls_pkcs7_get_crl_count}
107 @deftypefun {int} {gnutls_pkcs7_get_crl_count} (gnutls_pkcs7_t @var{pkcs7})
108 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
110 This function will return the number of certifcates in the PKCS7
113 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
114 negative error value.
117 @subheading gnutls_pkcs7_get_crl_raw
118 @anchor{gnutls_pkcs7_get_crl_raw}
119 @deftypefun {int} {gnutls_pkcs7_get_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{crl}, size_t * @var{crl_size})
120 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
122 @var{indx}: contains the index of the crl to extract
124 @var{crl}: the contents of the crl will be copied there (may be null)
126 @var{crl_size}: should hold the size of the crl
128 This function will return a crl of the PKCS7 or RFC2630 crl set.
130 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
131 negative error value. If the provided buffer is not long enough,
132 then @code{crl_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is
133 returned. After the last crl has been read
134 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
137 @subheading gnutls_pkcs7_get_crt_count
138 @anchor{gnutls_pkcs7_get_crt_count}
139 @deftypefun {int} {gnutls_pkcs7_get_crt_count} (gnutls_pkcs7_t @var{pkcs7})
140 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
142 This function will return the number of certifcates in the PKCS7
143 or RFC2630 certificate set.
145 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
146 negative error value.
149 @subheading gnutls_pkcs7_get_crt_raw
150 @anchor{gnutls_pkcs7_get_crt_raw}
151 @deftypefun {int} {gnutls_pkcs7_get_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{certificate}, size_t * @var{certificate_size})
152 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
154 @var{indx}: contains the index of the certificate to extract
156 @var{certificate}: the contents of the certificate will be copied
159 @var{certificate_size}: should hold the size of the certificate
161 This function will return a certificate of the PKCS7 or RFC2630
164 After the last certificate has been read
165 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
167 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
168 negative error value. If the provided buffer is not long enough,
169 then @code{certificate_size} is updated and
170 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned.
173 @subheading gnutls_pkcs7_import
174 @anchor{gnutls_pkcs7_import}
175 @deftypefun {int} {gnutls_pkcs7_import} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
176 @var{pkcs7}: The structure to store the parsed PKCS7.
178 @var{data}: The DER or PEM encoded PKCS7.
180 @var{format}: One of DER or PEM
182 This function will convert the given DER or PEM encoded PKCS7 to
183 the native @code{gnutls_pkcs7_t} format. The output will be stored in
186 If the PKCS7 is PEM encoded it should have a header of "PKCS7".
188 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
189 negative error value.
192 @subheading gnutls_pkcs7_init
193 @anchor{gnutls_pkcs7_init}
194 @deftypefun {int} {gnutls_pkcs7_init} (gnutls_pkcs7_t * @var{pkcs7})
195 @var{pkcs7}: The structure to be initialized
197 This function will initialize a PKCS7 structure. PKCS7 structures
198 usually contain lists of X.509 Certificates and X.509 Certificate
201 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
202 negative error value.
205 @subheading gnutls_pkcs7_set_crl
206 @anchor{gnutls_pkcs7_set_crl}
207 @deftypefun {int} {gnutls_pkcs7_set_crl} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crl_t @var{crl})
208 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
210 @var{crl}: the DER encoded crl to be added
212 This function will add a parsed CRL to the PKCS7 or RFC2630 crl
215 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
216 negative error value.
219 @subheading gnutls_pkcs7_set_crl_raw
220 @anchor{gnutls_pkcs7_set_crl_raw}
221 @deftypefun {int} {gnutls_pkcs7_set_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crl})
222 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
224 @var{crl}: the DER encoded crl to be added
226 This function will add a crl to the PKCS7 or RFC2630 crl set.
228 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
229 negative error value.
232 @subheading gnutls_pkcs7_set_crt
233 @anchor{gnutls_pkcs7_set_crt}
234 @deftypefun {int} {gnutls_pkcs7_set_crt} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crt_t @var{crt})
235 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
237 @var{crt}: the certificate to be copied.
239 This function will add a parsed certificate to the PKCS7 or
240 RFC2630 certificate set. This is a wrapper function over
241 @code{gnutls_pkcs7_set_crt_raw()} .
243 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
244 negative error value.
247 @subheading gnutls_pkcs7_set_crt_raw
248 @anchor{gnutls_pkcs7_set_crt_raw}
249 @deftypefun {int} {gnutls_pkcs7_set_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crt})
250 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
252 @var{crt}: the DER encoded certificate to be added
254 This function will add a certificate to the PKCS7 or RFC2630
257 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
258 negative error value.
261 @subheading gnutls_subject_alt_names_deinit
262 @anchor{gnutls_subject_alt_names_deinit}
263 @deftypefun {void} {gnutls_subject_alt_names_deinit} (gnutls_subject_alt_names_t @var{sans})
264 @var{sans}: The alternative names structure
266 This function will deinitialize an alternative names structure.
268 @strong{Since:} 3.3.0
271 @subheading gnutls_subject_alt_names_get
272 @anchor{gnutls_subject_alt_names_get}
273 @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})
274 @var{sans}: The alternative names structure
276 @var{seq}: The index of the name to get
278 @var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} )
280 @var{san}: The alternative name data (should be treated as constant)
282 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} (should be treated as constant)
284 This function will return a specific alternative name as stored in
285 the @code{sans} structure. The returned values should be treated as constant
286 and valid for the lifetime of @code{sans} .
288 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
289 if the index is out of bounds, otherwise a negative error value.
291 @strong{Since:} 3.3.0
294 @subheading gnutls_subject_alt_names_init
295 @anchor{gnutls_subject_alt_names_init}
296 @deftypefun {int} {gnutls_subject_alt_names_init} (gnutls_subject_alt_names_t * @var{sans})
297 @var{sans}: The alternative names structure
299 This function will initialize an alternative names structure.
301 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
303 @strong{Since:} 3.3.0
306 @subheading gnutls_subject_alt_names_set
307 @anchor{gnutls_subject_alt_names_set}
308 @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})
309 @var{sans}: The alternative names structure
311 @var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
313 @var{san}: The alternative name data
315 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
317 This function will store the specified alternative name in
318 the @code{sans} structure.
320 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
322 @strong{Since:} 3.3.0
325 @subheading gnutls_x509_aia_deinit
326 @anchor{gnutls_x509_aia_deinit}
327 @deftypefun {void} {gnutls_x509_aia_deinit} (gnutls_x509_aia_t @var{aia})
328 @var{aia}: The authority info access structure
330 This function will deinitialize a CRL distribution points structure.
332 @strong{Since:} 3.3.0
335 @subheading gnutls_x509_aia_get
336 @anchor{gnutls_x509_aia_get}
337 @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})
338 @var{aia}: The authority info access structure
340 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
342 @var{oid}: the type of available data; to be treated as constant.
344 @var{san_type}: Will hold the type of the name of @code{gnutls_subject_alt_names_t} (may be null).
346 @var{san}: the access location name; to be treated as constant (may be null).
348 This function reads from the Authority Information Access structure.
350 The @code{seq} input parameter is used to indicate which member of the
351 sequence the caller is interested in. The first member is 0, the
352 second member 1 and so on. When the @code{seq} value is out of bounds,
353 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
355 Typically @code{oid} is @code{GNUTLS_OID_AD_CAISSUERS} or @code{GNUTLS_OID_AD_OCSP} .
357 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
359 @strong{Since:} 3.3.0
362 @subheading gnutls_x509_aia_init
363 @anchor{gnutls_x509_aia_init}
364 @deftypefun {int} {gnutls_x509_aia_init} (gnutls_x509_aia_t * @var{aia})
365 @var{aia}: The authority info access structure
367 This function will initialize a CRL distribution points structure.
369 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
371 @strong{Since:} 3.3.0
374 @subheading gnutls_x509_aia_set
375 @anchor{gnutls_x509_aia_set}
376 @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})
377 @var{aia}: The authority info access structure
379 @var{oid}: the type of data.
381 @var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
383 @var{san}: The alternative name data
385 This function will store the specified alternative name in
386 the @code{aia} structure.
388 Typically the value for @code{oid} should be @code{GNUTLS_OID_AD_OCSP} , or
389 @code{GNUTLS_OID_AD_CAISSUERS} .
391 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
393 @strong{Since:} 3.3.0
396 @subheading gnutls_x509_aki_deinit
397 @anchor{gnutls_x509_aki_deinit}
398 @deftypefun {void} {gnutls_x509_aki_deinit} (gnutls_x509_aki_t @var{aki})
399 @var{aki}: The authority key identifier structure
401 This function will deinitialize an authority key identifier structure.
403 @strong{Since:} 3.3.0
406 @subheading gnutls_x509_aki_get_cert_issuer
407 @anchor{gnutls_x509_aki_get_cert_issuer}
408 @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})
409 @var{aki}: The authority key ID structure
411 @var{seq}: The index of the name to get
413 @var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null
415 @var{san}: The alternative name data (may be null and should be treated as constant)
417 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} (should be treated as constant)
419 @var{serial}: The authorityCertSerialNumber number (may be null)
421 This function will return a specific authorityCertIssuer name as stored in
422 the @code{aki} structure, as well as the authorityCertSerialNumber.
424 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
425 if the index is out of bounds, otherwise a negative error value.
427 @strong{Since:} 3.3.0
430 @subheading gnutls_x509_aki_get_id
431 @anchor{gnutls_x509_aki_get_id}
432 @deftypefun {int} {gnutls_x509_aki_get_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{id})
433 @var{aki}: The authority key ID structure
435 @var{id}: Will hold the identifier
437 This function will return the key identifier as stored in
438 the @code{aki} structure.
440 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
441 if the index is out of bounds, otherwise a negative error value.
443 @strong{Since:} 3.3.0
446 @subheading gnutls_x509_aki_init
447 @anchor{gnutls_x509_aki_init}
448 @deftypefun {int} {gnutls_x509_aki_init} (gnutls_x509_aki_t * @var{aki})
449 @var{aki}: The authority key ID structure
451 This function will initialize an authority key ID structure.
453 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
455 @strong{Since:} 3.3.0
458 @subheading gnutls_x509_aki_set_cert_issuer
459 @anchor{gnutls_x509_aki_set_cert_issuer}
460 @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})
461 @var{aki}: The authority key ID structure
463 @var{san_type}: the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null
465 @var{san}: The alternative name data
467 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
469 @var{serial}: The authorityCertSerialNumber number (may be null)
471 This function will set the authorityCertIssuer name and the authorityCertSerialNumber
472 to be stored in the @code{aki} structure. When storing multiple names, the serial
473 should be set on the first call, and subsequent calls should use a @code{NULL} serial.
475 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
477 @strong{Since:} 3.3.0
480 @subheading gnutls_x509_aki_set_id
481 @anchor{gnutls_x509_aki_set_id}
482 @deftypefun {int} {gnutls_x509_aki_set_id} (gnutls_x509_aki_t @var{aki}, const gnutls_datum_t * @var{id})
483 @var{aki}: The authority key ID structure
485 @var{id}: the key identifier
487 This function will set the keyIdentifier to be stored in the @code{aki} structure.
489 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
491 @strong{Since:} 3.3.0
494 @subheading gnutls_x509_crl_check_issuer
495 @anchor{gnutls_x509_crl_check_issuer}
496 @deftypefun {int} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer})
497 @var{crl}: is the CRL to be checked
499 @var{issuer}: is the certificate of a possible issuer
501 This function will check if the given CRL was issued by the given
504 @strong{Returns:} true (1) if the given CRL was issued by the given issuer,
505 and false (0) if not.
508 @subheading gnutls_x509_crl_deinit
509 @anchor{gnutls_x509_crl_deinit}
510 @deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl})
511 @var{crl}: The structure to be deinitialized
513 This function will deinitialize a CRL structure.
516 @subheading gnutls_x509_crl_dist_points_deinit
517 @anchor{gnutls_x509_crl_dist_points_deinit}
518 @deftypefun {void} {gnutls_x509_crl_dist_points_deinit} (gnutls_x509_crl_dist_points_t @var{cdp})
519 @var{cdp}: The CRL distribution points structure
521 This function will deinitialize a CRL distribution points structure.
523 @strong{Since:} 3.3.0
526 @subheading gnutls_x509_crl_dist_points_get
527 @anchor{gnutls_x509_crl_dist_points_get}
528 @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})
529 @var{cdp}: The CRL distribution points structure
531 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
533 @var{type}: The name type of the corresponding name (gnutls_x509_subject_alt_name_t)
535 @var{san}: The distribution point names (to be treated as constant)
537 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
539 This function retrieves the individual CRL distribution points (2.5.29.31),
540 contained in provided structure.
542 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
543 if the index is out of bounds, otherwise a negative error value.
546 @subheading gnutls_x509_crl_dist_points_init
547 @anchor{gnutls_x509_crl_dist_points_init}
548 @deftypefun {int} {gnutls_x509_crl_dist_points_init} (gnutls_x509_crl_dist_points_t * @var{cdp})
549 @var{cdp}: The CRL distribution points structure
551 This function will initialize a CRL distribution points structure.
553 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
555 @strong{Since:} 3.3.0
558 @subheading gnutls_x509_crl_dist_points_set
559 @anchor{gnutls_x509_crl_dist_points_set}
560 @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})
561 @var{cdp}: The CRL distribution points structure
563 @var{type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
565 @var{san}: The point name data
567 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
569 This function will store the specified CRL distibution point value
570 the @code{cdp} structure.
572 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
574 @strong{Since:} 3.3.0
577 @subheading gnutls_x509_crl_export
578 @anchor{gnutls_x509_crl_export}
579 @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})
580 @var{crl}: Holds the revocation list
582 @var{format}: the format of output params. One of PEM or DER.
584 @var{output_data}: will contain a private key PEM or DER encoded
586 @var{output_data_size}: holds the size of output_data (and will
587 be replaced by the actual size of parameters)
589 This function will export the revocation list to DER or PEM format.
591 If the buffer provided is not long enough to hold the output, then
592 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
594 If the structure is PEM encoded, it will have a header
597 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
598 negative error value. and a negative error code on failure.
601 @subheading gnutls_x509_crl_export2
602 @anchor{gnutls_x509_crl_export2}
603 @deftypefun {int} {gnutls_x509_crl_export2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
604 @var{crl}: Holds the revocation list
606 @var{format}: the format of output params. One of PEM or DER.
608 @var{out}: will contain a private key PEM or DER encoded
610 This function will export the revocation list to DER or PEM format.
612 The output buffer is allocated using @code{gnutls_malloc()} .
614 If the structure is PEM encoded, it will have a header
617 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
618 negative error value. and a negative error code on failure.
623 @subheading gnutls_x509_crl_get_authority_key_gn_serial
624 @anchor{gnutls_x509_crl_get_authority_key_gn_serial}
625 @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})
626 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
628 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
630 @var{alt}: is the place where the alternative name will be copied to
632 @var{alt_size}: holds the size of alt.
634 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
636 @var{serial}: buffer to store the serial number (may be null)
638 @var{serial_size}: Holds the size of the serial field (may be null)
640 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
642 This function will return the X.509 authority key
643 identifier when stored as a general name (authorityCertIssuer)
646 Because more than one general names might be stored
647 @code{seq} can be used as a counter to request them all until
648 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
650 @strong{Returns:} Returns 0 on success, or an error code.
655 @subheading gnutls_x509_crl_get_authority_key_id
656 @anchor{gnutls_x509_crl_get_authority_key_id}
657 @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})
658 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
660 @var{id}: The place where the identifier will be copied
662 @var{id_size}: Holds the size of the result field.
664 @var{critical}: will be non-zero if the extension is marked as critical
667 This function will return the CRL authority's key identifier. This
668 is obtained by the X.509 Authority Key identifier extension field
669 (2.5.29.35). Note that this function
670 only returns the keyIdentifier field of the extension and
671 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
672 the name and serial number of the certificate. In that case
673 @code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used.
675 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
676 negative error code in case of an error.
678 @strong{Since:} 2.8.0
681 @subheading gnutls_x509_crl_get_crt_count
682 @anchor{gnutls_x509_crl_get_crt_count}
683 @deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl})
684 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
686 This function will return the number of revoked certificates in the
689 @strong{Returns:} number of certificates, a negative error code on failure.
692 @subheading gnutls_x509_crl_get_crt_serial
693 @anchor{gnutls_x509_crl_get_crt_serial}
694 @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})
695 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
697 @var{indx}: the index of the certificate to extract (starting from 0)
699 @var{serial}: where the serial number will be copied
701 @var{serial_size}: initially holds the size of serial
703 @var{t}: if non null, will hold the time this certificate was revoked
705 This function will retrieve the serial number of the specified, by
706 the index, revoked certificate.
708 Note that this function will have performance issues in large sequences
709 of revoked certificates. In that case use @code{gnutls_x509_crl_iter_crt_serial()} .
711 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
712 negative error value. and a negative error code on error.
715 @subheading gnutls_x509_crl_get_dn_oid
716 @anchor{gnutls_x509_crl_get_dn_oid}
717 @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})
718 @var{crl}: should contain a gnutls_x509_crl_t structure
720 @var{indx}: Specifies which DN OID to send. Use (0) to get the first one.
722 @var{oid}: a pointer to a structure to hold the name (may be null)
724 @var{sizeof_oid}: initially holds the size of 'oid'
726 This function will extract the requested OID of the name of the CRL
727 issuer, specified by the given index.
729 If oid is null then only the size will be filled.
731 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
732 not long enough, and in that case the sizeof_oid will be updated
733 with the required size. On success 0 is returned.
736 @subheading gnutls_x509_crl_get_extension_data
737 @anchor{gnutls_x509_crl_get_extension_data}
738 @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})
739 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
741 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
743 @var{data}: a pointer to a structure to hold the data (may be null)
745 @var{sizeof_data}: initially holds the size of @code{oid}
747 This function will return the requested extension data in the CRL.
748 The extension data will be stored as a string in the provided
751 Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and
752 critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead,
753 if you want to get data indexed by the extension OID rather than
756 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
757 negative error code in case of an error. If your have reached the
758 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
761 @strong{Since:} 2.8.0
764 @subheading gnutls_x509_crl_get_extension_data2
765 @anchor{gnutls_x509_crl_get_extension_data2}
766 @deftypefun {int} {gnutls_x509_crl_get_extension_data2} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, gnutls_datum_t * @var{data})
767 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
769 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
771 @var{data}: will contain the extension DER-encoded data
773 This function will return the requested by the index extension data in the
774 certificate revocation list. The extension data will be allocated using
775 @code{gnutls_malloc()} .
777 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
779 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
780 otherwise a negative error code is returned. If you have reached the
781 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
785 @subheading gnutls_x509_crl_get_extension_info
786 @anchor{gnutls_x509_crl_get_extension_info}
787 @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})
788 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
790 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
792 @var{oid}: a pointer to a structure to hold the OID
794 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
795 holds actual size of @code{oid} .
797 @var{critical}: output variable with critical flag, may be NULL.
799 This function will return the requested extension OID in the CRL,
800 and the critical flag for it. The extension OID will be stored as
801 a string in the provided buffer. Use
802 @code{gnutls_x509_crl_get_extension_data()} to extract the data.
804 If the buffer provided is not long enough to hold the output, then
805 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
808 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
809 negative error code in case of an error. If your have reached the
810 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
813 @strong{Since:} 2.8.0
816 @subheading gnutls_x509_crl_get_extension_oid
817 @anchor{gnutls_x509_crl_get_extension_oid}
818 @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})
819 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
821 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
823 @var{oid}: a pointer to a structure to hold the OID (may be null)
825 @var{sizeof_oid}: initially holds the size of @code{oid}
827 This function will return the requested extension OID in the CRL.
828 The extension OID will be stored as a string in the provided
831 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
832 negative error code in case of an error. If your have reached the
833 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
836 @strong{Since:} 2.8.0
839 @subheading gnutls_x509_crl_get_issuer_dn
840 @anchor{gnutls_x509_crl_get_issuer_dn}
841 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (const gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf})
842 @var{crl}: should contain a gnutls_x509_crl_t structure
844 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
846 @var{sizeof_buf}: initially holds the size of @code{buf}
848 This function will copy the name of the CRL issuer in the provided
849 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
850 described in RFC4514. The output string will be ASCII or UTF-8
851 encoded, depending on the certificate data.
853 If buf is @code{NULL} then only the size will be filled.
855 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
856 not long enough, and in that case the sizeof_buf will be updated
857 with the required size, and 0 on success.
860 @subheading gnutls_x509_crl_get_issuer_dn2
861 @anchor{gnutls_x509_crl_get_issuer_dn2}
862 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn2} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
863 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
865 @var{dn}: a pointer to a structure to hold the name
867 This function will allocate buffer and copy the name of the CRL issuer.
868 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
869 described in RFC4514. The output string will be ASCII or UTF-8
870 encoded, depending on the certificate data.
872 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
873 negative error value. and a negative error code on error.
875 @strong{Since:} 3.1.10
878 @subheading gnutls_x509_crl_get_issuer_dn_by_oid
879 @anchor{gnutls_x509_crl_get_issuer_dn_by_oid}
880 @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})
881 @var{crl}: should contain a gnutls_x509_crl_t structure
883 @var{oid}: holds an Object Identified in null terminated string
885 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
887 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
889 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
891 @var{sizeof_buf}: initially holds the size of @code{buf}
893 This function will extract the part of the name of the CRL issuer
894 specified by the given OID. The output will be encoded as described
895 in RFC4514. The output string will be ASCII or UTF-8 encoded,
896 depending on the certificate data.
898 Some helper macros with popular OIDs can be found in gnutls/x509.h
899 If raw flag is (0), this function will only return known OIDs as
900 text. Other OIDs will be DER encoded, as described in RFC4514 -- in
901 hex format with a '#' prefix. You can check about known OIDs
902 using @code{gnutls_x509_dn_oid_known()} .
904 If buf is null then only the size will be filled.
906 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
907 not long enough, and in that case the sizeof_buf will be updated
908 with the required size, and 0 on success.
911 @subheading gnutls_x509_crl_get_next_update
912 @anchor{gnutls_x509_crl_get_next_update}
913 @deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl})
914 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
916 This function will return the time the next CRL will be issued.
917 This field is optional in a CRL so it might be normal to get an
920 @strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error.
923 @subheading gnutls_x509_crl_get_number
924 @anchor{gnutls_x509_crl_get_number}
925 @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})
926 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
928 @var{ret}: The place where the number will be copied
930 @var{ret_size}: Holds the size of the result field.
932 @var{critical}: will be non-zero if the extension is marked as critical
935 This function will return the CRL number extension. This is
936 obtained by the CRL Number extension field (2.5.29.20).
938 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
939 negative error code in case of an error.
941 @strong{Since:} 2.8.0
944 @subheading gnutls_x509_crl_get_raw_issuer_dn
945 @anchor{gnutls_x509_crl_get_raw_issuer_dn}
946 @deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
947 @var{crl}: should contain a gnutls_x509_crl_t structure
949 @var{dn}: will hold the starting point of the DN
951 This function will return a pointer to the DER encoded DN structure
954 @strong{Returns:} a negative error code on error, and (0) on success.
956 @strong{Since:} 2.12.0
959 @subheading gnutls_x509_crl_get_signature
960 @anchor{gnutls_x509_crl_get_signature}
961 @deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig})
962 @var{crl}: should contain a gnutls_x509_crl_t structure
964 @var{sig}: a pointer where the signature part will be copied (may be null).
966 @var{sizeof_sig}: initially holds the size of @code{sig}
968 This function will extract the signature field of a CRL.
970 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
971 negative error value. and a negative error code on error.
974 @subheading gnutls_x509_crl_get_signature_algorithm
975 @anchor{gnutls_x509_crl_get_signature_algorithm}
976 @deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl})
977 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
979 This function will return a value of the @code{gnutls_sign_algorithm_t}
980 enumeration that is the signature algorithm.
982 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
983 negative error value.
986 @subheading gnutls_x509_crl_get_this_update
987 @anchor{gnutls_x509_crl_get_this_update}
988 @deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl})
989 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
991 This function will return the time this CRL was issued.
993 @strong{Returns:} when the CRL was issued, or (time_t)-1 on error.
996 @subheading gnutls_x509_crl_get_version
997 @anchor{gnutls_x509_crl_get_version}
998 @deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl})
999 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
1001 This function will return the version of the specified CRL.
1003 @strong{Returns:} The version number, or a negative error code on error.
1006 @subheading gnutls_x509_crl_import
1007 @anchor{gnutls_x509_crl_import}
1008 @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})
1009 @var{crl}: The structure to store the parsed CRL.
1011 @var{data}: The DER or PEM encoded CRL.
1013 @var{format}: One of DER or PEM
1015 This function will convert the given DER or PEM encoded CRL
1016 to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'.
1018 If the CRL is PEM encoded it should have a header of "X509 CRL".
1020 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1021 negative error value.
1024 @subheading gnutls_x509_crl_init
1025 @anchor{gnutls_x509_crl_init}
1026 @deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl})
1027 @var{crl}: The structure to be initialized
1029 This function will initialize a CRL structure. CRL stands for
1030 Certificate Revocation List. A revocation list usually contains
1031 lists of certificate serial numbers that have been revoked by an
1032 Authority. The revocation lists are always signed with the
1033 authority's private key.
1035 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1036 negative error value.
1039 @subheading gnutls_x509_crl_iter_crt_serial
1040 @anchor{gnutls_x509_crl_iter_crt_serial}
1041 @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})
1042 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
1044 @var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} )
1046 @var{serial}: where the serial number will be copied
1048 @var{serial_size}: initially holds the size of serial
1050 @var{t}: if non null, will hold the time this certificate was revoked
1052 This function performs the same as @code{gnutls_x509_crl_get_crt_serial()} ,
1053 but reads sequentially and keeps state in the iterator
1054 between calls. That allows it to provide better performance in sequences
1055 with many elements (50000+).
1057 When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1058 is returned and the iterator is reset.
1060 After use, the iterator must be deinitialized using @code{gnutls_x509_crl_iter_deinit()} .
1062 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1063 negative error value. and a negative error code on error.
1066 @subheading gnutls_x509_crl_iter_deinit
1067 @anchor{gnutls_x509_crl_iter_deinit}
1068 @deftypefun {void} {gnutls_x509_crl_iter_deinit} (gnutls_x509_crl_iter_t @var{iter})
1069 @var{iter}: The iterator structure to be deinitialized
1071 This function will deinitialize an iterator structure.
1074 @subheading gnutls_x509_crl_list_import
1075 @anchor{gnutls_x509_crl_list_import}
1076 @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})
1077 @var{crls}: The structures to store the parsed CRLs. Must not be initialized.
1079 @var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available.
1081 @var{data}: The PEM encoded CRLs
1083 @var{format}: One of DER or PEM.
1085 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
1087 This function will convert the given PEM encoded CRL list
1088 to the native gnutls_x509_crl_t format. The output will be stored
1089 in @code{crls} . They will be automatically initialized.
1091 If the Certificate is PEM encoded it should have a header of "X509 CRL".
1093 @strong{Returns:} the number of certificates read or a negative error value.
1098 @subheading gnutls_x509_crl_list_import2
1099 @anchor{gnutls_x509_crl_list_import2}
1100 @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})
1101 @var{crls}: The structures to store the parsed crl list. Must not be initialized.
1103 @var{size}: It will contain the size of the list.
1105 @var{data}: The PEM encoded CRL.
1107 @var{format}: One of DER or PEM.
1109 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
1111 This function will convert the given PEM encoded CRL list
1112 to the native gnutls_x509_crl_t format. The output will be stored
1113 in @code{crls} . They will be automatically initialized.
1115 If the Certificate is PEM encoded it should have a header of "X509
1118 @strong{Returns:} the number of certificates read or a negative error value.
1123 @subheading gnutls_x509_crl_print
1124 @anchor{gnutls_x509_crl_print}
1125 @deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1126 @var{crl}: The structure to be printed
1128 @var{format}: Indicate the format to use
1130 @var{out}: Newly allocated datum with (0) terminated string.
1132 This function will pretty print a X.509 certificate revocation
1133 list, suitable for display to a human.
1135 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
1137 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1138 negative error value.
1141 @subheading gnutls_x509_crl_set_authority_key_id
1142 @anchor{gnutls_x509_crl_set_authority_key_id}
1143 @deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size})
1144 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1146 @var{id}: The key ID
1148 @var{id_size}: Holds the size of the serial field.
1150 This function will set the CRL's authority key ID extension. Only
1151 the keyIdentifier field can be set with this function. This may
1152 be used by an authority that holds multiple private keys, to distinguish
1155 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1156 negative error value.
1158 @strong{Since:} 2.8.0
1161 @subheading gnutls_x509_crl_set_crt
1162 @anchor{gnutls_x509_crl_set_crt}
1163 @deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time})
1164 @var{crl}: should contain a gnutls_x509_crl_t structure
1166 @var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate
1168 @var{revocation_time}: The time this certificate was revoked
1170 This function will set a revoked certificate's serial number to the CRL.
1172 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1173 negative error value.
1176 @subheading gnutls_x509_crl_set_crt_serial
1177 @anchor{gnutls_x509_crl_set_crt_serial}
1178 @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})
1179 @var{crl}: should contain a gnutls_x509_crl_t structure
1181 @var{serial}: The revoked certificate's serial number
1183 @var{serial_size}: Holds the size of the serial field.
1185 @var{revocation_time}: The time this certificate was revoked
1187 This function will set a revoked certificate's serial number to the CRL.
1189 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1190 negative error value.
1193 @subheading gnutls_x509_crl_set_next_update
1194 @anchor{gnutls_x509_crl_set_next_update}
1195 @deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time})
1196 @var{crl}: should contain a gnutls_x509_crl_t structure
1198 @var{exp_time}: The actual time
1200 This function will set the time this CRL will be updated.
1202 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1203 negative error value.
1206 @subheading gnutls_x509_crl_set_number
1207 @anchor{gnutls_x509_crl_set_number}
1208 @deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size})
1209 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1211 @var{nr}: The CRL number
1213 @var{nr_size}: Holds the size of the nr field.
1215 This function will set the CRL's number extension. This
1216 is to be used as a unique and monotonic number assigned to
1217 the CRL by the authority.
1219 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1220 negative error value.
1222 @strong{Since:} 2.8.0
1225 @subheading gnutls_x509_crl_set_this_update
1226 @anchor{gnutls_x509_crl_set_this_update}
1227 @deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time})
1228 @var{crl}: should contain a gnutls_x509_crl_t structure
1230 @var{act_time}: The actual time
1232 This function will set the time this CRL was issued.
1234 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1235 negative error value.
1238 @subheading gnutls_x509_crl_set_version
1239 @anchor{gnutls_x509_crl_set_version}
1240 @deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version})
1241 @var{crl}: should contain a gnutls_x509_crl_t structure
1243 @var{version}: holds the version number. For CRLv1 crls must be 1.
1245 This function will set the version of the CRL. This
1246 must be one for CRL version 1, and so on. The CRLs generated
1247 by gnutls should have a version number of 2.
1249 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1250 negative error value.
1253 @subheading gnutls_x509_crl_sign2
1254 @anchor{gnutls_x509_crl_sign2}
1255 @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})
1256 @var{crl}: should contain a gnutls_x509_crl_t structure
1258 @var{issuer}: is the certificate of the certificate issuer
1260 @var{issuer_key}: holds the issuer's private key
1262 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1264 @var{flags}: must be 0
1266 This function will sign the CRL with the issuer's private key, and
1267 will copy the issuer's information into the CRL.
1269 This must be the last step in a certificate CRL since all
1270 the previously set parameters are now signed.
1272 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1273 negative error value.
1276 @subheading gnutls_x509_crl_verify
1277 @anchor{gnutls_x509_crl_verify}
1278 @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})
1279 @var{crl}: is the crl to be verified
1281 @var{trusted_cas}: is a certificate list that is considered to be trusted one
1283 @var{tcas_size}: holds the number of CA certificates in CA_list
1285 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1287 @var{verify}: will hold the crl verification output.
1289 This function will try to verify the given crl and return its verification status.
1290 See @code{gnutls_x509_crt_list_verify()} for a detailed description of
1291 return values. Note that since GnuTLS 3.1.4 this function includes
1294 Note that value in @code{verify} is set only when the return value of this
1295 function is success (i.e, failure to trust a CRL a certificate does not imply
1296 a negative return value).
1298 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1299 negative error value.
1302 @subheading gnutls_x509_crq_deinit
1303 @anchor{gnutls_x509_crq_deinit}
1304 @deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq})
1305 @var{crq}: The structure to be initialized
1307 This function will deinitialize a PKCS@code{10} certificate request
1311 @subheading gnutls_x509_crq_export
1312 @anchor{gnutls_x509_crq_export}
1313 @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})
1314 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1316 @var{format}: the format of output params. One of PEM or DER.
1318 @var{output_data}: will contain a certificate request PEM or DER encoded
1320 @var{output_data_size}: holds the size of output_data (and will be
1321 replaced by the actual size of parameters)
1323 This function will export the certificate request to a PEM or DER
1324 encoded PKCS10 structure.
1326 If the buffer provided is not long enough to hold the output, then
1327 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and
1328 * @code{output_data_size} will be updated.
1330 If the structure is PEM encoded, it will have a header of "BEGIN
1331 NEW CERTIFICATE REQUEST".
1333 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1334 negative error value.
1337 @subheading gnutls_x509_crq_export2
1338 @anchor{gnutls_x509_crq_export2}
1339 @deftypefun {int} {gnutls_x509_crq_export2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
1340 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1342 @var{format}: the format of output params. One of PEM or DER.
1344 @var{out}: will contain a certificate request PEM or DER encoded
1346 This function will export the certificate request to a PEM or DER
1347 encoded PKCS10 structure.
1349 The output buffer is allocated using @code{gnutls_malloc()} .
1351 If the structure is PEM encoded, it will have a header of "BEGIN
1352 NEW CERTIFICATE REQUEST".
1354 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1355 negative error value.
1360 @subheading gnutls_x509_crq_get_attribute_by_oid
1361 @anchor{gnutls_x509_crq_get_attribute_by_oid}
1362 @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})
1363 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1365 @var{oid}: holds an Object Identifier in null-terminated string
1367 @var{indx}: In case multiple same OIDs exist in the attribute list, this
1368 specifies which to get, use (0) to get the first one
1370 @var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} )
1372 @var{buf_size}: initially holds the size of @code{buf}
1374 This function will return the attribute in the certificate request
1375 specified by the given Object ID. The attribute will be DER
1378 Attributes in a certificate request is an optional set of data
1379 appended to the request. Their interpretation depends on the CA policy.
1381 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1382 negative error value.
1385 @subheading gnutls_x509_crq_get_attribute_data
1386 @anchor{gnutls_x509_crq_get_attribute_data}
1387 @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})
1388 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1390 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1392 @var{data}: a pointer to a structure to hold the data (may be null)
1394 @var{sizeof_data}: initially holds the size of @code{oid}
1396 This function will return the requested attribute data in the
1397 certificate request. The attribute data will be stored as a string in the
1400 Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID.
1401 Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead,
1402 if you want to get data indexed by the attribute OID rather than
1405 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1406 negative error code in case of an error. If your have reached the
1407 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1410 @strong{Since:} 2.8.0
1413 @subheading gnutls_x509_crq_get_attribute_info
1414 @anchor{gnutls_x509_crq_get_attribute_info}
1415 @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})
1416 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1418 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1420 @var{oid}: a pointer to a structure to hold the OID
1422 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1423 holds actual size of @code{oid} .
1425 This function will return the requested attribute OID in the
1426 certificate, and the critical flag for it. The attribute OID will
1427 be stored as a string in the provided buffer. Use
1428 @code{gnutls_x509_crq_get_attribute_data()} to extract the data.
1430 If the buffer provided is not long enough to hold the output, then
1431 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1434 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1435 negative error code in case of an error. If your have reached the
1436 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1439 @strong{Since:} 2.8.0
1442 @subheading gnutls_x509_crq_get_basic_constraints
1443 @anchor{gnutls_x509_crq_get_basic_constraints}
1444 @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})
1445 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1447 @var{critical}: will be non-zero if the extension is marked as critical
1449 @var{ca}: pointer to output integer indicating CA status, may be NULL,
1450 value is 1 if the certificate CA flag is set, 0 otherwise.
1452 @var{pathlen}: pointer to output integer indicating path length (may be
1453 NULL), non-negative error codes indicate a present pathLenConstraint
1454 field and the actual value, -1 indicate that the field is absent.
1456 This function will read the certificate's basic constraints, and
1457 return the certificates CA status. It reads the basicConstraints
1458 X.509 extension (2.5.29.19).
1460 @strong{Returns:} If the certificate is a CA a positive value will be
1461 returned, or (0) if the certificate does not have CA flag set.
1462 A negative error code may be returned in case of errors. If the
1463 certificate does not contain the basicConstraints extension
1464 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1466 @strong{Since:} 2.8.0
1469 @subheading gnutls_x509_crq_get_challenge_password
1470 @anchor{gnutls_x509_crq_get_challenge_password}
1471 @deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{pass_size})
1472 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1474 @var{pass}: will hold a (0)-terminated password string
1476 @var{pass_size}: Initially holds the size of @code{pass} .
1478 This function will return the challenge password in the request.
1479 The challenge password is intended to be used for requesting a
1480 revocation of the certificate.
1482 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1483 negative error value.
1486 @subheading gnutls_x509_crq_get_dn
1487 @anchor{gnutls_x509_crq_get_dn}
1488 @deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{buf_size})
1489 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1491 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1493 @var{buf_size}: initially holds the size of @code{buf}
1495 This function will copy the name of the Certificate request subject
1496 to the provided buffer. The name will be in the form
1497 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
1498 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate
1501 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
1502 long enough, and in that case the * @code{buf_size} will be updated with
1503 the required size. On success 0 is returned.
1506 @subheading gnutls_x509_crq_get_dn2
1507 @anchor{gnutls_x509_crq_get_dn2}
1508 @deftypefun {int} {gnutls_x509_crq_get_dn2} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn})
1509 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1511 @var{dn}: a pointer to a structure to hold the name
1513 This function will allocate buffer and copy the name of the Certificate
1514 request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
1515 described in RFC4514. The output string will be ASCII or UTF-8
1516 encoded, depending on the certificate data.
1518 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1519 negative error value. and a negative error code on error.
1521 @strong{Since:} 3.1.10
1524 @subheading gnutls_x509_crq_get_dn_by_oid
1525 @anchor{gnutls_x509_crq_get_dn_by_oid}
1526 @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})
1527 @var{crq}: should contain a gnutls_x509_crq_t structure
1529 @var{oid}: holds an Object Identifier in a null terminated string
1531 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies
1532 which to get. Use (0) to get the first one.
1534 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
1536 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1538 @var{buf_size}: initially holds the size of @code{buf}
1540 This function will extract the part of the name of the Certificate
1541 request subject, specified by the given OID. The output will be
1542 encoded as described in RFC2253. The output string will be ASCII
1543 or UTF-8 encoded, depending on the certificate data.
1545 Some helper macros with popular OIDs can be found in gnutls/x509.h
1546 If raw flag is (0), this function will only return known OIDs as
1547 text. Other OIDs will be DER encoded, as described in RFC2253 --
1548 in hex format with a '\#' prefix. You can check about known OIDs
1549 using @code{gnutls_x509_dn_oid_known()} .
1551 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1552 not long enough, and in that case the * @code{buf_size} will be
1553 updated with the required size. On success 0 is returned.
1556 @subheading gnutls_x509_crq_get_dn_oid
1557 @anchor{gnutls_x509_crq_get_dn_oid}
1558 @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})
1559 @var{crq}: should contain a gnutls_x509_crq_t structure
1561 @var{indx}: Specifies which DN OID to get. Use (0) to get the first one.
1563 @var{oid}: a pointer to a structure to hold the name (may be @code{NULL} )
1565 @var{sizeof_oid}: initially holds the size of @code{oid}
1567 This function will extract the requested OID of the name of the
1568 certificate request subject, specified by the given index.
1570 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1571 not long enough, and in that case the * @code{sizeof_oid} will be
1572 updated with the required size. On success 0 is returned.
1575 @subheading gnutls_x509_crq_get_extension_by_oid
1576 @anchor{gnutls_x509_crq_get_extension_by_oid}
1577 @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})
1578 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1580 @var{oid}: holds an Object Identifier in a null terminated string
1582 @var{indx}: In case multiple same OIDs exist in the extensions, this
1583 specifies which to get. Use (0) to get the first one.
1585 @var{buf}: a pointer to a structure to hold the name (may be null)
1587 @var{buf_size}: initially holds the size of @code{buf}
1589 @var{critical}: will be non-zero if the extension is marked as critical
1591 This function will return the extension specified by the OID in
1592 the certificate. The extensions will be returned as binary data
1593 DER encoded, in the provided buffer.
1595 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1596 negative error code in case of an error. If the certificate does not
1597 contain the specified extension
1598 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1600 @strong{Since:} 2.8.0
1603 @subheading gnutls_x509_crq_get_extension_data
1604 @anchor{gnutls_x509_crq_get_extension_data}
1605 @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})
1606 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1608 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1610 @var{data}: a pointer to a structure to hold the data (may be null)
1612 @var{sizeof_data}: initially holds the size of @code{oid}
1614 This function will return the requested extension data in the
1615 certificate. The extension data will be stored as a string in the
1618 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and
1619 critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead,
1620 if you want to get data indexed by the extension OID rather than
1623 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1624 negative error code in case of an error. If your have reached the
1625 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1628 @strong{Since:} 2.8.0
1631 @subheading gnutls_x509_crq_get_extension_data2
1632 @anchor{gnutls_x509_crq_get_extension_data2}
1633 @deftypefun {int} {gnutls_x509_crq_get_extension_data2} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, gnutls_datum_t * @var{data})
1634 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1636 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
1638 @var{data}: will contain the extension DER-encoded data
1640 This function will return the requested extension data in the
1641 certificate request. The extension data will be allocated using
1642 @code{gnutls_malloc()} .
1644 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID.
1646 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
1647 otherwise a negative error code is returned. If you have reached the
1648 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1651 @strong{Since:} 3.3.0
1654 @subheading gnutls_x509_crq_get_extension_info
1655 @anchor{gnutls_x509_crq_get_extension_info}
1656 @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})
1657 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1659 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1661 @var{oid}: a pointer to a structure to hold the OID
1663 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1664 holds actual size of @code{oid} .
1666 @var{critical}: output variable with critical flag, may be NULL.
1668 This function will return the requested extension OID in the
1669 certificate, and the critical flag for it. The extension OID will
1670 be stored as a string in the provided buffer. Use
1671 @code{gnutls_x509_crq_get_extension_data()} to extract the data.
1673 If the buffer provided is not long enough to hold the output, then
1674 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1677 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1678 negative error code in case of an error. If your have reached the
1679 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1682 @strong{Since:} 2.8.0
1685 @subheading gnutls_x509_crq_get_key_id
1686 @anchor{gnutls_x509_crq_get_key_id}
1687 @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})
1688 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1690 @var{flags}: should be 0 for now
1692 @var{output_data}: will contain the key ID
1694 @var{output_data_size}: holds the size of output_data (and will be
1695 replaced by the actual size of parameters)
1697 This function will return a unique ID that depends on the public key
1698 parameters. This ID can be used in checking whether a certificate
1699 corresponds to the given private key.
1701 If the buffer provided is not long enough to hold the output, then
1702 * @code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1703 be returned. The output will normally be a SHA-1 hash output,
1706 @strong{Returns:} In case of failure a negative error code will be
1707 returned, and 0 on success.
1709 @strong{Since:} 2.8.0
1712 @subheading gnutls_x509_crq_get_key_purpose_oid
1713 @anchor{gnutls_x509_crq_get_key_purpose_oid}
1714 @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})
1715 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1717 @var{indx}: This specifies which OID to return, use (0) to get the first one
1719 @var{oid}: a pointer to a buffer to hold the OID (may be @code{NULL} )
1721 @var{sizeof_oid}: initially holds the size of @code{oid}
1723 @var{critical}: output variable with critical flag, may be @code{NULL} .
1725 This function will extract the key purpose OIDs of the Certificate
1726 specified by the given index. These are stored in the Extended Key
1727 Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for
1728 human readable names.
1730 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1731 not long enough, and in that case the * @code{sizeof_oid} will be
1732 updated with the required size. On success 0 is returned.
1734 @strong{Since:} 2.8.0
1737 @subheading gnutls_x509_crq_get_key_rsa_raw
1738 @anchor{gnutls_x509_crq_get_key_rsa_raw}
1739 @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})
1740 @var{crq}: Holds the certificate
1742 @var{m}: will hold the modulus
1744 @var{e}: will hold the public exponent
1746 This function will export the RSA public key's parameters found in
1747 the given structure. The new parameters will be allocated using
1748 @code{gnutls_malloc()} and will be stored in the appropriate datum.
1750 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1751 negative error value.
1753 @strong{Since:} 2.8.0
1756 @subheading gnutls_x509_crq_get_key_usage
1757 @anchor{gnutls_x509_crq_get_key_usage}
1758 @deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
1759 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1761 @var{key_usage}: where the key usage bits will be stored
1763 @var{critical}: will be non-zero if the extension is marked as critical
1765 This function will return certificate's key usage, by reading the
1766 keyUsage X.509 extension (2.5.29.15). The key usage value will
1767 ORed values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
1768 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
1769 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
1770 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
1771 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
1773 @strong{Returns:} the certificate key usage, or a negative error code in case of
1774 parsing error. If the certificate does not contain the keyUsage
1775 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
1778 @strong{Since:} 2.8.0
1781 @subheading gnutls_x509_crq_get_pk_algorithm
1782 @anchor{gnutls_x509_crq_get_pk_algorithm}
1783 @deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits})
1784 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1786 @var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits
1788 This function will return the public key algorithm of a PKCS@code{10}
1789 certificate request.
1791 If bits is non-@code{NULL} , it should have enough size to hold the
1792 parameters size in bits. For RSA the bits returned is the modulus.
1793 For DSA the bits returned are of the public exponent.
1795 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1796 success, or a negative error code on error.
1799 @subheading gnutls_x509_crq_get_private_key_usage_period
1800 @anchor{gnutls_x509_crq_get_private_key_usage_period}
1801 @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})
1802 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1804 @var{activation}: The activation time
1806 @var{expiration}: The expiration time
1808 @var{critical}: the extension status
1810 This function will return the expiration and activation
1811 times of the private key of the certificate.
1813 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1814 if the extension is not present, otherwise a negative error value.
1817 @subheading gnutls_x509_crq_get_subject_alt_name
1818 @anchor{gnutls_x509_crq_get_subject_alt_name}
1819 @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})
1820 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1822 @var{seq}: specifies the sequence number of the alt name, 0 for the
1823 first one, 1 for the second etc.
1825 @var{ret}: is the place where the alternative name will be copied to
1827 @var{ret_size}: holds the size of ret.
1829 @var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type
1831 @var{critical}: will be non-zero if the extension is marked as critical
1834 This function will return the alternative names, contained in the
1835 given certificate. It is the same as
1836 @code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it
1837 will return the type of the alternative name in @code{ret_type} even if
1838 the function fails for some reason (i.e. the buffer provided is
1841 @strong{Returns:} the alternative subject name type on success, one of the
1842 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
1843 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
1844 hold the value. In that case @code{ret_size} will be updated with the
1845 required size. If the certificate request does not have an
1846 Alternative name with the specified sequence number then
1847 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1849 @strong{Since:} 2.8.0
1852 @subheading gnutls_x509_crq_get_subject_alt_othername_oid
1853 @anchor{gnutls_x509_crq_get_subject_alt_othername_oid}
1854 @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})
1855 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1857 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1859 @var{ret}: is the place where the otherName OID will be copied to
1861 @var{ret_size}: holds the size of ret.
1863 This function will extract the type OID of an otherName Subject
1864 Alternative Name, contained in the given certificate, and return
1865 the type as an enumerated element.
1867 This function is only useful if
1868 @code{gnutls_x509_crq_get_subject_alt_name()} returned
1869 @code{GNUTLS_SAN_OTHERNAME} .
1871 @strong{Returns:} the alternative subject name type on success, one of the
1872 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs,
1873 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
1874 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
1875 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
1876 @code{ret_size} is not large enough to hold the value. In that case
1877 @code{ret_size} will be updated with the required size. If the
1878 certificate does not have an Alternative name with the specified
1879 sequence number and with the otherName type then
1880 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1882 @strong{Since:} 2.8.0
1885 @subheading gnutls_x509_crq_get_version
1886 @anchor{gnutls_x509_crq_get_version}
1887 @deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq})
1888 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1890 This function will return the version of the specified Certificate
1893 @strong{Returns:} version of certificate request, or a negative error code on
1897 @subheading gnutls_x509_crq_import
1898 @anchor{gnutls_x509_crq_import}
1899 @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})
1900 @var{crq}: The structure to store the parsed certificate request.
1902 @var{data}: The DER or PEM encoded certificate.
1904 @var{format}: One of DER or PEM
1906 This function will convert the given DER or PEM encoded certificate
1907 request to a @code{gnutls_x509_crq_t} structure. The output will be
1908 stored in @code{crq} .
1910 If the Certificate is PEM encoded it should have a header of "NEW
1911 CERTIFICATE REQUEST".
1913 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1914 negative error value.
1917 @subheading gnutls_x509_crq_init
1918 @anchor{gnutls_x509_crq_init}
1919 @deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq})
1920 @var{crq}: The structure to be initialized
1922 This function will initialize a PKCS@code{10} certificate request
1925 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1926 negative error value.
1929 @subheading gnutls_x509_crq_print
1930 @anchor{gnutls_x509_crq_print}
1931 @deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1932 @var{crq}: The structure to be printed
1934 @var{format}: Indicate the format to use
1936 @var{out}: Newly allocated datum with (0) terminated string.
1938 This function will pretty print a certificate request, suitable for
1941 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
1943 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1944 negative error value.
1946 @strong{Since:} 2.8.0
1949 @subheading gnutls_x509_crq_set_attribute_by_oid
1950 @anchor{gnutls_x509_crq_set_attribute_by_oid}
1951 @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})
1952 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1954 @var{oid}: holds an Object Identifier in a null-terminated string
1956 @var{buf}: a pointer to a structure that holds the attribute data
1958 @var{buf_size}: holds the size of @code{buf}
1960 This function will set the attribute in the certificate request
1961 specified by the given Object ID. The provided attribute must be be DER
1964 Attributes in a certificate request is an optional set of data
1965 appended to the request. Their interpretation depends on the CA policy.
1967 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1968 negative error value.
1971 @subheading gnutls_x509_crq_set_basic_constraints
1972 @anchor{gnutls_x509_crq_set_basic_constraints}
1973 @deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint})
1974 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1976 @var{ca}: true(1) or false(0) depending on the Certificate authority status.
1978 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
1979 and negative error codes indicate that the pathLenConstraints field should
1982 This function will set the basicConstraints 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_challenge_password
1991 @anchor{gnutls_x509_crq_set_challenge_password}
1992 @deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass})
1993 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1995 @var{pass}: holds a (0)-terminated password
1997 This function will set a challenge password to be used when
1998 revoking the request.
2000 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2001 negative error value.
2004 @subheading gnutls_x509_crq_set_dn
2005 @anchor{gnutls_x509_crq_set_dn}
2006 @deftypefun {int} {gnutls_x509_crq_set_dn} (gnutls_x509_crq_t @var{crq}, const char * @var{dn}, const char ** @var{err})
2007 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2009 @var{dn}: a comma separated DN string (RFC4514)
2011 @var{err}: indicates the error position (if any)
2013 This function will set the DN on the provided certificate.
2014 The input string should be plain ASCII or UTF-8 encoded.
2016 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2017 negative error value.
2020 @subheading gnutls_x509_crq_set_dn_by_oid
2021 @anchor{gnutls_x509_crq_set_dn_by_oid}
2022 @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})
2023 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2025 @var{oid}: holds an Object Identifier in a (0)-terminated string
2027 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
2029 @var{data}: a pointer to the input data
2031 @var{sizeof_data}: holds the size of @code{data}
2033 This function will set the part of the name of the Certificate
2034 request subject, specified by the given OID. The input string
2035 should be ASCII or UTF-8 encoded.
2037 Some helper macros with popular OIDs can be found in gnutls/x509.h
2038 With this function you can only set the known OIDs. You can test
2039 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
2040 not known (by gnutls) you should properly DER encode your data, and
2041 call this function with raw_flag set.
2043 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2044 negative error value.
2047 @subheading gnutls_x509_crq_set_key
2048 @anchor{gnutls_x509_crq_set_key}
2049 @deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
2050 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2052 @var{key}: holds a private key
2054 This function will set the public parameters from the given private
2057 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2058 negative error value.
2061 @subheading gnutls_x509_crq_set_key_purpose_oid
2062 @anchor{gnutls_x509_crq_set_key_purpose_oid}
2063 @deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical})
2064 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2066 @var{oid}: a pointer to a (0)-terminated string that holds the OID
2068 @var{critical}: Whether this extension will be critical or not
2070 This function will set the key purpose OIDs of the Certificate.
2071 These are stored in the Extended Key Usage extension (2.5.29.37)
2072 See the GNUTLS_KP_* definitions for human readable names.
2074 Subsequent calls to this function will append OIDs to the OID list.
2076 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2077 negative error value.
2079 @strong{Since:} 2.8.0
2082 @subheading gnutls_x509_crq_set_key_rsa_raw
2083 @anchor{gnutls_x509_crq_set_key_rsa_raw}
2084 @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})
2085 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2087 @var{m}: holds the modulus
2089 @var{e}: holds the public exponent
2091 This function will set the public parameters from the given private
2092 key to the request. Only RSA keys are currently supported.
2094 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2095 negative error value.
2097 @strong{Since:} 2.6.0
2100 @subheading gnutls_x509_crq_set_key_usage
2101 @anchor{gnutls_x509_crq_set_key_usage}
2102 @deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage})
2103 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2105 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
2107 This function will set the keyUsage certificate extension.
2109 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2110 negative error value.
2112 @strong{Since:} 2.8.0
2115 @subheading gnutls_x509_crq_set_private_key_usage_period
2116 @anchor{gnutls_x509_crq_set_private_key_usage_period}
2117 @deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration})
2118 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2120 @var{activation}: The activation time
2122 @var{expiration}: The expiration time
2124 This function will set the private key usage period extension (2.5.29.16).
2126 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2127 negative error value.
2130 @subheading gnutls_x509_crq_set_subject_alt_name
2131 @anchor{gnutls_x509_crq_set_subject_alt_name}
2132 @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})
2133 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2135 @var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations
2137 @var{data}: The data to be set
2139 @var{data_size}: The size of data to be set
2141 @var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or
2142 @code{GNUTLS_FSAN_APPEND} to append.
2144 This function will set the subject alternative name certificate
2145 extension. It can set the following types:
2147 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2148 negative error value.
2150 @strong{Since:} 2.8.0
2153 @subheading gnutls_x509_crq_set_version
2154 @anchor{gnutls_x509_crq_set_version}
2155 @deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version})
2156 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2158 @var{version}: holds the version number, for v1 Requests must be 1
2160 This function will set the version of the certificate request. For
2161 version 1 requests this must be one.
2163 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2164 negative error value.
2167 @subheading gnutls_x509_crq_sign2
2168 @anchor{gnutls_x509_crq_sign2}
2169 @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})
2170 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2172 @var{key}: holds a private key
2174 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
2176 @var{flags}: must be 0
2178 This function will sign the certificate request with a private key.
2179 This must be the same key as the one used in
2180 @code{gnutls_x509_crt_set_key()} since a certificate request is self
2183 This must be the last step in a certificate request generation
2184 since all the previously set parameters are now signed.
2186 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2187 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
2188 information in the certificate request (e.g., the version using
2189 @code{gnutls_x509_crq_set_version()} ).
2192 @subheading gnutls_x509_crq_verify
2193 @anchor{gnutls_x509_crq_verify}
2194 @deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
2195 @var{crq}: is the crq to be verified
2197 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2199 This function will verify self signature in the certificate
2200 request and return its status.
2202 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
2203 is returned, and zero or positive code on success.
2208 @subheading gnutls_x509_crt_check_hostname
2209 @anchor{gnutls_x509_crt_check_hostname}
2210 @deftypefun {int} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname})
2211 @var{cert}: should contain an gnutls_x509_crt_t structure
2213 @var{hostname}: A null terminated string that contains a DNS name
2215 This function will check if the given certificate's subject matches
2216 the given hostname. This is a basic implementation of the matching
2217 described in RFC2818 (HTTPS), which takes into account wildcards,
2218 and the DNSName/IPAddress subject alternative name PKIX extension.
2220 The comparison may have false-negatives as it is done byte by byte in
2223 Wildcards are only considered if the domain name consists of three
2224 components or more, and the wildcard starts at the leftmost position.
2226 @strong{Returns:} non-zero for a successful match, and zero on failure.
2229 @subheading gnutls_x509_crt_check_hostname2
2230 @anchor{gnutls_x509_crt_check_hostname2}
2231 @deftypefun {int} {gnutls_x509_crt_check_hostname2} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}, unsigned int @var{flags})
2232 @var{cert}: should contain an gnutls_x509_crt_t structure
2234 @var{hostname}: A null terminated string that contains a DNS name
2236 @var{flags}: gnutls_certificate_verify_flags
2238 This function will check if the given certificate's subject matches
2239 the given hostname. This is a basic implementation of the matching
2240 described in RFC2818 (HTTPS), which takes into account wildcards,
2241 and the DNSName/IPAddress subject alternative name PKIX extension.
2243 The comparison may have false-negatives as it is done byte by byte in
2246 When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS} is specified no
2247 wildcards are considered. Otherwise they are only considered if the
2248 domain name consists of three components or more, and the wildcard
2249 starts at the leftmost position.
2251 @strong{Returns:} non-zero for a successful match, and zero on failure.
2254 @subheading gnutls_x509_crt_check_issuer
2255 @anchor{gnutls_x509_crt_check_issuer}
2256 @deftypefun {int} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer})
2257 @var{cert}: is the certificate to be checked
2259 @var{issuer}: is the certificate of a possible issuer
2261 This function will check if the given certificate was issued by the
2262 given issuer. It checks the DN fields and the authority
2263 key identifier and subject key identifier fields match.
2265 @strong{Returns:} It will return true (1) if the given certificate is issued
2266 by the given issuer, and false (0) if not.
2269 @subheading gnutls_x509_crt_check_revocation
2270 @anchor{gnutls_x509_crt_check_revocation}
2271 @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})
2272 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2274 @var{crl_list}: should contain a list of gnutls_x509_crl_t structures
2276 @var{crl_list_length}: the length of the crl_list
2278 This function will return check if the given certificate is
2279 revoked. It is assumed that the CRLs have been verified before.
2281 @strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A
2282 negative error code is returned on error.
2285 @subheading gnutls_x509_crt_cpy_crl_dist_points
2286 @anchor{gnutls_x509_crt_cpy_crl_dist_points}
2287 @deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src})
2288 @var{dst}: a certificate of type @code{gnutls_x509_crt_t}
2290 @var{src}: the certificate where the dist points will be copied from
2292 This function will copy the CRL distribution points certificate
2293 extension, from the source to the destination certificate.
2294 This may be useful to copy from a CA certificate to issued ones.
2296 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2297 negative error value.
2300 @subheading gnutls_x509_crt_deinit
2301 @anchor{gnutls_x509_crt_deinit}
2302 @deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert})
2303 @var{cert}: The structure to be deinitialized
2305 This function will deinitialize a certificate structure.
2308 @subheading gnutls_x509_crt_export
2309 @anchor{gnutls_x509_crt_export}
2310 @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})
2311 @var{cert}: Holds the certificate
2313 @var{format}: the format of output params. One of PEM or DER.
2315 @var{output_data}: will contain a certificate PEM or DER encoded
2317 @var{output_data_size}: holds the size of output_data (and will be
2318 replaced by the actual size of parameters)
2320 This function will export the certificate to DER or PEM format.
2322 If the buffer provided is not long enough to hold the output, then
2323 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2326 If the structure is PEM encoded, it will have a header
2327 of "BEGIN CERTIFICATE".
2329 @strong{Returns:} In case of failure a negative error code will be
2330 returned, and 0 on success.
2333 @subheading gnutls_x509_crt_export2
2334 @anchor{gnutls_x509_crt_export2}
2335 @deftypefun {int} {gnutls_x509_crt_export2} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
2336 @var{cert}: Holds the certificate
2338 @var{format}: the format of output params. One of PEM or DER.
2340 @var{out}: will contain a certificate PEM or DER encoded
2342 This function will export the certificate to DER or PEM format.
2343 The output buffer is allocated using @code{gnutls_malloc()} .
2345 If the structure is PEM encoded, it will have a header
2346 of "BEGIN CERTIFICATE".
2348 @strong{Returns:} In case of failure a negative error code will be
2349 returned, and 0 on success.
2351 @strong{Since:} 3.1.3
2354 @subheading gnutls_x509_crt_get_activation_time
2355 @anchor{gnutls_x509_crt_get_activation_time}
2356 @deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert})
2357 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2359 This function will return the time this Certificate was or will be
2362 @strong{Returns:} activation time, or (time_t)-1 on error.
2365 @subheading gnutls_x509_crt_get_authority_info_access
2366 @anchor{gnutls_x509_crt_get_authority_info_access}
2367 @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})
2368 @var{crt}: Holds the certificate
2370 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
2372 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
2374 @var{data}: output data to be freed with @code{gnutls_free()} .
2376 @var{critical}: pointer to output integer that is set to non-0 if the extension is marked as critical (may be @code{NULL} )
2378 Note that a simpler API to access the authority info data is provided
2379 by @code{gnutls_x509_aia_get()} and @code{gnutls_x509_ext_import_aia()} .
2381 This function extracts the Authority Information Access (AIA)
2382 extension, see RFC 5280 section 4.2.2.1 for more information. The
2383 AIA extension holds a sequence of AccessDescription (AD) data.
2385 The @code{seq} input parameter is used to indicate which member of the
2386 sequence the caller is interested in. The first member is 0, the
2387 second member 1 and so on. When the @code{seq} value is out of bounds,
2388 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2390 The type of data returned in @code{data} is specified via @code{what} which
2391 should be @code{gnutls_info_access_what_t} values.
2393 If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the
2394 accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
2396 If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will
2397 hold the accessLocation GeneralName type (e.g.,
2398 "uniformResourceIdentifier").
2400 If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI
2401 data. Requesting this @code{what} value leads to an error if the
2402 accessLocation is not of the "uniformResourceIdentifier" type.
2404 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
2405 Requesting this @code{what} value leads to an error if the accessMethod
2406 is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
2407 the "uniformResourceIdentifier" type.
2409 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
2410 URI. Requesting this @code{what} value leads to an error if the
2411 accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
2412 accessLocation is not of the "uniformResourceIdentifier" type.
2414 More @code{what} values may be allocated in the future as needed.
2416 If @code{data} is NULL, the function does the same without storing the
2417 output data, that is, it will set @code{critical} and do error checking
2420 The value of the critical flag is returned in * @code{critical} . Supply a
2421 NULL @code{critical} if you want the function to make sure the extension
2422 is non-critical, as required by RFC 5280.
2424 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on
2425 invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is
2426 incorrectly marked as critical (use a non-NULL @code{critical} to
2427 override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does
2428 not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a
2429 negative error code.
2434 @subheading gnutls_x509_crt_get_authority_key_gn_serial
2435 @anchor{gnutls_x509_crt_get_authority_key_gn_serial}
2436 @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})
2437 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2439 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2441 @var{alt}: is the place where the alternative name will be copied to
2443 @var{alt_size}: holds the size of alt.
2445 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2447 @var{serial}: buffer to store the serial number (may be null)
2449 @var{serial_size}: Holds the size of the serial field (may be null)
2451 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2453 This function will return the X.509 authority key
2454 identifier when stored as a general name (authorityCertIssuer)
2457 Because more than one general names might be stored
2458 @code{seq} can be used as a counter to request them all until
2459 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2461 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2462 if the extension is not present, otherwise a negative error value.
2467 @subheading gnutls_x509_crt_get_authority_key_id
2468 @anchor{gnutls_x509_crt_get_authority_key_id}
2469 @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})
2470 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2472 @var{id}: The place where the identifier will be copied
2474 @var{id_size}: Holds the size of the id field.
2476 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2478 This function will return the X.509v3 certificate authority's key
2479 identifier. This is obtained by the X.509 Authority Key
2480 identifier extension field (2.5.29.35). Note that this function
2481 only returns the keyIdentifier field of the extension and
2482 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
2483 the name and serial number of the certificate. In that case
2484 @code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used.
2486 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2487 if the extension is not present, otherwise a negative error value.
2490 @subheading gnutls_x509_crt_get_basic_constraints
2491 @anchor{gnutls_x509_crt_get_basic_constraints}
2492 @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})
2493 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2495 @var{critical}: will be non-zero if the extension is marked as critical
2497 @var{ca}: pointer to output integer indicating CA status, may be NULL,
2498 value is 1 if the certificate CA flag is set, 0 otherwise.
2500 @var{pathlen}: pointer to output integer indicating path length (may be
2501 NULL), non-negative error codes indicate a present pathLenConstraint
2502 field and the actual value, -1 indicate that the field is absent.
2504 This function will read the certificate's basic constraints, and
2505 return the certificates CA status. It reads the basicConstraints
2506 X.509 extension (2.5.29.19).
2508 @strong{Returns:} If the certificate is a CA a positive value will be
2509 returned, or (0) if the certificate does not have CA flag set. A
2510 negative error code may be returned in case of errors. If the
2511 certificate does not contain the basicConstraints extension
2512 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2515 @subheading gnutls_x509_crt_get_ca_status
2516 @anchor{gnutls_x509_crt_get_ca_status}
2517 @deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical})
2518 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2520 @var{critical}: will be non-zero if the extension is marked as critical
2522 This function will return certificates CA status, by reading the
2523 basicConstraints X.509 extension (2.5.29.19). If the certificate is
2524 a CA a positive value will be returned, or (0) if the certificate
2525 does not have CA flag set.
2527 Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the
2528 pathLenConstraint field too.
2530 @strong{Returns:} A negative error code may be returned in case of parsing error.
2531 If the certificate does not contain the basicConstraints extension
2532 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
2535 @subheading gnutls_x509_crt_get_crl_dist_points
2536 @anchor{gnutls_x509_crt_get_crl_dist_points}
2537 @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})
2538 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2540 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
2542 @var{san}: is the place where the distribution point will be copied to
2544 @var{san_size}: holds the size of ret.
2546 @var{reason_flags}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
2548 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2550 This function retrieves the CRL distribution points (2.5.29.31),
2551 contained in the given certificate in the X509v3 Certificate
2554 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if
2555 @code{ret_size} is not enough to hold the distribution point, or the
2556 type of the distribution point if everything was ok. The type is
2557 one of the enumerated @code{gnutls_x509_subject_alt_name_t} . If the
2558 certificate does not have an Alternative name with the specified
2559 sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is
2563 @subheading gnutls_x509_crt_get_dn
2564 @anchor{gnutls_x509_crt_get_dn}
2565 @deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2566 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2568 @var{buf}: a pointer to a structure to hold the name (may be null)
2570 @var{buf_size}: initially holds the size of @code{buf}
2572 This function will copy the name of the Certificate in the provided
2573 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2574 described in RFC4514. The output string will be ASCII or UTF-8
2575 encoded, depending on the certificate data.
2577 If @code{buf} is null then only the size will be filled.
2579 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2580 long enough, and in that case the @code{buf_size} will be updated
2581 with the required size. On success 0 is returned.
2584 @subheading gnutls_x509_crt_get_dn2
2585 @anchor{gnutls_x509_crt_get_dn2}
2586 @deftypefun {int} {gnutls_x509_crt_get_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
2587 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2589 @var{dn}: a pointer to a structure to hold the name
2591 This function will allocate buffer and copy the name of the Certificate.
2592 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2593 described in RFC4514. The output string will be ASCII or UTF-8
2594 encoded, depending on the certificate data.
2596 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2597 negative error value. and a negative error code on error.
2599 @strong{Since:} 3.1.10
2602 @subheading gnutls_x509_crt_get_dn_by_oid
2603 @anchor{gnutls_x509_crt_get_dn_by_oid}
2604 @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})
2605 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2607 @var{oid}: holds an Object Identified in null terminated string
2609 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2611 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
2613 @var{buf}: a pointer where the DN part will be copied (may be null).
2615 @var{buf_size}: initially holds the size of @code{buf}
2617 This function will extract the part of the name of the Certificate
2618 subject specified by the given OID. The output, if the raw flag is
2619 not used, will be encoded as described in RFC4514. Thus a string
2620 that is ASCII or UTF-8 encoded, depending on the certificate data.
2622 Some helper macros with popular OIDs can be found in gnutls/x509.h
2623 If raw flag is (0), this function will only return known OIDs as
2624 text. Other OIDs will be DER encoded, as described in RFC4514 --
2625 in hex format with a '#' prefix. You can check about known OIDs
2626 using @code{gnutls_x509_dn_oid_known()} .
2628 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
2629 @code{buf_size} will not include the null character.
2631 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2632 long enough, and in that case the @code{buf_size} will be updated with
2633 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2634 are no data in the current index. On success 0 is returned.
2637 @subheading gnutls_x509_crt_get_dn_oid
2638 @anchor{gnutls_x509_crt_get_dn_oid}
2639 @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})
2640 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2642 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2644 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2646 @var{oid_size}: initially holds the size of @code{oid}
2648 This function will extract the OIDs of the name of the Certificate
2649 subject specified by the given index.
2651 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
2652 account for the trailing null.
2654 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2655 long enough, and in that case the @code{buf_size} will be updated with
2656 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2657 are no data in the current index. On success 0 is returned.
2660 @subheading gnutls_x509_crt_get_expiration_time
2661 @anchor{gnutls_x509_crt_get_expiration_time}
2662 @deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert})
2663 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2665 This function will return the time this Certificate was or will be
2668 The no well defined expiration time can be checked against with the
2669 @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION} macro.
2671 @strong{Returns:} expiration time, or (time_t)-1 on error.
2674 @subheading gnutls_x509_crt_get_extension_by_oid
2675 @anchor{gnutls_x509_crt_get_extension_by_oid}
2676 @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})
2677 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2679 @var{oid}: holds an Object Identified in null terminated string
2681 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2683 @var{buf}: a pointer to a structure to hold the name (may be null)
2685 @var{buf_size}: initially holds the size of @code{buf}
2687 @var{critical}: will be non-zero if the extension is marked as critical
2689 This function will return the extension specified by the OID in the
2690 certificate. The extensions will be returned as binary data DER
2691 encoded, in the provided buffer.
2693 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2694 otherwise a negative error code is returned. If the certificate does not
2695 contain the specified extension
2696 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2699 @subheading gnutls_x509_crt_get_extension_data
2700 @anchor{gnutls_x509_crt_get_extension_data}
2701 @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})
2702 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2704 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2706 @var{data}: a pointer to a structure to hold the data (may be null)
2708 @var{sizeof_data}: initially holds the size of @code{data}
2710 This function will return the requested extension data in the
2711 certificate. The extension data will be stored in the
2714 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and
2715 critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead,
2716 if you want to get data indexed by the extension OID rather than
2719 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2720 otherwise a negative error code is returned. If you have reached the
2721 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2725 @subheading gnutls_x509_crt_get_extension_data2
2726 @anchor{gnutls_x509_crt_get_extension_data2}
2727 @deftypefun {int} {gnutls_x509_crt_get_extension_data2} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, gnutls_datum_t * @var{data})
2728 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2730 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
2732 @var{data}: will contain the extension DER-encoded data
2734 This function will return the requested by the index extension data in the
2735 certificate. The extension data will be allocated using
2736 @code{gnutls_malloc()} .
2738 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
2740 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2741 otherwise a negative error code is returned. If you have reached the
2742 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2746 @subheading gnutls_x509_crt_get_extension_info
2747 @anchor{gnutls_x509_crt_get_extension_info}
2748 @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})
2749 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2751 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2753 @var{oid}: a pointer to a structure to hold the OID
2755 @var{oid_size}: initially holds the maximum size of @code{oid} , on return
2756 holds actual size of @code{oid} .
2758 @var{critical}: output variable with critical flag, may be NULL.
2760 This function will return the requested extension OID in the
2761 certificate, and the critical flag for it. The extension OID will
2762 be stored as a string in the provided buffer. Use
2763 @code{gnutls_x509_crt_get_extension()} to extract the data.
2765 If the buffer provided is not long enough to hold the output, then
2766 @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
2767 returned. The @code{oid} returned will be null terminated, although
2768 @code{oid_size} will not account for the trailing null.
2770 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2771 otherwise a negative error code is returned. If you have reached the
2772 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2776 @subheading gnutls_x509_crt_get_extension_oid
2777 @anchor{gnutls_x509_crt_get_extension_oid}
2778 @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})
2779 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2781 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2783 @var{oid}: a pointer to a structure to hold the OID (may be null)
2785 @var{oid_size}: initially holds the size of @code{oid}
2787 This function will return the requested extension OID in the certificate.
2788 The extension OID will be stored as a string in the provided buffer.
2790 The @code{oid} returned will be null terminated, although @code{oid_size} will not
2791 account for the trailing null.
2793 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2794 otherwise a negative error code is returned. If you have reached the
2795 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2799 @subheading gnutls_x509_crt_get_fingerprint
2800 @anchor{gnutls_x509_crt_get_fingerprint}
2801 @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})
2802 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2804 @var{algo}: is a digest algorithm
2806 @var{buf}: a pointer to a structure to hold the fingerprint (may be null)
2808 @var{buf_size}: initially holds the size of @code{buf}
2810 This function will calculate and copy the certificate's fingerprint
2811 in the provided buffer. The fingerprint is a hash of the DER-encoded
2812 data of the certificate.
2814 If the buffer is null then only the size will be filled.
2816 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2817 not long enough, and in that case the *buf_size will be updated
2818 with the required size. On success 0 is returned.
2821 @subheading gnutls_x509_crt_get_issuer
2822 @anchor{gnutls_x509_crt_get_issuer}
2823 @deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2824 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2826 @var{dn}: output variable with pointer to uint8_t DN
2828 Return the Certificate's Issuer DN as a @code{gnutls_x509_dn_t} data type,
2829 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
2831 Note that @code{dn} should be treated as constant. Because it points
2832 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
2835 @strong{Returns:} Returns 0 on success, or an error code.
2838 @subheading gnutls_x509_crt_get_issuer_alt_name
2839 @anchor{gnutls_x509_crt_get_issuer_alt_name}
2840 @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})
2841 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2843 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2845 @var{ian}: is the place where the alternative name will be copied to
2847 @var{ian_size}: holds the size of ian.
2849 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2851 This function retrieves the Issuer Alternative Name (2.5.29.18),
2852 contained in the given certificate in the X509v3 Certificate
2855 When the SAN type is otherName, it will extract the data in the
2856 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2857 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2858 the corresponding OID and the "virtual" SAN types (e.g.,
2859 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
2861 If an otherName OID is known, the data will be decoded. Otherwise
2862 the returned data will be DER encoded, and you will have to decode
2863 it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer
2864 AltName is recognized.
2866 @strong{Returns:} the alternative issuer name type on success, one of the
2867 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2868 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2869 to hold the value. In that case @code{ian_size} will be updated with
2870 the required size. If the certificate does not have an
2871 Alternative name with the specified sequence number then
2872 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2874 @strong{Since:} 2.10.0
2877 @subheading gnutls_x509_crt_get_issuer_alt_name2
2878 @anchor{gnutls_x509_crt_get_issuer_alt_name2}
2879 @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})
2880 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2882 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2884 @var{ian}: is the place where the alternative name will be copied to
2886 @var{ian_size}: holds the size of ret.
2888 @var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2890 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2892 This function will return the alternative names, contained in the
2893 given certificate. It is the same as
2894 @code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it
2895 will return the type of the alternative name in @code{ian_type} even if
2896 the function fails for some reason (i.e. the buffer provided is
2899 @strong{Returns:} the alternative issuer name type on success, one of the
2900 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2901 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2902 to hold the value. In that case @code{ian_size} will be updated with
2903 the required size. If the certificate does not have an
2904 Alternative name with the specified sequence number then
2905 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2907 @strong{Since:} 2.10.0
2910 @subheading gnutls_x509_crt_get_issuer_alt_othername_oid
2911 @anchor{gnutls_x509_crt_get_issuer_alt_othername_oid}
2912 @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})
2913 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2915 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2917 @var{ret}: is the place where the otherName OID will be copied to
2919 @var{ret_size}: holds the size of ret.
2921 This function will extract the type OID of an otherName Subject
2922 Alternative Name, contained in the given certificate, and return
2923 the type as an enumerated element.
2925 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
2926 account for the trailing null.
2928 This function is only useful if
2929 @code{gnutls_x509_crt_get_issuer_alt_name()} returned
2930 @code{GNUTLS_SAN_OTHERNAME} .
2932 @strong{Returns:} the alternative issuer name type on success, one of the
2933 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2934 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2935 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
2936 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2937 @code{ret_size} is not large enough to hold the value. In that case
2938 @code{ret_size} will be updated with the required size. If the
2939 certificate does not have an Alternative name with the specified
2940 sequence number and with the otherName type then
2941 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2943 @strong{Since:} 2.10.0
2946 @subheading gnutls_x509_crt_get_issuer_dn
2947 @anchor{gnutls_x509_crt_get_issuer_dn}
2948 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2949 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2951 @var{buf}: a pointer to a structure to hold the name (may be null)
2953 @var{buf_size}: initially holds the size of @code{buf}
2955 This function will copy the name of the Certificate issuer in the
2956 provided buffer. The name will be in the form
2957 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
2958 will be ASCII or UTF-8 encoded, depending on the certificate data.
2960 If @code{buf} is null then only the size will be filled.
2962 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2963 long enough, and in that case the @code{buf_size} will be updated with
2964 the required size. On success 0 is returned.
2967 @subheading gnutls_x509_crt_get_issuer_dn2
2968 @anchor{gnutls_x509_crt_get_issuer_dn2}
2969 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
2970 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2972 @var{dn}: a pointer to a structure to hold the name
2974 This function will allocate buffer and copy the name of issuer of the Certificate.
2975 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2976 described in RFC4514. The output string will be ASCII or UTF-8
2977 encoded, depending on the certificate data.
2979 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2980 negative error value. and a negative error code on error.
2982 @strong{Since:} 3.1.10
2985 @subheading gnutls_x509_crt_get_issuer_dn_by_oid
2986 @anchor{gnutls_x509_crt_get_issuer_dn_by_oid}
2987 @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})
2988 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2990 @var{oid}: holds an Object Identified in null terminated string
2992 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2994 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
2996 @var{buf}: a pointer to a structure to hold the name (may be null)
2998 @var{buf_size}: initially holds the size of @code{buf}
3000 This function will extract the part of the name of the Certificate
3001 issuer specified by the given OID. The output, if the raw flag is not
3002 used, will be encoded as described in RFC4514. Thus a string that is
3003 ASCII or UTF-8 encoded, depending on the certificate data.
3005 Some helper macros with popular OIDs can be found in gnutls/x509.h
3006 If raw flag is (0), this function will only return known OIDs as
3007 text. Other OIDs will be DER encoded, as described in RFC4514 --
3008 in hex format with a '#' prefix. You can check about known OIDs
3009 using @code{gnutls_x509_dn_oid_known()} .
3011 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
3012 @code{buf_size} will not include the null character.
3014 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
3015 long enough, and in that case the @code{buf_size} will be updated with
3016 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
3017 are no data in the current index. On success 0 is returned.
3020 @subheading gnutls_x509_crt_get_issuer_dn_oid
3021 @anchor{gnutls_x509_crt_get_issuer_dn_oid}
3022 @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})
3023 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3025 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
3027 @var{oid}: a pointer to a buffer to hold the OID (may be null)
3029 @var{oid_size}: initially holds the size of @code{oid}
3031 This function will extract the OIDs of the name of the Certificate
3032 issuer specified by the given index.
3034 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
3035 account for the trailing null.
3037 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
3038 long enough, and in that case the @code{buf_size} will be updated with
3039 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
3040 are no data in the current index. On success 0 is returned.
3043 @subheading gnutls_x509_crt_get_issuer_unique_id
3044 @anchor{gnutls_x509_crt_get_issuer_unique_id}
3045 @deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
3046 @var{crt}: Holds the certificate
3048 @var{buf}: user allocated memory buffer, will hold the unique id
3050 @var{buf_size}: size of user allocated memory buffer (on input), will hold
3051 actual size of the unique ID on return.
3053 This function will extract the issuerUniqueID value (if present) for
3054 the given certificate.
3056 If the user allocated memory buffer is not large enough to hold the
3057 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
3058 returned, and buf_size will be set to the actual length.
3060 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3062 @strong{Since:} 2.12.0
3065 @subheading gnutls_x509_crt_get_key_id
3066 @anchor{gnutls_x509_crt_get_key_id}
3067 @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})
3068 @var{crt}: Holds the certificate
3070 @var{flags}: should be 0 for now
3072 @var{output_data}: will contain the key ID
3074 @var{output_data_size}: holds the size of output_data (and will be
3075 replaced by the actual size of parameters)
3077 This function will return a unique ID that depends on the public
3078 key parameters. This ID can be used in checking whether a
3079 certificate corresponds to the given private key.
3081 If the buffer provided is not long enough to hold the output, then
3082 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3083 be returned. The output will normally be a SHA-1 hash output,
3086 @strong{Returns:} In case of failure a negative error code will be
3087 returned, and 0 on success.
3090 @subheading gnutls_x509_crt_get_key_purpose_oid
3091 @anchor{gnutls_x509_crt_get_key_purpose_oid}
3092 @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})
3093 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3095 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
3097 @var{oid}: a pointer to a buffer to hold the OID (may be null)
3099 @var{oid_size}: initially holds the size of @code{oid}
3101 @var{critical}: output flag to indicate criticality of extension
3103 This function will extract the key purpose OIDs of the Certificate
3104 specified by the given index. These are stored in the Extended Key
3105 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
3106 human readable names.
3108 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
3109 account for the trailing null.
3111 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
3112 not long enough, and in that case the *oid_size will be updated
3113 with the required size. On success 0 is returned.
3116 @subheading gnutls_x509_crt_get_key_usage
3117 @anchor{gnutls_x509_crt_get_key_usage}
3118 @deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
3119 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3121 @var{key_usage}: where the key usage bits will be stored
3123 @var{critical}: will be non-zero if the extension is marked as critical
3125 This function will return certificate's key usage, by reading the
3126 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
3127 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
3128 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
3129 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
3130 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
3131 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
3133 @strong{Returns:} the certificate key usage, or a negative error code in case of
3134 parsing error. If the certificate does not contain the keyUsage
3135 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
3139 @subheading gnutls_x509_crt_get_name_constraints
3140 @anchor{gnutls_x509_crt_get_name_constraints}
3141 @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})
3142 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
3144 @var{nc}: The nameconstraints intermediate structure
3146 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
3148 @var{critical}: the extension status
3150 This function will return an intermediate structure containing
3151 the name constraints of the provided CA certificate. That
3152 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
3153 to verify whether a server's name is in accordance with the constraints.
3155 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
3156 the @code{nc} structure is empty
3157 this function will behave identically as if the flag was not set.
3158 Otherwise if there are elements in the @code{nc} structure then only the
3159 excluded constraints will be appended to the constraints.
3161 Note that @code{nc} must be initialized prior to calling this function.
3163 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3164 if the extension is not present, otherwise a negative error value.
3166 @strong{Since:} 3.3.0
3169 @subheading gnutls_x509_crt_get_pk_algorithm
3170 @anchor{gnutls_x509_crt_get_pk_algorithm}
3171 @deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits})
3172 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3174 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
3176 This function will return the public key algorithm of an X.509
3179 If bits is non null, it should have enough size to hold the parameters
3180 size in bits. For RSA the bits returned is the modulus.
3181 For DSA the bits returned are of the public
3184 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3185 success, or a negative error code on error.
3188 @subheading gnutls_x509_crt_get_pk_dsa_raw
3189 @anchor{gnutls_x509_crt_get_pk_dsa_raw}
3190 @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})
3191 @var{crt}: Holds the certificate
3193 @var{p}: will hold the p
3195 @var{q}: will hold the q
3197 @var{g}: will hold the g
3199 @var{y}: will hold the y
3201 This function will export the DSA public key's parameters found in
3202 the given certificate. The new parameters will be allocated using
3203 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3205 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3208 @subheading gnutls_x509_crt_get_pk_rsa_raw
3209 @anchor{gnutls_x509_crt_get_pk_rsa_raw}
3210 @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})
3211 @var{crt}: Holds the certificate
3213 @var{m}: will hold the modulus
3215 @var{e}: will hold the public exponent
3217 This function will export the RSA public key's parameters found in
3218 the given structure. The new parameters will be allocated using
3219 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3221 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3224 @subheading gnutls_x509_crt_get_policy
3225 @anchor{gnutls_x509_crt_get_policy}
3226 @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})
3227 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
3229 @var{indx}: This specifies which policy to return. Use (0) to get the first one.
3231 @var{policy}: A pointer to a policy structure.
3233 @var{critical}: will be non-zero if the extension is marked as critical
3235 This function will extract the certificate policy (extension 2.5.29.32)
3236 specified by the given index.
3238 The policy returned by this function must be deinitialized by using
3239 @code{gnutls_x509_policy_release()} .
3241 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3242 if the extension is not present, otherwise a negative error value.
3244 @strong{Since:} 3.1.5
3247 @subheading gnutls_x509_crt_get_private_key_usage_period
3248 @anchor{gnutls_x509_crt_get_private_key_usage_period}
3249 @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})
3250 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3252 @var{activation}: The activation time
3254 @var{expiration}: The expiration time
3256 @var{critical}: the extension status
3258 This function will return the expiration and activation
3259 times of the private key of the certificate. It relies on
3260 the PKIX extension 2.5.29.16 being present.
3262 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3263 if the extension is not present, otherwise a negative error value.
3266 @subheading gnutls_x509_crt_get_proxy
3267 @anchor{gnutls_x509_crt_get_proxy}
3268 @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})
3269 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3271 @var{critical}: will be non-zero if the extension is marked as critical
3273 @var{pathlen}: pointer to output integer indicating path length (may be
3274 NULL), non-negative error codes indicate a present pCPathLenConstraint
3275 field and the actual value, -1 indicate that the field is absent.
3277 @var{policyLanguage}: output variable with OID of policy language
3279 @var{policy}: output variable with policy data
3281 @var{sizeof_policy}: output variable size of policy data
3283 This function will get information from a proxy certificate. It
3284 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
3286 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
3287 otherwise a negative error code is returned.
3290 @subheading gnutls_x509_crt_get_raw_dn
3291 @anchor{gnutls_x509_crt_get_raw_dn}
3292 @deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3293 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3295 @var{dn}: will hold the starting point of the DN
3297 This function will return a pointer to the DER encoded DN structure and
3298 the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3300 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3301 negative error value. or a negative error code on error.
3304 @subheading gnutls_x509_crt_get_raw_issuer_dn
3305 @anchor{gnutls_x509_crt_get_raw_issuer_dn}
3306 @deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3307 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3309 @var{dn}: will hold the starting point of the DN
3311 This function will return a pointer to the DER encoded DN structure
3312 and the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3314 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3315 negative error value.or a negative error code on error.
3318 @subheading gnutls_x509_crt_get_serial
3319 @anchor{gnutls_x509_crt_get_serial}
3320 @deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size})
3321 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3323 @var{result}: The place where the serial number will be copied
3325 @var{result_size}: Holds the size of the result field.
3327 This function will return the X.509 certificate's serial number.
3328 This is obtained by the X509 Certificate serialNumber field. Serial
3329 is not always a 32 or 64bit number. Some CAs use large serial
3330 numbers, thus it may be wise to handle it as something uint8_t.
3332 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3333 negative error value.
3336 @subheading gnutls_x509_crt_get_signature
3337 @anchor{gnutls_x509_crt_get_signature}
3338 @deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sig_size})
3339 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3341 @var{sig}: a pointer where the signature part will be copied (may be null).
3343 @var{sig_size}: initially holds the size of @code{sig}
3345 This function will extract the signature field of a certificate.
3347 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3348 negative error value. and a negative error code on error.
3351 @subheading gnutls_x509_crt_get_signature_algorithm
3352 @anchor{gnutls_x509_crt_get_signature_algorithm}
3353 @deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert})
3354 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3356 This function will return a value of the @code{gnutls_sign_algorithm_t}
3357 enumeration that is the signature algorithm that has been used to
3358 sign this certificate.
3360 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code on
3364 @subheading gnutls_x509_crt_get_subject
3365 @anchor{gnutls_x509_crt_get_subject}
3366 @deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
3367 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3369 @var{dn}: output variable with pointer to uint8_t DN.
3371 Return the Certificate's Subject DN as a @code{gnutls_x509_dn_t} data type,
3372 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
3374 Note that @code{dn} should be treated as constant. Because it points
3375 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
3378 @strong{Returns:} Returns 0 on success, or an error code.
3381 @subheading gnutls_x509_crt_get_subject_alt_name
3382 @anchor{gnutls_x509_crt_get_subject_alt_name}
3383 @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})
3384 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3386 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3388 @var{san}: is the place where the alternative name will be copied to
3390 @var{san_size}: holds the size of san.
3392 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3394 This function retrieves the Alternative Name (2.5.29.17), contained
3395 in the given certificate in the X509v3 Certificate Extensions.
3397 When the SAN type is otherName, it will extract the data in the
3398 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
3399 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
3400 the corresponding OID and the "virtual" SAN types (e.g.,
3401 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
3403 If an otherName OID is known, the data will be decoded. Otherwise
3404 the returned data will be DER encoded, and you will have to decode
3405 it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is
3408 @strong{Returns:} the alternative subject name type on success, one of the
3409 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3410 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to
3411 hold the value. In that case @code{san_size} will be updated with the
3412 required size. If the certificate does not have an Alternative
3413 name with the specified sequence number then
3414 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3417 @subheading gnutls_x509_crt_get_subject_alt_name2
3418 @anchor{gnutls_x509_crt_get_subject_alt_name2}
3419 @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})
3420 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3422 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3424 @var{san}: is the place where the alternative name will be copied to
3426 @var{san_size}: holds the size of ret.
3428 @var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
3430 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3432 This function will return the alternative names, contained in the
3433 given certificate. It is the same as
3434 @code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it
3435 will return the type of the alternative name in @code{san_type} even if
3436 the function fails for some reason (i.e. the buffer provided is
3439 @strong{Returns:} the alternative subject name type on success, one of the
3440 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3441 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough
3442 to hold the value. In that case @code{san_size} will be updated with
3443 the required size. If the certificate does not have an
3444 Alternative name with the specified sequence number then
3445 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3448 @subheading gnutls_x509_crt_get_subject_alt_othername_oid
3449 @anchor{gnutls_x509_crt_get_subject_alt_othername_oid}
3450 @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})
3451 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3453 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3455 @var{oid}: is the place where the otherName OID will be copied to
3457 @var{oid_size}: holds the size of ret.
3459 This function will extract the type OID of an otherName Subject
3460 Alternative Name, contained in the given certificate, and return
3461 the type as an enumerated element.
3463 This function is only useful if
3464 @code{gnutls_x509_crt_get_subject_alt_name()} returned
3465 @code{GNUTLS_SAN_OTHERNAME} .
3467 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
3468 account for the trailing null.
3470 @strong{Returns:} the alternative subject name type on success, one of the
3471 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
3472 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
3473 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
3474 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
3475 @code{ian_size} is not large enough to hold the value. In that case
3476 @code{ian_size} will be updated with the required size. If the
3477 certificate does not have an Alternative name with the specified
3478 sequence number and with the otherName type then
3479 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3482 @subheading gnutls_x509_crt_get_subject_key_id
3483 @anchor{gnutls_x509_crt_get_subject_key_id}
3484 @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})
3485 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3487 @var{ret}: The place where the identifier will be copied
3489 @var{ret_size}: Holds the size of the result field.
3491 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3493 This function will return the X.509v3 certificate's subject key
3494 identifier. This is obtained by the X.509 Subject Key identifier
3495 extension field (2.5.29.14).
3497 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3498 if the extension is not present, otherwise a negative error value.
3501 @subheading gnutls_x509_crt_get_subject_unique_id
3502 @anchor{gnutls_x509_crt_get_subject_unique_id}
3503 @deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
3504 @var{crt}: Holds the certificate
3506 @var{buf}: user allocated memory buffer, will hold the unique id
3508 @var{buf_size}: size of user allocated memory buffer (on input), will hold
3509 actual size of the unique ID on return.
3511 This function will extract the subjectUniqueID value (if present) for
3512 the given certificate.
3514 If the user allocated memory buffer is not large enough to hold the
3515 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
3516 returned, and buf_size will be set to the actual length.
3518 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3521 @subheading gnutls_x509_crt_get_version
3522 @anchor{gnutls_x509_crt_get_version}
3523 @deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert})
3524 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3526 This function will return the version of the specified Certificate.
3528 @strong{Returns:} version of certificate, or a negative error code on error.
3531 @subheading gnutls_x509_crt_import
3532 @anchor{gnutls_x509_crt_import}
3533 @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})
3534 @var{cert}: The structure to store the parsed certificate.
3536 @var{data}: The DER or PEM encoded certificate.
3538 @var{format}: One of DER or PEM
3540 This function will convert the given DER or PEM encoded Certificate
3541 to the native gnutls_x509_crt_t format. The output will be stored
3544 If the Certificate is PEM encoded it should have a header of "X509
3545 CERTIFICATE", or "CERTIFICATE".
3547 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3548 negative error value.
3551 @subheading gnutls_x509_crt_init
3552 @anchor{gnutls_x509_crt_init}
3553 @deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert})
3554 @var{cert}: The structure to be initialized
3556 This function will initialize an X.509 certificate structure.
3558 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3559 negative error value.
3562 @subheading gnutls_x509_crt_list_import
3563 @anchor{gnutls_x509_crt_list_import}
3564 @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})
3565 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
3567 @var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
3569 @var{data}: The PEM encoded certificate.
3571 @var{format}: One of DER or PEM.
3573 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3575 This function will convert the given PEM encoded certificate list
3576 to the native gnutls_x509_crt_t format. The output will be stored
3577 in @code{certs} . They will be automatically initialized.
3579 The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause
3580 import to fail if the certificates in the provided buffer are more
3581 than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED}
3582 flag will cause the function to fail if the provided list is not
3583 sorted from subject to issuer.
3585 If the Certificate is PEM encoded it should have a header of "X509
3586 CERTIFICATE", or "CERTIFICATE".
3588 @strong{Returns:} the number of certificates read or a negative error value.
3591 @subheading gnutls_x509_crt_list_import2
3592 @anchor{gnutls_x509_crt_list_import2}
3593 @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})
3594 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
3596 @var{size}: It will contain the size of the list.
3598 @var{data}: The PEM encoded certificate.
3600 @var{format}: One of DER or PEM.
3602 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3604 This function will convert the given PEM encoded certificate list
3605 to the native gnutls_x509_crt_t format. The output will be stored
3606 in @code{certs} which will allocated and initialized.
3608 If the Certificate is PEM encoded it should have a header of "X509
3609 CERTIFICATE", or "CERTIFICATE".
3611 To deinitialize @code{certs} , you need to deinitialize each crt structure
3612 independently, and use @code{gnutls_free()} at
3614 @strong{Returns:} the number of certificates read or a negative error value.
3619 @subheading gnutls_x509_crt_list_verify
3620 @anchor{gnutls_x509_crt_list_verify}
3621 @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})
3622 @var{cert_list}: is the certificate list to be verified
3624 @var{cert_list_length}: holds the number of certificate in cert_list
3626 @var{CA_list}: is the CA list which will be used in verification
3628 @var{CA_list_length}: holds the number of CA certificate in CA_list
3630 @var{CRL_list}: holds a list of CRLs.
3632 @var{CRL_list_length}: the length of CRL list.
3634 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3636 @var{verify}: will hold the certificate verification output.
3638 This function will try to verify the given certificate list and
3639 return its status. If no flags are specified (0), this function
3640 will use the basicConstraints (2.5.29.19) PKIX extension. This
3641 means that only a certificate authority is allowed to sign a
3644 You must also check the peer's name in order to check if the verified
3645 certificate belongs to the actual peer.
3647 The certificate verification output will be put in @code{verify} and will
3648 be one or more of the gnutls_certificate_status_t enumerated
3649 elements bitwise or'd. For a more detailed verification status use
3650 @code{gnutls_x509_crt_verify()} per list element.
3652 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3653 negative error value.
3656 @subheading gnutls_x509_crt_print
3657 @anchor{gnutls_x509_crt_print}
3658 @deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
3659 @var{cert}: The structure to be printed
3661 @var{format}: Indicate the format to use
3663 @var{out}: Newly allocated datum with (0) terminated string.
3665 This function will pretty print a X.509 certificate, suitable for
3668 If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the
3669 certificate will be output, on multiple lines. The
3670 @code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some
3671 selected fields, which is useful for logging purposes.
3673 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
3675 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3676 negative error value.
3679 @subheading gnutls_x509_crt_set_activation_time
3680 @anchor{gnutls_x509_crt_set_activation_time}
3681 @deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time})
3682 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3684 @var{act_time}: The actual time
3686 This function will set the time this Certificate was or will be
3689 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3690 negative error value.
3693 @subheading gnutls_x509_crt_set_authority_info_access
3694 @anchor{gnutls_x509_crt_set_authority_info_access}
3695 @deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data})
3696 @var{crt}: Holds the certificate
3698 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
3700 @var{data}: output data to be freed with @code{gnutls_free()} .
3702 This function sets the Authority Information Access (AIA)
3703 extension, see RFC 5280 section 4.2.2.1 for more information.
3705 The type of data stored in @code{data} is specified via @code{what} which
3706 should be @code{gnutls_info_access_what_t} values.
3708 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
3709 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
3712 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3713 negative error value.
3718 @subheading gnutls_x509_crt_set_authority_key_id
3719 @anchor{gnutls_x509_crt_set_authority_key_id}
3720 @deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3721 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3723 @var{id}: The key ID
3725 @var{id_size}: Holds the size of the key ID field.
3727 This function will set the X.509 certificate's authority key ID extension.
3728 Only the keyIdentifier field can be set with this function.
3730 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3731 negative error value.
3734 @subheading gnutls_x509_crt_set_basic_constraints
3735 @anchor{gnutls_x509_crt_set_basic_constraints}
3736 @deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint})
3737 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3739 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3741 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
3742 and negative error codes indicate that the pathLenConstraints field should
3745 This function will set the basicConstraints certificate extension.
3747 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3748 negative error value.
3751 @subheading gnutls_x509_crt_set_ca_status
3752 @anchor{gnutls_x509_crt_set_ca_status}
3753 @deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca})
3754 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3756 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3758 This function will set the basicConstraints certificate extension.
3759 Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control
3760 the pathLenConstraint field too.
3762 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3763 negative error value.
3766 @subheading gnutls_x509_crt_set_crl_dist_points
3767 @anchor{gnutls_x509_crt_set_crl_dist_points}
3768 @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})
3769 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3771 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3773 @var{data_string}: The data to be set
3775 @var{reason_flags}: revocation reasons
3777 This function will set the CRL distribution points certificate extension.
3779 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3780 negative error value.
3783 @subheading gnutls_x509_crt_set_crl_dist_points2
3784 @anchor{gnutls_x509_crt_set_crl_dist_points2}
3785 @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})
3786 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3788 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3790 @var{data}: The data to be set
3792 @var{data_size}: The data size
3794 @var{reason_flags}: revocation reasons
3796 This function will set the CRL distribution points certificate extension.
3798 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3799 negative error value.
3801 @strong{Since:} 2.6.0
3804 @subheading gnutls_x509_crt_set_crq
3805 @anchor{gnutls_x509_crt_set_crq}
3806 @deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3807 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3809 @var{crq}: holds a certificate request
3811 This function will set the name and public parameters as well as
3812 the extensions from the given certificate request to the certificate.
3813 Only RSA keys are currently supported.
3815 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3816 negative error value.
3819 @subheading gnutls_x509_crt_set_crq_extensions
3820 @anchor{gnutls_x509_crt_set_crq_extensions}
3821 @deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3822 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3824 @var{crq}: holds a certificate request
3826 This function will set extensions from the given request to the
3829 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3830 negative error value.
3832 @strong{Since:} 2.8.0
3835 @subheading gnutls_x509_crt_set_dn
3836 @anchor{gnutls_x509_crt_set_dn}
3837 @deftypefun {int} {gnutls_x509_crt_set_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
3838 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3840 @var{dn}: a comma separated DN string (RFC4514)
3842 @var{err}: indicates the error position (if any)
3844 This function will set the DN on the provided certificate.
3845 The input string should be plain ASCII or UTF-8 encoded.
3847 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3848 negative error value.
3851 @subheading gnutls_x509_crt_set_dn_by_oid
3852 @anchor{gnutls_x509_crt_set_dn_by_oid}
3853 @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})
3854 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3856 @var{oid}: holds an Object Identifier in a null terminated string
3858 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3860 @var{name}: a pointer to the name
3862 @var{sizeof_name}: holds the size of @code{name}
3864 This function will set the part of the name of the Certificate
3865 subject, specified by the given OID. The input string should be
3866 ASCII or UTF-8 encoded.
3868 Some helper macros with popular OIDs can be found in gnutls/x509.h
3869 With this function you can only set the known OIDs. You can test
3870 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3871 not known (by gnutls) you should properly DER encode your data,
3872 and call this function with @code{raw_flag} set.
3874 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3875 negative error value.
3878 @subheading gnutls_x509_crt_set_expiration_time
3879 @anchor{gnutls_x509_crt_set_expiration_time}
3880 @deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time})
3881 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3883 @var{exp_time}: The actual time
3885 This function will set the time this Certificate will expire.
3886 Setting an expiration time to (time_t)-1 or to @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION}
3887 will set to the no well-defined expiration date value.
3889 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3890 negative error value.
3893 @subheading gnutls_x509_crt_set_extension_by_oid
3894 @anchor{gnutls_x509_crt_set_extension_by_oid}
3895 @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})
3896 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3898 @var{oid}: holds an Object Identified in null terminated string
3900 @var{buf}: a pointer to a DER encoded data
3902 @var{sizeof_buf}: holds the size of @code{buf}
3904 @var{critical}: should be non-zero if the extension is to be marked as critical
3906 This function will set an the extension, by the specified OID, in
3907 the certificate. The extension data should be binary data DER
3910 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3911 negative error value.
3914 @subheading gnutls_x509_crt_set_issuer_alt_name
3915 @anchor{gnutls_x509_crt_set_issuer_alt_name}
3916 @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})
3917 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3919 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3921 @var{data}: The data to be set
3923 @var{data_size}: The size of data to be set
3925 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
3927 This function will set the issuer alternative name certificate
3928 extension. It can set the same types as @code{gnutls_x509_crt_set_subject_alt_name()} .
3930 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3931 negative error value.
3933 @strong{Since:} 3.3.0
3936 @subheading gnutls_x509_crt_set_issuer_dn
3937 @anchor{gnutls_x509_crt_set_issuer_dn}
3938 @deftypefun {int} {gnutls_x509_crt_set_issuer_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
3939 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3941 @var{dn}: a comma separated DN string (RFC4514)
3943 @var{err}: indicates the error position (if any)
3945 This function will set the DN on the provided certificate.
3946 The input string should be plain ASCII or UTF-8 encoded.
3948 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3949 negative error value.
3952 @subheading gnutls_x509_crt_set_issuer_dn_by_oid
3953 @anchor{gnutls_x509_crt_set_issuer_dn_by_oid}
3954 @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})
3955 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3957 @var{oid}: holds an Object Identifier in a null terminated string
3959 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3961 @var{name}: a pointer to the name
3963 @var{sizeof_name}: holds the size of @code{name}
3965 This function will set the part of the name of the Certificate
3966 issuer, specified by the given OID. The input string should be
3967 ASCII or UTF-8 encoded.
3969 Some helper macros with popular OIDs can be found in gnutls/x509.h
3970 With this function you can only set the known OIDs. You can test
3971 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3972 not known (by gnutls) you should properly DER encode your data,
3973 and call this function with @code{raw_flag} set.
3975 Normally you do not need to call this function, since the signing
3976 operation will copy the signer's name as the issuer of the
3979 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3980 negative error value.
3983 @subheading gnutls_x509_crt_set_key
3984 @anchor{gnutls_x509_crt_set_key}
3985 @deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key})
3986 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3988 @var{key}: holds a private key
3990 This function will set the public parameters from the given
3991 private key to the certificate. Only RSA keys are currently
3994 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3995 negative error value.
3998 @subheading gnutls_x509_crt_set_key_purpose_oid
3999 @anchor{gnutls_x509_crt_set_key_purpose_oid}
4000 @deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical})
4001 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4003 @var{oid}: a pointer to a null terminated string that holds the OID
4005 @var{critical}: Whether this extension will be critical or not
4007 This function will set the key purpose OIDs of the Certificate.
4008 These are stored in the Extended Key Usage extension (2.5.29.37)
4009 See the GNUTLS_KP_* definitions for human readable names.
4011 Subsequent calls to this function will append OIDs to the OID list.
4013 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
4014 otherwise a negative error code is returned.
4017 @subheading gnutls_x509_crt_set_key_usage
4018 @anchor{gnutls_x509_crt_set_key_usage}
4019 @deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage})
4020 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4022 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4024 This function will set the keyUsage certificate extension.
4026 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4027 negative error value.
4030 @subheading gnutls_x509_crt_set_name_constraints
4031 @anchor{gnutls_x509_crt_set_name_constraints}
4032 @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})
4033 @var{crt}: The certificate structure
4035 @var{nc}: The nameconstraints structure
4037 @var{critical}: whether this extension will be critical
4039 This function will set the provided name constraints to
4040 the certificate extension list. This extension is always
4043 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4045 @strong{Since:} 3.3.0
4048 @subheading gnutls_x509_crt_set_pin_function
4049 @anchor{gnutls_x509_crt_set_pin_function}
4050 @deftypefun {void} {gnutls_x509_crt_set_pin_function} (gnutls_x509_crt_t @var{crt}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
4051 @var{crt}: The certificate structure
4053 @var{fn}: the callback
4055 @var{userdata}: data associated with the callback
4057 This function will set a callback function to be used when
4058 it is required to access a protected object. This function overrides
4059 the global function set using @code{gnutls_pkcs11_set_pin_function()} .
4061 Note that this callback is currently used only during the import
4062 of a PKCS @code{11} certificate with @code{gnutls_x509_crt_import_pkcs11_url()} .
4064 @strong{Since:} 3.1.0
4067 @subheading gnutls_x509_crt_set_policy
4068 @anchor{gnutls_x509_crt_set_policy}
4069 @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})
4070 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
4072 @var{policy}: A pointer to a policy structure.
4074 @var{critical}: use non-zero if the extension is marked as critical
4076 This function will set the certificate policy extension (2.5.29.32).
4077 Multiple calls to this function append a new policy.
4079 Note the maximum text size for the qualifier @code{GNUTLS_X509_QUALIFIER_NOTICE}
4080 is 200 characters. This function will fail with @code{GNUTLS_E_INVALID_REQUEST}
4081 if this is exceeded.
4083 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4084 negative error value.
4086 @strong{Since:} 3.1.5
4089 @subheading gnutls_x509_crt_set_private_key_usage_period
4090 @anchor{gnutls_x509_crt_set_private_key_usage_period}
4091 @deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration})
4092 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4094 @var{activation}: The activation time
4096 @var{expiration}: The expiration time
4098 This function will set the private key usage period extension (2.5.29.16).
4100 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4101 negative error value.
4104 @subheading gnutls_x509_crt_set_proxy
4105 @anchor{gnutls_x509_crt_set_proxy}
4106 @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})
4107 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4109 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4110 and negative error codes indicate that the pathLenConstraints field should
4113 @var{policyLanguage}: OID describing the language of @code{policy} .
4115 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4117 @var{sizeof_policy}: size of @code{policy} .
4119 This function will set the proxyCertInfo extension.
4121 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4122 negative error value.
4125 @subheading gnutls_x509_crt_set_proxy_dn
4126 @anchor{gnutls_x509_crt_set_proxy_dn}
4127 @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})
4128 @var{crt}: a gnutls_x509_crt_t structure with the new proxy cert
4130 @var{eecrt}: the end entity certificate that will be issuing the proxy
4132 @var{raw_flag}: must be 0, or 1 if the CN is DER encoded
4134 @var{name}: a pointer to the CN name, may be NULL (but MUST then be added later)
4136 @var{sizeof_name}: holds the size of @code{name}
4138 This function will set the subject in @code{crt} to the end entity's
4139 @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy
4140 certificate naming style. Note that if @code{name} is @code{NULL} , you MUST
4141 set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar.
4143 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4144 negative error value.
4147 @subheading gnutls_x509_crt_set_serial
4148 @anchor{gnutls_x509_crt_set_serial}
4149 @deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size})
4150 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4152 @var{serial}: The serial number
4154 @var{serial_size}: Holds the size of the serial field.
4156 This function will set the X.509 certificate's serial number.
4157 While the serial number is an integer, it is often handled
4158 as an opaque field by several CAs. For this reason this function
4159 accepts any kind of data as a serial number. To be consistent
4160 with the X.509/PKIX specifications the provided @code{serial} should be
4161 a big-endian positive number (i.e. it's leftmost bit should be zero).
4163 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4164 negative error value.
4167 @subheading gnutls_x509_crt_set_subject_alt_name
4168 @anchor{gnutls_x509_crt_set_subject_alt_name}
4169 @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})
4170 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4172 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4174 @var{data}: The data to be set
4176 @var{data_size}: The size of data to be set
4178 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
4180 This function will set the subject alternative name certificate
4181 extension. It can set the following types:
4183 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4184 negative error value.
4186 @strong{Since:} 2.6.0
4189 @subheading gnutls_x509_crt_set_subject_alternative_name
4190 @anchor{gnutls_x509_crt_set_subject_alternative_name}
4191 @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})
4192 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4194 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4196 @var{data_string}: The data to be set, a (0) terminated string
4198 This function will set the subject alternative name certificate
4199 extension. This function assumes that data can be expressed as a null
4202 The name of the function is unfortunate since it is incosistent with
4203 @code{gnutls_x509_crt_get_subject_alt_name()} .
4205 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4206 negative error value.
4209 @subheading gnutls_x509_crt_set_subject_key_id
4210 @anchor{gnutls_x509_crt_set_subject_key_id}
4211 @deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4212 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4214 @var{id}: The key ID
4216 @var{id_size}: Holds the size of the subject key ID field.
4218 This function will set the X.509 certificate's subject key ID
4221 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4222 negative error value.
4225 @subheading gnutls_x509_crt_set_version
4226 @anchor{gnutls_x509_crt_set_version}
4227 @deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version})
4228 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4230 @var{version}: holds the version number. For X.509v1 certificates must be 1.
4232 This function will set the version of the certificate. This must
4233 be one for X.509 version 1, and so on. Plain certificates without
4234 extensions must have version set to one.
4236 To create well-formed certificates, you must specify version 3 if
4237 you use any certificate extensions. Extensions are created by
4238 functions such as @code{gnutls_x509_crt_set_subject_alt_name()}
4239 or @code{gnutls_x509_crt_set_key_usage()} .
4241 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4242 negative error value.
4245 @subheading gnutls_x509_crt_sign
4246 @anchor{gnutls_x509_crt_sign}
4247 @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})
4248 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4250 @var{issuer}: is the certificate of the certificate issuer
4252 @var{issuer_key}: holds the issuer's private key
4254 This function is the same a @code{gnutls_x509_crt_sign2()} with no flags,
4255 and SHA1 as the hash algorithm.
4257 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4258 negative error value.
4261 @subheading gnutls_x509_crt_sign2
4262 @anchor{gnutls_x509_crt_sign2}
4263 @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})
4264 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4266 @var{issuer}: is the certificate of the certificate issuer
4268 @var{issuer_key}: holds the issuer's private key
4270 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
4272 @var{flags}: must be 0
4274 This function will sign the certificate with the issuer's private key, and
4275 will copy the issuer's information into the certificate.
4277 This must be the last step in a certificate generation since all
4278 the previously set parameters are now signed.
4280 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4281 negative error value.
4284 @subheading gnutls_x509_crt_verify
4285 @anchor{gnutls_x509_crt_verify}
4286 @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})
4287 @var{cert}: is the certificate to be verified
4289 @var{CA_list}: is one certificate that is considered to be trusted one
4291 @var{CA_list_length}: holds the number of CA certificate in CA_list
4293 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
4295 @var{verify}: will hold the certificate verification output.
4297 This function will try to verify the given certificate and return
4298 its status. Note that a verification error does not imply a negative
4299 return status. In that case the @code{verify} status is set.
4301 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4302 negative error value.
4305 @subheading gnutls_x509_dn_deinit
4306 @anchor{gnutls_x509_dn_deinit}
4307 @deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn})
4308 @var{dn}: a DN uint8_t object pointer.
4310 This function deallocates the DN object as returned by
4311 @code{gnutls_x509_dn_import()} .
4313 @strong{Since:} 2.4.0
4316 @subheading gnutls_x509_dn_export
4317 @anchor{gnutls_x509_dn_export}
4318 @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})
4319 @var{dn}: Holds the uint8_t DN object
4321 @var{format}: the format of output params. One of PEM or DER.
4323 @var{output_data}: will contain a DN PEM or DER encoded
4325 @var{output_data_size}: holds the size of output_data (and will be
4326 replaced by the actual size of parameters)
4328 This function will export the DN to DER or PEM format.
4330 If the buffer provided is not long enough to hold the output, then
4331 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
4334 If the structure is PEM encoded, it will have a header
4337 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4338 negative error value.
4341 @subheading gnutls_x509_dn_export2
4342 @anchor{gnutls_x509_dn_export2}
4343 @deftypefun {int} {gnutls_x509_dn_export2} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
4344 @var{dn}: Holds the uint8_t DN object
4346 @var{format}: the format of output params. One of PEM or DER.
4348 @var{out}: will contain a DN PEM or DER encoded
4350 This function will export the DN to DER or PEM format.
4352 The output buffer is allocated using @code{gnutls_malloc()} .
4354 If the structure is PEM encoded, it will have a header
4357 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4358 negative error value.
4360 @strong{Since:} 3.1.3
4363 @subheading gnutls_x509_dn_get_rdn_ava
4364 @anchor{gnutls_x509_dn_get_rdn_ava}
4365 @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})
4366 @var{dn}: a pointer to DN
4368 @var{irdn}: index of RDN
4370 @var{iava}: index of AVA.
4372 @var{ava}: Pointer to structure which will hold output information.
4374 Get pointers to data within the DN. The format of the @code{ava} structure
4377 struct gnutls_x509_ava_st @{
4379 gnutls_datum_t value;
4380 unsigned long value_tag;
4383 The X.509 distinguished name is a sequence of sequences of strings
4384 and this is what the @code{irdn} and @code{iava} indexes model.
4386 Note that @code{ava} will contain pointers into the @code{dn} structure which
4387 in turns points to the original certificate. Thus you should not
4388 modify any data or deallocate any of those.
4390 This is a low-level function that requires the caller to do the
4391 value conversions when necessary (e.g. from UCS-2).
4393 @strong{Returns:} Returns 0 on success, or an error code.
4396 @subheading gnutls_x509_dn_import
4397 @anchor{gnutls_x509_dn_import}
4398 @deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data})
4399 @var{dn}: the structure that will hold the imported DN
4401 @var{data}: should contain a DER encoded RDN sequence
4403 This function parses an RDN sequence and stores the result to a
4404 @code{gnutls_x509_dn_t} structure. The structure must have been initialized
4405 with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to
4408 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4409 negative error value.
4411 @strong{Since:} 2.4.0
4414 @subheading gnutls_x509_dn_init
4415 @anchor{gnutls_x509_dn_init}
4416 @deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn})
4417 @var{dn}: the object to be initialized
4419 This function initializes a @code{gnutls_x509_dn_t} structure.
4421 The object returned must be deallocated using
4422 @code{gnutls_x509_dn_deinit()} .
4424 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4425 negative error value.
4427 @strong{Since:} 2.4.0
4430 @subheading gnutls_x509_dn_oid_known
4431 @anchor{gnutls_x509_dn_oid_known}
4432 @deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid})
4433 @var{oid}: holds an Object Identifier in a null terminated string
4435 This function will inform about known DN OIDs. This is useful since
4436 functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information
4437 on known OIDs to properly encode their input. Object Identifiers
4438 that are not known are not encoded by these functions, and their
4439 input is stored directly into the ASN.1 structure. In that case of
4440 unknown OIDs, you have the responsibility of DER encoding your
4443 @strong{Returns:} 1 on known OIDs and 0 otherwise.
4446 @subheading gnutls_x509_dn_oid_name
4447 @anchor{gnutls_x509_dn_oid_name}
4448 @deftypefun {const char *} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags})
4449 @var{oid}: holds an Object Identifier in a null terminated string
4451 @var{flags}: 0 or GNUTLS_X509_DN_OID_*
4453 This function will return the name of a known DN OID. If
4454 @code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function
4455 will return the given OID if no descriptive name has been
4458 @strong{Returns:} A null terminated string or NULL otherwise.
4463 @subheading gnutls_x509_ext_export_aia
4464 @anchor{gnutls_x509_ext_export_aia}
4465 @deftypefun {int} {gnutls_x509_ext_export_aia} (gnutls_x509_aia_t @var{aia}, gnutls_datum_t * @var{ext})
4466 @var{aia}: The authority info access structure
4468 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4470 This function will DER encode the Authority Information Access (AIA)
4471 extension; see RFC 5280 section 4.2.2.1 for more information on the
4474 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4475 negative error value.
4477 @strong{Since:} 3.3.0
4480 @subheading gnutls_x509_ext_export_authority_key_id
4481 @anchor{gnutls_x509_ext_export_authority_key_id}
4482 @deftypefun {int} {gnutls_x509_ext_export_authority_key_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{ext})
4483 @var{aki}: An initialized authority key identifier structure
4485 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4487 This function will convert the provided key identifier to a
4488 DER-encoded PKIX AuthorityKeyIdentifier extension.
4489 The output data in @code{ext} will be allocated using
4490 @code{gnutls_malloc()} .
4492 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4494 @strong{Since:} 3.3.0
4497 @subheading gnutls_x509_ext_export_basic_constraints
4498 @anchor{gnutls_x509_ext_export_basic_constraints}
4499 @deftypefun {int} {gnutls_x509_ext_export_basic_constraints} (unsigned int @var{ca}, int @var{pathlen}, gnutls_datum_t * @var{ext})
4500 @var{ca}: non-zero for a CA
4502 @var{pathlen}: The path length constraint (set to -1 for no constraint)
4504 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4506 This function will convert the parameters provided to a basic constraints
4507 DER encoded extension (2.5.29.19).
4508 The @code{ext} data will be allocated using
4509 @code{gnutls_malloc()} .
4511 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4512 negative error value.
4514 @strong{Since:} 3.3.0
4517 @subheading gnutls_x509_ext_export_crl_dist_points
4518 @anchor{gnutls_x509_ext_export_crl_dist_points}
4519 @deftypefun {int} {gnutls_x509_ext_export_crl_dist_points} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_datum_t * @var{ext})
4520 @var{cdp}: A pointer to an initialized CRL distribution points structure.
4522 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4524 This function will convert the provided policies, to a certificate policy
4525 DER encoded extension (2.5.29.31).
4527 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4529 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4531 @strong{Since:} 3.3.0
4534 @subheading gnutls_x509_ext_export_key_purposes
4535 @anchor{gnutls_x509_ext_export_key_purposes}
4536 @deftypefun {int} {gnutls_x509_ext_export_key_purposes} (gnutls_x509_key_purposes_t @var{p}, gnutls_datum_t * @var{ext})
4537 @var{p}: The key purposes structure
4539 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4541 This function will convert the key purposes structure to a
4542 DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in
4543 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4545 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4547 @strong{Since:} 3.3.0
4550 @subheading gnutls_x509_ext_export_key_usage
4551 @anchor{gnutls_x509_ext_export_key_usage}
4552 @deftypefun {int} {gnutls_x509_ext_export_key_usage} (unsigned int @var{usage}, gnutls_datum_t * @var{ext})
4553 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4555 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4557 This function will convert the keyUsage bit string to a DER
4558 encoded PKIX extension. The @code{ext} data will be allocated using
4559 @code{gnutls_malloc()} .
4561 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4562 negative error value.
4564 @strong{Since:} 3.3.0
4567 @subheading gnutls_x509_ext_export_name_constraints
4568 @anchor{gnutls_x509_ext_export_name_constraints}
4569 @deftypefun {int} {gnutls_x509_ext_export_name_constraints} (gnutls_x509_name_constraints_t @var{nc}, gnutls_datum_t * @var{ext})
4570 @var{nc}: The nameconstraints structure
4572 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4574 This function will convert the provided name constraints structure to a
4575 DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in
4576 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4578 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4580 @strong{Since:} 3.3.0
4583 @subheading gnutls_x509_ext_export_policies
4584 @anchor{gnutls_x509_ext_export_policies}
4585 @deftypefun {int} {gnutls_x509_ext_export_policies} (gnutls_x509_policies_t @var{policies}, gnutls_datum_t * @var{ext})
4586 @var{policies}: A pointer to an initialized policies structure.
4588 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4590 This function will convert the provided policies, to a certificate policy
4591 DER encoded extension (2.5.29.32).
4593 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4595 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4597 @strong{Since:} 3.3.0
4600 @subheading gnutls_x509_ext_export_private_key_usage_period
4601 @anchor{gnutls_x509_ext_export_private_key_usage_period}
4602 @deftypefun {int} {gnutls_x509_ext_export_private_key_usage_period} (time_t @var{activation}, time_t @var{expiration}, gnutls_datum_t * @var{ext})
4603 @var{activation}: The activation time
4605 @var{expiration}: The expiration time
4607 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4609 This function will convert the periods provided to a private key
4610 usage DER encoded extension (2.5.29.16).
4611 The @code{ext} data will be allocated using
4612 @code{gnutls_malloc()} .
4614 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4615 negative error value.
4617 @strong{Since:} 3.3.0
4620 @subheading gnutls_x509_ext_export_proxy
4621 @anchor{gnutls_x509_ext_export_proxy}
4622 @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})
4623 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4624 and negative error codes indicate that the pathLenConstraints field should
4627 @var{policyLanguage}: OID describing the language of @code{policy} .
4629 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4631 @var{sizeof_policy}: size of @code{policy} .
4633 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4635 This function will convert the parameters provided to a proxyCertInfo extension.
4637 The @code{ext} data will be allocated using
4638 @code{gnutls_malloc()} .
4640 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4641 negative error value.
4643 @strong{Since:} 3.3.0
4646 @subheading gnutls_x509_ext_export_subject_alt_names
4647 @anchor{gnutls_x509_ext_export_subject_alt_names}
4648 @deftypefun {int} {gnutls_x509_ext_export_subject_alt_names} (gnutls_subject_alt_names_t @var{sans}, gnutls_datum_t * @var{ext})
4649 @var{sans}: The alternative names structure
4651 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4653 This function will convert the provided alternative names structure to a
4654 DER-encoded SubjectAltName PKIX extension. The output data in @code{ext} will be allocated using
4655 @code{gnutls_malloc()} .
4657 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4659 @strong{Since:} 3.3.0
4662 @subheading gnutls_x509_ext_export_subject_key_id
4663 @anchor{gnutls_x509_ext_export_subject_key_id}
4664 @deftypefun {int} {gnutls_x509_ext_export_subject_key_id} (const gnutls_datum_t * @var{id}, gnutls_datum_t * @var{ext})
4665 @var{id}: The key identifier
4667 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4669 This function will convert the provided key identifier to a
4670 DER-encoded PKIX SubjectKeyIdentifier extension.
4671 The output data in @code{ext} will be allocated using
4672 @code{gnutls_malloc()} .
4674 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4676 @strong{Since:} 3.3.0
4679 @subheading gnutls_x509_ext_import_aia
4680 @anchor{gnutls_x509_ext_import_aia}
4681 @deftypefun {int} {gnutls_x509_ext_import_aia} (const gnutls_datum_t * @var{ext}, gnutls_x509_aia_t @var{aia}, unsigned int @var{flags})
4682 @var{ext}: The DER-encoded extension data
4684 @var{aia}: The authority info access structure
4686 @var{flags}: should be zero
4688 This function extracts the Authority Information Access (AIA)
4689 extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1
4690 for more information on the extension. The
4691 AIA extension holds a sequence of AccessDescription (AD) data.
4693 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4695 @strong{Since:} 3.3.0
4698 @subheading gnutls_x509_ext_import_authority_key_id
4699 @anchor{gnutls_x509_ext_import_authority_key_id}
4700 @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})
4701 @var{ext}: a DER encoded extension
4703 @var{aki}: An initialized authority key identifier structure
4705 @var{flags}: should be zero
4707 This function will return the subject key ID stored in the provided
4708 AuthorityKeyIdentifier extension.
4710 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4711 if the extension is not present, otherwise a negative error value.
4713 @strong{Since:} 3.3.0
4716 @subheading gnutls_x509_ext_import_basic_constraints
4717 @anchor{gnutls_x509_ext_import_basic_constraints}
4718 @deftypefun {int} {gnutls_x509_ext_import_basic_constraints} (const gnutls_datum_t * @var{ext}, unsigned int * @var{ca}, int * @var{pathlen})
4719 @var{ext}: the DER encoded extension data
4721 @var{ca}: will be non zero if the CA status is true
4723 @var{pathlen}: the path length constraint; will be set to -1 for no limit
4725 This function will return the CA status and path length constraint
4726 as written in the PKIX extension 2.5.29.19.
4728 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4729 negative error value.
4731 @strong{Since:} 3.3.0
4734 @subheading gnutls_x509_ext_import_crl_dist_points
4735 @anchor{gnutls_x509_ext_import_crl_dist_points}
4736 @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})
4737 @var{ext}: the DER encoded extension data
4739 @var{cdp}: A pointer to an initialized CRL distribution points structure.
4741 @var{flags}: should be zero
4743 This function will extract the CRL distribution points extension (2.5.29.31)
4744 and store it into the provided structure.
4746 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4748 @strong{Since:} 3.3.0
4751 @subheading gnutls_x509_ext_import_key_purposes
4752 @anchor{gnutls_x509_ext_import_key_purposes}
4753 @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})
4754 @var{ext}: The DER-encoded extension data
4756 @var{p}: The key purposes structure
4758 @var{flags}: should be zero
4760 This function will extract the key purposes in the provided DER-encoded
4761 ExtKeyUsageSyntax PKIX extension, to a @code{gnutls_x509_key_purposes_t} structure.
4762 The structure must be initialized.
4764 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4766 @strong{Since:} 3.3.0
4769 @subheading gnutls_x509_ext_import_key_usage
4770 @anchor{gnutls_x509_ext_import_key_usage}
4771 @deftypefun {int} {gnutls_x509_ext_import_key_usage} (const gnutls_datum_t * @var{ext}, unsigned int * @var{key_usage})
4772 @var{ext}: the DER encoded extension data
4774 @var{key_usage}: where the key usage bits will be stored
4776 This function will return certificate's key usage, by reading the DER
4777 data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
4778 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
4779 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
4780 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
4781 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
4782 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
4784 @strong{Returns:} the certificate key usage, or a negative error code in case of
4785 parsing error. If the certificate does not contain the keyUsage
4786 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
4789 @strong{Since:} 3.3.0
4792 @subheading gnutls_x509_ext_import_name_constraints
4793 @anchor{gnutls_x509_ext_import_name_constraints}
4794 @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})
4795 @var{ext}: a DER encoded extension
4797 @var{nc}: The nameconstraints intermediate structure
4799 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
4801 This function will return an intermediate structure containing
4802 the name constraints of the provided NameConstraints extension. That
4803 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
4804 to verify whether a server's name is in accordance with the constraints.
4806 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
4807 the @code{nc} structure is empty
4808 this function will behave identically as if the flag was not set.
4809 Otherwise if there are elements in the @code{nc} structure then only the
4810 excluded constraints will be appended to the constraints.
4812 Note that @code{nc} must be initialized prior to calling this function.
4814 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4815 if the extension is not present, otherwise a negative error value.
4817 @strong{Since:} 3.3.0
4820 @subheading gnutls_x509_ext_import_policies
4821 @anchor{gnutls_x509_ext_import_policies}
4822 @deftypefun {int} {gnutls_x509_ext_import_policies} (const gnutls_datum_t * @var{ext}, gnutls_x509_policies_t @var{policies}, unsigned int @var{flags})
4823 @var{ext}: the DER encoded extension data
4825 @var{policies}: A pointer to an initialized policies structures.
4827 @var{flags}: should be zero
4829 This function will extract the certificate policy extension (2.5.29.32)
4830 and store it the provided structure.
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_private_key_usage_period
4838 @anchor{gnutls_x509_ext_import_private_key_usage_period}
4839 @deftypefun {int} {gnutls_x509_ext_import_private_key_usage_period} (const gnutls_datum_t * @var{ext}, time_t * @var{activation}, time_t * @var{expiration})
4840 @var{ext}: the DER encoded extension data
4842 @var{activation}: Will hold the activation time
4844 @var{expiration}: Will hold the expiration time
4846 This function will return the expiration and activation
4847 times of the private key as written in the
4848 PKIX extension 2.5.29.16.
4850 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4851 negative error value.
4853 @strong{Since:} 3.3.0
4856 @subheading gnutls_x509_ext_import_proxy
4857 @anchor{gnutls_x509_ext_import_proxy}
4858 @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})
4859 @var{ext}: the DER encoded extension data
4861 @var{pathlen}: pointer to output integer indicating path length (may be
4862 NULL), non-negative error codes indicate a present pCPathLenConstraint
4863 field and the actual value, -1 indicate that the field is absent.
4865 @var{policyLanguage}: output variable with OID of policy language
4867 @var{policy}: output variable with policy data
4869 @var{sizeof_policy}: output variable size of policy data
4871 This function will return the information from a proxy certificate
4872 extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
4874 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4875 negative error value.
4877 @strong{Since:} 3.3.0
4880 @subheading gnutls_x509_ext_import_subject_alt_names
4881 @anchor{gnutls_x509_ext_import_subject_alt_names}
4882 @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})
4883 @var{ext}: The DER-encoded extension data
4885 @var{sans}: The alternative names structure
4887 @var{flags}: should be zero
4889 This function will export the alternative names in the provided DER-encoded
4890 SubjectAltName PKIX extension, to a @code{gnutls_subject_alt_names_t} structure. The structure
4891 must have been initialized.
4893 This function will succeed even if there no subject alternative names
4896 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4898 @strong{Since:} 3.3.0
4901 @subheading gnutls_x509_ext_import_subject_key_id
4902 @anchor{gnutls_x509_ext_import_subject_key_id}
4903 @deftypefun {int} {gnutls_x509_ext_import_subject_key_id} (const gnutls_datum_t * @var{ext}, gnutls_datum_t * @var{id})
4904 @var{ext}: a DER encoded extension
4906 @var{id}: will contain the subject key ID
4908 This function will return the subject key ID stored in the provided
4909 SubjectKeyIdentifier extension. The ID will be allocated using
4910 @code{gnutls_malloc()} .
4912 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4913 if the extension is not present, otherwise a negative error value.
4915 @strong{Since:} 3.3.0
4918 @subheading gnutls_x509_key_purpose_deinit
4919 @anchor{gnutls_x509_key_purpose_deinit}
4920 @deftypefun {void} {gnutls_x509_key_purpose_deinit} (gnutls_x509_key_purposes_t @var{p})
4921 @var{p}: The key purposes structure
4923 This function will deinitialize an alternative names structure.
4925 @strong{Since:} 3.3.0
4928 @subheading gnutls_x509_key_purpose_get
4929 @anchor{gnutls_x509_key_purpose_get}
4930 @deftypefun {int} {gnutls_x509_key_purpose_get} (gnutls_x509_key_purposes_t @var{p}, unsigned @var{idx}, gnutls_datum_t * @var{oid})
4931 @var{p}: The key purposes structure
4933 @var{idx}: The index of the key purpose to retrieve
4935 @var{oid}: Will hold the object identifier of the key purpose (to be treated as constant)
4937 This function will retrieve the specified by the index key purpose in the
4940 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4941 if the index is out of bounds, otherwise a negative error value.
4943 @strong{Since:} 3.3.0
4946 @subheading gnutls_x509_key_purpose_init
4947 @anchor{gnutls_x509_key_purpose_init}
4948 @deftypefun {int} {gnutls_x509_key_purpose_init} (gnutls_x509_key_purposes_t * @var{p})
4949 @var{p}: The key purposes structure
4951 This function will initialize an alternative names structure.
4953 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4955 @strong{Since:} 3.3.0
4958 @subheading gnutls_x509_key_purpose_set
4959 @anchor{gnutls_x509_key_purpose_set}
4960 @deftypefun {int} {gnutls_x509_key_purpose_set} (gnutls_x509_key_purposes_t @var{p}, const char * @var{oid})
4961 @var{p}: The key purposes structure
4963 @var{oid}: The object identifier of the key purpose
4965 This function will store the specified key purpose in the
4968 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
4970 @strong{Since:} 3.3.0
4973 @subheading gnutls_x509_name_constraints_add_excluded
4974 @anchor{gnutls_x509_name_constraints_add_excluded}
4975 @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})
4976 @var{nc}: The nameconstraints structure
4978 @var{type}: The type of the constraints
4980 @var{name}: The data of the constraints
4982 This function will add a name constraint to the list of excluded
4985 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4987 @strong{Since:} 3.3.0
4990 @subheading gnutls_x509_name_constraints_add_permitted
4991 @anchor{gnutls_x509_name_constraints_add_permitted}
4992 @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})
4993 @var{nc}: The nameconstraints structure
4995 @var{type}: The type of the constraints
4997 @var{name}: The data of the constraints
4999 This function will add a name constraint to the list of permitted
5002 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5004 @strong{Since:} 3.3.0
5007 @subheading gnutls_x509_name_constraints_check
5008 @anchor{gnutls_x509_name_constraints_check}
5009 @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})
5010 @var{nc}: the extracted name constraints structure
5012 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5014 @var{name}: the name to be checked
5016 This function will check the provided name against the constraints in
5017 @code{nc} using the RFC5280 rules. Currently this function is limited to DNS
5018 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5020 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5022 @strong{Since:} 3.3.0
5025 @subheading gnutls_x509_name_constraints_check_crt
5026 @anchor{gnutls_x509_name_constraints_check_crt}
5027 @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})
5028 @var{nc}: the extracted name constraints structure
5030 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5032 @var{cert}: the certificate to be checked
5034 This function will check the provided certificate names against the constraints in
5035 @code{nc} using the RFC5280 rules. It will traverse all the certificate's names and
5038 Currently this function is limited to DNS
5039 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5041 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5043 @strong{Since:} 3.3.0
5046 @subheading gnutls_x509_name_constraints_deinit
5047 @anchor{gnutls_x509_name_constraints_deinit}
5048 @deftypefun {void} {gnutls_x509_name_constraints_deinit} (gnutls_x509_name_constraints_t @var{nc})
5049 @var{nc}: The nameconstraints structure
5051 This function will deinitialize a name constraints structure.
5053 @strong{Since:} 3.3.0
5056 @subheading gnutls_x509_name_constraints_get_excluded
5057 @anchor{gnutls_x509_name_constraints_get_excluded}
5058 @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})
5059 @var{nc}: the extracted name constraints structure
5061 @var{idx}: the index of the constraint
5063 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5065 @var{name}: the name in the constraint (of the specific type)
5067 This function will return an intermediate structure containing
5068 the name constraints of the provided CA certificate. That
5069 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5070 to verify whether a server's name is in accordance with the constraints.
5072 The name should be treated as constant and valid for the lifetime of @code{nc} .
5074 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5075 if the extension is not present, otherwise a negative error value.
5077 @strong{Since:} 3.3.0
5080 @subheading gnutls_x509_name_constraints_get_permitted
5081 @anchor{gnutls_x509_name_constraints_get_permitted}
5082 @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})
5083 @var{nc}: the extracted name constraints structure
5085 @var{idx}: the index of the constraint
5087 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5089 @var{name}: the name in the constraint (of the specific type)
5091 This function will return an intermediate structure containing
5092 the name constraints of the provided CA certificate. That
5093 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5094 to verify whether a server's name is in accordance with the constraints.
5096 The name should be treated as constant and valid for the lifetime of @code{nc} .
5098 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5099 if the extension is not present, otherwise a negative error value.
5101 @strong{Since:} 3.3.0
5104 @subheading gnutls_x509_name_constraints_init
5105 @anchor{gnutls_x509_name_constraints_init}
5106 @deftypefun {int} {gnutls_x509_name_constraints_init} (gnutls_x509_name_constraints_t * @var{nc})
5107 @var{nc}: The nameconstraints structure
5109 This function will initialize a name constraints structure.
5111 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5113 @strong{Since:} 3.3.0
5116 @subheading gnutls_x509_policies_deinit
5117 @anchor{gnutls_x509_policies_deinit}
5118 @deftypefun {void} {gnutls_x509_policies_deinit} (gnutls_x509_policies_t @var{policies})
5119 @var{policies}: The authority key identifier structure
5121 This function will deinitialize an authority key identifier structure.
5123 @strong{Since:} 3.3.0
5126 @subheading gnutls_x509_policies_get
5127 @anchor{gnutls_x509_policies_get}
5128 @deftypefun {int} {gnutls_x509_policies_get} (gnutls_x509_policies_t @var{policies}, unsigned int @var{seq}, struct gnutls_x509_policy_st * @var{policy})
5129 @var{policies}: The policies structure
5131 @var{seq}: The index of the name to get
5133 @var{policy}: Will hold the policy
5135 This function will return a specific policy as stored in
5136 the @code{policies} structure. The returned values should be treated as constant
5137 and valid for the lifetime of @code{policies} .
5139 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5140 if the index is out of bounds, otherwise a negative error value.
5142 @strong{Since:} 3.3.0
5145 @subheading gnutls_x509_policies_init
5146 @anchor{gnutls_x509_policies_init}
5147 @deftypefun {int} {gnutls_x509_policies_init} (gnutls_x509_policies_t * @var{policies})
5148 @var{policies}: The authority key ID structure
5150 This function will initialize an authority key ID structure.
5152 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5154 @strong{Since:} 3.3.0
5157 @subheading gnutls_x509_policies_set
5158 @anchor{gnutls_x509_policies_set}
5159 @deftypefun {int} {gnutls_x509_policies_set} (gnutls_x509_policies_t @var{policies}, const struct gnutls_x509_policy_st * @var{policy})
5160 @var{policies}: An initialized policies structure
5162 @var{policy}: Contains the policy to set
5164 This function will store the specified policy in
5165 the provided @code{policies} structure.
5167 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
5169 @strong{Since:} 3.3.0
5172 @subheading gnutls_x509_policy_release
5173 @anchor{gnutls_x509_policy_release}
5174 @deftypefun {void} {gnutls_x509_policy_release} (struct gnutls_x509_policy_st * @var{policy})
5175 @var{policy}: a certificate policy
5177 This function will deinitialize all memory associated with the provided
5178 @code{policy} . The policy is allocated using @code{gnutls_x509_crt_get_policy()} .
5180 @strong{Since:} 3.1.5
5183 @subheading gnutls_x509_privkey_cpy
5184 @anchor{gnutls_x509_privkey_cpy}
5185 @deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src})
5186 @var{dst}: The destination key, which should be initialized.
5188 @var{src}: The source key
5190 This function will copy a private key from source to destination
5191 key. Destination has to be initialized.
5193 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5194 negative error value.
5197 @subheading gnutls_x509_privkey_deinit
5198 @anchor{gnutls_x509_privkey_deinit}
5199 @deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key})
5200 @var{key}: The structure to be deinitialized
5202 This function will deinitialize a private key structure.
5205 @subheading gnutls_x509_privkey_export
5206 @anchor{gnutls_x509_privkey_export}
5207 @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})
5208 @var{key}: Holds the key
5210 @var{format}: the format of output params. One of PEM or DER.
5212 @var{output_data}: will contain a private key PEM or DER encoded
5214 @var{output_data_size}: holds the size of output_data (and will be
5215 replaced by the actual size of parameters)
5217 This function will export the private key to a PKCS1 structure for
5218 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5219 the same format with the parameters used by openssl.
5221 If the buffer provided is not long enough to hold the output, then
5222 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
5225 If the structure is PEM encoded, it will have a header
5226 of "BEGIN RSA PRIVATE KEY".
5228 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5229 negative error value.
5232 @subheading gnutls_x509_privkey_export2
5233 @anchor{gnutls_x509_privkey_export2}
5234 @deftypefun {int} {gnutls_x509_privkey_export2} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
5235 @var{key}: Holds the key
5237 @var{format}: the format of output params. One of PEM or DER.
5239 @var{out}: will contain a private key PEM or DER encoded
5241 This function will export the private key to a PKCS1 structure for
5242 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5243 the same format with the parameters used by openssl.
5245 The output buffer is allocated using @code{gnutls_malloc()} .
5247 If the structure is PEM encoded, it will have a header
5248 of "BEGIN RSA PRIVATE KEY".
5250 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5251 negative error value.
5256 @subheading gnutls_x509_privkey_export2_pkcs8
5257 @anchor{gnutls_x509_privkey_export2_pkcs8}
5258 @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})
5259 @var{key}: Holds the key
5261 @var{format}: the format of output params. One of PEM or DER.
5263 @var{password}: the password that will be used to encrypt the key.
5265 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5267 @var{out}: will contain a private key PEM or DER encoded
5269 This function will export the private key to a PKCS8 structure.
5270 Both RSA and DSA keys can be exported. For DSA keys we use
5271 PKCS @code{11} definitions. If the flags do not specify the encryption
5272 cipher, then the default 3DES (PBES2) will be used.
5274 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5275 encryption schemas, or ASCII for the PKCS12 schemas.
5277 The output buffer is allocated using @code{gnutls_malloc()} .
5279 If the structure is PEM encoded, it will have a header
5280 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5281 encryption is not used.
5283 @strong{Returns:} In case of failure a negative error code will be
5284 returned, and 0 on success.
5289 @subheading gnutls_x509_privkey_export_dsa_raw
5290 @anchor{gnutls_x509_privkey_export_dsa_raw}
5291 @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})
5292 @var{key}: a structure that holds the DSA parameters
5294 @var{p}: will hold the p
5296 @var{q}: will hold the q
5298 @var{g}: will hold the g
5300 @var{y}: will hold the y
5302 @var{x}: will hold the x
5304 This function will export the DSA private key's parameters found
5305 in the given structure. The new parameters will be allocated using
5306 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5308 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5309 negative error value.
5312 @subheading gnutls_x509_privkey_export_ecc_raw
5313 @anchor{gnutls_x509_privkey_export_ecc_raw}
5314 @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})
5315 @var{key}: a structure that holds the rsa parameters
5317 @var{curve}: will hold the curve
5319 @var{x}: will hold the x coordinate
5321 @var{y}: will hold the y coordinate
5323 @var{k}: will hold the private key
5325 This function will export the ECC private key's parameters found
5326 in the given structure. The new parameters will be allocated using
5327 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5329 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5330 negative error value.
5335 @subheading gnutls_x509_privkey_export_pkcs8
5336 @anchor{gnutls_x509_privkey_export_pkcs8}
5337 @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})
5338 @var{key}: Holds the key
5340 @var{format}: the format of output params. One of PEM or DER.
5342 @var{password}: the password that will be used to encrypt the key.
5344 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5346 @var{output_data}: will contain a private key PEM or DER encoded
5348 @var{output_data_size}: holds the size of output_data (and will be
5349 replaced by the actual size of parameters)
5351 This function will export the private key to a PKCS8 structure.
5352 Both RSA and DSA keys can be exported. For DSA keys we use
5353 PKCS @code{11} definitions. If the flags do not specify the encryption
5354 cipher, then the default 3DES (PBES2) will be used.
5356 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5357 encryption schemas, or ASCII for the PKCS12 schemas.
5359 If the buffer provided is not long enough to hold the output, then
5360 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
5363 If the structure is PEM encoded, it will have a header
5364 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5365 encryption is not used.
5367 @strong{Returns:} In case of failure a negative error code will be
5368 returned, and 0 on success.
5371 @subheading gnutls_x509_privkey_export_rsa_raw
5372 @anchor{gnutls_x509_privkey_export_rsa_raw}
5373 @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})
5374 @var{key}: a structure that holds the rsa parameters
5376 @var{m}: will hold the modulus
5378 @var{e}: will hold the public exponent
5380 @var{d}: will hold the private exponent
5382 @var{p}: will hold the first prime (p)
5384 @var{q}: will hold the second prime (q)
5386 @var{u}: will hold the coefficient
5388 This function will export the RSA private key's parameters found
5389 in the given structure. The new parameters will be allocated using
5390 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5392 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5393 negative error value.
5396 @subheading gnutls_x509_privkey_export_rsa_raw2
5397 @anchor{gnutls_x509_privkey_export_rsa_raw2}
5398 @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})
5399 @var{key}: a structure that holds the rsa parameters
5401 @var{m}: will hold the modulus
5403 @var{e}: will hold the public exponent
5405 @var{d}: will hold the private exponent
5407 @var{p}: will hold the first prime (p)
5409 @var{q}: will hold the second prime (q)
5411 @var{u}: will hold the coefficient
5413 @var{e1}: will hold e1 = d mod (p-1)
5415 @var{e2}: will hold e2 = d mod (q-1)
5417 This function will export the RSA private key's parameters found
5418 in the given structure. The new parameters will be allocated using
5419 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5421 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5422 negative error value.
5424 @strong{Since:} 2.12.0
5427 @subheading gnutls_x509_privkey_fix
5428 @anchor{gnutls_x509_privkey_fix}
5429 @deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key})
5430 @var{key}: Holds the key
5432 This function will recalculate the secondary parameters in a key.
5433 In RSA keys, this can be the coefficient and exponent1,2.
5435 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5436 negative error value.
5439 @subheading gnutls_x509_privkey_generate
5440 @anchor{gnutls_x509_privkey_generate}
5441 @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})
5442 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5444 @var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .
5446 @var{bits}: the size of the modulus
5448 @var{flags}: unused for now. Must be 0.
5450 This function will generate a random private key. Note that this
5451 function must be called on an empty private key.
5453 Note that when generating an elliptic curve key, the curve
5454 can be substituted in the place of the bits parameter using the
5455 @code{GNUTLS_CURVE_TO_BITS()} macro.
5457 For DSA keys, if the subgroup size needs to be specified check
5458 the @code{GNUTLS_SUBGROUP_TO_BITS()} macro.
5460 Do not set the number of bits directly, use @code{gnutls_sec_param_to_pk_bits()} .
5462 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5463 negative error value.
5466 @subheading gnutls_x509_privkey_get_key_id
5467 @anchor{gnutls_x509_privkey_get_key_id}
5468 @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})
5469 @var{key}: Holds the key
5471 @var{flags}: should be 0 for now
5473 @var{output_data}: will contain the key ID
5475 @var{output_data_size}: holds the size of output_data (and will be
5476 replaced by the actual size of parameters)
5478 This function will return a unique ID that depends on the public key
5479 parameters. This ID can be used in checking whether a certificate
5480 corresponds to the given key.
5482 If the buffer provided is not long enough to hold the output, then
5483 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
5484 be returned. The output will normally be a SHA-1 hash output,
5487 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5488 negative error value.
5491 @subheading gnutls_x509_privkey_get_pk_algorithm
5492 @anchor{gnutls_x509_privkey_get_pk_algorithm}
5493 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key})
5494 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5496 This function will return the public key algorithm of a private
5499 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5500 success, or a negative error code on error.
5503 @subheading gnutls_x509_privkey_get_pk_algorithm2
5504 @anchor{gnutls_x509_privkey_get_pk_algorithm2}
5505 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm2} (gnutls_x509_privkey_t @var{key}, unsigned int * @var{bits})
5506 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5508 @var{bits}: The number of bits in the public key algorithm
5510 This function will return the public key algorithm of a private
5513 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5514 success, or a negative error code on error.
5517 @subheading gnutls_x509_privkey_import
5518 @anchor{gnutls_x509_privkey_import}
5519 @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})
5520 @var{key}: The structure to store the parsed key
5522 @var{data}: The DER or PEM encoded certificate.
5524 @var{format}: One of DER or PEM
5526 This function will convert the given DER or PEM encoded key to the
5527 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5530 If the key is PEM encoded it should have a header that contains "PRIVATE
5531 KEY". Note that this function falls back to PKCS @code{8} decoding without
5532 password, if the default format fails to import.
5534 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5535 negative error value.
5538 @subheading gnutls_x509_privkey_import2
5539 @anchor{gnutls_x509_privkey_import2}
5540 @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})
5541 @var{key}: The structure to store the parsed key
5543 @var{data}: The DER or PEM encoded key.
5545 @var{format}: One of DER or PEM
5547 @var{password}: A password (optional)
5549 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5551 This function will import the given DER or PEM encoded key, to
5552 the native @code{gnutls_x509_privkey_t} format, irrespective of the
5553 input format. The input format is auto-detected.
5555 The supported formats are basic unencrypted key, PKCS8, PKCS12,
5556 and the openssl format.
5558 If the provided key is encrypted but no password was given, then
5559 @code{GNUTLS_E_DECRYPTION_FAILED} is returned.
5561 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5562 negative error value.
5565 @subheading gnutls_x509_privkey_import_dsa_raw
5566 @anchor{gnutls_x509_privkey_import_dsa_raw}
5567 @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})
5568 @var{key}: The structure to store the parsed key
5570 @var{p}: holds the p
5572 @var{q}: holds the q
5574 @var{g}: holds the g
5576 @var{y}: holds the y
5578 @var{x}: holds the x
5580 This function will convert the given DSA raw parameters to the
5581 native @code{gnutls_x509_privkey_t} format. The output will be stored
5584 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5585 negative error value.
5588 @subheading gnutls_x509_privkey_import_ecc_raw
5589 @anchor{gnutls_x509_privkey_import_ecc_raw}
5590 @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})
5591 @var{key}: The structure to store the parsed key
5593 @var{curve}: holds the curve
5595 @var{x}: holds the x
5597 @var{y}: holds the y
5599 @var{k}: holds the k
5601 This function will convert the given elliptic curve parameters to the
5602 native @code{gnutls_x509_privkey_t} format. The output will be stored
5605 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5606 negative error value.
5611 @subheading gnutls_x509_privkey_import_openssl
5612 @anchor{gnutls_x509_privkey_import_openssl}
5613 @deftypefun {int} {gnutls_x509_privkey_import_openssl} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, const char * @var{password})
5614 @var{key}: The structure to store the parsed key
5616 @var{data}: The DER or PEM encoded key.
5618 @var{password}: the password to decrypt the key (if it is encrypted).
5620 This function will convert the given PEM encrypted to
5621 the native gnutls_x509_privkey_t format. The
5622 output will be stored in @code{key} .
5624 The @code{password} should be in ASCII. If the password is not provided
5625 or wrong then @code{GNUTLS_E_DECRYPTION_FAILED} will be returned.
5627 If the Certificate is PEM encoded it should have a header of
5628 "PRIVATE KEY" and the "DEK-Info" header.
5630 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5631 negative error value.
5634 @subheading gnutls_x509_privkey_import_pkcs8
5635 @anchor{gnutls_x509_privkey_import_pkcs8}
5636 @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})
5637 @var{key}: The structure to store the parsed key
5639 @var{data}: The DER or PEM encoded key.
5641 @var{format}: One of DER or PEM
5643 @var{password}: the password to decrypt the key (if it is encrypted).
5645 @var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
5647 This function will convert the given DER or PEM encoded PKCS8 2.0
5648 encrypted key to the native gnutls_x509_privkey_t format. The
5649 output will be stored in @code{key} . Both RSA and DSA keys can be
5650 imported, and flags can only be used to indicate an unencrypted
5653 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5654 encryption schemas, or ASCII for the PKCS12 schemas.
5656 If the Certificate is PEM encoded it should have a header of
5657 "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to
5658 specify the flags if the key is DER encoded, since in that case
5659 the encryption status cannot be auto-detected.
5661 If the @code{GNUTLS_PKCS_PLAIN} flag is specified and the supplied data
5662 are encrypted then @code{GNUTLS_E_DECRYPTION_FAILED} is returned.
5664 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5665 negative error value.
5668 @subheading gnutls_x509_privkey_import_rsa_raw
5669 @anchor{gnutls_x509_privkey_import_rsa_raw}
5670 @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})
5671 @var{key}: The structure to store the parsed key
5673 @var{m}: holds the modulus
5675 @var{e}: holds the public exponent
5677 @var{d}: holds the private exponent
5679 @var{p}: holds the first prime (p)
5681 @var{q}: holds the second prime (q)
5683 @var{u}: holds the coefficient
5685 This function will convert the given RSA raw parameters to the
5686 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5689 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5690 negative error value.
5693 @subheading gnutls_x509_privkey_import_rsa_raw2
5694 @anchor{gnutls_x509_privkey_import_rsa_raw2}
5695 @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})
5696 @var{key}: The structure to store the parsed key
5698 @var{m}: holds the modulus
5700 @var{e}: holds the public exponent
5702 @var{d}: holds the private exponent
5704 @var{p}: holds the first prime (p)
5706 @var{q}: holds the second prime (q)
5708 @var{u}: holds the coefficient (optional)
5710 @var{e1}: holds e1 = d mod (p-1) (optional)
5712 @var{e2}: holds e2 = d mod (q-1) (optional)
5714 This function will convert the given RSA raw parameters to the
5715 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5718 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5719 negative error value.
5722 @subheading gnutls_x509_privkey_init
5723 @anchor{gnutls_x509_privkey_init}
5724 @deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key})
5725 @var{key}: The structure to be initialized
5727 This function will initialize an private key structure.
5729 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5730 negative error value.
5733 @subheading gnutls_x509_privkey_sec_param
5734 @anchor{gnutls_x509_privkey_sec_param}
5735 @deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key})
5736 @var{key}: a key structure
5738 This function will return the security parameter appropriate with
5741 @strong{Returns:} On success, a valid security parameter is returned otherwise
5742 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
5744 @strong{Since:} 2.12.0
5747 @subheading gnutls_x509_privkey_verify_params
5748 @anchor{gnutls_x509_privkey_verify_params}
5749 @deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key})
5750 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5752 This function will verify the private key parameters.
5754 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5755 negative error value.
5758 @subheading gnutls_x509_rdn_get
5759 @anchor{gnutls_x509_rdn_get}
5760 @deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{buf_size})
5761 @var{idn}: should contain a DER encoded RDN sequence
5763 @var{buf}: a pointer to a structure to hold the peer's name
5765 @var{buf_size}: holds the size of @code{buf}
5767 This function will return the name of the given RDN sequence. The
5768 name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
5771 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5772 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5773 updated if the provided buffer is not long enough, otherwise a
5774 negative error value.
5777 @subheading gnutls_x509_rdn_get_by_oid
5778 @anchor{gnutls_x509_rdn_get_by_oid}
5779 @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})
5780 @var{idn}: should contain a DER encoded RDN sequence
5782 @var{oid}: an Object Identifier
5784 @var{indx}: In case multiple same OIDs exist in the RDN indicates which
5785 to send. Use 0 for the first one.
5787 @var{raw_flag}: If non-zero then the raw DER data are returned.
5789 @var{buf}: a pointer to a structure to hold the peer's name
5791 @var{buf_size}: holds the size of @code{buf}
5793 This function will return the name of the given Object identifier,
5794 of the RDN sequence. The name will be encoded using the rules
5797 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5798 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5799 updated if the provided buffer is not long enough, otherwise a
5800 negative error value.
5803 @subheading gnutls_x509_rdn_get_oid
5804 @anchor{gnutls_x509_rdn_get_oid}
5805 @deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size})
5806 @var{idn}: should contain a DER encoded RDN sequence
5808 @var{indx}: Indicates which OID to return. Use 0 for the first one.
5810 @var{buf}: a pointer to a structure to hold the peer's name OID
5812 @var{buf_size}: holds the size of @code{buf}
5814 This function will return the specified Object identifier, of the
5817 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5818 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5819 updated if the provided buffer is not long enough, otherwise a
5820 negative error value.
5822 @strong{Since:} 2.4.0
5825 @subheading gnutls_x509_trust_list_add_cas
5826 @anchor{gnutls_x509_trust_list_add_cas}
5827 @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})
5828 @var{list}: The structure of the list
5830 @var{clist}: A list of CAs
5832 @var{clist_size}: The length of the CA list
5834 @var{flags}: should be 0 or an or'ed sequence of @code{GNUTLS_TL} options.
5836 This function will add the given certificate authorities
5837 to the trusted list. The list of CAs must not be deinitialized
5838 during this structure's lifetime.
5840 If the flag @code{GNUTLS_TL_NO_DUPLICATES} is specified, then
5841 the provided @code{clist} entries that are duplicates will not be
5842 added to the list and will be deinitialized.
5844 @strong{Returns:} The number of added elements is returned.
5846 @strong{Since:} 3.0.0
5849 @subheading gnutls_x509_trust_list_add_crls
5850 @anchor{gnutls_x509_trust_list_add_crls}
5851 @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})
5852 @var{list}: The structure of the list
5854 @var{crl_list}: A list of CRLs
5856 @var{crl_size}: The length of the CRL list
5858 @var{flags}: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
5860 @var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
5862 This function will add the given certificate revocation lists
5863 to the trusted list. The list of CRLs must not be deinitialized
5864 during this structure's lifetime.
5866 This function must be called after @code{gnutls_x509_trust_list_add_cas()}
5867 to allow verifying the CRLs for validity.
5869 @strong{Returns:} The number of added elements is returned.
5874 @subheading gnutls_x509_trust_list_add_named_crt
5875 @anchor{gnutls_x509_trust_list_add_named_crt}
5876 @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})
5877 @var{list}: The structure of the list
5879 @var{cert}: A certificate
5881 @var{name}: An identifier for the certificate
5883 @var{name_size}: The size of the identifier
5885 @var{flags}: should be 0.
5887 This function will add the given certificate to the trusted
5888 list and associate it with a name. The certificate will not be
5889 be used for verification with @code{gnutls_x509_trust_list_verify_crt()}
5890 but only with @code{gnutls_x509_trust_list_verify_named_crt()} .
5892 In principle this function can be used to set individual "server"
5893 certificates that are trusted by the user for that specific server
5894 but for no other purposes.
5896 The certificate must not be deinitialized during the lifetime
5897 of the trusted list.
5899 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5900 negative error value.
5902 @strong{Since:} 3.0.0
5905 @subheading gnutls_x509_trust_list_add_system_trust
5906 @anchor{gnutls_x509_trust_list_add_system_trust}
5907 @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})
5908 @var{list}: The structure of the list
5910 @var{tl_flags}: GNUTLS_TL_*
5912 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
5914 This function adds the system's default trusted certificate
5915 authorities to the trusted list. Note that on unsupported system
5916 this function returns @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .
5918 @strong{Returns:} The number of added elements or a negative error code on error.
5923 @subheading gnutls_x509_trust_list_add_trust_file
5924 @anchor{gnutls_x509_trust_list_add_trust_file}
5925 @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})
5926 @var{list}: The structure of the list
5928 @var{ca_file}: A file containing a list of CAs (optional)
5930 @var{crl_file}: A file containing a list of CRLs (optional)
5932 @var{type}: The format of the certificates
5934 @var{tl_flags}: GNUTLS_TL_*
5936 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
5938 This function will add the given certificate authorities
5939 to the trusted list. pkcs11 URLs are also accepted, instead
5940 of files, by this function.
5942 @strong{Returns:} The number of added elements is returned.
5947 @subheading gnutls_x509_trust_list_add_trust_mem
5948 @anchor{gnutls_x509_trust_list_add_trust_mem}
5949 @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})
5950 @var{list}: The structure of the list
5952 @var{cas}: A buffer containing a list of CAs (optional)
5954 @var{crls}: A buffer containing a list of CRLs (optional)
5956 @var{type}: The format of the certificates
5958 @var{tl_flags}: GNUTLS_TL_*
5960 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
5962 This function will add the given certificate authorities
5963 to the trusted list.
5965 @strong{Returns:} The number of added elements is returned.
5970 @subheading gnutls_x509_trust_list_deinit
5971 @anchor{gnutls_x509_trust_list_deinit}
5972 @deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all})
5973 @var{list}: The structure to be deinitialized
5975 @var{all}: if non-zero it will deinitialize all the certificates and CRLs contained in the structure.
5977 This function will deinitialize a trust list. Note that the
5978 @code{all} flag should be typically non-zero unless you have specified
5979 your certificates using @code{gnutls_x509_trust_list_add_cas()} and you
5980 want to prevent them from being deinitialized by this function.
5982 @strong{Since:} 3.0.0
5985 @subheading gnutls_x509_trust_list_get_issuer
5986 @anchor{gnutls_x509_trust_list_get_issuer}
5987 @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})
5988 @var{list}: The structure of the list
5990 @var{cert}: is the certificate to find issuer for
5992 @var{issuer}: Will hold the issuer if any. Should be treated as constant.
5994 @var{flags}: Use zero.
5996 This function will attempt to find the issuer of the
5999 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6000 negative error value.
6005 @subheading gnutls_x509_trust_list_init
6006 @anchor{gnutls_x509_trust_list_init}
6007 @deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size})
6008 @var{list}: The structure to be initialized
6010 @var{size}: The size of the internal hash table. Use (0) for default size.
6012 This function will initialize an X.509 trust list structure.
6014 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6015 negative error value.
6017 @strong{Since:} 3.0.0
6020 @subheading gnutls_x509_trust_list_remove_cas
6021 @anchor{gnutls_x509_trust_list_remove_cas}
6022 @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})
6023 @var{list}: The structure of the list
6025 @var{clist}: A list of CAs
6027 @var{clist_size}: The length of the CA list
6029 This function will remove the given certificate authorities
6030 from the trusted list.
6032 Note that this function can accept certificates and authorities
6033 not yet known. In that case they will be kept in a separate
6034 black list that will be used during certificate verification.
6035 Unlike @code{gnutls_x509_trust_list_add_cas()} there is no deinitialization
6036 restriction for certificate list provided in this function.
6038 @strong{Returns:} The number of removed elements is returned.
6040 @strong{Since:} 3.1.10
6043 @subheading gnutls_x509_trust_list_remove_trust_file
6044 @anchor{gnutls_x509_trust_list_remove_trust_file}
6045 @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})
6046 @var{list}: The structure of the list
6048 @var{ca_file}: A file containing a list of CAs
6050 @var{type}: The format of the certificates
6052 This function will remove the given certificate authorities
6053 from the trusted list, and add them into a black list when needed.
6054 PKCS 11 URLs are also accepted, instead
6055 of files, by this function.
6057 See also @code{gnutls_x509_trust_list_remove_cas()} .
6059 @strong{Returns:} The number of added elements is returned.
6061 @strong{Since:} 3.1.10
6064 @subheading gnutls_x509_trust_list_remove_trust_mem
6065 @anchor{gnutls_x509_trust_list_remove_trust_mem}
6066 @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})
6067 @var{list}: The structure of the list
6069 @var{cas}: A buffer containing a list of CAs (optional)
6071 @var{type}: The format of the certificates
6073 This function will remove the provided certificate authorities
6074 from the trusted list, and add them into a black list when needed.
6076 See also @code{gnutls_x509_trust_list_remove_cas()} .
6078 @strong{Returns:} The number of removed elements is returned.
6080 @strong{Since:} 3.1.10
6083 @subheading gnutls_x509_trust_list_verify_crt
6084 @anchor{gnutls_x509_trust_list_verify_crt}
6085 @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})
6086 @var{list}: The structure of the list
6088 @var{cert_list}: is the certificate list to be verified
6090 @var{cert_list_size}: is the certificate list size
6092 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6094 @var{voutput}: will hold the certificate verification output.
6096 @var{func}: If non-null will be called on each chain element verification with the output.
6098 This function will try to verify the given certificate and return
6099 its status. The @code{verify} parameter will hold an OR'ed sequence of
6100 @code{gnutls_certificate_status_t} flags.
6102 Additionally a certificate verification profile can be specified
6103 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6104 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6107 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6108 negative error value.
6113 @subheading gnutls_x509_trust_list_verify_named_crt
6114 @anchor{gnutls_x509_trust_list_verify_named_crt}
6115 @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})
6116 @var{list}: The structure of the list
6118 @var{cert}: is the certificate to be verified
6120 @var{name}: is the certificate's name
6122 @var{name_size}: is the certificate's name size
6124 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6126 @var{voutput}: will hold the certificate verification output.
6128 @var{func}: If non-null will be called on each chain element verification with the output.
6130 This function will try to find a certificate that is associated with the provided
6131 name --see @code{gnutls_x509_trust_list_add_named_crt()} . If a match is found the certificate is considered valid.
6132 In addition to that this function will also check CRLs.
6133 The @code{voutput} parameter will hold an OR'ed sequence of @code{gnutls_certificate_status_t} flags.
6135 Additionally a certificate verification profile can be specified
6136 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6137 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6140 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6141 negative error value.
6143 @strong{Since:} 3.0.0