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} )
415 @var{san}: The alternative name data
417 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
419 @var{serial}: The authorityCertSerialNumber number
421 This function will return a specific authorityCertIssuer name as stored in
422 the @code{aki} structure, as well as the authorityCertSerialNumber. All the returned
423 values should be treated as constant, and may be set to @code{NULL} when are not required.
425 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
426 if the index is out of bounds, otherwise a negative error value.
428 @strong{Since:} 3.3.0
431 @subheading gnutls_x509_aki_get_id
432 @anchor{gnutls_x509_aki_get_id}
433 @deftypefun {int} {gnutls_x509_aki_get_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{id})
434 @var{aki}: The authority key ID structure
436 @var{id}: Will hold the identifier
438 This function will return the key identifier as stored in
439 the @code{aki} structure. The identifier should be treated as constant.
441 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
442 if the index is out of bounds, otherwise a negative error value.
444 @strong{Since:} 3.3.0
447 @subheading gnutls_x509_aki_init
448 @anchor{gnutls_x509_aki_init}
449 @deftypefun {int} {gnutls_x509_aki_init} (gnutls_x509_aki_t * @var{aki})
450 @var{aki}: The authority key ID structure
452 This function will initialize an authority key ID structure.
454 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
456 @strong{Since:} 3.3.0
459 @subheading gnutls_x509_aki_set_cert_issuer
460 @anchor{gnutls_x509_aki_set_cert_issuer}
461 @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})
462 @var{aki}: The authority key ID structure
464 @var{san_type}: the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null
466 @var{san}: The alternative name data
468 @var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME}
470 @var{serial}: The authorityCertSerialNumber number (may be null)
472 This function will set the authorityCertIssuer name and the authorityCertSerialNumber
473 to be stored in the @code{aki} structure. When storing multiple names, the serial
474 should be set on the first call, and subsequent calls should use a @code{NULL} serial.
476 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
478 @strong{Since:} 3.3.0
481 @subheading gnutls_x509_aki_set_id
482 @anchor{gnutls_x509_aki_set_id}
483 @deftypefun {int} {gnutls_x509_aki_set_id} (gnutls_x509_aki_t @var{aki}, const gnutls_datum_t * @var{id})
484 @var{aki}: The authority key ID structure
486 @var{id}: the key identifier
488 This function will set the keyIdentifier to be stored in the @code{aki} structure.
490 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
492 @strong{Since:} 3.3.0
495 @subheading gnutls_x509_crl_check_issuer
496 @anchor{gnutls_x509_crl_check_issuer}
497 @deftypefun {int} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer})
498 @var{crl}: is the CRL to be checked
500 @var{issuer}: is the certificate of a possible issuer
502 This function will check if the given CRL was issued by the given
505 @strong{Returns:} true (1) if the given CRL was issued by the given issuer,
506 and false (0) if not.
509 @subheading gnutls_x509_crl_deinit
510 @anchor{gnutls_x509_crl_deinit}
511 @deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl})
512 @var{crl}: The structure to be deinitialized
514 This function will deinitialize a CRL structure.
517 @subheading gnutls_x509_crl_dist_points_deinit
518 @anchor{gnutls_x509_crl_dist_points_deinit}
519 @deftypefun {void} {gnutls_x509_crl_dist_points_deinit} (gnutls_x509_crl_dist_points_t @var{cdp})
520 @var{cdp}: The CRL distribution points structure
522 This function will deinitialize a CRL distribution points structure.
524 @strong{Since:} 3.3.0
527 @subheading gnutls_x509_crl_dist_points_get
528 @anchor{gnutls_x509_crl_dist_points_get}
529 @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})
530 @var{cdp}: The CRL distribution points structure
532 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
534 @var{type}: The name type of the corresponding name (gnutls_x509_subject_alt_name_t)
536 @var{san}: The distribution point names (to be treated as constant)
538 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
540 This function retrieves the individual CRL distribution points (2.5.29.31),
541 contained in provided structure.
543 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
544 if the index is out of bounds, otherwise a negative error value.
547 @subheading gnutls_x509_crl_dist_points_init
548 @anchor{gnutls_x509_crl_dist_points_init}
549 @deftypefun {int} {gnutls_x509_crl_dist_points_init} (gnutls_x509_crl_dist_points_t * @var{cdp})
550 @var{cdp}: The CRL distribution points structure
552 This function will initialize a CRL distribution points structure.
554 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
556 @strong{Since:} 3.3.0
559 @subheading gnutls_x509_crl_dist_points_set
560 @anchor{gnutls_x509_crl_dist_points_set}
561 @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})
562 @var{cdp}: The CRL distribution points structure
564 @var{type}: The type of the name (of @code{gnutls_subject_alt_names_t} )
566 @var{san}: The point name data
568 @var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
570 This function will store the specified CRL distibution point value
571 the @code{cdp} structure.
573 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
575 @strong{Since:} 3.3.0
578 @subheading gnutls_x509_crl_export
579 @anchor{gnutls_x509_crl_export}
580 @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})
581 @var{crl}: Holds the revocation list
583 @var{format}: the format of output params. One of PEM or DER.
585 @var{output_data}: will contain a private key PEM or DER encoded
587 @var{output_data_size}: holds the size of output_data (and will
588 be replaced by the actual size of parameters)
590 This function will export the revocation list to DER or PEM format.
592 If the buffer provided is not long enough to hold the output, then
593 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
595 If the structure is PEM encoded, it will have a header
598 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
599 negative error value.
602 @subheading gnutls_x509_crl_export2
603 @anchor{gnutls_x509_crl_export2}
604 @deftypefun {int} {gnutls_x509_crl_export2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
605 @var{crl}: Holds the revocation list
607 @var{format}: the format of output params. One of PEM or DER.
609 @var{out}: will contain a private key PEM or DER encoded
611 This function will export the revocation list to DER or PEM format.
613 The output buffer is allocated using @code{gnutls_malloc()} .
615 If the structure is PEM encoded, it will have a header
618 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
619 negative error value.
624 @subheading gnutls_x509_crl_get_authority_key_gn_serial
625 @anchor{gnutls_x509_crl_get_authority_key_gn_serial}
626 @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})
627 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
629 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
631 @var{alt}: is the place where the alternative name will be copied to
633 @var{alt_size}: holds the size of alt.
635 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
637 @var{serial}: buffer to store the serial number (may be null)
639 @var{serial_size}: Holds the size of the serial field (may be null)
641 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
643 This function will return the X.509 authority key
644 identifier when stored as a general name (authorityCertIssuer)
647 Because more than one general names might be stored
648 @code{seq} can be used as a counter to request them all until
649 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
651 @strong{Returns:} Returns 0 on success, or an error code.
656 @subheading gnutls_x509_crl_get_authority_key_id
657 @anchor{gnutls_x509_crl_get_authority_key_id}
658 @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})
659 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
661 @var{id}: The place where the identifier will be copied
663 @var{id_size}: Holds the size of the result field.
665 @var{critical}: will be non-zero if the extension is marked as critical
668 This function will return the CRL authority's key identifier. This
669 is obtained by the X.509 Authority Key identifier extension field
670 (2.5.29.35). Note that this function
671 only returns the keyIdentifier field of the extension and
672 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
673 the name and serial number of the certificate. In that case
674 @code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used.
676 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
677 negative error code in case of an error.
679 @strong{Since:} 2.8.0
682 @subheading gnutls_x509_crl_get_crt_count
683 @anchor{gnutls_x509_crl_get_crt_count}
684 @deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl})
685 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
687 This function will return the number of revoked certificates in the
690 @strong{Returns:} number of certificates, a negative error code on failure.
693 @subheading gnutls_x509_crl_get_crt_serial
694 @anchor{gnutls_x509_crl_get_crt_serial}
695 @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})
696 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
698 @var{indx}: the index of the certificate to extract (starting from 0)
700 @var{serial}: where the serial number will be copied
702 @var{serial_size}: initially holds the size of serial
704 @var{t}: if non null, will hold the time this certificate was revoked
706 This function will retrieve the serial number of the specified, by
707 the index, revoked certificate.
709 Note that this function will have performance issues in large sequences
710 of revoked certificates. In that case use @code{gnutls_x509_crl_iter_crt_serial()} .
712 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
713 negative error value.
716 @subheading gnutls_x509_crl_get_dn_oid
717 @anchor{gnutls_x509_crl_get_dn_oid}
718 @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})
719 @var{crl}: should contain a gnutls_x509_crl_t structure
721 @var{indx}: Specifies which DN OID to send. Use (0) to get the first one.
723 @var{oid}: a pointer to a structure to hold the name (may be null)
725 @var{sizeof_oid}: initially holds the size of 'oid'
727 This function will extract the requested OID of the name of the CRL
728 issuer, specified by the given index.
730 If oid is null then only the size will be filled.
732 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
733 not long enough, and in that case the sizeof_oid will be updated
734 with the required size. On success 0 is returned.
737 @subheading gnutls_x509_crl_get_extension_data
738 @anchor{gnutls_x509_crl_get_extension_data}
739 @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})
740 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
742 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
744 @var{data}: a pointer to a structure to hold the data (may be null)
746 @var{sizeof_data}: initially holds the size of @code{oid}
748 This function will return the requested extension data in the CRL.
749 The extension data will be stored as a string in the provided
752 Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and
753 critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead,
754 if you want to get data indexed by the extension OID rather than
757 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
758 negative error code in case of an error. If your have reached the
759 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
762 @strong{Since:} 2.8.0
765 @subheading gnutls_x509_crl_get_extension_data2
766 @anchor{gnutls_x509_crl_get_extension_data2}
767 @deftypefun {int} {gnutls_x509_crl_get_extension_data2} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, gnutls_datum_t * @var{data})
768 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
770 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
772 @var{data}: will contain the extension DER-encoded data
774 This function will return the requested by the index extension data in the
775 certificate revocation list. The extension data will be allocated using
776 @code{gnutls_malloc()} .
778 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
780 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
781 otherwise a negative error code is returned. If you have reached the
782 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
786 @subheading gnutls_x509_crl_get_extension_info
787 @anchor{gnutls_x509_crl_get_extension_info}
788 @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})
789 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
791 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
793 @var{oid}: a pointer to a structure to hold the OID
795 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
796 holds actual size of @code{oid} .
798 @var{critical}: output variable with critical flag, may be NULL.
800 This function will return the requested extension OID in the CRL,
801 and the critical flag for it. The extension OID will be stored as
802 a string in the provided buffer. Use
803 @code{gnutls_x509_crl_get_extension_data()} to extract the data.
805 If the buffer provided is not long enough to hold the output, then
806 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
809 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
810 negative error code in case of an error. If your have reached the
811 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
814 @strong{Since:} 2.8.0
817 @subheading gnutls_x509_crl_get_extension_oid
818 @anchor{gnutls_x509_crl_get_extension_oid}
819 @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})
820 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
822 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
824 @var{oid}: a pointer to a structure to hold the OID (may be null)
826 @var{sizeof_oid}: initially holds the size of @code{oid}
828 This function will return the requested extension OID in the CRL.
829 The extension OID will be stored as a string in the provided
832 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
833 negative error code in case of an error. If your have reached the
834 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
837 @strong{Since:} 2.8.0
840 @subheading gnutls_x509_crl_get_issuer_dn
841 @anchor{gnutls_x509_crl_get_issuer_dn}
842 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (const gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf})
843 @var{crl}: should contain a gnutls_x509_crl_t structure
845 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
847 @var{sizeof_buf}: initially holds the size of @code{buf}
849 This function will copy the name of the CRL issuer in the provided
850 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
851 described in RFC4514. The output string will be ASCII or UTF-8
852 encoded, depending on the certificate data.
854 If buf is @code{NULL} then only the size will be filled.
856 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
857 not long enough, and in that case the sizeof_buf will be updated
858 with the required size, and 0 on success.
861 @subheading gnutls_x509_crl_get_issuer_dn2
862 @anchor{gnutls_x509_crl_get_issuer_dn2}
863 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn2} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
864 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
866 @var{dn}: a pointer to a structure to hold the name
868 This function will allocate buffer and copy the name of the CRL issuer.
869 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
870 described in RFC4514. The output string will be ASCII or UTF-8
871 encoded, depending on the certificate data.
873 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
874 negative error value.
876 @strong{Since:} 3.1.10
879 @subheading gnutls_x509_crl_get_issuer_dn_by_oid
880 @anchor{gnutls_x509_crl_get_issuer_dn_by_oid}
881 @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})
882 @var{crl}: should contain a gnutls_x509_crl_t structure
884 @var{oid}: holds an Object Identified in null terminated string
886 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
888 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
890 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
892 @var{sizeof_buf}: initially holds the size of @code{buf}
894 This function will extract the part of the name of the CRL issuer
895 specified by the given OID. The output will be encoded as described
896 in RFC4514. The output string will be ASCII or UTF-8 encoded,
897 depending on the certificate data.
899 Some helper macros with popular OIDs can be found in gnutls/x509.h
900 If raw flag is (0), this function will only return known OIDs as
901 text. Other OIDs will be DER encoded, as described in RFC4514 -- in
902 hex format with a '#' prefix. You can check about known OIDs
903 using @code{gnutls_x509_dn_oid_known()} .
905 If buf is null then only the size will be filled.
907 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
908 not long enough, and in that case the sizeof_buf will be updated
909 with the required size, and 0 on success.
912 @subheading gnutls_x509_crl_get_next_update
913 @anchor{gnutls_x509_crl_get_next_update}
914 @deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl})
915 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
917 This function will return the time the next CRL will be issued.
918 This field is optional in a CRL so it might be normal to get an
921 @strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error.
924 @subheading gnutls_x509_crl_get_number
925 @anchor{gnutls_x509_crl_get_number}
926 @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})
927 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
929 @var{ret}: The place where the number will be copied
931 @var{ret_size}: Holds the size of the result field.
933 @var{critical}: will be non-zero if the extension is marked as critical
936 This function will return the CRL number extension. This is
937 obtained by the CRL Number extension field (2.5.29.20).
939 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
940 negative error code in case of an error.
942 @strong{Since:} 2.8.0
945 @subheading gnutls_x509_crl_get_raw_issuer_dn
946 @anchor{gnutls_x509_crl_get_raw_issuer_dn}
947 @deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
948 @var{crl}: should contain a gnutls_x509_crl_t structure
950 @var{dn}: will hold the starting point of the DN
952 This function will return a pointer to the DER encoded DN structure
955 @strong{Returns:} a negative error code on error, and (0) on success.
957 @strong{Since:} 2.12.0
960 @subheading gnutls_x509_crl_get_signature
961 @anchor{gnutls_x509_crl_get_signature}
962 @deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig})
963 @var{crl}: should contain a gnutls_x509_crl_t structure
965 @var{sig}: a pointer where the signature part will be copied (may be null).
967 @var{sizeof_sig}: initially holds the size of @code{sig}
969 This function will extract the signature field of a CRL.
971 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
972 negative error value.
975 @subheading gnutls_x509_crl_get_signature_algorithm
976 @anchor{gnutls_x509_crl_get_signature_algorithm}
977 @deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl})
978 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
980 This function will return a value of the @code{gnutls_sign_algorithm_t}
981 enumeration that is the signature algorithm.
983 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
984 negative error value.
987 @subheading gnutls_x509_crl_get_this_update
988 @anchor{gnutls_x509_crl_get_this_update}
989 @deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl})
990 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
992 This function will return the time this CRL was issued.
994 @strong{Returns:} when the CRL was issued, or (time_t)-1 on error.
997 @subheading gnutls_x509_crl_get_version
998 @anchor{gnutls_x509_crl_get_version}
999 @deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl})
1000 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
1002 This function will return the version of the specified CRL.
1004 @strong{Returns:} The version number, or a negative error code on error.
1007 @subheading gnutls_x509_crl_import
1008 @anchor{gnutls_x509_crl_import}
1009 @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})
1010 @var{crl}: The structure to store the parsed CRL.
1012 @var{data}: The DER or PEM encoded CRL.
1014 @var{format}: One of DER or PEM
1016 This function will convert the given DER or PEM encoded CRL
1017 to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'.
1019 If the CRL is PEM encoded it should have a header of "X509 CRL".
1021 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1022 negative error value.
1025 @subheading gnutls_x509_crl_init
1026 @anchor{gnutls_x509_crl_init}
1027 @deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl})
1028 @var{crl}: The structure to be initialized
1030 This function will initialize a CRL structure. CRL stands for
1031 Certificate Revocation List. A revocation list usually contains
1032 lists of certificate serial numbers that have been revoked by an
1033 Authority. The revocation lists are always signed with the
1034 authority's private key.
1036 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1037 negative error value.
1040 @subheading gnutls_x509_crl_iter_crt_serial
1041 @anchor{gnutls_x509_crl_iter_crt_serial}
1042 @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})
1043 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
1045 @var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} )
1047 @var{serial}: where the serial number will be copied
1049 @var{serial_size}: initially holds the size of serial
1051 @var{t}: if non null, will hold the time this certificate was revoked
1053 This function performs the same as @code{gnutls_x509_crl_get_crt_serial()} ,
1054 but reads sequentially and keeps state in the iterator
1055 between calls. That allows it to provide better performance in sequences
1056 with many elements (50000+).
1058 When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1059 is returned and the iterator is reset.
1061 After use, the iterator must be deinitialized using @code{gnutls_x509_crl_iter_deinit()} .
1063 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1064 negative error value.
1067 @subheading gnutls_x509_crl_iter_deinit
1068 @anchor{gnutls_x509_crl_iter_deinit}
1069 @deftypefun {void} {gnutls_x509_crl_iter_deinit} (gnutls_x509_crl_iter_t @var{iter})
1070 @var{iter}: The iterator structure to be deinitialized
1072 This function will deinitialize an iterator structure.
1075 @subheading gnutls_x509_crl_list_import
1076 @anchor{gnutls_x509_crl_list_import}
1077 @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})
1078 @var{crls}: The structures to store the parsed CRLs. Must not be initialized.
1080 @var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available.
1082 @var{data}: The PEM encoded CRLs
1084 @var{format}: One of DER or PEM.
1086 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
1088 This function will convert the given PEM encoded CRL list
1089 to the native gnutls_x509_crl_t format. The output will be stored
1090 in @code{crls} . They will be automatically initialized.
1092 If the Certificate is PEM encoded it should have a header of "X509 CRL".
1094 @strong{Returns:} the number of certificates read or a negative error value.
1099 @subheading gnutls_x509_crl_list_import2
1100 @anchor{gnutls_x509_crl_list_import2}
1101 @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})
1102 @var{crls}: The structures to store the parsed crl list. Must not be initialized.
1104 @var{size}: It will contain the size of the list.
1106 @var{data}: The PEM encoded CRL.
1108 @var{format}: One of DER or PEM.
1110 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
1112 This function will convert the given PEM encoded CRL list
1113 to the native gnutls_x509_crl_t format. The output will be stored
1114 in @code{crls} . They will be automatically initialized.
1116 If the Certificate is PEM encoded it should have a header of "X509
1119 @strong{Returns:} the number of certificates read or a negative error value.
1124 @subheading gnutls_x509_crl_print
1125 @anchor{gnutls_x509_crl_print}
1126 @deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1127 @var{crl}: The structure to be printed
1129 @var{format}: Indicate the format to use
1131 @var{out}: Newly allocated datum with null terminated string.
1133 This function will pretty print a X.509 certificate revocation
1134 list, suitable for display to a human.
1136 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
1138 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1139 negative error value.
1142 @subheading gnutls_x509_crl_set_authority_key_id
1143 @anchor{gnutls_x509_crl_set_authority_key_id}
1144 @deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size})
1145 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1147 @var{id}: The key ID
1149 @var{id_size}: Holds the size of the serial field.
1151 This function will set the CRL's authority key ID extension. Only
1152 the keyIdentifier field can be set with this function. This may
1153 be used by an authority that holds multiple private keys, to distinguish
1156 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1157 negative error value.
1159 @strong{Since:} 2.8.0
1162 @subheading gnutls_x509_crl_set_crt
1163 @anchor{gnutls_x509_crl_set_crt}
1164 @deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time})
1165 @var{crl}: should contain a gnutls_x509_crl_t structure
1167 @var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate
1169 @var{revocation_time}: The time this certificate was revoked
1171 This function will set a revoked certificate's serial number to the CRL.
1173 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1174 negative error value.
1177 @subheading gnutls_x509_crl_set_crt_serial
1178 @anchor{gnutls_x509_crl_set_crt_serial}
1179 @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})
1180 @var{crl}: should contain a gnutls_x509_crl_t structure
1182 @var{serial}: The revoked certificate's serial number
1184 @var{serial_size}: Holds the size of the serial field.
1186 @var{revocation_time}: The time this certificate was revoked
1188 This function will set a revoked certificate's serial number to the CRL.
1190 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1191 negative error value.
1194 @subheading gnutls_x509_crl_set_next_update
1195 @anchor{gnutls_x509_crl_set_next_update}
1196 @deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time})
1197 @var{crl}: should contain a gnutls_x509_crl_t structure
1199 @var{exp_time}: The actual time
1201 This function will set the time this CRL will be updated.
1203 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1204 negative error value.
1207 @subheading gnutls_x509_crl_set_number
1208 @anchor{gnutls_x509_crl_set_number}
1209 @deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size})
1210 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1212 @var{nr}: The CRL number
1214 @var{nr_size}: Holds the size of the nr field.
1216 This function will set the CRL's number extension. This
1217 is to be used as a unique and monotonic number assigned to
1218 the CRL by the authority.
1220 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1221 negative error value.
1223 @strong{Since:} 2.8.0
1226 @subheading gnutls_x509_crl_set_this_update
1227 @anchor{gnutls_x509_crl_set_this_update}
1228 @deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time})
1229 @var{crl}: should contain a gnutls_x509_crl_t structure
1231 @var{act_time}: The actual time
1233 This function will set the time this CRL was issued.
1235 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1236 negative error value.
1239 @subheading gnutls_x509_crl_set_version
1240 @anchor{gnutls_x509_crl_set_version}
1241 @deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version})
1242 @var{crl}: should contain a gnutls_x509_crl_t structure
1244 @var{version}: holds the version number. For CRLv1 crls must be 1.
1246 This function will set the version of the CRL. This
1247 must be one for CRL version 1, and so on. The CRLs generated
1248 by gnutls should have a version number of 2.
1250 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1251 negative error value.
1254 @subheading gnutls_x509_crl_sign2
1255 @anchor{gnutls_x509_crl_sign2}
1256 @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})
1257 @var{crl}: should contain a gnutls_x509_crl_t structure
1259 @var{issuer}: is the certificate of the certificate issuer
1261 @var{issuer_key}: holds the issuer's private key
1263 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1265 @var{flags}: must be 0
1267 This function will sign the CRL with the issuer's private key, and
1268 will copy the issuer's information into the CRL.
1270 This must be the last step in a certificate CRL since all
1271 the previously set parameters are now signed.
1273 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1274 negative error value.
1277 @subheading gnutls_x509_crl_verify
1278 @anchor{gnutls_x509_crl_verify}
1279 @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})
1280 @var{crl}: is the crl to be verified
1282 @var{trusted_cas}: is a certificate list that is considered to be trusted one
1284 @var{tcas_size}: holds the number of CA certificates in CA_list
1286 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1288 @var{verify}: will hold the crl verification output.
1290 This function will try to verify the given crl and return its verification status.
1291 See @code{gnutls_x509_crt_list_verify()} for a detailed description of
1292 return values. Note that since GnuTLS 3.1.4 this function includes
1295 Note that value in @code{verify} is set only when the return value of this
1296 function is success (i.e, failure to trust a CRL a certificate does not imply
1297 a negative return value).
1299 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1300 negative error value.
1303 @subheading gnutls_x509_crq_deinit
1304 @anchor{gnutls_x509_crq_deinit}
1305 @deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq})
1306 @var{crq}: The structure to be initialized
1308 This function will deinitialize a PKCS@code{10} certificate request
1312 @subheading gnutls_x509_crq_export
1313 @anchor{gnutls_x509_crq_export}
1314 @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})
1315 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1317 @var{format}: the format of output params. One of PEM or DER.
1319 @var{output_data}: will contain a certificate request PEM or DER encoded
1321 @var{output_data_size}: holds the size of output_data (and will be
1322 replaced by the actual size of parameters)
1324 This function will export the certificate request to a PEM or DER
1325 encoded PKCS10 structure.
1327 If the buffer provided is not long enough to hold the output, then
1328 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and
1329 * @code{output_data_size} will be updated.
1331 If the structure is PEM encoded, it will have a header of "BEGIN
1332 NEW CERTIFICATE REQUEST".
1334 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1335 negative error value.
1338 @subheading gnutls_x509_crq_export2
1339 @anchor{gnutls_x509_crq_export2}
1340 @deftypefun {int} {gnutls_x509_crq_export2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
1341 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1343 @var{format}: the format of output params. One of PEM or DER.
1345 @var{out}: will contain a certificate request PEM or DER encoded
1347 This function will export the certificate request to a PEM or DER
1348 encoded PKCS10 structure.
1350 The output buffer is allocated using @code{gnutls_malloc()} .
1352 If the structure is PEM encoded, it will have a header of "BEGIN
1353 NEW CERTIFICATE REQUEST".
1355 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1356 negative error value.
1361 @subheading gnutls_x509_crq_get_attribute_by_oid
1362 @anchor{gnutls_x509_crq_get_attribute_by_oid}
1363 @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})
1364 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1366 @var{oid}: holds an Object Identifier in null-terminated string
1368 @var{indx}: In case multiple same OIDs exist in the attribute list, this
1369 specifies which to get, use (0) to get the first one
1371 @var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} )
1373 @var{buf_size}: initially holds the size of @code{buf}
1375 This function will return the attribute in the certificate request
1376 specified by the given Object ID. The attribute will be DER
1379 Attributes in a certificate request is an optional set of data
1380 appended to the request. Their interpretation depends on the CA policy.
1382 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1383 negative error value.
1386 @subheading gnutls_x509_crq_get_attribute_data
1387 @anchor{gnutls_x509_crq_get_attribute_data}
1388 @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})
1389 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1391 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1393 @var{data}: a pointer to a structure to hold the data (may be null)
1395 @var{sizeof_data}: initially holds the size of @code{oid}
1397 This function will return the requested attribute data in the
1398 certificate request. The attribute data will be stored as a string in the
1401 Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID.
1402 Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead,
1403 if you want to get data indexed by the attribute OID rather than
1406 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1407 negative error code in case of an error. If your have reached the
1408 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1411 @strong{Since:} 2.8.0
1414 @subheading gnutls_x509_crq_get_attribute_info
1415 @anchor{gnutls_x509_crq_get_attribute_info}
1416 @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})
1417 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1419 @var{indx}: Specifies which attribute number to get. Use (0) to get the first one.
1421 @var{oid}: a pointer to a structure to hold the OID
1423 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1424 holds actual size of @code{oid} .
1426 This function will return the requested attribute OID in the
1427 certificate, and the critical flag for it. The attribute OID will
1428 be stored as a string in the provided buffer. Use
1429 @code{gnutls_x509_crq_get_attribute_data()} to extract the data.
1431 If the buffer provided is not long enough to hold the output, then
1432 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1435 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1436 negative error code in case of an error. If your have reached the
1437 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1440 @strong{Since:} 2.8.0
1443 @subheading gnutls_x509_crq_get_basic_constraints
1444 @anchor{gnutls_x509_crq_get_basic_constraints}
1445 @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})
1446 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1448 @var{critical}: will be non-zero if the extension is marked as critical
1450 @var{ca}: pointer to output integer indicating CA status, may be NULL,
1451 value is 1 if the certificate CA flag is set, 0 otherwise.
1453 @var{pathlen}: pointer to output integer indicating path length (may be
1454 NULL), non-negative error codes indicate a present pathLenConstraint
1455 field and the actual value, -1 indicate that the field is absent.
1457 This function will read the certificate's basic constraints, and
1458 return the certificates CA status. It reads the basicConstraints
1459 X.509 extension (2.5.29.19).
1461 @strong{Returns:} If the certificate is a CA a positive value will be
1462 returned, or (0) if the certificate does not have CA flag set.
1463 A negative error code may be returned in case of errors. If the
1464 certificate does not contain the basicConstraints extension
1465 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1467 @strong{Since:} 2.8.0
1470 @subheading gnutls_x509_crq_get_challenge_password
1471 @anchor{gnutls_x509_crq_get_challenge_password}
1472 @deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{pass_size})
1473 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1475 @var{pass}: will hold a (0)-terminated password string
1477 @var{pass_size}: Initially holds the size of @code{pass} .
1479 This function will return the challenge password in the request.
1480 The challenge password is intended to be used for requesting a
1481 revocation of the certificate.
1483 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1484 negative error value.
1487 @subheading gnutls_x509_crq_get_dn
1488 @anchor{gnutls_x509_crq_get_dn}
1489 @deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{buf_size})
1490 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1492 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1494 @var{buf_size}: initially holds the size of @code{buf}
1496 This function will copy the name of the Certificate request subject
1497 to the provided buffer. The name will be in the form
1498 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
1499 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate
1502 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
1503 long enough, and in that case the * @code{buf_size} will be updated with
1504 the required size. On success 0 is returned.
1507 @subheading gnutls_x509_crq_get_dn2
1508 @anchor{gnutls_x509_crq_get_dn2}
1509 @deftypefun {int} {gnutls_x509_crq_get_dn2} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn})
1510 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1512 @var{dn}: a pointer to a structure to hold the name
1514 This function will allocate buffer and copy the name of the Certificate
1515 request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
1516 described in RFC4514. The output string will be ASCII or UTF-8
1517 encoded, depending on the certificate data.
1519 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1520 negative error value. and a negative error code on error.
1522 @strong{Since:} 3.1.10
1525 @subheading gnutls_x509_crq_get_dn_by_oid
1526 @anchor{gnutls_x509_crq_get_dn_by_oid}
1527 @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})
1528 @var{crq}: should contain a gnutls_x509_crq_t structure
1530 @var{oid}: holds an Object Identifier in a null terminated string
1532 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies
1533 which to get. Use (0) to get the first one.
1535 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
1537 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1539 @var{buf_size}: initially holds the size of @code{buf}
1541 This function will extract the part of the name of the Certificate
1542 request subject, specified by the given OID. The output will be
1543 encoded as described in RFC2253. The output string will be ASCII
1544 or UTF-8 encoded, depending on the certificate data.
1546 Some helper macros with popular OIDs can be found in gnutls/x509.h
1547 If raw flag is (0), this function will only return known OIDs as
1548 text. Other OIDs will be DER encoded, as described in RFC2253 --
1549 in hex format with a '\#' prefix. You can check about known OIDs
1550 using @code{gnutls_x509_dn_oid_known()} .
1552 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1553 not long enough, and in that case the * @code{buf_size} will be
1554 updated with the required size. On success 0 is returned.
1557 @subheading gnutls_x509_crq_get_dn_oid
1558 @anchor{gnutls_x509_crq_get_dn_oid}
1559 @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})
1560 @var{crq}: should contain a gnutls_x509_crq_t structure
1562 @var{indx}: Specifies which DN OID to get. Use (0) to get the first one.
1564 @var{oid}: a pointer to a structure to hold the name (may be @code{NULL} )
1566 @var{sizeof_oid}: initially holds the size of @code{oid}
1568 This function will extract the requested OID of the name of the
1569 certificate request subject, specified by the given index.
1571 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1572 not long enough, and in that case the * @code{sizeof_oid} will be
1573 updated with the required size. On success 0 is returned.
1576 @subheading gnutls_x509_crq_get_extension_by_oid
1577 @anchor{gnutls_x509_crq_get_extension_by_oid}
1578 @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})
1579 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1581 @var{oid}: holds an Object Identifier in a null terminated string
1583 @var{indx}: In case multiple same OIDs exist in the extensions, this
1584 specifies which to get. Use (0) to get the first one.
1586 @var{buf}: a pointer to a structure to hold the name (may be null)
1588 @var{buf_size}: initially holds the size of @code{buf}
1590 @var{critical}: will be non-zero if the extension is marked as critical
1592 This function will return the extension specified by the OID in
1593 the certificate. The extensions will be returned as binary data
1594 DER encoded, in the provided buffer.
1596 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1597 negative error code in case of an error. If the certificate does not
1598 contain the specified extension
1599 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1601 @strong{Since:} 2.8.0
1604 @subheading gnutls_x509_crq_get_extension_by_oid2
1605 @anchor{gnutls_x509_crq_get_extension_by_oid2}
1606 @deftypefun {int} {gnutls_x509_crq_get_extension_by_oid2} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, int @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical})
1607 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1609 @var{oid}: holds an Object Identifier in a null terminated string
1611 @var{indx}: In case multiple same OIDs exist in the extensions, this
1612 specifies which to get. Use (0) to get the first one.
1614 @var{output}: will hold the allocated extension data
1616 @var{critical}: will be non-zero if the extension is marked as critical
1618 This function will return the extension specified by the OID in
1619 the certificate. The extensions will be returned as binary data
1620 DER encoded, in the provided buffer.
1622 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1623 negative error code in case of an error. If the certificate does not
1624 contain the specified extension
1625 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1627 @strong{Since:} 3.3.8
1630 @subheading gnutls_x509_crq_get_extension_data
1631 @anchor{gnutls_x509_crq_get_extension_data}
1632 @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})
1633 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1635 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1637 @var{data}: a pointer to a structure to hold the data (may be null)
1639 @var{sizeof_data}: initially holds the size of @code{oid}
1641 This function will return the requested extension data in the
1642 certificate. The extension data will be stored as a string in the
1645 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and
1646 critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead,
1647 if you want to get data indexed by the extension OID rather than
1650 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1651 negative error code in case of an error. If your have reached the
1652 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1655 @strong{Since:} 2.8.0
1658 @subheading gnutls_x509_crq_get_extension_data2
1659 @anchor{gnutls_x509_crq_get_extension_data2}
1660 @deftypefun {int} {gnutls_x509_crq_get_extension_data2} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, gnutls_datum_t * @var{data})
1661 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1663 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
1665 @var{data}: will contain the extension DER-encoded data
1667 This function will return the requested extension data in the
1668 certificate request. The extension data will be allocated using
1669 @code{gnutls_malloc()} .
1671 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID.
1673 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
1674 otherwise a negative error code is returned. If you have reached the
1675 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1678 @strong{Since:} 3.3.0
1681 @subheading gnutls_x509_crq_get_extension_info
1682 @anchor{gnutls_x509_crq_get_extension_info}
1683 @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})
1684 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1686 @var{indx}: Specifies which extension number to get. Use (0) to get the first one.
1688 @var{oid}: a pointer to a structure to hold the OID
1690 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1691 holds actual size of @code{oid} .
1693 @var{critical}: output variable with critical flag, may be NULL.
1695 This function will return the requested extension OID in the
1696 certificate, and the critical flag for it. The extension OID will
1697 be stored as a string in the provided buffer. Use
1698 @code{gnutls_x509_crq_get_extension_data()} to extract the data.
1700 If the buffer provided is not long enough to hold the output, then
1701 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1704 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1705 negative error code in case of an error. If your have reached the
1706 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1709 @strong{Since:} 2.8.0
1712 @subheading gnutls_x509_crq_get_key_id
1713 @anchor{gnutls_x509_crq_get_key_id}
1714 @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})
1715 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1717 @var{flags}: should be 0 for now
1719 @var{output_data}: will contain the key ID
1721 @var{output_data_size}: holds the size of output_data (and will be
1722 replaced by the actual size of parameters)
1724 This function will return a unique ID that depends on the public key
1725 parameters. This ID can be used in checking whether a certificate
1726 corresponds to the given private key.
1728 If the buffer provided is not long enough to hold the output, then
1729 * @code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1730 be returned. The output will normally be a SHA-1 hash output,
1733 @strong{Returns:} In case of failure a negative error code will be
1734 returned, and 0 on success.
1736 @strong{Since:} 2.8.0
1739 @subheading gnutls_x509_crq_get_key_purpose_oid
1740 @anchor{gnutls_x509_crq_get_key_purpose_oid}
1741 @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})
1742 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1744 @var{indx}: This specifies which OID to return, use (0) to get the first one
1746 @var{oid}: a pointer to a buffer to hold the OID (may be @code{NULL} )
1748 @var{sizeof_oid}: initially holds the size of @code{oid}
1750 @var{critical}: output variable with critical flag, may be @code{NULL} .
1752 This function will extract the key purpose OIDs of the Certificate
1753 specified by the given index. These are stored in the Extended Key
1754 Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for
1755 human readable names.
1757 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1758 not long enough, and in that case the * @code{sizeof_oid} will be
1759 updated with the required size. On success 0 is returned.
1761 @strong{Since:} 2.8.0
1764 @subheading gnutls_x509_crq_get_key_rsa_raw
1765 @anchor{gnutls_x509_crq_get_key_rsa_raw}
1766 @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})
1767 @var{crq}: Holds the certificate
1769 @var{m}: will hold the modulus
1771 @var{e}: will hold the public exponent
1773 This function will export the RSA public key's parameters found in
1774 the given structure. The new parameters will be allocated using
1775 @code{gnutls_malloc()} and will be stored in the appropriate datum.
1777 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1778 negative error value.
1780 @strong{Since:} 2.8.0
1783 @subheading gnutls_x509_crq_get_key_usage
1784 @anchor{gnutls_x509_crq_get_key_usage}
1785 @deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
1786 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1788 @var{key_usage}: where the key usage bits will be stored
1790 @var{critical}: will be non-zero if the extension is marked as critical
1792 This function will return certificate's key usage, by reading the
1793 keyUsage X.509 extension (2.5.29.15). The key usage value will
1794 ORed values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
1795 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
1796 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
1797 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
1798 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
1800 @strong{Returns:} the certificate key usage, or a negative error code in case of
1801 parsing error. If the certificate does not contain the keyUsage
1802 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
1805 @strong{Since:} 2.8.0
1808 @subheading gnutls_x509_crq_get_pk_algorithm
1809 @anchor{gnutls_x509_crq_get_pk_algorithm}
1810 @deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits})
1811 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1813 @var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits
1815 This function will return the public key algorithm of a PKCS@code{10}
1816 certificate request.
1818 If bits is non-@code{NULL} , it should have enough size to hold the
1819 parameters size in bits. For RSA the bits returned is the modulus.
1820 For DSA the bits returned are of the public exponent.
1822 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1823 success, or a negative error code on error.
1826 @subheading gnutls_x509_crq_get_private_key_usage_period
1827 @anchor{gnutls_x509_crq_get_private_key_usage_period}
1828 @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})
1829 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1831 @var{activation}: The activation time
1833 @var{expiration}: The expiration time
1835 @var{critical}: the extension status
1837 This function will return the expiration and activation
1838 times of the private key of the certificate.
1840 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1841 if the extension is not present, otherwise a negative error value.
1844 @subheading gnutls_x509_crq_get_subject_alt_name
1845 @anchor{gnutls_x509_crq_get_subject_alt_name}
1846 @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})
1847 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1849 @var{seq}: specifies the sequence number of the alt name, 0 for the
1850 first one, 1 for the second etc.
1852 @var{ret}: is the place where the alternative name will be copied to
1854 @var{ret_size}: holds the size of ret.
1856 @var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type
1858 @var{critical}: will be non-zero if the extension is marked as critical
1861 This function will return the alternative names, contained in the
1862 given certificate. It is the same as
1863 @code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it
1864 will return the type of the alternative name in @code{ret_type} even if
1865 the function fails for some reason (i.e. the buffer provided is
1868 @strong{Returns:} the alternative subject name type on success, one of the
1869 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
1870 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
1871 hold the value. In that case @code{ret_size} will be updated with the
1872 required size. If the certificate request does not have an
1873 Alternative name with the specified sequence number then
1874 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1876 @strong{Since:} 2.8.0
1879 @subheading gnutls_x509_crq_get_subject_alt_othername_oid
1880 @anchor{gnutls_x509_crq_get_subject_alt_othername_oid}
1881 @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})
1882 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1884 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1886 @var{ret}: is the place where the otherName OID will be copied to
1888 @var{ret_size}: holds the size of ret.
1890 This function will extract the type OID of an otherName Subject
1891 Alternative Name, contained in the given certificate, and return
1892 the type as an enumerated element.
1894 This function is only useful if
1895 @code{gnutls_x509_crq_get_subject_alt_name()} returned
1896 @code{GNUTLS_SAN_OTHERNAME} .
1898 @strong{Returns:} the alternative subject name type on success, one of the
1899 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs,
1900 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
1901 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
1902 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
1903 @code{ret_size} is not large enough to hold the value. In that case
1904 @code{ret_size} will be updated with the required size. If the
1905 certificate does not have an Alternative name with the specified
1906 sequence number and with the otherName type then
1907 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1909 @strong{Since:} 2.8.0
1912 @subheading gnutls_x509_crq_get_version
1913 @anchor{gnutls_x509_crq_get_version}
1914 @deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq})
1915 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1917 This function will return the version of the specified Certificate
1920 @strong{Returns:} version of certificate request, or a negative error code on
1924 @subheading gnutls_x509_crq_import
1925 @anchor{gnutls_x509_crq_import}
1926 @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})
1927 @var{crq}: The structure to store the parsed certificate request.
1929 @var{data}: The DER or PEM encoded certificate.
1931 @var{format}: One of DER or PEM
1933 This function will convert the given DER or PEM encoded certificate
1934 request to a @code{gnutls_x509_crq_t} structure. The output will be
1935 stored in @code{crq} .
1937 If the Certificate is PEM encoded it should have a header of "NEW
1938 CERTIFICATE REQUEST".
1940 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1941 negative error value.
1944 @subheading gnutls_x509_crq_init
1945 @anchor{gnutls_x509_crq_init}
1946 @deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq})
1947 @var{crq}: The structure to be initialized
1949 This function will initialize a PKCS@code{10} certificate request
1952 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1953 negative error value.
1956 @subheading gnutls_x509_crq_print
1957 @anchor{gnutls_x509_crq_print}
1958 @deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1959 @var{crq}: The structure to be printed
1961 @var{format}: Indicate the format to use
1963 @var{out}: Newly allocated datum with null terminated string.
1965 This function will pretty print a certificate request, suitable for
1968 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
1970 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1971 negative error value.
1973 @strong{Since:} 2.8.0
1976 @subheading gnutls_x509_crq_set_attribute_by_oid
1977 @anchor{gnutls_x509_crq_set_attribute_by_oid}
1978 @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})
1979 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1981 @var{oid}: holds an Object Identifier in a null-terminated string
1983 @var{buf}: a pointer to a structure that holds the attribute data
1985 @var{buf_size}: holds the size of @code{buf}
1987 This function will set the attribute in the certificate request
1988 specified by the given Object ID. The provided attribute must be be DER
1991 Attributes in a certificate request is an optional set of data
1992 appended to the request. Their interpretation depends on the CA policy.
1994 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1995 negative error value.
1998 @subheading gnutls_x509_crq_set_basic_constraints
1999 @anchor{gnutls_x509_crq_set_basic_constraints}
2000 @deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint})
2001 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2003 @var{ca}: true(1) or false(0) depending on the Certificate authority status.
2005 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
2006 and negative error codes indicate that the pathLenConstraints field should
2009 This function will set the basicConstraints certificate extension.
2011 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2012 negative error value.
2014 @strong{Since:} 2.8.0
2017 @subheading gnutls_x509_crq_set_challenge_password
2018 @anchor{gnutls_x509_crq_set_challenge_password}
2019 @deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass})
2020 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2022 @var{pass}: holds a (0)-terminated password
2024 This function will set a challenge password to be used when
2025 revoking the request.
2027 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2028 negative error value.
2031 @subheading gnutls_x509_crq_set_dn
2032 @anchor{gnutls_x509_crq_set_dn}
2033 @deftypefun {int} {gnutls_x509_crq_set_dn} (gnutls_x509_crq_t @var{crq}, const char * @var{dn}, const char ** @var{err})
2034 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2036 @var{dn}: a comma separated DN string (RFC4514)
2038 @var{err}: indicates the error position (if any)
2040 This function will set the DN on the provided certificate.
2041 The input string should be plain ASCII or UTF-8 encoded.
2043 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2044 negative error value.
2047 @subheading gnutls_x509_crq_set_dn_by_oid
2048 @anchor{gnutls_x509_crq_set_dn_by_oid}
2049 @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})
2050 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2052 @var{oid}: holds an Object Identifier in a (0)-terminated string
2054 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
2056 @var{data}: a pointer to the input data
2058 @var{sizeof_data}: holds the size of @code{data}
2060 This function will set the part of the name of the Certificate
2061 request subject, specified by the given OID. The input string
2062 should be ASCII or UTF-8 encoded.
2064 Some helper macros with popular OIDs can be found in gnutls/x509.h
2065 With this function you can only set the known OIDs. You can test
2066 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
2067 not known (by gnutls) you should properly DER encode your data, and
2068 call this function with raw_flag set.
2070 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2071 negative error value.
2074 @subheading gnutls_x509_crq_set_key
2075 @anchor{gnutls_x509_crq_set_key}
2076 @deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
2077 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2079 @var{key}: holds a private key
2081 This function will set the public parameters from the given private
2084 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2085 negative error value.
2088 @subheading gnutls_x509_crq_set_key_purpose_oid
2089 @anchor{gnutls_x509_crq_set_key_purpose_oid}
2090 @deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical})
2091 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2093 @var{oid}: a pointer to a (0)-terminated string that holds the OID
2095 @var{critical}: Whether this extension will be critical or not
2097 This function will set the key purpose OIDs of the Certificate.
2098 These are stored in the Extended Key Usage extension (2.5.29.37)
2099 See the GNUTLS_KP_* definitions for human readable names.
2101 Subsequent calls to this function will append OIDs to the OID list.
2103 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2104 negative error value.
2106 @strong{Since:} 2.8.0
2109 @subheading gnutls_x509_crq_set_key_rsa_raw
2110 @anchor{gnutls_x509_crq_set_key_rsa_raw}
2111 @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})
2112 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2114 @var{m}: holds the modulus
2116 @var{e}: holds the public exponent
2118 This function will set the public parameters from the given private
2119 key to the request. Only RSA keys are currently supported.
2121 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2122 negative error value.
2124 @strong{Since:} 2.6.0
2127 @subheading gnutls_x509_crq_set_key_usage
2128 @anchor{gnutls_x509_crq_set_key_usage}
2129 @deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage})
2130 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2132 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
2134 This function will set the keyUsage certificate extension.
2136 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2137 negative error value.
2139 @strong{Since:} 2.8.0
2142 @subheading gnutls_x509_crq_set_private_key_usage_period
2143 @anchor{gnutls_x509_crq_set_private_key_usage_period}
2144 @deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration})
2145 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
2147 @var{activation}: The activation time
2149 @var{expiration}: The expiration time
2151 This function will set the private key usage period extension (2.5.29.16).
2153 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2154 negative error value.
2157 @subheading gnutls_x509_crq_set_subject_alt_name
2158 @anchor{gnutls_x509_crq_set_subject_alt_name}
2159 @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})
2160 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
2162 @var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations
2164 @var{data}: The data to be set
2166 @var{data_size}: The size of data to be set
2168 @var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or
2169 @code{GNUTLS_FSAN_APPEND} to append.
2171 This function will set the subject alternative name certificate
2172 extension. It can set the following types:
2174 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2175 negative error value.
2177 @strong{Since:} 2.8.0
2180 @subheading gnutls_x509_crq_set_version
2181 @anchor{gnutls_x509_crq_set_version}
2182 @deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version})
2183 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2185 @var{version}: holds the version number, for v1 Requests must be 1
2187 This function will set the version of the certificate request. For
2188 version 1 requests this must be one.
2190 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2191 negative error value.
2194 @subheading gnutls_x509_crq_sign2
2195 @anchor{gnutls_x509_crq_sign2}
2196 @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})
2197 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
2199 @var{key}: holds a private key
2201 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
2203 @var{flags}: must be 0
2205 This function will sign the certificate request with a private key.
2206 This must be the same key as the one used in
2207 @code{gnutls_x509_crt_set_key()} since a certificate request is self
2210 This must be the last step in a certificate request generation
2211 since all the previously set parameters are now signed.
2213 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2214 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
2215 information in the certificate request (e.g., the version using
2216 @code{gnutls_x509_crq_set_version()} ).
2219 @subheading gnutls_x509_crq_verify
2220 @anchor{gnutls_x509_crq_verify}
2221 @deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
2222 @var{crq}: is the crq to be verified
2224 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2226 This function will verify self signature in the certificate
2227 request and return its status.
2229 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
2230 is returned, and zero or positive code on success.
2235 @subheading gnutls_x509_crt_check_hostname
2236 @anchor{gnutls_x509_crt_check_hostname}
2237 @deftypefun {int} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname})
2238 @var{cert}: should contain an gnutls_x509_crt_t structure
2240 @var{hostname}: A null terminated string that contains a DNS name
2242 This function will check if the given certificate's subject matches
2243 the given hostname. This is a basic implementation of the matching
2244 described in RFC6125, and takes into account wildcards,
2245 and the DNSName/IPAddress subject alternative name PKIX extension.
2247 For details see also @code{gnutls_x509_crt_check_hostname2()} .
2249 @strong{Returns:} non-zero for a successful match, and zero on failure.
2252 @subheading gnutls_x509_crt_check_hostname2
2253 @anchor{gnutls_x509_crt_check_hostname2}
2254 @deftypefun {int} {gnutls_x509_crt_check_hostname2} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}, unsigned int @var{flags})
2255 @var{cert}: should contain an gnutls_x509_crt_t structure
2257 @var{hostname}: A null terminated string that contains a DNS name
2259 @var{flags}: gnutls_certificate_verify_flags
2261 This function will check if the given certificate's subject matches
2262 the given hostname. This is a basic implementation of the matching
2263 described in RFC6125, and takes into account wildcards,
2264 and the DNSName/IPAddress subject alternative name PKIX extension.
2266 IPv4 addresses are accepted by this function in the dotted-decimal
2267 format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the hexadecimal
2268 x:x:x:x:x:x:x:x format. For them the IPAddress subject alternative
2269 name extension is consulted, as well as the DNSNames in case of a non-match.
2270 The latter fallback exists due to misconfiguration of many servers
2271 which place an IPAddress inside the DNSName extension.
2273 The comparison of dns names may have false-negatives as it is done byte
2274 by byte in non-ascii names.
2276 When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS} is specified no
2277 wildcards are considered. Otherwise they are only considered if the
2278 domain name consists of three components or more, and the wildcard
2279 starts at the leftmost position.
2281 @strong{Returns:} non-zero for a successful match, and zero on failure.
2284 @subheading gnutls_x509_crt_check_issuer
2285 @anchor{gnutls_x509_crt_check_issuer}
2286 @deftypefun {int} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer})
2287 @var{cert}: is the certificate to be checked
2289 @var{issuer}: is the certificate of a possible issuer
2291 This function will check if the given certificate was issued by the
2292 given issuer. It checks the DN fields and the authority
2293 key identifier and subject key identifier fields match.
2295 If the same certificate is provided at the @code{cert} and @code{issuer} fields,
2296 it will check whether the certificate is self-signed.
2298 @strong{Returns:} It will return true (1) if the given certificate is issued
2299 by the given issuer, and false (0) if not.
2302 @subheading gnutls_x509_crt_check_revocation
2303 @anchor{gnutls_x509_crt_check_revocation}
2304 @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})
2305 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2307 @var{crl_list}: should contain a list of gnutls_x509_crl_t structures
2309 @var{crl_list_length}: the length of the crl_list
2311 This function will return check if the given certificate is
2312 revoked. It is assumed that the CRLs have been verified before.
2314 @strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A
2315 negative error code is returned on error.
2318 @subheading gnutls_x509_crt_cpy_crl_dist_points
2319 @anchor{gnutls_x509_crt_cpy_crl_dist_points}
2320 @deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src})
2321 @var{dst}: a certificate of type @code{gnutls_x509_crt_t}
2323 @var{src}: the certificate where the dist points will be copied from
2325 This function will copy the CRL distribution points certificate
2326 extension, from the source to the destination certificate.
2327 This may be useful to copy from a CA certificate to issued ones.
2329 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2330 negative error value.
2333 @subheading gnutls_x509_crt_deinit
2334 @anchor{gnutls_x509_crt_deinit}
2335 @deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert})
2336 @var{cert}: The structure to be deinitialized
2338 This function will deinitialize a certificate structure.
2341 @subheading gnutls_x509_crt_export
2342 @anchor{gnutls_x509_crt_export}
2343 @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})
2344 @var{cert}: Holds the certificate
2346 @var{format}: the format of output params. One of PEM or DER.
2348 @var{output_data}: will contain a certificate PEM or DER encoded
2350 @var{output_data_size}: holds the size of output_data (and will be
2351 replaced by the actual size of parameters)
2353 This function will export the certificate to DER or PEM format.
2355 If the buffer provided is not long enough to hold the output, then
2356 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2359 If the structure is PEM encoded, it will have a header
2360 of "BEGIN CERTIFICATE".
2362 @strong{Returns:} In case of failure a negative error code will be
2363 returned, and 0 on success.
2366 @subheading gnutls_x509_crt_export2
2367 @anchor{gnutls_x509_crt_export2}
2368 @deftypefun {int} {gnutls_x509_crt_export2} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
2369 @var{cert}: Holds the certificate
2371 @var{format}: the format of output params. One of PEM or DER.
2373 @var{out}: will contain a certificate PEM or DER encoded
2375 This function will export the certificate to DER or PEM format.
2376 The output buffer is allocated using @code{gnutls_malloc()} .
2378 If the structure is PEM encoded, it will have a header
2379 of "BEGIN CERTIFICATE".
2381 @strong{Returns:} In case of failure a negative error code will be
2382 returned, and 0 on success.
2384 @strong{Since:} 3.1.3
2387 @subheading gnutls_x509_crt_get_activation_time
2388 @anchor{gnutls_x509_crt_get_activation_time}
2389 @deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert})
2390 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2392 This function will return the time this Certificate was or will be
2395 @strong{Returns:} activation time, or (time_t)-1 on error.
2398 @subheading gnutls_x509_crt_get_authority_info_access
2399 @anchor{gnutls_x509_crt_get_authority_info_access}
2400 @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})
2401 @var{crt}: Holds the certificate
2403 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
2405 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
2407 @var{data}: output data to be freed with @code{gnutls_free()} .
2409 @var{critical}: pointer to output integer that is set to non-zero if the extension is marked as critical (may be @code{NULL} )
2411 Note that a simpler API to access the authority info data is provided
2412 by @code{gnutls_x509_aia_get()} and @code{gnutls_x509_ext_import_aia()} .
2414 This function extracts the Authority Information Access (AIA)
2415 extension, see RFC 5280 section 4.2.2.1 for more information. The
2416 AIA extension holds a sequence of AccessDescription (AD) data.
2418 The @code{seq} input parameter is used to indicate which member of the
2419 sequence the caller is interested in. The first member is 0, the
2420 second member 1 and so on. When the @code{seq} value is out of bounds,
2421 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2423 The type of data returned in @code{data} is specified via @code{what} which
2424 should be @code{gnutls_info_access_what_t} values.
2426 If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the
2427 accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
2429 If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will
2430 hold the accessLocation GeneralName type (e.g.,
2431 "uniformResourceIdentifier").
2433 If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI
2434 data. Requesting this @code{what} value leads to an error if the
2435 accessLocation is not of the "uniformResourceIdentifier" type.
2437 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
2438 Requesting this @code{what} value leads to an error if the accessMethod
2439 is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
2440 the "uniformResourceIdentifier" type. In that case @code{GNUTLS_E_UNKNOWN_ALGORITHM}
2441 will be returned, and @code{seq} should be increased and this function
2444 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
2445 URI. Requesting this @code{what} value leads to an error if the
2446 accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
2447 accessLocation is not of the "uniformResourceIdentifier" type.
2448 In that case handle as in @code{GNUTLS_IA_OCSP_URI} .
2450 More @code{what} values may be allocated in the future as needed.
2452 If @code{data} is NULL, the function does the same without storing the
2453 output data, that is, it will set @code{critical} and do error checking
2456 The value of the critical flag is returned in * @code{critical} . Supply a
2457 NULL @code{critical} if you want the function to make sure the extension
2458 is non-critical, as required by RFC 5280.
2460 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on
2461 invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is
2462 incorrectly marked as critical (use a non-NULL @code{critical} to
2463 override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does
2464 not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a
2465 negative error code.
2470 @subheading gnutls_x509_crt_get_authority_key_gn_serial
2471 @anchor{gnutls_x509_crt_get_authority_key_gn_serial}
2472 @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})
2473 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2475 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2477 @var{alt}: is the place where the alternative name will be copied to
2479 @var{alt_size}: holds the size of alt.
2481 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2483 @var{serial}: buffer to store the serial number (may be null)
2485 @var{serial_size}: Holds the size of the serial field (may be null)
2487 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2489 This function will return the X.509 authority key
2490 identifier when stored as a general name (authorityCertIssuer)
2493 Because more than one general names might be stored
2494 @code{seq} can be used as a counter to request them all until
2495 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2497 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2498 if the extension is not present, otherwise a negative error value.
2503 @subheading gnutls_x509_crt_get_authority_key_id
2504 @anchor{gnutls_x509_crt_get_authority_key_id}
2505 @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})
2506 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2508 @var{id}: The place where the identifier will be copied
2510 @var{id_size}: Holds the size of the id field.
2512 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2514 This function will return the X.509v3 certificate authority's key
2515 identifier. This is obtained by the X.509 Authority Key
2516 identifier extension field (2.5.29.35). Note that this function
2517 only returns the keyIdentifier field of the extension and
2518 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
2519 the name and serial number of the certificate. In that case
2520 @code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used.
2522 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2523 if the extension is not present, otherwise a negative error value.
2526 @subheading gnutls_x509_crt_get_basic_constraints
2527 @anchor{gnutls_x509_crt_get_basic_constraints}
2528 @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})
2529 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2531 @var{critical}: will be non-zero if the extension is marked as critical
2533 @var{ca}: pointer to output integer indicating CA status, may be NULL,
2534 value is 1 if the certificate CA flag is set, 0 otherwise.
2536 @var{pathlen}: pointer to output integer indicating path length (may be
2537 NULL), non-negative error codes indicate a present pathLenConstraint
2538 field and the actual value, -1 indicate that the field is absent.
2540 This function will read the certificate's basic constraints, and
2541 return the certificates CA status. It reads the basicConstraints
2542 X.509 extension (2.5.29.19).
2544 @strong{Returns:} If the certificate is a CA a positive value will be
2545 returned, or (0) if the certificate does not have CA flag set. A
2546 negative error code may be returned in case of errors. If the
2547 certificate does not contain the basicConstraints extension
2548 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2551 @subheading gnutls_x509_crt_get_ca_status
2552 @anchor{gnutls_x509_crt_get_ca_status}
2553 @deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical})
2554 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2556 @var{critical}: will be non-zero if the extension is marked as critical
2558 This function will return certificates CA status, by reading the
2559 basicConstraints X.509 extension (2.5.29.19). If the certificate is
2560 a CA a positive value will be returned, or (0) if the certificate
2561 does not have CA flag set.
2563 Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the
2564 pathLenConstraint field too.
2566 @strong{Returns:} If the certificate is a CA a positive value will be
2567 returned, or (0) if the certificate does not have CA flag set. A
2568 negative error code may be returned in case of errors. If the
2569 certificate does not contain the basicConstraints extension
2570 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2573 @subheading gnutls_x509_crt_get_crl_dist_points
2574 @anchor{gnutls_x509_crt_get_crl_dist_points}
2575 @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})
2576 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2578 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
2580 @var{san}: is the place where the distribution point will be copied to
2582 @var{san_size}: holds the size of ret.
2584 @var{reason_flags}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} .
2586 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2588 This function retrieves the CRL distribution points (2.5.29.31),
2589 contained in the given certificate in the X509v3 Certificate
2592 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if
2593 @code{ret_size} is not enough to hold the distribution point, or the
2594 type of the distribution point if everything was ok. The type is
2595 one of the enumerated @code{gnutls_x509_subject_alt_name_t} . If the
2596 certificate does not have an Alternative name with the specified
2597 sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is
2601 @subheading gnutls_x509_crt_get_dn
2602 @anchor{gnutls_x509_crt_get_dn}
2603 @deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2604 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2606 @var{buf}: a pointer to a structure to hold the name (may be null)
2608 @var{buf_size}: initially holds the size of @code{buf}
2610 This function will copy the name of the Certificate in the provided
2611 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2612 described in RFC4514. The output string will be ASCII or UTF-8
2613 encoded, depending on the certificate data.
2615 If @code{buf} is null then only the size will be filled.
2617 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2618 long enough, and in that case the @code{buf_size} will be updated
2619 with the required size. On success 0 is returned.
2622 @subheading gnutls_x509_crt_get_dn2
2623 @anchor{gnutls_x509_crt_get_dn2}
2624 @deftypefun {int} {gnutls_x509_crt_get_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
2625 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2627 @var{dn}: a pointer to a structure to hold the name
2629 This function will allocate buffer and copy the name of the Certificate.
2630 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2631 described in RFC4514. The output string will be ASCII or UTF-8
2632 encoded, depending on the certificate data.
2634 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2635 negative error value. and a negative error code on error.
2637 @strong{Since:} 3.1.10
2640 @subheading gnutls_x509_crt_get_dn_by_oid
2641 @anchor{gnutls_x509_crt_get_dn_by_oid}
2642 @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})
2643 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2645 @var{oid}: holds an Object Identified in null terminated string
2647 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2649 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
2651 @var{buf}: a pointer where the DN part will be copied (may be null).
2653 @var{buf_size}: initially holds the size of @code{buf}
2655 This function will extract the part of the name of the Certificate
2656 subject specified by the given OID. The output, if the raw flag is
2657 not used, will be encoded as described in RFC4514. Thus a string
2658 that is ASCII or UTF-8 encoded, depending on the certificate data.
2660 Some helper macros with popular OIDs can be found in gnutls/x509.h
2661 If raw flag is (0), this function will only return known OIDs as
2662 text. Other OIDs will be DER encoded, as described in RFC4514 --
2663 in hex format with a '#' prefix. You can check about known OIDs
2664 using @code{gnutls_x509_dn_oid_known()} .
2666 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
2667 @code{buf_size} will not include the null character.
2669 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2670 long enough, and in that case the @code{buf_size} will be updated with
2671 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2672 are no data in the current index. On success 0 is returned.
2675 @subheading gnutls_x509_crt_get_dn_oid
2676 @anchor{gnutls_x509_crt_get_dn_oid}
2677 @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})
2678 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2680 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2682 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2684 @var{oid_size}: initially holds the size of @code{oid}
2686 This function will extract the OIDs of the name of the Certificate
2687 subject specified by the given index.
2689 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
2690 account for the trailing null.
2692 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2693 long enough, and in that case the @code{buf_size} will be updated with
2694 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
2695 are no data in the current index. On success 0 is returned.
2698 @subheading gnutls_x509_crt_get_expiration_time
2699 @anchor{gnutls_x509_crt_get_expiration_time}
2700 @deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert})
2701 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2703 This function will return the time this Certificate was or will be
2706 The no well defined expiration time can be checked against with the
2707 @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION} macro.
2709 @strong{Returns:} expiration time, or (time_t)-1 on error.
2712 @subheading gnutls_x509_crt_get_extension_by_oid
2713 @anchor{gnutls_x509_crt_get_extension_by_oid}
2714 @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})
2715 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2717 @var{oid}: holds an Object Identified in null terminated string
2719 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2721 @var{buf}: a pointer to a structure to hold the name (may be null)
2723 @var{buf_size}: initially holds the size of @code{buf}
2725 @var{critical}: will be non-zero if the extension is marked as critical
2727 This function will return the extension specified by the OID in the
2728 certificate. The extensions will be returned as binary data DER
2729 encoded, in the provided buffer.
2731 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2732 otherwise a negative error code is returned. If the certificate does not
2733 contain the specified extension
2734 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2737 @subheading gnutls_x509_crt_get_extension_by_oid2
2738 @anchor{gnutls_x509_crt_get_extension_by_oid2}
2739 @deftypefun {int} {gnutls_x509_crt_get_extension_by_oid2} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, int @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical})
2740 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2742 @var{oid}: holds an Object Identified in null terminated string
2744 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2746 @var{output}: will hold the allocated extension data
2748 @var{critical}: will be non-zero if the extension is marked as critical
2750 This function will return the extension specified by the OID in the
2751 certificate. The extensions will be returned as binary data DER
2752 encoded, in the provided buffer.
2754 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2755 otherwise a negative error code is returned. If the certificate does not
2756 contain the specified extension
2757 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2759 @strong{Since:} 3.3.8
2762 @subheading gnutls_x509_crt_get_extension_data
2763 @anchor{gnutls_x509_crt_get_extension_data}
2764 @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})
2765 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2767 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2769 @var{data}: a pointer to a structure to hold the data (may be null)
2771 @var{sizeof_data}: initially holds the size of @code{data}
2773 This function will return the requested extension data in the
2774 certificate. The extension data will be stored in the
2777 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and
2778 critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead,
2779 if you want to get data indexed by the extension OID rather than
2782 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2783 otherwise a negative error code is returned. If you have reached the
2784 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2788 @subheading gnutls_x509_crt_get_extension_data2
2789 @anchor{gnutls_x509_crt_get_extension_data2}
2790 @deftypefun {int} {gnutls_x509_crt_get_extension_data2} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, gnutls_datum_t * @var{data})
2791 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2793 @var{indx}: Specifies which extension OID to read. Use (0) to get the first one.
2795 @var{data}: will contain the extension DER-encoded data
2797 This function will return the requested by the index extension data in the
2798 certificate. The extension data will be allocated using
2799 @code{gnutls_malloc()} .
2801 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID.
2803 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2804 otherwise a negative error code is returned. If you have reached the
2805 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2809 @subheading gnutls_x509_crt_get_extension_info
2810 @anchor{gnutls_x509_crt_get_extension_info}
2811 @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})
2812 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2814 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2816 @var{oid}: a pointer to a structure to hold the OID
2818 @var{oid_size}: initially holds the maximum size of @code{oid} , on return
2819 holds actual size of @code{oid} .
2821 @var{critical}: output variable with critical flag, may be NULL.
2823 This function will return the requested extension OID in the
2824 certificate, and the critical flag for it. The extension OID will
2825 be stored as a string in the provided buffer. Use
2826 @code{gnutls_x509_crt_get_extension()} to extract the data.
2828 If the buffer provided is not long enough to hold the output, then
2829 @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
2830 returned. The @code{oid} returned will be null terminated, although
2831 @code{oid_size} will not account for the trailing null.
2833 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2834 otherwise a negative error code is returned. If you have reached the
2835 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2839 @subheading gnutls_x509_crt_get_extension_oid
2840 @anchor{gnutls_x509_crt_get_extension_oid}
2841 @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})
2842 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2844 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2846 @var{oid}: a pointer to a structure to hold the OID (may be null)
2848 @var{oid_size}: initially holds the size of @code{oid}
2850 This function will return the requested extension OID in the certificate.
2851 The extension OID will be stored as a string in the provided buffer.
2853 The @code{oid} returned will be null terminated, although @code{oid_size} will not
2854 account for the trailing null.
2856 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2857 otherwise a negative error code is returned. If you have reached the
2858 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2862 @subheading gnutls_x509_crt_get_fingerprint
2863 @anchor{gnutls_x509_crt_get_fingerprint}
2864 @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})
2865 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2867 @var{algo}: is a digest algorithm
2869 @var{buf}: a pointer to a structure to hold the fingerprint (may be null)
2871 @var{buf_size}: initially holds the size of @code{buf}
2873 This function will calculate and copy the certificate's fingerprint
2874 in the provided buffer. The fingerprint is a hash of the DER-encoded
2875 data of the certificate.
2877 If the buffer is null then only the size will be filled.
2879 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2880 not long enough, and in that case the *buf_size will be updated
2881 with the required size. On success 0 is returned.
2884 @subheading gnutls_x509_crt_get_issuer
2885 @anchor{gnutls_x509_crt_get_issuer}
2886 @deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2887 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2889 @var{dn}: output variable with pointer to uint8_t DN
2891 Return the Certificate's Issuer DN as a @code{gnutls_x509_dn_t} data type,
2892 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
2894 Note that @code{dn} should be treated as constant. Because it points
2895 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
2898 @strong{Returns:} Returns 0 on success, or an error code.
2901 @subheading gnutls_x509_crt_get_issuer_alt_name
2902 @anchor{gnutls_x509_crt_get_issuer_alt_name}
2903 @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})
2904 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2906 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2908 @var{ian}: is the place where the alternative name will be copied to
2910 @var{ian_size}: holds the size of ian.
2912 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2914 This function retrieves the Issuer Alternative Name (2.5.29.18),
2915 contained in the given certificate in the X509v3 Certificate
2918 When the SAN type is otherName, it will extract the data in the
2919 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2920 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2921 the corresponding OID and the "virtual" SAN types (e.g.,
2922 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
2924 If an otherName OID is known, the data will be decoded. Otherwise
2925 the returned data will be DER encoded, and you will have to decode
2926 it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer
2927 AltName is recognized.
2929 @strong{Returns:} the alternative issuer name type on success, one of the
2930 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2931 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2932 to hold the value. In that case @code{ian_size} will be updated with
2933 the required size. If the certificate does not have an
2934 Alternative name with the specified sequence number then
2935 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2937 @strong{Since:} 2.10.0
2940 @subheading gnutls_x509_crt_get_issuer_alt_name2
2941 @anchor{gnutls_x509_crt_get_issuer_alt_name2}
2942 @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})
2943 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2945 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2947 @var{ian}: is the place where the alternative name will be copied to
2949 @var{ian_size}: holds the size of ret.
2951 @var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2953 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
2955 This function will return the alternative names, contained in the
2956 given certificate. It is the same as
2957 @code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it
2958 will return the type of the alternative name in @code{ian_type} even if
2959 the function fails for some reason (i.e. the buffer provided is
2962 @strong{Returns:} the alternative issuer name type on success, one of the
2963 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2964 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2965 to hold the value. In that case @code{ian_size} will be updated with
2966 the required size. If the certificate does not have an
2967 Alternative name with the specified sequence number then
2968 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2970 @strong{Since:} 2.10.0
2973 @subheading gnutls_x509_crt_get_issuer_alt_othername_oid
2974 @anchor{gnutls_x509_crt_get_issuer_alt_othername_oid}
2975 @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})
2976 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2978 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2980 @var{ret}: is the place where the otherName OID will be copied to
2982 @var{ret_size}: holds the size of ret.
2984 This function will extract the type OID of an otherName Subject
2985 Alternative Name, contained in the given certificate, and return
2986 the type as an enumerated element.
2988 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
2989 account for the trailing null.
2991 This function is only useful if
2992 @code{gnutls_x509_crt_get_issuer_alt_name()} returned
2993 @code{GNUTLS_SAN_OTHERNAME} .
2995 @strong{Returns:} the alternative issuer name type on success, one of the
2996 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2997 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2998 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
2999 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
3000 @code{ret_size} is not large enough to hold the value. In that case
3001 @code{ret_size} will be updated with the required size. If the
3002 certificate does not have an Alternative name with the specified
3003 sequence number and with the otherName type then
3004 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3006 @strong{Since:} 2.10.0
3009 @subheading gnutls_x509_crt_get_issuer_dn
3010 @anchor{gnutls_x509_crt_get_issuer_dn}
3011 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
3012 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3014 @var{buf}: a pointer to a structure to hold the name (may be null)
3016 @var{buf_size}: initially holds the size of @code{buf}
3018 This function will copy the name of the Certificate issuer in the
3019 provided buffer. The name will be in the form
3020 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
3021 will be ASCII or UTF-8 encoded, depending on the certificate data.
3023 If @code{buf} is null then only the size will be filled.
3025 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
3026 long enough, and in that case the @code{buf_size} will be updated with
3027 the required size. On success 0 is returned.
3030 @subheading gnutls_x509_crt_get_issuer_dn2
3031 @anchor{gnutls_x509_crt_get_issuer_dn2}
3032 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3033 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3035 @var{dn}: a pointer to a structure to hold the name
3037 This function will allocate buffer and copy the name of issuer of the Certificate.
3038 The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
3039 described in RFC4514. The output string will be ASCII or UTF-8
3040 encoded, depending on the certificate data.
3042 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3043 negative error value. and a negative error code on error.
3045 @strong{Since:} 3.1.10
3048 @subheading gnutls_x509_crt_get_issuer_dn_by_oid
3049 @anchor{gnutls_x509_crt_get_issuer_dn_by_oid}
3050 @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})
3051 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3053 @var{oid}: holds an Object Identified in null terminated string
3055 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
3057 @var{raw_flag}: If non-zero returns the raw DER data of the DN part.
3059 @var{buf}: a pointer to a structure to hold the name (may be null)
3061 @var{buf_size}: initially holds the size of @code{buf}
3063 This function will extract the part of the name of the Certificate
3064 issuer specified by the given OID. The output, if the raw flag is not
3065 used, will be encoded as described in RFC4514. Thus a string that is
3066 ASCII or UTF-8 encoded, depending on the certificate data.
3068 Some helper macros with popular OIDs can be found in gnutls/x509.h
3069 If raw flag is (0), this function will only return known OIDs as
3070 text. Other OIDs will be DER encoded, as described in RFC4514 --
3071 in hex format with a '#' prefix. You can check about known OIDs
3072 using @code{gnutls_x509_dn_oid_known()} .
3074 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
3075 @code{buf_size} will not include the null character.
3077 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
3078 long enough, and in that case the @code{buf_size} will be updated with
3079 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
3080 are no data in the current index. On success 0 is returned.
3083 @subheading gnutls_x509_crt_get_issuer_dn_oid
3084 @anchor{gnutls_x509_crt_get_issuer_dn_oid}
3085 @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})
3086 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3088 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
3090 @var{oid}: a pointer to a buffer to hold the OID (may be null)
3092 @var{oid_size}: initially holds the size of @code{oid}
3094 This function will extract the OIDs of the name of the Certificate
3095 issuer specified by the given index.
3097 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
3098 account for the trailing null.
3100 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
3101 long enough, and in that case the @code{buf_size} will be updated with
3102 the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there
3103 are no data in the current index. On success 0 is returned.
3106 @subheading gnutls_x509_crt_get_issuer_unique_id
3107 @anchor{gnutls_x509_crt_get_issuer_unique_id}
3108 @deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
3109 @var{crt}: Holds the certificate
3111 @var{buf}: user allocated memory buffer, will hold the unique id
3113 @var{buf_size}: size of user allocated memory buffer (on input), will hold
3114 actual size of the unique ID on return.
3116 This function will extract the issuerUniqueID value (if present) for
3117 the given certificate.
3119 If the user allocated memory buffer is not large enough to hold the
3120 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
3121 returned, and buf_size will be set to the actual length.
3123 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3125 @strong{Since:} 2.12.0
3128 @subheading gnutls_x509_crt_get_key_id
3129 @anchor{gnutls_x509_crt_get_key_id}
3130 @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})
3131 @var{crt}: Holds the certificate
3133 @var{flags}: should be 0 for now
3135 @var{output_data}: will contain the key ID
3137 @var{output_data_size}: holds the size of output_data (and will be
3138 replaced by the actual size of parameters)
3140 This function will return a unique ID that depends on the public
3141 key parameters. This ID can be used in checking whether a
3142 certificate corresponds to the given private key.
3144 If the buffer provided is not long enough to hold the output, then
3145 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3146 be returned. The output will normally be a SHA-1 hash output,
3149 @strong{Returns:} In case of failure a negative error code will be
3150 returned, and 0 on success.
3153 @subheading gnutls_x509_crt_get_key_purpose_oid
3154 @anchor{gnutls_x509_crt_get_key_purpose_oid}
3155 @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})
3156 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3158 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
3160 @var{oid}: a pointer to a buffer to hold the OID (may be null)
3162 @var{oid_size}: initially holds the size of @code{oid}
3164 @var{critical}: output flag to indicate criticality of extension
3166 This function will extract the key purpose OIDs of the Certificate
3167 specified by the given index. These are stored in the Extended Key
3168 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
3169 human readable names.
3171 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
3172 account for the trailing null.
3174 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
3175 not long enough, and in that case the *oid_size will be updated
3176 with the required size. On success 0 is returned.
3179 @subheading gnutls_x509_crt_get_key_usage
3180 @anchor{gnutls_x509_crt_get_key_usage}
3181 @deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
3182 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3184 @var{key_usage}: where the key usage bits will be stored
3186 @var{critical}: will be non-zero if the extension is marked as critical
3188 This function will return certificate's key usage, by reading the
3189 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
3190 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
3191 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
3192 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
3193 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
3194 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
3196 @strong{Returns:} the certificate key usage, or a negative error code in case of
3197 parsing error. If the certificate does not contain the keyUsage
3198 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
3202 @subheading gnutls_x509_crt_get_name_constraints
3203 @anchor{gnutls_x509_crt_get_name_constraints}
3204 @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})
3205 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
3207 @var{nc}: The nameconstraints intermediate structure
3209 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
3211 @var{critical}: the extension status
3213 This function will return an intermediate structure containing
3214 the name constraints of the provided CA certificate. That
3215 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
3216 to verify whether a server's name is in accordance with the constraints.
3218 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
3219 the @code{nc} structure is empty
3220 this function will behave identically as if the flag was not set.
3221 Otherwise if there are elements in the @code{nc} structure then only the
3222 excluded constraints will be appended to the constraints.
3224 Note that @code{nc} must be initialized prior to calling this function.
3226 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3227 if the extension is not present, otherwise a negative error value.
3229 @strong{Since:} 3.3.0
3232 @subheading gnutls_x509_crt_get_pk_algorithm
3233 @anchor{gnutls_x509_crt_get_pk_algorithm}
3234 @deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits})
3235 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3237 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
3239 This function will return the public key algorithm of an X.509
3242 If bits is non null, it should have enough size to hold the parameters
3243 size in bits. For RSA the bits returned is the modulus.
3244 For DSA the bits returned are of the public
3247 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3248 success, or a negative error code on error.
3251 @subheading gnutls_x509_crt_get_pk_dsa_raw
3252 @anchor{gnutls_x509_crt_get_pk_dsa_raw}
3253 @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})
3254 @var{crt}: Holds the certificate
3256 @var{p}: will hold the p
3258 @var{q}: will hold the q
3260 @var{g}: will hold the g
3262 @var{y}: will hold the y
3264 This function will export the DSA public key's parameters found in
3265 the given certificate. The new parameters will be allocated using
3266 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3268 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3271 @subheading gnutls_x509_crt_get_pk_rsa_raw
3272 @anchor{gnutls_x509_crt_get_pk_rsa_raw}
3273 @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})
3274 @var{crt}: Holds the certificate
3276 @var{m}: will hold the modulus
3278 @var{e}: will hold the public exponent
3280 This function will export the RSA public key's parameters found in
3281 the given structure. The new parameters will be allocated using
3282 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3284 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3287 @subheading gnutls_x509_crt_get_policy
3288 @anchor{gnutls_x509_crt_get_policy}
3289 @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})
3290 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
3292 @var{indx}: This specifies which policy to return. Use (0) to get the first one.
3294 @var{policy}: A pointer to a policy structure.
3296 @var{critical}: will be non-zero if the extension is marked as critical
3298 This function will extract the certificate policy (extension 2.5.29.32)
3299 specified by the given index.
3301 The policy returned by this function must be deinitialized by using
3302 @code{gnutls_x509_policy_release()} .
3304 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3305 if the extension is not present, otherwise a negative error value.
3307 @strong{Since:} 3.1.5
3310 @subheading gnutls_x509_crt_get_private_key_usage_period
3311 @anchor{gnutls_x509_crt_get_private_key_usage_period}
3312 @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})
3313 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3315 @var{activation}: The activation time
3317 @var{expiration}: The expiration time
3319 @var{critical}: the extension status
3321 This function will return the expiration and activation
3322 times of the private key of the certificate. It relies on
3323 the PKIX extension 2.5.29.16 being present.
3325 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3326 if the extension is not present, otherwise a negative error value.
3329 @subheading gnutls_x509_crt_get_proxy
3330 @anchor{gnutls_x509_crt_get_proxy}
3331 @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})
3332 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3334 @var{critical}: will be non-zero if the extension is marked as critical
3336 @var{pathlen}: pointer to output integer indicating path length (may be
3337 NULL), non-negative error codes indicate a present pCPathLenConstraint
3338 field and the actual value, -1 indicate that the field is absent.
3340 @var{policyLanguage}: output variable with OID of policy language
3342 @var{policy}: output variable with policy data
3344 @var{sizeof_policy}: output variable size of policy data
3346 This function will get information from a proxy certificate. It
3347 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
3349 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
3350 otherwise a negative error code is returned.
3353 @subheading gnutls_x509_crt_get_raw_dn
3354 @anchor{gnutls_x509_crt_get_raw_dn}
3355 @deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3356 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3358 @var{dn}: will hold the starting point of the DN
3360 This function will return a pointer to the DER encoded DN structure and
3361 the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3363 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3364 negative error value. or a negative error code on error.
3367 @subheading gnutls_x509_crt_get_raw_issuer_dn
3368 @anchor{gnutls_x509_crt_get_raw_issuer_dn}
3369 @deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn})
3370 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3372 @var{dn}: will hold the starting point of the DN
3374 This function will return a pointer to the DER encoded DN structure
3375 and the length. This points to allocated data that must be free'd using @code{gnutls_free()} .
3377 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3378 negative error value.or a negative error code on error.
3381 @subheading gnutls_x509_crt_get_serial
3382 @anchor{gnutls_x509_crt_get_serial}
3383 @deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size})
3384 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3386 @var{result}: The place where the serial number will be copied
3388 @var{result_size}: Holds the size of the result field.
3390 This function will return the X.509 certificate's serial number.
3391 This is obtained by the X509 Certificate serialNumber field. Serial
3392 is not always a 32 or 64bit number. Some CAs use large serial
3393 numbers, thus it may be wise to handle it as something uint8_t.
3395 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3396 negative error value.
3399 @subheading gnutls_x509_crt_get_signature
3400 @anchor{gnutls_x509_crt_get_signature}
3401 @deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sig_size})
3402 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3404 @var{sig}: a pointer where the signature part will be copied (may be null).
3406 @var{sig_size}: initially holds the size of @code{sig}
3408 This function will extract the signature field of a certificate.
3410 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3411 negative error value. and a negative error code on error.
3414 @subheading gnutls_x509_crt_get_signature_algorithm
3415 @anchor{gnutls_x509_crt_get_signature_algorithm}
3416 @deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert})
3417 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3419 This function will return a value of the @code{gnutls_sign_algorithm_t}
3420 enumeration that is the signature algorithm that has been used to
3421 sign this certificate.
3423 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code on
3427 @subheading gnutls_x509_crt_get_subject
3428 @anchor{gnutls_x509_crt_get_subject}
3429 @deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
3430 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3432 @var{dn}: output variable with pointer to uint8_t DN.
3434 Return the Certificate's Subject DN as a @code{gnutls_x509_dn_t} data type,
3435 that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} .
3437 Note that @code{dn} should be treated as constant. Because it points
3438 into the @code{cert} object, you should not use @code{dn} after @code{cert} is
3441 @strong{Returns:} Returns 0 on success, or an error code.
3444 @subheading gnutls_x509_crt_get_subject_alt_name
3445 @anchor{gnutls_x509_crt_get_subject_alt_name}
3446 @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})
3447 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3449 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3451 @var{san}: is the place where the alternative name will be copied to
3453 @var{san_size}: holds the size of san.
3455 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3457 This function retrieves the Alternative Name (2.5.29.17), contained
3458 in the given certificate in the X509v3 Certificate Extensions.
3460 When the SAN type is otherName, it will extract the data in the
3461 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
3462 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
3463 the corresponding OID and the "virtual" SAN types (e.g.,
3464 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
3466 If an otherName OID is known, the data will be decoded. Otherwise
3467 the returned data will be DER encoded, and you will have to decode
3468 it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is
3471 @strong{Returns:} the alternative subject name type on success, one of the
3472 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3473 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to
3474 hold the value. In that case @code{san_size} will be updated with the
3475 required size. If the certificate does not have an Alternative
3476 name with the specified sequence number then
3477 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3480 @subheading gnutls_x509_crt_get_subject_alt_name2
3481 @anchor{gnutls_x509_crt_get_subject_alt_name2}
3482 @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})
3483 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3485 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3487 @var{san}: is the place where the alternative name will be copied to
3489 @var{san_size}: holds the size of ret.
3491 @var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
3493 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3495 This function will return the alternative names, contained in the
3496 given certificate. It is the same as
3497 @code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it
3498 will return the type of the alternative name in @code{san_type} even if
3499 the function fails for some reason (i.e. the buffer provided is
3502 @strong{Returns:} the alternative subject name type on success, one of the
3503 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
3504 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough
3505 to hold the value. In that case @code{san_size} will be updated with
3506 the required size. If the certificate does not have an
3507 Alternative name with the specified sequence number then
3508 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3511 @subheading gnutls_x509_crt_get_subject_alt_othername_oid
3512 @anchor{gnutls_x509_crt_get_subject_alt_othername_oid}
3513 @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})
3514 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3516 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
3518 @var{oid}: is the place where the otherName OID will be copied to
3520 @var{oid_size}: holds the size of ret.
3522 This function will extract the type OID of an otherName Subject
3523 Alternative Name, contained in the given certificate, and return
3524 the type as an enumerated element.
3526 This function is only useful if
3527 @code{gnutls_x509_crt_get_subject_alt_name()} returned
3528 @code{GNUTLS_SAN_OTHERNAME} .
3530 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
3531 account for the trailing null.
3533 @strong{Returns:} the alternative subject name type on success, one of the
3534 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
3535 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
3536 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
3537 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
3538 @code{ian_size} is not large enough to hold the value. In that case
3539 @code{ian_size} will be updated with the required size. If the
3540 certificate does not have an Alternative name with the specified
3541 sequence number and with the otherName type then
3542 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
3545 @subheading gnutls_x509_crt_get_subject_key_id
3546 @anchor{gnutls_x509_crt_get_subject_key_id}
3547 @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})
3548 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3550 @var{ret}: The place where the identifier will be copied
3552 @var{ret_size}: Holds the size of the result field.
3554 @var{critical}: will be non-zero if the extension is marked as critical (may be null)
3556 This function will return the X.509v3 certificate's subject key
3557 identifier. This is obtained by the X.509 Subject Key identifier
3558 extension field (2.5.29.14).
3560 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3561 if the extension is not present, otherwise a negative error value.
3564 @subheading gnutls_x509_crt_get_subject_unique_id
3565 @anchor{gnutls_x509_crt_get_subject_unique_id}
3566 @deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
3567 @var{crt}: Holds the certificate
3569 @var{buf}: user allocated memory buffer, will hold the unique id
3571 @var{buf_size}: size of user allocated memory buffer (on input), will hold
3572 actual size of the unique ID on return.
3574 This function will extract the subjectUniqueID value (if present) for
3575 the given certificate.
3577 If the user allocated memory buffer is not large enough to hold the
3578 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
3579 returned, and buf_size will be set to the actual length.
3581 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
3584 @subheading gnutls_x509_crt_get_version
3585 @anchor{gnutls_x509_crt_get_version}
3586 @deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert})
3587 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3589 This function will return the version of the specified Certificate.
3591 @strong{Returns:} version of certificate, or a negative error code on error.
3594 @subheading gnutls_x509_crt_import
3595 @anchor{gnutls_x509_crt_import}
3596 @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})
3597 @var{cert}: The structure to store the parsed certificate.
3599 @var{data}: The DER or PEM encoded certificate.
3601 @var{format}: One of DER or PEM
3603 This function will convert the given DER or PEM encoded Certificate
3604 to the native gnutls_x509_crt_t format. The output will be stored
3607 If the Certificate is PEM encoded it should have a header of "X509
3608 CERTIFICATE", or "CERTIFICATE".
3610 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3611 negative error value.
3614 @subheading gnutls_x509_crt_init
3615 @anchor{gnutls_x509_crt_init}
3616 @deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert})
3617 @var{cert}: The structure to be initialized
3619 This function will initialize an X.509 certificate structure.
3621 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3622 negative error value.
3625 @subheading gnutls_x509_crt_list_import
3626 @anchor{gnutls_x509_crt_list_import}
3627 @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})
3628 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
3630 @var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
3632 @var{data}: The PEM encoded certificate.
3634 @var{format}: One of DER or PEM.
3636 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3638 This function will convert the given PEM encoded certificate list
3639 to the native gnutls_x509_crt_t format. The output will be stored
3640 in @code{certs} . They will be automatically initialized.
3642 The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause
3643 import to fail if the certificates in the provided buffer are more
3644 than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED}
3645 flag will cause the function to fail if the provided list is not
3646 sorted from subject to issuer.
3648 If the Certificate is PEM encoded it should have a header of "X509
3649 CERTIFICATE", or "CERTIFICATE".
3651 @strong{Returns:} the number of certificates read or a negative error value.
3654 @subheading gnutls_x509_crt_list_import2
3655 @anchor{gnutls_x509_crt_list_import2}
3656 @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})
3657 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
3659 @var{size}: It will contain the size of the list.
3661 @var{data}: The PEM encoded certificate.
3663 @var{format}: One of DER or PEM.
3665 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
3667 This function will convert the given PEM encoded certificate list
3668 to the native gnutls_x509_crt_t format. The output will be stored
3669 in @code{certs} which will allocated and initialized.
3671 If the Certificate is PEM encoded it should have a header of "X509
3672 CERTIFICATE", or "CERTIFICATE".
3674 To deinitialize @code{certs} , you need to deinitialize each crt structure
3675 independently, and use @code{gnutls_free()} at
3677 @strong{Returns:} the number of certificates read or a negative error value.
3682 @subheading gnutls_x509_crt_list_verify
3683 @anchor{gnutls_x509_crt_list_verify}
3684 @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})
3685 @var{cert_list}: is the certificate list to be verified
3687 @var{cert_list_length}: holds the number of certificate in cert_list
3689 @var{CA_list}: is the CA list which will be used in verification
3691 @var{CA_list_length}: holds the number of CA certificate in CA_list
3693 @var{CRL_list}: holds a list of CRLs.
3695 @var{CRL_list_length}: the length of CRL list.
3697 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3699 @var{verify}: will hold the certificate verification output.
3701 This function will try to verify the given certificate list and
3702 return its status. If no flags are specified (0), this function
3703 will use the basicConstraints (2.5.29.19) PKIX extension. This
3704 means that only a certificate authority is allowed to sign a
3707 You must also check the peer's name in order to check if the verified
3708 certificate belongs to the actual peer.
3710 The certificate verification output will be put in @code{verify} and will
3711 be one or more of the gnutls_certificate_status_t enumerated
3712 elements bitwise or'd. For a more detailed verification status use
3713 @code{gnutls_x509_crt_verify()} per list element.
3715 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3716 negative error value.
3719 @subheading gnutls_x509_crt_print
3720 @anchor{gnutls_x509_crt_print}
3721 @deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
3722 @var{cert}: The structure to be printed
3724 @var{format}: Indicate the format to use
3726 @var{out}: Newly allocated datum with null terminated string.
3728 This function will pretty print a X.509 certificate, suitable for
3731 If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the
3732 certificate will be output, on multiple lines. The
3733 @code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some
3734 selected fields, which is useful for logging purposes.
3736 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
3738 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3739 negative error value.
3742 @subheading gnutls_x509_crt_set_activation_time
3743 @anchor{gnutls_x509_crt_set_activation_time}
3744 @deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time})
3745 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3747 @var{act_time}: The actual time
3749 This function will set the time this Certificate was or will be
3752 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3753 negative error value.
3756 @subheading gnutls_x509_crt_set_authority_info_access
3757 @anchor{gnutls_x509_crt_set_authority_info_access}
3758 @deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data})
3759 @var{crt}: Holds the certificate
3761 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
3763 @var{data}: output data to be freed with @code{gnutls_free()} .
3765 This function sets the Authority Information Access (AIA)
3766 extension, see RFC 5280 section 4.2.2.1 for more information.
3768 The type of data stored in @code{data} is specified via @code{what} which
3769 should be @code{gnutls_info_access_what_t} values.
3771 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
3772 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
3775 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3776 negative error value.
3781 @subheading gnutls_x509_crt_set_authority_key_id
3782 @anchor{gnutls_x509_crt_set_authority_key_id}
3783 @deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3784 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3786 @var{id}: The key ID
3788 @var{id_size}: Holds the size of the key ID field.
3790 This function will set the X.509 certificate's authority key ID extension.
3791 Only the keyIdentifier field can be set with this function.
3793 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3794 negative error value.
3797 @subheading gnutls_x509_crt_set_basic_constraints
3798 @anchor{gnutls_x509_crt_set_basic_constraints}
3799 @deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint})
3800 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3802 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3804 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
3805 and negative error codes indicate that the pathLenConstraints field should
3808 This function will set the basicConstraints certificate extension.
3810 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3811 negative error value.
3814 @subheading gnutls_x509_crt_set_ca_status
3815 @anchor{gnutls_x509_crt_set_ca_status}
3816 @deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca})
3817 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3819 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3821 This function will set the basicConstraints certificate extension.
3822 Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control
3823 the pathLenConstraint field too.
3825 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3826 negative error value.
3829 @subheading gnutls_x509_crt_set_crl_dist_points
3830 @anchor{gnutls_x509_crt_set_crl_dist_points}
3831 @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})
3832 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3834 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3836 @var{data_string}: The data to be set
3838 @var{reason_flags}: revocation reasons
3840 This function will set the CRL distribution points certificate extension.
3842 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3843 negative error value.
3846 @subheading gnutls_x509_crt_set_crl_dist_points2
3847 @anchor{gnutls_x509_crt_set_crl_dist_points2}
3848 @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})
3849 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3851 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3853 @var{data}: The data to be set
3855 @var{data_size}: The data size
3857 @var{reason_flags}: revocation reasons
3859 This function will set the CRL distribution points certificate extension.
3861 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3862 negative error value.
3864 @strong{Since:} 2.6.0
3867 @subheading gnutls_x509_crt_set_crq
3868 @anchor{gnutls_x509_crt_set_crq}
3869 @deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3870 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3872 @var{crq}: holds a certificate request
3874 This function will set the name and public parameters as well as
3875 the extensions from the given certificate request to the certificate.
3876 Only RSA keys are currently supported.
3878 Note that this function will only set the @code{crq} if it is self
3879 signed and the signature is correct. See @code{gnutls_x509_crq_sign2()} .
3881 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3882 negative error value.
3885 @subheading gnutls_x509_crt_set_crq_extensions
3886 @anchor{gnutls_x509_crt_set_crq_extensions}
3887 @deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3888 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3890 @var{crq}: holds a certificate request
3892 This function will set extensions from the given request to the
3895 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3896 negative error value.
3898 @strong{Since:} 2.8.0
3901 @subheading gnutls_x509_crt_set_dn
3902 @anchor{gnutls_x509_crt_set_dn}
3903 @deftypefun {int} {gnutls_x509_crt_set_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
3904 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3906 @var{dn}: a comma separated DN string (RFC4514)
3908 @var{err}: indicates the error position (if any)
3910 This function will set the DN on the provided certificate.
3911 The input string should be plain ASCII or UTF-8 encoded.
3913 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3914 negative error value.
3917 @subheading gnutls_x509_crt_set_dn_by_oid
3918 @anchor{gnutls_x509_crt_set_dn_by_oid}
3919 @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})
3920 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3922 @var{oid}: holds an Object Identifier in a null terminated string
3924 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3926 @var{name}: a pointer to the name
3928 @var{sizeof_name}: holds the size of @code{name}
3930 This function will set the part of the name of the Certificate
3931 subject, specified by the given OID. The input string should be
3932 ASCII or UTF-8 encoded.
3934 Some helper macros with popular OIDs can be found in gnutls/x509.h
3935 With this function you can only set the known OIDs. You can test
3936 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3937 not known (by gnutls) you should properly DER encode your data,
3938 and call this function with @code{raw_flag} set.
3940 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3941 negative error value.
3944 @subheading gnutls_x509_crt_set_expiration_time
3945 @anchor{gnutls_x509_crt_set_expiration_time}
3946 @deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time})
3947 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3949 @var{exp_time}: The actual time
3951 This function will set the time this Certificate will expire.
3952 Setting an expiration time to (time_t)-1 or to @code{GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION}
3953 will set to the no well-defined expiration date value.
3955 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3956 negative error value.
3959 @subheading gnutls_x509_crt_set_extension_by_oid
3960 @anchor{gnutls_x509_crt_set_extension_by_oid}
3961 @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})
3962 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3964 @var{oid}: holds an Object Identified in null terminated string
3966 @var{buf}: a pointer to a DER encoded data
3968 @var{sizeof_buf}: holds the size of @code{buf}
3970 @var{critical}: should be non-zero if the extension is to be marked as critical
3972 This function will set an the extension, by the specified OID, in
3973 the certificate. The extension data should be binary data DER
3976 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3977 negative error value.
3980 @subheading gnutls_x509_crt_set_issuer_alt_name
3981 @anchor{gnutls_x509_crt_set_issuer_alt_name}
3982 @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})
3983 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3985 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3987 @var{data}: The data to be set
3989 @var{data_size}: The size of data to be set
3991 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
3993 This function will set the issuer alternative name certificate
3994 extension. It can set the same types as @code{gnutls_x509_crt_set_subject_alt_name()} .
3996 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3997 negative error value.
3999 @strong{Since:} 3.3.0
4002 @subheading gnutls_x509_crt_set_issuer_dn
4003 @anchor{gnutls_x509_crt_set_issuer_dn}
4004 @deftypefun {int} {gnutls_x509_crt_set_issuer_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err})
4005 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4007 @var{dn}: a comma separated DN string (RFC4514)
4009 @var{err}: indicates the error position (if any)
4011 This function will set the DN on the provided certificate.
4012 The input string should be plain ASCII or UTF-8 encoded.
4014 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4015 negative error value.
4018 @subheading gnutls_x509_crt_set_issuer_dn_by_oid
4019 @anchor{gnutls_x509_crt_set_issuer_dn_by_oid}
4020 @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})
4021 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4023 @var{oid}: holds an Object Identifier in a null terminated string
4025 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
4027 @var{name}: a pointer to the name
4029 @var{sizeof_name}: holds the size of @code{name}
4031 This function will set the part of the name of the Certificate
4032 issuer, specified by the given OID. The input string should be
4033 ASCII or UTF-8 encoded.
4035 Some helper macros with popular OIDs can be found in gnutls/x509.h
4036 With this function you can only set the known OIDs. You can test
4037 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
4038 not known (by gnutls) you should properly DER encode your data,
4039 and call this function with @code{raw_flag} set.
4041 Normally you do not need to call this function, since the signing
4042 operation will copy the signer's name as the issuer of the
4045 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4046 negative error value.
4049 @subheading gnutls_x509_crt_set_issuer_unique_id
4050 @anchor{gnutls_x509_crt_set_issuer_unique_id}
4051 @deftypefun {int} {gnutls_x509_crt_set_issuer_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4052 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4054 @var{id}: The unique ID
4056 @var{id_size}: Holds the size of the unique ID.
4058 This function will set the X.509 certificate's issuer unique ID field.
4060 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4061 negative error value.
4064 @subheading gnutls_x509_crt_set_key
4065 @anchor{gnutls_x509_crt_set_key}
4066 @deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key})
4067 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4069 @var{key}: holds a private key
4071 This function will set the public parameters from the given
4072 private key to the certificate. Only RSA keys are currently
4075 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4076 negative error value.
4079 @subheading gnutls_x509_crt_set_key_purpose_oid
4080 @anchor{gnutls_x509_crt_set_key_purpose_oid}
4081 @deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical})
4082 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4084 @var{oid}: a pointer to a null terminated string that holds the OID
4086 @var{critical}: Whether this extension will be critical or not
4088 This function will set the key purpose OIDs of the Certificate.
4089 These are stored in the Extended Key Usage extension (2.5.29.37)
4090 See the GNUTLS_KP_* definitions for human readable names.
4092 Subsequent calls to this function will append OIDs to the OID list.
4094 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
4095 otherwise a negative error code is returned.
4098 @subheading gnutls_x509_crt_set_key_usage
4099 @anchor{gnutls_x509_crt_set_key_usage}
4100 @deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage})
4101 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4103 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4105 This function will set the keyUsage certificate extension.
4107 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4108 negative error value.
4111 @subheading gnutls_x509_crt_set_name_constraints
4112 @anchor{gnutls_x509_crt_set_name_constraints}
4113 @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})
4114 @var{crt}: The certificate structure
4116 @var{nc}: The nameconstraints structure
4118 @var{critical}: whether this extension will be critical
4120 This function will set the provided name constraints to
4121 the certificate extension list. This extension is always
4124 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4126 @strong{Since:} 3.3.0
4129 @subheading gnutls_x509_crt_set_pin_function
4130 @anchor{gnutls_x509_crt_set_pin_function}
4131 @deftypefun {void} {gnutls_x509_crt_set_pin_function} (gnutls_x509_crt_t @var{crt}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
4132 @var{crt}: The certificate structure
4134 @var{fn}: the callback
4136 @var{userdata}: data associated with the callback
4138 This function will set a callback function to be used when
4139 it is required to access a protected object. This function overrides
4140 the global function set using @code{gnutls_pkcs11_set_pin_function()} .
4142 Note that this callback is currently used only during the import
4143 of a PKCS @code{11} certificate with @code{gnutls_x509_crt_import_pkcs11_url()} .
4145 @strong{Since:} 3.1.0
4148 @subheading gnutls_x509_crt_set_policy
4149 @anchor{gnutls_x509_crt_set_policy}
4150 @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})
4151 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
4153 @var{policy}: A pointer to a policy structure.
4155 @var{critical}: use non-zero if the extension is marked as critical
4157 This function will set the certificate policy extension (2.5.29.32).
4158 Multiple calls to this function append a new policy.
4160 Note the maximum text size for the qualifier @code{GNUTLS_X509_QUALIFIER_NOTICE}
4161 is 200 characters. This function will fail with @code{GNUTLS_E_INVALID_REQUEST}
4162 if this is exceeded.
4164 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4165 negative error value.
4167 @strong{Since:} 3.1.5
4170 @subheading gnutls_x509_crt_set_private_key_usage_period
4171 @anchor{gnutls_x509_crt_set_private_key_usage_period}
4172 @deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration})
4173 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4175 @var{activation}: The activation time
4177 @var{expiration}: The expiration time
4179 This function will set the private key usage period extension (2.5.29.16).
4181 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4182 negative error value.
4185 @subheading gnutls_x509_crt_set_proxy
4186 @anchor{gnutls_x509_crt_set_proxy}
4187 @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})
4188 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4190 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4191 and negative error codes indicate that the pathLenConstraints field should
4194 @var{policyLanguage}: OID describing the language of @code{policy} .
4196 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4198 @var{sizeof_policy}: size of @code{policy} .
4200 This function will set the proxyCertInfo extension.
4202 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4203 negative error value.
4206 @subheading gnutls_x509_crt_set_proxy_dn
4207 @anchor{gnutls_x509_crt_set_proxy_dn}
4208 @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})
4209 @var{crt}: a gnutls_x509_crt_t structure with the new proxy cert
4211 @var{eecrt}: the end entity certificate that will be issuing the proxy
4213 @var{raw_flag}: must be 0, or 1 if the CN is DER encoded
4215 @var{name}: a pointer to the CN name, may be NULL (but MUST then be added later)
4217 @var{sizeof_name}: holds the size of @code{name}
4219 This function will set the subject in @code{crt} to the end entity's
4220 @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy
4221 certificate naming style. Note that if @code{name} is @code{NULL} , you MUST
4222 set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar.
4224 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4225 negative error value.
4228 @subheading gnutls_x509_crt_set_serial
4229 @anchor{gnutls_x509_crt_set_serial}
4230 @deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size})
4231 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4233 @var{serial}: The serial number
4235 @var{serial_size}: Holds the size of the serial field.
4237 This function will set the X.509 certificate's serial number.
4238 While the serial number is an integer, it is often handled
4239 as an opaque field by several CAs. For this reason this function
4240 accepts any kind of data as a serial number. To be consistent
4241 with the X.509/PKIX specifications the provided @code{serial} should be
4242 a big-endian positive number (i.e. it's leftmost bit should be zero).
4244 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4245 negative error value.
4248 @subheading gnutls_x509_crt_set_subject_alt_name
4249 @anchor{gnutls_x509_crt_set_subject_alt_name}
4250 @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})
4251 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4253 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4255 @var{data}: The data to be set
4257 @var{data_size}: The size of data to be set
4259 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
4261 This function will set the subject alternative name certificate
4262 extension. It can set the following types:
4264 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4265 negative error value.
4267 @strong{Since:} 2.6.0
4270 @subheading gnutls_x509_crt_set_subject_alternative_name
4271 @anchor{gnutls_x509_crt_set_subject_alternative_name}
4272 @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})
4273 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4275 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
4277 @var{data_string}: The data to be set, a (0) terminated string
4279 This function will set the subject alternative name certificate
4280 extension. This function assumes that data can be expressed as a null
4283 The name of the function is unfortunate since it is incosistent with
4284 @code{gnutls_x509_crt_get_subject_alt_name()} .
4286 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4287 negative error value.
4290 @subheading gnutls_x509_crt_set_subject_key_id
4291 @anchor{gnutls_x509_crt_set_subject_key_id}
4292 @deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4293 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4295 @var{id}: The key ID
4297 @var{id_size}: Holds the size of the subject key ID field.
4299 This function will set the X.509 certificate's subject key ID
4302 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4303 negative error value.
4306 @subheading gnutls_x509_crt_set_subject_unique_id
4307 @anchor{gnutls_x509_crt_set_subject_unique_id}
4308 @deftypefun {int} {gnutls_x509_crt_set_subject_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
4309 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
4311 @var{id}: The unique ID
4313 @var{id_size}: Holds the size of the unique ID.
4315 This function will set the X.509 certificate's subject unique ID field.
4317 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4318 negative error value.
4321 @subheading gnutls_x509_crt_set_version
4322 @anchor{gnutls_x509_crt_set_version}
4323 @deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version})
4324 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4326 @var{version}: holds the version number. For X.509v1 certificates must be 1.
4328 This function will set the version of the certificate. This must
4329 be one for X.509 version 1, and so on. Plain certificates without
4330 extensions must have version set to one.
4332 To create well-formed certificates, you must specify version 3 if
4333 you use any certificate extensions. Extensions are created by
4334 functions such as @code{gnutls_x509_crt_set_subject_alt_name()}
4335 or @code{gnutls_x509_crt_set_key_usage()} .
4337 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4338 negative error value.
4341 @subheading gnutls_x509_crt_sign
4342 @anchor{gnutls_x509_crt_sign}
4343 @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})
4344 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4346 @var{issuer}: is the certificate of the certificate issuer
4348 @var{issuer_key}: holds the issuer's private key
4350 This function is the same a @code{gnutls_x509_crt_sign2()} with no flags,
4351 and SHA1 as the hash algorithm.
4353 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4354 negative error value.
4357 @subheading gnutls_x509_crt_sign2
4358 @anchor{gnutls_x509_crt_sign2}
4359 @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})
4360 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
4362 @var{issuer}: is the certificate of the certificate issuer
4364 @var{issuer_key}: holds the issuer's private key
4366 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
4368 @var{flags}: must be 0
4370 This function will sign the certificate with the issuer's private key, and
4371 will copy the issuer's information into the certificate.
4373 This must be the last step in a certificate generation since all
4374 the previously set parameters are now signed.
4376 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4377 negative error value.
4380 @subheading gnutls_x509_crt_verify
4381 @anchor{gnutls_x509_crt_verify}
4382 @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})
4383 @var{cert}: is the certificate to be verified
4385 @var{CA_list}: is one certificate that is considered to be trusted one
4387 @var{CA_list_length}: holds the number of CA certificate in CA_list
4389 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
4391 @var{verify}: will hold the certificate verification output.
4393 This function will try to verify the given certificate and return
4394 its status. Note that a verification error does not imply a negative
4395 return status. In that case the @code{verify} status is set.
4397 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4398 negative error value.
4401 @subheading gnutls_x509_dn_deinit
4402 @anchor{gnutls_x509_dn_deinit}
4403 @deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn})
4404 @var{dn}: a DN uint8_t object pointer.
4406 This function deallocates the DN object as returned by
4407 @code{gnutls_x509_dn_import()} .
4409 @strong{Since:} 2.4.0
4412 @subheading gnutls_x509_dn_export
4413 @anchor{gnutls_x509_dn_export}
4414 @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})
4415 @var{dn}: Holds the uint8_t DN object
4417 @var{format}: the format of output params. One of PEM or DER.
4419 @var{output_data}: will contain a DN PEM or DER encoded
4421 @var{output_data_size}: holds the size of output_data (and will be
4422 replaced by the actual size of parameters)
4424 This function will export the DN to DER or PEM format.
4426 If the buffer provided is not long enough to hold the output, then
4427 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
4430 If the structure is PEM encoded, it will have a header
4433 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4434 negative error value.
4437 @subheading gnutls_x509_dn_export2
4438 @anchor{gnutls_x509_dn_export2}
4439 @deftypefun {int} {gnutls_x509_dn_export2} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
4440 @var{dn}: Holds the uint8_t DN object
4442 @var{format}: the format of output params. One of PEM or DER.
4444 @var{out}: will contain a DN PEM or DER encoded
4446 This function will export the DN to DER or PEM format.
4448 The output buffer is allocated using @code{gnutls_malloc()} .
4450 If the structure is PEM encoded, it will have a header
4453 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4454 negative error value.
4456 @strong{Since:} 3.1.3
4459 @subheading gnutls_x509_dn_get_rdn_ava
4460 @anchor{gnutls_x509_dn_get_rdn_ava}
4461 @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})
4462 @var{dn}: a pointer to DN
4464 @var{irdn}: index of RDN
4466 @var{iava}: index of AVA.
4468 @var{ava}: Pointer to structure which will hold output information.
4470 Get pointers to data within the DN. The format of the @code{ava} structure
4473 struct gnutls_x509_ava_st @{
4475 gnutls_datum_t value;
4476 unsigned long value_tag;
4479 The X.509 distinguished name is a sequence of sequences of strings
4480 and this is what the @code{irdn} and @code{iava} indexes model.
4482 Note that @code{ava} will contain pointers into the @code{dn} structure which
4483 in turns points to the original certificate. Thus you should not
4484 modify any data or deallocate any of those.
4486 This is a low-level function that requires the caller to do the
4487 value conversions when necessary (e.g. from UCS-2).
4489 @strong{Returns:} Returns 0 on success, or an error code.
4492 @subheading gnutls_x509_dn_import
4493 @anchor{gnutls_x509_dn_import}
4494 @deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data})
4495 @var{dn}: the structure that will hold the imported DN
4497 @var{data}: should contain a DER encoded RDN sequence
4499 This function parses an RDN sequence and stores the result to a
4500 @code{gnutls_x509_dn_t} structure. The structure must have been initialized
4501 with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to
4504 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4505 negative error value.
4507 @strong{Since:} 2.4.0
4510 @subheading gnutls_x509_dn_init
4511 @anchor{gnutls_x509_dn_init}
4512 @deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn})
4513 @var{dn}: the object to be initialized
4515 This function initializes a @code{gnutls_x509_dn_t} structure.
4517 The object returned must be deallocated using
4518 @code{gnutls_x509_dn_deinit()} .
4520 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4521 negative error value.
4523 @strong{Since:} 2.4.0
4526 @subheading gnutls_x509_dn_oid_known
4527 @anchor{gnutls_x509_dn_oid_known}
4528 @deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid})
4529 @var{oid}: holds an Object Identifier in a null terminated string
4531 This function will inform about known DN OIDs. This is useful since
4532 functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information
4533 on known OIDs to properly encode their input. Object Identifiers
4534 that are not known are not encoded by these functions, and their
4535 input is stored directly into the ASN.1 structure. In that case of
4536 unknown OIDs, you have the responsibility of DER encoding your
4539 @strong{Returns:} 1 on known OIDs and 0 otherwise.
4542 @subheading gnutls_x509_dn_oid_name
4543 @anchor{gnutls_x509_dn_oid_name}
4544 @deftypefun {const char *} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags})
4545 @var{oid}: holds an Object Identifier in a null terminated string
4547 @var{flags}: 0 or GNUTLS_X509_DN_OID_*
4549 This function will return the name of a known DN OID. If
4550 @code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function
4551 will return the given OID if no descriptive name has been
4554 @strong{Returns:} A null terminated string or NULL otherwise.
4559 @subheading gnutls_x509_ext_deinit
4560 @anchor{gnutls_x509_ext_deinit}
4561 @deftypefun {void} {gnutls_x509_ext_deinit} (gnutls_x509_ext_st * @var{ext})
4562 @var{ext}: The extensions structure
4564 This function will deinitialize an extensions structure.
4566 @strong{Since:} 3.3.8
4569 @subheading gnutls_x509_ext_export_aia
4570 @anchor{gnutls_x509_ext_export_aia}
4571 @deftypefun {int} {gnutls_x509_ext_export_aia} (gnutls_x509_aia_t @var{aia}, gnutls_datum_t * @var{ext})
4572 @var{aia}: The authority info access structure
4574 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4576 This function will DER encode the Authority Information Access (AIA)
4577 extension; see RFC 5280 section 4.2.2.1 for more information on the
4580 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4581 negative error value.
4583 @strong{Since:} 3.3.0
4586 @subheading gnutls_x509_ext_export_authority_key_id
4587 @anchor{gnutls_x509_ext_export_authority_key_id}
4588 @deftypefun {int} {gnutls_x509_ext_export_authority_key_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{ext})
4589 @var{aki}: An initialized authority key identifier structure
4591 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4593 This function will convert the provided key identifier to a
4594 DER-encoded PKIX AuthorityKeyIdentifier extension.
4595 The output data in @code{ext} will be allocated using
4596 @code{gnutls_malloc()} .
4598 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4600 @strong{Since:} 3.3.0
4603 @subheading gnutls_x509_ext_export_basic_constraints
4604 @anchor{gnutls_x509_ext_export_basic_constraints}
4605 @deftypefun {int} {gnutls_x509_ext_export_basic_constraints} (unsigned int @var{ca}, int @var{pathlen}, gnutls_datum_t * @var{ext})
4606 @var{ca}: non-zero for a CA
4608 @var{pathlen}: The path length constraint (set to -1 for no constraint)
4610 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4612 This function will convert the parameters provided to a basic constraints
4613 DER encoded extension (2.5.29.19).
4614 The @code{ext} data will be allocated using
4615 @code{gnutls_malloc()} .
4617 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4618 negative error value.
4620 @strong{Since:} 3.3.0
4623 @subheading gnutls_x509_ext_export_crl_dist_points
4624 @anchor{gnutls_x509_ext_export_crl_dist_points}
4625 @deftypefun {int} {gnutls_x509_ext_export_crl_dist_points} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_datum_t * @var{ext})
4626 @var{cdp}: A pointer to an initialized CRL distribution points structure.
4628 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4630 This function will convert the provided policies, to a certificate policy
4631 DER encoded extension (2.5.29.31).
4633 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4635 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4637 @strong{Since:} 3.3.0
4640 @subheading gnutls_x509_ext_export_key_purposes
4641 @anchor{gnutls_x509_ext_export_key_purposes}
4642 @deftypefun {int} {gnutls_x509_ext_export_key_purposes} (gnutls_x509_key_purposes_t @var{p}, gnutls_datum_t * @var{ext})
4643 @var{p}: The key purposes structure
4645 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4647 This function will convert the key purposes structure to a
4648 DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in
4649 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4651 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4653 @strong{Since:} 3.3.0
4656 @subheading gnutls_x509_ext_export_key_usage
4657 @anchor{gnutls_x509_ext_export_key_usage}
4658 @deftypefun {int} {gnutls_x509_ext_export_key_usage} (unsigned int @var{usage}, gnutls_datum_t * @var{ext})
4659 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4661 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4663 This function will convert the keyUsage bit string to a DER
4664 encoded PKIX extension. The @code{ext} data will be allocated using
4665 @code{gnutls_malloc()} .
4667 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4668 negative error value.
4670 @strong{Since:} 3.3.0
4673 @subheading gnutls_x509_ext_export_name_constraints
4674 @anchor{gnutls_x509_ext_export_name_constraints}
4675 @deftypefun {int} {gnutls_x509_ext_export_name_constraints} (gnutls_x509_name_constraints_t @var{nc}, gnutls_datum_t * @var{ext})
4676 @var{nc}: The nameconstraints structure
4678 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4680 This function will convert the provided name constraints structure to a
4681 DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in
4682 @code{ext} will be allocated usin @code{gnutls_malloc()} .
4684 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4686 @strong{Since:} 3.3.0
4689 @subheading gnutls_x509_ext_export_policies
4690 @anchor{gnutls_x509_ext_export_policies}
4691 @deftypefun {int} {gnutls_x509_ext_export_policies} (gnutls_x509_policies_t @var{policies}, gnutls_datum_t * @var{ext})
4692 @var{policies}: A pointer to an initialized policies structure.
4694 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4696 This function will convert the provided policies, to a certificate policy
4697 DER encoded extension (2.5.29.32).
4699 The @code{ext} data will be allocated using @code{gnutls_malloc()} .
4701 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4703 @strong{Since:} 3.3.0
4706 @subheading gnutls_x509_ext_export_private_key_usage_period
4707 @anchor{gnutls_x509_ext_export_private_key_usage_period}
4708 @deftypefun {int} {gnutls_x509_ext_export_private_key_usage_period} (time_t @var{activation}, time_t @var{expiration}, gnutls_datum_t * @var{ext})
4709 @var{activation}: The activation time
4711 @var{expiration}: The expiration time
4713 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4715 This function will convert the periods provided to a private key
4716 usage DER encoded extension (2.5.29.16).
4717 The @code{ext} data will be allocated using
4718 @code{gnutls_malloc()} .
4720 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4721 negative error value.
4723 @strong{Since:} 3.3.0
4726 @subheading gnutls_x509_ext_export_proxy
4727 @anchor{gnutls_x509_ext_export_proxy}
4728 @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})
4729 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
4730 and negative error codes indicate that the pathLenConstraints field should
4733 @var{policyLanguage}: OID describing the language of @code{policy} .
4735 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
4737 @var{sizeof_policy}: size of @code{policy} .
4739 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4741 This function will convert the parameters provided to a proxyCertInfo extension.
4743 The @code{ext} data will be allocated using
4744 @code{gnutls_malloc()} .
4746 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4747 negative error value.
4749 @strong{Since:} 3.3.0
4752 @subheading gnutls_x509_ext_export_subject_alt_names
4753 @anchor{gnutls_x509_ext_export_subject_alt_names}
4754 @deftypefun {int} {gnutls_x509_ext_export_subject_alt_names} (gnutls_subject_alt_names_t @var{sans}, gnutls_datum_t * @var{ext})
4755 @var{sans}: The alternative names structure
4757 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4759 This function will convert the provided alternative names structure to a
4760 DER-encoded SubjectAltName PKIX extension. The output data in @code{ext} will be allocated using
4761 @code{gnutls_malloc()} .
4763 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4765 @strong{Since:} 3.3.0
4768 @subheading gnutls_x509_ext_export_subject_key_id
4769 @anchor{gnutls_x509_ext_export_subject_key_id}
4770 @deftypefun {int} {gnutls_x509_ext_export_subject_key_id} (const gnutls_datum_t * @var{id}, gnutls_datum_t * @var{ext})
4771 @var{id}: The key identifier
4773 @var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} .
4775 This function will convert the provided key identifier to a
4776 DER-encoded PKIX SubjectKeyIdentifier extension.
4777 The output data in @code{ext} will be allocated using
4778 @code{gnutls_malloc()} .
4780 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4782 @strong{Since:} 3.3.0
4785 @subheading gnutls_x509_ext_import_aia
4786 @anchor{gnutls_x509_ext_import_aia}
4787 @deftypefun {int} {gnutls_x509_ext_import_aia} (const gnutls_datum_t * @var{ext}, gnutls_x509_aia_t @var{aia}, unsigned int @var{flags})
4788 @var{ext}: The DER-encoded extension data
4790 @var{aia}: The authority info access structure
4792 @var{flags}: should be zero
4794 This function extracts the Authority Information Access (AIA)
4795 extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1
4796 for more information on the extension. The
4797 AIA extension holds a sequence of AccessDescription (AD) data.
4799 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4801 @strong{Since:} 3.3.0
4804 @subheading gnutls_x509_ext_import_authority_key_id
4805 @anchor{gnutls_x509_ext_import_authority_key_id}
4806 @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})
4807 @var{ext}: a DER encoded extension
4809 @var{aki}: An initialized authority key identifier structure
4811 @var{flags}: should be zero
4813 This function will return the subject key ID stored in the provided
4814 AuthorityKeyIdentifier extension.
4816 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4817 if the extension is not present, otherwise a negative error value.
4819 @strong{Since:} 3.3.0
4822 @subheading gnutls_x509_ext_import_basic_constraints
4823 @anchor{gnutls_x509_ext_import_basic_constraints}
4824 @deftypefun {int} {gnutls_x509_ext_import_basic_constraints} (const gnutls_datum_t * @var{ext}, unsigned int * @var{ca}, int * @var{pathlen})
4825 @var{ext}: the DER encoded extension data
4827 @var{ca}: will be non zero if the CA status is true
4829 @var{pathlen}: the path length constraint; will be set to -1 for no limit
4831 This function will return the CA status and path length constraint
4832 as written in the PKIX extension 2.5.29.19.
4834 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4835 negative error value.
4837 @strong{Since:} 3.3.0
4840 @subheading gnutls_x509_ext_import_crl_dist_points
4841 @anchor{gnutls_x509_ext_import_crl_dist_points}
4842 @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})
4843 @var{ext}: the DER encoded extension data
4845 @var{cdp}: A pointer to an initialized CRL distribution points structure.
4847 @var{flags}: should be zero
4849 This function will extract the CRL distribution points extension (2.5.29.31)
4850 and store it into the provided structure.
4852 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4854 @strong{Since:} 3.3.0
4857 @subheading gnutls_x509_ext_import_key_purposes
4858 @anchor{gnutls_x509_ext_import_key_purposes}
4859 @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})
4860 @var{ext}: The DER-encoded extension data
4862 @var{p}: The key purposes structure
4864 @var{flags}: should be zero
4866 This function will extract the key purposes in the provided DER-encoded
4867 ExtKeyUsageSyntax PKIX extension, to a @code{gnutls_x509_key_purposes_t} structure.
4868 The structure must be initialized.
4870 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4872 @strong{Since:} 3.3.0
4875 @subheading gnutls_x509_ext_import_key_usage
4876 @anchor{gnutls_x509_ext_import_key_usage}
4877 @deftypefun {int} {gnutls_x509_ext_import_key_usage} (const gnutls_datum_t * @var{ext}, unsigned int * @var{key_usage})
4878 @var{ext}: the DER encoded extension data
4880 @var{key_usage}: where the key usage bits will be stored
4882 This function will return certificate's key usage, by reading the DER
4883 data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
4884 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
4885 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
4886 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
4887 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
4888 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
4890 @strong{Returns:} the certificate key usage, or a negative error code in case of
4891 parsing error. If the certificate does not contain the keyUsage
4892 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
4895 @strong{Since:} 3.3.0
4898 @subheading gnutls_x509_ext_import_name_constraints
4899 @anchor{gnutls_x509_ext_import_name_constraints}
4900 @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})
4901 @var{ext}: a DER encoded extension
4903 @var{nc}: The nameconstraints intermediate structure
4905 @var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND}
4907 This function will return an intermediate structure containing
4908 the name constraints of the provided NameConstraints extension. That
4909 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
4910 to verify whether a server's name is in accordance with the constraints.
4912 When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if
4913 the @code{nc} structure is empty
4914 this function will behave identically as if the flag was not set.
4915 Otherwise if there are elements in the @code{nc} structure then only the
4916 excluded constraints will be appended to the constraints.
4918 Note that @code{nc} must be initialized prior to calling this function.
4920 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
4921 if the extension is not present, otherwise a negative error value.
4923 @strong{Since:} 3.3.0
4926 @subheading gnutls_x509_ext_import_policies
4927 @anchor{gnutls_x509_ext_import_policies}
4928 @deftypefun {int} {gnutls_x509_ext_import_policies} (const gnutls_datum_t * @var{ext}, gnutls_x509_policies_t @var{policies}, unsigned int @var{flags})
4929 @var{ext}: the DER encoded extension data
4931 @var{policies}: A pointer to an initialized policies structures.
4933 @var{flags}: should be zero
4935 This function will extract the certificate policy extension (2.5.29.32)
4936 and store it the provided structure.
4938 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
4940 @strong{Since:} 3.3.0
4943 @subheading gnutls_x509_ext_import_private_key_usage_period
4944 @anchor{gnutls_x509_ext_import_private_key_usage_period}
4945 @deftypefun {int} {gnutls_x509_ext_import_private_key_usage_period} (const gnutls_datum_t * @var{ext}, time_t * @var{activation}, time_t * @var{expiration})
4946 @var{ext}: the DER encoded extension data
4948 @var{activation}: Will hold the activation time
4950 @var{expiration}: Will hold the expiration time
4952 This function will return the expiration and activation
4953 times of the private key as written in the
4954 PKIX extension 2.5.29.16.
4956 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4957 negative error value.
4959 @strong{Since:} 3.3.0
4962 @subheading gnutls_x509_ext_import_proxy
4963 @anchor{gnutls_x509_ext_import_proxy}
4964 @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})
4965 @var{ext}: the DER encoded extension data
4967 @var{pathlen}: pointer to output integer indicating path length (may be
4968 NULL), non-negative error codes indicate a present pCPathLenConstraint
4969 field and the actual value, -1 indicate that the field is absent.
4971 @var{policyLanguage}: output variable with OID of policy language
4973 @var{policy}: output variable with policy data
4975 @var{sizeof_policy}: output variable size of policy data
4977 This function will return the information from a proxy certificate
4978 extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
4979 The @code{policyLanguage} and @code{policy} values must be deinitialized using @code{gnutls_free()} after use.
4981 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4982 negative error value.
4984 @strong{Since:} 3.3.0
4987 @subheading gnutls_x509_ext_import_subject_alt_names
4988 @anchor{gnutls_x509_ext_import_subject_alt_names}
4989 @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})
4990 @var{ext}: The DER-encoded extension data
4992 @var{sans}: The alternative names structure
4994 @var{flags}: should be zero
4996 This function will export the alternative names in the provided DER-encoded
4997 SubjectAltName PKIX extension, to a @code{gnutls_subject_alt_names_t} structure. The structure
4998 must have been initialized.
5000 This function will succeed even if there no subject alternative names
5003 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5005 @strong{Since:} 3.3.0
5008 @subheading gnutls_x509_ext_import_subject_key_id
5009 @anchor{gnutls_x509_ext_import_subject_key_id}
5010 @deftypefun {int} {gnutls_x509_ext_import_subject_key_id} (const gnutls_datum_t * @var{ext}, gnutls_datum_t * @var{id})
5011 @var{ext}: a DER encoded extension
5013 @var{id}: will contain the subject key ID
5015 This function will return the subject key ID stored in the provided
5016 SubjectKeyIdentifier extension. The ID will be allocated using
5017 @code{gnutls_malloc()} .
5019 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5020 if the extension is not present, otherwise a negative error value.
5022 @strong{Since:} 3.3.0
5025 @subheading gnutls_x509_ext_print
5026 @anchor{gnutls_x509_ext_print}
5027 @deftypefun {int} {gnutls_x509_ext_print} (gnutls_x509_ext_st * @var{exts}, unsigned int @var{exts_size}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
5028 @var{exts}: The structures to be printed
5030 @var{exts_size}: the number of available structures
5032 @var{format}: Indicate the format to use
5034 @var{out}: Newly allocated datum with null terminated string.
5036 This function will pretty print X.509 certificate extensions,
5037 suitable for display to a human.
5039 The output @code{out} needs to be deallocated using @code{gnutls_free()} .
5041 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5042 negative error value.
5045 @subheading gnutls_x509_key_purpose_deinit
5046 @anchor{gnutls_x509_key_purpose_deinit}
5047 @deftypefun {void} {gnutls_x509_key_purpose_deinit} (gnutls_x509_key_purposes_t @var{p})
5048 @var{p}: The key purposes structure
5050 This function will deinitialize an alternative names structure.
5052 @strong{Since:} 3.3.0
5055 @subheading gnutls_x509_key_purpose_get
5056 @anchor{gnutls_x509_key_purpose_get}
5057 @deftypefun {int} {gnutls_x509_key_purpose_get} (gnutls_x509_key_purposes_t @var{p}, unsigned @var{idx}, gnutls_datum_t * @var{oid})
5058 @var{p}: The key purposes structure
5060 @var{idx}: The index of the key purpose to retrieve
5062 @var{oid}: Will hold the object identifier of the key purpose (to be treated as constant)
5064 This function will retrieve the specified by the index key purpose in the
5065 purposes structure. The object identifier will be a null terminated string.
5067 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5068 if the index is out of bounds, otherwise a negative error value.
5070 @strong{Since:} 3.3.0
5073 @subheading gnutls_x509_key_purpose_init
5074 @anchor{gnutls_x509_key_purpose_init}
5075 @deftypefun {int} {gnutls_x509_key_purpose_init} (gnutls_x509_key_purposes_t * @var{p})
5076 @var{p}: The key purposes structure
5078 This function will initialize an alternative names structure.
5080 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5082 @strong{Since:} 3.3.0
5085 @subheading gnutls_x509_key_purpose_set
5086 @anchor{gnutls_x509_key_purpose_set}
5087 @deftypefun {int} {gnutls_x509_key_purpose_set} (gnutls_x509_key_purposes_t @var{p}, const char * @var{oid})
5088 @var{p}: The key purposes structure
5090 @var{oid}: The object identifier of the key purpose
5092 This function will store the specified key purpose in the
5095 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
5097 @strong{Since:} 3.3.0
5100 @subheading gnutls_x509_name_constraints_add_excluded
5101 @anchor{gnutls_x509_name_constraints_add_excluded}
5102 @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})
5103 @var{nc}: The nameconstraints structure
5105 @var{type}: The type of the constraints
5107 @var{name}: The data of the constraints
5109 This function will add a name constraint to the list of excluded
5110 constraints. The constraints @code{type} can be any of the following types:
5111 @code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} ,
5112 @code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address
5113 in network byte order is expected, followed by its network mask (which is
5114 4 bytes in IPv4 or 16-bytes in IPv6).
5116 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5118 @strong{Since:} 3.3.0
5121 @subheading gnutls_x509_name_constraints_add_permitted
5122 @anchor{gnutls_x509_name_constraints_add_permitted}
5123 @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})
5124 @var{nc}: The nameconstraints structure
5126 @var{type}: The type of the constraints
5128 @var{name}: The data of the constraints
5130 This function will add a name constraint to the list of permitted
5131 constraints. The constraints @code{type} can be any of the following types:
5132 @code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} ,
5133 @code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address
5134 in network byte order is expected, followed by its network mask.
5136 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5138 @strong{Since:} 3.3.0
5141 @subheading gnutls_x509_name_constraints_check
5142 @anchor{gnutls_x509_name_constraints_check}
5143 @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})
5144 @var{nc}: the extracted name constraints structure
5146 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5148 @var{name}: the name to be checked
5150 This function will check the provided name against the constraints in
5151 @code{nc} using the RFC5280 rules. Currently this function is limited to DNS
5152 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5154 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5156 @strong{Since:} 3.3.0
5159 @subheading gnutls_x509_name_constraints_check_crt
5160 @anchor{gnutls_x509_name_constraints_check_crt}
5161 @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})
5162 @var{nc}: the extracted name constraints structure
5164 @var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
5166 @var{cert}: the certificate to be checked
5168 This function will check the provided certificate names against the constraints in
5169 @code{nc} using the RFC5280 rules. It will traverse all the certificate's names and
5172 Currently this function is limited to DNS
5173 names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ).
5175 @strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise.
5177 @strong{Since:} 3.3.0
5180 @subheading gnutls_x509_name_constraints_deinit
5181 @anchor{gnutls_x509_name_constraints_deinit}
5182 @deftypefun {void} {gnutls_x509_name_constraints_deinit} (gnutls_x509_name_constraints_t @var{nc})
5183 @var{nc}: The nameconstraints structure
5185 This function will deinitialize a name constraints structure.
5187 @strong{Since:} 3.3.0
5190 @subheading gnutls_x509_name_constraints_get_excluded
5191 @anchor{gnutls_x509_name_constraints_get_excluded}
5192 @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})
5193 @var{nc}: the extracted name constraints structure
5195 @var{idx}: the index of the constraint
5197 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5199 @var{name}: the name in the constraint (of the specific type)
5201 This function will return an intermediate structure containing
5202 the name constraints of the provided CA certificate. That
5203 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5204 to verify whether a server's name is in accordance with the constraints.
5206 The name should be treated as constant and valid for the lifetime of @code{nc} .
5208 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5209 if the extension is not present, otherwise a negative error value.
5211 @strong{Since:} 3.3.0
5214 @subheading gnutls_x509_name_constraints_get_permitted
5215 @anchor{gnutls_x509_name_constraints_get_permitted}
5216 @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})
5217 @var{nc}: the extracted name constraints structure
5219 @var{idx}: the index of the constraint
5221 @var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
5223 @var{name}: the name in the constraint (of the specific type)
5225 This function will return an intermediate structure containing
5226 the name constraints of the provided CA certificate. That
5227 structure can be used in combination with @code{gnutls_x509_name_constraints_check()}
5228 to verify whether a server's name is in accordance with the constraints.
5230 The name should be treated as constant and valid for the lifetime of @code{nc} .
5232 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5233 if the extension is not present, otherwise a negative error value.
5235 @strong{Since:} 3.3.0
5238 @subheading gnutls_x509_name_constraints_init
5239 @anchor{gnutls_x509_name_constraints_init}
5240 @deftypefun {int} {gnutls_x509_name_constraints_init} (gnutls_x509_name_constraints_t * @var{nc})
5241 @var{nc}: The nameconstraints structure
5243 This function will initialize a name constraints structure.
5245 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5247 @strong{Since:} 3.3.0
5250 @subheading gnutls_x509_othername_to_virtual
5251 @anchor{gnutls_x509_othername_to_virtual}
5252 @deftypefun {int} {gnutls_x509_othername_to_virtual} (const char * @var{oid}, const gnutls_datum_t * @var{othername}, unsigned int * @var{virt_type}, gnutls_datum_t * @var{virt})
5253 @var{oid}: The othername object identifier
5255 @var{othername}: -- undescribed --
5257 @var{virt_type}: GNUTLS_SAN_OTHERNAME_XXX
5259 @var{virt}: allocated printable data
5261 This function will parse and convert the othername data to a virtual
5262 type supported by gnutls.
5264 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5266 @strong{Since:} 3.3.8
5269 @subheading gnutls_x509_policies_deinit
5270 @anchor{gnutls_x509_policies_deinit}
5271 @deftypefun {void} {gnutls_x509_policies_deinit} (gnutls_x509_policies_t @var{policies})
5272 @var{policies}: The authority key identifier structure
5274 This function will deinitialize an authority key identifier structure.
5276 @strong{Since:} 3.3.0
5279 @subheading gnutls_x509_policies_get
5280 @anchor{gnutls_x509_policies_get}
5281 @deftypefun {int} {gnutls_x509_policies_get} (gnutls_x509_policies_t @var{policies}, unsigned int @var{seq}, struct gnutls_x509_policy_st * @var{policy})
5282 @var{policies}: The policies structure
5284 @var{seq}: The index of the name to get
5286 @var{policy}: Will hold the policy
5288 This function will return a specific policy as stored in
5289 the @code{policies} structure. The returned values should be treated as constant
5290 and valid for the lifetime of @code{policies} .
5292 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
5293 if the index is out of bounds, otherwise a negative error value.
5295 @strong{Since:} 3.3.0
5298 @subheading gnutls_x509_policies_init
5299 @anchor{gnutls_x509_policies_init}
5300 @deftypefun {int} {gnutls_x509_policies_init} (gnutls_x509_policies_t * @var{policies})
5301 @var{policies}: The authority key ID structure
5303 This function will initialize an authority key ID structure.
5305 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value.
5307 @strong{Since:} 3.3.0
5310 @subheading gnutls_x509_policies_set
5311 @anchor{gnutls_x509_policies_set}
5312 @deftypefun {int} {gnutls_x509_policies_set} (gnutls_x509_policies_t @var{policies}, const struct gnutls_x509_policy_st * @var{policy})
5313 @var{policies}: An initialized policies structure
5315 @var{policy}: Contains the policy to set
5317 This function will store the specified policy in
5318 the provided @code{policies} structure.
5320 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value.
5322 @strong{Since:} 3.3.0
5325 @subheading gnutls_x509_policy_release
5326 @anchor{gnutls_x509_policy_release}
5327 @deftypefun {void} {gnutls_x509_policy_release} (struct gnutls_x509_policy_st * @var{policy})
5328 @var{policy}: a certificate policy
5330 This function will deinitialize all memory associated with the provided
5331 @code{policy} . The policy is allocated using @code{gnutls_x509_crt_get_policy()} .
5333 @strong{Since:} 3.1.5
5336 @subheading gnutls_x509_privkey_cpy
5337 @anchor{gnutls_x509_privkey_cpy}
5338 @deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src})
5339 @var{dst}: The destination key, which should be initialized.
5341 @var{src}: The source key
5343 This function will copy a private key from source to destination
5344 key. Destination has to be initialized.
5346 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5347 negative error value.
5350 @subheading gnutls_x509_privkey_deinit
5351 @anchor{gnutls_x509_privkey_deinit}
5352 @deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key})
5353 @var{key}: The structure to be deinitialized
5355 This function will deinitialize a private key structure.
5358 @subheading gnutls_x509_privkey_export
5359 @anchor{gnutls_x509_privkey_export}
5360 @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})
5361 @var{key}: Holds the key
5363 @var{format}: the format of output params. One of PEM or DER.
5365 @var{output_data}: will contain a private key PEM or DER encoded
5367 @var{output_data_size}: holds the size of output_data (and will be
5368 replaced by the actual size of parameters)
5370 This function will export the private key to a PKCS1 structure for
5371 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5372 the same format with the parameters used by openssl.
5374 If the buffer provided is not long enough to hold the output, then
5375 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
5378 If the structure is PEM encoded, it will have a header
5379 of "BEGIN RSA PRIVATE KEY".
5381 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5382 negative error value.
5385 @subheading gnutls_x509_privkey_export2
5386 @anchor{gnutls_x509_privkey_export2}
5387 @deftypefun {int} {gnutls_x509_privkey_export2} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
5388 @var{key}: Holds the key
5390 @var{format}: the format of output params. One of PEM or DER.
5392 @var{out}: will contain a private key PEM or DER encoded
5394 This function will export the private key to a PKCS1 structure for
5395 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
5396 the same format with the parameters used by openssl.
5398 The output buffer is allocated using @code{gnutls_malloc()} .
5400 If the structure is PEM encoded, it will have a header
5401 of "BEGIN RSA PRIVATE KEY".
5403 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5404 negative error value.
5409 @subheading gnutls_x509_privkey_export2_pkcs8
5410 @anchor{gnutls_x509_privkey_export2_pkcs8}
5411 @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})
5412 @var{key}: Holds the key
5414 @var{format}: the format of output params. One of PEM or DER.
5416 @var{password}: the password that will be used to encrypt the key.
5418 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5420 @var{out}: will contain a private key PEM or DER encoded
5422 This function will export the private key to a PKCS8 structure.
5423 Both RSA and DSA keys can be exported. For DSA keys we use
5424 PKCS @code{11} definitions. If the flags do not specify the encryption
5425 cipher, then the default 3DES (PBES2) will be used.
5427 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5428 encryption schemas, or ASCII for the PKCS12 schemas.
5430 The output buffer is allocated using @code{gnutls_malloc()} .
5432 If the structure is PEM encoded, it will have a header
5433 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5434 encryption is not used.
5436 @strong{Returns:} In case of failure a negative error code will be
5437 returned, and 0 on success.
5442 @subheading gnutls_x509_privkey_export_dsa_raw
5443 @anchor{gnutls_x509_privkey_export_dsa_raw}
5444 @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})
5445 @var{key}: a structure that holds the DSA parameters
5447 @var{p}: will hold the p
5449 @var{q}: will hold the q
5451 @var{g}: will hold the g
5453 @var{y}: will hold the y
5455 @var{x}: will hold the x
5457 This function will export the DSA private key's parameters found
5458 in the given structure. The new parameters will be allocated using
5459 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5461 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5462 negative error value.
5465 @subheading gnutls_x509_privkey_export_ecc_raw
5466 @anchor{gnutls_x509_privkey_export_ecc_raw}
5467 @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})
5468 @var{key}: a structure that holds the rsa parameters
5470 @var{curve}: will hold the curve
5472 @var{x}: will hold the x coordinate
5474 @var{y}: will hold the y coordinate
5476 @var{k}: will hold the private key
5478 This function will export the ECC private key's parameters found
5479 in the given structure. The new parameters will be allocated using
5480 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5482 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5483 negative error value.
5488 @subheading gnutls_x509_privkey_export_pkcs8
5489 @anchor{gnutls_x509_privkey_export_pkcs8}
5490 @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})
5491 @var{key}: Holds the key
5493 @var{format}: the format of output params. One of PEM or DER.
5495 @var{password}: the password that will be used to encrypt the key.
5497 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5499 @var{output_data}: will contain a private key PEM or DER encoded
5501 @var{output_data_size}: holds the size of output_data (and will be
5502 replaced by the actual size of parameters)
5504 This function will export the private key to a PKCS8 structure.
5505 Both RSA and DSA keys can be exported. For DSA keys we use
5506 PKCS @code{11} definitions. If the flags do not specify the encryption
5507 cipher, then the default 3DES (PBES2) will be used.
5509 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5510 encryption schemas, or ASCII for the PKCS12 schemas.
5512 If the buffer provided is not long enough to hold the output, then
5513 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
5516 If the structure is PEM encoded, it will have a header
5517 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
5518 encryption is not used.
5520 @strong{Returns:} In case of failure a negative error code will be
5521 returned, and 0 on success.
5524 @subheading gnutls_x509_privkey_export_rsa_raw
5525 @anchor{gnutls_x509_privkey_export_rsa_raw}
5526 @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})
5527 @var{key}: a structure that holds the rsa parameters
5529 @var{m}: will hold the modulus
5531 @var{e}: will hold the public exponent
5533 @var{d}: will hold the private exponent
5535 @var{p}: will hold the first prime (p)
5537 @var{q}: will hold the second prime (q)
5539 @var{u}: will hold the coefficient
5541 This function will export the RSA private key's parameters found
5542 in the given structure. The new parameters will be allocated using
5543 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5545 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5546 negative error value.
5549 @subheading gnutls_x509_privkey_export_rsa_raw2
5550 @anchor{gnutls_x509_privkey_export_rsa_raw2}
5551 @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})
5552 @var{key}: a structure that holds the rsa parameters
5554 @var{m}: will hold the modulus
5556 @var{e}: will hold the public exponent
5558 @var{d}: will hold the private exponent
5560 @var{p}: will hold the first prime (p)
5562 @var{q}: will hold the second prime (q)
5564 @var{u}: will hold the coefficient
5566 @var{e1}: will hold e1 = d mod (p-1)
5568 @var{e2}: will hold e2 = d mod (q-1)
5570 This function will export the RSA private key's parameters found
5571 in the given structure. The new parameters will be allocated using
5572 @code{gnutls_malloc()} and will be stored in the appropriate datum.
5574 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5575 negative error value.
5577 @strong{Since:} 2.12.0
5580 @subheading gnutls_x509_privkey_fix
5581 @anchor{gnutls_x509_privkey_fix}
5582 @deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key})
5583 @var{key}: Holds the key
5585 This function will recalculate the secondary parameters in a key.
5586 In RSA keys, this can be the coefficient and exponent1,2.
5588 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5589 negative error value.
5592 @subheading gnutls_x509_privkey_generate
5593 @anchor{gnutls_x509_privkey_generate}
5594 @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})
5595 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5597 @var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .
5599 @var{bits}: the size of the modulus
5601 @var{flags}: unused for now. Must be 0.
5603 This function will generate a random private key. Note that this
5604 function must be called on an empty private key.
5606 Note that when generating an elliptic curve key, the curve
5607 can be substituted in the place of the bits parameter using the
5608 @code{GNUTLS_CURVE_TO_BITS()} macro.
5610 For DSA keys, if the subgroup size needs to be specified check
5611 the @code{GNUTLS_SUBGROUP_TO_BITS()} macro.
5613 Do not set the number of bits directly, use @code{gnutls_sec_param_to_pk_bits()} .
5615 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5616 negative error value.
5619 @subheading gnutls_x509_privkey_get_key_id
5620 @anchor{gnutls_x509_privkey_get_key_id}
5621 @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})
5622 @var{key}: Holds the key
5624 @var{flags}: should be 0 for now
5626 @var{output_data}: will contain the key ID
5628 @var{output_data_size}: holds the size of output_data (and will be
5629 replaced by the actual size of parameters)
5631 This function will return a unique ID that depends on the public key
5632 parameters. This ID can be used in checking whether a certificate
5633 corresponds to the given key.
5635 If the buffer provided is not long enough to hold the output, then
5636 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
5637 be returned. The output will normally be a SHA-1 hash output,
5640 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5641 negative error value.
5644 @subheading gnutls_x509_privkey_get_pk_algorithm
5645 @anchor{gnutls_x509_privkey_get_pk_algorithm}
5646 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key})
5647 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5649 This function will return the public key algorithm of a private
5652 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5653 success, or a negative error code on error.
5656 @subheading gnutls_x509_privkey_get_pk_algorithm2
5657 @anchor{gnutls_x509_privkey_get_pk_algorithm2}
5658 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm2} (gnutls_x509_privkey_t @var{key}, unsigned int * @var{bits})
5659 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5661 @var{bits}: The number of bits in the public key algorithm
5663 This function will return the public key algorithm of a private
5666 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
5667 success, or a negative error code on error.
5670 @subheading gnutls_x509_privkey_import
5671 @anchor{gnutls_x509_privkey_import}
5672 @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})
5673 @var{key}: The structure to store the parsed key
5675 @var{data}: The DER or PEM encoded certificate.
5677 @var{format}: One of DER or PEM
5679 This function will convert the given DER or PEM encoded key to the
5680 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5683 If the key is PEM encoded it should have a header that contains "PRIVATE
5684 KEY". Note that this function falls back to PKCS @code{8} decoding without
5685 password, if the default format fails to import.
5687 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5688 negative error value.
5691 @subheading gnutls_x509_privkey_import2
5692 @anchor{gnutls_x509_privkey_import2}
5693 @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})
5694 @var{key}: The structure to store the parsed key
5696 @var{data}: The DER or PEM encoded key.
5698 @var{format}: One of DER or PEM
5700 @var{password}: A password (optional)
5702 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
5704 This function will import the given DER or PEM encoded key, to
5705 the native @code{gnutls_x509_privkey_t} format, irrespective of the
5706 input format. The input format is auto-detected.
5708 The supported formats are basic unencrypted key, PKCS8, PKCS12,
5709 and the openssl format.
5711 If the provided key is encrypted but no password was given, then
5712 @code{GNUTLS_E_DECRYPTION_FAILED} is returned.
5714 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5715 negative error value.
5718 @subheading gnutls_x509_privkey_import_dsa_raw
5719 @anchor{gnutls_x509_privkey_import_dsa_raw}
5720 @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})
5721 @var{key}: The structure to store the parsed key
5723 @var{p}: holds the p
5725 @var{q}: holds the q
5727 @var{g}: holds the g
5729 @var{y}: holds the y
5731 @var{x}: holds the x
5733 This function will convert the given DSA raw parameters to the
5734 native @code{gnutls_x509_privkey_t} format. The output will be stored
5737 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5738 negative error value.
5741 @subheading gnutls_x509_privkey_import_ecc_raw
5742 @anchor{gnutls_x509_privkey_import_ecc_raw}
5743 @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})
5744 @var{key}: The structure to store the parsed key
5746 @var{curve}: holds the curve
5748 @var{x}: holds the x
5750 @var{y}: holds the y
5752 @var{k}: holds the k
5754 This function will convert the given elliptic curve parameters to the
5755 native @code{gnutls_x509_privkey_t} format. The output will be stored
5758 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5759 negative error value.
5764 @subheading gnutls_x509_privkey_import_openssl
5765 @anchor{gnutls_x509_privkey_import_openssl}
5766 @deftypefun {int} {gnutls_x509_privkey_import_openssl} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, const char * @var{password})
5767 @var{key}: The structure to store the parsed key
5769 @var{data}: The DER or PEM encoded key.
5771 @var{password}: the password to decrypt the key (if it is encrypted).
5773 This function will convert the given PEM encrypted to
5774 the native gnutls_x509_privkey_t format. The
5775 output will be stored in @code{key} .
5777 The @code{password} should be in ASCII. If the password is not provided
5778 or wrong then @code{GNUTLS_E_DECRYPTION_FAILED} will be returned.
5780 If the Certificate is PEM encoded it should have a header of
5781 "PRIVATE KEY" and the "DEK-Info" header.
5783 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5784 negative error value.
5787 @subheading gnutls_x509_privkey_import_pkcs8
5788 @anchor{gnutls_x509_privkey_import_pkcs8}
5789 @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})
5790 @var{key}: The structure to store the parsed key
5792 @var{data}: The DER or PEM encoded key.
5794 @var{format}: One of DER or PEM
5796 @var{password}: the password to decrypt the key (if it is encrypted).
5798 @var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
5800 This function will convert the given DER or PEM encoded PKCS8 2.0
5801 encrypted key to the native gnutls_x509_privkey_t format. The
5802 output will be stored in @code{key} . Both RSA and DSA keys can be
5803 imported, and flags can only be used to indicate an unencrypted
5806 The @code{password} can be either ASCII or UTF-8 in the default PBES2
5807 encryption schemas, or ASCII for the PKCS12 schemas.
5809 If the Certificate is PEM encoded it should have a header of
5810 "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to
5811 specify the flags if the key is DER encoded, since in that case
5812 the encryption status cannot be auto-detected.
5814 If the @code{GNUTLS_PKCS_PLAIN} flag is specified and the supplied data
5815 are encrypted then @code{GNUTLS_E_DECRYPTION_FAILED} is returned.
5817 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5818 negative error value.
5821 @subheading gnutls_x509_privkey_import_rsa_raw
5822 @anchor{gnutls_x509_privkey_import_rsa_raw}
5823 @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})
5824 @var{key}: The structure to store the parsed key
5826 @var{m}: holds the modulus
5828 @var{e}: holds the public exponent
5830 @var{d}: holds the private exponent
5832 @var{p}: holds the first prime (p)
5834 @var{q}: holds the second prime (q)
5836 @var{u}: holds the coefficient
5838 This function will convert the given RSA raw parameters to the
5839 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5842 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5843 negative error value.
5846 @subheading gnutls_x509_privkey_import_rsa_raw2
5847 @anchor{gnutls_x509_privkey_import_rsa_raw2}
5848 @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})
5849 @var{key}: The structure to store the parsed key
5851 @var{m}: holds the modulus
5853 @var{e}: holds the public exponent
5855 @var{d}: holds the private exponent
5857 @var{p}: holds the first prime (p)
5859 @var{q}: holds the second prime (q)
5861 @var{u}: holds the coefficient (optional)
5863 @var{e1}: holds e1 = d mod (p-1) (optional)
5865 @var{e2}: holds e2 = d mod (q-1) (optional)
5867 This function will convert the given RSA raw parameters to the
5868 native @code{gnutls_x509_privkey_t} format. The output will be stored in
5871 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5872 negative error value.
5875 @subheading gnutls_x509_privkey_init
5876 @anchor{gnutls_x509_privkey_init}
5877 @deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key})
5878 @var{key}: The structure to be initialized
5880 This function will initialize an private key structure.
5882 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5883 negative error value.
5886 @subheading gnutls_x509_privkey_sec_param
5887 @anchor{gnutls_x509_privkey_sec_param}
5888 @deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key})
5889 @var{key}: a key structure
5891 This function will return the security parameter appropriate with
5894 @strong{Returns:} On success, a valid security parameter is returned otherwise
5895 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
5897 @strong{Since:} 2.12.0
5900 @subheading gnutls_x509_privkey_verify_params
5901 @anchor{gnutls_x509_privkey_verify_params}
5902 @deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key})
5903 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
5905 This function will verify the private key parameters.
5907 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
5908 negative error value.
5911 @subheading gnutls_x509_rdn_get
5912 @anchor{gnutls_x509_rdn_get}
5913 @deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{buf_size})
5914 @var{idn}: should contain a DER encoded RDN sequence
5916 @var{buf}: a pointer to a structure to hold the peer's name
5918 @var{buf_size}: holds the size of @code{buf}
5920 This function will return the name of the given RDN sequence. The
5921 name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
5924 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5925 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5926 updated if the provided buffer is not long enough, otherwise a
5927 negative error value.
5930 @subheading gnutls_x509_rdn_get_by_oid
5931 @anchor{gnutls_x509_rdn_get_by_oid}
5932 @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})
5933 @var{idn}: should contain a DER encoded RDN sequence
5935 @var{oid}: an Object Identifier
5937 @var{indx}: In case multiple same OIDs exist in the RDN indicates which
5938 to send. Use 0 for the first one.
5940 @var{raw_flag}: If non-zero then the raw DER data are returned.
5942 @var{buf}: a pointer to a structure to hold the peer's name
5944 @var{buf_size}: holds the size of @code{buf}
5946 This function will return the name of the given Object identifier,
5947 of the RDN sequence. The name will be encoded using the rules
5950 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5951 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5952 updated if the provided buffer is not long enough, otherwise a
5953 negative error value.
5956 @subheading gnutls_x509_rdn_get_oid
5957 @anchor{gnutls_x509_rdn_get_oid}
5958 @deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, int @var{indx}, void * @var{buf}, size_t * @var{buf_size})
5959 @var{idn}: should contain a DER encoded RDN sequence
5961 @var{indx}: Indicates which OID to return. Use 0 for the first one.
5963 @var{buf}: a pointer to a structure to hold the peer's name OID
5965 @var{buf_size}: holds the size of @code{buf}
5967 This function will return the specified Object identifier, of the
5970 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
5971 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is
5972 updated if the provided buffer is not long enough, otherwise a
5973 negative error value.
5975 @strong{Since:} 2.4.0
5978 @subheading gnutls_x509_trust_list_add_cas
5979 @anchor{gnutls_x509_trust_list_add_cas}
5980 @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})
5981 @var{list}: The structure of the list
5983 @var{clist}: A list of CAs
5985 @var{clist_size}: The length of the CA list
5987 @var{flags}: should be 0 or an or'ed sequence of @code{GNUTLS_TL} options.
5989 This function will add the given certificate authorities
5990 to the trusted list. The list of CAs must not be deinitialized
5991 during this structure's lifetime.
5993 If the flag @code{GNUTLS_TL_NO_DUPLICATES} is specified, then
5994 the provided @code{clist} entries that are duplicates will not be
5995 added to the list and will be deinitialized.
5997 @strong{Returns:} The number of added elements is returned.
5999 @strong{Since:} 3.0.0
6002 @subheading gnutls_x509_trust_list_add_crls
6003 @anchor{gnutls_x509_trust_list_add_crls}
6004 @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})
6005 @var{list}: The structure of the list
6007 @var{crl_list}: A list of CRLs
6009 @var{crl_size}: The length of the CRL list
6011 @var{flags}: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
6013 @var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6015 This function will add the given certificate revocation lists
6016 to the trusted list. The list of CRLs must not be deinitialized
6017 during this structure's lifetime.
6019 This function must be called after @code{gnutls_x509_trust_list_add_cas()}
6020 to allow verifying the CRLs for validity. If the flag @code{GNUTLS_TL_NO_DUPLICATES}
6021 is given, then any provided CRLs that are a duplicate, will be deinitialized
6022 and not added to the list (that assumes that @code{gnutls_x509_trust_list_deinit()}
6023 will be called with all=1).
6025 @strong{Returns:} The number of added elements is returned.
6030 @subheading gnutls_x509_trust_list_add_named_crt
6031 @anchor{gnutls_x509_trust_list_add_named_crt}
6032 @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})
6033 @var{list}: The structure of the list
6035 @var{cert}: A certificate
6037 @var{name}: An identifier for the certificate
6039 @var{name_size}: The size of the identifier
6041 @var{flags}: should be 0.
6043 This function will add the given certificate to the trusted
6044 list and associate it with a name. The certificate will not be
6045 be used for verification with @code{gnutls_x509_trust_list_verify_crt()}
6046 but only with @code{gnutls_x509_trust_list_verify_named_crt()} .
6048 In principle this function can be used to set individual "server"
6049 certificates that are trusted by the user for that specific server
6050 but for no other purposes.
6052 The certificate must not be deinitialized during the lifetime
6053 of the trusted list.
6055 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6056 negative error value.
6058 @strong{Since:} 3.0.0
6061 @subheading gnutls_x509_trust_list_add_system_trust
6062 @anchor{gnutls_x509_trust_list_add_system_trust}
6063 @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})
6064 @var{list}: The structure of the list
6066 @var{tl_flags}: GNUTLS_TL_*
6068 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6070 This function adds the system's default trusted certificate
6071 authorities to the trusted list. Note that on unsupported systems
6072 this function returns @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .
6074 This function implies the flag @code{GNUTLS_TL_NO_DUPLICATES} .
6076 @strong{Returns:} The number of added elements or a negative error code on error.
6081 @subheading gnutls_x509_trust_list_add_trust_dir
6082 @anchor{gnutls_x509_trust_list_add_trust_dir}
6083 @deftypefun {int} {gnutls_x509_trust_list_add_trust_dir} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_dir}, const char * @var{crl_dir}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags})
6084 @var{list}: The structure of the list
6086 @var{ca_dir}: A directory containing the CAs (optional)
6088 @var{crl_dir}: A directory containing a list of CRLs (optional)
6090 @var{type}: The format of the certificates
6092 @var{tl_flags}: GNUTLS_TL_*
6094 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6096 This function will add the given certificate authorities
6097 to the trusted list. Only directories are accepted by
6100 @strong{Returns:} The number of added elements is returned.
6102 @strong{Since:} 3.3.6
6105 @subheading gnutls_x509_trust_list_add_trust_file
6106 @anchor{gnutls_x509_trust_list_add_trust_file}
6107 @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})
6108 @var{list}: The structure of the list
6110 @var{ca_file}: A file containing a list of CAs (optional)
6112 @var{crl_file}: A file containing a list of CRLs (optional)
6114 @var{type}: The format of the certificates
6116 @var{tl_flags}: GNUTLS_TL_*
6118 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6120 This function will add the given certificate authorities
6121 to the trusted list. PKCS @code{11} URLs are also accepted, instead
6122 of files, by this function. A PKCS @code{11} URL implies a trust
6123 database (a specially marked module in p11-kit); the URL "pkcs11:"
6124 implies all trust databases in the system. Only a single URL specifying
6125 trust databases can be set; they cannot be stacked with multiple calls.
6127 @strong{Returns:} The number of added elements is returned.
6132 @subheading gnutls_x509_trust_list_add_trust_mem
6133 @anchor{gnutls_x509_trust_list_add_trust_mem}
6134 @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})
6135 @var{list}: The structure of the list
6137 @var{cas}: A buffer containing a list of CAs (optional)
6139 @var{crls}: A buffer containing a list of CRLs (optional)
6141 @var{type}: The format of the certificates
6143 @var{tl_flags}: GNUTLS_TL_*
6145 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
6147 This function will add the given certificate authorities
6148 to the trusted list.
6150 @strong{Returns:} The number of added elements is returned.
6155 @subheading gnutls_x509_trust_list_deinit
6156 @anchor{gnutls_x509_trust_list_deinit}
6157 @deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all})
6158 @var{list}: The structure to be deinitialized
6160 @var{all}: if non-zero it will deinitialize all the certificates and CRLs contained in the structure.
6162 This function will deinitialize a trust list. Note that the
6163 @code{all} flag should be typically non-zero unless you have specified
6164 your certificates using @code{gnutls_x509_trust_list_add_cas()} and you
6165 want to prevent them from being deinitialized by this function.
6167 @strong{Since:} 3.0.0
6170 @subheading gnutls_x509_trust_list_get_issuer
6171 @anchor{gnutls_x509_trust_list_get_issuer}
6172 @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})
6173 @var{list}: The structure of the list
6175 @var{cert}: is the certificate to find issuer for
6177 @var{issuer}: Will hold the issuer if any. Should be treated as constant.
6179 @var{flags}: Use zero or @code{GNUTLS_TL_GET_COPY}
6181 This function will find the issuer of the given certificate.
6182 If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer
6183 will be returned which must be freed using @code{gnutls_x509_crt_deinit()} .
6184 Note that the flag @code{GNUTLS_TL_GET_COPY} is required for this function
6185 to work with PKCS @code{11} trust lists in a thread-safe way.
6187 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6188 negative error value.
6193 @subheading gnutls_x509_trust_list_init
6194 @anchor{gnutls_x509_trust_list_init}
6195 @deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size})
6196 @var{list}: The structure to be initialized
6198 @var{size}: The size of the internal hash table. Use (0) for default size.
6200 This function will initialize an X.509 trust list structure.
6202 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6203 negative error value.
6205 @strong{Since:} 3.0.0
6208 @subheading gnutls_x509_trust_list_remove_cas
6209 @anchor{gnutls_x509_trust_list_remove_cas}
6210 @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})
6211 @var{list}: The structure of the list
6213 @var{clist}: A list of CAs
6215 @var{clist_size}: The length of the CA list
6217 This function will remove the given certificate authorities
6218 from the trusted list.
6220 Note that this function can accept certificates and authorities
6221 not yet known. In that case they will be kept in a separate
6222 black list that will be used during certificate verification.
6223 Unlike @code{gnutls_x509_trust_list_add_cas()} there is no deinitialization
6224 restriction for certificate list provided in this function.
6226 @strong{Returns:} The number of removed elements is returned.
6228 @strong{Since:} 3.1.10
6231 @subheading gnutls_x509_trust_list_remove_trust_file
6232 @anchor{gnutls_x509_trust_list_remove_trust_file}
6233 @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})
6234 @var{list}: The structure of the list
6236 @var{ca_file}: A file containing a list of CAs
6238 @var{type}: The format of the certificates
6240 This function will remove the given certificate authorities
6241 from the trusted list, and add them into a black list when needed.
6242 PKCS 11 URLs are also accepted, instead
6243 of files, by this function.
6245 See also @code{gnutls_x509_trust_list_remove_cas()} .
6247 @strong{Returns:} The number of added elements is returned.
6249 @strong{Since:} 3.1.10
6252 @subheading gnutls_x509_trust_list_remove_trust_mem
6253 @anchor{gnutls_x509_trust_list_remove_trust_mem}
6254 @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})
6255 @var{list}: The structure of the list
6257 @var{cas}: A buffer containing a list of CAs (optional)
6259 @var{type}: The format of the certificates
6261 This function will remove the provided certificate authorities
6262 from the trusted list, and add them into a black list when needed.
6264 See also @code{gnutls_x509_trust_list_remove_cas()} .
6266 @strong{Returns:} The number of removed elements is returned.
6268 @strong{Since:} 3.1.10
6271 @subheading gnutls_x509_trust_list_verify_crt
6272 @anchor{gnutls_x509_trust_list_verify_crt}
6273 @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})
6274 @var{list}: The structure of the list
6276 @var{cert_list}: is the certificate list to be verified
6278 @var{cert_list_size}: is the certificate list size
6280 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6282 @var{voutput}: will hold the certificate verification output.
6284 @var{func}: If non-null will be called on each chain element verification with the output.
6286 This function will try to verify the given certificate and return
6287 its status. The @code{verify} parameter will hold an OR'ed sequence of
6288 @code{gnutls_certificate_status_t} flags.
6290 Additionally a certificate verification profile can be specified
6291 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6292 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6295 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6296 negative error value.
6301 @subheading gnutls_x509_trust_list_verify_crt2
6302 @anchor{gnutls_x509_trust_list_verify_crt2}
6303 @deftypefun {int} {gnutls_x509_trust_list_verify_crt2} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t * @var{cert_list}, unsigned int @var{cert_list_size}, gnutls_typed_vdata_st * @var{data}, unsigned int @var{elements}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func})
6304 @var{list}: The structure of the list
6306 @var{cert_list}: is the certificate list to be verified
6308 @var{cert_list_size}: is the certificate list size
6310 @var{data}: an array of typed data
6312 @var{elements}: the number of data elements
6314 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6316 @var{voutput}: will hold the certificate verification output.
6318 @var{func}: If non-null will be called on each chain element verification with the output.
6320 This function will try to verify the given certificate and return
6321 its status. The @code{verify} parameter will hold an OR'ed sequence of
6322 @code{gnutls_certificate_status_t} flags.
6324 Additionally a certificate verification profile can be specified
6325 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6326 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6329 The acceptable @code{data} types are @code{GNUTLS_DT_DNS_HOSTNAME} and @code{GNUTLS_DT_KEY_PURPOSE_OID} .
6330 The former accepts as data a null-terminated hostname, and the latter a null-terminated
6331 object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ).
6332 If a DNS hostname is provided then this function will compare
6333 the hostname in the certificate against the given. If names do not match the
6334 @code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set.
6335 If a key purpose OID is provided and the end-certificate contains the extended key
6336 usage PKIX extension, it will be required to be have the provided key purpose
6337 or be marked for any purpose, otherwise verification will fail with @code{GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE} status.
6339 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6340 negative error value. Note that verification failure will not result to an
6341 error code, only @code{voutput} will be updated.
6343 @strong{Since:} 3.3.8
6346 @subheading gnutls_x509_trust_list_verify_named_crt
6347 @anchor{gnutls_x509_trust_list_verify_named_crt}
6348 @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})
6349 @var{list}: The structure of the list
6351 @var{cert}: is the certificate to be verified
6353 @var{name}: is the certificate's name
6355 @var{name_size}: is the certificate's name size
6357 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
6359 @var{voutput}: will hold the certificate verification output.
6361 @var{func}: If non-null will be called on each chain element verification with the output.
6363 This function will try to find a certificate that is associated with the provided
6364 name --see @code{gnutls_x509_trust_list_add_named_crt()} . If a match is found the certificate is considered valid.
6365 In addition to that this function will also check CRLs.
6366 The @code{voutput} parameter will hold an OR'ed sequence of @code{gnutls_certificate_status_t} flags.
6368 Additionally a certificate verification profile can be specified
6369 from the ones in @code{gnutls_certificate_verification_profiles_t} by
6370 ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification
6373 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
6374 negative error value.
6376 @strong{Since:} 3.0.0