5 @subheading gnutls_pkcs12_bag_decrypt
6 @anchor{gnutls_pkcs12_bag_decrypt}
7 @deftypefun {int} {gnutls_pkcs12_bag_decrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass})
10 @var{pass}: The password used for encryption, must be ASCII.
12 This function will decrypt the given encrypted bag and return 0 on
15 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
16 otherwise an error code is returned.
19 @subheading gnutls_pkcs12_bag_deinit
20 @anchor{gnutls_pkcs12_bag_deinit}
21 @deftypefun {void} {gnutls_pkcs12_bag_deinit} (gnutls_pkcs12_bag_t @var{bag})
22 @var{bag}: The structure to be initialized
24 This function will deinitialize a PKCS12 Bag structure.
27 @subheading gnutls_pkcs12_bag_encrypt
28 @anchor{gnutls_pkcs12_bag_encrypt}
29 @deftypefun {int} {gnutls_pkcs12_bag_encrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass}, unsigned int @var{flags})
32 @var{pass}: The password used for encryption, must be ASCII
34 @var{flags}: should be one of @code{gnutls_pkcs_encrypt_flags_t} elements bitwise or'd
36 This function will encrypt the given bag.
38 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
39 otherwise an error code is returned.
42 @subheading gnutls_pkcs12_bag_get_count
43 @anchor{gnutls_pkcs12_bag_get_count}
44 @deftypefun {int} {gnutls_pkcs12_bag_get_count} (gnutls_pkcs12_bag_t @var{bag})
47 This function will return the number of the elements withing the bag.
49 @strong{Returns:} Number of elements in bag, or an negative error code on
53 @subheading gnutls_pkcs12_bag_get_data
54 @anchor{gnutls_pkcs12_bag_get_data}
55 @deftypefun {int} {gnutls_pkcs12_bag_get_data} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, gnutls_datum_t * @var{data})
58 @var{indx}: The element of the bag to get the data from
60 @var{data}: where the bag's data will be. Should be treated as constant.
62 This function will return the bag's data. The data is a constant
63 that is stored into the bag. Should not be accessed after the bag
66 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
70 @subheading gnutls_pkcs12_bag_get_friendly_name
71 @anchor{gnutls_pkcs12_bag_get_friendly_name}
72 @deftypefun {int} {gnutls_pkcs12_bag_get_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, char ** @var{name})
75 @var{indx}: The bag's element to add the id
77 @var{name}: will hold a pointer to the name (to be treated as const)
79 This function will return the friendly name, of the specified bag
80 element. The key ID is usually used to distinguish the local
81 private key and the certificate pair.
83 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
84 negative error value. or a negative value on error.
87 @subheading gnutls_pkcs12_bag_get_key_id
88 @anchor{gnutls_pkcs12_bag_get_key_id}
89 @deftypefun {int} {gnutls_pkcs12_bag_get_key_id} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, gnutls_datum_t * @var{id})
92 @var{indx}: The bag's element to add the id
94 @var{id}: where the ID will be copied (to be treated as const)
96 This function will return the key ID, of the specified bag element.
97 The key ID is usually used to distinguish the local private key and
100 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
101 negative error value. or a negative value on error.
104 @subheading gnutls_pkcs12_bag_get_type
105 @anchor{gnutls_pkcs12_bag_get_type}
106 @deftypefun {gnutls_pkcs12_bag_type_t} {gnutls_pkcs12_bag_get_type} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx})
109 @var{indx}: The element of the bag to get the type
111 This function will return the bag's type.
113 @strong{Returns:} One of the @code{gnutls_pkcs12_bag_type_t} enumerations.
116 @subheading gnutls_pkcs12_bag_init
117 @anchor{gnutls_pkcs12_bag_init}
118 @deftypefun {int} {gnutls_pkcs12_bag_init} (gnutls_pkcs12_bag_t * @var{bag})
119 @var{bag}: The structure to be initialized
121 This function will initialize a PKCS12 bag structure. PKCS12 Bags
122 usually contain private keys, lists of X.509 Certificates and X.509
123 Certificate revocation lists.
125 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
126 negative error value.
129 @subheading gnutls_pkcs12_bag_set_crl
130 @anchor{gnutls_pkcs12_bag_set_crl}
131 @deftypefun {int} {gnutls_pkcs12_bag_set_crl} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crl_t @var{crl})
134 @var{crl}: the CRL to be copied.
136 This function will insert the given CRL into the
137 bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()}.
139 @strong{Returns:} the index of the added bag on success, or a negative value
143 @subheading gnutls_pkcs12_bag_set_crt
144 @anchor{gnutls_pkcs12_bag_set_crt}
145 @deftypefun {int} {gnutls_pkcs12_bag_set_crt} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crt_t @var{crt})
148 @var{crt}: the certificate to be copied.
150 This function will insert the given certificate into the
151 bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()}.
153 @strong{Returns:} the index of the added bag on success, or a negative
157 @subheading gnutls_pkcs12_bag_set_data
158 @anchor{gnutls_pkcs12_bag_set_data}
159 @deftypefun {int} {gnutls_pkcs12_bag_set_data} (gnutls_pkcs12_bag_t @var{bag}, gnutls_pkcs12_bag_type_t @var{type}, const gnutls_datum_t * @var{data})
162 @var{type}: The data's type
164 @var{data}: the data to be copied.
166 This function will insert the given data of the given type into
169 @strong{Returns:} the index of the added bag on success, or a negative
173 @subheading gnutls_pkcs12_bag_set_friendly_name
174 @anchor{gnutls_pkcs12_bag_set_friendly_name}
175 @deftypefun {int} {gnutls_pkcs12_bag_set_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, const char * @var{name})
178 @var{indx}: The bag's element to add the id
182 This function will add the given key friendly name, to the
183 specified, by the index, bag element. The name will be encoded as
184 a 'Friendly name' bag attribute, which is usually used to set a
185 user name to the local private key and the certificate pair.
187 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
188 negative error value. or a negative value on error.
191 @subheading gnutls_pkcs12_bag_set_key_id
192 @anchor{gnutls_pkcs12_bag_set_key_id}
193 @deftypefun {int} {gnutls_pkcs12_bag_set_key_id} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, const gnutls_datum_t * @var{id})
196 @var{indx}: The bag's element to add the id
200 This function will add the given key ID, to the specified, by the
201 index, bag element. The key ID will be encoded as a 'Local key
202 identifier' bag attribute, which is usually used to distinguish
203 the local private key and the certificate pair.
205 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
206 negative error value. or a negative value on error.
209 @subheading gnutls_pkcs12_deinit
210 @anchor{gnutls_pkcs12_deinit}
211 @deftypefun {void} {gnutls_pkcs12_deinit} (gnutls_pkcs12_t @var{pkcs12})
212 @var{pkcs12}: The structure to be initialized
214 This function will deinitialize a PKCS12 structure.
217 @subheading gnutls_pkcs12_export
218 @anchor{gnutls_pkcs12_export}
219 @deftypefun {int} {gnutls_pkcs12_export} (gnutls_pkcs12_t @var{pkcs12}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
220 @var{pkcs12}: Holds the pkcs12 structure
222 @var{format}: the format of output params. One of PEM or DER.
224 @var{output_data}: will contain a structure PEM or DER encoded
226 @var{output_data_size}: holds the size of output_data (and will be
227 replaced by the actual size of parameters)
229 This function will export the pkcs12 structure to DER or PEM format.
231 If the buffer provided is not long enough to hold the output, then
232 *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
235 If the structure is PEM encoded, it will have a header
238 @strong{Return value:} In case of failure a negative value will be
239 returned, and 0 on success.
242 @subheading gnutls_pkcs12_generate_mac
243 @anchor{gnutls_pkcs12_generate_mac}
244 @deftypefun {int} {gnutls_pkcs12_generate_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
245 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
247 @var{pass}: The password for the MAC
249 This function will generate a MAC for the PKCS12 structure.
251 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
252 negative error value.
255 @subheading gnutls_pkcs12_get_bag
256 @anchor{gnutls_pkcs12_get_bag}
257 @deftypefun {int} {gnutls_pkcs12_get_bag} (gnutls_pkcs12_t @var{pkcs12}, int @var{indx}, gnutls_pkcs12_bag_t @var{bag})
258 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
260 @var{indx}: contains the index of the bag to extract
262 @var{bag}: An initialized bag, where the contents of the bag will be copied
264 This function will return a Bag from the PKCS12 structure.
266 After the last Bag has been read
267 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
269 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
270 negative error value.
273 @subheading gnutls_pkcs12_import
274 @anchor{gnutls_pkcs12_import}
275 @deftypefun {int} {gnutls_pkcs12_import} (gnutls_pkcs12_t @var{pkcs12}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
276 @var{pkcs12}: The structure to store the parsed PKCS12.
278 @var{data}: The DER or PEM encoded PKCS12.
280 @var{format}: One of DER or PEM
282 @var{flags}: an ORed sequence of gnutls_privkey_pkcs8_flags
284 This function will convert the given DER or PEM encoded PKCS12
285 to the native gnutls_pkcs12_t format. The output will be stored in 'pkcs12'.
287 If the PKCS12 is PEM encoded it should have a header of "PKCS12".
289 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
290 negative error value.
293 @subheading gnutls_pkcs12_init
294 @anchor{gnutls_pkcs12_init}
295 @deftypefun {int} {gnutls_pkcs12_init} (gnutls_pkcs12_t * @var{pkcs12})
296 @var{pkcs12}: The structure to be initialized
298 This function will initialize a PKCS12 structure. PKCS12 structures
299 usually contain lists of X.509 Certificates and X.509 Certificate
302 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
303 negative error value.
306 @subheading gnutls_pkcs12_set_bag
307 @anchor{gnutls_pkcs12_set_bag}
308 @deftypefun {int} {gnutls_pkcs12_set_bag} (gnutls_pkcs12_t @var{pkcs12}, gnutls_pkcs12_bag_t @var{bag})
309 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
311 @var{bag}: An initialized bag
313 This function will insert a Bag into the PKCS12 structure.
315 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
316 negative error value.
319 @subheading gnutls_pkcs12_verify_mac
320 @anchor{gnutls_pkcs12_verify_mac}
321 @deftypefun {int} {gnutls_pkcs12_verify_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
322 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
324 @var{pass}: The password for the MAC
326 This function will verify the MAC for the PKCS12 structure.
328 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
329 negative error value.
332 @subheading gnutls_pkcs7_deinit
333 @anchor{gnutls_pkcs7_deinit}
334 @deftypefun {void} {gnutls_pkcs7_deinit} (gnutls_pkcs7_t @var{pkcs7})
335 @var{pkcs7}: The structure to be initialized
337 This function will deinitialize a PKCS7 structure.
340 @subheading gnutls_pkcs7_delete_crl
341 @anchor{gnutls_pkcs7_delete_crl}
342 @deftypefun {int} {gnutls_pkcs7_delete_crl} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
343 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
345 @var{indx}: the index of the crl to delete
347 This function will delete a crl from a PKCS7 or RFC2630 crl set.
348 Index starts from 0. Returns 0 on success.
350 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
351 negative error value.
354 @subheading gnutls_pkcs7_delete_crt
355 @anchor{gnutls_pkcs7_delete_crt}
356 @deftypefun {int} {gnutls_pkcs7_delete_crt} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx})
357 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
359 @var{indx}: the index of the certificate to delete
361 This function will delete a certificate from a PKCS7 or RFC2630
362 certificate set. Index starts from 0. Returns 0 on success.
364 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
365 negative error value.
368 @subheading gnutls_pkcs7_export
369 @anchor{gnutls_pkcs7_export}
370 @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})
371 @var{pkcs7}: Holds the pkcs7 structure
373 @var{format}: the format of output params. One of PEM or DER.
375 @var{output_data}: will contain a structure PEM or DER encoded
377 @var{output_data_size}: holds the size of output_data (and will be
378 replaced by the actual size of parameters)
380 This function will export the pkcs7 structure to DER or PEM format.
382 If the buffer provided is not long enough to hold the output, then
383 *@code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
386 If the structure is PEM encoded, it will have a header
389 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
390 negative error value.
393 @subheading gnutls_pkcs7_get_crl_count
394 @anchor{gnutls_pkcs7_get_crl_count}
395 @deftypefun {int} {gnutls_pkcs7_get_crl_count} (gnutls_pkcs7_t @var{pkcs7})
396 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
398 This function will return the number of certifcates in the PKCS7
401 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
402 negative error value.
405 @subheading gnutls_pkcs7_get_crl_raw
406 @anchor{gnutls_pkcs7_get_crl_raw}
407 @deftypefun {int} {gnutls_pkcs7_get_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{crl}, size_t * @var{crl_size})
408 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
410 @var{indx}: contains the index of the crl to extract
412 @var{crl}: the contents of the crl will be copied there (may be null)
414 @var{crl_size}: should hold the size of the crl
416 This function will return a crl of the PKCS7 or RFC2630 crl set.
418 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
419 negative error value. If the provided buffer is not long enough,
420 then @code{crl_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is
421 returned. After the last crl has been read
422 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
425 @subheading gnutls_pkcs7_get_crt_count
426 @anchor{gnutls_pkcs7_get_crt_count}
427 @deftypefun {int} {gnutls_pkcs7_get_crt_count} (gnutls_pkcs7_t @var{pkcs7})
428 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
430 This function will return the number of certifcates in the PKCS7
431 or RFC2630 certificate set.
433 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
434 negative error value.
437 @subheading gnutls_pkcs7_get_crt_raw
438 @anchor{gnutls_pkcs7_get_crt_raw}
439 @deftypefun {int} {gnutls_pkcs7_get_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, int @var{indx}, void * @var{certificate}, size_t * @var{certificate_size})
440 @var{pkcs7}: should contain a gnutls_pkcs7_t structure
442 @var{indx}: contains the index of the certificate to extract
444 @var{certificate}: the contents of the certificate will be copied
447 @var{certificate_size}: should hold the size of the certificate
449 This function will return a certificate of the PKCS7 or RFC2630
452 After the last certificate has been read
453 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
455 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
456 negative error value. If the provided buffer is not long enough,
457 then @code{certificate_size} is updated and
458 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned.
461 @subheading gnutls_pkcs7_import
462 @anchor{gnutls_pkcs7_import}
463 @deftypefun {int} {gnutls_pkcs7_import} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
464 @var{pkcs7}: The structure to store the parsed PKCS7.
466 @var{data}: The DER or PEM encoded PKCS7.
468 @var{format}: One of DER or PEM
470 This function will convert the given DER or PEM encoded PKCS7 to
471 the native @code{gnutls_pkcs7_t} format. The output will be stored in
474 If the PKCS7 is PEM encoded it should have a header of "PKCS7".
476 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
477 negative error value.
480 @subheading gnutls_pkcs7_init
481 @anchor{gnutls_pkcs7_init}
482 @deftypefun {int} {gnutls_pkcs7_init} (gnutls_pkcs7_t * @var{pkcs7})
483 @var{pkcs7}: The structure to be initialized
485 This function will initialize a PKCS7 structure. PKCS7 structures
486 usually contain lists of X.509 Certificates and X.509 Certificate
489 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
490 negative error value.
493 @subheading gnutls_pkcs7_set_crl_raw
494 @anchor{gnutls_pkcs7_set_crl_raw}
495 @deftypefun {int} {gnutls_pkcs7_set_crl_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crl})
496 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
498 @var{crl}: the DER encoded crl to be added
500 This function will add a crl to the PKCS7 or RFC2630 crl set.
502 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
503 negative error value.
506 @subheading gnutls_pkcs7_set_crl
507 @anchor{gnutls_pkcs7_set_crl}
508 @deftypefun {int} {gnutls_pkcs7_set_crl} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crl_t @var{crl})
509 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
511 @var{crl}: the DER encoded crl to be added
513 This function will add a parsed CRL to the PKCS7 or RFC2630 crl
516 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
517 negative error value.
520 @subheading gnutls_pkcs7_set_crt_raw
521 @anchor{gnutls_pkcs7_set_crt_raw}
522 @deftypefun {int} {gnutls_pkcs7_set_crt_raw} (gnutls_pkcs7_t @var{pkcs7}, const gnutls_datum_t * @var{crt})
523 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
525 @var{crt}: the DER encoded certificate to be added
527 This function will add a certificate to the PKCS7 or RFC2630
530 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
531 negative error value.
534 @subheading gnutls_pkcs7_set_crt
535 @anchor{gnutls_pkcs7_set_crt}
536 @deftypefun {int} {gnutls_pkcs7_set_crt} (gnutls_pkcs7_t @var{pkcs7}, gnutls_x509_crt_t @var{crt})
537 @var{pkcs7}: should contain a @code{gnutls_pkcs7_t} structure
539 @var{crt}: the certificate to be copied.
541 This function will add a parsed certificate to the PKCS7 or
542 RFC2630 certificate set. This is a wrapper function over
543 @code{gnutls_pkcs7_set_crt_raw()} .
545 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
546 negative error value.
549 @subheading gnutls_x509_crl_check_issuer
550 @anchor{gnutls_x509_crl_check_issuer}
551 @deftypefun {int} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{cert}, gnutls_x509_crt_t @var{issuer})
552 @var{issuer}: is the certificate of a possible issuer
554 This function will check if the given CRL was issued by the given
555 issuer certificate. It will return true (1) if the given CRL was
556 issued by the given issuer, and false (0) if not.
558 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
559 negative error value.
562 @subheading gnutls_x509_crl_deinit
563 @anchor{gnutls_x509_crl_deinit}
564 @deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl})
565 @var{crl}: The structure to be initialized
567 This function will deinitialize a CRL structure.
570 @subheading gnutls_x509_crl_export
571 @anchor{gnutls_x509_crl_export}
572 @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})
573 @var{crl}: Holds the revocation list
575 @var{format}: the format of output params. One of PEM or DER.
577 @var{output_data}: will contain a private key PEM or DER encoded
579 @var{output_data_size}: holds the size of output_data (and will
580 be replaced by the actual size of parameters)
582 This function will export the revocation list to DER or PEM format.
584 If the buffer provided is not long enough to hold the output, then
585 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
587 If the structure is PEM encoded, it will have a header
590 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
591 negative error value. and a negative value on failure.
594 @subheading gnutls_x509_crl_get_authority_key_id
595 @anchor{gnutls_x509_crl_get_authority_key_id}
596 @deftypefun {int} {gnutls_x509_crl_get_authority_key_id} (gnutls_x509_crl_t @var{crl}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical})
597 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
599 @var{ret}: The place where the identifier will be copied
601 @var{ret_size}: Holds the size of the result field.
603 @var{critical}: will be non zero if the extension is marked as critical
606 This function will return the CRL authority's key identifier. This
607 is obtained by the X.509 Authority Key identifier extension field
608 (2.5.29.35). Note that this function only returns the
609 keyIdentifier field of the extension.
611 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
612 negative value in case of an error.
614 @strong{Since:} 2.8.0
617 @subheading gnutls_x509_crl_get_crt_count
618 @anchor{gnutls_x509_crl_get_crt_count}
619 @deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl})
620 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
622 This function will return the number of revoked certificates in the
625 @strong{Returns:} number of certificates, a negative value on failure.
628 @subheading gnutls_x509_crl_get_crt_serial
629 @anchor{gnutls_x509_crl_get_crt_serial}
630 @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})
631 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
633 @var{indx}: the index of the certificate to extract (starting from 0)
635 @var{serial}: where the serial number will be copied
637 @var{serial_size}: initially holds the size of serial
639 @var{t}: if non null, will hold the time this certificate was revoked
641 This function will retrieve the serial number of the specified, by
642 the index, revoked certificate.
644 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
645 negative error value. and a negative value on error.
648 @subheading gnutls_x509_crl_get_dn_oid
649 @anchor{gnutls_x509_crl_get_dn_oid}
650 @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})
651 @var{crl}: should contain a gnutls_x509_crl_t structure
653 @var{indx}: Specifies which DN OID to send. Use zero to get the first one.
655 @var{oid}: a pointer to a structure to hold the name (may be null)
657 @var{sizeof_oid}: initially holds the size of 'oid'
659 This function will extract the requested OID of the name of the CRL
660 issuer, specified by the given index.
662 If oid is null then only the size will be filled.
664 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
665 not long enough, and in that case the sizeof_oid will be updated
666 with the required size. On success 0 is returned.
669 @subheading gnutls_x509_crl_get_extension_data
670 @anchor{gnutls_x509_crl_get_extension_data}
671 @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})
672 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
674 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
676 @var{data}: a pointer to a structure to hold the data (may be null)
678 @var{sizeof_data}: initially holds the size of @code{oid}
680 This function will return the requested extension data in the CRL.
681 The extension data will be stored as a string in the provided
684 Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and
685 critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead,
686 if you want to get data indexed by the extension OID rather than
689 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
690 negative value in case of an error. If your have reached the
691 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
694 @strong{Since:} 2.8.0
697 @subheading gnutls_x509_crl_get_extension_info
698 @anchor{gnutls_x509_crl_get_extension_info}
699 @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}, int * @var{critical})
700 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
702 @var{indx}: Specifies which extension OID to send, use zero to get the first one.
704 @var{oid}: a pointer to a structure to hold the OID
706 @var{sizeof_oid}: initially holds the maximum size of @code{oid}, on return
707 holds actual size of @code{oid}.
709 @var{critical}: output variable with critical flag, may be NULL.
711 This function will return the requested extension OID in the CRL,
712 and the critical flag for it. The extension OID will be stored as
713 a string in the provided buffer. Use
714 @code{gnutls_x509_crl_get_extension_data()} to extract the data.
716 If the buffer provided is not long enough to hold the output, then
717 *@code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
720 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
721 negative value in case of an error. If your have reached the
722 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
725 @strong{Since:} 2.8.0
728 @subheading gnutls_x509_crl_get_extension_oid
729 @anchor{gnutls_x509_crl_get_extension_oid}
730 @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})
731 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
733 @var{indx}: Specifies which extension OID to send, use zero to get the first one.
735 @var{oid}: a pointer to a structure to hold the OID (may be null)
737 @var{sizeof_oid}: initially holds the size of @code{oid}
739 This function will return the requested extension OID in the CRL.
740 The extension OID will be stored as a string in the provided
743 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
744 negative value in case of an error. If your have reached the
745 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
748 @strong{Since:} 2.8.0
751 @subheading gnutls_x509_crl_get_issuer_dn_by_oid
752 @anchor{gnutls_x509_crl_get_issuer_dn_by_oid}
753 @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})
754 @var{crl}: should contain a gnutls_x509_crl_t structure
756 @var{oid}: holds an Object Identified in null terminated string
758 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
760 @var{raw_flag}: If non zero returns the raw DER data of the DN part.
762 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
764 @var{sizeof_buf}: initially holds the size of @code{buf}
766 This function will extract the part of the name of the CRL issuer
767 specified by the given OID. The output will be encoded as described
768 in RFC2253. The output string will be ASCII or UTF-8 encoded,
769 depending on the certificate data.
771 Some helper macros with popular OIDs can be found in gnutls/x509.h
772 If raw flag is zero, this function will only return known OIDs as
773 text. Other OIDs will be DER encoded, as described in RFC2253 -- in
774 hex format with a '\#' prefix. You can check about known OIDs
775 using @code{gnutls_x509_dn_oid_known()}.
777 If buf is null then only the size will be filled.
779 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
780 not long enough, and in that case the sizeof_buf will be updated
781 with the required size, and 0 on success.
784 @subheading gnutls_x509_crl_get_issuer_dn
785 @anchor{gnutls_x509_crl_get_issuer_dn}
786 @deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (const gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf})
787 @var{crl}: should contain a gnutls_x509_crl_t structure
789 @var{buf}: a pointer to a structure to hold the peer's name (may be null)
791 @var{sizeof_buf}: initially holds the size of @code{buf}
793 This function will copy the name of the CRL issuer in the provided
794 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
795 described in RFC2253. The output string will be ASCII or UTF-8
796 encoded, depending on the certificate data.
798 If buf is @code{NULL} then only the size will be filled.
800 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
801 not long enough, and in that case the sizeof_buf will be updated
802 with the required size, and 0 on success.
805 @subheading gnutls_x509_crl_get_next_update
806 @anchor{gnutls_x509_crl_get_next_update}
807 @deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl})
808 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
810 This function will return the time the next CRL will be issued.
811 This field is optional in a CRL so it might be normal to get an
814 @strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error.
817 @subheading gnutls_x509_crl_get_number
818 @anchor{gnutls_x509_crl_get_number}
819 @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})
820 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
822 @var{ret}: The place where the number will be copied
824 @var{ret_size}: Holds the size of the result field.
826 @var{critical}: will be non zero if the extension is marked as critical
829 This function will return the CRL number extension. This is
830 obtained by the CRL Number extension field (2.5.29.20).
832 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
833 negative value in case of an error.
835 @strong{Since:} 2.8.0
838 @subheading gnutls_x509_crl_get_raw_issuer_dn
839 @anchor{gnutls_x509_crl_get_raw_issuer_dn}
840 @deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn})
841 @var{crl}: should contain a gnutls_x509_crl_t structure
843 @var{dn}: will hold the starting point of the DN
845 This function will return a pointer to the DER encoded DN structure
848 @strong{Returns:} a negative value on error, and zero on success.
850 @strong{Since:} 2.12.0
853 @subheading gnutls_x509_crl_get_signature_algorithm
854 @anchor{gnutls_x509_crl_get_signature_algorithm}
855 @deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl})
856 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
858 This function will return a value of the @code{gnutls_sign_algorithm_t}
859 enumeration that is the signature algorithm.
861 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
862 negative error value.
865 @subheading gnutls_x509_crl_get_signature
866 @anchor{gnutls_x509_crl_get_signature}
867 @deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig})
868 @var{crl}: should contain a gnutls_x509_crl_t structure
870 @var{sig}: a pointer where the signature part will be copied (may be null).
872 @var{sizeof_sig}: initially holds the size of @code{sig}
874 This function will extract the signature field of a CRL.
876 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
877 negative error value. and a negative value on error.
880 @subheading gnutls_x509_crl_get_this_update
881 @anchor{gnutls_x509_crl_get_this_update}
882 @deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl})
883 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
885 This function will return the time this CRL was issued.
887 @strong{Returns:} when the CRL was issued, or (time_t)-1 on error.
890 @subheading gnutls_x509_crl_get_version
891 @anchor{gnutls_x509_crl_get_version}
892 @deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl})
893 @var{crl}: should contain a @code{gnutls_x509_crl_t} structure
895 This function will return the version of the specified CRL.
897 @strong{Returns:} The version number, or a negative value on error.
900 @subheading gnutls_x509_crl_import
901 @anchor{gnutls_x509_crl_import}
902 @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})
903 @var{crl}: The structure to store the parsed CRL.
905 @var{data}: The DER or PEM encoded CRL.
907 @var{format}: One of DER or PEM
909 This function will convert the given DER or PEM encoded CRL
910 to the native @code{gnutls_x509_crl_t} format. The output will be stored in 'crl'.
912 If the CRL is PEM encoded it should have a header of "X509 CRL".
914 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
915 negative error value.
918 @subheading gnutls_x509_crl_init
919 @anchor{gnutls_x509_crl_init}
920 @deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl})
921 @var{crl}: The structure to be initialized
923 This function will initialize a CRL structure. CRL stands for
924 Certificate Revocation List. A revocation list usually contains
925 lists of certificate serial numbers that have been revoked by an
926 Authority. The revocation lists are always signed with the
927 authority's private key.
929 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
930 negative error value.
933 @subheading gnutls_x509_crl_print
934 @anchor{gnutls_x509_crl_print}
935 @deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
936 @var{crl}: The structure to be printed
938 @var{format}: Indicate the format to use
940 @var{out}: Newly allocated datum with zero terminated string.
942 This function will pretty print a X.509 certificate revocation
943 list, suitable for display to a human.
945 The output @code{out} needs to be deallocate using @code{gnutls_free()}.
947 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
948 negative error value.
951 @subheading gnutls_x509_crl_privkey_sign
952 @anchor{gnutls_x509_crl_privkey_sign}
953 @deftypefun {int} {gnutls_x509_crl_privkey_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
954 @var{crl}: should contain a gnutls_x509_crl_t structure
956 @var{issuer}: is the certificate of the certificate issuer
958 @var{issuer_key}: holds the issuer's private key
960 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
962 @var{flags}: must be 0
964 This function will sign the CRL with the issuer's private key, and
965 will copy the issuer's information into the CRL.
967 This must be the last step in a certificate CRL since all
968 the previously set parameters are now signed.
970 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
971 negative error value.
974 @subheading gnutls_x509_crl_set_authority_key_id
975 @anchor{gnutls_x509_crl_set_authority_key_id}
976 @deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size})
977 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
981 @var{id_size}: Holds the size of the serial field.
983 This function will set the CRL's authority key ID extension. Only
984 the keyIdentifier field can be set with this function.
986 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
987 negative error value.
989 @strong{Since:} 2.8.0
992 @subheading gnutls_x509_crl_set_crt_serial
993 @anchor{gnutls_x509_crl_set_crt_serial}
994 @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})
995 @var{crl}: should contain a gnutls_x509_crl_t structure
997 @var{serial}: The revoked certificate's serial number
999 @var{serial_size}: Holds the size of the serial field.
1001 @var{revocation_time}: The time this certificate was revoked
1003 This function will set a revoked certificate's serial number to the CRL.
1005 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1006 negative error value.
1009 @subheading gnutls_x509_crl_set_crt
1010 @anchor{gnutls_x509_crl_set_crt}
1011 @deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time})
1012 @var{crl}: should contain a gnutls_x509_crl_t structure
1014 @var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate
1016 @var{revocation_time}: The time this certificate was revoked
1018 This function will set a revoked certificate's serial number to the CRL.
1020 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1021 negative error value.
1024 @subheading gnutls_x509_crl_set_next_update
1025 @anchor{gnutls_x509_crl_set_next_update}
1026 @deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time})
1027 @var{crl}: should contain a gnutls_x509_crl_t structure
1029 @var{exp_time}: The actual time
1031 This function will set the time this CRL will be updated.
1033 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1034 negative error value.
1037 @subheading gnutls_x509_crl_set_number
1038 @anchor{gnutls_x509_crl_set_number}
1039 @deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size})
1040 @var{crl}: a CRL of type @code{gnutls_x509_crl_t}
1042 @var{nr}: The CRL number
1044 @var{nr_size}: Holds the size of the nr field.
1046 This function will set the CRL's number extension.
1048 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1049 negative error value.
1051 @strong{Since:} 2.8.0
1054 @subheading gnutls_x509_crl_set_this_update
1055 @anchor{gnutls_x509_crl_set_this_update}
1056 @deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time})
1057 @var{crl}: should contain a gnutls_x509_crl_t structure
1059 @var{act_time}: The actual time
1061 This function will set the time this CRL was issued.
1063 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1064 negative error value.
1067 @subheading gnutls_x509_crl_set_version
1068 @anchor{gnutls_x509_crl_set_version}
1069 @deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version})
1070 @var{crl}: should contain a gnutls_x509_crl_t structure
1072 @var{version}: holds the version number. For CRLv1 crls must be 1.
1074 This function will set the version of the CRL. This
1075 must be one for CRL version 1, and so on. The CRLs generated
1076 by gnutls should have a version number of 2.
1078 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1079 negative error value.
1082 @subheading gnutls_x509_crl_sign2
1083 @anchor{gnutls_x509_crl_sign2}
1084 @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})
1085 @var{crl}: should contain a gnutls_x509_crl_t structure
1087 @var{issuer}: is the certificate of the certificate issuer
1089 @var{issuer_key}: holds the issuer's private key
1091 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1093 @var{flags}: must be 0
1095 This function will sign the CRL with the issuer's private key, and
1096 will copy the issuer's information into the CRL.
1098 This must be the last step in a certificate CRL since all
1099 the previously set parameters are now signed.
1101 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1102 negative error value.
1104 @strong{Deprecated:} Use @code{gnutls_x509_crl_privkey_sign()} instead.
1107 @subheading gnutls_x509_crl_sign
1108 @anchor{gnutls_x509_crl_sign}
1109 @deftypefun {int} {gnutls_x509_crl_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key})
1110 @var{crl}: should contain a gnutls_x509_crl_t structure
1112 @var{issuer}: is the certificate of the certificate issuer
1114 @var{issuer_key}: holds the issuer's private key
1116 This function is the same a @code{gnutls_x509_crl_sign2()} with no flags, and
1117 SHA1 as the hash algorithm.
1119 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1120 negative error value.
1122 @strong{Deprecated:} Use @code{gnutls_x509_crl_privkey_sign()}.
1125 @subheading gnutls_x509_crl_verify
1126 @anchor{gnutls_x509_crl_verify}
1127 @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})
1128 @var{crl}: is the crl to be verified
1130 @var{CA_list}: is a certificate list that is considered to be trusted one
1132 @var{CA_list_length}: holds the number of CA certificates in CA_list
1134 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1136 @var{verify}: will hold the crl verification output.
1138 This function will try to verify the given crl and return its status.
1139 See @code{gnutls_x509_crt_list_verify()} for a detailed description of
1142 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1143 negative error value.
1146 @subheading gnutls_x509_crq_deinit
1147 @anchor{gnutls_x509_crq_deinit}
1148 @deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq})
1149 @var{crq}: The structure to be initialized
1151 This function will deinitialize a PKCS@code{10} certificate request
1155 @subheading gnutls_x509_crq_export
1156 @anchor{gnutls_x509_crq_export}
1157 @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})
1158 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1160 @var{format}: the format of output params. One of PEM or DER.
1162 @var{output_data}: will contain a certificate request PEM or DER encoded
1164 @var{output_data_size}: holds the size of output_data (and will be
1165 replaced by the actual size of parameters)
1167 This function will export the certificate request to a PEM or DER
1168 encoded PKCS10 structure.
1170 If the buffer provided is not long enough to hold the output, then
1171 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and
1172 *@code{output_data_size} will be updated.
1174 If the structure is PEM encoded, it will have a header of "BEGIN
1175 NEW CERTIFICATE REQUEST".
1177 @strong{Return value:} In case of failure a negative value will be
1178 returned, and 0 on success.
1181 @subheading gnutls_x509_crq_get_attribute_by_oid
1182 @anchor{gnutls_x509_crq_get_attribute_by_oid}
1183 @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})
1184 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1186 @var{oid}: holds an Object Identified in zero-terminated string
1188 @var{indx}: In case multiple same OIDs exist in the attribute list, this
1189 specifies which to send, use zero to get the first one
1191 @var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL})
1193 @var{sizeof_buf}: initially holds the size of @code{buf}
1195 This function will return the attribute in the certificate request
1196 specified by the given Object ID. The attribute will be DER
1199 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1200 negative error value.
1203 @subheading gnutls_x509_crq_get_attribute_data
1204 @anchor{gnutls_x509_crq_get_attribute_data}
1205 @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})
1206 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1208 @var{indx}: Specifies which attribute OID to send. Use zero to get the first one.
1210 @var{data}: a pointer to a structure to hold the data (may be null)
1212 @var{sizeof_data}: initially holds the size of @code{oid}
1214 This function will return the requested attribute data in the
1215 certificate request. The attribute data will be stored as a string in the
1218 Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID.
1219 Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead,
1220 if you want to get data indexed by the attribute OID rather than
1223 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1224 negative value in case of an error. If your have reached the
1225 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1228 @strong{Since:} 2.8.0
1231 @subheading gnutls_x509_crq_get_attribute_info
1232 @anchor{gnutls_x509_crq_get_attribute_info}
1233 @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})
1234 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1236 @var{indx}: Specifies which attribute OID to send. Use zero to get the first one.
1238 @var{oid}: a pointer to a structure to hold the OID
1240 @var{sizeof_oid}: initially holds the maximum size of @code{oid}, on return
1241 holds actual size of @code{oid}.
1243 This function will return the requested attribute OID in the
1244 certificate, and the critical flag for it. The attribute OID will
1245 be stored as a string in the provided buffer. Use
1246 @code{gnutls_x509_crq_get_attribute_data()} to extract the data.
1248 If the buffer provided is not long enough to hold the output, then
1249 *@code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1252 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1253 negative value in case of an error. If your have reached the
1254 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1257 @strong{Since:} 2.8.0
1260 @subheading gnutls_x509_crq_get_basic_constraints
1261 @anchor{gnutls_x509_crq_get_basic_constraints}
1262 @deftypefun {int} {gnutls_x509_crq_get_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{critical}, int * @var{ca}, int * @var{pathlen})
1263 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1265 @var{critical}: will be non zero if the extension is marked as critical
1267 @var{ca}: pointer to output integer indicating CA status, may be NULL,
1268 value is 1 if the certificate CA flag is set, 0 otherwise.
1270 @var{pathlen}: pointer to output integer indicating path length (may be
1271 NULL), non-negative values indicate a present pathLenConstraint
1272 field and the actual value, -1 indicate that the field is absent.
1274 This function will read the certificate's basic constraints, and
1275 return the certificates CA status. It reads the basicConstraints
1276 X.509 extension (2.5.29.19).
1278 @strong{Return value:} If the certificate is a CA a positive value will be
1279 returned, or zero if the certificate does not have CA flag set.
1280 A negative value may be returned in case of errors. If the
1281 certificate does not contain the basicConstraints extension
1282 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1284 @strong{Since:} 2.8.0
1287 @subheading gnutls_x509_crq_get_challenge_password
1288 @anchor{gnutls_x509_crq_get_challenge_password}
1289 @deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{sizeof_pass})
1290 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1292 @var{pass}: will hold a zero-terminated password string
1294 @var{sizeof_pass}: Initially holds the size of @code{pass}.
1296 This function will return the challenge password in the request.
1297 The challenge password is intended to be used for requesting a
1298 revocation of the certificate.
1300 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1301 negative error value.
1304 @subheading gnutls_x509_crq_get_dn_by_oid
1305 @anchor{gnutls_x509_crq_get_dn_by_oid}
1306 @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})
1307 @var{crq}: should contain a gnutls_x509_crq_t structure
1309 @var{oid}: holds an Object Identified in null terminated string
1311 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies
1312 which to send. Use zero to get the first one.
1314 @var{raw_flag}: If non zero returns the raw DER data of the DN part.
1316 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL})
1318 @var{sizeof_buf}: initially holds the size of @code{buf}
1320 This function will extract the part of the name of the Certificate
1321 request subject, specified by the given OID. The output will be
1322 encoded as described in RFC2253. The output string will be ASCII
1323 or UTF-8 encoded, depending on the certificate data.
1325 Some helper macros with popular OIDs can be found in gnutls/x509.h
1326 If raw flag is zero, this function will only return known OIDs as
1327 text. Other OIDs will be DER encoded, as described in RFC2253 --
1328 in hex format with a '\#' prefix. You can check about known OIDs
1329 using @code{gnutls_x509_dn_oid_known()}.
1331 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1332 not long enough, and in that case the *@code{sizeof_buf} will be
1333 updated with the required size. On success 0 is returned.
1336 @subheading gnutls_x509_crq_get_dn_oid
1337 @anchor{gnutls_x509_crq_get_dn_oid}
1338 @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})
1339 @var{crq}: should contain a gnutls_x509_crq_t structure
1341 @var{indx}: Specifies which DN OID to send. Use zero to get the first one.
1343 @var{oid}: a pointer to a structure to hold the name (may be @code{NULL})
1345 @var{sizeof_oid}: initially holds the size of @code{oid}
1347 This function will extract the requested OID of the name of the
1348 certificate request subject, specified by the given index.
1350 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1351 not long enough, and in that case the *@code{sizeof_oid} will be
1352 updated with the required size. On success 0 is returned.
1355 @subheading gnutls_x509_crq_get_dn
1356 @anchor{gnutls_x509_crq_get_dn}
1357 @deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{sizeof_buf})
1358 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1360 @var{buf}: a pointer to a structure to hold the name (may be @code{NULL})
1362 @var{sizeof_buf}: initially holds the size of @code{buf}
1364 This function will copy the name of the Certificate request subject
1365 to the provided buffer. The name will be in the form
1366 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
1367 @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate
1370 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
1371 long enough, and in that case the *@code{sizeof_buf} will be updated with
1372 the required size. On success 0 is returned.
1375 @subheading gnutls_x509_crq_get_extension_by_oid
1376 @anchor{gnutls_x509_crq_get_extension_by_oid}
1377 @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})
1378 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1380 @var{oid}: holds an Object Identified in null terminated string
1382 @var{indx}: In case multiple same OIDs exist in the extensions, this
1383 specifies which to send. Use zero to get the first one.
1385 @var{buf}: a pointer to a structure to hold the name (may be null)
1387 @var{sizeof_buf}: initially holds the size of @code{buf}
1389 @var{critical}: will be non zero if the extension is marked as critical
1391 This function will return the extension specified by the OID in
1392 the certificate. The extensions will be returned as binary data
1393 DER encoded, in the provided buffer.
1395 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1396 negative value in case of an error. If the certificate does not
1397 contain the specified extension
1398 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
1400 @strong{Since:} 2.8.0
1403 @subheading gnutls_x509_crq_get_extension_data
1404 @anchor{gnutls_x509_crq_get_extension_data}
1405 @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})
1406 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1408 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
1410 @var{data}: a pointer to a structure to hold the data (may be null)
1412 @var{sizeof_data}: initially holds the size of @code{oid}
1414 This function will return the requested extension data in the
1415 certificate. The extension data will be stored as a string in the
1418 Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID and
1419 critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead,
1420 if you want to get data indexed by the extension OID rather than
1423 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1424 negative value in case of an error. If your have reached the
1425 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1428 @strong{Since:} 2.8.0
1431 @subheading gnutls_x509_crq_get_extension_info
1432 @anchor{gnutls_x509_crq_get_extension_info}
1433 @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}, int * @var{critical})
1434 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1436 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
1438 @var{oid}: a pointer to a structure to hold the OID
1440 @var{sizeof_oid}: initially holds the maximum size of @code{oid}, on return
1441 holds actual size of @code{oid}.
1443 @var{critical}: output variable with critical flag, may be NULL.
1445 This function will return the requested extension OID in the
1446 certificate, and the critical flag for it. The extension OID will
1447 be stored as a string in the provided buffer. Use
1448 @code{gnutls_x509_crq_get_extension_data()} to extract the data.
1450 If the buffer provided is not long enough to hold the output, then
1451 *@code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
1454 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1455 negative value in case of an error. If your have reached the
1456 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
1459 @strong{Since:} 2.8.0
1462 @subheading gnutls_x509_crq_get_key_id
1463 @anchor{gnutls_x509_crq_get_key_id}
1464 @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})
1465 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1467 @var{flags}: should be 0 for now
1469 @var{output_data}: will contain the key ID
1471 @var{output_data_size}: holds the size of output_data (and will be
1472 replaced by the actual size of parameters)
1474 This function will return a unique ID the depends on the public key
1475 parameters. This ID can be used in checking whether a certificate
1476 corresponds to the given private key.
1478 If the buffer provided is not long enough to hold the output, then
1479 *@code{output_data_size} is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1480 be returned. The output will normally be a SHA-1 hash output,
1483 @strong{Return value:} In case of failure a negative value will be
1484 returned, and 0 on success.
1486 @strong{Since:} 2.8.0
1489 @subheading gnutls_x509_crq_get_key_purpose_oid
1490 @anchor{gnutls_x509_crq_get_key_purpose_oid}
1491 @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})
1492 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1494 @var{indx}: This specifies which OID to return, use zero to get the first one
1496 @var{oid}: a pointer to a buffer to hold the OID (may be @code{NULL})
1498 @var{sizeof_oid}: initially holds the size of @code{oid}
1500 @var{critical}: output variable with critical flag, may be @code{NULL}.
1502 This function will extract the key purpose OIDs of the Certificate
1503 specified by the given index. These are stored in the Extended Key
1504 Usage extension (2.5.29.37). See the GNUTLS_KP_* definitions for
1505 human readable names.
1507 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
1508 not long enough, and in that case the *@code{sizeof_oid} will be
1509 updated with the required size. On success 0 is returned.
1511 @strong{Since:} 2.8.0
1514 @subheading gnutls_x509_crq_get_key_rsa_raw
1515 @anchor{gnutls_x509_crq_get_key_rsa_raw}
1516 @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})
1517 @var{crq}: Holds the certificate
1519 @var{m}: will hold the modulus
1521 @var{e}: will hold the public exponent
1523 This function will export the RSA public key's parameters found in
1524 the given structure. The new parameters will be allocated using
1525 @code{gnutls_malloc()} and will be stored in the appropriate datum.
1527 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1528 negative error value.
1530 @strong{Since:} 2.8.0
1533 @subheading gnutls_x509_crq_get_key_usage
1534 @anchor{gnutls_x509_crq_get_key_usage}
1535 @deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
1536 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1538 @var{key_usage}: where the key usage bits will be stored
1540 @var{critical}: will be non zero if the extension is marked as critical
1542 This function will return certificate's key usage, by reading the
1543 keyUsage X.509 extension (2.5.29.15). The key usage value will
1545 @strong{ORed values of the:} @code{GNUTLS_KEY_DIGITAL_SIGNATURE},
1546 @code{GNUTLS_KEY_NON_REPUDIATION}, @code{GNUTLS_KEY_KEY_ENCIPHERMENT},
1547 @code{GNUTLS_KEY_DATA_ENCIPHERMENT}, @code{GNUTLS_KEY_KEY_AGREEMENT},
1548 @code{GNUTLS_KEY_KEY_CERT_SIGN}, @code{GNUTLS_KEY_CRL_SIGN},
1549 @code{GNUTLS_KEY_ENCIPHER_ONLY}, @code{GNUTLS_KEY_DECIPHER_ONLY}.
1551 @strong{Returns:} the certificate key usage, or a negative value in case of
1552 parsing error. If the certificate does not contain the keyUsage
1553 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
1556 @strong{Since:} 2.8.0
1559 @subheading gnutls_x509_crq_get_pk_algorithm
1560 @anchor{gnutls_x509_crq_get_pk_algorithm}
1561 @deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits})
1562 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1564 @var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits
1566 This function will return the public key algorithm of a PKCS@code{10}
1567 certificate request.
1569 If bits is non-@code{NULL}, it should have enough size to hold the
1570 parameters size in bits. For RSA the bits returned is the modulus.
1571 For DSA the bits returned are of the public exponent.
1573 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1574 success, or a negative value on error.
1577 @subheading gnutls_x509_crq_get_subject_alt_name
1578 @anchor{gnutls_x509_crq_get_subject_alt_name}
1579 @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})
1580 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1582 @var{seq}: specifies the sequence number of the alt name, 0 for the
1583 first one, 1 for the second etc.
1585 @var{ret}: is the place where the alternative name will be copied to
1587 @var{ret_size}: holds the size of ret.
1589 @var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type
1591 @var{critical}: will be non zero if the extension is marked as critical
1594 This function will return the alternative names, contained in the
1595 given certificate. It is the same as
1596 @code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it
1597 will return the type of the alternative name in @code{ret_type} even if
1598 the function fails for some reason (i.e. the buffer provided is
1601 @strong{Returns:} the alternative subject name type on success, one of the
1602 enumerated @code{gnutls_x509_subject_alt_name_t}. It will return
1603 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
1604 hold the value. In that case @code{ret_size} will be updated with the
1605 required size. If the certificate request does not have an
1606 Alternative name with the specified sequence number then
1607 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1609 @strong{Since:} 2.8.0
1612 @subheading gnutls_x509_crq_get_subject_alt_othername_oid
1613 @anchor{gnutls_x509_crq_get_subject_alt_othername_oid}
1614 @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})
1615 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1617 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
1619 @var{ret}: is the place where the otherName OID will be copied to
1621 @var{ret_size}: holds the size of ret.
1623 This function will extract the type OID of an otherName Subject
1624 Alternative Name, contained in the given certificate, and return
1625 the type as an enumerated element.
1627 This function is only useful if
1628 @code{gnutls_x509_crq_get_subject_alt_name()} returned
1629 @code{GNUTLS_SAN_OTHERNAME}.
1631 @strong{Returns:} the alternative subject name type on success, one of the
1632 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs,
1633 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
1634 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP}, and @code{GNUTLS_SAN_OTHERNAME} for
1635 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
1636 @code{ret_size} is not large enough to hold the value. In that case
1637 @code{ret_size} will be updated with the required size. If the
1638 certificate does not have an Alternative name with the specified
1639 sequence number and with the otherName type then
1640 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
1642 @strong{Since:} 2.8.0
1645 @subheading gnutls_x509_crq_get_version
1646 @anchor{gnutls_x509_crq_get_version}
1647 @deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq})
1648 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1650 This function will return the version of the specified Certificate
1653 @strong{Returns:} version of certificate request, or a negative value on
1657 @subheading gnutls_x509_crq_import
1658 @anchor{gnutls_x509_crq_import}
1659 @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})
1660 @var{crq}: The structure to store the parsed certificate request.
1662 @var{data}: The DER or PEM encoded certificate.
1664 @var{format}: One of DER or PEM
1666 This function will convert the given DER or PEM encoded certificate
1667 request to a @code{gnutls_x509_crq_t} structure. The output will be
1668 stored in @code{crq}.
1670 If the Certificate is PEM encoded it should have a header of "NEW
1671 CERTIFICATE REQUEST".
1673 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1674 negative error value.
1677 @subheading gnutls_x509_crq_init
1678 @anchor{gnutls_x509_crq_init}
1679 @deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq})
1680 @var{crq}: The structure to be initialized
1682 This function will initialize a PKCS@code{10} certificate request
1685 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1686 negative error value.
1689 @subheading gnutls_x509_crq_print
1690 @anchor{gnutls_x509_crq_print}
1691 @deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
1692 @var{crq}: The structure to be printed
1694 @var{format}: Indicate the format to use
1696 @var{out}: Newly allocated datum with zero terminated string.
1698 This function will pretty print a certificate request, suitable for
1701 The output @code{out} needs to be deallocate using @code{gnutls_free()}.
1703 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1704 negative error value.
1706 @strong{Since:} 2.8.0
1709 @subheading gnutls_x509_crq_privkey_sign
1710 @anchor{gnutls_x509_crq_privkey_sign}
1711 @deftypefun {int} {gnutls_x509_crq_privkey_sign} (gnutls_x509_crq_t @var{crq}, gnutls_privkey_t @var{key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
1712 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1714 @var{key}: holds a private key
1716 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
1718 @var{flags}: must be 0
1720 This function will sign the certificate request with a private key.
1721 This must be the same key as the one used in
1722 @code{gnutls_x509_crt_set_key()} since a certificate request is self
1725 This must be the last step in a certificate request generation
1726 since all the previously set parameters are now signed.
1728 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
1729 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
1730 information in the certificate request (e.g., the version using
1731 @code{gnutls_x509_crq_set_version()}).
1734 @subheading gnutls_x509_crq_set_attribute_by_oid
1735 @anchor{gnutls_x509_crq_set_attribute_by_oid}
1736 @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})
1737 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1739 @var{oid}: holds an Object Identified in zero-terminated string
1741 @var{buf}: a pointer to a structure that holds the attribute data
1743 @var{sizeof_buf}: holds the size of @code{buf}
1745 This function will set the attribute in the certificate request
1746 specified by the given Object ID. The attribute must be be DER
1749 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1750 negative error value.
1753 @subheading gnutls_x509_crq_set_basic_constraints
1754 @anchor{gnutls_x509_crq_set_basic_constraints}
1755 @deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint})
1756 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1758 @var{ca}: true(1) or false(0) depending on the Certificate authority status.
1760 @var{pathLenConstraint}: non-negative values indicate maximum length of path,
1761 and negative values indicate that the pathLenConstraints field should
1764 This function will set the basicConstraints certificate extension.
1766 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1767 negative error value.
1769 @strong{Since:} 2.8.0
1772 @subheading gnutls_x509_crq_set_challenge_password
1773 @anchor{gnutls_x509_crq_set_challenge_password}
1774 @deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass})
1775 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1777 @var{pass}: holds a zero-terminated password
1779 This function will set a challenge password to be used when
1780 revoking the request.
1782 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1783 negative error value.
1786 @subheading gnutls_x509_crq_set_dn_by_oid
1787 @anchor{gnutls_x509_crq_set_dn_by_oid}
1788 @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})
1789 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1791 @var{oid}: holds an Object Identifier in a zero-terminated string
1793 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
1795 @var{data}: a pointer to the input data
1797 @var{sizeof_data}: holds the size of @code{data}
1799 This function will set the part of the name of the Certificate
1800 request subject, specified by the given OID. The input string
1801 should be ASCII or UTF-8 encoded.
1803 Some helper macros with popular OIDs can be found in gnutls/x509.h
1804 With this function you can only set the known OIDs. You can test
1805 for known OIDs using @code{gnutls_x509_dn_oid_known()}. For OIDs that are
1806 not known (by gnutls) you should properly DER encode your data, and
1807 call this function with raw_flag set.
1809 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1810 negative error value.
1813 @subheading gnutls_x509_crq_set_key_purpose_oid
1814 @anchor{gnutls_x509_crq_set_key_purpose_oid}
1815 @deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical})
1816 @var{crq}: a certificate of type @code{gnutls_x509_crq_t}
1818 @var{oid}: a pointer to a zero-terminated string that holds the OID
1820 @var{critical}: Whether this extension will be critical or not
1822 This function will set the key purpose OIDs of the Certificate.
1823 These are stored in the Extended Key Usage extension (2.5.29.37)
1824 See the GNUTLS_KP_* definitions for human readable names.
1826 Subsequent calls to this function will append OIDs to the OID list.
1828 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1829 negative error value.
1831 @strong{Since:} 2.8.0
1834 @subheading gnutls_x509_crq_set_key_rsa_raw
1835 @anchor{gnutls_x509_crq_set_key_rsa_raw}
1836 @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})
1837 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1839 @var{m}: holds the modulus
1841 @var{e}: holds the public exponent
1843 This function will set the public parameters from the given private
1844 key to the request. Only RSA keys are currently supported.
1846 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1847 negative error value.
1849 @strong{Since:} 2.6.0
1852 @subheading gnutls_x509_crq_set_key_usage
1853 @anchor{gnutls_x509_crq_set_key_usage}
1854 @deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage})
1855 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1857 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
1859 This function will set the keyUsage certificate extension.
1861 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1862 negative error value.
1864 @strong{Since:} 2.8.0
1867 @subheading gnutls_x509_crq_set_key
1868 @anchor{gnutls_x509_crq_set_key}
1869 @deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
1870 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1872 @var{key}: holds a private key
1874 This function will set the public parameters from the given private
1875 key to the request. Only RSA keys are currently supported.
1877 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1878 negative error value.
1881 @subheading gnutls_x509_crq_set_subject_alt_name
1882 @anchor{gnutls_x509_crq_set_subject_alt_name}
1883 @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})
1884 @var{crq}: a certificate request of type @code{gnutls_x509_crq_t}
1886 @var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations
1888 @var{data}: The data to be set
1890 @var{data_size}: The size of data to be set
1892 @var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or
1893 @code{GNUTLS_FSAN_APPEND} to append.
1895 This function will set the subject alternative name certificate
1896 extension. It can set the following types:
1898 &GNUTLS_SAN_DNSNAME: as a text string
1900 &GNUTLS_SAN_RFC822NAME: as a text string
1902 &GNUTLS_SAN_URI: as a text string
1904 &GNUTLS_SAN_IPADDRESS: as a binary IP address (4 or 16 bytes)
1906 Other values can be set as binary values with the proper DER encoding.
1908 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1909 negative error value.
1911 @strong{Since:} 2.8.0
1914 @subheading gnutls_x509_crq_set_version
1915 @anchor{gnutls_x509_crq_set_version}
1916 @deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version})
1917 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1919 @var{version}: holds the version number, for v1 Requests must be 1
1921 This function will set the version of the certificate request. For
1922 version 1 requests this must be one.
1924 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1925 negative error value.
1928 @subheading gnutls_x509_crq_sign2
1929 @anchor{gnutls_x509_crq_sign2}
1930 @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})
1931 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1933 @var{key}: holds a private key
1935 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
1937 @var{flags}: must be 0
1939 This function will sign the certificate request with a private key.
1940 This must be the same key as the one used in
1941 @code{gnutls_x509_crt_set_key()} since a certificate request is self
1944 This must be the last step in a certificate request generation
1945 since all the previously set parameters are now signed.
1947 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
1948 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
1949 information in the certificate request (e.g., the version using
1950 @code{gnutls_x509_crq_set_version()}).
1952 @strong{Deprecated:} Use @code{gnutls_x509_crq_privkey_sign()} instead.
1955 @subheading gnutls_x509_crq_sign
1956 @anchor{gnutls_x509_crq_sign}
1957 @deftypefun {int} {gnutls_x509_crq_sign} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key})
1958 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1960 @var{key}: holds a private key
1962 This function is the same a @code{gnutls_x509_crq_sign2()} with no flags,
1963 and SHA1 as the hash algorithm.
1965 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1966 negative error value.
1968 @strong{Deprecated:} Use @code{gnutls_x509_crq_privkey_sign()} instead.
1971 @subheading gnutls_x509_crq_verify
1972 @anchor{gnutls_x509_crq_verify}
1973 @deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
1974 @var{crq}: is the crq to be verified
1976 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
1978 This function will verify self signature in the certificate
1979 request and return its status.
1981 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
1982 if verification failed, otherwise a negative error value.
1985 @subheading gnutls_x509_crt_check_hostname
1986 @anchor{gnutls_x509_crt_check_hostname}
1987 @deftypefun {int} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname})
1988 @var{cert}: should contain an gnutls_x509_crt_t structure
1990 @var{hostname}: A null terminated string that contains a DNS name
1992 This function will check if the given certificate's subject matches
1993 the given hostname. This is a basic implementation of the matching
1994 described in RFC2818 (HTTPS), which takes into account wildcards,
1995 and the DNSName/IPAddress subject alternative name PKIX extension.
1997 @strong{Returns:} non zero for a successful match, and zero on failure.
2000 @subheading gnutls_x509_crt_check_issuer
2001 @anchor{gnutls_x509_crt_check_issuer}
2002 @deftypefun {int} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer})
2003 @var{cert}: is the certificate to be checked
2005 @var{issuer}: is the certificate of a possible issuer
2007 This function will check if the given certificate was issued by the
2008 given issuer. It checks the DN fields and the authority
2009 key identifier and subject key identifier fields match.
2011 @strong{Returns:} It will return true (1) if the given certificate is issued
2012 by the given issuer, and false (0) if not. A negative value is
2013 returned in case of an error.
2016 @subheading gnutls_x509_crt_check_revocation
2017 @anchor{gnutls_x509_crt_check_revocation}
2018 @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})
2019 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2021 @var{crl_list}: should contain a list of gnutls_x509_crl_t structures
2023 @var{crl_list_length}: the length of the crl_list
2025 This function will return check if the given certificate is
2026 revoked. It is assumed that the CRLs have been verified before.
2028 @strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A
2029 negative value is returned on error.
2032 @subheading gnutls_x509_crt_cpy_crl_dist_points
2033 @anchor{gnutls_x509_crt_cpy_crl_dist_points}
2034 @deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src})
2035 @var{dst}: a certificate of type @code{gnutls_x509_crt_t}
2037 @var{src}: the certificate where the dist points will be copied from
2039 This function will copy the CRL distribution points certificate
2040 extension, from the source to the destination certificate.
2041 This may be useful to copy from a CA certificate to issued ones.
2043 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2044 negative error value.
2047 @subheading gnutls_x509_crt_deinit
2048 @anchor{gnutls_x509_crt_deinit}
2049 @deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert})
2050 @var{cert}: The structure to be deinitialized
2052 This function will deinitialize a certificate structure.
2055 @subheading gnutls_x509_crt_export
2056 @anchor{gnutls_x509_crt_export}
2057 @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})
2058 @var{cert}: Holds the certificate
2060 @var{format}: the format of output params. One of PEM or DER.
2062 @var{output_data}: will contain a certificate PEM or DER encoded
2064 @var{output_data_size}: holds the size of output_data (and will be
2065 replaced by the actual size of parameters)
2067 This function will export the certificate to DER or PEM format.
2069 If the buffer provided is not long enough to hold the output, then
2070 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2073 If the structure is PEM encoded, it will have a header
2074 of "BEGIN CERTIFICATE".
2076 @strong{Return value:} In case of failure a negative value will be
2077 returned, and 0 on success.
2080 @subheading gnutls_x509_crt_get_activation_time
2081 @anchor{gnutls_x509_crt_get_activation_time}
2082 @deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert})
2083 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2085 This function will return the time this Certificate was or will be
2088 @strong{Returns:} activation time, or (time_t)-1 on error.
2091 @subheading gnutls_x509_crt_get_authority_key_id
2092 @anchor{gnutls_x509_crt_get_authority_key_id}
2093 @deftypefun {int} {gnutls_x509_crt_get_authority_key_id} (gnutls_x509_crt_t @var{cert}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical})
2094 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2096 @var{ret}: The place where the identifier will be copied
2098 @var{ret_size}: Holds the size of the result field.
2100 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2102 This function will return the X.509v3 certificate authority's key
2103 identifier. This is obtained by the X.509 Authority Key
2104 identifier extension field (2.5.29.35). Note that this function
2105 only returns the keyIdentifier field of the extension.
2107 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2108 negative error value.
2111 @subheading gnutls_x509_crt_get_basic_constraints
2112 @anchor{gnutls_x509_crt_get_basic_constraints}
2113 @deftypefun {int} {gnutls_x509_crt_get_basic_constraints} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}, int * @var{ca}, int * @var{pathlen})
2114 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2116 @var{critical}: will be non zero if the extension is marked as critical
2118 @var{ca}: pointer to output integer indicating CA status, may be NULL,
2119 value is 1 if the certificate CA flag is set, 0 otherwise.
2121 @var{pathlen}: pointer to output integer indicating path length (may be
2122 NULL), non-negative values indicate a present pathLenConstraint
2123 field and the actual value, -1 indicate that the field is absent.
2125 This function will read the certificate's basic constraints, and
2126 return the certificates CA status. It reads the basicConstraints
2127 X.509 extension (2.5.29.19).
2129 @strong{Return value:} If the certificate is a CA a positive value will be
2130 returned, or zero if the certificate does not have CA flag set. A
2131 negative value may be returned in case of errors. If the
2132 certificate does not contain the basicConstraints extension
2133 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2136 @subheading gnutls_x509_crt_get_ca_status
2137 @anchor{gnutls_x509_crt_get_ca_status}
2138 @deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical})
2139 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2141 @var{critical}: will be non zero if the extension is marked as critical
2143 This function will return certificates CA status, by reading the
2144 basicConstraints X.509 extension (2.5.29.19). If the certificate is
2145 a CA a positive value will be returned, or zero if the certificate
2146 does not have CA flag set.
2148 Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the
2149 pathLenConstraint field too.
2151 @strong{Returns:} A negative value may be returned in case of parsing error.
2152 If the certificate does not contain the basicConstraints extension
2153 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned.
2156 @subheading gnutls_x509_crt_get_crl_dist_points
2157 @anchor{gnutls_x509_crt_get_crl_dist_points}
2158 @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})
2159 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2161 @var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
2163 @var{ret}: is the place where the distribution point will be copied to
2165 @var{ret_size}: holds the size of ret.
2167 @var{reason_flags}: Revocation reasons flags.
2169 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2171 This function retrieves the CRL distribution points (2.5.29.31),
2172 contained in the given certificate in the X509v3 Certificate
2175 @code{reason_flags} should be an ORed sequence of
2176 @code{GNUTLS_CRL_REASON_UNUSED}, @code{GNUTLS_CRL_REASON_KEY_COMPROMISE},
2177 @code{GNUTLS_CRL_REASON_CA_COMPROMISE},
2178 @code{GNUTLS_CRL_REASON_AFFILIATION_CHANGED},
2179 @code{GNUTLS_CRL_REASON_SUPERSEEDED},
2180 @code{GNUTLS_CRL_REASON_CESSATION_OF_OPERATION},
2181 @code{GNUTLS_CRL_REASON_CERTIFICATE_HOLD},
2182 @code{GNUTLS_CRL_REASON_PRIVILEGE_WITHDRAWN},
2183 @code{GNUTLS_CRL_REASON_AA_COMPROMISE}, or zero for all possible reasons.
2185 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates &@code{ret_size} if
2186 &@code{ret_size} is not enough to hold the distribution point, or the
2187 type of the distribution point if everything was ok. The type is
2188 one of the enumerated @code{gnutls_x509_subject_alt_name_t}. If the
2189 certificate does not have an Alternative name with the specified
2190 sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is
2194 @subheading gnutls_x509_crt_get_dn_by_oid
2195 @anchor{gnutls_x509_crt_get_dn_by_oid}
2196 @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{sizeof_buf})
2197 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2199 @var{oid}: holds an Object Identified in null terminated string
2201 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
2203 @var{raw_flag}: If non zero returns the raw DER data of the DN part.
2205 @var{buf}: a pointer where the DN part will be copied (may be null).
2207 @var{sizeof_buf}: initially holds the size of @code{buf}
2209 This function will extract the part of the name of the Certificate
2210 subject specified by the given OID. The output, if the raw flag is
2211 not used, will be encoded as described in RFC2253. Thus a string
2212 that is ASCII or UTF-8 encoded, depending on the certificate data.
2214 Some helper macros with popular OIDs can be found in gnutls/x509.h
2215 If raw flag is zero, this function will only return known OIDs as
2216 text. Other OIDs will be DER encoded, as described in RFC2253 --
2217 in hex format with a '\#' prefix. You can check about known OIDs
2218 using @code{gnutls_x509_dn_oid_known()}.
2220 If @code{buf} is null then only the size will be filled.
2222 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2223 not long enough, and in that case the *sizeof_buf will be updated
2224 with the required size. On success 0 is returned.
2227 @subheading gnutls_x509_crt_get_dn_oid
2228 @anchor{gnutls_x509_crt_get_dn_oid}
2229 @deftypefun {int} {gnutls_x509_crt_get_dn_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
2230 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2232 @var{indx}: This specifies which OID to return. Use zero to get the first one.
2234 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2236 @var{sizeof_oid}: initially holds the size of @code{oid}
2238 This function will extract the OIDs of the name of the Certificate
2239 subject specified by the given index.
2241 If oid is null then only the size will be filled.
2243 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2244 not long enough, and in that case the *sizeof_oid will be updated
2245 with the required size. On success 0 is returned.
2248 @subheading gnutls_x509_crt_get_dn
2249 @anchor{gnutls_x509_crt_get_dn}
2250 @deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{sizeof_buf})
2251 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2253 @var{buf}: a pointer to a structure to hold the name (may be null)
2255 @var{sizeof_buf}: initially holds the size of @code{buf}
2257 This function will copy the name of the Certificate in the provided
2258 buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2259 described in RFC2253. The output string will be ASCII or UTF-8
2260 encoded, depending on the certificate data.
2262 If @code{buf} is null then only the size will be filled.
2264 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not
2265 long enough, and in that case the *sizeof_buf will be updated
2266 with the required size. On success 0 is returned.
2269 @subheading gnutls_x509_crt_get_expiration_time
2270 @anchor{gnutls_x509_crt_get_expiration_time}
2271 @deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert})
2272 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2274 This function will return the time this Certificate was or will be
2277 @strong{Returns:} expiration time, or (time_t)-1 on error.
2280 @subheading gnutls_x509_crt_get_extension_by_oid
2281 @anchor{gnutls_x509_crt_get_extension_by_oid}
2282 @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{sizeof_buf}, unsigned int * @var{critical})
2283 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2285 @var{oid}: holds an Object Identified in null terminated string
2287 @var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use zero to get the first one.
2289 @var{buf}: a pointer to a structure to hold the name (may be null)
2291 @var{sizeof_buf}: initially holds the size of @code{buf}
2293 @var{critical}: will be non zero if the extension is marked as critical
2295 This function will return the extension specified by the OID in the
2296 certificate. The extensions will be returned as binary data DER
2297 encoded, in the provided buffer.
2299 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
2300 otherwise an error code is returned. If the certificate does not
2301 contain the specified extension
2302 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2305 @subheading gnutls_x509_crt_get_extension_data
2306 @anchor{gnutls_x509_crt_get_extension_data}
2307 @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})
2308 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2310 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
2312 @var{data}: a pointer to a structure to hold the data (may be null)
2314 @var{sizeof_data}: initially holds the size of @code{oid}
2316 This function will return the requested extension data in the
2317 certificate. The extension data will be stored as a string in the
2320 Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and
2321 critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead,
2322 if you want to get data indexed by the extension OID rather than
2325 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
2326 otherwise an error code is returned. If you have reached the
2327 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2331 @subheading gnutls_x509_crt_get_extension_info
2332 @anchor{gnutls_x509_crt_get_extension_info}
2333 @deftypefun {int} {gnutls_x509_crt_get_extension_info} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, int * @var{critical})
2334 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2336 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
2338 @var{oid}: a pointer to a structure to hold the OID
2340 @var{sizeof_oid}: initially holds the maximum size of @code{oid}, on return
2341 holds actual size of @code{oid}.
2343 @var{critical}: output variable with critical flag, may be NULL.
2345 This function will return the requested extension OID in the
2346 certificate, and the critical flag for it. The extension OID will
2347 be stored as a string in the provided buffer. Use
2348 @code{gnutls_x509_crt_get_extension_data()} to extract the data.
2350 If the buffer provided is not long enough to hold the output, then
2351 *@code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be
2354 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
2355 otherwise an error code is returned. If you have reached the
2356 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2360 @subheading gnutls_x509_crt_get_extension_oid
2361 @anchor{gnutls_x509_crt_get_extension_oid}
2362 @deftypefun {int} {gnutls_x509_crt_get_extension_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
2363 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2365 @var{indx}: Specifies which extension OID to send. Use zero to get the first one.
2367 @var{oid}: a pointer to a structure to hold the OID (may be null)
2369 @var{sizeof_oid}: initially holds the size of @code{oid}
2371 This function will return the requested extension OID in the certificate.
2372 The extension OID will be stored as a string in the provided buffer.
2374 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
2375 otherwise an error code is returned. If you have reached the
2376 last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
2380 @subheading gnutls_x509_crt_get_fingerprint
2381 @anchor{gnutls_x509_crt_get_fingerprint}
2382 @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{sizeof_buf})
2383 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2385 @var{algo}: is a digest algorithm
2387 @var{buf}: a pointer to a structure to hold the fingerprint (may be null)
2389 @var{sizeof_buf}: initially holds the size of @code{buf}
2391 This function will calculate and copy the certificate's fingerprint
2392 in the provided buffer.
2394 If the buffer is null then only the size will be filled.
2396 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2397 not long enough, and in that case the *sizeof_buf will be updated
2398 with the required size. On success 0 is returned.
2401 @subheading gnutls_x509_crt_get_issuer_alt_name2
2402 @anchor{gnutls_x509_crt_get_issuer_alt_name2}
2403 @deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{ret_type}, unsigned int * @var{critical})
2404 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2406 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2408 @var{ret}: is the place where the alternative name will be copied to
2410 @var{ret_size}: holds the size of ret.
2412 @var{ret_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2414 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2416 This function will return the alternative names, contained in the
2417 given certificate. It is the same as
2418 @code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it
2419 will return the type of the alternative name in @code{ret_type} even if
2420 the function fails for some reason (i.e. the buffer provided is
2423 @strong{Returns:} the alternative issuer name type on success, one of the
2424 enumerated @code{gnutls_x509_subject_alt_name_t}. It will return
2425 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough
2426 to hold the value. In that case @code{ret_size} will be updated with
2427 the required size. If the certificate does not have an
2428 Alternative name with the specified sequence number then
2429 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2431 @strong{Since:} 2.10.0
2434 @subheading gnutls_x509_crt_get_issuer_alt_name
2435 @anchor{gnutls_x509_crt_get_issuer_alt_name}
2436 @deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical})
2437 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2439 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2441 @var{ret}: is the place where the alternative name will be copied to
2443 @var{ret_size}: holds the size of ret.
2445 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2447 This function retrieves the Issuer Alternative Name (2.5.29.18),
2448 contained in the given certificate in the X509v3 Certificate
2451 When the SAN type is otherName, it will extract the data in the
2452 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2453 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2454 the corresponding OID and the "virtual" SAN types (e.g.,
2455 @code{GNUTLS_SAN_OTHERNAME_XMPP}).
2457 If an otherName OID is known, the data will be decoded. Otherwise
2458 the returned data will be DER encoded, and you will have to decode
2459 it yourself. Currently, only the RFC 3920 id-on-xmppAddr Issuer
2460 AltName is recognized.
2462 @strong{Returns:} the alternative issuer name type on success, one of the
2463 enumerated @code{gnutls_x509_subject_alt_name_t}. It will return
2464 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough
2465 to hold the value. In that case @code{ret_size} will be updated with
2466 the required size. If the certificate does not have an
2467 Alternative name with the specified sequence number then
2468 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2470 @strong{Since:} 2.10.0
2473 @subheading gnutls_x509_crt_get_issuer_alt_othername_oid
2474 @anchor{gnutls_x509_crt_get_issuer_alt_othername_oid}
2475 @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})
2476 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2478 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2480 @var{ret}: is the place where the otherName OID will be copied to
2482 @var{ret_size}: holds the size of ret.
2484 This function will extract the type OID of an otherName Subject
2485 Alternative Name, contained in the given certificate, and return
2486 the type as an enumerated element.
2488 This function is only useful if
2489 @code{gnutls_x509_crt_get_issuer_alt_name()} returned
2490 @code{GNUTLS_SAN_OTHERNAME}.
2492 @strong{Returns:} the alternative issuer name type on success, one of the
2493 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2494 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2495 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP}, and @code{GNUTLS_SAN_OTHERNAME} for
2496 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2497 @code{ret_size} is not large enough to hold the value. In that case
2498 @code{ret_size} will be updated with the required size. If the
2499 certificate does not have an Alternative name with the specified
2500 sequence number and with the otherName type then
2501 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2503 @strong{Since:} 2.10.0
2506 @subheading gnutls_x509_crt_get_issuer_dn_by_oid
2507 @anchor{gnutls_x509_crt_get_issuer_dn_by_oid}
2508 @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{sizeof_buf})
2509 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2511 @var{oid}: holds an Object Identified in null terminated string
2513 @var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
2515 @var{raw_flag}: If non zero returns the raw DER data of the DN part.
2517 @var{buf}: a pointer to a structure to hold the name (may be null)
2519 @var{sizeof_buf}: initially holds the size of @code{buf}
2521 This function will extract the part of the name of the Certificate
2522 issuer specified by the given OID. The output, if the raw flag is not
2523 used, will be encoded as described in RFC2253. Thus a string that is
2524 ASCII or UTF-8 encoded, depending on the certificate data.
2526 Some helper macros with popular OIDs can be found in gnutls/x509.h
2527 If raw flag is zero, this function will only return known OIDs as
2528 text. Other OIDs will be DER encoded, as described in RFC2253 --
2529 in hex format with a '\#' prefix. You can check about known OIDs
2530 using @code{gnutls_x509_dn_oid_known()}.
2532 If @code{buf} is null then only the size will be filled.
2534 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2535 long enough, and in that case the *sizeof_buf will be updated
2536 with the required size. On success 0 is returned.
2539 @subheading gnutls_x509_crt_get_issuer_dn_oid
2540 @anchor{gnutls_x509_crt_get_issuer_dn_oid}
2541 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid})
2542 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2544 @var{indx}: This specifies which OID to return. Use zero to get the first one.
2546 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2548 @var{sizeof_oid}: initially holds the size of @code{oid}
2550 This function will extract the OIDs of the name of the Certificate
2551 issuer specified by the given index.
2553 If @code{oid} is null then only the size will be filled.
2555 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2556 long enough, and in that case the *sizeof_oid will be updated
2557 with the required size. On success 0 is returned.
2560 @subheading gnutls_x509_crt_get_issuer_dn
2561 @anchor{gnutls_x509_crt_get_issuer_dn}
2562 @deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{sizeof_buf})
2563 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2565 @var{buf}: a pointer to a structure to hold the name (may be null)
2567 @var{sizeof_buf}: initially holds the size of @code{buf}
2569 This function will copy the name of the Certificate issuer in the
2570 provided buffer. The name will be in the form
2571 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string
2572 will be ASCII or UTF-8 encoded, depending on the certificate data.
2574 If @code{buf} is null then only the size will be filled.
2576 @strong{Returns:} GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
2577 long enough, and in that case the *sizeof_buf will be updated with
2578 the required size. On success 0 is returned.
2581 @subheading gnutls_x509_crt_get_issuer_unique_id
2582 @anchor{gnutls_x509_crt_get_issuer_unique_id}
2583 @deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{sizeof_buf})
2584 @var{crt}: Holds the certificate
2586 @var{buf}: user allocated memory buffer, will hold the unique id
2588 @var{sizeof_buf}: size of user allocated memory buffer (on input), will hold
2589 actual size of the unique ID on return.
2591 This function will extract the issuerUniqueID value (if present) for
2592 the given certificate.
2594 If the user allocated memory buffer is not large enough to hold the
2595 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
2596 returned, and sizeof_buf will be set to the actual length.
2598 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
2601 @subheading gnutls_x509_crt_get_issuer
2602 @anchor{gnutls_x509_crt_get_issuer}
2603 @deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
2604 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2606 @var{dn}: output variable with pointer to opaque DN
2608 Return the Certificate's Issuer DN as an opaque data type. You may
2609 use @code{gnutls_x509_dn_get_rdn_ava()} to decode the DN.
2611 Note that @code{dn} should be treated as constant. Because points
2612 into the @code{cert} object, you may not deallocate @code{cert}
2613 and continue to access @code{dn}.
2615 @strong{Returns:} Returns 0 on success, or an error code.
2618 @subheading gnutls_x509_crt_get_key_id
2619 @anchor{gnutls_x509_crt_get_key_id}
2620 @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})
2621 @var{crt}: Holds the certificate
2623 @var{flags}: should be 0 for now
2625 @var{output_data}: will contain the key ID
2627 @var{output_data_size}: holds the size of output_data (and will be
2628 replaced by the actual size of parameters)
2630 This function will return a unique ID the depends on the public
2631 key parameters. This ID can be used in checking whether a
2632 certificate corresponds to the given private key.
2634 If the buffer provided is not long enough to hold the output, then
2635 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2636 be returned. The output will normally be a SHA-1 hash output,
2639 @strong{Return value:} In case of failure a negative value will be
2640 returned, and 0 on success.
2643 @subheading gnutls_x509_crt_get_key_purpose_oid
2644 @anchor{gnutls_x509_crt_get_key_purpose_oid}
2645 @deftypefun {int} {gnutls_x509_crt_get_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, int @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical})
2646 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2648 @var{indx}: This specifies which OID to return. Use zero to get the first one.
2650 @var{oid}: a pointer to a buffer to hold the OID (may be null)
2652 @var{sizeof_oid}: initially holds the size of @code{oid}
2654 @var{critical}: output flag to indicate criticality of extension
2656 This function will extract the key purpose OIDs of the Certificate
2657 specified by the given index. These are stored in the Extended Key
2658 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
2659 human readable names.
2661 If @code{oid} is null then only the size will be filled.
2663 @strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is
2664 not long enough, and in that case the *sizeof_oid will be updated
2665 with the required size. On success 0 is returned.
2668 @subheading gnutls_x509_crt_get_key_usage
2669 @anchor{gnutls_x509_crt_get_key_usage}
2670 @deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical})
2671 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2673 @var{key_usage}: where the key usage bits will be stored
2675 @var{critical}: will be non zero if the extension is marked as critical
2677 This function will return certificate's key usage, by reading the
2678 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
2679 values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE},
2680 @code{GNUTLS_KEY_NON_REPUDIATION}, @code{GNUTLS_KEY_KEY_ENCIPHERMENT},
2681 @code{GNUTLS_KEY_DATA_ENCIPHERMENT}, @code{GNUTLS_KEY_KEY_AGREEMENT},
2682 @code{GNUTLS_KEY_KEY_CERT_SIGN}, @code{GNUTLS_KEY_CRL_SIGN},
2683 @code{GNUTLS_KEY_ENCIPHER_ONLY}, @code{GNUTLS_KEY_DECIPHER_ONLY}.
2685 @strong{Returns:} the certificate key usage, or a negative value in case of
2686 parsing error. If the certificate does not contain the keyUsage
2687 extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be
2691 @subheading gnutls_x509_crt_get_pk_algorithm
2692 @anchor{gnutls_x509_crt_get_pk_algorithm}
2693 @deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits})
2694 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2696 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
2698 This function will return the public key algorithm of an X.509
2701 If bits is non null, it should have enough size to hold the parameters
2702 size in bits. For RSA the bits returned is the modulus.
2703 For DSA the bits returned are of the public
2706 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
2707 success, or a negative value on error.
2710 @subheading gnutls_x509_crt_get_pk_dsa_raw
2711 @anchor{gnutls_x509_crt_get_pk_dsa_raw}
2712 @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})
2713 @var{crt}: Holds the certificate
2715 @var{p}: will hold the p
2717 @var{q}: will hold the q
2719 @var{g}: will hold the g
2721 @var{y}: will hold the y
2723 This function will export the DSA public key's parameters found in
2724 the given certificate. The new parameters will be allocated using
2725 @code{gnutls_malloc()} and will be stored in the appropriate datum.
2727 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
2730 @subheading gnutls_x509_crt_get_pk_rsa_raw
2731 @anchor{gnutls_x509_crt_get_pk_rsa_raw}
2732 @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})
2733 @var{crt}: Holds the certificate
2735 @var{m}: will hold the modulus
2737 @var{e}: will hold the public exponent
2739 This function will export the RSA public key's parameters found in
2740 the given structure. The new parameters will be allocated using
2741 @code{gnutls_malloc()} and will be stored in the appropriate datum.
2743 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
2746 @subheading gnutls_x509_crt_get_preferred_hash_algorithm
2747 @anchor{gnutls_x509_crt_get_preferred_hash_algorithm}
2748 @deftypefun {int} {gnutls_x509_crt_get_preferred_hash_algorithm} (gnutls_x509_crt_t @var{crt}, gnutls_digest_algorithm_t * @var{hash}, unsigned int * @var{mand})
2749 @var{crt}: Holds the certificate
2751 @var{hash}: The result of the call with the hash algorithm used for signature
2753 @var{mand}: If non zero it means that the algorithm MUST use this hash. May be NULL.
2755 This function will read the certifcate and return the appropriate digest
2756 algorithm to use for signing with this certificate. Some certificates (i.e.
2757 DSA might not be able to sign without the preferred algorithm).
2759 @strong{Deprecated:} Please use @code{gnutls_pubkey_get_preferred_hash_algorithm()}.
2761 @strong{Returns:} the 0 if the hash algorithm is found. A negative value is
2764 @strong{Since:} 2.11.0
2767 @subheading gnutls_x509_crt_get_proxy
2768 @anchor{gnutls_x509_crt_get_proxy}
2769 @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})
2770 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2772 @var{critical}: will be non zero if the extension is marked as critical
2774 @var{pathlen}: pointer to output integer indicating path length (may be
2775 NULL), non-negative values indicate a present pCPathLenConstraint
2776 field and the actual value, -1 indicate that the field is absent.
2778 @var{policyLanguage}: output variable with OID of policy language
2780 @var{policy}: output variable with policy data
2782 @var{sizeof_policy}: output variable size of policy data
2784 This function will get information from a proxy certificate. It
2785 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
2787 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
2788 otherwise an error code is returned.
2791 @subheading gnutls_x509_crt_get_raw_dn
2792 @anchor{gnutls_x509_crt_get_raw_dn}
2793 @deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{start})
2794 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2796 @var{start}: will hold the starting point of the DN
2798 This function will return a pointer to the DER encoded DN structure and
2801 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2802 negative error value. or a negative value on error.
2805 @subheading gnutls_x509_crt_get_raw_issuer_dn
2806 @anchor{gnutls_x509_crt_get_raw_issuer_dn}
2807 @deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{start})
2808 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2810 @var{start}: will hold the starting point of the DN
2812 This function will return a pointer to the DER encoded DN structure
2815 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2816 negative error value.or a negative value on error.
2819 @subheading gnutls_x509_crt_get_serial
2820 @anchor{gnutls_x509_crt_get_serial}
2821 @deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size})
2822 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2824 @var{result}: The place where the serial number will be copied
2826 @var{result_size}: Holds the size of the result field.
2828 This function will return the X.509 certificate's serial number.
2829 This is obtained by the X509 Certificate serialNumber field. Serial
2830 is not always a 32 or 64bit number. Some CAs use large serial
2831 numbers, thus it may be wise to handle it as something opaque.
2833 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2834 negative error value.
2837 @subheading gnutls_x509_crt_get_signature_algorithm
2838 @anchor{gnutls_x509_crt_get_signature_algorithm}
2839 @deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert})
2840 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2842 This function will return a value of the @code{gnutls_sign_algorithm_t}
2843 enumeration that is the signature algorithm that has been used to
2844 sign this certificate.
2846 @strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative value on
2850 @subheading gnutls_x509_crt_get_signature
2851 @anchor{gnutls_x509_crt_get_signature}
2852 @deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sizeof_sig})
2853 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2855 @var{sig}: a pointer where the signature part will be copied (may be null).
2857 @var{sizeof_sig}: initially holds the size of @code{sig}
2859 This function will extract the signature field of a certificate.
2861 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2862 negative error value. and a negative value on error.
2865 @subheading gnutls_x509_crt_get_subject_alt_name2
2866 @anchor{gnutls_x509_crt_get_subject_alt_name2}
2867 @deftypefun {int} {gnutls_x509_crt_get_subject_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{ret_type}, unsigned int * @var{critical})
2868 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2870 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2872 @var{ret}: is the place where the alternative name will be copied to
2874 @var{ret_size}: holds the size of ret.
2876 @var{ret_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
2878 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2880 This function will return the alternative names, contained in the
2881 given certificate. It is the same as
2882 @code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it
2883 will return the type of the alternative name in @code{ret_type} even if
2884 the function fails for some reason (i.e. the buffer provided is
2887 @strong{Returns:} the alternative subject name type on success, one of the
2888 enumerated @code{gnutls_x509_subject_alt_name_t}. It will return
2889 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough
2890 to hold the value. In that case @code{ret_size} will be updated with
2891 the required size. If the certificate does not have an
2892 Alternative name with the specified sequence number then
2893 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2896 @subheading gnutls_x509_crt_get_subject_alt_name
2897 @anchor{gnutls_x509_crt_get_subject_alt_name}
2898 @deftypefun {int} {gnutls_x509_crt_get_subject_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical})
2899 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2901 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2903 @var{ret}: is the place where the alternative name will be copied to
2905 @var{ret_size}: holds the size of ret.
2907 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2909 This function retrieves the Alternative Name (2.5.29.17), contained
2910 in the given certificate in the X509v3 Certificate Extensions.
2912 When the SAN type is otherName, it will extract the data in the
2913 otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned.
2914 You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get
2915 the corresponding OID and the "virtual" SAN types (e.g.,
2916 @code{GNUTLS_SAN_OTHERNAME_XMPP}).
2918 If an otherName OID is known, the data will be decoded. Otherwise
2919 the returned data will be DER encoded, and you will have to decode
2920 it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is
2923 @strong{Returns:} the alternative subject name type on success, one of the
2924 enumerated @code{gnutls_x509_subject_alt_name_t}. It will return
2925 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to
2926 hold the value. In that case @code{ret_size} will be updated with the
2927 required size. If the certificate does not have an Alternative
2928 name with the specified sequence number then
2929 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2932 @subheading gnutls_x509_crt_get_subject_alt_othername_oid
2933 @anchor{gnutls_x509_crt_get_subject_alt_othername_oid}
2934 @deftypefun {int} {gnutls_x509_crt_get_subject_alt_othername_oid} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size})
2935 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2937 @var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
2939 @var{ret}: is the place where the otherName OID will be copied to
2941 @var{ret_size}: holds the size of ret.
2943 This function will extract the type OID of an otherName Subject
2944 Alternative Name, contained in the given certificate, and return
2945 the type as an enumerated element.
2947 This function is only useful if
2948 @code{gnutls_x509_crt_get_subject_alt_name()} returned
2949 @code{GNUTLS_SAN_OTHERNAME}.
2951 @strong{Returns:} the alternative subject name type on success, one of the
2952 enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it
2953 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
2954 e.g. @code{GNUTLS_SAN_OTHERNAME_XMPP}, and @code{GNUTLS_SAN_OTHERNAME} for
2955 unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if
2956 @code{ret_size} is not large enough to hold the value. In that case
2957 @code{ret_size} will be updated with the required size. If the
2958 certificate does not have an Alternative name with the specified
2959 sequence number and with the otherName type then
2960 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned.
2963 @subheading gnutls_x509_crt_get_subject_key_id
2964 @anchor{gnutls_x509_crt_get_subject_key_id}
2965 @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})
2966 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
2968 @var{ret}: The place where the identifier will be copied
2970 @var{ret_size}: Holds the size of the result field.
2972 @var{critical}: will be non zero if the extension is marked as critical (may be null)
2974 This function will return the X.509v3 certificate's subject key
2975 identifier. This is obtained by the X.509 Subject Key identifier
2976 extension field (2.5.29.14).
2978 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2979 negative error value.
2982 @subheading gnutls_x509_crt_get_subject_unique_id
2983 @anchor{gnutls_x509_crt_get_subject_unique_id}
2984 @deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{sizeof_buf})
2985 @var{crt}: Holds the certificate
2987 @var{buf}: user allocated memory buffer, will hold the unique id
2989 @var{sizeof_buf}: size of user allocated memory buffer (on input), will hold
2990 actual size of the unique ID on return.
2992 This function will extract the subjectUniqueID value (if present) for
2993 the given certificate.
2995 If the user allocated memory buffer is not large enough to hold the
2996 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
2997 returned, and sizeof_buf will be set to the actual length.
2999 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
3002 @subheading gnutls_x509_crt_get_subject
3003 @anchor{gnutls_x509_crt_get_subject}
3004 @deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn})
3005 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3007 @var{dn}: output variable with pointer to opaque DN.
3009 Return the Certificate's Subject DN as an opaque data type. You
3010 may use @code{gnutls_x509_dn_get_rdn_ava()} to decode the DN.
3012 Note that @code{dn} should be treated as constant. Because points
3013 into the @code{cert} object, you may not deallocate @code{cert}
3014 and continue to access @code{dn}.
3016 @strong{Returns:} Returns 0 on success, or an error code.
3019 @subheading gnutls_x509_crt_get_verify_algorithm
3020 @anchor{gnutls_x509_crt_get_verify_algorithm}
3021 @deftypefun {int} {gnutls_x509_crt_get_verify_algorithm} (gnutls_x509_crt_t @var{crt}, const gnutls_datum_t * @var{signature}, gnutls_digest_algorithm_t * @var{hash})
3022 @var{crt}: Holds the certificate
3024 @var{signature}: contains the signature
3026 @var{hash}: The result of the call with the hash algorithm used for signature
3028 This function will read the certifcate and the signed data to
3029 determine the hash algorithm used to generate the signature.
3031 @strong{Deprecated:} Use @code{gnutls_pubkey_get_verify_algorithm()} instead.
3033 @strong{Returns:} the 0 if the hash algorithm is found. A negative value is
3036 @strong{Since:} 2.8.0
3039 @subheading gnutls_x509_crt_get_version
3040 @anchor{gnutls_x509_crt_get_version}
3041 @deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert})
3042 @var{cert}: should contain a @code{gnutls_x509_crt_t} structure
3044 This function will return the version of the specified Certificate.
3046 @strong{Returns:} version of certificate, or a negative value on error.
3049 @subheading gnutls_x509_crt_import
3050 @anchor{gnutls_x509_crt_import}
3051 @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})
3052 @var{cert}: The structure to store the parsed certificate.
3054 @var{data}: The DER or PEM encoded certificate.
3056 @var{format}: One of DER or PEM
3058 This function will convert the given DER or PEM encoded Certificate
3059 to the native gnutls_x509_crt_t format. The output will be stored
3062 If the Certificate is PEM encoded it should have a header of "X509
3063 CERTIFICATE", or "CERTIFICATE".
3065 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3066 negative error value.
3069 @subheading gnutls_x509_crt_init
3070 @anchor{gnutls_x509_crt_init}
3071 @deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert})
3072 @var{cert}: The structure to be initialized
3074 This function will initialize an X.509 certificate structure.
3076 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3077 negative error value.
3080 @subheading gnutls_x509_crt_list_import
3081 @anchor{gnutls_x509_crt_list_import}
3082 @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})
3083 @var{certs}: The structures to store the parsed certificate. Must not be initialized.
3085 @var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
3087 @var{data}: The PEM encoded certificate.
3089 @var{format}: One of DER or PEM.
3091 @var{flags}: must be zero or an OR'd sequence of gnutls_certificate_import_flags.
3093 This function will convert the given PEM encoded certificate list
3094 to the native gnutls_x509_crt_t format. The output will be stored
3095 in @code{certs}. They will be automatically initialized.
3097 The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause
3098 import to fail if the certificates in the provided buffer are more
3099 than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED}
3100 flag will cause the function to fail if the provided list is not
3101 sorted from subject to issuer.
3103 If the Certificate is PEM encoded it should have a header of "X509
3104 CERTIFICATE", or "CERTIFICATE".
3106 @strong{Returns:} the number of certificates read or a negative error value.
3109 @subheading gnutls_x509_crt_list_verify
3110 @anchor{gnutls_x509_crt_list_verify}
3111 @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})
3112 @var{cert_list}: is the certificate list to be verified
3114 @var{cert_list_length}: holds the number of certificate in cert_list
3116 @var{CA_list}: is the CA list which will be used in verification
3118 @var{CA_list_length}: holds the number of CA certificate in CA_list
3120 @var{CRL_list}: holds a list of CRLs.
3122 @var{CRL_list_length}: the length of CRL list.
3124 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3126 @var{verify}: will hold the certificate verification output.
3128 This function will try to verify the given certificate list and
3129 return its status. If no flags are specified (0), this function
3130 will use the basicConstraints (2.5.29.19) PKIX extension. This
3131 means that only a certificate authority is allowed to sign a
3134 You must also check the peer's name in order to check if the verified
3135 certificate belongs to the actual peer.
3137 The certificate verification output will be put in @code{verify} and will
3138 be one or more of the gnutls_certificate_status_t enumerated
3139 elements bitwise or'd. For a more detailed verification status use
3140 @code{gnutls_x509_crt_verify()} per list element.
3142 @strong{GNUTLS_CERT_INVALID:} the certificate chain is not valid.
3144 @strong{GNUTLS_CERT_REVOKED:} a certificate in the chain has been revoked.
3146 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3147 negative error value.
3150 @subheading gnutls_x509_crt_print
3151 @anchor{gnutls_x509_crt_print}
3152 @deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
3153 @var{cert}: The structure to be printed
3155 @var{format}: Indicate the format to use
3157 @var{out}: Newly allocated datum with zero terminated string.
3159 This function will pretty print a X.509 certificate, suitable for
3162 If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the
3163 certificate will be output, on multiple lines. The
3164 @code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some
3165 selected fields, which is useful for logging purposes.
3167 The output @code{out} needs to be deallocate using @code{gnutls_free()}.
3169 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3170 negative error value.
3173 @subheading gnutls_x509_crt_privkey_sign
3174 @anchor{gnutls_x509_crt_privkey_sign}
3175 @deftypefun {int} {gnutls_x509_crt_privkey_sign} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
3176 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3178 @var{issuer}: is the certificate of the certificate issuer
3180 @var{issuer_key}: holds the issuer's private key
3182 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
3184 @var{flags}: must be 0
3186 This function will sign the certificate with the issuer's private key, and
3187 will copy the issuer's information into the certificate.
3189 This must be the last step in a certificate generation since all
3190 the previously set parameters are now signed.
3192 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3193 negative error value.
3196 @subheading gnutls_x509_crt_set_activation_time
3197 @anchor{gnutls_x509_crt_set_activation_time}
3198 @deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time})
3199 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3201 @var{act_time}: The actual time
3203 This function will set the time this Certificate was or will be
3206 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3207 negative error value.
3210 @subheading gnutls_x509_crt_set_authority_key_id
3211 @anchor{gnutls_x509_crt_set_authority_key_id}
3212 @deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3213 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3215 @var{id}: The key ID
3217 @var{id_size}: Holds the size of the serial field.
3219 This function will set the X.509 certificate's authority key ID extension.
3220 Only the keyIdentifier field can be set with this function.
3222 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3223 negative error value.
3226 @subheading gnutls_x509_crt_set_basic_constraints
3227 @anchor{gnutls_x509_crt_set_basic_constraints}
3228 @deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint})
3229 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3231 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3233 @var{pathLenConstraint}: non-negative values indicate maximum length of path,
3234 and negative values indicate that the pathLenConstraints field should
3237 This function will set the basicConstraints certificate extension.
3239 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3240 negative error value.
3243 @subheading gnutls_x509_crt_set_ca_status
3244 @anchor{gnutls_x509_crt_set_ca_status}
3245 @deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca})
3246 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3248 @var{ca}: true(1) or false(0). Depending on the Certificate authority status.
3250 This function will set the basicConstraints certificate extension.
3251 Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control
3252 the pathLenConstraint field too.
3254 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3255 negative error value.
3258 @subheading gnutls_x509_crt_set_crl_dist_points2
3259 @anchor{gnutls_x509_crt_set_crl_dist_points2}
3260 @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})
3261 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3263 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3265 @var{data}: The data to be set
3267 @var{data_size}: The data size
3269 @var{reason_flags}: revocation reasons
3271 This function will set the CRL distribution points certificate extension.
3273 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3274 negative error value.
3276 @strong{Since:} 2.6.0
3279 @subheading gnutls_x509_crt_set_crl_dist_points
3280 @anchor{gnutls_x509_crt_set_crl_dist_points}
3281 @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})
3282 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3284 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3286 @var{data_string}: The data to be set
3288 @var{reason_flags}: revocation reasons
3290 This function will set the CRL distribution points certificate extension.
3292 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3293 negative error value.
3296 @subheading gnutls_x509_crt_set_crq_extensions
3297 @anchor{gnutls_x509_crt_set_crq_extensions}
3298 @deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3299 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3301 @var{crq}: holds a certificate request
3303 This function will set extensions from the given request to the
3306 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3307 negative error value.
3309 @strong{Since:} 2.8.0
3312 @subheading gnutls_x509_crt_set_crq
3313 @anchor{gnutls_x509_crt_set_crq}
3314 @deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq})
3315 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3317 @var{crq}: holds a certificate request
3319 This function will set the name and public parameters as well as
3320 the extensions from the given certificate request to the certificate.
3321 Only RSA keys are currently supported.
3323 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3324 negative error value.
3327 @subheading gnutls_x509_crt_set_dn_by_oid
3328 @anchor{gnutls_x509_crt_set_dn_by_oid}
3329 @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})
3330 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3332 @var{oid}: holds an Object Identifier in a null terminated string
3334 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3336 @var{name}: a pointer to the name
3338 @var{sizeof_name}: holds the size of @code{name}
3340 This function will set the part of the name of the Certificate
3341 subject, specified by the given OID. The input string should be
3342 ASCII or UTF-8 encoded.
3344 Some helper macros with popular OIDs can be found in gnutls/x509.h
3345 With this function you can only set the known OIDs. You can test
3346 for known OIDs using @code{gnutls_x509_dn_oid_known()}. For OIDs that are
3347 not known (by gnutls) you should properly DER encode your data,
3348 and call this function with @code{raw_flag} set.
3350 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3351 negative error value.
3354 @subheading gnutls_x509_crt_set_expiration_time
3355 @anchor{gnutls_x509_crt_set_expiration_time}
3356 @deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time})
3357 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3359 @var{exp_time}: The actual time
3361 This function will set the time this Certificate will expire.
3363 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3364 negative error value.
3367 @subheading gnutls_x509_crt_set_extension_by_oid
3368 @anchor{gnutls_x509_crt_set_extension_by_oid}
3369 @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})
3370 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3372 @var{oid}: holds an Object Identified in null terminated string
3374 @var{buf}: a pointer to a DER encoded data
3376 @var{sizeof_buf}: holds the size of @code{buf}
3378 @var{critical}: should be non zero if the extension is to be marked as critical
3380 This function will set an the extension, by the specified OID, in
3381 the certificate. The extension data should be binary data DER
3384 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3385 negative error value.
3388 @subheading gnutls_x509_crt_set_issuer_dn_by_oid
3389 @anchor{gnutls_x509_crt_set_issuer_dn_by_oid}
3390 @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})
3391 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3393 @var{oid}: holds an Object Identifier in a null terminated string
3395 @var{raw_flag}: must be 0, or 1 if the data are DER encoded
3397 @var{name}: a pointer to the name
3399 @var{sizeof_name}: holds the size of @code{name}
3401 This function will set the part of the name of the Certificate
3402 issuer, specified by the given OID. The input string should be
3403 ASCII or UTF-8 encoded.
3405 Some helper macros with popular OIDs can be found in gnutls/x509.h
3406 With this function you can only set the known OIDs. You can test
3407 for known OIDs using @code{gnutls_x509_dn_oid_known()}. For OIDs that are
3408 not known (by gnutls) you should properly DER encode your data,
3409 and call this function with @code{raw_flag} set.
3411 Normally you do not need to call this function, since the signing
3412 operation will copy the signer's name as the issuer of the
3415 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3416 negative error value.
3419 @subheading gnutls_x509_crt_set_key_purpose_oid
3420 @anchor{gnutls_x509_crt_set_key_purpose_oid}
3421 @deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical})
3422 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3424 @var{oid}: a pointer to a null terminated string that holds the OID
3426 @var{critical}: Whether this extension will be critical or not
3428 This function will set the key purpose OIDs of the Certificate.
3429 These are stored in the Extended Key Usage extension (2.5.29.37)
3430 See the GNUTLS_KP_* definitions for human readable names.
3432 Subsequent calls to this function will append OIDs to the OID list.
3434 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
3435 otherwise an error code is returned.
3438 @subheading gnutls_x509_crt_set_key_usage
3439 @anchor{gnutls_x509_crt_set_key_usage}
3440 @deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage})
3441 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3443 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
3445 This function will set the keyUsage certificate extension.
3447 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3448 negative error value.
3451 @subheading gnutls_x509_crt_set_key
3452 @anchor{gnutls_x509_crt_set_key}
3453 @deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key})
3454 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3456 @var{key}: holds a private key
3458 This function will set the public parameters from the given
3459 private key to the certificate. Only RSA keys are currently
3462 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3463 negative error value.
3466 @subheading gnutls_x509_crt_set_proxy_dn
3467 @anchor{gnutls_x509_crt_set_proxy_dn}
3468 @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})
3469 @var{crt}: a gnutls_x509_crt_t structure with the new proxy cert
3471 @var{eecrt}: the end entity certificate that will be issuing the proxy
3473 @var{raw_flag}: must be 0, or 1 if the CN is DER encoded
3475 @var{name}: a pointer to the CN name, may be NULL (but MUST then be added later)
3477 @var{sizeof_name}: holds the size of @code{name}
3479 This function will set the subject in @code{crt} to the end entity's
3480 @code{eecrt} subject name, and add a single Common Name component @code{name}
3481 of size @code{sizeof_name}. This corresponds to the required proxy
3482 certificate naming style. Note that if @code{name} is @code{NULL}, you MUST
3483 set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar.
3485 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3486 negative error value.
3489 @subheading gnutls_x509_crt_set_proxy
3490 @anchor{gnutls_x509_crt_set_proxy}
3491 @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})
3492 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3494 @var{pathLenConstraint}: non-negative values indicate maximum length of path,
3495 and negative values indicate that the pathLenConstraints field should
3498 @var{policyLanguage}: OID describing the language of @code{policy}.
3500 @var{policy}: opaque byte array with policy language, can be @code{NULL}
3502 @var{sizeof_policy}: size of @code{policy}.
3504 This function will set the proxyCertInfo extension.
3506 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3507 negative error value.
3510 @subheading gnutls_x509_crt_set_serial
3511 @anchor{gnutls_x509_crt_set_serial}
3512 @deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size})
3513 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3515 @var{serial}: The serial number
3517 @var{serial_size}: Holds the size of the serial field.
3519 This function will set the X.509 certificate's serial number.
3520 Serial is not always a 32 or 64bit number. Some CAs use large
3521 serial numbers, thus it may be wise to handle it as something
3524 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3525 negative error value.
3528 @subheading gnutls_x509_crt_set_subject_alt_name
3529 @anchor{gnutls_x509_crt_set_subject_alt_name}
3530 @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})
3531 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3533 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3535 @var{data}: The data to be set
3537 @var{data_size}: The size of data to be set
3539 @var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
3541 This function will set the subject alternative name certificate
3542 extension. It can set the following types:
3544 &GNUTLS_SAN_DNSNAME: as a text string
3546 &GNUTLS_SAN_RFC822NAME: as a text string
3548 &GNUTLS_SAN_URI: as a text string
3550 &GNUTLS_SAN_IPADDRESS: as a binary IP address (4 or 16 bytes)
3552 Other values can be set as binary values with the proper DER encoding.
3554 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3555 negative error value.
3557 @strong{Since:} 2.6.0
3560 @subheading gnutls_x509_crt_set_subject_alternative_name
3561 @anchor{gnutls_x509_crt_set_subject_alternative_name}
3562 @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})
3563 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3565 @var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations
3567 @var{data_string}: The data to be set, a zero terminated string
3569 This function will set the subject alternative name certificate
3570 extension. This function assumes that data can be expressed as a null
3573 The name of the function is unfortunate since it is incosistent with
3574 @code{gnutls_x509_crt_get_subject_alt_name()}.
3576 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3577 negative error value.
3580 @subheading gnutls_x509_crt_set_subject_key_id
3581 @anchor{gnutls_x509_crt_set_subject_key_id}
3582 @deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size})
3583 @var{cert}: a certificate of type @code{gnutls_x509_crt_t}
3585 @var{id}: The key ID
3587 @var{id_size}: Holds the size of the serial field.
3589 This function will set the X.509 certificate's subject key ID
3592 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3593 negative error value.
3596 @subheading gnutls_x509_crt_set_version
3597 @anchor{gnutls_x509_crt_set_version}
3598 @deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version})
3599 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3601 @var{version}: holds the version number. For X.509v1 certificates must be 1.
3603 This function will set the version of the certificate. This must
3604 be one for X.509 version 1, and so on. Plain certificates without
3605 extensions must have version set to one.
3607 To create well-formed certificates, you must specify version 3 if
3608 you use any certificate extensions. Extensions are created by
3609 functions such as @code{gnutls_x509_crt_set_subject_alt_name()}
3610 or @code{gnutls_x509_crt_set_key_usage()}.
3612 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3613 negative error value.
3616 @subheading gnutls_x509_crt_sign2
3617 @anchor{gnutls_x509_crt_sign2}
3618 @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})
3619 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3621 @var{issuer}: is the certificate of the certificate issuer
3623 @var{issuer_key}: holds the issuer's private key
3625 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
3627 @var{flags}: must be 0
3629 This function will sign the certificate with the issuer's private key, and
3630 will copy the issuer's information into the certificate.
3632 This must be the last step in a certificate generation since all
3633 the previously set parameters are now signed.
3635 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3636 negative error value.
3639 @subheading gnutls_x509_crt_sign
3640 @anchor{gnutls_x509_crt_sign}
3641 @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})
3642 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
3644 @var{issuer}: is the certificate of the certificate issuer
3646 @var{issuer_key}: holds the issuer's private key
3648 This function is the same a @code{gnutls_x509_crt_sign2()} with no flags,
3649 and SHA1 as the hash algorithm.
3651 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3652 negative error value.
3655 @subheading gnutls_x509_crt_verify_data
3656 @anchor{gnutls_x509_crt_verify_data}
3657 @deftypefun {int} {gnutls_x509_crt_verify_data} (gnutls_x509_crt_t @var{crt}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature})
3658 @var{crt}: Holds the certificate
3660 @var{flags}: should be 0 for now
3662 @var{data}: holds the data to be signed
3664 @var{signature}: contains the signature
3666 This function will verify the given signed data, using the
3667 parameters from the certificate.
3669 Deprecated. Please use @code{gnutls_pubkey_verify_data()}.
3671 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
3672 is returned, and a positive code on success.
3675 @subheading gnutls_x509_crt_verify_hash
3676 @anchor{gnutls_x509_crt_verify_hash}
3677 @deftypefun {int} {gnutls_x509_crt_verify_hash} (gnutls_x509_crt_t @var{crt}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash}, const gnutls_datum_t * @var{signature})
3678 @var{crt}: Holds the certificate
3680 @var{flags}: should be 0 for now
3682 @var{hash}: holds the hash digest to be verified
3684 @var{signature}: contains the signature
3686 This function will verify the given signed digest, using the
3687 parameters from the certificate.
3689 Deprecated. Please use @code{gnutls_pubkey_verify_data()}.
3691 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
3692 is returned, and a positive code on success.
3695 @subheading gnutls_x509_crt_verify
3696 @anchor{gnutls_x509_crt_verify}
3697 @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})
3698 @var{cert}: is the certificate to be verified
3700 @var{CA_list}: is one certificate that is considered to be trusted one
3702 @var{CA_list_length}: holds the number of CA certificate in CA_list
3704 @var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
3706 @var{verify}: will hold the certificate verification output.
3708 This function will try to verify the given certificate and return
3711 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3712 negative error value.
3715 @subheading gnutls_x509_dn_deinit
3716 @anchor{gnutls_x509_dn_deinit}
3717 @deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn})
3718 @var{dn}: a DN opaque object pointer.
3720 This function deallocates the DN object as returned by
3721 @code{gnutls_x509_dn_import()}.
3723 @strong{Since:} 2.4.0
3726 @subheading gnutls_x509_dn_export
3727 @anchor{gnutls_x509_dn_export}
3728 @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})
3729 @var{dn}: Holds the opaque DN object
3731 @var{format}: the format of output params. One of PEM or DER.
3733 @var{output_data}: will contain a DN 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 DN to DER or PEM format.
3740 If the buffer provided is not long enough to hold the output, then
3741 *@code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
3744 If the structure is PEM encoded, it will have a header
3747 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3748 negative error value.
3751 @subheading gnutls_x509_dn_get_rdn_ava
3752 @anchor{gnutls_x509_dn_get_rdn_ava}
3753 @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})
3754 @var{dn}: input variable with opaque DN pointer
3756 @var{irdn}: index of RDN
3758 @var{iava}: index of AVA.
3760 @var{ava}: Pointer to structure which will hold output information.
3762 Get pointers to data within the DN.
3764 Note that @code{ava} will contain pointers into the @code{dn} structure, so you
3765 should not modify any data or deallocate it. Note also that the DN
3766 in turn points into the original certificate structure, and thus
3767 you may not deallocate the certificate and continue to access @code{dn}.
3769 @strong{Returns:} Returns 0 on success, or an error code.
3772 @subheading gnutls_x509_dn_import
3773 @anchor{gnutls_x509_dn_import}
3774 @deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data})
3775 @var{dn}: the structure that will hold the imported DN
3777 @var{data}: should contain a DER encoded RDN sequence
3779 This function parses an RDN sequence and stores the result to a
3780 @code{gnutls_x509_dn_t} structure. The structure must have been initialized
3781 with @code{gnutls_x509_dn_init()}. You may use @code{gnutls_x509_dn_get_rdn_ava()} to
3784 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3785 negative error value.
3787 @strong{Since:} 2.4.0
3790 @subheading gnutls_x509_dn_init
3791 @anchor{gnutls_x509_dn_init}
3792 @deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn})
3793 @var{dn}: the object to be initialized
3795 This function initializes a @code{gnutls_x509_dn_t} structure.
3797 The object returned must be deallocated using
3798 @code{gnutls_x509_dn_deinit()}.
3800 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3801 negative error value.
3803 @strong{Since:} 2.4.0
3805 @subheading gnutls_x509_dn_oid_known
3806 @anchor{gnutls_x509_dn_oid_known}
3807 @deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid})
3808 @var{oid}: holds an Object Identifier in a null terminated string
3810 This function will inform about known DN OIDs. This is useful since
3811 functions like @code{gnutls_x509_crt_set_dn_by_oid()} use the information
3812 on known OIDs to properly encode their input. Object Identifiers
3813 that are not known are not encoded by these functions, and their
3814 input is stored directly into the ASN.1 structure. In that case of
3815 unknown OIDs, you have the responsibility of DER encoding your
3818 @strong{Returns:} 1 on known OIDs and 0 otherwise.
3821 @subheading gnutls_x509_privkey_cpy
3822 @anchor{gnutls_x509_privkey_cpy}
3823 @deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src})
3824 @var{dst}: The destination key, which should be initialized.
3826 @var{src}: The source key
3828 This function will copy a private key from source to destination
3829 key. Destination has to be initialized.
3831 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3832 negative error value.
3835 @subheading gnutls_x509_privkey_deinit
3836 @anchor{gnutls_x509_privkey_deinit}
3837 @deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key})
3838 @var{key}: The structure to be deinitialized
3840 This function will deinitialize a private key structure.
3843 @subheading gnutls_x509_privkey_export_dsa_raw
3844 @anchor{gnutls_x509_privkey_export_dsa_raw}
3845 @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})
3846 @var{key}: a structure that holds the DSA parameters
3848 @var{p}: will hold the p
3850 @var{q}: will hold the q
3852 @var{g}: will hold the g
3854 @var{y}: will hold the y
3856 @var{x}: will hold the x
3858 This function will export the DSA private key's parameters found
3859 in the given structure. The new parameters will be allocated using
3860 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3862 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3863 negative error value.
3866 @subheading gnutls_x509_privkey_export_pkcs8
3867 @anchor{gnutls_x509_privkey_export_pkcs8}
3868 @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})
3869 @var{key}: Holds the key
3871 @var{format}: the format of output params. One of PEM or DER.
3873 @var{password}: the password that will be used to encrypt the key.
3875 @var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3877 @var{output_data}: will contain a private key PEM or DER encoded
3879 @var{output_data_size}: holds the size of output_data (and will be
3880 replaced by the actual size of parameters)
3882 This function will export the private key to a PKCS8 structure.
3883 Both RSA and DSA keys can be exported. For DSA keys we use
3884 PKCS @code{11} definitions. If the flags do not specify the encryption
3885 cipher, then the default 3DES (PBES2) will be used.
3887 The @code{password} can be either ASCII or UTF-8 in the default PBES2
3888 encryption schemas, or ASCII for the PKCS12 schemas.
3890 If the buffer provided is not long enough to hold the output, then
3891 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3894 If the structure is PEM encoded, it will have a header
3895 of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if
3896 encryption is not used.
3898 @strong{Return value:} In case of failure a negative value will be
3899 returned, and 0 on success.
3902 @subheading gnutls_x509_privkey_export_rsa_raw2
3903 @anchor{gnutls_x509_privkey_export_rsa_raw2}
3904 @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})
3905 @var{key}: a structure that holds the rsa parameters
3907 @var{m}: will hold the modulus
3909 @var{e}: will hold the public exponent
3911 @var{d}: will hold the private exponent
3913 @var{p}: will hold the first prime (p)
3915 @var{q}: will hold the second prime (q)
3917 @var{u}: will hold the coefficient
3919 @var{e1}: will hold e1 = d mod (p-1)
3921 @var{e2}: will hold e2 = d mod (q-1)
3923 This function will export the RSA private key's parameters found
3924 in the given structure. The new parameters will be allocated using
3925 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3927 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3928 negative error value.
3931 @subheading gnutls_x509_privkey_export_rsa_raw
3932 @anchor{gnutls_x509_privkey_export_rsa_raw}
3933 @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})
3934 @var{key}: a structure that holds the rsa parameters
3936 @var{m}: will hold the modulus
3938 @var{e}: will hold the public exponent
3940 @var{d}: will hold the private exponent
3942 @var{p}: will hold the first prime (p)
3944 @var{q}: will hold the second prime (q)
3946 @var{u}: will hold the coefficient
3948 This function will export the RSA private key's parameters found
3949 in the given structure. The new parameters will be allocated using
3950 @code{gnutls_malloc()} and will be stored in the appropriate datum.
3952 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3953 negative error value.
3956 @subheading gnutls_x509_privkey_export
3957 @anchor{gnutls_x509_privkey_export}
3958 @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})
3959 @var{key}: Holds the key
3961 @var{format}: the format of output params. One of PEM or DER.
3963 @var{output_data}: will contain a private key PEM or DER encoded
3965 @var{output_data_size}: holds the size of output_data (and will be
3966 replaced by the actual size of parameters)
3968 This function will export the private key to a PKCS1 structure for
3969 RSA keys, or an integer sequence for DSA keys. The DSA keys are in
3970 the same format with the parameters used by openssl.
3972 If the buffer provided is not long enough to hold the output, then
3973 *@code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}
3976 If the structure is PEM encoded, it will have a header
3977 of "BEGIN RSA PRIVATE KEY".
3979 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3980 negative error value.
3983 @subheading gnutls_x509_privkey_fix
3984 @anchor{gnutls_x509_privkey_fix}
3985 @deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key})
3986 @var{key}: Holds the key
3988 This function will recalculate the secondary parameters in a key.
3989 In RSA keys, this can be the coefficient and exponent1,2.
3991 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3992 negative error value.
3995 @subheading gnutls_x509_privkey_generate
3996 @anchor{gnutls_x509_privkey_generate}
3997 @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})
3998 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
4000 @var{algo}: is one of RSA or DSA.
4002 @var{bits}: the size of the modulus
4004 @var{flags}: unused for now. Must be 0.
4006 This function will generate a random private key. Note that this
4007 function must be called on an empty private key.
4009 Do not set the number of bits directly, use @code{gnutls_sec_param_to_pk_bits()}.
4011 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4012 negative error value.
4015 @subheading gnutls_x509_privkey_get_key_id
4016 @anchor{gnutls_x509_privkey_get_key_id}
4017 @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})
4018 @var{key}: Holds the key
4020 @var{flags}: should be 0 for now
4022 @var{output_data}: will contain the key ID
4024 @var{output_data_size}: holds the size of output_data (and will be
4025 replaced by the actual size of parameters)
4027 This function will return a unique ID the depends on the public key
4028 parameters. This ID can be used in checking whether a certificate
4029 corresponds to the given key.
4031 If the buffer provided is not long enough to hold the output, then
4032 *@code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
4033 be returned. The output will normally be a SHA-1 hash output,
4036 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4037 negative error value.
4040 @subheading gnutls_x509_privkey_get_pk_algorithm
4041 @anchor{gnutls_x509_privkey_get_pk_algorithm}
4042 @deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key})
4043 @var{key}: should contain a @code{gnutls_x509_privkey_t} structure
4045 This function will return the public key algorithm of a private
4048 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
4049 success, or a negative value on error.
4052 @subheading gnutls_x509_privkey_import_dsa_raw
4053 @anchor{gnutls_x509_privkey_import_dsa_raw}
4054 @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})
4055 @var{key}: The structure to store the parsed key
4057 @var{p}: holds the p
4059 @var{q}: holds the q
4061 @var{g}: holds the g
4063 @var{y}: holds the y
4065 @var{x}: holds the x
4067 This function will convert the given DSA raw parameters to the
4068 native @code{gnutls_x509_privkey_t} format. The output will be stored
4071 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4072 negative error value.
4075 @subheading gnutls_x509_privkey_import_pkcs8
4076 @anchor{gnutls_x509_privkey_import_pkcs8}
4077 @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})
4078 @var{key}: The structure to store the parsed key
4080 @var{data}: The DER or PEM encoded key.
4082 @var{format}: One of DER or PEM
4084 @var{password}: the password to decrypt the key (if it is encrypted).
4086 @var{flags}: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
4088 This function will convert the given DER or PEM encoded PKCS8 2.0
4089 encrypted key to the native gnutls_x509_privkey_t format. The
4090 output will be stored in @code{key}. Both RSA and DSA keys can be
4091 imported, and flags can only be used to indicate an unencrypted
4094 The @code{password} can be either ASCII or UTF-8 in the default PBES2
4095 encryption schemas, or ASCII for the PKCS12 schemas.
4097 If the Certificate is PEM encoded it should have a header of
4098 "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to
4099 specify the flags if the key is DER encoded, since in that case
4100 the encryption status cannot be auto-detected.
4102 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4103 negative error value.
4106 @subheading gnutls_x509_privkey_import_rsa_raw2
4107 @anchor{gnutls_x509_privkey_import_rsa_raw2}
4108 @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})
4109 @var{key}: The structure to store the parsed key
4111 @var{m}: holds the modulus
4113 @var{e}: holds the public exponent
4115 @var{d}: holds the private exponent
4117 @var{p}: holds the first prime (p)
4119 @var{q}: holds the second prime (q)
4121 @var{u}: holds the coefficient
4123 @var{e1}: holds e1 = d mod (p-1)
4125 @var{e2}: holds e2 = d mod (q-1)
4127 This function will convert the given RSA raw parameters to the
4128 native @code{gnutls_x509_privkey_t} format. The output will be stored in
4131 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4132 negative error value.
4135 @subheading gnutls_x509_privkey_import_rsa_raw
4136 @anchor{gnutls_x509_privkey_import_rsa_raw}
4137 @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})
4138 @var{key}: The structure to store the parsed key
4140 @var{m}: holds the modulus
4142 @var{e}: holds the public exponent
4144 @var{d}: holds the private exponent
4146 @var{p}: holds the first prime (p)
4148 @var{q}: holds the second prime (q)
4150 @var{u}: holds the coefficient
4152 This function will convert the given RSA raw parameters to the
4153 native @code{gnutls_x509_privkey_t} format. The output will be stored in
4156 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4157 negative error value.
4160 @subheading gnutls_x509_privkey_import
4161 @anchor{gnutls_x509_privkey_import}
4162 @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})
4163 @var{key}: The structure to store the parsed key
4165 @var{data}: The DER or PEM encoded certificate.
4167 @var{format}: One of DER or PEM
4169 This function will convert the given DER or PEM encoded key to the
4170 native @code{gnutls_x509_privkey_t} format. The output will be stored in
4173 If the key is PEM encoded it should have a header of "RSA PRIVATE
4174 KEY", or "DSA PRIVATE KEY".
4176 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4177 negative error value.
4180 @subheading gnutls_x509_privkey_init
4181 @anchor{gnutls_x509_privkey_init}
4182 @deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key})
4183 @var{key}: The structure to be initialized
4185 This function will initialize an private key structure.
4187 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4188 negative error value.
4191 @subheading gnutls_x509_privkey_sec_param
4192 @anchor{gnutls_x509_privkey_sec_param}
4193 @deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key})
4194 @var{key}: a key structure
4196 This function will return the security parameter appropriate with
4199 @strong{Returns:} On success, a valid security parameter is returned otherwise
4200 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
4203 @subheading gnutls_x509_privkey_sign_data
4204 @anchor{gnutls_x509_privkey_sign_data}
4205 @deftypefun {int} {gnutls_x509_privkey_sign_data} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, void * @var{signature}, size_t * @var{signature_size})
4206 @var{key}: Holds the key
4208 @var{digest}: should be MD5 or SHA1
4210 @var{flags}: should be 0 for now
4212 @var{data}: holds the data to be signed
4214 @var{signature}: will contain the signature
4216 @var{signature_size}: holds the size of signature (and will be replaced
4219 This function will sign the given data using a signature algorithm
4220 supported by the private key. Signature algorithms are always used
4221 together with a hash functions. Different hash functions may be
4222 used for the RSA algorithm, but only SHA-1 for the DSA keys.
4224 If the buffer provided is not long enough to hold the output, then
4225 *@code{signature_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
4228 Use @code{gnutls_x509_crt_get_preferred_hash_algorithm()} to determine
4231 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4232 negative error value.
4234 @strong{Deprecated:} Use @code{gnutls_privkey_sign_data()}.
4237 @subheading gnutls_x509_privkey_sign_hash
4238 @anchor{gnutls_x509_privkey_sign_hash}
4239 @deftypefun {int} {gnutls_x509_privkey_sign_hash} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{hash}, gnutls_datum_t * @var{signature})
4240 @var{key}: Holds the key
4242 @var{hash}: holds the data to be signed
4244 @var{signature}: will contain newly allocated signature
4246 This function will sign the given hash using the private key. Do not
4247 use this function directly unless you know what it is. Typical signing
4248 requires the data to be hashed and stored in special formats
4249 (e.g. BER Digest-Info for RSA).
4251 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4252 negative error value.
4254 @strong{Deprecated in:} 2.12.0
4257 @subheading gnutls_x509_privkey_verify_data
4258 @anchor{gnutls_x509_privkey_verify_data}
4259 @deftypefun {int} {gnutls_x509_privkey_verify_data} (gnutls_x509_privkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature})
4260 @var{key}: Holds the key
4262 @var{flags}: should be 0 for now
4264 @var{data}: holds the data to be signed
4266 @var{signature}: contains the signature
4268 This function will verify the given signed data, using the
4269 parameters in the private key.
4271 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
4272 is returned, and a positive code on success.
4274 @strong{Deprecated:} Use @code{gnutls_pubkey_verify_data()}.
4277 @subheading gnutls_x509_rdn_get_by_oid
4278 @anchor{gnutls_x509_rdn_get_by_oid}
4279 @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})
4280 @var{idn}: should contain a DER encoded RDN sequence
4282 @var{oid}: an Object Identifier
4284 @var{indx}: In case multiple same OIDs exist in the RDN indicates which
4285 to send. Use 0 for the first one.
4287 @var{raw_flag}: If non zero then the raw DER data are returned.
4289 @var{buf}: a pointer to a structure to hold the peer's name
4291 @var{sizeof_buf}: holds the size of @code{buf}
4293 This function will return the name of the given Object identifier,
4294 of the RDN sequence. The name will be encoded using the rules
4297 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, or
4298 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and *@code{sizeof_buf} is
4299 updated if the provided buffer is not long enough, otherwise a
4300 negative error value.
4303 @subheading gnutls_x509_rdn_get_oid
4304 @anchor{gnutls_x509_rdn_get_oid}
4305 @deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, int @var{indx}, void * @var{buf}, size_t * @var{sizeof_buf})
4306 @var{idn}: should contain a DER encoded RDN sequence
4308 @var{indx}: Indicates which OID to return. Use 0 for the first one.
4310 @var{buf}: a pointer to a structure to hold the peer's name OID
4312 @var{sizeof_buf}: holds the size of @code{buf}
4314 This function will return the specified Object identifier, of the
4317 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, or
4318 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and *@code{sizeof_buf} is
4319 updated if the provided buffer is not long enough, otherwise a
4320 negative error value.
4322 @strong{Since:} 2.4.0
4325 @subheading gnutls_x509_rdn_get
4326 @anchor{gnutls_x509_rdn_get}
4327 @deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{sizeof_buf})
4328 @var{idn}: should contain a DER encoded RDN sequence
4330 @var{buf}: a pointer to a structure to hold the peer's name
4332 @var{sizeof_buf}: holds the size of @code{buf}
4334 This function will return the name of the given RDN sequence. The
4335 name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
4338 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, or
4339 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and *@code{sizeof_buf} is
4340 updated if the provided buffer is not long enough, otherwise a
4341 negative error value.