2 @subheading gnutls_pkcs7_deinit
3 @anchor{gnutls_pkcs7_deinit}
4 @deftypefun {void} {gnutls_pkcs7_deinit} (gnutls_pkcs7_t @var{pkcs7})
5 @var{pkcs7}: The structure to be initialized
7 This function will deinitialize a PKCS7 structure.
10 @subheading gnutls_pkcs7_delete_crl
11 @anchor{gnutls_pkcs7_delete_crl}
12 @deftypefun {int} {gnutls_pkcs7_delete_crl} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
13 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
15 @var{indx}: the index of the crl to delete
17 This function will delete a crl from a PKCS7 or RFC2630 crl set.
18 Index starts from 0. Returns 0 on success.
20 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
24 @subheading gnutls_pkcs7_delete_crt
25 @anchor{gnutls_pkcs7_delete_crt}
26 @deftypefun {int} {gnutls_pkcs7_delete_crt} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
27 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
29 @var{indx}: the index of the certificate to delete
31 This function will delete a certificate from a PKCS7 or RFC2630
32 certificate set. Index starts from 0. Returns 0 on success.
34 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
38 @subheading gnutls_pkcs7_export
39 @anchor{gnutls_pkcs7_export}
40 @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})
41 @var{pkcs7}: Holds the pkcs7 structure
43 @var{format}: the format of output params. One of PEM or DER.
45 @var{output_data}: will contain a structure PEM or DER encoded
47 @var{output_data_size}: holds the size of output_data (and will be
48 replaced by the actual size of parameters)
50 This function will export the pkcs7 structure to DER or PEM format.
52 If the buffer provided is not long enough to hold the output, then
53 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
56 If the structure is PEM encoded, it will have a header
59 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
63 @subheading gnutls_pkcs7_get_crl_count
64 @anchor{gnutls_pkcs7_get_crl_count}
65 @deftypefun {int} {gnutls_pkcs7_get_crl_count} (gnutls_pkcs7_t @var{pkcs7})
66 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
68 This function will return the number of certifcates in the PKCS7
71 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
75 @subheading gnutls_pkcs7_get_crl_raw
76 @anchor{gnutls_pkcs7_get_crl_raw}
77 @deftypefun {int} {gnutls_pkcs7_get_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{crl}, size_t * @var{crl_size})
78 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
80 @var{indx}: contains the index of the crl to extract
82 @var{crl}: the contents of the crl will be copied there (may be null)
84 @var{crl_size}: should hold the size of the crl
86 This function will return a crl of the PKCS7 or RFC2630 crl set.
88 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
89 negative error value. If the provided buffer is not long enough,
90 then @code{crl_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is
91 returned. After the last crl has been read
92 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
95 @subheading gnutls_pkcs7_get_crt_count
96 @anchor{gnutls_pkcs7_get_crt_count}
97 @deftypefun {int} {gnutls_pkcs7_get_crt_count} (gnutls_pkcs7_t @var{pkcs7})
98 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
100 This function will return the number of certifcates in the PKCS7
101 or RFC2630 certificate set.
103 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
104 negative error value.
107 @subheading gnutls_pkcs7_get_crt_raw
108 @anchor{gnutls_pkcs7_get_crt_raw}
109 @deftypefun {int} {gnutls_pkcs7_get_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{certificate}, size_t * @var{certificate_size})
110 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
112 @var{indx}: contains the index of the certificate to extract
114 @var{certificate}: the contents of the certificate will be copied
117 @var{certificate_size}: should hold the size of the certificate
119 This function will return a certificate of the PKCS7 or RFC2630
122 After the last certificate has been read
123 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
125 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
126 negative error value. If the provided buffer is not long enough,
127 then @code{certificate_size} is updated and
128 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned.
131 @subheading gnutls_pkcs7_import
132 @anchor{gnutls_pkcs7_import}
133 @deftypefun {int} {gnutls_pkcs7_import} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
134 @var{pkcs7}: The structure to store the parsed PKCS7.
136 @var{data}: The DER or PEM encoded PKCS7.
138 @var{format}: One of DER or PEM
140 This function will convert the given DER or PEM encoded PKCS7 to
141 the native @code{gnutls_pkcs7_t} format. The output will be stored in
144 If the PKCS7 is PEM encoded it should have a header of "PKCS7".
146 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
147 negative error value.
150 @subheading gnutls_pkcs7_init
151 @anchor{gnutls_pkcs7_init}
152 @deftypefun {int} {gnutls_pkcs7_init} (gnutls_pkcs7_t * @var{pkcs7})
153 @var{pkcs7}: The structure to be initialized
155 This function will initialize a PKCS7 structure. PKCS7 structures
156 usually contain lists of X.509 Certificates and X.509 Certificate
159 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
160 negative error value.
163 @subheading gnutls_pkcs7_set_crl
164 @anchor{gnutls_pkcs7_set_crl}
165 @deftypefun {int} {gnutls_pkcs7_set_crl} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crl_t @var{crl})
166 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
168 @var{crl}: the DER encoded crl to be added
170 This function will add a parsed CRL to the PKCS7 or RFC2630 crl
173 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
174 negative error value.
177 @subheading gnutls_pkcs7_set_crl_raw
178 @anchor{gnutls_pkcs7_set_crl_raw}
179 @deftypefun {int} {gnutls_pkcs7_set_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crl})
180 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
182 @var{crl}: the DER encoded crl to be added
184 This function will add a crl to the PKCS7 or RFC2630 crl set.
186 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
187 negative error value.
190 @subheading gnutls_pkcs7_set_crt
191 @anchor{gnutls_pkcs7_set_crt}
192 @deftypefun {int} {gnutls_pkcs7_set_crt} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crt_t @var{crt})
193 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
195 @var{crt}: the certificate to be copied.
197 This function will add a parsed certificate to the PKCS7 or
198 RFC2630 certificate set. This is a wrapper function over
199 @code{gnutls_pkcs7_set_crt_raw()} .
201 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
202 negative error value.
205 @subheading gnutls_pkcs7_set_crt_raw
206 @anchor{gnutls_pkcs7_set_crt_raw}
207 @deftypefun {int} {gnutls_pkcs7_set_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crt})
208 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
210 @var{crt}: the DER encoded certificate to be added
212 This function will add a certificate to the PKCS7 or RFC2630
215 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
216 negative error value.
219 @subheading gnutls_x509_crl_check_issuer
220 @anchor{gnutls_x509_crl_check_issuer}
221 @deftypefun {int} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer})
222 @var{crl}: is the CRL to be checked
224 @var{issuer}: is the certificate of a possible issuer
226 This function will check if the given CRL was issued by the given
227 issuer certificate. It will return true (1) if the given CRL was
228 issued by the given issuer, and false (0) if not.
230 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
231 negative error value.
234 @subheading gnutls_x509_crl_deinit
235 @anchor{gnutls_x509_crl_deinit}
236 @deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl})
237 @var{crl}: The structure to be initialized
239 This function will deinitialize a CRL structure.
242 @subheading gnutls_x509_crl_export
243 @anchor{gnutls_x509_crl_export}
244 @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})
245 @var{crl}: Holds the revocation list
247 @var{format}: the format of output params. One of PEM or DER.
249 @var{output_data}: will contain a private key PEM or DER encoded
251 @var{output_data_size}: holds the size of output_data (and will
252 be replaced by the actual size of parameters)
254 This function will export the revocation list to DER or PEM format.
256 If the buffer provided is not long enough to hold the output, then
257 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
259 If the structure is PEM encoded, it will have a header
262 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
263 negative error value. and a negative error code on failure.
266 @subheading gnutls_x509_crl_get_authority_key_gn_serial
267 @anchor{gnutls_x509_crl_get_authority_key_gn_serial}
268 @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})
269 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
271 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
273 @var{alt}: is the place where the alternative name will be copied to
275 @var{alt_size}: holds the size of alt.
277 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
279 @var{serial}: buffer to store the serial number (may be null)
281 @var{serial_size}: Holds the size of the serial field (may be null)
283 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
285 This function will return the X.509 authority key
286 identifier when stored as a general name (authorityCertIssuer)
289 Because more than one general names might be stored
290 @code{seq} can be used as a counter to request them all until
291 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
293 @strong{Returns:} Returns 0 on success, or an error code.
298 @subheading gnutls_x509_crl_get_authority_key_id
299 @anchor{gnutls_x509_crl_get_authority_key_id}
300 @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})
301 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
303 @var{id}: The place where the identifier will be copied
305 @var{id_size}: Holds the size of the result field.
307 @var{critical}: will be non (0) if the extension is marked as critical
310 This function will return the CRL authority's key identifier. This
311 is obtained by the X.509 Authority Key identifier extension field
312 (2.5.29.35). Note that this function
313 only returns the keyIdentifier field of the extension and
314 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
315 the name and serial number of the certificate. In that case
316 @code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used.
318 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
319 negative error code in case of an error.
321 @strong{Since:} 2.8.0
324 @subheading gnutls_x509_crl_get_crt_count
325 @anchor{gnutls_x509_crl_get_crt_count}
326 @deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl})
327 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
329 This function will return the number of revoked certificates in the
332 @strong{Returns:} number of certificates, a negative error code on failure.
335 @subheading gnutls_x509_crl_get_crt_serial
336 @anchor{gnutls_x509_crl_get_crt_serial}
337 @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})
338 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
340 @var{indx}: the index of the certificate to extract (starting from 0)
342 @var{serial}: where the serial number will be copied
344 @var{serial_size}: initially holds the size of serial
346 @var{t}: if non null, will hold the time this certificate was revoked
348 This function will retrieve the serial number of the specified, by
349 the index, revoked certificate.
351 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
352 negative error value. and a negative error code on error.
355 @subheading gnutls_x509_crl_get_dn_oid
356 @anchor{gnutls_x509_crl_get_dn_oid}
357 @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})
358 @var{crl}: should contain a gnutls_x509_crl_t structure
360 @var{indx}: Specifies which DN OID to send. Use (0) to get the first one.
362 @var{oid}: a pointer to a structure to hold the name (may be null)
364 @var{sizeof_oid}: initially holds the size of 'oid'
366 This function will extract the requested OID of the name of the CRL
367 issuer, specified by the given index.
369 If oid is null then only the size will be filled.
371 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
372 not long enough, and in that case the sizeof_oid will be updated
373 with the required size. On success 0 is returned.
376 @subheading gnutls_x509_crl_get_extension_data
377 @anchor{gnutls_x509_crl_get_extension_data}
378 @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})
379 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
381 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
383 @var{data}: a pointer to a structure to hold the data (may be null)
385 @var{sizeof_data}: initially holds the size of @code{oid}
387 This function will return the requested extension data in the CRL.
388 The extension data will be stored as a string in the provided
391 Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and
392 critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead,
393 if you want to get data indexed by the extension OID rather than
396 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
397 negative error code in case of an error. If your have reached the
398 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
401 @strong{Since:} 2.8.0
404 @subheading gnutls_x509_crl_get_extension_info
405 @anchor{gnutls_x509_crl_get_extension_info}
406 @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})
407 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
409 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
411 @var{oid}: a pointer to a structure to hold the OID
413 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
414 holds actual size of @code{oid} .
416 @var{critical}: output variable with critical flag, may be NULL.
418 This function will return the requested extension OID in the CRL,
419 and the critical flag for it. The extension OID will be stored as
420 a string in the provided buffer. Use
421 @code{gnutls_x509_crl_get_extension_data()} to extract the data.
423 If the buffer provided is not long enough to hold the output, then
424 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
427 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
428 negative error code in case of an error. If your have reached the
429 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
432 @strong{Since:} 2.8.0
435 @subheading gnutls_x509_crl_get_extension_oid
436 @anchor{gnutls_x509_crl_get_extension_oid}
437 @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})
438 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
440 @var{indx}: Specifies which extension OID to send, use (0) to get the first one.
442 @var{oid}: a pointer to a structure to hold the OID (may be null)
444 @var{sizeof_oid}: initially holds the size of @code{oid}
446 This function will return the requested extension OID in the CRL.
447 The extension OID will be stored as a string in the provided
450 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
451 negative error code in case of an error. If your have reached the
452 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
455 @strong{Since:} 2.8.0
458 @subheading gnutls_x509_crl_get_issuer_dn
459 @anchor{gnutls_x509_crl_get_issuer_dn}
460 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (const gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf})
461 @var{crl}: should contain a gnutls_x509_crl_t structure
463 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
465 @var{sizeof_buf}: initially holds the size of @code{buf}
467 This function will copy the name of the CRL issuer in the provided
468 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
469 described in RFC4514. The output string will be ASCII or UTF-8
470 encoded, depending on the certificate data.
472 If buf is @code{NULL} then only the size will be filled.
474 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
475 not long enough, and in that case the sizeof_buf will be updated
476 with the required size, and 0 on success.
479 @subheading gnutls_x509_crl_get_issuer_dn_by_oid
480 @anchor{gnutls_x509_crl_get_issuer_dn_by_oid}
481 @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})
482 @var{crl}: should contain a gnutls_x509_crl_t structure
484 @var{oid}: holds an Object Identified in null terminated string
486 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
488 @var{raw_flag}: If non (0) returns the raw DER data of the DN part.
490 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
492 @var{sizeof_buf}: initially holds the size of @code{buf}
494 This function will extract the part of the name of the CRL issuer
495 specified by the given OID. The output will be encoded as described
496 in RFC4514. The output string will be ASCII or UTF-8 encoded,
497 depending on the certificate data.
499 Some helper macros with popular OIDs can be found in gnutls/x509.h
500 If raw flag is (0), this function will only return known OIDs as
501 text. Other OIDs will be DER encoded, as described in RFC4514 -- in
502 hex format with a '#' prefix. You can check about known OIDs
503 using @code{gnutls_x509_dn_oid_known()} .
505 If buf is null then only the size will be filled.
507 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
508 not long enough, and in that case the sizeof_buf will be updated
509 with the required size, and 0 on success.
512 @subheading gnutls_x509_crl_get_next_update
513 @anchor{gnutls_x509_crl_get_next_update}
514 @deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl})
515 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
517 This function will return the time the next CRL will be issued.
518 This field is optional in a CRL so it might be normal to get an
521 @strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error.
524 @subheading gnutls_x509_crl_get_number
525 @anchor{gnutls_x509_crl_get_number}
526 @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})
527 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
529 @var{ret}: The place where the number will be copied
531 @var{ret_size}: Holds the size of the result field.
533 @var{critical}: will be non (0) if the extension is marked as critical
536 This function will return the CRL number extension. This is
537 obtained by the CRL Number extension field (2.5.29.20).
539 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
540 negative error code in case of an error.
542 @strong{Since:} 2.8.0
545 @subheading gnutls_x509_crl_get_raw_issuer_dn
546 @anchor{gnutls_x509_crl_get_raw_issuer_dn}
547 @deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
548 @var{crl}: should contain a gnutls_x509_crl_t structure
550 @var{dn}: will hold the starting point of the DN
552 This function will return a pointer to the DER encoded DN structure
555 @strong{Returns:} a negative error code on error, and (0) on success.
557 @strong{Since:} 2.12.0
560 @subheading gnutls_x509_crl_get_signature
561 @anchor{gnutls_x509_crl_get_signature}
562 @deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig})
563 @var{crl}: should contain a gnutls_x509_crl_t structure
565 @var{sig}: a pointer where the signature part will be copied (may be null).
567 @var{sizeof_sig}: initially holds the size of @code{sig}
569 This function will extract the signature field of a CRL.
571 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
572 negative error value. and a negative error code on error.
575 @subheading gnutls_x509_crl_get_signature_algorithm
576 @anchor{gnutls_x509_crl_get_signature_algorithm}
577 @deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl})
578 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
580 This function will return a value of the @code{gnutls_sign_algorithm_t}
581 enumeration that is the signature algorithm.
583 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
584 negative error value.
587 @subheading gnutls_x509_crl_get_this_update
588 @anchor{gnutls_x509_crl_get_this_update}
589 @deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl})
590 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
592 This function will return the time this CRL was issued.
594 @strong{Returns:} when the CRL was issued, or (time_t)-1 on error.
597 @subheading gnutls_x509_crl_get_version
598 @anchor{gnutls_x509_crl_get_version}
599 @deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl})
600 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
602 This function will return the version of the specified CRL.
604 @strong{Returns:} The version number, or a negative error code on error.
607 @subheading gnutls_x509_crl_import
608 @anchor{gnutls_x509_crl_import}
609 @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})
610 @var{crl}: The structure to store the parsed CRL.
612 @var{data}: The DER or PEM encoded CRL.
614 @var{format}: One of DER or PEM
616 This function will convert the given DER or PEM encoded CRL
617 to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'.
619 If the CRL is PEM encoded it should have a header of "X509 CRL".
621 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
622 negative error value.
625 @subheading gnutls_x509_crl_init
626 @anchor{gnutls_x509_crl_init}
627 @deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl})
628 @var{crl}: The structure to be initialized
630 This function will initialize a CRL structure. CRL stands for
631 Certificate Revocation List. A revocation list usually contains
632 lists of certificate serial numbers that have been revoked by an
633 Authority. The revocation lists are always signed with the
634 authority's private key.
636 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
637 negative error value.
640 @subheading gnutls_x509_crl_list_import
641 @anchor{gnutls_x509_crl_list_import}
642 @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})
643 @var{crls}: The structures to store the parsed CRLs. Must not be initialized.
645 @var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available.
647 @var{data}: The PEM encoded CRLs
649 @var{format}: One of DER or PEM.
651 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
653 This function will convert the given PEM encoded CRL list
654 to the native gnutls_x509_crl_t format. The output will be stored
655 in @code{crls} . They will be automatically initialized.
657 If the Certificate is PEM encoded it should have a header of "X509 CRL".
659 @strong{Returns:} the number of certificates read or a negative error value.
664 @subheading gnutls_x509_crl_list_import2
665 @anchor{gnutls_x509_crl_list_import2}
666 @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})
667 @var{crls}: The structures to store the parsed crl list. Must not be initialized.
669 @var{size}: It will contain the size of the list.
671 @var{data}: The PEM encoded CRL.
673 @var{format}: One of DER or PEM.
675 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
677 This function will convert the given PEM encoded CRL list
678 to the native gnutls_x509_crl_t format. The output will be stored
679 in @code{crls} . They will be automatically initialized.
681 If the Certificate is PEM encoded it should have a header of "X509
684 @strong{Returns:} the number of certificates read or a negative error value.
689 @subheading gnutls_x509_crl_print
690 @anchor{gnutls_x509_crl_print}
691 @deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
692 @var{crl}: The structure to be printed
694 @var{format}: Indicate the format to use
696 @var{out}: Newly allocated datum with (0) terminated string.
698 This function will pretty print a X.509 certificate revocation
699 list, suitable for display to a human.
701 The output @code{out} needs to be deallocate using @code{gnutls_free()} .
703 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
704 negative error value.
707 @subheading gnutls_x509_crl_set_authority_key_id
708 @anchor{gnutls_x509_crl_set_authority_key_id}
709 @deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size})
710 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
714 @var{id_size}: Holds the size of the serial field.
716 This function will set the CRL's authority key ID extension. Only
717 the keyIdentifier field can be set with this function. This may
718 be used by an authority that holds multiple private keys, to distinguish
721 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
722 negative error value.
724 @strong{Since:} 2.8.0
727 @subheading gnutls_x509_crl_set_crt
728 @anchor{gnutls_x509_crl_set_crt}
729 @deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time})
730 @var{crl}: should contain a gnutls_x509_crl_t structure
732 @var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate
734 @var{revocation_time}: The time this certificate was revoked
736 This function will set a revoked certificate's serial number to the CRL.
738 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
739 negative error value.
742 @subheading gnutls_x509_crl_set_crt_serial
743 @anchor{gnutls_x509_crl_set_crt_serial}
744 @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})
745 @var{crl}: should contain a gnutls_x509_crl_t structure
747 @var{serial}: The revoked certificate's serial number
749 @var{serial_size}: Holds the size of the serial field.
751 @var{revocation_time}: The time this certificate was revoked
753 This function will set a revoked certificate's serial number to the CRL.
755 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
756 negative error value.
759 @subheading gnutls_x509_crl_set_next_update
760 @anchor{gnutls_x509_crl_set_next_update}
761 @deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time})
762 @var{crl}: should contain a gnutls_x509_crl_t structure
764 @var{exp_time}: The actual time
766 This function will set the time this CRL will be updated.
768 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
769 negative error value.
772 @subheading gnutls_x509_crl_set_number
773 @anchor{gnutls_x509_crl_set_number}
774 @deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size})
775 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
777 @var{nr}: The CRL number
779 @var{nr_size}: Holds the size of the nr field.
781 This function will set the CRL's number extension. This
782 is to be used as a unique and monotonic number assigned to
783 the CRL by the authority.
785 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
786 negative error value.
788 @strong{Since:} 2.8.0
791 @subheading gnutls_x509_crl_set_this_update
792 @anchor{gnutls_x509_crl_set_this_update}
793 @deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time})
794 @var{crl}: should contain a gnutls_x509_crl_t structure
796 @var{act_time}: The actual time
798 This function will set the time this CRL was issued.
800 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
801 negative error value.
804 @subheading gnutls_x509_crl_set_version
805 @anchor{gnutls_x509_crl_set_version}
806 @deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version})
807 @var{crl}: should contain a gnutls_x509_crl_t structure
809 @var{version}: holds the version number. For CRLv1 crls must be 1.
811 This function will set the version of the CRL. This
812 must be one for CRL version 1, and so on. The CRLs generated
813 by gnutls should have a version number of 2.
815 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
816 negative error value.
819 @subheading gnutls_x509_crl_sign2
820 @anchor{gnutls_x509_crl_sign2}
821 @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})
822 @var{crl}: should contain a gnutls_x509_crl_t structure
824 @var{issuer}: is the certificate of the certificate issuer
826 @var{issuer_key}: holds the issuer's private key
828 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
830 @var{flags}: must be 0
832 This function will sign the CRL with the issuer's private key, and
833 will copy the issuer's information into the CRL.
835 This must be the last step in a certificate CRL since all
836 the previously set parameters are now signed.
838 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
839 negative error value.
842 @subheading gnutls_x509_crl_verify
843 @anchor{gnutls_x509_crl_verify}
844 @deftypefun {int} {gnutls_x509_crl_verify} (gnutls_x509_crl_t @var{crl}, const gnutls_x509_crt_t * @var{CA_list}, int @var{CA_list_length}, unsigned int @var{flags}, unsigned int * @var{verify})
845 @var{crl}: is the crl to be verified
847 @var{CA_list}: is a certificate list that is considered to be trusted one
849 @var{CA_list_length}: holds the number of CA certificates in CA_list
851 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
853 @var{verify}: will hold the crl verification output.
855 This function will try to verify the given crl and return its status.
856 See @code{gnutls_x509_crt_list_verify()} for a detailed description of
859 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
860 negative error value.
863 @subheading gnutls_x509_crq_deinit
864 @anchor{gnutls_x509_crq_deinit}
865 @deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq})
866 @var{crq}: The structure to be initialized
868 This function will deinitialize a PKCS@code{10} certificate request
872 @subheading gnutls_x509_crq_export
873 @anchor{gnutls_x509_crq_export}
874 @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})
875 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
877 @var{format}: the format of output params. One of PEM or DER.
879 @var{output_data}: will contain a certificate request PEM or DER encoded
881 @var{output_data_size}: holds the size of output_data (and will be
882 replaced by the actual size of parameters)
884 This function will export the certificate request to a PEM or DER
885 encoded PKCS10 structure.
887 If the buffer provided is not long enough to hold the output, then
888 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and
889 * @code{output_data_size} will be updated.
891 If the structure is PEM encoded, it will have a header of "BEGIN
892 NEW CERTIFICATE REQUEST".
894 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
895 negative error value.
898 @subheading gnutls_x509_crq_get_attribute_by_oid
899 @anchor{gnutls_x509_crq_get_attribute_by_oid}
900 @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{sizeof_buf})
901 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
903 @var{oid}: holds an Object Identified in (0)-terminated string
905 @var{indx}: In case multiple same OIDs exist in the attribute list, this
906 specifies which to send, use (0) to get the first one
908 @var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} )
910 @var{sizeof_buf}: initially holds the size of @code{buf}
912 This function will return the attribute in the certificate request
913 specified by the given Object ID. The attribute will be DER
916 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
917 negative error value.
920 @subheading gnutls_x509_crq_get_attribute_data
921 @anchor{gnutls_x509_crq_get_attribute_data}
922 @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})
923 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
925 @var{indx}: Specifies which attribute OID to send. Use (0) to get the first one.
927 @var{data}: a pointer to a structure to hold the data (may be null)
929 @var{sizeof_data}: initially holds the size of @code{oid}
931 This function will return the requested attribute data in the
932 certificate request. The attribute data will be stored as a string in the
935 Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID.
936 Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead,
937 if you want to get data indexed by the attribute OID rather than
940 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
941 negative error code in case of an error. If your have reached the
942 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
945 @strong{Since:} 2.8.0
948 @subheading gnutls_x509_crq_get_attribute_info
949 @anchor{gnutls_x509_crq_get_attribute_info}
950 @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})
951 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
953 @var{indx}: Specifies which attribute OID to send. Use (0) to get the first one.
955 @var{oid}: a pointer to a structure to hold the OID
957 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
958 holds actual size of @code{oid} .
960 This function will return the requested attribute OID in the
961 certificate, and the critical flag for it. The attribute OID will
962 be stored as a string in the provided buffer. Use
963 @code{gnutls_x509_crq_get_attribute_data()} to extract the data.
965 If the buffer provided is not long enough to hold the output, then
966 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
969 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
970 negative error code in case of an error. If your have reached the
971 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
974 @strong{Since:} 2.8.0
977 @subheading gnutls_x509_crq_get_basic_constraints
978 @anchor{gnutls_x509_crq_get_basic_constraints}
979 @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})
980 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
982 @var{critical}: will be non (0) if the extension is marked as critical
984 @var{ca}: pointer to output integer indicating CA status, may be NULL,
985 value is 1 if the certificate CA flag is set, 0 otherwise.
987 @var{pathlen}: pointer to output integer indicating path length (may be
988 NULL), non-negative error codes indicate a present pathLenConstraint
989 field and the actual value, -1 indicate that the field is absent.
991 This function will read the certificate's basic constraints, and
992 return the certificates CA status. It reads the basicConstraints
993 X.509 extension (2.5.29.19).
995 @strong{Returns:} If the certificate is a CA a positive value will be
996 returned, or (0) if the certificate does not have CA flag set.
997 A negative error code may be returned in case of errors. If the
998 certificate does not contain the basicConstraints extension
999 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1001 @strong{Since:} 2.8.0
1004 @subheading gnutls_x509_crq_get_challenge_password
1005 @anchor{gnutls_x509_crq_get_challenge_password}
1006 @deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{sizeof_pass})
1007 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1009 @var{pass}: will hold a (0)-terminated password string
1011 @var{sizeof_pass}: Initially holds the size of @code{pass} .
1013 This function will return the challenge password in the request.
1014 The challenge password is intended to be used for requesting a
1015 revocation of the certificate.
1017 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1018 negative error value.
1021 @subheading gnutls_x509_crq_get_dn
1022 @anchor{gnutls_x509_crq_get_dn}
1023 @deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{sizeof_buf})
1024 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1026 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1028 @var{sizeof_buf}: initially holds the size of @code{buf}
1030 This function will copy the name of the Certificate request subject
1031 to the provided buffer. The name will be in the form
1032 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
1033 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate
1036 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
1037 long enough, and in that case the * @code{sizeof_buf} will be updated with
1038 the required size. On success 0 is returned.
1041 @subheading gnutls_x509_crq_get_dn_by_oid
1042 @anchor{gnutls_x509_crq_get_dn_by_oid}
1043 @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{sizeof_buf})
1044 @var{crq}: should contain a gnutls_x509_crq_t structure
1046 @var{oid}: holds an Object Identified in null terminated string
1048 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies
1049 which to send. Use (0) to get the first one.
1051 @var{raw_flag}: If non (0) returns the raw DER data of the DN part.
1053 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL} )
1055 @var{sizeof_buf}: initially holds the size of @code{buf}
1057 This function will extract the part of the name of the Certificate
1058 request subject, specified by the given OID. The output will be
1059 encoded as described in RFC2253. The output string will be ASCII
1060 or UTF-8 encoded, depending on the certificate data.
1062 Some helper macros with popular OIDs can be found in gnutls/x509.h
1063 If raw flag is (0), this function will only return known OIDs as
1064 text. Other OIDs will be DER encoded, as described in RFC2253 --
1065 in hex format with a '\#' prefix. You can check about known OIDs
1066 using @code{gnutls_x509_dn_oid_known()} .
1068 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1069 not long enough, and in that case the * @code{sizeof_buf} will be
1070 updated with the required size. On success 0 is returned.
1073 @subheading gnutls_x509_crq_get_dn_oid
1074 @anchor{gnutls_x509_crq_get_dn_oid}
1075 @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})
1076 @var{crq}: should contain a gnutls_x509_crq_t structure
1078 @var{indx}: Specifies which DN OID to send. Use (0) to get the first one.
1080 @var{oid}: a pointer to a structure to hold the name (may be @code{NULL} )
1082 @var{sizeof_oid}: initially holds the size of @code{oid}
1084 This function will extract the requested OID of the name of the
1085 certificate request subject, specified by the given index.
1087 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1088 not long enough, and in that case the * @code{sizeof_oid} will be
1089 updated with the required size. On success 0 is returned.
1092 @subheading gnutls_x509_crq_get_extension_by_oid
1093 @anchor{gnutls_x509_crq_get_extension_by_oid}
1094 @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{sizeof_buf}, unsigned int * @var{critical})
1095 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1097 @var{oid}: holds an Object Identified in null terminated string
1099 @var{indx}: In case multiple same OIDs exist in the extensions, this
1100 specifies which to send. Use (0) to get the first one.
1102 @var{buf}: a pointer to a structure to hold the name (may be null)
1104 @var{sizeof_buf}: initially holds the size of @code{buf}
1106 @var{critical}: will be non (0) if the extension is marked as critical
1108 This function will return the extension specified by the OID in
1109 the certificate. The extensions will be returned as binary data
1110 DER encoded, in the provided buffer.
1112 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1113 negative error code in case of an error. If the certificate does not
1114 contain the specified extension
1115 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1117 @strong{Since:} 2.8.0
1120 @subheading gnutls_x509_crq_get_extension_data
1121 @anchor{gnutls_x509_crq_get_extension_data}
1122 @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})
1123 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1125 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
1127 @var{data}: a pointer to a structure to hold the data (may be null)
1129 @var{sizeof_data}: initially holds the size of @code{oid}
1131 This function will return the requested extension data in the
1132 certificate. The extension data will be stored as a string in the
1135 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and
1136 critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead,
1137 if you want to get data indexed by the extension OID rather than
1140 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1141 negative error code in case of an error. If your have reached the
1142 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1145 @strong{Since:} 2.8.0
1148 @subheading gnutls_x509_crq_get_extension_info
1149 @anchor{gnutls_x509_crq_get_extension_info}
1150 @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})
1151 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1153 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
1155 @var{oid}: a pointer to a structure to hold the OID
1157 @var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return
1158 holds actual size of @code{oid} .
1160 @var{critical}: output variable with critical flag, may be NULL.
1162 This function will return the requested extension OID in the
1163 certificate, and the critical flag for it. The extension OID will
1164 be stored as a string in the provided buffer. Use
1165 @code{gnutls_x509_crq_get_extension_data()} to extract the data.
1167 If the buffer provided is not long enough to hold the output, then
1168 * @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1171 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1172 negative error code in case of an error. If your have reached the
1173 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1176 @strong{Since:} 2.8.0
1179 @subheading gnutls_x509_crq_get_key_id
1180 @anchor{gnutls_x509_crq_get_key_id}
1181 @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})
1182 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1184 @var{flags}: should be 0 for now
1186 @var{output_data}: will contain the key ID
1188 @var{output_data_size}: holds the size of output_data (and will be
1189 replaced by the actual size of parameters)
1191 This function will return a unique ID the depends on the public key
1192 parameters. This ID can be used in checking whether a certificate
1193 corresponds to the given private key.
1195 If the buffer provided is not long enough to hold the output, then
1196 * @code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1197 be returned. The output will normally be a SHA-1 hash output,
1200 @strong{Returns:} In case of failure a negative error code will be
1201 returned, and 0 on success.
1203 @strong{Since:} 2.8.0
1206 @subheading gnutls_x509_crq_get_key_purpose_oid
1207 @anchor{gnutls_x509_crq_get_key_purpose_oid}
1208 @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})
1209 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1211 @var{indx}: This specifies which OID to return, use (0) to get the first one
1213 @var{oid}: a pointer to a buffer to hold the OID (may be @code{NULL} )
1215 @var{sizeof_oid}: initially holds the size of @code{oid}
1217 @var{critical}: output variable with critical flag, may be @code{NULL} .
1219 This function will extract the key purpose OIDs of the Certificate
1220 specified by the given index. These are stored in the Extended Key
1221 Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for
1222 human readable names.
1224 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1225 not long enough, and in that case the * @code{sizeof_oid} will be
1226 updated with the required size. On success 0 is returned.
1228 @strong{Since:} 2.8.0
1231 @subheading gnutls_x509_crq_get_key_rsa_raw
1232 @anchor{gnutls_x509_crq_get_key_rsa_raw}
1233 @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})
1234 @var{crq}: Holds the certificate
1236 @var{m}: will hold the modulus
1238 @var{e}: will hold the public exponent
1240 This function will export the RSA public key's parameters found in
1241 the given structure. The new parameters will be allocated using
1242 @code{gnutls_malloc()} and will be stored in the appropriate datum.
1244 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1245 negative error value.
1247 @strong{Since:} 2.8.0
1250 @subheading gnutls_x509_crq_get_key_usage
1251 @anchor{gnutls_x509_crq_get_key_usage}
1252 @deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
1253 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1255 @var{key_usage}: where the key usage bits will be stored
1257 @var{critical}: will be non (0) if the extension is marked as critical
1259 This function will return certificate's key usage, by reading the
1260 keyUsage X.509 extension (2.5.29.15). The key usage value will
1261 ORed values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
1262 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
1263 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
1264 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
1265 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
1267 @strong{Returns:} the certificate key usage, or a negative error code in case of
1268 parsing error. If the certificate does not contain the keyUsage
1269 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
1272 @strong{Since:} 2.8.0
1275 @subheading gnutls_x509_crq_get_pk_algorithm
1276 @anchor{gnutls_x509_crq_get_pk_algorithm}
1277 @deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits})
1278 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1280 @var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits
1282 This function will return the public key algorithm of a PKCS@code{10}
1283 certificate request.
1285 If bits is non-@code{NULL} , it should have enough size to hold the
1286 parameters size in bits. For RSA the bits returned is the modulus.
1287 For DSA the bits returned are of the public exponent.
1289 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1290 success, or a negative error code on error.
1293 @subheading gnutls_x509_crq_get_private_key_usage_period
1294 @anchor{gnutls_x509_crq_get_private_key_usage_period}
1295 @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})
1296 @var{crq}: -- undescribed --
1298 @var{activation}: The activation time
1300 @var{expiration}: The expiration time
1302 @var{critical}: the extension status
1304 This function will return the expiration and activation
1305 times of the private key of the certificate.
1307 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1308 if the extension is not present, otherwise a negative error value.
1311 @subheading gnutls_x509_crq_get_subject_alt_name
1312 @anchor{gnutls_x509_crq_get_subject_alt_name}
1313 @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})
1314 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1316 @var{seq}: specifies the sequence number of the alt name, 0 for the
1317 first one, 1 for the second etc.
1319 @var{ret}: is the place where the alternative name will be copied to
1321 @var{ret_size}: holds the size of ret.
1323 @var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type
1325 @var{critical}: will be non (0) if the extension is marked as critical
1328 This function will return the alternative names, contained in the
1329 given certificate. It is the same as
1330 @code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it
1331 will return the type of the alternative name in @code{ret_type} even if
1332 the function fails for some reason (i.e. the buffer provided is
1335 @strong{Returns:} the alternative subject name type on success, one of the
1336 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
1337 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
1338 hold the value. In that case @code{ret_size} will be updated with the
1339 required size. If the certificate request does not have an
1340 Alternative name with the specified sequence number then
1341 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1343 @strong{Since:} 2.8.0
1346 @subheading gnutls_x509_crq_get_subject_alt_othername_oid
1347 @anchor{gnutls_x509_crq_get_subject_alt_othername_oid}
1348 @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})
1349 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1351 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1353 @var{ret}: is the place where the otherName OID will be copied to
1355 @var{ret_size}: holds the size of ret.
1357 This function will extract the type OID of an otherName Subject
1358 Alternative Name, contained in the given certificate, and return
1359 the type as an enumerated element.
1361 This function is only useful if
1362 @code{gnutls_x509_crq_get_subject_alt_name()} returned
1363 @code{GNUTLS_SAN_OTHERNAME} .
1365 @strong{Returns:} the alternative subject name type on success, one of the
1366 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs,
1367 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
1368 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
1369 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
1370 @code{ret_size} is not large enough to hold the value. In that case
1371 @code{ret_size} will be updated with the required size. If the
1372 certificate does not have an Alternative name with the specified
1373 sequence number and with the otherName type then
1374 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1376 @strong{Since:} 2.8.0
1379 @subheading gnutls_x509_crq_get_version
1380 @anchor{gnutls_x509_crq_get_version}
1381 @deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq})
1382 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1384 This function will return the version of the specified Certificate
1387 @strong{Returns:} version of certificate request, or a negative error code on
1391 @subheading gnutls_x509_crq_import
1392 @anchor{gnutls_x509_crq_import}
1393 @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})
1394 @var{crq}: The structure to store the parsed certificate request.
1396 @var{data}: The DER or PEM encoded certificate.
1398 @var{format}: One of DER or PEM
1400 This function will convert the given DER or PEM encoded certificate
1401 request to a @code{gnutls_x509_crq_t} structure. The output will be
1402 stored in @code{crq} .
1404 If the Certificate is PEM encoded it should have a header of "NEW
1405 CERTIFICATE REQUEST".
1407 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1408 negative error value.
1411 @subheading gnutls_x509_crq_init
1412 @anchor{gnutls_x509_crq_init}
1413 @deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq})
1414 @var{crq}: The structure to be initialized
1416 This function will initialize a PKCS@code{10} certificate request
1419 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1420 negative error value.
1423 @subheading gnutls_x509_crq_print
1424 @anchor{gnutls_x509_crq_print}
1425 @deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1426 @var{crq}: The structure to be printed
1428 @var{format}: Indicate the format to use
1430 @var{out}: Newly allocated datum with (0) terminated string.
1432 This function will pretty print a certificate request, suitable for
1435 The output @code{out} needs to be deallocate using @code{gnutls_free()} .
1437 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1438 negative error value.
1440 @strong{Since:} 2.8.0
1443 @subheading gnutls_x509_crq_set_attribute_by_oid
1444 @anchor{gnutls_x509_crq_set_attribute_by_oid}
1445 @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{sizeof_buf})
1446 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1448 @var{oid}: holds an Object Identified in (0)-terminated string
1450 @var{buf}: a pointer to a structure that holds the attribute data
1452 @var{sizeof_buf}: holds the size of @code{buf}
1454 This function will set the attribute in the certificate request
1455 specified by the given Object ID. The attribute must be be DER
1458 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1459 negative error value.
1462 @subheading gnutls_x509_crq_set_basic_constraints
1463 @anchor{gnutls_x509_crq_set_basic_constraints}
1464 @deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint})
1465 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1467 @var{ca}: true(1) or false(0) depending on the Certificate authority status.
1469 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
1470 and negative error codes indicate that the pathLenConstraints field should
1473 This function will set the basicConstraints certificate extension.
1475 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1476 negative error value.
1478 @strong{Since:} 2.8.0
1481 @subheading gnutls_x509_crq_set_challenge_password
1482 @anchor{gnutls_x509_crq_set_challenge_password}
1483 @deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass})
1484 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1486 @var{pass}: holds a (0)-terminated password
1488 This function will set a challenge password to be used when
1489 revoking the request.
1491 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1492 negative error value.
1495 @subheading gnutls_x509_crq_set_dn_by_oid
1496 @anchor{gnutls_x509_crq_set_dn_by_oid}
1497 @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})
1498 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1500 @var{oid}: holds an Object Identifier in a (0)-terminated string
1502 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
1504 @var{data}: a pointer to the input data
1506 @var{sizeof_data}: holds the size of @code{data}
1508 This function will set the part of the name of the Certificate
1509 request subject, specified by the given OID. The input string
1510 should be ASCII or UTF-8 encoded.
1512 Some helper macros with popular OIDs can be found in gnutls/x509.h
1513 With this function you can only set the known OIDs. You can test
1514 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
1515 not known (by gnutls) you should properly DER encode your data, and
1516 call this function with raw_flag set.
1518 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1519 negative error value.
1522 @subheading gnutls_x509_crq_set_key
1523 @anchor{gnutls_x509_crq_set_key}
1524 @deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
1525 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1527 @var{key}: holds a private key
1529 This function will set the public parameters from the given private
1532 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1533 negative error value.
1536 @subheading gnutls_x509_crq_set_key_purpose_oid
1537 @anchor{gnutls_x509_crq_set_key_purpose_oid}
1538 @deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical})
1539 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1541 @var{oid}: a pointer to a (0)-terminated string that holds the OID
1543 @var{critical}: Whether this extension will be critical or not
1545 This function will set the key purpose OIDs of the Certificate.
1546 These are stored in the Extended Key Usage extension (2.5.29.37)
1547 See the GNUTLS_KP_* definitions for human readable names.
1549 Subsequent calls to this function will append OIDs to the OID list.
1551 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1552 negative error value.
1554 @strong{Since:} 2.8.0
1557 @subheading gnutls_x509_crq_set_key_rsa_raw
1558 @anchor{gnutls_x509_crq_set_key_rsa_raw}
1559 @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})
1560 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1562 @var{m}: holds the modulus
1564 @var{e}: holds the public exponent
1566 This function will set the public parameters from the given private
1567 key to the request. Only RSA keys are currently supported.
1569 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1570 negative error value.
1572 @strong{Since:} 2.6.0
1575 @subheading gnutls_x509_crq_set_key_usage
1576 @anchor{gnutls_x509_crq_set_key_usage}
1577 @deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage})
1578 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1580 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
1582 This function will set the keyUsage certificate extension.
1584 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1585 negative error value.
1587 @strong{Since:} 2.8.0
1590 @subheading gnutls_x509_crq_set_private_key_usage_period
1591 @anchor{gnutls_x509_crq_set_private_key_usage_period}
1592 @deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration})
1593 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1595 @var{activation}: The activation time
1597 @var{expiration}: The expiration time
1599 This function will set the private key usage period extension (2.5.29.16).
1601 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1602 negative error value.
1605 @subheading gnutls_x509_crq_set_subject_alt_name
1606 @anchor{gnutls_x509_crq_set_subject_alt_name}
1607 @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})
1608 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1610 @var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations
1612 @var{data}: The data to be set
1614 @var{data_size}: The size of data to be set
1616 @var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or
1617 @code{GNUTLS_FSAN_APPEND} to append.
1619 This function will set the subject alternative name certificate
1620 extension. It can set the following types:
1622 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1623 negative error value.
1625 @strong{Since:} 2.8.0
1628 @subheading gnutls_x509_crq_set_version
1629 @anchor{gnutls_x509_crq_set_version}
1630 @deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version})
1631 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1633 @var{version}: holds the version number, for v1 Requests must be 1
1635 This function will set the version of the certificate request. For
1636 version 1 requests this must be one.
1638 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1639 negative error value.
1642 @subheading gnutls_x509_crq_sign2
1643 @anchor{gnutls_x509_crq_sign2}
1644 @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})
1645 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1647 @var{key}: holds a private key
1649 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
1651 @var{flags}: must be 0
1653 This function will sign the certificate request with a private key.
1654 This must be the same key as the one used in
1655 @code{gnutls_x509_crt_set_key()} since a certificate request is self
1658 This must be the last step in a certificate request generation
1659 since all the previously set parameters are now signed.
1661 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
1662 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
1663 information in the certificate request (e.g., the version using
1664 @code{gnutls_x509_crq_set_version()} ).
1667 @subheading gnutls_x509_crq_verify
1668 @anchor{gnutls_x509_crq_verify}
1669 @deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
1670 @var{crq}: is the crq to be verified
1672 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1674 This function will verify self signature in the certificate
1675 request and return its status.
1677 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
1678 is returned, and zero or positive code on success.
1683 @subheading gnutls_x509_crt_check_hostname
1684 @anchor{gnutls_x509_crt_check_hostname}
1685 @deftypefun {int} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname})
1686 @var{cert}: should contain an gnutls_x509_crt_t structure
1688 @var{hostname}: A null terminated string that contains a DNS name
1690 This function will check if the given certificate's subject matches
1691 the given hostname. This is a basic implementation of the matching
1692 described in RFC2818 (HTTPS), which takes into account wildcards,
1693 and the DNSName/IPAddress subject alternative name PKIX extension.
1695 @strong{Returns:} non (0) for a successful match, and (0) on failure.
1698 @subheading gnutls_x509_crt_check_issuer
1699 @anchor{gnutls_x509_crt_check_issuer}
1700 @deftypefun {int} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer})
1701 @var{cert}: is the certificate to be checked
1703 @var{issuer}: is the certificate of a possible issuer
1705 This function will check if the given certificate was issued by the
1708 @strong{Returns:} It will return true (1) if the given certificate is issued
1709 by the given issuer, and false (0) if not. A negative error code is
1710 returned in case of an error.
1713 @subheading gnutls_x509_crt_check_revocation
1714 @anchor{gnutls_x509_crt_check_revocation}
1715 @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})
1716 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1718 @var{crl_list}: should contain a list of gnutls_x509_crl_t structures
1720 @var{crl_list_length}: the length of the crl_list
1722 This function will return check if the given certificate is
1723 revoked. It is assumed that the CRLs have been verified before.
1725 @strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A
1726 negative error code is returned on error.
1729 @subheading gnutls_x509_crt_cpy_crl_dist_points
1730 @anchor{gnutls_x509_crt_cpy_crl_dist_points}
1731 @deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src})
1732 @var{dst}: a certificate of type @code{gnutls_x509_crt_t}
1734 @var{src}: the certificate where the dist points will be copied from
1736 This function will copy the CRL distribution points certificate
1737 extension, from the source to the destination certificate.
1738 This may be useful to copy from a CA certificate to issued ones.
1740 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1741 negative error value.
1744 @subheading gnutls_x509_crt_deinit
1745 @anchor{gnutls_x509_crt_deinit}
1746 @deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert})
1747 @var{cert}: The structure to be deinitialized
1749 This function will deinitialize a certificate structure.
1752 @subheading gnutls_x509_crt_export
1753 @anchor{gnutls_x509_crt_export}
1754 @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})
1755 @var{cert}: Holds the certificate
1757 @var{format}: the format of output params. One of PEM or DER.
1759 @var{output_data}: will contain a certificate PEM or DER encoded
1761 @var{output_data_size}: holds the size of output_data (and will be
1762 replaced by the actual size of parameters)
1764 This function will export the certificate to DER or PEM format.
1766 If the buffer provided is not long enough to hold the output, then
1767 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1770 If the structure is PEM encoded, it will have a header
1771 of "BEGIN CERTIFICATE".
1773 @strong{Returns:} In case of failure a negative error code will be
1774 returned, and 0 on success.
1777 @subheading gnutls_x509_crt_get_activation_time
1778 @anchor{gnutls_x509_crt_get_activation_time}
1779 @deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert})
1780 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1782 This function will return the time this Certificate was or will be
1785 @strong{Returns:} activation time, or (time_t)-1 on error.
1788 @subheading gnutls_x509_crt_get_authority_info_access
1789 @anchor{gnutls_x509_crt_get_authority_info_access}
1790 @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})
1791 @var{crt}: Holds the certificate
1793 @var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
1795 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
1797 @var{data}: output data to be freed with @code{gnutls_free()} .
1799 @var{critical}: pointer to output integer that is set to non-0 if the extension is marked as critical (may be @code{NULL} )
1801 This function extracts the Authority Information Access (AIA)
1802 extension, see RFC 5280 section 4.2.2.1 for more information. The
1803 AIA extension holds a sequence of AccessDescription (AD) data:
1805 <informalexample><programlisting>
1806 AuthorityInfoAccessSyntax ::=
1807 SEQUENCE SIZE (1..MAX) OF AccessDescription
1809 AccessDescription ::= SEQUENCE @{
1810 accessMethod OBJECT IDENTIFIER,
1811 accessLocation GeneralName @}
1812 </programlisting></informalexample>
1814 The @code{seq} input parameter is used to indicate which member of the
1815 sequence the caller is interested in. The first member is 0, the
1816 second member 1 and so on. When the @code{seq} value is out of bounds,
1817 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1819 The type of data returned in @code{data} is specified via @code{what} which
1820 should be @code{gnutls_info_access_what_t} values.
1822 If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the
1823 accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
1825 If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will
1826 hold the accessLocation GeneralName type (e.g.,
1827 "uniformResourceIdentifier").
1829 If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI
1830 data. Requesting this @code{what} value leads to an error if the
1831 accessLocation is not of the "uniformResourceIdentifier" type.
1833 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
1834 Requesting this @code{what} value leads to an error if the accessMethod
1835 is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
1836 the "uniformResourceIdentifier" type.
1838 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
1839 URI. Requesting this @code{what} value leads to an error if the
1840 accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
1841 accessLocation is not of the "uniformResourceIdentifier" type.
1843 More @code{what} values may be allocated in the future as needed.
1845 If @code{data} is NULL, the function does the same without storing the
1846 output data, that is, it will set @code{critical} and do error checking
1849 The value of the critical flag is returned in * @code{critical} . Supply a
1850 NULL @code{critical} if you want the function to make sure the extension
1851 is non-critical, as required by RFC 5280.
1853 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on
1854 invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is
1855 incorrectly marked as critical (use a non-NULL @code{critical} to
1856 override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does
1857 not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a
1858 negative error code.
1863 @subheading gnutls_x509_crt_get_authority_key_gn_serial
1864 @anchor{gnutls_x509_crt_get_authority_key_gn_serial}
1865 @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})
1866 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1868 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1870 @var{alt}: is the place where the alternative name will be copied to
1872 @var{alt_size}: holds the size of alt.
1874 @var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
1876 @var{serial}: buffer to store the serial number (may be null)
1878 @var{serial_size}: Holds the size of the serial field (may be null)
1880 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
1882 This function will return the X.509 authority key
1883 identifier when stored as a general name (authorityCertIssuer)
1886 Because more than one general names might be stored
1887 @code{seq} can be used as a counter to request them all until
1888 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1890 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1891 if the extension is not present, otherwise a negative error value.
1896 @subheading gnutls_x509_crt_get_authority_key_id
1897 @anchor{gnutls_x509_crt_get_authority_key_id}
1898 @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})
1899 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1901 @var{id}: The place where the identifier will be copied
1903 @var{id_size}: Holds the size of the id field.
1905 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
1907 This function will return the X.509v3 certificate authority's key
1908 identifier. This is obtained by the X.509 Authority Key
1909 identifier extension field (2.5.29.35). Note that this function
1910 only returns the keyIdentifier field of the extension and
1911 @code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains
1912 the name and serial number of the certificate. In that case
1913 @code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used.
1915 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1916 if the extension is not present, otherwise a negative error value.
1919 @subheading gnutls_x509_crt_get_basic_constraints
1920 @anchor{gnutls_x509_crt_get_basic_constraints}
1921 @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})
1922 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1924 @var{critical}: will be non (0) if the extension is marked as critical
1926 @var{ca}: pointer to output integer indicating CA status, may be NULL,
1927 value is 1 if the certificate CA flag is set, 0 otherwise.
1929 @var{pathlen}: pointer to output integer indicating path length (may be
1930 NULL), non-negative error codes indicate a present pathLenConstraint
1931 field and the actual value, -1 indicate that the field is absent.
1933 This function will read the certificate's basic constraints, and
1934 return the certificates CA status. It reads the basicConstraints
1935 X.509 extension (2.5.29.19).
1937 @strong{Returns:} If the certificate is a CA a positive value will be
1938 returned, or (0) if the certificate does not have CA flag set. A
1939 negative error code may be returned in case of errors. If the
1940 certificate does not contain the basicConstraints extension
1941 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
1944 @subheading gnutls_x509_crt_get_ca_status
1945 @anchor{gnutls_x509_crt_get_ca_status}
1946 @deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical})
1947 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1949 @var{critical}: will be non (0) if the extension is marked as critical
1951 This function will return certificates CA status, by reading the
1952 basicConstraints X.509 extension (2.5.29.19). If the certificate is
1953 a CA a positive value will be returned, or (0) if the certificate
1954 does not have CA flag set.
1956 Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the
1957 pathLenConstraint field too.
1959 @strong{Returns:} A negative error code may be returned in case of parsing error.
1960 If the certificate does not contain the basicConstraints extension
1961 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1964 @subheading gnutls_x509_crt_get_crl_dist_points
1965 @anchor{gnutls_x509_crt_get_crl_dist_points}
1966 @deftypefun {int} {gnutls_x509_crt_get_crl_dist_points} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{reason_flags}, unsigned int * @var{critical})
1967 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
1969 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
1971 @var{ret}: is the place where the distribution point will be copied to
1973 @var{ret_size}: holds the size of ret.
1975 @var{reason_flags}: Revocation reasons flags.
1977 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
1979 This function retrieves the CRL distribution points (2.5.29.31),
1980 contained in the given certificate in the X509v3 Certificate
1983 @code{reason_flags} should be an ORed sequence of
1984 @code{GNUTLS_CRL_REASON_UNUSED} , @code{GNUTLS_CRL_REASON_KEY_COMPROMISE} ,
1985 @code{GNUTLS_CRL_REASON_CA_COMPROMISE} ,
1986 @code{GNUTLS_CRL_REASON_AFFILIATION_CHANGED} ,
1987 @code{GNUTLS_CRL_REASON_SUPERSEEDED} ,
1988 @code{GNUTLS_CRL_REASON_CESSATION_OF_OPERATION} ,
1989 @code{GNUTLS_CRL_REASON_CERTIFICATE_HOLD} ,
1990 @code{GNUTLS_CRL_REASON_PRIVILEGE_WITHDRAWN} ,
1991 @code{GNUTLS_CRL_REASON_AA_COMPROMISE} , or (0) for all possible reasons.
1993 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if
1994 @code{ret_size} is not enough to hold the distribution point, or the
1995 type of the distribution point if everything was ok. The type is
1996 one of the enumerated @code{gnutls_x509_subject_alt_name_t} . If the
1997 certificate does not have an Alternative name with the specified
1998 sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is
2002 @subheading gnutls_x509_crt_get_dn
2003 @anchor{gnutls_x509_crt_get_dn}
2004 @deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2005 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2007 @var{buf}: a pointer to a structure to hold the name (may be null)
2009 @var{buf_size}: initially holds the size of @code{buf}
2011 This function will copy the name of the Certificate in the provided
2012 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2013 described in RFC4514. The output string will be ASCII or UTF-8
2014 encoded, depending on the certificate data.
2016 If @code{buf} is null then only the size will be filled.
2018 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2019 long enough, and in that case the @code{buf_size} will be updated
2020 with the required size. On success 0 is returned.
2023 @subheading gnutls_x509_crt_get_dn_by_oid
2024 @anchor{gnutls_x509_crt_get_dn_by_oid}
2025 @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})
2026 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2028 @var{oid}: holds an Object Identified in null terminated string
2030 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2032 @var{raw_flag}: If non (0) returns the raw DER data of the DN part.
2034 @var{buf}: a pointer where the DN part will be copied (may be null).
2036 @var{buf_size}: initially holds the size of @code{buf}
2038 This function will extract the part of the name of the Certificate
2039 subject specified by the given OID. The output, if the raw flag is
2040 not used, will be encoded as described in RFC4514. Thus a string
2041 that is ASCII or UTF-8 encoded, depending on the certificate data.
2043 Some helper macros with popular OIDs can be found in gnutls/x509.h
2044 If raw flag is (0), this function will only return known OIDs as
2045 text. Other OIDs will be DER encoded, as described in RFC4514 --
2046 in hex format with a '#' prefix. You can check about known OIDs
2047 using @code{gnutls_x509_dn_oid_known()} .
2049 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
2050 @code{buf_size} will not include the null character.
2052 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2053 not long enough, and in that case the *buf_size will be updated
2054 with the required size. On success 0 is returned.
2057 @subheading gnutls_x509_crt_get_dn_oid
2058 @anchor{gnutls_x509_crt_get_dn_oid}
2059 @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})
2060 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2062 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2064 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2066 @var{oid_size}: initially holds the size of @code{oid}
2068 This function will extract the OIDs of the name of the Certificate
2069 subject specified by the given index.
2071 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
2072 account for the trailing null.
2074 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2075 not long enough, and in that case the @code{oid_size} will be updated
2076 with the required size. On success 0 is returned.
2079 @subheading gnutls_x509_crt_get_expiration_time
2080 @anchor{gnutls_x509_crt_get_expiration_time}
2081 @deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert})
2082 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2084 This function will return the time this Certificate was or will be
2087 @strong{Returns:} expiration time, or (time_t)-1 on error.
2090 @subheading gnutls_x509_crt_get_extension_by_oid
2091 @anchor{gnutls_x509_crt_get_extension_by_oid}
2092 @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})
2093 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2095 @var{oid}: holds an Object Identified in null terminated string
2097 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
2099 @var{buf}: a pointer to a structure to hold the name (may be null)
2101 @var{buf_size}: initially holds the size of @code{buf}
2103 @var{critical}: will be non (0) if the extension is marked as critical
2105 This function will return the extension specified by the OID in the
2106 certificate. The extensions will be returned as binary data DER
2107 encoded, in the provided buffer.
2109 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2110 otherwise a negative error code is returned. If the certificate does not
2111 contain the specified extension
2112 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2115 @subheading gnutls_x509_crt_get_extension_data
2116 @anchor{gnutls_x509_crt_get_extension_data}
2117 @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})
2118 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2120 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2122 @var{data}: a pointer to a structure to hold the data (may be null)
2124 @var{sizeof_data}: initially holds the size of @code{oid}
2126 This function will return the requested extension data in the
2127 certificate. The extension data will be stored as a string in the
2130 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and
2131 critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead,
2132 if you want to get data indexed by the extension OID rather than
2135 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2136 otherwise a negative error code is returned. If you have reached the
2137 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2141 @subheading gnutls_x509_crt_get_extension_info
2142 @anchor{gnutls_x509_crt_get_extension_info}
2143 @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})
2144 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2146 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2148 @var{oid}: a pointer to a structure to hold the OID
2150 @var{oid_size}: initially holds the maximum size of @code{oid} , on return
2151 holds actual size of @code{oid} .
2153 @var{critical}: output variable with critical flag, may be NULL.
2155 This function will return the requested extension OID in the
2156 certificate, and the critical flag for it. The extension OID will
2157 be stored as a string in the provided buffer. Use
2158 @code{gnutls_x509_crt_get_extension_data()} to extract the data.
2160 If the buffer provided is not long enough to hold the output, then
2161 @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
2162 returned. The @code{oid} returned will be null terminated, although
2163 @code{oid_size} will not account for the trailing null.
2165 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2166 otherwise a negative error code is returned. If you have reached the
2167 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2171 @subheading gnutls_x509_crt_get_extension_oid
2172 @anchor{gnutls_x509_crt_get_extension_oid}
2173 @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})
2174 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2176 @var{indx}: Specifies which extension OID to send. Use (0) to get the first one.
2178 @var{oid}: a pointer to a structure to hold the OID (may be null)
2180 @var{oid_size}: initially holds the size of @code{oid}
2182 This function will return the requested extension OID in the certificate.
2183 The extension OID will be stored as a string in the provided buffer.
2185 The @code{oid} returned will be null terminated, although @code{oid_size} will not
2186 account for the trailing null.
2188 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2189 otherwise a negative error code is returned. If you have reached the
2190 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2194 @subheading gnutls_x509_crt_get_fingerprint
2195 @anchor{gnutls_x509_crt_get_fingerprint}
2196 @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})
2197 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2199 @var{algo}: is a digest algorithm
2201 @var{buf}: a pointer to a structure to hold the fingerprint (may be null)
2203 @var{buf_size}: initially holds the size of @code{buf}
2205 This function will calculate and copy the certificate's fingerprint
2206 in the provided buffer.
2208 If the buffer is null then only the size will be filled.
2210 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2211 not long enough, and in that case the *buf_size will be updated
2212 with the required size. On success 0 is returned.
2215 @subheading gnutls_x509_crt_get_issuer
2216 @anchor{gnutls_x509_crt_get_issuer}
2217 @deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2218 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2220 @var{dn}: output variable with pointer to uint8_t DN
2222 Return the Certificate's Issuer DN as an uint8_t data type. You may
2223 use @code{gnutls_x509_dn_get_rdn_ava()} to decode the DN.
2225 Note that @code{dn} should be treated as constant. Because points
2226 into the @code{cert} object, you may not deallocate @code{cert} and continue to access @code{dn} .
2228 @strong{Returns:} Returns 0 on success, or an error code.
2231 @subheading gnutls_x509_crt_get_issuer_alt_name
2232 @anchor{gnutls_x509_crt_get_issuer_alt_name}
2233 @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})
2234 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2236 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2238 @var{ian}: is the place where the alternative name will be copied to
2240 @var{ian_size}: holds the size of ian.
2242 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
2244 This function retrieves the Issuer Alternative Name (2.5.29.18),
2245 contained in the given certificate in the X509v3 Certificate
2248 When the SAN type is otherName, it will extract the data in the
2249 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2250 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2251 the corresponding OID and the "virtual" SAN types (e.g.,
2252 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
2254 If an otherName OID is known, the data will be decoded. Otherwise
2255 the returned data will be DER encoded, and you will have to decode
2256 it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer
2257 AltName is recognized.
2259 @strong{Returns:} the alternative issuer name type on success, one of the
2260 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2261 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2262 to hold the value. In that case @code{ian_size} will be updated with
2263 the required size. If the certificate does not have an
2264 Alternative name with the specified sequence number then
2265 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2267 @strong{Since:} 2.10.0
2270 @subheading gnutls_x509_crt_get_issuer_alt_name2
2271 @anchor{gnutls_x509_crt_get_issuer_alt_name2}
2272 @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})
2273 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2275 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2277 @var{ian}: is the place where the alternative name will be copied to
2279 @var{ian_size}: holds the size of ret.
2281 @var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2283 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
2285 This function will return the alternative names, contained in the
2286 given certificate. It is the same as
2287 @code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it
2288 will return the type of the alternative name in @code{ian_type} even if
2289 the function fails for some reason (i.e. the buffer provided is
2292 @strong{Returns:} the alternative issuer name type on success, one of the
2293 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2294 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough
2295 to hold the value. In that case @code{ian_size} will be updated with
2296 the required size. If the certificate does not have an
2297 Alternative name with the specified sequence number then
2298 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2300 @strong{Since:} 2.10.0
2303 @subheading gnutls_x509_crt_get_issuer_alt_othername_oid
2304 @anchor{gnutls_x509_crt_get_issuer_alt_othername_oid}
2305 @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})
2306 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2308 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2310 @var{ret}: is the place where the otherName OID will be copied to
2312 @var{ret_size}: holds the size of ret.
2314 This function will extract the type OID of an otherName Subject
2315 Alternative Name, contained in the given certificate, and return
2316 the type as an enumerated element.
2318 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
2319 account for the trailing null.
2321 This function is only useful if
2322 @code{gnutls_x509_crt_get_issuer_alt_name()} returned
2323 @code{GNUTLS_SAN_OTHERNAME} .
2325 @strong{Returns:} the alternative issuer name type on success, one of the
2326 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2327 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2328 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
2329 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2330 @code{ret_size} is not large enough to hold the value. In that case
2331 @code{ret_size} will be updated with the required size. If the
2332 certificate does not have an Alternative name with the specified
2333 sequence number and with the otherName type then
2334 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2336 @strong{Since:} 2.10.0
2339 @subheading gnutls_x509_crt_get_issuer_dn
2340 @anchor{gnutls_x509_crt_get_issuer_dn}
2341 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size})
2342 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2344 @var{buf}: a pointer to a structure to hold the name (may be null)
2346 @var{buf_size}: initially holds the size of @code{buf}
2348 This function will copy the name of the Certificate issuer in the
2349 provided buffer. The name will be in the form
2350 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
2351 will be ASCII or UTF-8 encoded, depending on the certificate data.
2353 If @code{buf} is null then only the size will be filled.
2355 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2356 long enough, and in that case the @code{buf_size} will be updated with
2357 the required size. On success 0 is returned.
2360 @subheading gnutls_x509_crt_get_issuer_dn_by_oid
2361 @anchor{gnutls_x509_crt_get_issuer_dn_by_oid}
2362 @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})
2363 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2365 @var{oid}: holds an Object Identified in null terminated string
2367 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
2369 @var{raw_flag}: If non (0) returns the raw DER data of the DN part.
2371 @var{buf}: a pointer to a structure to hold the name (may be null)
2373 @var{buf_size}: initially holds the size of @code{buf}
2375 This function will extract the part of the name of the Certificate
2376 issuer specified by the given OID. The output, if the raw flag is not
2377 used, will be encoded as described in RFC4514. Thus a string that is
2378 ASCII or UTF-8 encoded, depending on the certificate data.
2380 Some helper macros with popular OIDs can be found in gnutls/x509.h
2381 If raw flag is (0), this function will only return known OIDs as
2382 text. Other OIDs will be DER encoded, as described in RFC4514 --
2383 in hex format with a '#' prefix. You can check about known OIDs
2384 using @code{gnutls_x509_dn_oid_known()} .
2386 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
2387 @code{buf_size} will not include the null character.
2389 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2390 long enough, and in that case the @code{buf_size} will be updated
2391 with the required size. On success 0 is returned.
2394 @subheading gnutls_x509_crt_get_issuer_dn_oid
2395 @anchor{gnutls_x509_crt_get_issuer_dn_oid}
2396 @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})
2397 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2399 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2401 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2403 @var{oid_size}: initially holds the size of @code{oid}
2405 This function will extract the OIDs of the name of the Certificate
2406 issuer specified by the given index.
2408 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
2409 account for the trailing null.
2411 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2412 long enough, and in that case the @code{oid_size} will be updated
2413 with the required size. On success 0 is returned.
2416 @subheading gnutls_x509_crt_get_issuer_unique_id
2417 @anchor{gnutls_x509_crt_get_issuer_unique_id}
2418 @deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
2419 @var{crt}: Holds the certificate
2421 @var{buf}: user allocated memory buffer, will hold the unique id
2423 @var{buf_size}: size of user allocated memory buffer (on input), will hold
2424 actual size of the unique ID on return.
2426 This function will extract the issuerUniqueID value (if present) for
2427 the given certificate.
2429 If the user allocated memory buffer is not large enough to hold the
2430 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
2431 returned, and buf_size will be set to the actual length.
2433 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2435 @strong{Since:} 2.12.0
2438 @subheading gnutls_x509_crt_get_key_id
2439 @anchor{gnutls_x509_crt_get_key_id}
2440 @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})
2441 @var{crt}: Holds the certificate
2443 @var{flags}: should be 0 for now
2445 @var{output_data}: will contain the key ID
2447 @var{output_data_size}: holds the size of output_data (and will be
2448 replaced by the actual size of parameters)
2450 This function will return a unique ID the depends on the public
2451 key parameters. This ID can be used in checking whether a
2452 certificate corresponds to the given private key.
2454 If the buffer provided is not long enough to hold the output, then
2455 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2456 be returned. The output will normally be a SHA-1 hash output,
2459 @strong{Returns:} In case of failure a negative error code will be
2460 returned, and 0 on success.
2463 @subheading gnutls_x509_crt_get_key_purpose_oid
2464 @anchor{gnutls_x509_crt_get_key_purpose_oid}
2465 @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})
2466 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2468 @var{indx}: This specifies which OID to return. Use (0) to get the first one.
2470 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2472 @var{oid_size}: initially holds the size of @code{oid}
2474 @var{critical}: output flag to indicate criticality of extension
2476 This function will extract the key purpose OIDs of the Certificate
2477 specified by the given index. These are stored in the Extended Key
2478 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
2479 human readable names.
2481 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
2482 account for the trailing null.
2484 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2485 not long enough, and in that case the *oid_size will be updated
2486 with the required size. On success 0 is returned.
2489 @subheading gnutls_x509_crt_get_key_usage
2490 @anchor{gnutls_x509_crt_get_key_usage}
2491 @deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
2492 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2494 @var{key_usage}: where the key usage bits will be stored
2496 @var{critical}: will be non (0) if the extension is marked as critical
2498 This function will return certificate's key usage, by reading the
2499 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
2500 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} ,
2501 @code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} ,
2502 @code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} ,
2503 @code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} ,
2504 @code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} .
2506 @strong{Returns:} the certificate key usage, or a negative error code in case of
2507 parsing error. If the certificate does not contain the keyUsage
2508 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
2512 @subheading gnutls_x509_crt_get_pk_algorithm
2513 @anchor{gnutls_x509_crt_get_pk_algorithm}
2514 @deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits})
2515 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2517 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
2519 This function will return the public key algorithm of an X.509
2522 If bits is non null, it should have enough size to hold the parameters
2523 size in bits. For RSA the bits returned is the modulus.
2524 For DSA the bits returned are of the public
2527 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
2528 success, or a negative error code on error.
2531 @subheading gnutls_x509_crt_get_pk_dsa_raw
2532 @anchor{gnutls_x509_crt_get_pk_dsa_raw}
2533 @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})
2534 @var{crt}: Holds the certificate
2536 @var{p}: will hold the p
2538 @var{q}: will hold the q
2540 @var{g}: will hold the g
2542 @var{y}: will hold the y
2544 This function will export the DSA public key's parameters found in
2545 the given certificate. The new parameters will be allocated using
2546 @code{gnutls_malloc()} and will be stored in the appropriate datum.
2548 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2551 @subheading gnutls_x509_crt_get_pk_rsa_raw
2552 @anchor{gnutls_x509_crt_get_pk_rsa_raw}
2553 @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})
2554 @var{crt}: Holds the certificate
2556 @var{m}: will hold the modulus
2558 @var{e}: will hold the public exponent
2560 This function will export the RSA public key's parameters found in
2561 the given structure. The new parameters will be allocated using
2562 @code{gnutls_malloc()} and will be stored in the appropriate datum.
2564 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2567 @subheading gnutls_x509_crt_get_private_key_usage_period
2568 @anchor{gnutls_x509_crt_get_private_key_usage_period}
2569 @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})
2570 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2572 @var{activation}: The activation time
2574 @var{expiration}: The expiration time
2576 @var{critical}: the extension status
2578 This function will return the expiration and activation
2579 times of the private key of the certificate. It relies on
2580 the PKIX extension 2.5.29.16 being present.
2582 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2583 if the extension is not present, otherwise a negative error value.
2586 @subheading gnutls_x509_crt_get_proxy
2587 @anchor{gnutls_x509_crt_get_proxy}
2588 @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})
2589 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2591 @var{critical}: will be non (0) if the extension is marked as critical
2593 @var{pathlen}: pointer to output integer indicating path length (may be
2594 NULL), non-negative error codes indicate a present pCPathLenConstraint
2595 field and the actual value, -1 indicate that the field is absent.
2597 @var{policyLanguage}: output variable with OID of policy language
2599 @var{policy}: output variable with policy data
2601 @var{sizeof_policy}: output variable size of policy data
2603 This function will get information from a proxy certificate. It
2604 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
2606 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
2607 otherwise a negative error code is returned.
2610 @subheading gnutls_x509_crt_get_raw_dn
2611 @anchor{gnutls_x509_crt_get_raw_dn}
2612 @deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{start})
2613 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2615 @var{start}: will hold the starting point of the DN
2617 This function will return a pointer to the DER encoded DN structure and
2620 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2621 negative error value. or a negative error code on error.
2624 @subheading gnutls_x509_crt_get_raw_issuer_dn
2625 @anchor{gnutls_x509_crt_get_raw_issuer_dn}
2626 @deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{start})
2627 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2629 @var{start}: will hold the starting point of the DN
2631 This function will return a pointer to the DER encoded DN structure
2634 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2635 negative error value.or a negative error code on error.
2638 @subheading gnutls_x509_crt_get_serial
2639 @anchor{gnutls_x509_crt_get_serial}
2640 @deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size})
2641 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2643 @var{result}: The place where the serial number will be copied
2645 @var{result_size}: Holds the size of the result field.
2647 This function will return the X.509 certificate's serial number.
2648 This is obtained by the X509 Certificate serialNumber field. Serial
2649 is not always a 32 or 64bit number. Some CAs use large serial
2650 numbers, thus it may be wise to handle it as something uint8_t.
2652 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2653 negative error value.
2656 @subheading gnutls_x509_crt_get_signature
2657 @anchor{gnutls_x509_crt_get_signature}
2658 @deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sizeof_sig})
2659 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2661 @var{sig}: a pointer where the signature part will be copied (may be null).
2663 @var{sizeof_sig}: initially holds the size of @code{sig}
2665 This function will extract the signature field of a certificate.
2667 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2668 negative error value. and a negative error code on error.
2671 @subheading gnutls_x509_crt_get_signature_algorithm
2672 @anchor{gnutls_x509_crt_get_signature_algorithm}
2673 @deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert})
2674 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2676 This function will return a value of the @code{gnutls_sign_algorithm_t}
2677 enumeration that is the signature algorithm that has been used to
2678 sign this certificate.
2680 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code on
2684 @subheading gnutls_x509_crt_get_subject
2685 @anchor{gnutls_x509_crt_get_subject}
2686 @deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2687 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2689 @var{dn}: output variable with pointer to uint8_t DN.
2691 Return the Certificate's Subject DN as an uint8_t data type. You
2692 may use @code{gnutls_x509_dn_get_rdn_ava()} to decode the DN.
2694 Note that @code{dn} should be treated as constant. Because points
2695 into the @code{cert} object, you may not deallocate @code{cert} and continue to access @code{dn} .
2697 @strong{Returns:} Returns 0 on success, or an error code.
2700 @subheading gnutls_x509_crt_get_subject_alt_name
2701 @anchor{gnutls_x509_crt_get_subject_alt_name}
2702 @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})
2703 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2705 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2707 @var{san}: is the place where the alternative name will be copied to
2709 @var{san_size}: holds the size of san.
2711 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
2713 This function retrieves the Alternative Name (2.5.29.17), contained
2714 in the given certificate in the X509v3 Certificate Extensions.
2716 When the SAN type is otherName, it will extract the data in the
2717 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2718 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2719 the corresponding OID and the "virtual" SAN types (e.g.,
2720 @code{GNUTLS_SAN_OTHERNAME_XMPP} ).
2722 If an otherName OID is known, the data will be decoded. Otherwise
2723 the returned data will be DER encoded, and you will have to decode
2724 it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is
2727 @strong{Returns:} the alternative subject name type on success, one of the
2728 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2729 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to
2730 hold the value. In that case @code{san_size} will be updated with the
2731 required size. If the certificate does not have an Alternative
2732 name with the specified sequence number then
2733 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2736 @subheading gnutls_x509_crt_get_subject_alt_name2
2737 @anchor{gnutls_x509_crt_get_subject_alt_name2}
2738 @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})
2739 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2741 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2743 @var{san}: is the place where the alternative name will be copied to
2745 @var{san_size}: holds the size of ret.
2747 @var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2749 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
2751 This function will return the alternative names, contained in the
2752 given certificate. It is the same as
2753 @code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it
2754 will return the type of the alternative name in @code{san_type} even if
2755 the function fails for some reason (i.e. the buffer provided is
2758 @strong{Returns:} the alternative subject name type on success, one of the
2759 enumerated @code{gnutls_x509_subject_alt_name_t} . It will return
2760 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough
2761 to hold the value. In that case @code{san_size} will be updated with
2762 the required size. If the certificate does not have an
2763 Alternative name with the specified sequence number then
2764 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2767 @subheading gnutls_x509_crt_get_subject_alt_othername_oid
2768 @anchor{gnutls_x509_crt_get_subject_alt_othername_oid}
2769 @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})
2770 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2772 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2774 @var{oid}: is the place where the otherName OID will be copied to
2776 @var{oid_size}: holds the size of ret.
2778 This function will extract the type OID of an otherName Subject
2779 Alternative Name, contained in the given certificate, and return
2780 the type as an enumerated element.
2782 This function is only useful if
2783 @code{gnutls_x509_crt_get_subject_alt_name()} returned
2784 @code{GNUTLS_SAN_OTHERNAME} .
2786 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
2787 account for the trailing null.
2789 @strong{Returns:} the alternative subject name type on success, one of the
2790 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2791 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2792 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for
2793 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2794 @code{ian_size} is not large enough to hold the value. In that case
2795 @code{ian_size} will be updated with the required size. If the
2796 certificate does not have an Alternative name with the specified
2797 sequence number and with the otherName type then
2798 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2801 @subheading gnutls_x509_crt_get_subject_key_id
2802 @anchor{gnutls_x509_crt_get_subject_key_id}
2803 @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})
2804 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2806 @var{ret}: The place where the identifier will be copied
2808 @var{ret_size}: Holds the size of the result field.
2810 @var{critical}: will be non (0) if the extension is marked as critical (may be null)
2812 This function will return the X.509v3 certificate's subject key
2813 identifier. This is obtained by the X.509 Subject Key identifier
2814 extension field (2.5.29.14).
2816 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2817 if the extension is not present, otherwise a negative error value.
2820 @subheading gnutls_x509_crt_get_subject_unique_id
2821 @anchor{gnutls_x509_crt_get_subject_unique_id}
2822 @deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size})
2823 @var{crt}: Holds the certificate
2825 @var{buf}: user allocated memory buffer, will hold the unique id
2827 @var{buf_size}: size of user allocated memory buffer (on input), will hold
2828 actual size of the unique ID on return.
2830 This function will extract the subjectUniqueID value (if present) for
2831 the given certificate.
2833 If the user allocated memory buffer is not large enough to hold the
2834 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
2835 returned, and buf_size will be set to the actual length.
2837 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
2840 @subheading gnutls_x509_crt_get_version
2841 @anchor{gnutls_x509_crt_get_version}
2842 @deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert})
2843 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2845 This function will return the version of the specified Certificate.
2847 @strong{Returns:} version of certificate, or a negative error code on error.
2850 @subheading gnutls_x509_crt_import
2851 @anchor{gnutls_x509_crt_import}
2852 @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})
2853 @var{cert}: The structure to store the parsed certificate.
2855 @var{data}: The DER or PEM encoded certificate.
2857 @var{format}: One of DER or PEM
2859 This function will convert the given DER or PEM encoded Certificate
2860 to the native gnutls_x509_crt_t format. The output will be stored
2863 If the Certificate is PEM encoded it should have a header of "X509
2864 CERTIFICATE", or "CERTIFICATE".
2866 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2867 negative error value.
2870 @subheading gnutls_x509_crt_init
2871 @anchor{gnutls_x509_crt_init}
2872 @deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert})
2873 @var{cert}: The structure to be initialized
2875 This function will initialize an X.509 certificate structure.
2877 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2878 negative error value.
2881 @subheading gnutls_x509_crt_list_import
2882 @anchor{gnutls_x509_crt_list_import}
2883 @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})
2884 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
2886 @var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
2888 @var{data}: The PEM encoded certificate.
2890 @var{format}: One of DER or PEM.
2892 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
2894 This function will convert the given PEM encoded certificate list
2895 to the native gnutls_x509_crt_t format. The output will be stored
2896 in @code{certs} . They will be automatically initialized.
2898 The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause
2899 import to fail if the certificates in the provided buffer are more
2900 than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED}
2901 flag will cause the function to fail if the provided list is not
2902 sorted from subject to issuer.
2904 If the Certificate is PEM encoded it should have a header of "X509
2905 CERTIFICATE", or "CERTIFICATE".
2907 @strong{Returns:} the number of certificates read or a negative error value.
2910 @subheading gnutls_x509_crt_list_import2
2911 @anchor{gnutls_x509_crt_list_import2}
2912 @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})
2913 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
2915 @var{size}: It will contain the size of the list.
2917 @var{data}: The PEM encoded certificate.
2919 @var{format}: One of DER or PEM.
2921 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
2923 This function will convert the given PEM encoded certificate list
2924 to the native gnutls_x509_crt_t format. The output will be stored
2925 in @code{certs} which will be initialized.
2927 If the Certificate is PEM encoded it should have a header of "X509
2928 CERTIFICATE", or "CERTIFICATE".
2930 @strong{Returns:} the number of certificates read or a negative error value.
2935 @subheading gnutls_x509_crt_list_verify
2936 @anchor{gnutls_x509_crt_list_verify}
2937 @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})
2938 @var{cert_list}: is the certificate list to be verified
2940 @var{cert_list_length}: holds the number of certificate in cert_list
2942 @var{CA_list}: is the CA list which will be used in verification
2944 @var{CA_list_length}: holds the number of CA certificate in CA_list
2946 @var{CRL_list}: holds a list of CRLs.
2948 @var{CRL_list_length}: the length of CRL list.
2950 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2952 @var{verify}: will hold the certificate verification output.
2954 This function will try to verify the given certificate list and
2955 return its status. If no flags are specified (0), this function
2956 will use the basicConstraints (2.5.29.19) PKIX extension. This
2957 means that only a certificate authority is allowed to sign a
2960 You must also check the peer's name in order to check if the verified
2961 certificate belongs to the actual peer.
2963 The certificate verification output will be put in @code{verify} and will
2964 be one or more of the gnutls_certificate_status_t enumerated
2965 elements bitwise or'd. For a more detailed verification status use
2966 @code{gnutls_x509_crt_verify()} per list element.
2968 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2969 negative error value.
2972 @subheading gnutls_x509_crt_print
2973 @anchor{gnutls_x509_crt_print}
2974 @deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
2975 @var{cert}: The structure to be printed
2977 @var{format}: Indicate the format to use
2979 @var{out}: Newly allocated datum with (0) terminated string.
2981 This function will pretty print a X.509 certificate, suitable for
2984 If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the
2985 certificate will be output, on multiple lines. The
2986 @code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some
2987 selected fields, which is useful for logging purposes.
2989 The output @code{out} needs to be deallocate using @code{gnutls_free()} .
2991 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
2992 negative error value.
2995 @subheading gnutls_x509_crt_set_activation_time
2996 @anchor{gnutls_x509_crt_set_activation_time}
2997 @deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time})
2998 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3000 @var{act_time}: The actual time
3002 This function will set the time this Certificate was or will be
3005 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3006 negative error value.
3009 @subheading gnutls_x509_crt_set_authority_info_access
3010 @anchor{gnutls_x509_crt_set_authority_info_access}
3011 @deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data})
3012 @var{crt}: Holds the certificate
3014 @var{what}: what data to get, a @code{gnutls_info_access_what_t} type.
3016 @var{data}: output data to be freed with @code{gnutls_free()} .
3018 This function sets the Authority Information Access (AIA)
3019 extension, see RFC 5280 section 4.2.2.1 for more information.
3021 The type of data stored in @code{data} is specified via @code{what} which
3022 should be @code{gnutls_info_access_what_t} values.
3024 If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI.
3025 If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers
3028 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3029 negative error value.
3034 @subheading gnutls_x509_crt_set_authority_key_id
3035 @anchor{gnutls_x509_crt_set_authority_key_id}
3036 @deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3037 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3039 @var{id}: The key ID
3041 @var{id_size}: Holds the size of the serial field.
3043 This function will set the X.509 certificate's authority key ID extension.
3044 Only the keyIdentifier field can be set with this function.
3046 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3047 negative error value.
3050 @subheading gnutls_x509_crt_set_basic_constraints
3051 @anchor{gnutls_x509_crt_set_basic_constraints}
3052 @deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint})
3053 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3055 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3057 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
3058 and negative error codes indicate that the pathLenConstraints field should
3061 This function will set the basicConstraints certificate extension.
3063 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3064 negative error value.
3067 @subheading gnutls_x509_crt_set_ca_status
3068 @anchor{gnutls_x509_crt_set_ca_status}
3069 @deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca})
3070 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3072 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3074 This function will set the basicConstraints certificate extension.
3075 Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control
3076 the pathLenConstraint field too.
3078 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3079 negative error value.
3082 @subheading gnutls_x509_crt_set_crl_dist_points
3083 @anchor{gnutls_x509_crt_set_crl_dist_points}
3084 @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})
3085 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3087 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3089 @var{data_string}: The data to be set
3091 @var{reason_flags}: revocation reasons
3093 This function will set the CRL distribution points certificate extension.
3095 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3096 negative error value.
3099 @subheading gnutls_x509_crt_set_crl_dist_points2
3100 @anchor{gnutls_x509_crt_set_crl_dist_points2}
3101 @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})
3102 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3104 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3106 @var{data}: The data to be set
3108 @var{data_size}: The data size
3110 @var{reason_flags}: revocation reasons
3112 This function will set the CRL distribution points certificate extension.
3114 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3115 negative error value.
3117 @strong{Since:} 2.6.0
3120 @subheading gnutls_x509_crt_set_crq
3121 @anchor{gnutls_x509_crt_set_crq}
3122 @deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3123 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3125 @var{crq}: holds a certificate request
3127 This function will set the name and public parameters as well as
3128 the extensions from the given certificate request to the certificate.
3129 Only RSA keys are currently supported.
3131 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3132 negative error value.
3135 @subheading gnutls_x509_crt_set_crq_extensions
3136 @anchor{gnutls_x509_crt_set_crq_extensions}
3137 @deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3138 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3140 @var{crq}: holds a certificate request
3142 This function will set extensions from the given request to the
3145 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3146 negative error value.
3148 @strong{Since:} 2.8.0
3151 @subheading gnutls_x509_crt_set_dn_by_oid
3152 @anchor{gnutls_x509_crt_set_dn_by_oid}
3153 @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})
3154 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3156 @var{oid}: holds an Object Identifier in a null terminated string
3158 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3160 @var{name}: a pointer to the name
3162 @var{sizeof_name}: holds the size of @code{name}
3164 This function will set the part of the name of the Certificate
3165 subject, specified by the given OID. The input string should be
3166 ASCII or UTF-8 encoded.
3168 Some helper macros with popular OIDs can be found in gnutls/x509.h
3169 With this function you can only set the known OIDs. You can test
3170 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3171 not known (by gnutls) you should properly DER encode your data,
3172 and call this function with @code{raw_flag} set.
3174 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3175 negative error value.
3178 @subheading gnutls_x509_crt_set_expiration_time
3179 @anchor{gnutls_x509_crt_set_expiration_time}
3180 @deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time})
3181 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3183 @var{exp_time}: The actual time
3185 This function will set the time this Certificate will expire.
3187 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3188 negative error value.
3191 @subheading gnutls_x509_crt_set_extension_by_oid
3192 @anchor{gnutls_x509_crt_set_extension_by_oid}
3193 @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})
3194 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3196 @var{oid}: holds an Object Identified in null terminated string
3198 @var{buf}: a pointer to a DER encoded data
3200 @var{sizeof_buf}: holds the size of @code{buf}
3202 @var{critical}: should be non (0) if the extension is to be marked as critical
3204 This function will set an the extension, by the specified OID, in
3205 the certificate. The extension data should be binary data DER
3208 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3209 negative error value.
3212 @subheading gnutls_x509_crt_set_issuer_dn_by_oid
3213 @anchor{gnutls_x509_crt_set_issuer_dn_by_oid}
3214 @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})
3215 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3217 @var{oid}: holds an Object Identifier in a null terminated string
3219 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3221 @var{name}: a pointer to the name
3223 @var{sizeof_name}: holds the size of @code{name}
3225 This function will set the part of the name of the Certificate
3226 issuer, specified by the given OID. The input string should be
3227 ASCII or UTF-8 encoded.
3229 Some helper macros with popular OIDs can be found in gnutls/x509.h
3230 With this function you can only set the known OIDs. You can test
3231 for known OIDs using @code{gnutls_x509_dn_oid_known()} . For OIDs that are
3232 not known (by gnutls) you should properly DER encode your data,
3233 and call this function with @code{raw_flag} set.
3235 Normally you do not need to call this function, since the signing
3236 operation will copy the signer's name as the issuer of the
3239 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3240 negative error value.
3243 @subheading gnutls_x509_crt_set_key
3244 @anchor{gnutls_x509_crt_set_key}
3245 @deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key})
3246 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3248 @var{key}: holds a private key
3250 This function will set the public parameters from the given
3251 private key to the certificate. Only RSA keys are currently
3254 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3255 negative error value.
3258 @subheading gnutls_x509_crt_set_key_purpose_oid
3259 @anchor{gnutls_x509_crt_set_key_purpose_oid}
3260 @deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical})
3261 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3263 @var{oid}: a pointer to a null terminated string that holds the OID
3265 @var{critical}: Whether this extension will be critical or not
3267 This function will set the key purpose OIDs of the Certificate.
3268 These are stored in the Extended Key Usage extension (2.5.29.37)
3269 See the GNUTLS_KP_* definitions for human readable names.
3271 Subsequent calls to this function will append OIDs to the OID list.
3273 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned,
3274 otherwise a negative error code is returned.
3277 @subheading gnutls_x509_crt_set_key_usage
3278 @anchor{gnutls_x509_crt_set_key_usage}
3279 @deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage})
3280 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3282 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
3284 This function will set the keyUsage certificate extension.
3286 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3287 negative error value.
3290 @subheading gnutls_x509_crt_set_private_key_usage_period
3291 @anchor{gnutls_x509_crt_set_private_key_usage_period}
3292 @deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration})
3293 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3295 @var{activation}: The activation time
3297 @var{expiration}: The expiration time
3299 This function will set the private key usage period extension (2.5.29.16).
3301 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3302 negative error value.
3305 @subheading gnutls_x509_crt_set_proxy
3306 @anchor{gnutls_x509_crt_set_proxy}
3307 @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})
3308 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3310 @var{pathLenConstraint}: non-negative error codes indicate maximum length of path,
3311 and negative error codes indicate that the pathLenConstraints field should
3314 @var{policyLanguage}: OID describing the language of @code{policy} .
3316 @var{policy}: uint8_t byte array with policy language, can be @code{NULL}
3318 @var{sizeof_policy}: size of @code{policy} .
3320 This function will set the proxyCertInfo extension.
3322 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3323 negative error value.
3326 @subheading gnutls_x509_crt_set_proxy_dn
3327 @anchor{gnutls_x509_crt_set_proxy_dn}
3328 @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})
3329 @var{crt}: a gnutls_x509_crt_t structure with the new proxy cert
3331 @var{eecrt}: the end entity certificate that will be issuing the proxy
3333 @var{raw_flag}: must be 0, or 1 if the CN is DER encoded
3335 @var{name}: a pointer to the CN name, may be NULL (but MUST then be added later)
3337 @var{sizeof_name}: holds the size of @code{name}
3339 This function will set the subject in @code{crt} to the end entity's
3340 @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy
3341 certificate naming style. Note that if @code{name} is @code{NULL} , you MUST
3342 set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar.
3344 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3345 negative error value.
3348 @subheading gnutls_x509_crt_set_serial
3349 @anchor{gnutls_x509_crt_set_serial}
3350 @deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size})
3351 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3353 @var{serial}: The serial number
3355 @var{serial_size}: Holds the size of the serial field.
3357 This function will set the X.509 certificate's serial number.
3358 Serial is not always a 32 or 64bit number. Some CAs use large
3359 serial numbers, thus it may be wise to handle it as something
3362 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3363 negative error value.
3366 @subheading gnutls_x509_crt_set_subject_alternative_name
3367 @anchor{gnutls_x509_crt_set_subject_alternative_name}
3368 @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})
3369 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3371 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3373 @var{data_string}: The data to be set, a (0) terminated string
3375 This function will set the subject alternative name certificate
3376 extension. This function assumes that data can be expressed as a null
3379 The name of the function is unfortunate since it is incosistent with
3380 @code{gnutls_x509_crt_get_subject_alt_name()} .
3382 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3383 negative error value.
3386 @subheading gnutls_x509_crt_set_subject_alt_name
3387 @anchor{gnutls_x509_crt_set_subject_alt_name}
3388 @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})
3389 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3391 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3393 @var{data}: The data to be set
3395 @var{data_size}: The size of data to be set
3397 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
3399 This function will set the subject alternative name certificate
3400 extension. It can set the following types:
3402 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3403 negative error value.
3405 @strong{Since:} 2.6.0
3408 @subheading gnutls_x509_crt_set_subject_key_id
3409 @anchor{gnutls_x509_crt_set_subject_key_id}
3410 @deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3411 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3413 @var{id}: The key ID
3415 @var{id_size}: Holds the size of the serial field.
3417 This function will set the X.509 certificate's subject key ID
3420 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3421 negative error value.
3424 @subheading gnutls_x509_crt_set_version
3425 @anchor{gnutls_x509_crt_set_version}
3426 @deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version})
3427 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3429 @var{version}: holds the version number. For X.509v1 certificates must be 1.
3431 This function will set the version of the certificate. This must
3432 be one for X.509 version 1, and so on. Plain certificates without
3433 extensions must have version set to one.
3435 To create well-formed certificates, you must specify version 3 if
3436 you use any certificate extensions. Extensions are created by
3437 functions such as @code{gnutls_x509_crt_set_subject_alt_name()}
3438 or @code{gnutls_x509_crt_set_key_usage()} .
3440 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3441 negative error value.
3444 @subheading gnutls_x509_crt_sign
3445 @anchor{gnutls_x509_crt_sign}
3446 @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})
3447 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3449 @var{issuer}: is the certificate of the certificate issuer
3451 @var{issuer_key}: holds the issuer's private key
3453 This function is the same a @code{gnutls_x509_crt_sign2()} with no flags,
3454 and SHA1 as the hash algorithm.
3456 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3457 negative error value.
3460 @subheading gnutls_x509_crt_sign2
3461 @anchor{gnutls_x509_crt_sign2}
3462 @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})
3463 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3465 @var{issuer}: is the certificate of the certificate issuer
3467 @var{issuer_key}: holds the issuer's private key
3469 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
3471 @var{flags}: must be 0
3473 This function will sign the certificate with the issuer's private key, and
3474 will copy the issuer's information into the certificate.
3476 This must be the last step in a certificate generation since all
3477 the previously set parameters are now signed.
3479 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3480 negative error value.
3483 @subheading gnutls_x509_crt_verify
3484 @anchor{gnutls_x509_crt_verify}
3485 @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})
3486 @var{cert}: is the certificate to be verified
3488 @var{CA_list}: is one certificate that is considered to be trusted one
3490 @var{CA_list_length}: holds the number of CA certificate in CA_list
3492 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3494 @var{verify}: will hold the certificate verification output.
3496 This function will try to verify the given certificate and return
3499 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3500 negative error value.
3503 @subheading gnutls_x509_dn_deinit
3504 @anchor{gnutls_x509_dn_deinit}
3505 @deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn})
3506 @var{dn}: a DN uint8_t object pointer.
3508 This function deallocates the DN object as returned by
3509 @code{gnutls_x509_dn_import()} .
3511 @strong{Since:} 2.4.0
3514 @subheading gnutls_x509_dn_export
3515 @anchor{gnutls_x509_dn_export}
3516 @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})
3517 @var{dn}: Holds the uint8_t DN object
3519 @var{format}: the format of output params. One of PEM or DER.
3521 @var{output_data}: will contain a DN PEM or DER encoded
3523 @var{output_data_size}: holds the size of output_data (and will be
3524 replaced by the actual size of parameters)
3526 This function will export the DN to DER or PEM format.
3528 If the buffer provided is not long enough to hold the output, then
3529 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
3532 If the structure is PEM encoded, it will have a header
3535 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3536 negative error value.
3539 @subheading gnutls_x509_dn_get_rdn_ava
3540 @anchor{gnutls_x509_dn_get_rdn_ava}
3541 @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})
3542 @var{dn}: input variable with uint8_t DN pointer
3544 @var{irdn}: index of RDN
3546 @var{iava}: index of AVA.
3548 @var{ava}: Pointer to structure which will hold output information.
3550 Get pointers to data within the DN.
3552 Note that @code{ava} will contain pointers into the @code{dn} structure, so you
3553 should not modify any data or deallocate it. Note also that the DN
3554 in turn points into the original certificate structure, and thus
3555 you may not deallocate the certificate and continue to access @code{dn} .
3557 @strong{Returns:} Returns 0 on success, or an error code.
3560 @subheading gnutls_x509_dn_import
3561 @anchor{gnutls_x509_dn_import}
3562 @deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data})
3563 @var{dn}: the structure that will hold the imported DN
3565 @var{data}: should contain a DER encoded RDN sequence
3567 This function parses an RDN sequence and stores the result to a
3568 @code{gnutls_x509_dn_t} structure. The structure must have been initialized
3569 with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to
3572 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3573 negative error value.
3575 @strong{Since:} 2.4.0
3578 @subheading gnutls_x509_dn_init
3579 @anchor{gnutls_x509_dn_init}
3580 @deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn})
3581 @var{dn}: the object to be initialized
3583 This function initializes a @code{gnutls_x509_dn_t} structure.
3585 The object returned must be deallocated using
3586 @code{gnutls_x509_dn_deinit()} .
3588 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3589 negative error value.
3591 @strong{Since:} 2.4.0
3594 @subheading gnutls_x509_dn_oid_known
3595 @anchor{gnutls_x509_dn_oid_known}
3596 @deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid})
3597 @var{oid}: holds an Object Identifier in a null terminated string
3599 This function will inform about known DN OIDs. This is useful since
3600 functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information
3601 on known OIDs to properly encode their input. Object Identifiers
3602 that are not known are not encoded by these functions, and their
3603 input is stored directly into the ASN.1 structure. In that case of
3604 unknown OIDs, you have the responsibility of DER encoding your
3607 @strong{Returns:} 1 on known OIDs and 0 otherwise.
3610 @subheading gnutls_x509_dn_oid_name
3611 @anchor{gnutls_x509_dn_oid_name}
3612 @deftypefun {const char*} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags})
3613 @var{oid}: holds an Object Identifier in a null terminated string
3615 @var{flags}: 0 or @code{GNUTLS_X509_DN_OID_} *
3617 This function will return the name of a known DN OID. If
3618 @code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function
3619 will return the given OID if no descriptive name has been
3622 @strong{Returns:} A null terminated string or NULL otherwise.
3627 @subheading gnutls_x509_privkey_cpy
3628 @anchor{gnutls_x509_privkey_cpy}
3629 @deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src})
3630 @var{dst}: The destination key, which should be initialized.
3632 @var{src}: The source key
3634 This function will copy a private key from source to destination
3635 key. Destination has to be initialized.
3637 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3638 negative error value.
3641 @subheading gnutls_x509_privkey_deinit
3642 @anchor{gnutls_x509_privkey_deinit}
3643 @deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key})
3644 @var{key}: The structure to be deinitialized
3646 This function will deinitialize a private key structure.
3649 @subheading gnutls_x509_privkey_export
3650 @anchor{gnutls_x509_privkey_export}
3651 @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})
3652 @var{key}: Holds the key
3654 @var{format}: the format of output params. One of PEM or DER.
3656 @var{output_data}: will contain a private key PEM or DER encoded
3658 @var{output_data_size}: holds the size of output_data (and will be
3659 replaced by the actual size of parameters)
3661 This function will export the private key to a PKCS1 structure for
3662 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
3663 the same format with the parameters used by openssl.
3665 If the buffer provided is not long enough to hold the output, then
3666 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
3669 If the structure is PEM encoded, it will have a header
3670 of "BEGIN RSA PRIVATE KEY".
3672 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3673 negative error value.
3676 @subheading gnutls_x509_privkey_export_dsa_raw
3677 @anchor{gnutls_x509_privkey_export_dsa_raw}
3678 @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})
3679 @var{key}: a structure that holds the DSA parameters
3681 @var{p}: will hold the p
3683 @var{q}: will hold the q
3685 @var{g}: will hold the g
3687 @var{y}: will hold the y
3689 @var{x}: will hold the x
3691 This function will export the DSA private key's parameters found
3692 in the given structure. The new parameters will be allocated using
3693 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3695 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3696 negative error value.
3699 @subheading gnutls_x509_privkey_export_ecc_raw
3700 @anchor{gnutls_x509_privkey_export_ecc_raw}
3701 @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})
3702 @var{key}: a structure that holds the rsa parameters
3704 @var{curve}: will hold the curve
3706 @var{x}: will hold the x coordinate
3708 @var{y}: will hold the y coordinate
3710 @var{k}: will hold the private key
3712 This function will export the ECC private key's parameters found
3713 in the given structure. The new parameters will be allocated using
3714 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3716 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3717 negative error value.
3722 @subheading gnutls_x509_privkey_export_pkcs8
3723 @anchor{gnutls_x509_privkey_export_pkcs8}
3724 @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})
3725 @var{key}: Holds the key
3727 @var{format}: the format of output params. One of PEM or DER.
3729 @var{password}: the password that will be used to encrypt the key.
3731 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3733 @var{output_data}: will contain a private key PEM or DER encoded
3735 @var{output_data_size}: holds the size of output_data (and will be
3736 replaced by the actual size of parameters)
3738 This function will export the private key to a PKCS8 structure.
3739 Both RSA and DSA keys can be exported. For DSA keys we use
3740 PKCS @code{11} definitions. If the flags do not specify the encryption
3741 cipher, then the default 3DES (PBES2) will be used.
3743 The @code{password} can be either ASCII or UTF-8 in the default PBES2
3744 encryption schemas, or ASCII for the PKCS12 schemas.
3746 If the buffer provided is not long enough to hold the output, then
3747 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3750 If the structure is PEM encoded, it will have a header
3751 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
3752 encryption is not used.
3754 @strong{Returns:} In case of failure a negative error code will be
3755 returned, and 0 on success.
3758 @subheading gnutls_x509_privkey_export_rsa_raw
3759 @anchor{gnutls_x509_privkey_export_rsa_raw}
3760 @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})
3761 @var{key}: a structure that holds the rsa parameters
3763 @var{m}: will hold the modulus
3765 @var{e}: will hold the public exponent
3767 @var{d}: will hold the private exponent
3769 @var{p}: will hold the first prime (p)
3771 @var{q}: will hold the second prime (q)
3773 @var{u}: will hold the coefficient
3775 This function will export the RSA private key's parameters found
3776 in the given structure. The new parameters will be allocated using
3777 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3779 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3780 negative error value.
3783 @subheading gnutls_x509_privkey_export_rsa_raw2
3784 @anchor{gnutls_x509_privkey_export_rsa_raw2}
3785 @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})
3786 @var{key}: a structure that holds the rsa parameters
3788 @var{m}: will hold the modulus
3790 @var{e}: will hold the public exponent
3792 @var{d}: will hold the private exponent
3794 @var{p}: will hold the first prime (p)
3796 @var{q}: will hold the second prime (q)
3798 @var{u}: will hold the coefficient
3800 @var{e1}: will hold e1 = d mod (p-1)
3802 @var{e2}: will hold e2 = d mod (q-1)
3804 This function will export the RSA private key's parameters found
3805 in the given structure. The new parameters will be allocated using
3806 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3808 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3809 negative error value.
3811 @strong{Since:} 2.12.0
3814 @subheading gnutls_x509_privkey_fix
3815 @anchor{gnutls_x509_privkey_fix}
3816 @deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key})
3817 @var{key}: Holds the key
3819 This function will recalculate the secondary parameters in a key.
3820 In RSA keys, this can be the coefficient and exponent1,2.
3822 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3823 negative error value.
3826 @subheading gnutls_x509_privkey_generate
3827 @anchor{gnutls_x509_privkey_generate}
3828 @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})
3829 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
3831 @var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .
3833 @var{bits}: the size of the modulus
3835 @var{flags}: unused for now. Must be 0.
3837 This function will generate a random private key. Note that this
3838 function must be called on an empty private key.
3840 Do not set the number of bits directly, use @code{gnutls_sec_param_to_pk_bits()} .
3842 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3843 negative error value.
3846 @subheading gnutls_x509_privkey_get_key_id
3847 @anchor{gnutls_x509_privkey_get_key_id}
3848 @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})
3849 @var{key}: Holds the key
3851 @var{flags}: should be 0 for now
3853 @var{output_data}: will contain the key ID
3855 @var{output_data_size}: holds the size of output_data (and will be
3856 replaced by the actual size of parameters)
3858 This function will return a unique ID the depends on the public key
3859 parameters. This ID can be used in checking whether a certificate
3860 corresponds to the given key.
3862 If the buffer provided is not long enough to hold the output, then
3863 * @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
3864 be returned. The output will normally be a SHA-1 hash output,
3867 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3868 negative error value.
3871 @subheading gnutls_x509_privkey_get_pk_algorithm
3872 @anchor{gnutls_x509_privkey_get_pk_algorithm}
3873 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key})
3874 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
3876 This function will return the public key algorithm of a private
3879 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3880 success, or a negative error code on error.
3883 @subheading gnutls_x509_privkey_import
3884 @anchor{gnutls_x509_privkey_import}
3885 @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})
3886 @var{key}: The structure to store the parsed key
3888 @var{data}: The DER or PEM encoded certificate.
3890 @var{format}: One of DER or PEM
3892 This function will convert the given DER or PEM encoded key to the
3893 native @code{gnutls_x509_privkey_t} format. The output will be stored in
3896 If the key is PEM encoded it should have a header of "RSA PRIVATE
3897 KEY", or "DSA PRIVATE KEY".
3899 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3900 negative error value.
3903 @subheading gnutls_x509_privkey_import_dsa_raw
3904 @anchor{gnutls_x509_privkey_import_dsa_raw}
3905 @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})
3906 @var{key}: The structure to store the parsed key
3908 @var{p}: holds the p
3910 @var{q}: holds the q
3912 @var{g}: holds the g
3914 @var{y}: holds the y
3916 @var{x}: holds the x
3918 This function will convert the given DSA raw parameters to the
3919 native @code{gnutls_x509_privkey_t} format. The output will be stored
3922 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3923 negative error value.
3926 @subheading gnutls_x509_privkey_import_ecc_raw
3927 @anchor{gnutls_x509_privkey_import_ecc_raw}
3928 @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})
3929 @var{key}: The structure to store the parsed key
3931 @var{curve}: holds the curve
3933 @var{x}: holds the x
3935 @var{y}: holds the y
3937 @var{k}: holds the k
3939 This function will convert the given elliptic curve parameters to the
3940 native @code{gnutls_x509_privkey_t} format. The output will be stored
3943 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3944 negative error value.
3949 @subheading gnutls_x509_privkey_import_pkcs8
3950 @anchor{gnutls_x509_privkey_import_pkcs8}
3951 @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})
3952 @var{key}: The structure to store the parsed key
3954 @var{data}: The DER or PEM encoded key.
3956 @var{format}: One of DER or PEM
3958 @var{password}: the password to decrypt the key (if it is encrypted).
3960 @var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
3962 This function will convert the given DER or PEM encoded PKCS8 2.0
3963 encrypted key to the native gnutls_x509_privkey_t format. The
3964 output will be stored in @code{key} . Both RSA and DSA keys can be
3965 imported, and flags can only be used to indicate an unencrypted
3968 The @code{password} can be either ASCII or UTF-8 in the default PBES2
3969 encryption schemas, or ASCII for the PKCS12 schemas.
3971 If the Certificate is PEM encoded it should have a header of
3972 "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to
3973 specify the flags if the key is DER encoded, since in that case
3974 the encryption status cannot be auto-detected.
3976 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
3977 negative error value.
3980 @subheading gnutls_x509_privkey_import_rsa_raw
3981 @anchor{gnutls_x509_privkey_import_rsa_raw}
3982 @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})
3983 @var{key}: The structure to store the parsed key
3985 @var{m}: holds the modulus
3987 @var{e}: holds the public exponent
3989 @var{d}: holds the private exponent
3991 @var{p}: holds the first prime (p)
3993 @var{q}: holds the second prime (q)
3995 @var{u}: holds the coefficient
3997 This function will convert the given RSA raw parameters to the
3998 native @code{gnutls_x509_privkey_t} format. The output will be stored in
4001 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4002 negative error value.
4005 @subheading gnutls_x509_privkey_import_rsa_raw2
4006 @anchor{gnutls_x509_privkey_import_rsa_raw2}
4007 @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})
4008 @var{key}: The structure to store the parsed key
4010 @var{m}: holds the modulus
4012 @var{e}: holds the public exponent
4014 @var{d}: holds the private exponent
4016 @var{p}: holds the first prime (p)
4018 @var{q}: holds the second prime (q)
4020 @var{u}: holds the coefficient
4022 @var{e1}: holds e1 = d mod (p-1)
4024 @var{e2}: holds e2 = d mod (q-1)
4026 This function will convert the given RSA raw parameters to the
4027 native @code{gnutls_x509_privkey_t} format. The output will be stored in
4030 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4031 negative error value.
4034 @subheading gnutls_x509_privkey_init
4035 @anchor{gnutls_x509_privkey_init}
4036 @deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key})
4037 @var{key}: The structure to be initialized
4039 This function will initialize an private key structure.
4041 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4042 negative error value.
4045 @subheading gnutls_x509_privkey_sec_param
4046 @anchor{gnutls_x509_privkey_sec_param}
4047 @deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key})
4048 @var{key}: a key structure
4050 This function will return the security parameter appropriate with
4053 @strong{Returns:} On success, a valid security parameter is returned otherwise
4054 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
4056 @strong{Since:} 2.12.0
4059 @subheading gnutls_x509_privkey_verify_params
4060 @anchor{gnutls_x509_privkey_verify_params}
4061 @deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key})
4062 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
4064 This function will verify the private key parameters.
4066 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4067 negative error value.
4070 @subheading gnutls_x509_rdn_get
4071 @anchor{gnutls_x509_rdn_get}
4072 @deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{sizeof_buf})
4073 @var{idn}: should contain a DER encoded RDN sequence
4075 @var{buf}: a pointer to a structure to hold the peer's name
4077 @var{sizeof_buf}: holds the size of @code{buf}
4079 This function will return the name of the given RDN sequence. The
4080 name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
4083 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
4084 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{sizeof_buf} is
4085 updated if the provided buffer is not long enough, otherwise a
4086 negative error value.
4089 @subheading gnutls_x509_rdn_get_by_oid
4090 @anchor{gnutls_x509_rdn_get_by_oid}
4091 @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{sizeof_buf})
4092 @var{idn}: should contain a DER encoded RDN sequence
4094 @var{oid}: an Object Identifier
4096 @var{indx}: In case multiple same OIDs exist in the RDN indicates which
4097 to send. Use 0 for the first one.
4099 @var{raw_flag}: If non (0) then the raw DER data are returned.
4101 @var{buf}: a pointer to a structure to hold the peer's name
4103 @var{sizeof_buf}: holds the size of @code{buf}
4105 This function will return the name of the given Object identifier,
4106 of the RDN sequence. The name will be encoded using the rules
4109 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
4110 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{sizeof_buf} is
4111 updated if the provided buffer is not long enough, otherwise a
4112 negative error value.
4115 @subheading gnutls_x509_rdn_get_oid
4116 @anchor{gnutls_x509_rdn_get_oid}
4117 @deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, int @var{indx}, void * @var{buf}, size_t * @var{sizeof_buf})
4118 @var{idn}: should contain a DER encoded RDN sequence
4120 @var{indx}: Indicates which OID to return. Use 0 for the first one.
4122 @var{buf}: a pointer to a structure to hold the peer's name OID
4124 @var{sizeof_buf}: holds the size of @code{buf}
4126 This function will return the specified Object identifier, of the
4129 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or
4130 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{sizeof_buf} is
4131 updated if the provided buffer is not long enough, otherwise a
4132 negative error value.
4134 @strong{Since:} 2.4.0
4137 @subheading gnutls_x509_trust_list_add_cas
4138 @anchor{gnutls_x509_trust_list_add_cas}
4139 @deftypefun {int} {gnutls_x509_trust_list_add_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, int @var{clist_size}, unsigned int @var{flags})
4140 @var{list}: The structure of the list
4142 @var{clist}: A list of CAs
4144 @var{clist_size}: The length of the CA list
4146 @var{flags}: should be 0.
4148 This function will add the given certificate authorities
4149 to the trusted list. The list of CAs must not be deinitialized
4150 during this structure's lifetime.
4152 @strong{Returns:} The number of added elements is returned.
4157 @subheading gnutls_x509_trust_list_add_crls
4158 @anchor{gnutls_x509_trust_list_add_crls}
4159 @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})
4160 @var{list}: The structure of the list
4162 @var{crl_list}: A list of CRLs
4164 @var{crl_size}: The length of the CRL list
4166 @var{flags}: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
4168 @var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
4170 This function will add the given certificate revocation lists
4171 to the trusted list. The list of CRLs must not be deinitialized
4172 during this structure's lifetime.
4174 This function must be called after @code{gnutls_x509_trust_list_add_cas()}
4175 to allow verifying the CRLs for validity.
4177 @strong{Returns:} The number of added elements is returned.
4182 @subheading gnutls_x509_trust_list_add_named_crt
4183 @anchor{gnutls_x509_trust_list_add_named_crt}
4184 @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})
4185 @var{list}: The structure of the list
4187 @var{cert}: A certificate
4189 @var{name}: An identifier for the certificate
4191 @var{name_size}: The size of the identifier
4193 @var{flags}: should be 0.
4195 This function will add the given certificate to the trusted
4196 list and associate it with a name. The certificate will not be
4197 be used for verification with @code{gnutls_x509_trust_list_verify_crt()}
4198 but only with @code{gnutls_x509_trust_list_verify_named_crt()} .
4200 In principle this function can be used to set individual "server"
4201 certificates that are trusted by the user for that specific server
4202 but for no other purposes.
4204 The certificate must not be deinitialized during the lifetime
4205 of the trusted list.
4207 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4208 negative error value.
4213 @subheading gnutls_x509_trust_list_add_system_trust
4214 @anchor{gnutls_x509_trust_list_add_system_trust}
4215 @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})
4216 @var{list}: The structure of the list
4218 @var{tl_flags}: GNUTLS_TL_*
4220 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
4222 This function adds the system's default trusted certificate
4223 authorities to the trusted list.
4225 @strong{Returns:} The number of added elements is returned.
4230 @subheading gnutls_x509_trust_list_add_trust_file
4231 @anchor{gnutls_x509_trust_list_add_trust_file}
4232 @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})
4233 @var{list}: The structure of the list
4235 @var{ca_file}: A file containing a list of CAs (optional)
4237 @var{crl_file}: A file containing a list of CRLs (optional)
4239 @var{type}: The format of the certificates
4241 @var{tl_flags}: GNUTLS_TL_*
4243 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
4245 This function will add the given certificate authorities
4246 to the trusted list. pkcs11 URLs are also accepted, instead
4247 of files, by this function.
4249 @strong{Returns:} The number of added elements is returned.
4254 @subheading gnutls_x509_trust_list_add_trust_mem
4255 @anchor{gnutls_x509_trust_list_add_trust_mem}
4256 @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})
4257 @var{list}: The structure of the list
4259 @var{cas}: -- undescribed --
4261 @var{crls}: -- undescribed --
4263 @var{type}: The format of the certificates
4265 @var{tl_flags}: GNUTLS_TL_*
4267 @var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
4269 This function will add the given certificate authorities
4270 to the trusted list.
4272 @strong{Returns:} The number of added elements is returned.
4277 @subheading gnutls_x509_trust_list_deinit
4278 @anchor{gnutls_x509_trust_list_deinit}
4279 @deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all})
4280 @var{list}: The structure to be deinitialized
4282 @var{all}: if non-(0) it will deinitialize all the certificates and CRLs contained in the structure.
4284 This function will deinitialize a trust list.
4289 @subheading gnutls_x509_trust_list_get_issuer
4290 @anchor{gnutls_x509_trust_list_get_issuer}
4291 @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})
4292 @var{list}: The structure of the list
4294 @var{cert}: is the certificate to find issuer for
4296 @var{issuer}: Will hold the issuer if any. Should be treated as constant.
4298 @var{flags}: Use (0).
4300 This function will attempt to find the issuer of the
4303 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4304 negative error value.
4309 @subheading gnutls_x509_trust_list_init
4310 @anchor{gnutls_x509_trust_list_init}
4311 @deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size})
4312 @var{list}: The structure to be initialized
4314 @var{size}: The size of the internal hash table. Use (0) for default size.
4316 This function will initialize an X.509 trust list structure.
4318 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4319 negative error value.
4324 @subheading gnutls_x509_trust_list_verify_crt
4325 @anchor{gnutls_x509_trust_list_verify_crt}
4326 @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{verify}, gnutls_verify_output_function @var{func})
4327 @var{list}: The structure of the list
4329 @var{cert_list}: is the certificate list to be verified
4331 @var{cert_list_size}: is the certificate list size
4333 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
4335 @var{verify}: will hold the certificate verification output.
4337 @var{func}: If non-null will be called on each chain element verification with the output.
4339 This function will try to verify the given certificate and return
4342 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4343 negative error value.
4348 @subheading gnutls_x509_trust_list_verify_named_crt
4349 @anchor{gnutls_x509_trust_list_verify_named_crt}
4350 @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{verify}, gnutls_verify_output_function @var{func})
4351 @var{list}: The structure of the list
4353 @var{cert}: is the certificate to be verified
4355 @var{name}: is the certificate's name
4357 @var{name_size}: is the certificate's name size
4359 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
4361 @var{verify}: will hold the certificate verification output.
4363 @var{func}: If non-null will be called on each chain element verification with the output.
4365 This function will try to find a matching named certificate. If a
4366 match is found the certificate is considered valid. In addition to that
4367 this function will also check CRLs.
4369 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
4370 negative error value.