1 This is gnutls.info, produced by makeinfo version 5.2 from gnutls.texi.
3 This manual is last updated 5 April 2014 for version 3.3.5 of GnuTLS.
5 Copyright (C) 2001-2013 Free Software Foundation, Inc.\\ Copyright (C)
6 2001-2013 Nikos Mavrogiannopoulos
8 Permission is granted to copy, distribute and/or modify this
9 document under the terms of the GNU Free Documentation License,
10 Version 1.3 or any later version published by the Free Software
11 Foundation; with no Invariant Sections, no Front-Cover Texts, and
12 no Back-Cover Texts. A copy of the license is included in the
13 section entitled "GNU Free Documentation License".
14 INFO-DIR-SECTION Software libraries
16 * GnuTLS: (gnutls). GNU Transport Layer Security Library.
19 INFO-DIR-SECTION System Administration
21 * certtool: (gnutls)Invoking certtool. Manipulate certificates and keys.
22 * gnutls-serv: (gnutls)Invoking gnutls-serv. GnuTLS test server.
23 * gnutls-cli: (gnutls)Invoking gnutls-cli. GnuTLS test client.
24 * gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug. GnuTLS debug client.
25 * psktool: (gnutls)Invoking psktool. Simple TLS-Pre-Shared-Keys manager.
26 * srptool: (gnutls)Invoking srptool. Simple SRP password tool.
30 File: gnutls.info, Node: OCSP API, Next: OpenPGP API, Prev: X509 certificate API, Up: API reference
35 The following functions are for OCSP certificate status checking. Their
36 prototypes lie in 'gnutls/ocsp.h'.
38 gnutls_ocsp_req_add_cert
39 ------------------------
41 -- Function: int gnutls_ocsp_req_add_cert (gnutls_ocsp_req_t REQ,
42 gnutls_digest_algorithm_t DIGEST, gnutls_x509_crt_t ISSUER,
43 gnutls_x509_crt_t CERT)
44 REQ: should contain a 'gnutls_ocsp_req_t' structure
46 DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
48 ISSUER: issuer of 'subject' certificate
50 CERT: certificate to request status for
52 This function will add another request to the OCSP request for a
53 particular certificate. The issuer name hash, issuer key hash, and
54 serial number fields is populated as follows. The issuer name and
55 the serial number is taken from 'cert' . The issuer key is taken
56 from 'issuer' . The hashed values will be hashed using the
57 'digest' algorithm, normally 'GNUTLS_DIG_SHA1' .
59 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
60 otherwise a negative error code is returned.
62 gnutls_ocsp_req_add_cert_id
63 ---------------------------
65 -- Function: int gnutls_ocsp_req_add_cert_id (gnutls_ocsp_req_t REQ,
66 gnutls_digest_algorithm_t DIGEST, const gnutls_datum_t *
67 ISSUER_NAME_HASH, const gnutls_datum_t * ISSUER_KEY_HASH,
68 const gnutls_datum_t * SERIAL_NUMBER)
69 REQ: should contain a 'gnutls_ocsp_req_t' structure
71 DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
73 ISSUER_NAME_HASH: hash of issuer's DN
75 ISSUER_KEY_HASH: hash of issuer's public key
77 SERIAL_NUMBER: serial number of certificate to check
79 This function will add another request to the OCSP request for a
80 particular certificate having the issuer name hash of
81 'issuer_name_hash' and issuer key hash of 'issuer_key_hash' (both
82 hashed using 'digest' ) and serial number 'serial_number' .
84 The information needed corresponds to the CertID structure:
86 <informalexample><programlisting> CertID ::= SEQUENCE {
87 hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, -
88 Hash of Issuer's DN issuerKeyHash OCTET STRING, - Hash of Issuers
89 public key serialNumber CertificateSerialNumber }
90 </programlisting></informalexample>
92 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
93 otherwise a negative error code is returned.
95 gnutls_ocsp_req_deinit
96 ----------------------
98 -- Function: void gnutls_ocsp_req_deinit (gnutls_ocsp_req_t REQ)
99 REQ: The structure to be deinitialized
101 This function will deinitialize a OCSP request structure.
103 gnutls_ocsp_req_export
104 ----------------------
106 -- Function: int gnutls_ocsp_req_export (gnutls_ocsp_req_t REQ,
107 gnutls_datum_t * DATA)
108 REQ: Holds the OCSP request
110 DATA: newly allocate buffer holding DER encoded OCSP request
112 This function will export the OCSP request to DER format.
114 *Returns:* In case of failure a negative error code will be
115 returned, and 0 on success.
117 gnutls_ocsp_req_get_cert_id
118 ---------------------------
120 -- Function: int gnutls_ocsp_req_get_cert_id (gnutls_ocsp_req_t REQ,
121 unsigned INDX, gnutls_digest_algorithm_t * DIGEST,
122 gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t *
123 ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER)
124 REQ: should contain a 'gnutls_ocsp_req_t' structure
126 INDX: Specifies which extension OID to get. Use (0) to get the
129 DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
132 ISSUER_NAME_HASH: output buffer with hash of issuer's DN
134 ISSUER_KEY_HASH: output buffer with hash of issuer's public key
136 SERIAL_NUMBER: output buffer with serial number of certificate to
139 This function will return the certificate information of the 'indx'
140 'ed request in the OCSP request. The information returned
141 corresponds to the CertID structure:
143 <informalexample><programlisting> CertID ::= SEQUENCE {
144 hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, -
145 Hash of Issuer's DN issuerKeyHash OCTET STRING, - Hash of Issuers
146 public key serialNumber CertificateSerialNumber }
147 </programlisting></informalexample>
149 Each of the pointers to output variables may be NULL to indicate
150 that the caller is not interested in that value.
152 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
153 otherwise a negative error code is returned. If you have reached
154 the last CertID available 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE'
157 gnutls_ocsp_req_get_extension
158 -----------------------------
160 -- Function: int gnutls_ocsp_req_get_extension (gnutls_ocsp_req_t REQ,
161 unsigned INDX, gnutls_datum_t * OID, unsigned int * CRITICAL,
162 gnutls_datum_t * DATA)
163 REQ: should contain a 'gnutls_ocsp_req_t' structure
165 INDX: Specifies which extension OID to get. Use (0) to get the
168 OID: will hold newly allocated buffer with OID of extension, may be
171 CRITICAL: output variable with critical flag, may be NULL.
173 DATA: will hold newly allocated buffer with extension data, may be
176 This function will return all information about the requested
177 extension in the OCSP request. The information returned is the
178 OID, the critical flag, and the data itself. The extension OID
179 will be stored as a string. Any of 'oid' , 'critical' , and 'data'
180 may be NULL which means that the caller is not interested in
181 getting that information back.
183 The caller needs to deallocate memory by calling 'gnutls_free()' on
184 'oid' ->data and 'data' ->data.
186 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
187 otherwise a negative error code is returned. If you have reached
188 the last extension available
189 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
191 gnutls_ocsp_req_get_nonce
192 -------------------------
194 -- Function: int gnutls_ocsp_req_get_nonce (gnutls_ocsp_req_t REQ,
195 unsigned int * CRITICAL, gnutls_datum_t * NONCE)
196 REQ: should contain a 'gnutls_ocsp_req_t' structure
198 CRITICAL: whether nonce extension is marked critical, or NULL
200 NONCE: will hold newly allocated buffer with nonce data
202 This function will return the OCSP request nonce extension data.
204 The caller needs to deallocate memory by calling 'gnutls_free()' on
207 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
208 otherwise a negative error code is returned.
210 gnutls_ocsp_req_get_version
211 ---------------------------
213 -- Function: int gnutls_ocsp_req_get_version (gnutls_ocsp_req_t REQ)
214 REQ: should contain a 'gnutls_ocsp_req_t' structure
216 This function will return the version of the OCSP request.
217 Typically this is always 1 indicating version 1.
219 *Returns:* version of OCSP request, or a negative error code on
222 gnutls_ocsp_req_import
223 ----------------------
225 -- Function: int gnutls_ocsp_req_import (gnutls_ocsp_req_t REQ, const
226 gnutls_datum_t * DATA)
227 REQ: The structure to store the parsed request.
229 DATA: DER encoded OCSP request.
231 This function will convert the given DER encoded OCSP request to
232 the native 'gnutls_ocsp_req_t' format. The output will be stored
235 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
236 otherwise a negative error value.
241 -- Function: int gnutls_ocsp_req_init (gnutls_ocsp_req_t * REQ)
242 REQ: The structure to be initialized
244 This function will initialize an OCSP request structure.
246 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
247 otherwise a negative error value.
249 gnutls_ocsp_req_print
250 ---------------------
252 -- Function: int gnutls_ocsp_req_print (gnutls_ocsp_req_t REQ,
253 gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)
254 REQ: The structure to be printed
256 FORMAT: Indicate the format to use
258 OUT: Newly allocated datum with (0) terminated string.
260 This function will pretty print a OCSP request, suitable for
263 If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
264 request will be output, on multiple lines.
266 The output 'out' ->data needs to be deallocate using
269 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
270 otherwise a negative error value.
272 gnutls_ocsp_req_randomize_nonce
273 -------------------------------
275 -- Function: int gnutls_ocsp_req_randomize_nonce (gnutls_ocsp_req_t
277 REQ: should contain a 'gnutls_ocsp_req_t' structure
279 This function will add or update an nonce extension to the OCSP
280 request with a newly generated random value.
282 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
283 otherwise a negative error code is returned.
285 gnutls_ocsp_req_set_extension
286 -----------------------------
288 -- Function: int gnutls_ocsp_req_set_extension (gnutls_ocsp_req_t REQ,
289 const char * OID, unsigned int CRITICAL, const gnutls_datum_t
291 REQ: should contain a 'gnutls_ocsp_req_t' structure
293 OID: buffer with OID of extension as a string.
295 CRITICAL: critical flag, normally false.
297 DATA: the extension data
299 This function will add an extension to the OCSP request. Calling
300 this function multiple times for the same OID will overwrite values
303 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
304 otherwise a negative error code is returned.
306 gnutls_ocsp_req_set_nonce
307 -------------------------
309 -- Function: int gnutls_ocsp_req_set_nonce (gnutls_ocsp_req_t REQ,
310 unsigned int CRITICAL, const gnutls_datum_t * NONCE)
311 REQ: should contain a 'gnutls_ocsp_req_t' structure
313 CRITICAL: critical flag, normally false.
315 NONCE: the nonce data
317 This function will add an nonce extension to the OCSP request.
318 Calling this function multiple times will overwrite values from
321 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
322 otherwise a negative error code is returned.
324 gnutls_ocsp_resp_check_crt
325 --------------------------
327 -- Function: int gnutls_ocsp_resp_check_crt (gnutls_ocsp_resp_t RESP,
328 unsigned int INDX, gnutls_x509_crt_t CRT)
329 RESP: should contain a 'gnutls_ocsp_resp_t' structure
331 INDX: Specifies response number to get. Use (0) to get the first
334 CRT: The certificate to check
336 This function will check whether the OCSP response is about the
337 provided certificate.
339 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
340 otherwise a negative error code is returned.
344 gnutls_ocsp_resp_deinit
345 -----------------------
347 -- Function: void gnutls_ocsp_resp_deinit (gnutls_ocsp_resp_t RESP)
348 RESP: The structure to be deinitialized
350 This function will deinitialize a OCSP response structure.
352 gnutls_ocsp_resp_export
353 -----------------------
355 -- Function: int gnutls_ocsp_resp_export (gnutls_ocsp_resp_t RESP,
356 gnutls_datum_t * DATA)
357 RESP: Holds the OCSP response
359 DATA: newly allocate buffer holding DER encoded OCSP response
361 This function will export the OCSP response to DER format.
363 *Returns:* In case of failure a negative error code will be
364 returned, and 0 on success.
366 gnutls_ocsp_resp_get_certs
367 --------------------------
369 -- Function: int gnutls_ocsp_resp_get_certs (gnutls_ocsp_resp_t RESP,
370 gnutls_x509_crt_t ** CERTS, size_t * NCERTS)
371 RESP: should contain a 'gnutls_ocsp_resp_t' structure
373 CERTS: newly allocated array with 'gnutls_x509_crt_t' certificates
375 NCERTS: output variable with number of allocated certs.
377 This function will extract the X.509 certificates found in the
378 Basic OCSP Response. The 'certs' output variable will hold a newly
379 allocated zero-terminated array with X.509 certificates.
381 Every certificate in the array needs to be de-allocated with
382 'gnutls_x509_crt_deinit()' and the array itself must be freed using
385 Both the 'certs' and 'ncerts' variables may be NULL. Then the
386 function will work as normal but will not return the NULL:d
387 information. This can be used to get the number of certificates
388 only, or to just get the certificate array without its size.
390 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
391 otherwise a negative error value.
393 gnutls_ocsp_resp_get_extension
394 ------------------------------
396 -- Function: int gnutls_ocsp_resp_get_extension (gnutls_ocsp_resp_t
397 RESP, unsigned INDX, gnutls_datum_t * OID, unsigned int *
398 CRITICAL, gnutls_datum_t * DATA)
399 RESP: should contain a 'gnutls_ocsp_resp_t' structure
401 INDX: Specifies which extension OID to get. Use (0) to get the
404 OID: will hold newly allocated buffer with OID of extension, may be
407 CRITICAL: output variable with critical flag, may be NULL.
409 DATA: will hold newly allocated buffer with extension data, may be
412 This function will return all information about the requested
413 extension in the OCSP response. The information returned is the
414 OID, the critical flag, and the data itself. The extension OID
415 will be stored as a string. Any of 'oid' , 'critical' , and 'data'
416 may be NULL which means that the caller is not interested in
417 getting that information back.
419 The caller needs to deallocate memory by calling 'gnutls_free()' on
420 'oid' ->data and 'data' ->data.
422 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
423 otherwise a negative error code is returned. If you have reached
424 the last extension available
425 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
427 gnutls_ocsp_resp_get_nonce
428 --------------------------
430 -- Function: int gnutls_ocsp_resp_get_nonce (gnutls_ocsp_resp_t RESP,
431 unsigned int * CRITICAL, gnutls_datum_t * NONCE)
432 RESP: should contain a 'gnutls_ocsp_resp_t' structure
434 CRITICAL: whether nonce extension is marked critical
436 NONCE: will hold newly allocated buffer with nonce data
438 This function will return the Basic OCSP Response nonce extension
441 The caller needs to deallocate memory by calling 'gnutls_free()' on
444 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
445 otherwise a negative error code is returned.
447 gnutls_ocsp_resp_get_produced
448 -----------------------------
450 -- Function: time_t gnutls_ocsp_resp_get_produced (gnutls_ocsp_resp_t
452 RESP: should contain a 'gnutls_ocsp_resp_t' structure
454 This function will return the time when the OCSP response was
457 *Returns:* signing time, or (time_t)-1 on error.
459 gnutls_ocsp_resp_get_responder
460 ------------------------------
462 -- Function: int gnutls_ocsp_resp_get_responder (gnutls_ocsp_resp_t
463 RESP, gnutls_datum_t * DN)
464 RESP: should contain a 'gnutls_ocsp_resp_t' structure
466 DN: newly allocated buffer with name
468 This function will extract the name of the Basic OCSP Response in
469 the provided buffer. The name will be in the form
470 "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string
471 will be ASCII or UTF-8 encoded, depending on the certificate data.
473 The caller needs to deallocate memory by calling 'gnutls_free()' on
476 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
477 otherwise a negative error code is returned.
479 gnutls_ocsp_resp_get_response
480 -----------------------------
482 -- Function: int gnutls_ocsp_resp_get_response (gnutls_ocsp_resp_t
483 RESP, gnutls_datum_t * RESPONSE_TYPE_OID, gnutls_datum_t *
485 RESP: should contain a 'gnutls_ocsp_resp_t' structure
487 RESPONSE_TYPE_OID: newly allocated output buffer with response type
490 RESPONSE: newly allocated output buffer with DER encoded response
492 This function will extract the response type OID in and the
493 response data from an OCSP response. Normally the
494 'response_type_oid' is always "1.3.6.1.5.5.7.48.1.1" which means
495 the 'response' should be decoded as a Basic OCSP Response, but
496 technically other response types could be used.
498 This function is typically only useful when you want to extract the
499 response type OID of an response for diagnostic purposes.
500 Otherwise 'gnutls_ocsp_resp_import()' will decode the basic OCSP
501 response part and the caller need not worry about that aspect.
503 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
504 otherwise a negative error value.
506 gnutls_ocsp_resp_get_signature
507 ------------------------------
509 -- Function: int gnutls_ocsp_resp_get_signature (gnutls_ocsp_resp_t
510 RESP, gnutls_datum_t * SIG)
511 RESP: should contain a 'gnutls_ocsp_resp_t' structure
513 SIG: newly allocated output buffer with signature data
515 This function will extract the signature field of a OCSP response.
517 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
518 otherwise a negative error value.
520 gnutls_ocsp_resp_get_signature_algorithm
521 ----------------------------------------
523 -- Function: int gnutls_ocsp_resp_get_signature_algorithm
524 (gnutls_ocsp_resp_t RESP)
525 RESP: should contain a 'gnutls_ocsp_resp_t' structure
527 This function will return a value of the 'gnutls_sign_algorithm_t'
528 enumeration that is the signature algorithm that has been used to
529 sign the OCSP response.
531 *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
534 gnutls_ocsp_resp_get_single
535 ---------------------------
537 -- Function: int gnutls_ocsp_resp_get_single (gnutls_ocsp_resp_t RESP,
538 unsigned INDX, gnutls_digest_algorithm_t * DIGEST,
539 gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t *
540 ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER, unsigned int
541 * CERT_STATUS, time_t * THIS_UPDATE, time_t * NEXT_UPDATE,
542 time_t * REVOCATION_TIME, unsigned int * REVOCATION_REASON)
543 RESP: should contain a 'gnutls_ocsp_resp_t' structure
545 INDX: Specifies response number to get. Use (0) to get the first
548 DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
551 ISSUER_NAME_HASH: output buffer with hash of issuer's DN
553 ISSUER_KEY_HASH: output buffer with hash of issuer's public key
555 SERIAL_NUMBER: output buffer with serial number of certificate to
558 CERT_STATUS: a certificate status, a 'gnutls_ocsp_cert_status_t'
561 THIS_UPDATE: time at which the status is known to be correct.
563 NEXT_UPDATE: when newer information will be available, or
564 (time_t)-1 if unspecified
566 REVOCATION_TIME: when 'cert_status' is 'GNUTLS_OCSP_CERT_REVOKED' ,
567 holds time of revocation.
569 REVOCATION_REASON: revocation reason, a 'gnutls_x509_crl_reason_t'
572 This function will return the certificate information of the 'indx'
573 'ed response in the Basic OCSP Response 'resp' . The information
574 returned corresponds to the OCSP SingleResponse structure except
575 the final singleExtensions.
577 Each of the pointers to output variables may be NULL to indicate
578 that the caller is not interested in that value.
580 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
581 otherwise a negative error code is returned. If you have reached
582 the last CertID available 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE'
585 gnutls_ocsp_resp_get_status
586 ---------------------------
588 -- Function: int gnutls_ocsp_resp_get_status (gnutls_ocsp_resp_t RESP)
589 RESP: should contain a 'gnutls_ocsp_resp_t' structure
591 This function will return the status of a OCSP response, an
592 'gnutls_ocsp_resp_status_t' enumeration.
594 *Returns:* status of OCSP request as a 'gnutls_ocsp_resp_status_t'
595 , or a negative error code on error.
597 gnutls_ocsp_resp_get_version
598 ----------------------------
600 -- Function: int gnutls_ocsp_resp_get_version (gnutls_ocsp_resp_t RESP)
601 RESP: should contain a 'gnutls_ocsp_resp_t' structure
603 This function will return the version of the Basic OCSP Response.
604 Typically this is always 1 indicating version 1.
606 *Returns:* version of Basic OCSP response, or a negative error code
609 gnutls_ocsp_resp_import
610 -----------------------
612 -- Function: int gnutls_ocsp_resp_import (gnutls_ocsp_resp_t RESP,
613 const gnutls_datum_t * DATA)
614 RESP: The structure to store the parsed response.
616 DATA: DER encoded OCSP response.
618 This function will convert the given DER encoded OCSP response to
619 the native 'gnutls_ocsp_resp_t' format. It also decodes the Basic
620 OCSP Response part, if any. The output will be stored in 'resp' .
622 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
623 otherwise a negative error value.
625 gnutls_ocsp_resp_init
626 ---------------------
628 -- Function: int gnutls_ocsp_resp_init (gnutls_ocsp_resp_t * RESP)
629 RESP: The structure to be initialized
631 This function will initialize an OCSP response structure.
633 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
634 otherwise a negative error value.
636 gnutls_ocsp_resp_print
637 ----------------------
639 -- Function: int gnutls_ocsp_resp_print (gnutls_ocsp_resp_t RESP,
640 gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)
641 RESP: The structure to be printed
643 FORMAT: Indicate the format to use
645 OUT: Newly allocated datum with (0) terminated string.
647 This function will pretty print a OCSP response, suitable for
650 If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
651 response will be output, on multiple lines.
653 The output 'out' ->data needs to be deallocate using
656 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
657 otherwise a negative error value.
659 gnutls_ocsp_resp_verify
660 -----------------------
662 -- Function: int gnutls_ocsp_resp_verify (gnutls_ocsp_resp_t RESP,
663 gnutls_x509_trust_list_t TRUSTLIST, unsigned int * VERIFY,
665 RESP: should contain a 'gnutls_ocsp_resp_t' structure
667 TRUSTLIST: trust anchors as a 'gnutls_x509_trust_list_t' structure
669 VERIFY: output variable with verification status, an
670 'gnutls_ocsp_cert_status_t'
672 FLAGS: verification flags, 0 for now.
674 Verify signature of the Basic OCSP Response against the public key
675 in the certificate of a trusted signer. The 'trustlist' should be
676 populated with trust anchors. The function will extract the signer
677 certificate from the Basic OCSP Response and will verify it against
678 the 'trustlist' . A trusted signer is a certificate that is either
679 in 'trustlist' , or it is signed directly by a certificate in
680 'trustlist' and has the id-ad-ocspSigning Extended Key Usage bit
683 The output 'verify' variable will hold verification status codes
684 (e.g., 'GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND' ,
685 'GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM' ) which are only valid if
686 the function returned 'GNUTLS_E_SUCCESS' .
688 Note that the function returns 'GNUTLS_E_SUCCESS' even when
689 verification failed. The caller must always inspect the 'verify'
690 variable to find out the verification status.
692 The 'flags' variable should be 0 for now.
694 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
695 otherwise a negative error value.
697 gnutls_ocsp_resp_verify_direct
698 ------------------------------
700 -- Function: int gnutls_ocsp_resp_verify_direct (gnutls_ocsp_resp_t
701 RESP, gnutls_x509_crt_t ISSUER, unsigned int * VERIFY,
703 RESP: should contain a 'gnutls_ocsp_resp_t' structure
705 ISSUER: certificate believed to have signed the response
707 VERIFY: output variable with verification status, an
708 'gnutls_ocsp_cert_status_t'
710 FLAGS: verification flags, 0 for now.
712 Verify signature of the Basic OCSP Response against the public key
713 in the 'issuer' certificate.
715 The output 'verify' variable will hold verification status codes
716 (e.g., 'GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND' ,
717 'GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM' ) which are only valid if
718 the function returned 'GNUTLS_E_SUCCESS' .
720 Note that the function returns 'GNUTLS_E_SUCCESS' even when
721 verification failed. The caller must always inspect the 'verify'
722 variable to find out the verification status.
724 The 'flags' variable should be 0 for now.
726 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
727 otherwise a negative error value.
730 File: gnutls.info, Node: OpenPGP API, Next: PKCS 12 API, Prev: OCSP API, Up: API reference
735 The following functions are to be used for OpenPGP certificate handling.
736 Their prototypes lie in 'gnutls/openpgp.h'.
738 gnutls_certificate_set_openpgp_key
739 ----------------------------------
741 -- Function: int gnutls_certificate_set_openpgp_key
742 (gnutls_certificate_credentials_t RES, gnutls_openpgp_crt_t
743 CRT, gnutls_openpgp_privkey_t PKEY)
744 RES: is a 'gnutls_certificate_credentials_t' structure.
746 CRT: contains an openpgp public key
748 PKEY: is an openpgp private key
750 This function sets a certificate/private key pair in the
751 gnutls_certificate_credentials_t structure. This function may be
752 called more than once (in case multiple keys/certificates exist for
755 Note that this function requires that the preferred key ids have
756 been set and be used. See
757 'gnutls_openpgp_crt_set_preferred_key_id()' . Otherwise the master
760 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
761 otherwise a negative error code is returned.
763 gnutls_certificate_set_openpgp_key_file
764 ---------------------------------------
766 -- Function: int gnutls_certificate_set_openpgp_key_file
767 (gnutls_certificate_credentials_t RES, const char * CERTFILE,
768 const char * KEYFILE, gnutls_openpgp_crt_fmt_t FORMAT)
769 RES: the destination context to save the data.
771 CERTFILE: the file that contains the public key.
773 KEYFILE: the file that contains the secret key.
775 FORMAT: the format of the keys
777 This funtion is used to load OpenPGP keys into the GnuTLS
778 credentials structure. The file should contain at least one valid
779 non encrypted subkey.
781 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
782 otherwise a negative error value.
784 gnutls_certificate_set_openpgp_key_file2
785 ----------------------------------------
787 -- Function: int gnutls_certificate_set_openpgp_key_file2
788 (gnutls_certificate_credentials_t RES, const char * CERTFILE,
789 const char * KEYFILE, const char * SUBKEY_ID,
790 gnutls_openpgp_crt_fmt_t FORMAT)
791 RES: the destination context to save the data.
793 CERTFILE: the file that contains the public key.
795 KEYFILE: the file that contains the secret key.
797 SUBKEY_ID: a hex encoded subkey id
799 FORMAT: the format of the keys
801 This funtion is used to load OpenPGP keys into the GnuTLS
802 credential structure. The file should contain at least one valid
803 non encrypted subkey.
805 The special keyword "auto" is also accepted as 'subkey_id' . In
806 that case the 'gnutls_openpgp_crt_get_auth_subkey()' will be used
807 to retrieve the subkey.
809 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
810 otherwise a negative error value.
814 gnutls_certificate_set_openpgp_key_mem
815 --------------------------------------
817 -- Function: int gnutls_certificate_set_openpgp_key_mem
818 (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
819 CERT, const gnutls_datum_t * KEY, gnutls_openpgp_crt_fmt_t
821 RES: the destination context to save the data.
823 CERT: the datum that contains the public key.
825 KEY: the datum that contains the secret key.
827 FORMAT: the format of the keys
829 This funtion is used to load OpenPGP keys into the GnuTLS
830 credential structure. The datum should contain at least one valid
831 non encrypted subkey.
833 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
834 otherwise a negative error value.
836 gnutls_certificate_set_openpgp_key_mem2
837 ---------------------------------------
839 -- Function: int gnutls_certificate_set_openpgp_key_mem2
840 (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
841 CERT, const gnutls_datum_t * KEY, const char * SUBKEY_ID,
842 gnutls_openpgp_crt_fmt_t FORMAT)
843 RES: the destination context to save the data.
845 CERT: the datum that contains the public key.
847 KEY: the datum that contains the secret key.
849 SUBKEY_ID: a hex encoded subkey id
851 FORMAT: the format of the keys
853 This funtion is used to load OpenPGP keys into the GnuTLS
854 credentials structure. The datum should contain at least one valid
855 non encrypted subkey.
857 The special keyword "auto" is also accepted as 'subkey_id' . In
858 that case the 'gnutls_openpgp_crt_get_auth_subkey()' will be used
859 to retrieve the subkey.
861 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
862 otherwise a negative error value.
866 gnutls_certificate_set_openpgp_keyring_file
867 -------------------------------------------
869 -- Function: int gnutls_certificate_set_openpgp_keyring_file
870 (gnutls_certificate_credentials_t C, const char * FILE,
871 gnutls_openpgp_crt_fmt_t FORMAT)
872 C: A certificate credentials structure
874 FILE: filename of the keyring.
876 FORMAT: format of keyring.
878 The function is used to set keyrings that will be used internally
879 by various OpenPGP functions. For example to find a key when it is
880 needed for an operations. The keyring will also be used at the
881 verification functions.
883 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
884 otherwise a negative error value.
886 gnutls_certificate_set_openpgp_keyring_mem
887 ------------------------------------------
889 -- Function: int gnutls_certificate_set_openpgp_keyring_mem
890 (gnutls_certificate_credentials_t C, const uint8_t * DATA,
891 size_t DLEN, gnutls_openpgp_crt_fmt_t FORMAT)
892 C: A certificate credentials structure
894 DATA: buffer with keyring data.
896 DLEN: length of data buffer.
898 FORMAT: the format of the keyring
900 The function is used to set keyrings that will be used internally
901 by various OpenPGP functions. For example to find a key when it is
902 needed for an operations. The keyring will also be used at the
903 verification functions.
905 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
906 otherwise a negative error value.
908 gnutls_openpgp_crt_check_hostname
909 ---------------------------------
911 -- Function: int gnutls_openpgp_crt_check_hostname
912 (gnutls_openpgp_crt_t KEY, const char * HOSTNAME)
913 KEY: should contain a 'gnutls_openpgp_crt_t' structure
915 HOSTNAME: A null terminated string that contains a DNS name
917 This function will check if the given key's owner matches the given
918 hostname. This is a basic implementation of the matching described
919 in RFC2818 (HTTPS), which takes into account wildcards.
921 *Returns:* non-zero for a successful match, and zero on failure.
923 gnutls_openpgp_crt_check_hostname2
924 ----------------------------------
926 -- Function: int gnutls_openpgp_crt_check_hostname2
927 (gnutls_openpgp_crt_t KEY, const char * HOSTNAME, unsigned
929 KEY: should contain a 'gnutls_openpgp_crt_t' structure
931 HOSTNAME: A null terminated string that contains a DNS name
933 FLAGS: gnutls_certificate_verify_flags
935 This function will check if the given key's owner matches the given
938 Unless, the flag 'GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS' is
939 specified, wildcards are only considered if the domain name
940 consists of three components or more, and the wildcard starts at
941 the leftmost position.
943 *Returns:* non-zero for a successful match, and zero on failure.
945 gnutls_openpgp_crt_deinit
946 -------------------------
948 -- Function: void gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t KEY)
949 KEY: The structure to be initialized
951 This function will deinitialize a key structure.
953 gnutls_openpgp_crt_export
954 -------------------------
956 -- Function: int gnutls_openpgp_crt_export (gnutls_openpgp_crt_t KEY,
957 gnutls_openpgp_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
961 FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
963 OUTPUT_DATA: will contain the raw or base64 encoded key
965 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
966 replaced by the actual size of parameters)
968 This function will convert the given key to RAW or Base64 format.
969 If the buffer provided is not long enough to hold the output, then
970 'GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned.
972 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
974 gnutls_openpgp_crt_export2
975 --------------------------
977 -- Function: int gnutls_openpgp_crt_export2 (gnutls_openpgp_crt_t KEY,
978 gnutls_openpgp_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
981 FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
983 OUT: will contain the raw or base64 encoded key
985 This function will convert the given key to RAW or Base64 format.
986 The output buffer is allocated using 'gnutls_malloc()' .
988 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
992 gnutls_openpgp_crt_get_auth_subkey
993 ----------------------------------
995 -- Function: int gnutls_openpgp_crt_get_auth_subkey
996 (gnutls_openpgp_crt_t CRT, gnutls_openpgp_keyid_t KEYID,
998 CRT: the structure that contains the OpenPGP public key.
1000 KEYID: the struct to save the keyid.
1002 FLAG: Non-zero indicates that a valid subkey is always returned.
1004 Returns the 64-bit keyID of the first valid OpenPGP subkey marked
1005 for authentication. If flag is non-zero and no authentication
1006 subkey exists, then a valid subkey will be returned even if it is
1007 not marked for authentication.
1009 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1011 gnutls_openpgp_crt_get_creation_time
1012 ------------------------------------
1014 -- Function: time_t gnutls_openpgp_crt_get_creation_time
1015 (gnutls_openpgp_crt_t KEY)
1016 KEY: the structure that contains the OpenPGP public key.
1018 Get key creation time.
1020 *Returns:* the timestamp when the OpenPGP key was created.
1022 gnutls_openpgp_crt_get_expiration_time
1023 --------------------------------------
1025 -- Function: time_t gnutls_openpgp_crt_get_expiration_time
1026 (gnutls_openpgp_crt_t KEY)
1027 KEY: the structure that contains the OpenPGP public key.
1029 Get key expiration time. A value of '0' means that the key doesn't
1032 *Returns:* the time when the OpenPGP key expires.
1034 gnutls_openpgp_crt_get_fingerprint
1035 ----------------------------------
1037 -- Function: int gnutls_openpgp_crt_get_fingerprint
1038 (gnutls_openpgp_crt_t KEY, void * FPR, size_t * FPRLEN)
1039 KEY: the raw data that contains the OpenPGP public key.
1041 FPR: the buffer to save the fingerprint, must hold at least 20
1044 FPRLEN: the integer to save the length of the fingerprint.
1046 Get key fingerprint. Depending on the algorithm, the fingerprint
1047 can be 16 or 20 bytes.
1049 *Returns:* On success, 0 is returned. Otherwise, an error code.
1051 gnutls_openpgp_crt_get_key_id
1052 -----------------------------
1054 -- Function: int gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t
1055 KEY, gnutls_openpgp_keyid_t KEYID)
1056 KEY: the structure that contains the OpenPGP public key.
1058 KEYID: the buffer to save the keyid.
1062 *Returns:* the 64-bit keyID of the OpenPGP key.
1066 gnutls_openpgp_crt_get_key_usage
1067 --------------------------------
1069 -- Function: int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t
1070 KEY, unsigned int * KEY_USAGE)
1071 KEY: should contain a gnutls_openpgp_crt_t structure
1073 KEY_USAGE: where the key usage bits will be stored
1075 This function will return certificate's key usage, by checking the
1076 key algorithm. The key usage value will ORed values of the:
1077 'GNUTLS_KEY_DIGITAL_SIGNATURE' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' .
1079 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1081 gnutls_openpgp_crt_get_name
1082 ---------------------------
1084 -- Function: int gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t KEY,
1085 int IDX, char * BUF, size_t * SIZEOF_BUF)
1086 KEY: the structure that contains the OpenPGP public key.
1088 IDX: the index of the ID to extract
1090 BUF: a pointer to a structure to hold the name, may be 'NULL' to
1091 only get the 'sizeof_buf' .
1093 SIZEOF_BUF: holds the maximum size of 'buf' , on return hold the
1094 actual/required size of 'buf' .
1096 Extracts the userID from the parsed OpenPGP key.
1098 *Returns:* 'GNUTLS_E_SUCCESS' on success, and if the index of the
1099 ID does not exist 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' , or an
1102 gnutls_openpgp_crt_get_pk_algorithm
1103 -----------------------------------
1105 -- Function: gnutls_pk_algorithm_t gnutls_openpgp_crt_get_pk_algorithm
1106 (gnutls_openpgp_crt_t KEY, unsigned int * BITS)
1107 KEY: is an OpenPGP key
1109 BITS: if bits is non null it will hold the size of the parameters'
1112 This function will return the public key algorithm of an OpenPGP
1115 If bits is non null, it should have enough size to hold the
1116 parameters size in bits. For RSA the bits returned is the modulus.
1117 For DSA the bits returned are of the public exponent.
1119 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1120 success, or GNUTLS_PK_UNKNOWN on error.
1122 gnutls_openpgp_crt_get_pk_dsa_raw
1123 ---------------------------------
1125 -- Function: int gnutls_openpgp_crt_get_pk_dsa_raw
1126 (gnutls_openpgp_crt_t CRT, gnutls_datum_t * P, gnutls_datum_t
1127 * Q, gnutls_datum_t * G, gnutls_datum_t * Y)
1128 CRT: Holds the certificate
1138 This function will export the DSA public key's parameters found in
1139 the given certificate. The new parameters will be allocated using
1140 'gnutls_malloc()' and will be stored in the appropriate datum.
1142 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1147 gnutls_openpgp_crt_get_pk_rsa_raw
1148 ---------------------------------
1150 -- Function: int gnutls_openpgp_crt_get_pk_rsa_raw
1151 (gnutls_openpgp_crt_t CRT, gnutls_datum_t * M, gnutls_datum_t
1153 CRT: Holds the certificate
1155 M: will hold the modulus
1157 E: will hold the public exponent
1159 This function will export the RSA public key's parameters found in
1160 the given structure. The new parameters will be allocated using
1161 'gnutls_malloc()' and will be stored in the appropriate datum.
1163 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1168 gnutls_openpgp_crt_get_preferred_key_id
1169 ---------------------------------------
1171 -- Function: int gnutls_openpgp_crt_get_preferred_key_id
1172 (gnutls_openpgp_crt_t KEY, gnutls_openpgp_keyid_t KEYID)
1173 KEY: the structure that contains the OpenPGP public key.
1175 KEYID: the struct to save the keyid.
1177 Get preferred key id. If it hasn't been set it returns
1178 'GNUTLS_E_INVALID_REQUEST' .
1180 *Returns:* the 64-bit preferred keyID of the OpenPGP key.
1182 gnutls_openpgp_crt_get_revoked_status
1183 -------------------------------------
1185 -- Function: int gnutls_openpgp_crt_get_revoked_status
1186 (gnutls_openpgp_crt_t KEY)
1187 KEY: the structure that contains the OpenPGP public key.
1189 Get revocation status of key.
1191 *Returns:* true (1) if the key has been revoked, or false (0) if it
1196 gnutls_openpgp_crt_get_subkey_count
1197 -----------------------------------
1199 -- Function: int gnutls_openpgp_crt_get_subkey_count
1200 (gnutls_openpgp_crt_t KEY)
1201 KEY: is an OpenPGP key
1203 This function will return the number of subkeys present in the
1204 given OpenPGP certificate.
1206 *Returns:* the number of subkeys, or a negative error code on
1211 gnutls_openpgp_crt_get_subkey_creation_time
1212 -------------------------------------------
1214 -- Function: time_t gnutls_openpgp_crt_get_subkey_creation_time
1215 (gnutls_openpgp_crt_t KEY, unsigned int IDX)
1216 KEY: the structure that contains the OpenPGP public key.
1218 IDX: the subkey index
1220 Get subkey creation time.
1222 *Returns:* the timestamp when the OpenPGP sub-key was created.
1226 gnutls_openpgp_crt_get_subkey_expiration_time
1227 ---------------------------------------------
1229 -- Function: time_t gnutls_openpgp_crt_get_subkey_expiration_time
1230 (gnutls_openpgp_crt_t KEY, unsigned int IDX)
1231 KEY: the structure that contains the OpenPGP public key.
1233 IDX: the subkey index
1235 Get subkey expiration time. A value of '0' means that the key
1236 doesn't expire at all.
1238 *Returns:* the time when the OpenPGP key expires.
1242 gnutls_openpgp_crt_get_subkey_fingerprint
1243 -----------------------------------------
1245 -- Function: int gnutls_openpgp_crt_get_subkey_fingerprint
1246 (gnutls_openpgp_crt_t KEY, unsigned int IDX, void * FPR,
1248 KEY: the raw data that contains the OpenPGP public key.
1250 IDX: the subkey index
1252 FPR: the buffer to save the fingerprint, must hold at least 20
1255 FPRLEN: the integer to save the length of the fingerprint.
1257 Get key fingerprint of a subkey. Depending on the algorithm, the
1258 fingerprint can be 16 or 20 bytes.
1260 *Returns:* On success, 0 is returned. Otherwise, an error code.
1264 gnutls_openpgp_crt_get_subkey_id
1265 --------------------------------
1267 -- Function: int gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t
1268 KEY, unsigned int IDX, gnutls_openpgp_keyid_t KEYID)
1269 KEY: the structure that contains the OpenPGP public key.
1271 IDX: the subkey index
1273 KEYID: the buffer to save the keyid.
1275 Get the subkey's key-id.
1277 *Returns:* the 64-bit keyID of the OpenPGP key.
1279 gnutls_openpgp_crt_get_subkey_idx
1280 ---------------------------------
1282 -- Function: int gnutls_openpgp_crt_get_subkey_idx
1283 (gnutls_openpgp_crt_t KEY, const gnutls_openpgp_keyid_t KEYID)
1284 KEY: the structure that contains the OpenPGP public key.
1290 *Returns:* the index of the subkey or a negative error value.
1294 gnutls_openpgp_crt_get_subkey_pk_algorithm
1295 ------------------------------------------
1297 -- Function: gnutls_pk_algorithm_t
1298 gnutls_openpgp_crt_get_subkey_pk_algorithm
1299 (gnutls_openpgp_crt_t KEY, unsigned int IDX, unsigned int *
1301 KEY: is an OpenPGP key
1303 IDX: is the subkey index
1305 BITS: if bits is non null it will hold the size of the parameters'
1308 This function will return the public key algorithm of a subkey of
1309 an OpenPGP certificate.
1311 If bits is non null, it should have enough size to hold the
1312 parameters size in bits. For RSA the bits returned is the modulus.
1313 For DSA the bits returned are of the public exponent.
1315 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1316 success, or GNUTLS_PK_UNKNOWN on error.
1320 gnutls_openpgp_crt_get_subkey_pk_dsa_raw
1321 ----------------------------------------
1323 -- Function: int gnutls_openpgp_crt_get_subkey_pk_dsa_raw
1324 (gnutls_openpgp_crt_t CRT, unsigned int IDX, gnutls_datum_t *
1325 P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y)
1326 CRT: Holds the certificate
1328 IDX: Is the subkey index
1338 This function will export the DSA public key's parameters found in
1339 the given certificate. The new parameters will be allocated using
1340 'gnutls_malloc()' and will be stored in the appropriate datum.
1342 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1347 gnutls_openpgp_crt_get_subkey_pk_rsa_raw
1348 ----------------------------------------
1350 -- Function: int gnutls_openpgp_crt_get_subkey_pk_rsa_raw
1351 (gnutls_openpgp_crt_t CRT, unsigned int IDX, gnutls_datum_t *
1352 M, gnutls_datum_t * E)
1353 CRT: Holds the certificate
1355 IDX: Is the subkey index
1357 M: will hold the modulus
1359 E: will hold the public exponent
1361 This function will export the RSA public key's parameters found in
1362 the given structure. The new parameters will be allocated using
1363 'gnutls_malloc()' and will be stored in the appropriate datum.
1365 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1370 gnutls_openpgp_crt_get_subkey_revoked_status
1371 --------------------------------------------
1373 -- Function: int gnutls_openpgp_crt_get_subkey_revoked_status
1374 (gnutls_openpgp_crt_t KEY, unsigned int IDX)
1375 KEY: the structure that contains the OpenPGP public key.
1377 IDX: is the subkey index
1379 Get subkey revocation status. A negative error code indicates an
1382 *Returns:* true (1) if the key has been revoked, or false (0) if it
1387 gnutls_openpgp_crt_get_subkey_usage
1388 -----------------------------------
1390 -- Function: int gnutls_openpgp_crt_get_subkey_usage
1391 (gnutls_openpgp_crt_t KEY, unsigned int IDX, unsigned int *
1393 KEY: should contain a gnutls_openpgp_crt_t structure
1395 IDX: the subkey index
1397 KEY_USAGE: where the key usage bits will be stored
1399 This function will return certificate's key usage, by checking the
1400 key algorithm. The key usage value will ORed values of
1401 'GNUTLS_KEY_DIGITAL_SIGNATURE' or 'GNUTLS_KEY_KEY_ENCIPHERMENT' .
1403 A negative error code may be returned in case of parsing error.
1405 *Returns:* key usage value.
1409 gnutls_openpgp_crt_get_version
1410 ------------------------------
1412 -- Function: int gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t
1414 KEY: the structure that contains the OpenPGP public key.
1416 Extract the version of the OpenPGP key.
1418 *Returns:* the version number is returned, or a negative error code
1421 gnutls_openpgp_crt_import
1422 -------------------------
1424 -- Function: int gnutls_openpgp_crt_import (gnutls_openpgp_crt_t KEY,
1425 const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT)
1426 KEY: The structure to store the parsed key.
1428 DATA: The RAW or BASE64 encoded key.
1430 FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1432 This function will convert the given RAW or Base64 encoded key to
1433 the native 'gnutls_openpgp_crt_t' format. The output will be
1436 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1438 gnutls_openpgp_crt_init
1439 -----------------------
1441 -- Function: int gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * KEY)
1442 KEY: The structure to be initialized
1444 This function will initialize an OpenPGP key structure.
1446 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1448 gnutls_openpgp_crt_print
1449 ------------------------
1451 -- Function: int gnutls_openpgp_crt_print (gnutls_openpgp_crt_t CERT,
1452 gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
1454 CERT: The structure to be printed
1456 FORMAT: Indicate the format to use
1458 OUT: Newly allocated datum with (0) terminated string.
1460 This function will pretty print an OpenPGP certificate, suitable
1461 for display to a human.
1463 The format should be (0) for future compatibility.
1465 The output 'out' needs to be deallocate using 'gnutls_free()' .
1467 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1469 gnutls_openpgp_crt_set_preferred_key_id
1470 ---------------------------------------
1472 -- Function: int gnutls_openpgp_crt_set_preferred_key_id
1473 (gnutls_openpgp_crt_t KEY, const gnutls_openpgp_keyid_t KEYID)
1474 KEY: the structure that contains the OpenPGP public key.
1476 KEYID: the selected keyid
1478 This allows setting a preferred key id for the given certificate.
1479 This key will be used by functions that involve key handling.
1481 If the provided 'keyid' is 'NULL' then the master key is set as
1484 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1485 otherwise a negative error code is returned.
1487 gnutls_openpgp_crt_verify_ring
1488 ------------------------------
1490 -- Function: int gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t
1491 KEY, gnutls_openpgp_keyring_t KEYRING, unsigned int FLAGS,
1492 unsigned int * VERIFY)
1493 KEY: the structure that holds the key.
1495 KEYRING: holds the keyring to check against
1497 FLAGS: unused (should be 0)
1499 VERIFY: will hold the certificate verification output.
1501 Verify all signatures in the key, using the given set of keys
1504 The key verification output will be put in 'verify' and will be one
1505 or more of the 'gnutls_certificate_status_t' enumerated elements
1508 Note that this function does not verify using any "web of trust".
1509 You may use GnuPG for that purpose, or any other external PGP
1512 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1514 gnutls_openpgp_crt_verify_self
1515 ------------------------------
1517 -- Function: int gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t
1518 KEY, unsigned int FLAGS, unsigned int * VERIFY)
1519 KEY: the structure that holds the key.
1521 FLAGS: unused (should be 0)
1523 VERIFY: will hold the key verification output.
1525 Verifies the self signature in the key. The key verification
1526 output will be put in 'verify' and will be one or more of the
1527 gnutls_certificate_status_t enumerated elements bitwise or'd.
1529 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1531 gnutls_openpgp_keyring_check_id
1532 -------------------------------
1534 -- Function: int gnutls_openpgp_keyring_check_id
1535 (gnutls_openpgp_keyring_t RING, const gnutls_openpgp_keyid_t
1536 KEYID, unsigned int FLAGS)
1537 RING: holds the keyring to check against
1539 KEYID: will hold the keyid to check for.
1541 FLAGS: unused (should be 0)
1543 Check if a given key ID exists in the keyring.
1545 *Returns:* 'GNUTLS_E_SUCCESS' on success (if keyid exists) and a
1546 negative error code on failure.
1548 gnutls_openpgp_keyring_deinit
1549 -----------------------------
1551 -- Function: void gnutls_openpgp_keyring_deinit
1552 (gnutls_openpgp_keyring_t KEYRING)
1553 KEYRING: The structure to be initialized
1555 This function will deinitialize a keyring structure.
1557 gnutls_openpgp_keyring_get_crt
1558 ------------------------------
1560 -- Function: int gnutls_openpgp_keyring_get_crt
1561 (gnutls_openpgp_keyring_t RING, unsigned int IDX,
1562 gnutls_openpgp_crt_t * CERT)
1563 RING: Holds the keyring.
1565 IDX: the index of the certificate to export
1567 CERT: An uninitialized 'gnutls_openpgp_crt_t' structure
1569 This function will extract an OpenPGP certificate from the given
1570 keyring. If the index given is out of range
1571 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned. The
1572 returned structure needs to be deinited.
1574 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1576 gnutls_openpgp_keyring_get_crt_count
1577 ------------------------------------
1579 -- Function: int gnutls_openpgp_keyring_get_crt_count
1580 (gnutls_openpgp_keyring_t RING)
1581 RING: is an OpenPGP key ring
1583 This function will return the number of OpenPGP certificates
1584 present in the given keyring.
1586 *Returns:* the number of subkeys, or a negative error code on
1589 gnutls_openpgp_keyring_import
1590 -----------------------------
1592 -- Function: int gnutls_openpgp_keyring_import
1593 (gnutls_openpgp_keyring_t KEYRING, const gnutls_datum_t *
1594 DATA, gnutls_openpgp_crt_fmt_t FORMAT)
1595 KEYRING: The structure to store the parsed key.
1597 DATA: The RAW or BASE64 encoded keyring.
1599 FORMAT: One of 'gnutls_openpgp_keyring_fmt' elements.
1601 This function will convert the given RAW or Base64 encoded keyring
1602 to the native 'gnutls_openpgp_keyring_t' format. The output will
1603 be stored in 'keyring'.
1605 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1607 gnutls_openpgp_keyring_init
1608 ---------------------------
1610 -- Function: int gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t
1612 KEYRING: The structure to be initialized
1614 This function will initialize an keyring structure.
1616 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1618 gnutls_openpgp_privkey_deinit
1619 -----------------------------
1621 -- Function: void gnutls_openpgp_privkey_deinit
1622 (gnutls_openpgp_privkey_t KEY)
1623 KEY: The structure to be initialized
1625 This function will deinitialize a key structure.
1627 gnutls_openpgp_privkey_export
1628 -----------------------------
1630 -- Function: int gnutls_openpgp_privkey_export
1631 (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_crt_fmt_t
1632 FORMAT, const char * PASSWORD, unsigned int FLAGS, void *
1633 OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)
1636 FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1638 PASSWORD: the password that will be used to encrypt the key.
1641 FLAGS: (0) for future compatibility
1643 OUTPUT_DATA: will contain the key base64 encoded or raw
1645 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
1646 replaced by the actual size of parameters)
1648 This function will convert the given key to RAW or Base64 format.
1649 If the buffer provided is not long enough to hold the output, then
1650 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
1652 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1656 gnutls_openpgp_privkey_export2
1657 ------------------------------
1659 -- Function: int gnutls_openpgp_privkey_export2
1660 (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_crt_fmt_t
1661 FORMAT, const char * PASSWORD, unsigned int FLAGS,
1662 gnutls_datum_t * OUT)
1665 FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1667 PASSWORD: the password that will be used to encrypt the key.
1670 FLAGS: (0) for future compatibility
1672 OUT: will contain the raw or based64 encoded key
1674 This function will convert the given key to RAW or Base64 format.
1675 The output buffer is allocated using 'gnutls_malloc()' .
1677 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1681 gnutls_openpgp_privkey_export_dsa_raw
1682 -------------------------------------
1684 -- Function: int gnutls_openpgp_privkey_export_dsa_raw
1685 (gnutls_openpgp_privkey_t PKEY, gnutls_datum_t * P,
1686 gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y,
1688 PKEY: Holds the certificate
1700 This function will export the DSA private key's parameters found in
1701 the given certificate. The new parameters will be allocated using
1702 'gnutls_malloc()' and will be stored in the appropriate datum.
1704 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1709 gnutls_openpgp_privkey_export_rsa_raw
1710 -------------------------------------
1712 -- Function: int gnutls_openpgp_privkey_export_rsa_raw
1713 (gnutls_openpgp_privkey_t PKEY, gnutls_datum_t * M,
1714 gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P,
1715 gnutls_datum_t * Q, gnutls_datum_t * U)
1716 PKEY: Holds the certificate
1718 M: will hold the modulus
1720 E: will hold the public exponent
1722 D: will hold the private exponent
1724 P: will hold the first prime (p)
1726 Q: will hold the second prime (q)
1728 U: will hold the coefficient
1730 This function will export the RSA private key's parameters found in
1731 the given structure. The new parameters will be allocated using
1732 'gnutls_malloc()' and will be stored in the appropriate datum.
1734 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1739 gnutls_openpgp_privkey_export_subkey_dsa_raw
1740 --------------------------------------------
1742 -- Function: int gnutls_openpgp_privkey_export_subkey_dsa_raw
1743 (gnutls_openpgp_privkey_t PKEY, unsigned int IDX,
1744 gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G,
1745 gnutls_datum_t * Y, gnutls_datum_t * X)
1746 PKEY: Holds the certificate
1748 IDX: Is the subkey index
1760 This function will export the DSA private key's parameters found in
1761 the given certificate. The new parameters will be allocated using
1762 'gnutls_malloc()' and will be stored in the appropriate datum.
1764 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1769 gnutls_openpgp_privkey_export_subkey_rsa_raw
1770 --------------------------------------------
1772 -- Function: int gnutls_openpgp_privkey_export_subkey_rsa_raw
1773 (gnutls_openpgp_privkey_t PKEY, unsigned int IDX,
1774 gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D,
1775 gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U)
1776 PKEY: Holds the certificate
1778 IDX: Is the subkey index
1780 M: will hold the modulus
1782 E: will hold the public exponent
1784 D: will hold the private exponent
1786 P: will hold the first prime (p)
1788 Q: will hold the second prime (q)
1790 U: will hold the coefficient
1792 This function will export the RSA private key's parameters found in
1793 the given structure. The new parameters will be allocated using
1794 'gnutls_malloc()' and will be stored in the appropriate datum.
1796 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1801 gnutls_openpgp_privkey_get_fingerprint
1802 --------------------------------------
1804 -- Function: int gnutls_openpgp_privkey_get_fingerprint
1805 (gnutls_openpgp_privkey_t KEY, void * FPR, size_t * FPRLEN)
1806 KEY: the raw data that contains the OpenPGP secret key.
1808 FPR: the buffer to save the fingerprint, must hold at least 20
1811 FPRLEN: the integer to save the length of the fingerprint.
1813 Get the fingerprint of the OpenPGP key. Depends on the algorithm,
1814 the fingerprint can be 16 or 20 bytes.
1816 *Returns:* On success, 0 is returned, or an error code.
1820 gnutls_openpgp_privkey_get_key_id
1821 ---------------------------------
1823 -- Function: int gnutls_openpgp_privkey_get_key_id
1824 (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_keyid_t KEYID)
1825 KEY: the structure that contains the OpenPGP secret key.
1827 KEYID: the buffer to save the keyid.
1831 *Returns:* the 64-bit keyID of the OpenPGP key.
1835 gnutls_openpgp_privkey_get_pk_algorithm
1836 ---------------------------------------
1838 -- Function: gnutls_pk_algorithm_t
1839 gnutls_openpgp_privkey_get_pk_algorithm
1840 (gnutls_openpgp_privkey_t KEY, unsigned int * BITS)
1841 KEY: is an OpenPGP key
1843 BITS: if bits is non null it will hold the size of the parameters'
1846 This function will return the public key algorithm of an OpenPGP
1849 If bits is non null, it should have enough size to hold the
1850 parameters size in bits. For RSA the bits returned is the modulus.
1851 For DSA the bits returned are of the public exponent.
1853 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1854 success, or a negative error code on error.
1858 gnutls_openpgp_privkey_get_preferred_key_id
1859 -------------------------------------------
1861 -- Function: int gnutls_openpgp_privkey_get_preferred_key_id
1862 (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_keyid_t KEYID)
1863 KEY: the structure that contains the OpenPGP public key.
1865 KEYID: the struct to save the keyid.
1867 Get the preferred key-id for the key.
1869 *Returns:* the 64-bit preferred keyID of the OpenPGP key, or if it
1870 hasn't been set it returns 'GNUTLS_E_INVALID_REQUEST' .
1872 gnutls_openpgp_privkey_get_revoked_status
1873 -----------------------------------------
1875 -- Function: int gnutls_openpgp_privkey_get_revoked_status
1876 (gnutls_openpgp_privkey_t KEY)
1877 KEY: the structure that contains the OpenPGP private key.
1879 Get revocation status of key.
1881 *Returns:* true (1) if the key has been revoked, or false (0) if it
1882 has not, or a negative error code indicates an error.
1886 gnutls_openpgp_privkey_get_subkey_count
1887 ---------------------------------------
1889 -- Function: int gnutls_openpgp_privkey_get_subkey_count
1890 (gnutls_openpgp_privkey_t KEY)
1891 KEY: is an OpenPGP key
1893 This function will return the number of subkeys present in the
1894 given OpenPGP certificate.
1896 *Returns:* the number of subkeys, or a negative error code on
1901 gnutls_openpgp_privkey_get_subkey_creation_time
1902 -----------------------------------------------
1904 -- Function: time_t gnutls_openpgp_privkey_get_subkey_creation_time
1905 (gnutls_openpgp_privkey_t KEY, unsigned int IDX)
1906 KEY: the structure that contains the OpenPGP private key.
1908 IDX: the subkey index
1910 Get subkey creation time.
1912 *Returns:* the timestamp when the OpenPGP key was created.
1916 gnutls_openpgp_privkey_get_subkey_expiration_time
1917 -------------------------------------------------
1919 -- Function: time_t gnutls_openpgp_privkey_get_subkey_expiration_time
1920 (gnutls_openpgp_privkey_t KEY, unsigned int IDX)
1921 KEY: the structure that contains the OpenPGP private key.
1923 IDX: the subkey index
1925 Get subkey expiration time. A value of '0' means that the key
1926 doesn't expire at all.
1928 *Returns:* the time when the OpenPGP key expires.
1932 gnutls_openpgp_privkey_get_subkey_fingerprint
1933 ---------------------------------------------
1935 -- Function: int gnutls_openpgp_privkey_get_subkey_fingerprint
1936 (gnutls_openpgp_privkey_t KEY, unsigned int IDX, void * FPR,
1938 KEY: the raw data that contains the OpenPGP secret key.
1940 IDX: the subkey index
1942 FPR: the buffer to save the fingerprint, must hold at least 20
1945 FPRLEN: the integer to save the length of the fingerprint.
1947 Get the fingerprint of an OpenPGP subkey. Depends on the
1948 algorithm, the fingerprint can be 16 or 20 bytes.
1950 *Returns:* On success, 0 is returned, or an error code.
1954 gnutls_openpgp_privkey_get_subkey_id
1955 ------------------------------------
1957 -- Function: int gnutls_openpgp_privkey_get_subkey_id
1958 (gnutls_openpgp_privkey_t KEY, unsigned int IDX,
1959 gnutls_openpgp_keyid_t KEYID)
1960 KEY: the structure that contains the OpenPGP secret key.
1962 IDX: the subkey index
1964 KEYID: the buffer to save the keyid.
1966 Get the key-id for the subkey.
1968 *Returns:* the 64-bit keyID of the OpenPGP key.
1972 gnutls_openpgp_privkey_get_subkey_idx
1973 -------------------------------------
1975 -- Function: int gnutls_openpgp_privkey_get_subkey_idx
1976 (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t
1978 KEY: the structure that contains the OpenPGP private key.
1982 Get index of subkey.
1984 *Returns:* the index of the subkey or a negative error value.
1988 gnutls_openpgp_privkey_get_subkey_pk_algorithm
1989 ----------------------------------------------
1991 -- Function: gnutls_pk_algorithm_t
1992 gnutls_openpgp_privkey_get_subkey_pk_algorithm
1993 (gnutls_openpgp_privkey_t KEY, unsigned int IDX, unsigned int
1995 KEY: is an OpenPGP key
1997 IDX: is the subkey index
1999 BITS: if bits is non null it will hold the size of the parameters'
2002 This function will return the public key algorithm of a subkey of
2003 an OpenPGP certificate.
2005 If bits is non null, it should have enough size to hold the
2006 parameters size in bits. For RSA the bits returned is the modulus.
2007 For DSA the bits returned are of the public exponent.
2009 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
2010 success, or a negative error code on error.
2014 gnutls_openpgp_privkey_get_subkey_revoked_status
2015 ------------------------------------------------
2017 -- Function: int gnutls_openpgp_privkey_get_subkey_revoked_status
2018 (gnutls_openpgp_privkey_t KEY, unsigned int IDX)
2019 KEY: the structure that contains the OpenPGP private key.
2021 IDX: is the subkey index
2023 Get revocation status of key.
2025 *Returns:* true (1) if the key has been revoked, or false (0) if it
2026 has not, or a negative error code indicates an error.
2030 gnutls_openpgp_privkey_import
2031 -----------------------------
2033 -- Function: int gnutls_openpgp_privkey_import
2034 (gnutls_openpgp_privkey_t KEY, const gnutls_datum_t * DATA,
2035 gnutls_openpgp_crt_fmt_t FORMAT, const char * PASSWORD,
2037 KEY: The structure to store the parsed key.
2039 DATA: The RAW or BASE64 encoded key.
2041 FORMAT: One of 'gnutls_openpgp_crt_fmt_t' elements.
2043 PASSWORD: not used for now
2045 FLAGS: should be (0)
2047 This function will convert the given RAW or Base64 encoded key to
2048 the native gnutls_openpgp_privkey_t format. The output will be
2051 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2053 gnutls_openpgp_privkey_init
2054 ---------------------------
2056 -- Function: int gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t
2058 KEY: The structure to be initialized
2060 This function will initialize an OpenPGP key structure.
2062 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2064 gnutls_openpgp_privkey_sec_param
2065 --------------------------------
2067 -- Function: gnutls_sec_param_t gnutls_openpgp_privkey_sec_param
2068 (gnutls_openpgp_privkey_t KEY)
2069 KEY: a key structure
2071 This function will return the security parameter appropriate with
2074 *Returns:* On success, a valid security parameter is returned
2075 otherwise 'GNUTLS_SEC_PARAM_UNKNOWN' is returned.
2079 gnutls_openpgp_privkey_set_preferred_key_id
2080 -------------------------------------------
2082 -- Function: int gnutls_openpgp_privkey_set_preferred_key_id
2083 (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t
2085 KEY: the structure that contains the OpenPGP public key.
2087 KEYID: the selected keyid
2089 This allows setting a preferred key id for the given certificate.
2090 This key will be used by functions that involve key handling.
2092 If the provided 'keyid' is 'NULL' then the master key is set as
2095 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2096 otherwise a negative error code is returned.
2098 gnutls_openpgp_set_recv_key_function
2099 ------------------------------------
2101 -- Function: void gnutls_openpgp_set_recv_key_function
2102 (gnutls_session_t SESSION, gnutls_openpgp_recv_key_func FUNC)
2103 SESSION: a TLS session
2107 This funtion will set a key retrieval function for OpenPGP keys.
2108 This callback is only useful in server side, and will be used if
2109 the peer sent a key fingerprint instead of a full key.
2111 The retrieved key must be allocated using 'gnutls_malloc()' .
2114 File: gnutls.info, Node: PKCS 12 API, Next: PKCS 11 API, Prev: OpenPGP API, Up: API reference
2119 The following functions are to be used for PKCS 12 handling. Their
2120 prototypes lie in 'gnutls/pkcs12.h'.
2122 gnutls_pkcs12_bag_decrypt
2123 -------------------------
2125 -- Function: int gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t BAG,
2129 PASS: The password used for encryption, must be ASCII.
2131 This function will decrypt the given encrypted bag and return 0 on
2134 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2135 otherwise a negative error code is returned.
2137 gnutls_pkcs12_bag_deinit
2138 ------------------------
2140 -- Function: void gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t BAG)
2141 BAG: The structure to be initialized
2143 This function will deinitialize a PKCS12 Bag structure.
2145 gnutls_pkcs12_bag_encrypt
2146 -------------------------
2148 -- Function: int gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t BAG,
2149 const char * PASS, unsigned int FLAGS)
2152 PASS: The password used for encryption, must be ASCII
2154 FLAGS: should be one of 'gnutls_pkcs_encrypt_flags_t' elements
2157 This function will encrypt the given bag.
2159 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2160 otherwise a negative error code is returned.
2162 gnutls_pkcs12_bag_get_count
2163 ---------------------------
2165 -- Function: int gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t BAG)
2168 This function will return the number of the elements withing the
2171 *Returns:* Number of elements in bag, or an negative error code on
2174 gnutls_pkcs12_bag_get_data
2175 --------------------------
2177 -- Function: int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t BAG,
2178 int INDX, gnutls_datum_t * DATA)
2181 INDX: The element of the bag to get the data from
2183 DATA: where the bag's data will be. Should be treated as constant.
2185 This function will return the bag's data. The data is a constant
2186 that is stored into the bag. Should not be accessed after the bag
2189 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2190 otherwise a negative error value.
2192 gnutls_pkcs12_bag_get_friendly_name
2193 -----------------------------------
2195 -- Function: int gnutls_pkcs12_bag_get_friendly_name
2196 (gnutls_pkcs12_bag_t BAG, int INDX, char ** NAME)
2199 INDX: The bag's element to add the id
2201 NAME: will hold a pointer to the name (to be treated as const)
2203 This function will return the friendly name, of the specified bag
2204 element. The key ID is usually used to distinguish the local
2205 private key and the certificate pair.
2207 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2208 otherwise a negative error value. or a negative error code on
2211 gnutls_pkcs12_bag_get_key_id
2212 ----------------------------
2214 -- Function: int gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t BAG,
2215 int INDX, gnutls_datum_t * ID)
2218 INDX: The bag's element to add the id
2220 ID: where the ID will be copied (to be treated as const)
2222 This function will return the key ID, of the specified bag element.
2223 The key ID is usually used to distinguish the local private key and
2224 the certificate pair.
2226 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2227 otherwise a negative error value. or a negative error code on
2230 gnutls_pkcs12_bag_get_type
2231 --------------------------
2233 -- Function: gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type
2234 (gnutls_pkcs12_bag_t BAG, int INDX)
2237 INDX: The element of the bag to get the type
2239 This function will return the bag's type.
2241 *Returns:* One of the 'gnutls_pkcs12_bag_type_t' enumerations.
2243 gnutls_pkcs12_bag_init
2244 ----------------------
2246 -- Function: int gnutls_pkcs12_bag_init (gnutls_pkcs12_bag_t * BAG)
2247 BAG: The structure to be initialized
2249 This function will initialize a PKCS12 bag structure. PKCS12 Bags
2250 usually contain private keys, lists of X.509 Certificates and X.509
2251 Certificate revocation lists.
2253 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2254 otherwise a negative error value.
2256 gnutls_pkcs12_bag_set_crl
2257 -------------------------
2259 -- Function: int gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t BAG,
2260 gnutls_x509_crl_t CRL)
2263 CRL: the CRL to be copied.
2265 This function will insert the given CRL into the bag. This is just
2266 a wrapper over 'gnutls_pkcs12_bag_set_data()' .
2268 *Returns:* the index of the added bag on success, or a negative
2269 error code on failure.
2271 gnutls_pkcs12_bag_set_crt
2272 -------------------------
2274 -- Function: int gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t BAG,
2275 gnutls_x509_crt_t CRT)
2278 CRT: the certificate to be copied.
2280 This function will insert the given certificate into the bag. This
2281 is just a wrapper over 'gnutls_pkcs12_bag_set_data()' .
2283 *Returns:* the index of the added bag on success, or a negative
2286 gnutls_pkcs12_bag_set_data
2287 --------------------------
2289 -- Function: int gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t BAG,
2290 gnutls_pkcs12_bag_type_t TYPE, const gnutls_datum_t * DATA)
2293 TYPE: The data's type
2295 DATA: the data to be copied.
2297 This function will insert the given data of the given type into the
2300 *Returns:* the index of the added bag on success, or a negative
2303 gnutls_pkcs12_bag_set_friendly_name
2304 -----------------------------------
2306 -- Function: int gnutls_pkcs12_bag_set_friendly_name
2307 (gnutls_pkcs12_bag_t BAG, int INDX, const char * NAME)
2310 INDX: The bag's element to add the id
2314 This function will add the given key friendly name, to the
2315 specified, by the index, bag element. The name will be encoded as
2316 a 'Friendly name' bag attribute, which is usually used to set a
2317 user name to the local private key and the certificate pair.
2319 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2320 otherwise a negative error value. or a negative error code on
2323 gnutls_pkcs12_bag_set_key_id
2324 ----------------------------
2326 -- Function: int gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t BAG,
2327 int INDX, const gnutls_datum_t * ID)
2330 INDX: The bag's element to add the id
2334 This function will add the given key ID, to the specified, by the
2335 index, bag element. The key ID will be encoded as a 'Local key
2336 identifier' bag attribute, which is usually used to distinguish the
2337 local private key and the certificate pair.
2339 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2340 otherwise a negative error value. or a negative error code on
2343 gnutls_pkcs12_deinit
2344 --------------------
2346 -- Function: void gnutls_pkcs12_deinit (gnutls_pkcs12_t PKCS12)
2347 PKCS12: The structure to be initialized
2349 This function will deinitialize a PKCS12 structure.
2351 gnutls_pkcs12_export
2352 --------------------
2354 -- Function: int gnutls_pkcs12_export (gnutls_pkcs12_t PKCS12,
2355 gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
2357 PKCS12: Holds the pkcs12 structure
2359 FORMAT: the format of output params. One of PEM or DER.
2361 OUTPUT_DATA: will contain a structure PEM or DER encoded
2363 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2364 replaced by the actual size of parameters)
2366 This function will export the pkcs12 structure to DER or PEM
2369 If the buffer provided is not long enough to hold the output, then
2370 *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
2373 If the structure is PEM encoded, it will have a header of "BEGIN
2376 *Returns:* In case of failure a negative error code will be
2377 returned, and 0 on success.
2379 gnutls_pkcs12_export2
2380 ---------------------
2382 -- Function: int gnutls_pkcs12_export2 (gnutls_pkcs12_t PKCS12,
2383 gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
2384 PKCS12: Holds the pkcs12 structure
2386 FORMAT: the format of output params. One of PEM or DER.
2388 OUT: will contain a structure PEM or DER encoded
2390 This function will export the pkcs12 structure to DER or PEM
2393 The output buffer is allocated using 'gnutls_malloc()' .
2395 If the structure is PEM encoded, it will have a header of "BEGIN
2398 *Returns:* In case of failure a negative error code will be
2399 returned, and 0 on success.
2403 gnutls_pkcs12_generate_mac
2404 --------------------------
2406 -- Function: int gnutls_pkcs12_generate_mac (gnutls_pkcs12_t PKCS12,
2408 PKCS12: should contain a gnutls_pkcs12_t structure
2410 PASS: The password for the MAC
2412 This function will generate a MAC for the PKCS12 structure.
2414 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2415 otherwise a negative error value.
2417 gnutls_pkcs12_get_bag
2418 ---------------------
2420 -- Function: int gnutls_pkcs12_get_bag (gnutls_pkcs12_t PKCS12, int
2421 INDX, gnutls_pkcs12_bag_t BAG)
2422 PKCS12: should contain a gnutls_pkcs12_t structure
2424 INDX: contains the index of the bag to extract
2426 BAG: An initialized bag, where the contents of the bag will be
2429 This function will return a Bag from the PKCS12 structure.
2431 After the last Bag has been read
2432 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
2434 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2435 otherwise a negative error value.
2437 gnutls_pkcs12_import
2438 --------------------
2440 -- Function: int gnutls_pkcs12_import (gnutls_pkcs12_t PKCS12, const
2441 gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned
2443 PKCS12: The structure to store the parsed PKCS12.
2445 DATA: The DER or PEM encoded PKCS12.
2447 FORMAT: One of DER or PEM
2449 FLAGS: an ORed sequence of gnutls_privkey_pkcs8_flags
2451 This function will convert the given DER or PEM encoded PKCS12 to
2452 the native gnutls_pkcs12_t format. The output will be stored in
2455 If the PKCS12 is PEM encoded it should have a header of "PKCS12".
2457 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2458 otherwise a negative error value.
2463 -- Function: int gnutls_pkcs12_init (gnutls_pkcs12_t * PKCS12)
2464 PKCS12: The structure to be initialized
2466 This function will initialize a PKCS12 structure. PKCS12
2467 structures usually contain lists of X.509 Certificates and X.509
2468 Certificate revocation lists.
2470 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2471 otherwise a negative error value.
2473 gnutls_pkcs12_set_bag
2474 ---------------------
2476 -- Function: int gnutls_pkcs12_set_bag (gnutls_pkcs12_t PKCS12,
2477 gnutls_pkcs12_bag_t BAG)
2478 PKCS12: should contain a gnutls_pkcs12_t structure
2480 BAG: An initialized bag
2482 This function will insert a Bag into the PKCS12 structure.
2484 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2485 otherwise a negative error value.
2487 gnutls_pkcs12_simple_parse
2488 --------------------------
2490 -- Function: int gnutls_pkcs12_simple_parse (gnutls_pkcs12_t P12, const
2491 char * PASSWORD, gnutls_x509_privkey_t * KEY,
2492 gnutls_x509_crt_t ** CHAIN, unsigned int * CHAIN_LEN,
2493 gnutls_x509_crt_t ** EXTRA_CERTS, unsigned int *
2494 EXTRA_CERTS_LEN, gnutls_x509_crl_t * CRL, unsigned int FLAGS)
2495 P12: the PKCS12 blob.
2497 PASSWORD: optional password used to decrypt PKCS12 blob, bags and
2500 KEY: a structure to store the parsed private key.
2502 CHAIN: the corresponding to key certificate chain (may be 'NULL' )
2504 CHAIN_LEN: will be updated with the number of additional (may be
2507 EXTRA_CERTS: optional pointer to receive an array of additional
2508 certificates found in the PKCS12 blob (may be 'NULL' ).
2510 EXTRA_CERTS_LEN: will be updated with the number of additional
2511 certs (may be 'NULL' ).
2513 CRL: an optional structure to store the parsed CRL (may be 'NULL'
2516 FLAGS: should be zero or one of GNUTLS_PKCS12_SP_*
2518 This function parses a PKCS12 blob in 'p12blob' and extracts the
2519 private key, the corresponding certificate chain, and any
2520 additional certificates and a CRL.
2522 The 'extra_certs_ret' and 'extra_certs_len' parameters are optional
2523 and both may be set to 'NULL' . If either is non-'NULL' , then
2526 Encrypted PKCS12 bags and PKCS8 private keys are supported.
2527 However, only password based security, and the same password for
2528 all operations, are supported.
2530 A PKCS12 file may contain many keys and/or certificates, and there
2531 is no way to identify which key/certificate pair you want. You
2532 should make sure the PKCS12 file only contain one key/certificate
2533 pair and/or one CRL.
2535 It is believed that the limitations of this function are acceptable
2536 for common usage, and that any more flexibility would introduce
2537 complexity that would make it harder to use this functionality at
2540 If the provided structure has encrypted fields but no password is
2541 provided then this function returns 'GNUTLS_E_DECRYPTION_FAILED' .
2543 Note that normally the chain constructed does not include self
2544 signed certificates, to comply with TLS' requirements. If,
2545 however, the flag 'GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED' is
2546 specified then self signed certificates will be included in the
2549 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2550 otherwise a negative error value.
2554 gnutls_pkcs12_verify_mac
2555 ------------------------
2557 -- Function: int gnutls_pkcs12_verify_mac (gnutls_pkcs12_t PKCS12,
2559 PKCS12: should contain a gnutls_pkcs12_t structure
2561 PASS: The password for the MAC
2563 This function will verify the MAC for the PKCS12 structure.
2565 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2566 otherwise a negative error value.
2569 File: gnutls.info, Node: PKCS 11 API, Next: TPM API, Prev: PKCS 12 API, Up: API reference
2571 E.7 Hardware token via PKCS 11 API
2572 ==================================
2574 The following functions are to be used for PKCS 11 handling. Their
2575 prototypes lie in 'gnutls/pkcs11.h'.
2577 gnutls_pkcs11_add_provider
2578 --------------------------
2580 -- Function: int gnutls_pkcs11_add_provider (const char * NAME, const
2582 NAME: The filename of the module
2584 PARAMS: should be NULL
2586 This function will load and add a PKCS 11 module to the module list
2587 used in gnutls. After this function is called the module will be
2588 used for PKCS 11 operations.
2590 When loading a module to be used for certificate verification, use
2591 the string 'trusted' as 'params' .
2593 Note that this function is not thread safe.
2595 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2596 otherwise a negative error value.
2600 gnutls_pkcs11_copy_secret_key
2601 -----------------------------
2603 -- Function: int gnutls_pkcs11_copy_secret_key (const char * TOKEN_URL,
2604 gnutls_datum_t * KEY, const char * LABEL, unsigned int
2605 KEY_USAGE, unsigned int FLAGS)
2606 TOKEN_URL: A PKCS '11' URL specifying a token
2610 LABEL: A name to be used for the stored data
2612 KEY_USAGE: One of GNUTLS_KEY_*
2614 FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2616 This function will copy a raw secret (symmetric) key into a PKCS
2617 '11' token specified by a URL. The key can be marked as sensitive
2620 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2621 otherwise a negative error value.
2625 gnutls_pkcs11_copy_x509_crt
2626 ---------------------------
2628 -- Function: int gnutls_pkcs11_copy_x509_crt (const char * TOKEN_URL,
2629 gnutls_x509_crt_t CRT, const char * LABEL, unsigned int FLAGS)
2630 TOKEN_URL: A PKCS '11' URL specifying a token
2634 LABEL: A name to be used for the stored data
2636 FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2638 This function will copy a certificate into a PKCS '11' token
2639 specified by a URL. The certificate can be marked as trusted or
2642 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2643 otherwise a negative error value.
2647 gnutls_pkcs11_copy_x509_privkey
2648 -------------------------------
2650 -- Function: int gnutls_pkcs11_copy_x509_privkey (const char *
2651 TOKEN_URL, gnutls_x509_privkey_t KEY, const char * LABEL,
2652 unsigned int KEY_USAGE, unsigned int FLAGS)
2653 TOKEN_URL: A PKCS '11' URL specifying a token
2657 LABEL: A name to be used for the stored data
2659 KEY_USAGE: One of GNUTLS_KEY_*
2661 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2663 This function will copy a private key into a PKCS '11' token
2664 specified by a URL. It is highly recommended flags to contain
2665 'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' unless there is a strong
2668 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2669 otherwise a negative error value.
2673 gnutls_pkcs11_crt_is_known
2674 --------------------------
2676 -- Function: int gnutls_pkcs11_crt_is_known (const char * URL,
2677 gnutls_x509_crt_t CERT, unsigned int FLAGS)
2678 URL: A PKCS 11 url identifying a token
2680 CERT: is the certificate to find issuer for
2682 FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2684 This function will check whether the provided certificate is stored
2685 in the specified token. This is useful in combination with
2686 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED' or
2687 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED' , to check whether a
2688 CA is present or a certificate is blacklisted in a trust PKCS '11'
2691 This function can be used with a 'url' of "pkcs11:", and in that
2692 case all modules will be searched. To restrict the modules to the
2693 marked as trusted in p11-kit use the
2694 'GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE' flag.
2696 Note that the flag 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED' is
2697 specific to p11-kit trust modules.
2699 *Returns:* If the certificate exists non-zero is returned,
2704 gnutls_pkcs11_deinit
2705 --------------------
2707 -- Function: void gnutls_pkcs11_deinit ( VOID)
2709 This function will deinitialize the PKCS 11 subsystem in gnutls.
2710 This function is only needed if you need to deinitialize the
2711 subsystem without calling 'gnutls_global_deinit()' .
2715 gnutls_pkcs11_delete_url
2716 ------------------------
2718 -- Function: int gnutls_pkcs11_delete_url (const char * OBJECT_URL,
2720 OBJECT_URL: The URL of the object to delete.
2722 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2724 This function will delete objects matching the given URL. Note that
2725 not all tokens support the delete operation.
2727 *Returns:* On success, the number of objects deleted is returned,
2728 otherwise a negative error value.
2732 gnutls_pkcs11_get_pin_function
2733 ------------------------------
2735 -- Function: gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void
2737 USERDATA: data to be supplied to callback
2739 This function will return the callback function set using
2740 'gnutls_pkcs11_set_pin_function()' .
2742 *Returns:* The function set or NULL otherwise.
2746 gnutls_pkcs11_get_raw_issuer
2747 ----------------------------
2749 -- Function: int gnutls_pkcs11_get_raw_issuer (const char * URL,
2750 gnutls_x509_crt_t CERT, gnutls_datum_t * ISSUER,
2751 gnutls_x509_crt_fmt_t FMT, unsigned int FLAGS)
2752 URL: A PKCS 11 url identifying a token
2754 CERT: is the certificate to find issuer for
2756 ISSUER: Will hold the issuer if any in an allocated buffer.
2758 FMT: The format of the exported issuer.
2760 FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2762 This function will return the issuer of a given certificate, if it
2763 is stored in the token. By default only marked as trusted issuers
2764 are retuned. If any issuer should be returned specify
2765 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY' in 'flags' .
2767 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2768 otherwise a negative error value.
2775 -- Function: int gnutls_pkcs11_init (unsigned int FLAGS, const char *
2776 DEPRECATED_CONFIG_FILE)
2777 FLAGS: An ORed sequence of 'GNUTLS_PKCS11_FLAG_' *
2779 DEPRECATED_CONFIG_FILE: either NULL or the location of a deprecated
2782 This function will initialize the PKCS 11 subsystem in gnutls. It
2783 will read configuration files if 'GNUTLS_PKCS11_FLAG_AUTO' is used
2784 or allow you to independently load PKCS 11 modules using
2785 'gnutls_pkcs11_add_provider()' if 'GNUTLS_PKCS11_FLAG_MANUAL' is
2788 Normally you don't need to call this function since it is being
2789 called when the first PKCS 11 operation is requested using the
2790 'GNUTLS_PKCS11_FLAG_AUTO' flag. If another flags are required then
2791 it must be called independently prior to any PKCS 11 operation.
2793 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2794 otherwise a negative error value.
2798 gnutls_pkcs11_obj_deinit
2799 ------------------------
2801 -- Function: void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t OBJ)
2802 OBJ: The structure to be initialized
2804 This function will deinitialize a certificate structure.
2808 gnutls_pkcs11_obj_export
2809 ------------------------
2811 -- Function: int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t OBJ,
2812 void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)
2813 OBJ: Holds the object
2815 OUTPUT_DATA: will contain the object data
2817 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2818 replaced by the actual size of parameters)
2820 This function will export the PKCS11 object data. It is normal for
2821 data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2824 If the buffer provided is not long enough to hold the output, then
2825 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2828 *Returns:* In case of failure a negative error code will be
2829 returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2833 gnutls_pkcs11_obj_export2
2834 -------------------------
2836 -- Function: int gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t OBJ,
2837 gnutls_datum_t * OUT)
2838 OBJ: Holds the object
2840 OUT: will contain the object data
2842 This function will export the PKCS11 object data. It is normal for
2843 data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2846 The output buffer is allocated using 'gnutls_malloc()' .
2848 *Returns:* In case of failure a negative error code will be
2849 returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2853 gnutls_pkcs11_obj_export3
2854 -------------------------
2856 -- Function: int gnutls_pkcs11_obj_export3 (gnutls_pkcs11_obj_t OBJ,
2857 gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * OUT)
2858 OBJ: Holds the object
2860 FMT: The format of the exported data
2862 OUT: will contain the object data
2864 This function will export the PKCS11 object data. It is normal for
2865 data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2868 The output buffer is allocated using 'gnutls_malloc()' .
2870 *Returns:* In case of failure a negative error code will be
2871 returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2875 gnutls_pkcs11_obj_export_url
2876 ----------------------------
2878 -- Function: int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t OBJ,
2879 gnutls_pkcs11_url_type_t DETAILED, char ** URL)
2880 OBJ: Holds the PKCS 11 certificate
2882 DETAILED: non zero if a detailed URL is required
2884 URL: will contain an allocated url
2886 This function will export a URL identifying the given certificate.
2888 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2889 otherwise a negative error value.
2893 gnutls_pkcs11_obj_get_info
2894 --------------------------
2896 -- Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t CRT,
2897 gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t *
2899 CRT: should contain a 'gnutls_pkcs11_obj_t' structure
2901 ITYPE: Denotes the type of information requested
2903 OUTPUT: where output will be stored
2905 OUTPUT_SIZE: contains the maximum size of the output and will be
2906 overwritten with actual
2908 This function will return information about the PKCS11 certificate
2909 such as the label, id as well as token information where the key is
2910 stored. When output is text it returns null terminated string
2911 although 'output_size' contains the size of the actual data only.
2913 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
2918 gnutls_pkcs11_obj_get_type
2919 --------------------------
2921 -- Function: gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type
2922 (gnutls_pkcs11_obj_t OBJ)
2923 OBJ: Holds the PKCS 11 object
2925 This function will return the type of the certificate being stored
2928 *Returns:* The type of the certificate.
2932 gnutls_pkcs11_obj_import_url
2933 ----------------------------
2935 -- Function: int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t OBJ,
2936 const char * URL, unsigned int FLAGS)
2937 OBJ: The structure to store the object
2939 URL: a PKCS 11 url identifying the key
2941 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2943 This function will "import" a PKCS 11 URL identifying an object
2944 (e.g. certificate) to the 'gnutls_pkcs11_obj_t' structure. This
2945 does not involve any parsing (such as X.509 or OpenPGP) since the
2946 'gnutls_pkcs11_obj_t' is format agnostic. Only data are
2949 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2950 otherwise a negative error value.
2954 gnutls_pkcs11_obj_init
2955 ----------------------
2957 -- Function: int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * OBJ)
2958 OBJ: The structure to be initialized
2960 This function will initialize a pkcs11 certificate structure.
2962 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2963 otherwise a negative error value.
2967 gnutls_pkcs11_obj_list_import_url
2968 ---------------------------------
2970 -- Function: int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t
2971 * P_LIST, unsigned int * N_LIST, const char * URL,
2972 gnutls_pkcs11_obj_attr_t ATTRS, unsigned int FLAGS)
2973 P_LIST: An uninitialized object list (may be NULL)
2975 N_LIST: initially should hold the maximum size of the list. Will
2976 contain the actual size.
2978 URL: A PKCS 11 url identifying a set of objects
2980 ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
2981 used to limit output
2983 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2985 This function will initialize and set values to an object list by
2986 using all objects identified by a PKCS 11 URL.
2988 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2989 otherwise a negative error value.
2993 gnutls_pkcs11_obj_list_import_url2
2994 ----------------------------------
2996 -- Function: int gnutls_pkcs11_obj_list_import_url2
2997 (gnutls_pkcs11_obj_t ** P_LIST, unsigned int * N_LIST, const
2998 char * URL, gnutls_pkcs11_obj_attr_t ATTRS, unsigned int
3000 P_LIST: An uninitialized object list (may be NULL)
3002 N_LIST: It will contain the size of the list.
3004 URL: A PKCS 11 url identifying a set of objects
3006 ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
3007 used to limit output
3009 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
3011 This function will initialize and set values to an object list by
3012 using all objects identified by the PKCS 11 URL. The output is
3013 stored in 'p_list' , which will be initialized.
3015 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3016 otherwise a negative error value.
3020 gnutls_pkcs11_obj_set_pin_function
3021 ----------------------------------
3023 -- Function: void gnutls_pkcs11_obj_set_pin_function
3024 (gnutls_pkcs11_obj_t OBJ, gnutls_pin_callback_t FN, void *
3026 OBJ: The object structure
3030 USERDATA: data associated with the callback
3032 This function will set a callback function to be used when required
3033 to access the object. This function overrides the global set using
3034 'gnutls_pkcs11_set_pin_function()' .
3038 gnutls_pkcs11_privkey_deinit
3039 ----------------------------
3041 -- Function: void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t
3043 KEY: The structure to be initialized
3045 This function will deinitialize a private key structure.
3047 gnutls_pkcs11_privkey_export_url
3048 --------------------------------
3050 -- Function: int gnutls_pkcs11_privkey_export_url
3051 (gnutls_pkcs11_privkey_t KEY, gnutls_pkcs11_url_type_t
3052 DETAILED, char ** URL)
3053 KEY: Holds the PKCS 11 key
3055 DETAILED: non zero if a detailed URL is required
3057 URL: will contain an allocated url
3059 This function will export a URL identifying the given key.
3061 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3062 otherwise a negative error value.
3064 gnutls_pkcs11_privkey_generate
3065 ------------------------------
3067 -- Function: int gnutls_pkcs11_privkey_generate (const char * URL,
3068 gnutls_pk_algorithm_t PK, unsigned int BITS, const char *
3069 LABEL, unsigned int FLAGS)
3072 PK: the public key algorithm
3074 BITS: the security bits
3078 FLAGS: should be zero
3080 This function will generate a private key in the specified by the
3081 'url' token. The private key will be generate within the token and
3082 will not be exportable.
3084 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3085 otherwise a negative error value.
3089 gnutls_pkcs11_privkey_generate2
3090 -------------------------------
3092 -- Function: int gnutls_pkcs11_privkey_generate2 (const char * URL,
3093 gnutls_pk_algorithm_t PK, unsigned int BITS, const char *
3094 LABEL, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * PUBKEY,
3098 PK: the public key algorithm
3100 BITS: the security bits
3104 FMT: the format of output params. PEM or DER.
3106 PUBKEY: will hold the public key (may be 'NULL' )
3108 FLAGS: should be zero
3110 This function will generate a private key in the specified by the
3111 'url' token. The private key will be generate within the token and
3112 will not be exportable. This function will store the DER-encoded
3113 public key in the SubjectPublicKeyInfo format in 'pubkey' . The
3114 'pubkey' should be deinitialized using 'gnutls_free()' .
3116 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3117 otherwise a negative error value.
3121 gnutls_pkcs11_privkey_get_info
3122 ------------------------------
3124 -- Function: int gnutls_pkcs11_privkey_get_info
3125 (gnutls_pkcs11_privkey_t PKEY, gnutls_pkcs11_obj_info_t ITYPE,
3126 void * OUTPUT, size_t * OUTPUT_SIZE)
3127 PKEY: should contain a 'gnutls_pkcs11_privkey_t' structure
3129 ITYPE: Denotes the type of information requested
3131 OUTPUT: where output will be stored
3133 OUTPUT_SIZE: contains the maximum size of the output and will be
3134 overwritten with actual
3136 This function will return information about the PKCS 11 private key
3137 such as the label, id as well as token information where the key is
3138 stored. When output is text it returns null terminated string
3139 although 'output_size' contains the size of the actual data only.
3141 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3144 gnutls_pkcs11_privkey_get_pk_algorithm
3145 --------------------------------------
3147 -- Function: int gnutls_pkcs11_privkey_get_pk_algorithm
3148 (gnutls_pkcs11_privkey_t KEY, unsigned int * BITS)
3149 KEY: should contain a 'gnutls_pkcs11_privkey_t' structure
3151 BITS: if bits is non null it will hold the size of the parameters'
3154 This function will return the public key algorithm of a private
3157 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3158 success, or a negative error code on error.
3160 gnutls_pkcs11_privkey_import_url
3161 --------------------------------
3163 -- Function: int gnutls_pkcs11_privkey_import_url
3164 (gnutls_pkcs11_privkey_t PKEY, const char * URL, unsigned int
3166 PKEY: The structure to store the parsed key
3168 URL: a PKCS 11 url identifying the key
3170 FLAGS: sequence of GNUTLS_PKCS_PRIVKEY_*
3172 This function will "import" a PKCS 11 URL identifying a private key
3173 to the 'gnutls_pkcs11_privkey_t' structure. In reality since in
3174 most cases keys cannot be exported, the private key structure is
3175 being associated with the available operations on the token.
3177 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3178 otherwise a negative error value.
3180 gnutls_pkcs11_privkey_init
3181 --------------------------
3183 -- Function: int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *
3185 KEY: The structure to be initialized
3187 This function will initialize an private key structure.
3189 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3190 otherwise a negative error value.
3192 gnutls_pkcs11_privkey_set_pin_function
3193 --------------------------------------
3195 -- Function: void gnutls_pkcs11_privkey_set_pin_function
3196 (gnutls_pkcs11_privkey_t KEY, gnutls_pin_callback_t FN, void *
3198 KEY: The private key
3202 USERDATA: data associated with the callback
3204 This function will set a callback function to be used when required
3205 to access the object. This function overrides the global set using
3206 'gnutls_pkcs11_set_pin_function()' .
3210 gnutls_pkcs11_privkey_status
3211 ----------------------------
3213 -- Function: int gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t
3217 Checks the status of the private key token.
3219 *Returns:* this function will return non-zero if the token holding
3220 the private key is still available (inserted), and zero otherwise.
3224 gnutls_pkcs11_reinit
3225 --------------------
3227 -- Function: int gnutls_pkcs11_reinit ( VOID)
3229 This function will reinitialize the PKCS 11 subsystem in gnutls.
3230 This is required by PKCS 11 when an application uses 'fork()' .
3231 The reinitialization function must be called on the child.
3233 Note that since GnuTLS 3.3.0, the reinitialization of the PKCS '11'
3234 subsystem occurs automatically after fork.
3236 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3237 otherwise a negative error value.
3241 gnutls_pkcs11_set_pin_function
3242 ------------------------------
3244 -- Function: void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t
3245 FN, void * USERDATA)
3246 FN: The PIN callback, a 'gnutls_pin_callback_t()' function.
3248 USERDATA: data to be supplied to callback
3250 This function will set a callback function to be used when a PIN is
3251 required for PKCS 11 operations. See 'gnutls_pin_callback_t()' on
3252 how the callback should behave.
3256 gnutls_pkcs11_set_token_function
3257 --------------------------------
3259 -- Function: void gnutls_pkcs11_set_token_function
3260 (gnutls_pkcs11_token_callback_t FN, void * USERDATA)
3261 FN: The token callback
3263 USERDATA: data to be supplied to callback
3265 This function will set a callback function to be used when a token
3266 needs to be inserted to continue PKCS 11 operations.
3270 gnutls_pkcs11_token_get_flags
3271 -----------------------------
3273 -- Function: int gnutls_pkcs11_token_get_flags (const char * URL,
3274 unsigned int * FLAGS)
3275 URL: should contain a PKCS 11 URL
3277 FLAGS: The output flags (GNUTLS_PKCS11_TOKEN_*)
3279 This function will return information about the PKCS 11 token
3282 The supported flags are: 'GNUTLS_PKCS11_TOKEN_HW' and
3283 'GNUTLS_PKCS11_TOKEN_TRUSTED' .
3285 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3290 gnutls_pkcs11_token_get_info
3291 ----------------------------
3293 -- Function: int gnutls_pkcs11_token_get_info (const char * URL,
3294 gnutls_pkcs11_token_info_t TTYPE, void * OUTPUT, size_t *
3296 URL: should contain a PKCS 11 URL
3298 TTYPE: Denotes the type of information requested
3300 OUTPUT: where output will be stored
3302 OUTPUT_SIZE: contains the maximum size of the output and will be
3303 overwritten with actual
3305 This function will return information about the PKCS 11 token such
3306 as the label, id, etc.
3308 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3313 gnutls_pkcs11_token_get_mechanism
3314 ---------------------------------
3316 -- Function: int gnutls_pkcs11_token_get_mechanism (const char * URL,
3317 unsigned int IDX, unsigned long * MECHANISM)
3318 URL: should contain a PKCS 11 URL
3320 IDX: The index of the mechanism
3322 MECHANISM: The PKCS '11' mechanism ID
3324 This function will return the names of the supported mechanisms by
3325 the token. It should be called with an increasing index until it
3326 return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
3328 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3333 gnutls_pkcs11_token_get_random
3334 ------------------------------
3336 -- Function: int gnutls_pkcs11_token_get_random (const char *
3337 TOKEN_URL, void * RNDDATA, size_t LEN)
3338 TOKEN_URL: A PKCS '11' URL specifying a token
3340 RNDDATA: A pointer to the memory area to be filled with random data
3342 LEN: The number of bytes of randomness to request
3344 This function will get random data from the given token. It will
3345 store rnddata and fill the memory pointed to by rnddata with len
3346 random bytes from the token.
3348 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3349 otherwise a negative error value.
3351 gnutls_pkcs11_token_get_url
3352 ---------------------------
3354 -- Function: int gnutls_pkcs11_token_get_url (unsigned int SEQ,
3355 gnutls_pkcs11_url_type_t DETAILED, char ** URL)
3356 SEQ: sequence number starting from 0
3358 DETAILED: non zero if a detailed URL is required
3360 URL: will contain an allocated url
3362 This function will return the URL for each token available in
3363 system. The url has to be released using 'gnutls_free()'
3365 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3366 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the sequence number
3367 exceeds the available tokens, otherwise a negative error value.
3371 gnutls_pkcs11_token_init
3372 ------------------------
3374 -- Function: int gnutls_pkcs11_token_init (const char * TOKEN_URL,
3375 const char * SO_PIN, const char * LABEL)
3376 TOKEN_URL: A PKCS '11' URL specifying a token
3378 SO_PIN: Security Officer's PIN
3380 LABEL: A name to be used for the token
3382 This function will initialize (format) a token. If the token is at
3383 a factory defaults state the security officer's PIN given will be
3384 set to be the default. Otherwise it should match the officer's
3387 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3388 otherwise a negative error value.
3390 gnutls_pkcs11_token_set_pin
3391 ---------------------------
3393 -- Function: int gnutls_pkcs11_token_set_pin (const char * TOKEN_URL,
3394 const char * OLDPIN, const char * NEWPIN, unsigned int FLAGS)
3395 TOKEN_URL: A PKCS '11' URL specifying a token
3397 OLDPIN: old user's PIN
3399 NEWPIN: new user's PIN
3401 FLAGS: one of 'gnutls_pin_flag_t' .
3403 This function will modify or set a user's PIN for the given token.
3404 If it is called to set a user pin for first time the oldpin must be
3407 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3408 otherwise a negative error value.
3410 gnutls_pkcs11_type_get_name
3411 ---------------------------
3413 -- Function: const char * gnutls_pkcs11_type_get_name
3414 (gnutls_pkcs11_obj_type_t TYPE)
3415 TYPE: Holds the PKCS 11 object type, a 'gnutls_pkcs11_obj_type_t' .
3417 This function will return a human readable description of the
3418 PKCS11 object type 'obj' . It will return "Unknown" for unknown
3421 *Returns:* human readable string labeling the PKCS11 object type
3426 gnutls_x509_crt_import_pkcs11
3427 -----------------------------
3429 -- Function: int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t CRT,
3430 gnutls_pkcs11_obj_t PKCS11_CRT)
3431 CRT: A certificate of type 'gnutls_x509_crt_t'
3433 PKCS11_CRT: A PKCS 11 object that contains a certificate
3435 This function will import a PKCS 11 certificate to a
3436 'gnutls_x509_crt_t' structure.
3438 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3439 otherwise a negative error value.
3443 gnutls_x509_crt_import_pkcs11_url
3444 ---------------------------------
3446 -- Function: int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t
3447 CRT, const char * URL, unsigned int FLAGS)
3448 CRT: A certificate of type 'gnutls_x509_crt_t'
3452 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
3454 This function will import a PKCS 11 certificate directly from a
3455 token without involving the 'gnutls_pkcs11_obj_t' structure. This
3456 function will fail if the certificate stored is not of X.509 type.
3458 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3459 otherwise a negative error value.
3463 gnutls_x509_crt_list_import_pkcs11
3464 ----------------------------------
3466 -- Function: int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t
3467 * CERTS, unsigned int CERT_MAX, gnutls_pkcs11_obj_t * const
3468 OBJS, unsigned int FLAGS)
3469 CERTS: A list of certificates of type 'gnutls_x509_crt_t'
3471 CERT_MAX: The maximum size of the list
3473 OBJS: A list of PKCS 11 objects
3477 This function will import a PKCS 11 certificate list to a list of
3478 'gnutls_x509_crt_t' structure. These must not be initialized.
3480 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3481 otherwise a negative error value.
3486 File: gnutls.info, Node: TPM API, Next: Abstract key API, Prev: PKCS 11 API, Up: API reference
3491 The following functions are to be used for TPM handling. Their
3492 prototypes lie in 'gnutls/tpm.h'.
3494 gnutls_tpm_get_registered
3495 -------------------------
3497 -- Function: int gnutls_tpm_get_registered (gnutls_tpm_key_list_t *
3499 LIST: a list to store the keys
3501 This function will get a list of stored keys in the TPM. The uuid
3504 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3505 otherwise a negative error value.
3509 gnutls_tpm_key_list_deinit
3510 --------------------------
3512 -- Function: void gnutls_tpm_key_list_deinit (gnutls_tpm_key_list_t
3514 LIST: a list of the keys
3516 This function will deinitialize the list of stored keys in the TPM.
3520 gnutls_tpm_key_list_get_url
3521 ---------------------------
3523 -- Function: int gnutls_tpm_key_list_get_url (gnutls_tpm_key_list_t
3524 LIST, unsigned int IDX, char ** URL, unsigned int FLAGS)
3525 LIST: a list of the keys
3527 IDX: The index of the key (starting from zero)
3529 URL: The URL to be returned
3531 FLAGS: should be zero
3533 This function will return for each given index a URL of the
3534 corresponding key. If the provided index is out of bounds then
3535 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3537 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3538 otherwise a negative error value.
3542 gnutls_tpm_privkey_delete
3543 -------------------------
3545 -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
3546 char * SRK_PASSWORD)
3547 URL: the URL describing the key
3549 SRK_PASSWORD: a password for the SRK key
3551 This function will unregister the private key from the TPM chip.
3553 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3554 otherwise a negative error value.
3558 gnutls_tpm_privkey_generate
3559 ---------------------------
3561 -- Function: int gnutls_tpm_privkey_generate (gnutls_pk_algorithm_t PK,
3562 unsigned int BITS, const char * SRK_PASSWORD, const char *
3563 KEY_PASSWORD, gnutls_tpmkey_fmt_t FORMAT,
3564 gnutls_x509_crt_fmt_t PUB_FORMAT, gnutls_datum_t * PRIVKEY,
3565 gnutls_datum_t * PUBKEY, unsigned int FLAGS)
3566 PK: the public key algorithm
3568 BITS: the security bits
3570 SRK_PASSWORD: a password to protect the exported key (optional)
3572 KEY_PASSWORD: the password for the TPM (optional)
3574 FORMAT: the format of the private key
3576 PUB_FORMAT: the format of the public key
3578 PRIVKEY: the generated key
3580 PUBKEY: the corresponding public key (may be null)
3582 FLAGS: should be a list of GNUTLS_TPM_* flags
3584 This function will generate a private key in the TPM chip. The
3585 private key will be generated within the chip and will be exported
3586 in a wrapped with TPM's master key form. Furthermore the wrapped
3587 key can be protected with the provided 'password' .
3589 Note that bits in TPM is quantized value. If the input value is
3590 not one of the allowed values, then it will be quantized to one of
3591 512, 1024, 2048, 4096, 8192 and 16384.
3595 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3596 otherwise a negative error value.
3601 File: gnutls.info, Node: Abstract key API, Next: DANE API, Prev: TPM API, Up: API reference
3603 E.9 Abstract key API
3604 ====================
3606 The following functions are to be used for abstract key handling. Their
3607 prototypes lie in 'gnutls/abstract.h'.
3609 gnutls_certificate_set_key
3610 --------------------------
3612 -- Function: int gnutls_certificate_set_key
3613 (gnutls_certificate_credentials_t RES, const char ** NAMES,
3614 int NAMES_SIZE, gnutls_pcert_st * PCERT_LIST, int
3615 PCERT_LIST_SIZE, gnutls_privkey_t KEY)
3616 RES: is a 'gnutls_certificate_credentials_t' structure.
3618 NAMES: is an array of DNS name of the certificate (NULL if none)
3620 NAMES_SIZE: holds the size of the names list
3622 PCERT_LIST: contains a certificate list (path) for the specified
3625 PCERT_LIST_SIZE: holds the size of the certificate list
3627 KEY: is a 'gnutls_privkey_t' key
3629 This function sets a certificate/private key pair in the
3630 gnutls_certificate_credentials_t structure. This function may be
3631 called more than once, in case multiple keys/certificates exist for
3632 the server. For clients that wants to send more than its own end
3633 entity certificate (e.g., also an intermediate CA cert) then put
3634 the certificate chain in 'pcert_list' .
3636 Note that the 'pcert_list' and 'key' will become part of the
3637 credentials structure and must not be deallocated. They will be
3638 automatically deallocated when the 'res' structure is
3641 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
3646 gnutls_certificate_set_retrieve_function2
3647 -----------------------------------------
3649 -- Function: void gnutls_certificate_set_retrieve_function2
3650 (gnutls_certificate_credentials_t CRED,
3651 gnutls_certificate_retrieve_function2 * FUNC)
3652 CRED: is a 'gnutls_certificate_credentials_t' structure.
3654 FUNC: is the callback function
3656 This function sets a callback to be called in order to retrieve the
3657 certificate to be used in the handshake.
3659 The callback's function prototype is: int
3660 (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int
3661 nreqs, const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length,
3662 gnutls_pcert_st** pcert, unsigned int *pcert_length,
3663 gnutls_privkey_t * pkey);
3665 'req_ca_cert' is only used in X.509 certificates. Contains a list
3666 with the CA names that the server considers trusted. Normally we
3667 should send a certificate that is signed by one of these CAs.
3668 These names are DER encoded. To get a more meaningful value use
3669 the function 'gnutls_x509_rdn_get()' .
3671 'pk_algos' contains a list with server's acceptable signature
3672 algorithms. The certificate returned should support the server's
3675 'pcert' should contain a single certificate and public or a list of
3678 'pcert_length' is the size of the previous list.
3680 'pkey' is the private key.
3682 If the callback function is provided then gnutls will call it, in
3683 the handshake, after the certificate request message has been
3686 In server side pk_algos and req_ca_dn are NULL.
3688 The callback function should set the certificate list to be sent,
3689 and return 0 on success. If no certificate was selected then the
3690 number of certificates should be set to zero. The value (-1)
3691 indicates error and the handshake will be terminated.
3698 -- Function: void gnutls_pcert_deinit (gnutls_pcert_st * PCERT)
3699 PCERT: The structure to be deinitialized
3701 This function will deinitialize a pcert structure.
3705 gnutls_pcert_import_openpgp
3706 ---------------------------
3708 -- Function: int gnutls_pcert_import_openpgp (gnutls_pcert_st * PCERT,
3709 gnutls_openpgp_crt_t CRT, unsigned int FLAGS)
3710 PCERT: The pcert structure
3712 CRT: The raw certificate to be imported
3716 This convenience function will import the given certificate to a
3717 'gnutls_pcert_st' structure. The structure must be deinitialized
3718 afterwards using 'gnutls_pcert_deinit()' ;
3720 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3721 otherwise a negative error value.
3725 gnutls_pcert_import_openpgp_raw
3726 -------------------------------
3728 -- Function: int gnutls_pcert_import_openpgp_raw (gnutls_pcert_st *
3729 PCERT, const gnutls_datum_t * CERT, gnutls_openpgp_crt_fmt_t
3730 FORMAT, gnutls_openpgp_keyid_t KEYID, unsigned int FLAGS)
3731 PCERT: The pcert structure
3733 CERT: The raw certificate to be imported
3735 FORMAT: The format of the certificate
3737 KEYID: The key ID to use (NULL for the master key)
3741 This convenience function will import the given certificate to a
3742 'gnutls_pcert_st' structure. The structure must be deinitialized
3743 afterwards using 'gnutls_pcert_deinit()' ;
3745 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3746 otherwise a negative error value.
3750 gnutls_pcert_import_x509
3751 ------------------------
3753 -- Function: int gnutls_pcert_import_x509 (gnutls_pcert_st * PCERT,
3754 gnutls_x509_crt_t CRT, unsigned int FLAGS)
3755 PCERT: The pcert structure
3757 CRT: The raw certificate to be imported
3761 This convenience function will import the given certificate to a
3762 'gnutls_pcert_st' structure. The structure must be deinitialized
3763 afterwards using 'gnutls_pcert_deinit()' ;
3765 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3766 otherwise a negative error value.
3770 gnutls_pcert_import_x509_raw
3771 ----------------------------
3773 -- Function: int gnutls_pcert_import_x509_raw (gnutls_pcert_st * PCERT,
3774 const gnutls_datum_t * CERT, gnutls_x509_crt_fmt_t FORMAT,
3776 PCERT: The pcert structure
3778 CERT: The raw certificate to be imported
3780 FORMAT: The format of the certificate
3784 This convenience function will import the given certificate to a
3785 'gnutls_pcert_st' structure. The structure must be deinitialized
3786 afterwards using 'gnutls_pcert_deinit()' ;
3788 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3789 otherwise a negative error value.
3793 gnutls_pcert_list_import_x509_raw
3794 ---------------------------------
3796 -- Function: int gnutls_pcert_list_import_x509_raw (gnutls_pcert_st *
3797 PCERTS, unsigned int * PCERT_MAX, const gnutls_datum_t * DATA,
3798 gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
3799 PCERTS: The structures to store the parsed certificate. Must not
3802 PCERT_MAX: Initially must hold the maximum number of certs. It
3803 will be updated with the number of certs available.
3805 DATA: The certificates.
3807 FORMAT: One of DER or PEM.
3809 FLAGS: must be (0) or an OR'd sequence of
3810 gnutls_certificate_import_flags.
3812 This function will convert the given PEM encoded certificate list
3813 to the native gnutls_x509_crt_t format. The output will be stored
3814 in 'certs' . They will be automatically initialized.
3816 If the Certificate is PEM encoded it should have a header of "X509
3817 CERTIFICATE", or "CERTIFICATE".
3819 *Returns:* the number of certificates read or a negative error
3824 gnutls_privkey_decrypt_data
3825 ---------------------------
3827 -- Function: int gnutls_privkey_decrypt_data (gnutls_privkey_t KEY,
3828 unsigned int FLAGS, const gnutls_datum_t * CIPHERTEXT,
3829 gnutls_datum_t * PLAINTEXT)
3834 CIPHERTEXT: holds the data to be decrypted
3836 PLAINTEXT: will contain the decrypted data, allocated with
3839 This function will decrypt the given data using the algorithm
3840 supported by the private key.
3842 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3843 otherwise a negative error value.
3847 gnutls_privkey_deinit
3848 ---------------------
3850 -- Function: void gnutls_privkey_deinit (gnutls_privkey_t KEY)
3851 KEY: The structure to be deinitialized
3853 This function will deinitialize a private key structure.
3857 gnutls_privkey_export_dsa_raw
3858 -----------------------------
3860 -- Function: int gnutls_privkey_export_dsa_raw (gnutls_privkey_t KEY,
3861 gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G,
3862 gnutls_datum_t * Y, gnutls_datum_t * X)
3863 KEY: Holds the public key
3875 This function will export the DSA private key's parameters found in
3876 the given structure. The new parameters will be allocated using
3877 'gnutls_malloc()' and will be stored in the appropriate datum.
3879 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3884 gnutls_privkey_export_ecc_raw
3885 -----------------------------
3887 -- Function: int gnutls_privkey_export_ecc_raw (gnutls_privkey_t KEY,
3888 gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t
3889 * Y, gnutls_datum_t * K)
3890 KEY: Holds the public key
3892 CURVE: will hold the curve
3894 X: will hold the x coordinate
3896 Y: will hold the y coordinate
3898 K: will hold the private key
3900 This function will export the ECC private key's parameters found in
3901 the given structure. The new parameters will be allocated using
3902 'gnutls_malloc()' and will be stored in the appropriate datum.
3904 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3909 gnutls_privkey_export_rsa_raw
3910 -----------------------------
3912 -- Function: int gnutls_privkey_export_rsa_raw (gnutls_privkey_t KEY,
3913 gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D,
3914 gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U,
3915 gnutls_datum_t * E1, gnutls_datum_t * E2)
3916 KEY: Holds the certificate
3918 M: will hold the modulus
3920 E: will hold the public exponent
3922 D: will hold the private exponent
3924 P: will hold the first prime (p)
3926 Q: will hold the second prime (q)
3928 U: will hold the coefficient
3930 E1: will hold e1 = d mod (p-1)
3932 E2: will hold e2 = d mod (q-1)
3934 This function will export the RSA private key's parameters found in
3935 the given structure. The new parameters will be allocated using
3936 'gnutls_malloc()' and will be stored in the appropriate datum.
3938 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3943 gnutls_privkey_generate
3944 -----------------------
3946 -- Function: int gnutls_privkey_generate (gnutls_privkey_t PKEY,
3947 gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int
3949 PKEY: The private key
3951 ALGO: is one of the algorithms in 'gnutls_pk_algorithm_t' .
3953 BITS: the size of the modulus
3955 FLAGS: unused for now. Must be 0.
3957 This function will generate a random private key. Note that this
3958 function must be called on an empty private key.
3960 Note that when generating an elliptic curve key, the curve can be
3961 substituted in the place of the bits parameter using the
3962 'GNUTLS_CURVE_TO_BITS()' macro.
3964 Do not set the number of bits directly, use
3965 'gnutls_sec_param_to_pk_bits()' .
3967 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3968 otherwise a negative error value.
3972 gnutls_privkey_get_pk_algorithm
3973 -------------------------------
3975 -- Function: int gnutls_privkey_get_pk_algorithm (gnutls_privkey_t KEY,
3976 unsigned int * BITS)
3977 KEY: should contain a 'gnutls_privkey_t' structure
3979 BITS: If set will return the number of bits of the parameters (may
3982 This function will return the public key algorithm of a private key
3983 and if possible will return a number of bits that indicates the
3984 security parameter of the key.
3986 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3987 success, or a negative error code on error.
3991 gnutls_privkey_get_type
3992 -----------------------
3994 -- Function: gnutls_privkey_type_t gnutls_privkey_get_type
3995 (gnutls_privkey_t KEY)
3996 KEY: should contain a 'gnutls_privkey_t' structure
3998 This function will return the type of the private key. This is
3999 actually the type of the subsystem used to set this private key.
4001 *Returns:* a member of the 'gnutls_privkey_type_t' enumeration on
4002 success, or a negative error code on error.
4006 gnutls_privkey_import_dsa_raw
4007 -----------------------------
4009 -- Function: int gnutls_privkey_import_dsa_raw (gnutls_privkey_t KEY,
4010 const gnutls_datum_t * P, const gnutls_datum_t * Q, const
4011 gnutls_datum_t * G, const gnutls_datum_t * Y, const
4013 KEY: The structure to store the parsed key
4025 This function will convert the given DSA raw parameters to the
4026 native 'gnutls_privkey_t' format. The output will be stored in
4029 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4030 otherwise a negative error value.
4032 gnutls_privkey_import_ecc_raw
4033 -----------------------------
4035 -- Function: int gnutls_privkey_import_ecc_raw (gnutls_privkey_t KEY,
4036 gnutls_ecc_curve_t CURVE, const gnutls_datum_t * X, const
4037 gnutls_datum_t * Y, const gnutls_datum_t * K)
4038 KEY: The structure to store the parsed key
4040 CURVE: holds the curve
4048 This function will convert the given elliptic curve parameters to
4049 the native 'gnutls_privkey_t' format. The output will be stored in
4052 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4053 otherwise a negative error value.
4057 gnutls_privkey_import_ext
4058 -------------------------
4060 -- Function: int gnutls_privkey_import_ext (gnutls_privkey_t PKEY,
4061 gnutls_pk_algorithm_t PK, void * USERDATA,
4062 gnutls_privkey_sign_func SIGN_FUNC,
4063 gnutls_privkey_decrypt_func DECRYPT_FUNC, unsigned int FLAGS)
4064 PKEY: The private key
4066 PK: The public key algorithm
4068 USERDATA: private data to be provided to the callbacks
4070 SIGN_FUNC: callback for signature operations
4072 DECRYPT_FUNC: callback for decryption operations
4074 FLAGS: Flags for the import
4076 This function will associate the given callbacks with the
4077 'gnutls_privkey_t' structure. At least one of the two callbacks
4080 See also 'gnutls_privkey_import_ext2()' .
4082 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4083 otherwise a negative error value.
4087 gnutls_privkey_import_ext2
4088 --------------------------
4090 -- Function: int gnutls_privkey_import_ext2 (gnutls_privkey_t PKEY,
4091 gnutls_pk_algorithm_t PK, void * USERDATA,
4092 gnutls_privkey_sign_func SIGN_FUNC,
4093 gnutls_privkey_decrypt_func DECRYPT_FUNC,
4094 gnutls_privkey_deinit_func DEINIT_FUNC, unsigned int FLAGS)
4095 PKEY: The private key
4097 PK: The public key algorithm
4099 USERDATA: private data to be provided to the callbacks
4101 SIGN_FUNC: callback for signature operations
4103 DECRYPT_FUNC: callback for decryption operations
4105 DEINIT_FUNC: a deinitialization function
4107 FLAGS: Flags for the import
4109 This function will associate the given callbacks with the
4110 'gnutls_privkey_t' structure. At least one of the two callbacks
4111 must be non-null. If a deinitialization function is provided then
4112 flags is assumed to contain 'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' .
4114 Note that the signing function is supposed to "raw" sign data,
4115 i.e., without any hashing or preprocessing. In case of RSA the
4116 DigestInfo will be provided, and the signing function is expected
4117 to do the PKCS '1' 1.5 padding and the exponentiation.
4119 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4120 otherwise a negative error value.
4124 gnutls_privkey_import_openpgp
4125 -----------------------------
4127 -- Function: int gnutls_privkey_import_openpgp (gnutls_privkey_t PKEY,
4128 gnutls_openpgp_privkey_t KEY, unsigned int FLAGS)
4129 PKEY: The private key
4131 KEY: The private key to be imported
4133 FLAGS: Flags for the import
4135 This function will import the given private key to the abstract
4136 'gnutls_privkey_t' structure.
4138 The 'gnutls_openpgp_privkey_t' object must not be deallocated
4139 during the lifetime of this structure. The subkey set as preferred
4140 will be used, or the master key otherwise.
4142 'flags' might be zero or one of
4143 'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4144 'GNUTLS_PRIVKEY_IMPORT_COPY' .
4146 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4147 otherwise a negative error value.
4151 gnutls_privkey_import_openpgp_raw
4152 ---------------------------------
4154 -- Function: int gnutls_privkey_import_openpgp_raw (gnutls_privkey_t
4155 PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t
4156 FORMAT, const gnutls_openpgp_keyid_t KEYID, const char *
4158 PKEY: The private key
4160 DATA: The private key data to be imported
4162 FORMAT: The format of the private key
4164 KEYID: The key id to use (optional)
4166 PASSWORD: A password (optional)
4168 This function will import the given private key to the abstract
4169 'gnutls_privkey_t' structure.
4171 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4172 otherwise a negative error value.
4176 gnutls_privkey_import_pkcs11
4177 ----------------------------
4179 -- Function: int gnutls_privkey_import_pkcs11 (gnutls_privkey_t PKEY,
4180 gnutls_pkcs11_privkey_t KEY, unsigned int FLAGS)
4181 PKEY: The private key
4183 KEY: The private key to be imported
4185 FLAGS: Flags for the import
4187 This function will import the given private key to the abstract
4188 'gnutls_privkey_t' structure.
4190 The 'gnutls_pkcs11_privkey_t' object must not be deallocated during
4191 the lifetime of this structure.
4193 'flags' might be zero or one of
4194 'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4195 'GNUTLS_PRIVKEY_IMPORT_COPY' .
4197 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4198 otherwise a negative error value.
4202 gnutls_privkey_import_pkcs11_url
4203 --------------------------------
4205 -- Function: int gnutls_privkey_import_pkcs11_url (gnutls_privkey_t
4206 KEY, const char * URL)
4207 KEY: A key of type 'gnutls_pubkey_t'
4211 This function will import a PKCS 11 private key to a
4212 'gnutls_private_key_t' structure.
4214 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4215 otherwise a negative error value.
4219 gnutls_privkey_import_rsa_raw
4220 -----------------------------
4222 -- Function: int gnutls_privkey_import_rsa_raw (gnutls_privkey_t KEY,
4223 const gnutls_datum_t * M, const gnutls_datum_t * E, const
4224 gnutls_datum_t * D, const gnutls_datum_t * P, const
4225 gnutls_datum_t * Q, const gnutls_datum_t * U, const
4226 gnutls_datum_t * E1, const gnutls_datum_t * E2)
4227 KEY: The structure to store the parsed key
4229 M: holds the modulus
4231 E: holds the public exponent
4233 D: holds the private exponent
4235 P: holds the first prime (p)
4237 Q: holds the second prime (q)
4239 U: holds the coefficient (optional)
4241 E1: holds e1 = d mod (p-1) (optional)
4243 E2: holds e2 = d mod (q-1) (optional)
4245 This function will convert the given RSA raw parameters to the
4246 native 'gnutls_privkey_t' format. The output will be stored in
4249 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4250 otherwise a negative error value.
4252 gnutls_privkey_import_tpm_raw
4253 -----------------------------
4255 -- Function: int gnutls_privkey_import_tpm_raw (gnutls_privkey_t PKEY,
4256 const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT,
4257 const char * SRK_PASSWORD, const char * KEY_PASSWORD, unsigned
4259 PKEY: The private key
4261 FDATA: The TPM key to be imported
4263 FORMAT: The format of the private key
4265 SRK_PASSWORD: The password for the SRK key (optional)
4267 KEY_PASSWORD: A password for the key (optional)
4269 FLAGS: should be zero
4271 This function will import the given private key to the abstract
4272 'gnutls_privkey_t' structure.
4274 With respect to passwords the same as in
4275 'gnutls_privkey_import_tpm_url()' apply.
4277 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4278 otherwise a negative error value.
4282 gnutls_privkey_import_tpm_url
4283 -----------------------------
4285 -- Function: int gnutls_privkey_import_tpm_url (gnutls_privkey_t PKEY,
4286 const char * URL, const char * SRK_PASSWORD, const char *
4287 KEY_PASSWORD, unsigned int FLAGS)
4288 PKEY: The private key
4290 URL: The URL of the TPM key to be imported
4292 SRK_PASSWORD: The password for the SRK key (optional)
4294 KEY_PASSWORD: A password for the key (optional)
4296 FLAGS: One of the GNUTLS_PRIVKEY_* flags
4298 This function will import the given private key to the abstract
4299 'gnutls_privkey_t' structure.
4301 Note that unless 'GNUTLS_PRIVKEY_DISABLE_CALLBACKS' is specified,
4302 if incorrect (or NULL) passwords are given the PKCS11 callback
4303 functions will be used to obtain the correct passwords. Otherwise
4304 if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
4305 returned and if the key password is wrong or not provided then
4306 'GNUTLS_E_TPM_KEY_PASSWORD_ERROR' is returned.
4308 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4309 otherwise a negative error value.
4313 gnutls_privkey_import_url
4314 -------------------------
4316 -- Function: int gnutls_privkey_import_url (gnutls_privkey_t KEY, const
4317 char * URL, unsigned int FLAGS)
4318 KEY: A key of type 'gnutls_privkey_t'
4322 FLAGS: should be zero
4324 This function will import a PKCS11 or TPM URL as a private key.
4325 The supported URL types can be checked using
4326 'gnutls_url_is_supported()' .
4328 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4329 otherwise a negative error value.
4333 gnutls_privkey_import_x509
4334 --------------------------
4336 -- Function: int gnutls_privkey_import_x509 (gnutls_privkey_t PKEY,
4337 gnutls_x509_privkey_t KEY, unsigned int FLAGS)
4338 PKEY: The private key
4340 KEY: The private key to be imported
4342 FLAGS: Flags for the import
4344 This function will import the given private key to the abstract
4345 'gnutls_privkey_t' structure.
4347 The 'gnutls_x509_privkey_t' object must not be deallocated during
4348 the lifetime of this structure.
4350 'flags' might be zero or one of
4351 'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4352 'GNUTLS_PRIVKEY_IMPORT_COPY' .
4354 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4355 otherwise a negative error value.
4359 gnutls_privkey_import_x509_raw
4360 ------------------------------
4362 -- Function: int gnutls_privkey_import_x509_raw (gnutls_privkey_t PKEY,
4363 const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT,
4364 const char * PASSWORD, unsigned int FLAGS)
4365 PKEY: The private key
4367 DATA: The private key data to be imported
4369 FORMAT: The format of the private key
4371 PASSWORD: A password (optional)
4373 FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
4375 This function will import the given private key to the abstract
4376 'gnutls_privkey_t' structure.
4378 The supported formats are basic unencrypted key, PKCS8, PKCS12, and
4381 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4382 otherwise a negative error value.
4389 -- Function: int gnutls_privkey_init (gnutls_privkey_t * KEY)
4390 KEY: The structure to be initialized
4392 This function will initialize an private key structure.
4394 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4395 otherwise a negative error value.
4399 gnutls_privkey_set_pin_function
4400 -------------------------------
4402 -- Function: void gnutls_privkey_set_pin_function (gnutls_privkey_t
4403 KEY, gnutls_pin_callback_t FN, void * USERDATA)
4404 KEY: A key of type 'gnutls_privkey_t'
4408 USERDATA: data associated with the callback
4410 This function will set a callback function to be used when required
4411 to access the object. This function overrides any other global PIN
4414 Note that this function must be called right after initialization
4419 gnutls_privkey_sign_data
4420 ------------------------
4422 -- Function: int gnutls_privkey_sign_data (gnutls_privkey_t SIGNER,
4423 gnutls_digest_algorithm_t HASH, unsigned int FLAGS, const
4424 gnutls_datum_t * DATA, gnutls_datum_t * SIGNATURE)
4425 SIGNER: Holds the key
4427 HASH: should be a digest algorithm
4429 FLAGS: Zero or one of 'gnutls_privkey_flags_t'
4431 DATA: holds the data to be signed
4433 SIGNATURE: will contain the signature allocate with
4436 This function will sign the given data using a signature algorithm
4437 supported by the private key. Signature algorithms are always used
4438 together with a hash functions. Different hash functions may be
4439 used for the RSA algorithm, but only the SHA family for the DSA
4442 You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
4443 determine the hash algorithm.
4445 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4446 otherwise a negative error value.
4450 gnutls_privkey_sign_hash
4451 ------------------------
4453 -- Function: int gnutls_privkey_sign_hash (gnutls_privkey_t SIGNER,
4454 gnutls_digest_algorithm_t HASH_ALGO, unsigned int FLAGS, const
4455 gnutls_datum_t * HASH_DATA, gnutls_datum_t * SIGNATURE)
4456 SIGNER: Holds the signer's key
4458 HASH_ALGO: The hash algorithm used
4460 FLAGS: Zero or one of 'gnutls_privkey_flags_t'
4462 HASH_DATA: holds the data to be signed
4464 SIGNATURE: will contain newly allocated signature
4466 This function will sign the given hashed data using a signature
4467 algorithm supported by the private key. Signature algorithms are
4468 always used together with a hash functions. Different hash
4469 functions may be used for the RSA algorithm, but only SHA-XXX for
4472 You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
4473 determine the hash algorithm.
4475 Note that if 'GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA' flag is specified
4476 this function will ignore 'hash_algo' and perform a raw PKCS1
4479 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4480 otherwise a negative error value.
4484 gnutls_privkey_status
4485 ---------------------
4487 -- Function: int gnutls_privkey_status (gnutls_privkey_t KEY)
4490 Checks the status of the private key token. This function is an
4491 actual wrapper over 'gnutls_pkcs11_privkey_status()' , and if the
4492 private key is a PKCS '11' token it will check whether it is
4495 *Returns:* this function will return non-zero if the token holding
4496 the private key is still available (inserted), and zero otherwise.
4500 gnutls_privkey_verify_params
4501 ----------------------------
4503 -- Function: int gnutls_privkey_verify_params (gnutls_privkey_t KEY)
4504 KEY: should contain a 'gnutls_privkey_t' structure
4506 This function will verify the private key parameters.
4508 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4509 otherwise a negative error value.
4513 gnutls_pubkey_deinit
4514 --------------------
4516 -- Function: void gnutls_pubkey_deinit (gnutls_pubkey_t KEY)
4517 KEY: The structure to be deinitialized
4519 This function will deinitialize a public key structure.
4523 gnutls_pubkey_encrypt_data
4524 --------------------------
4526 -- Function: int gnutls_pubkey_encrypt_data (gnutls_pubkey_t KEY,
4527 unsigned int FLAGS, const gnutls_datum_t * PLAINTEXT,
4528 gnutls_datum_t * CIPHERTEXT)
4529 KEY: Holds the public key
4531 FLAGS: should be 0 for now
4533 PLAINTEXT: The data to be encrypted
4535 CIPHERTEXT: contains the encrypted data
4537 This function will encrypt the given data, using the public key.
4539 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4540 otherwise a negative error value.
4544 gnutls_pubkey_export
4545 --------------------
4547 -- Function: int gnutls_pubkey_export (gnutls_pubkey_t KEY,
4548 gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
4550 KEY: Holds the certificate
4552 FORMAT: the format of output params. One of PEM or DER.
4554 OUTPUT_DATA: will contain a certificate PEM or DER encoded
4556 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4557 replaced by the actual size of parameters)
4559 This function will export the public key to DER or PEM format. The
4560 contents of the exported data is the SubjectPublicKeyInfo X.509
4563 If the buffer provided is not long enough to hold the output, then
4564 *output_data_size is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
4567 If the structure is PEM encoded, it will have a header of "BEGIN
4570 *Returns:* In case of failure a negative error code will be
4571 returned, and 0 on success.
4575 gnutls_pubkey_export2
4576 ---------------------
4578 -- Function: int gnutls_pubkey_export2 (gnutls_pubkey_t KEY,
4579 gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
4580 KEY: Holds the certificate
4582 FORMAT: the format of output params. One of PEM or DER.
4584 OUT: will contain a certificate PEM or DER encoded
4586 This function will export the public key to DER or PEM format. The
4587 contents of the exported data is the SubjectPublicKeyInfo X.509
4590 The output buffer will be allocated using 'gnutls_malloc()' .
4592 If the structure is PEM encoded, it will have a header of "BEGIN
4595 *Returns:* In case of failure a negative error code will be
4596 returned, and 0 on success.
4600 gnutls_pubkey_export_dsa_raw
4601 ----------------------------
4603 -- Function: int gnutls_pubkey_export_dsa_raw (gnutls_pubkey_t KEY,
4604 gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G,
4606 KEY: Holds the public key
4616 This function will export the DSA public key's parameters found in
4617 the given certificate. The new parameters will be allocated using
4618 'gnutls_malloc()' and will be stored in the appropriate datum.
4620 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4625 gnutls_pubkey_export_ecc_raw
4626 ----------------------------
4628 -- Function: int gnutls_pubkey_export_ecc_raw (gnutls_pubkey_t KEY,
4629 gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t
4631 KEY: Holds the public key
4633 CURVE: will hold the curve
4639 This function will export the ECC public key's parameters found in
4640 the given certificate. The new parameters will be allocated using
4641 'gnutls_malloc()' and will be stored in the appropriate datum.
4643 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4648 gnutls_pubkey_export_ecc_x962
4649 -----------------------------
4651 -- Function: int gnutls_pubkey_export_ecc_x962 (gnutls_pubkey_t KEY,
4652 gnutls_datum_t * PARAMETERS, gnutls_datum_t * ECPOINT)
4653 KEY: Holds the public key
4655 PARAMETERS: DER encoding of an ANSI X9.62 parameters
4657 ECPOINT: DER encoding of ANSI X9.62 ECPoint
4659 This function will export the ECC public key's parameters found in
4660 the given certificate. The new parameters will be allocated using
4661 'gnutls_malloc()' and will be stored in the appropriate datum.
4663 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4668 gnutls_pubkey_export_rsa_raw
4669 ----------------------------
4671 -- Function: int gnutls_pubkey_export_rsa_raw (gnutls_pubkey_t KEY,
4672 gnutls_datum_t * M, gnutls_datum_t * E)
4673 KEY: Holds the certificate
4675 M: will hold the modulus
4677 E: will hold the public exponent
4679 This function will export the RSA public key's parameters found in
4680 the given structure. The new parameters will be allocated using
4681 'gnutls_malloc()' and will be stored in the appropriate datum.
4683 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4688 gnutls_pubkey_get_key_id
4689 ------------------------
4691 -- Function: int gnutls_pubkey_get_key_id (gnutls_pubkey_t KEY,
4692 unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
4694 KEY: Holds the public key
4696 FLAGS: should be 0 for now
4698 OUTPUT_DATA: will contain the key ID
4700 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4701 replaced by the actual size of parameters)
4703 This function will return a unique ID that depends on the public
4704 key parameters. This ID can be used in checking whether a
4705 certificate corresponds to the given public key.
4707 If the buffer provided is not long enough to hold the output, then
4708 *output_data_size is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
4709 will be returned. The output will normally be a SHA-1 hash output,
4712 *Returns:* In case of failure a negative error code will be
4713 returned, and 0 on success.
4717 gnutls_pubkey_get_key_usage
4718 ---------------------------
4720 -- Function: int gnutls_pubkey_get_key_usage (gnutls_pubkey_t KEY,
4721 unsigned int * USAGE)
4722 KEY: should contain a 'gnutls_pubkey_t' structure
4724 USAGE: If set will return the number of bits of the parameters (may
4727 This function will return the key usage of the public key.
4729 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4730 otherwise a negative error value.
4734 gnutls_pubkey_get_openpgp_key_id
4735 --------------------------------
4737 -- Function: int gnutls_pubkey_get_openpgp_key_id (gnutls_pubkey_t KEY,
4738 unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
4739 OUTPUT_DATA_SIZE, unsigned int * SUBKEY)
4740 KEY: Holds the public key
4742 FLAGS: should be 0 or 'GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT'
4744 OUTPUT_DATA: will contain the key ID
4746 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4747 replaced by the actual size of parameters)
4749 SUBKEY: Will be non zero if the key ID corresponds to a subkey
4751 This function returns the OpenPGP key ID of the corresponding key.
4752 The key is a unique ID that depends on the public key parameters.
4754 If the flag 'GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT' is specified
4755 this function returns the fingerprint of the master key.
4757 If the buffer provided is not long enough to hold the output, then
4758 *output_data_size is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
4759 will be returned. The output is 'GNUTLS_OPENPGP_KEYID_SIZE' bytes
4762 *Returns:* In case of failure a negative error code will be
4763 returned, and 0 on success.
4767 gnutls_pubkey_get_pk_algorithm
4768 ------------------------------
4770 -- Function: int gnutls_pubkey_get_pk_algorithm (gnutls_pubkey_t KEY,
4771 unsigned int * BITS)
4772 KEY: should contain a 'gnutls_pubkey_t' structure
4774 BITS: If set will return the number of bits of the parameters (may
4777 This function will return the public key algorithm of a public key
4778 and if possible will return a number of bits that indicates the
4779 security parameter of the key.
4781 *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
4782 success, or a negative error code on error.
4786 gnutls_pubkey_get_preferred_hash_algorithm
4787 ------------------------------------------
4789 -- Function: int gnutls_pubkey_get_preferred_hash_algorithm
4790 (gnutls_pubkey_t KEY, gnutls_digest_algorithm_t * HASH,
4791 unsigned int * MAND)
4792 KEY: Holds the certificate
4794 HASH: The result of the call with the hash algorithm used for
4797 MAND: If non zero it means that the algorithm MUST use this hash.
4800 This function will read the certifcate and return the appropriate
4801 digest algorithm to use for signing with this certificate. Some
4802 certificates (i.e. DSA might not be able to sign without the
4803 preferred algorithm).
4805 To get the signature algorithm instead of just the hash use
4806 'gnutls_pk_to_sign()' with the algorithm of the certificate/key and
4807 the provided 'hash' .
4809 *Returns:* the 0 if the hash algorithm is found. A negative error
4810 code is returned on error.
4814 gnutls_pubkey_get_verify_algorithm
4815 ----------------------------------
4817 -- Function: int gnutls_pubkey_get_verify_algorithm (gnutls_pubkey_t
4818 KEY, const gnutls_datum_t * SIGNATURE,
4819 gnutls_digest_algorithm_t * HASH)
4820 KEY: Holds the certificate
4822 SIGNATURE: contains the signature
4824 HASH: The result of the call with the hash algorithm used for
4827 This function will read the certifcate and the signed data to
4828 determine the hash algorithm used to generate the signature.
4830 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4831 otherwise a negative error value.
4835 gnutls_pubkey_import
4836 --------------------
4838 -- Function: int gnutls_pubkey_import (gnutls_pubkey_t KEY, const
4839 gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
4840 KEY: The structure to store the parsed public key.
4842 DATA: The DER or PEM encoded certificate.
4844 FORMAT: One of DER or PEM
4846 This function will import the provided public key in a
4847 SubjectPublicKeyInfo X.509 structure to a native 'gnutls_pubkey_t'
4848 structure. The output will be stored in 'key' . If the public key
4849 is PEM encoded it should have a header of "PUBLIC KEY".
4851 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4852 otherwise a negative error value.
4856 gnutls_pubkey_import_dsa_raw
4857 ----------------------------
4859 -- Function: int gnutls_pubkey_import_dsa_raw (gnutls_pubkey_t KEY,
4860 const gnutls_datum_t * P, const gnutls_datum_t * Q, const
4861 gnutls_datum_t * G, const gnutls_datum_t * Y)
4862 KEY: The structure to store the parsed key
4872 This function will convert the given DSA raw parameters to the
4873 native 'gnutls_pubkey_t' format. The output will be stored in
4876 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4877 otherwise a negative error value.
4881 gnutls_pubkey_import_ecc_raw
4882 ----------------------------
4884 -- Function: int gnutls_pubkey_import_ecc_raw (gnutls_pubkey_t KEY,
4885 gnutls_ecc_curve_t CURVE, const gnutls_datum_t * X, const
4887 KEY: The structure to store the parsed key
4889 CURVE: holds the curve
4895 This function will convert the given elliptic curve parameters to a
4896 'gnutls_pubkey_t' . The output will be stored in 'key' .
4898 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4899 otherwise a negative error value.
4903 gnutls_pubkey_import_ecc_x962
4904 -----------------------------
4906 -- Function: int gnutls_pubkey_import_ecc_x962 (gnutls_pubkey_t KEY,
4907 const gnutls_datum_t * PARAMETERS, const gnutls_datum_t *
4909 KEY: The structure to store the parsed key
4911 PARAMETERS: DER encoding of an ANSI X9.62 parameters
4913 ECPOINT: DER encoding of ANSI X9.62 ECPoint
4915 This function will convert the given elliptic curve parameters to a
4916 'gnutls_pubkey_t' . The output will be stored in 'key' .
4918 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4919 otherwise a negative error value.
4923 gnutls_pubkey_import_openpgp
4924 ----------------------------
4926 -- Function: int gnutls_pubkey_import_openpgp (gnutls_pubkey_t KEY,
4927 gnutls_openpgp_crt_t CRT, unsigned int FLAGS)
4930 CRT: The certificate to be imported
4932 FLAGS: should be zero
4934 Imports a public key from an openpgp key. This function will
4935 import the given public key to the abstract 'gnutls_pubkey_t'
4936 structure. The subkey set as preferred will be imported or the
4937 master key otherwise.
4939 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4940 otherwise a negative error value.
4944 gnutls_pubkey_import_openpgp_raw
4945 --------------------------------
4947 -- Function: int gnutls_pubkey_import_openpgp_raw (gnutls_pubkey_t
4948 PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t
4949 FORMAT, const gnutls_openpgp_keyid_t KEYID, unsigned int
4951 PKEY: The public key
4953 DATA: The public key data to be imported
4955 FORMAT: The format of the public key
4957 KEYID: The key id to use (optional)
4959 FLAGS: Should be zero
4961 This function will import the given public key to the abstract
4962 'gnutls_pubkey_t' structure.
4964 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4965 otherwise a negative error value.
4969 gnutls_pubkey_import_pkcs11
4970 ---------------------------
4972 -- Function: int gnutls_pubkey_import_pkcs11 (gnutls_pubkey_t KEY,
4973 gnutls_pkcs11_obj_t OBJ, unsigned int FLAGS)
4976 OBJ: The parameters to be imported
4978 FLAGS: should be zero
4980 Imports a public key from a pkcs11 key. This function will import
4981 the given public key to the abstract 'gnutls_pubkey_t' structure.
4983 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4984 otherwise a negative error value.
4988 gnutls_pubkey_import_pkcs11_url
4989 -------------------------------
4991 -- Function: int gnutls_pubkey_import_pkcs11_url (gnutls_pubkey_t KEY,
4992 const char * URL, unsigned int FLAGS)
4993 KEY: A key of type 'gnutls_pubkey_t'
4997 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
4999 This function will import a PKCS 11 certificate to a
5000 'gnutls_pubkey_t' structure.
5002 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5003 otherwise a negative error value.
5007 gnutls_pubkey_import_privkey
5008 ----------------------------
5010 -- Function: int gnutls_pubkey_import_privkey (gnutls_pubkey_t KEY,
5011 gnutls_privkey_t PKEY, unsigned int USAGE, unsigned int FLAGS)
5014 PKEY: The private key
5016 USAGE: GNUTLS_KEY_* key usage flags.
5018 FLAGS: should be zero
5020 Imports the public key from a private. This function will import
5021 the given public key to the abstract 'gnutls_pubkey_t' structure.
5023 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5024 otherwise a negative error value.
5028 gnutls_pubkey_import_rsa_raw
5029 ----------------------------
5031 -- Function: int gnutls_pubkey_import_rsa_raw (gnutls_pubkey_t KEY,
5032 const gnutls_datum_t * M, const gnutls_datum_t * E)
5033 KEY: Is a structure will hold the parameters
5035 M: holds the modulus
5037 E: holds the public exponent
5039 This function will replace the parameters in the given structure.
5040 The new parameters should be stored in the appropriate
5043 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an negative error
5048 gnutls_pubkey_import_tpm_raw
5049 ----------------------------
5051 -- Function: int gnutls_pubkey_import_tpm_raw (gnutls_pubkey_t PKEY,
5052 const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT,
5053 const char * SRK_PASSWORD, unsigned int FLAGS)
5054 PKEY: The public key
5056 FDATA: The TPM key to be imported
5058 FORMAT: The format of the private key
5060 SRK_PASSWORD: The password for the SRK key (optional)
5062 FLAGS: One of the GNUTLS_PUBKEY_* flags
5064 This function will import the public key from the provided TPM key
5067 With respect to passwords the same as in
5068 'gnutls_pubkey_import_tpm_url()' apply.
5070 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5071 otherwise a negative error value.
5075 gnutls_pubkey_import_tpm_url
5076 ----------------------------
5078 -- Function: int gnutls_pubkey_import_tpm_url (gnutls_pubkey_t PKEY,
5079 const char * URL, const char * SRK_PASSWORD, unsigned int
5081 PKEY: The public key
5083 URL: The URL of the TPM key to be imported
5085 SRK_PASSWORD: The password for the SRK key (optional)
5087 FLAGS: should be zero
5089 This function will import the given private key to the abstract
5090 'gnutls_privkey_t' structure.
5092 Note that unless 'GNUTLS_PUBKEY_DISABLE_CALLBACKS' is specified, if
5093 incorrect (or NULL) passwords are given the PKCS11 callback
5094 functions will be used to obtain the correct passwords. Otherwise
5095 if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
5098 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5099 otherwise a negative error value.
5103 gnutls_pubkey_import_url
5104 ------------------------
5106 -- Function: int gnutls_pubkey_import_url (gnutls_pubkey_t KEY, const
5107 char * URL, unsigned int FLAGS)
5108 KEY: A key of type 'gnutls_pubkey_t'
5112 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
5114 This function will import a PKCS11 certificate or a TPM key as a
5117 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5118 otherwise a negative error value.
5122 gnutls_pubkey_import_x509
5123 -------------------------
5125 -- Function: int gnutls_pubkey_import_x509 (gnutls_pubkey_t KEY,
5126 gnutls_x509_crt_t CRT, unsigned int FLAGS)
5129 CRT: The certificate to be imported
5131 FLAGS: should be zero
5133 This function will import the given public key to the abstract
5134 'gnutls_pubkey_t' structure.
5136 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5137 otherwise a negative error value.
5141 gnutls_pubkey_import_x509_crq
5142 -----------------------------
5144 -- Function: int gnutls_pubkey_import_x509_crq (gnutls_pubkey_t KEY,
5145 gnutls_x509_crq_t CRQ, unsigned int FLAGS)
5148 CRQ: The certificate to be imported
5150 FLAGS: should be zero
5152 This function will import the given public key to the abstract
5153 'gnutls_pubkey_t' structure.
5155 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5156 otherwise a negative error value.
5160 gnutls_pubkey_import_x509_raw
5161 -----------------------------
5163 -- Function: int gnutls_pubkey_import_x509_raw (gnutls_pubkey_t PKEY,
5164 const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT,
5166 PKEY: The public key
5168 DATA: The public key data to be imported
5170 FORMAT: The format of the public key
5172 FLAGS: should be zero
5174 This function will import the given public key to the abstract
5175 'gnutls_pubkey_t' structure.
5177 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5178 otherwise a negative error value.
5185 -- Function: int gnutls_pubkey_init (gnutls_pubkey_t * KEY)
5186 KEY: The structure to be initialized
5188 This function will initialize an public key structure.
5190 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5191 otherwise a negative error value.
5198 -- Function: int gnutls_pubkey_print (gnutls_pubkey_t PUBKEY,
5199 gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
5201 PUBKEY: The structure to be printed
5203 FORMAT: Indicate the format to use
5205 OUT: Newly allocated datum with (0) terminated string.
5207 This function will pretty print public key information, suitable
5208 for display to a human.
5210 Only 'GNUTLS_CRT_PRINT_FULL' and 'GNUTLS_CRT_PRINT_FULL_NUMBERS'
5213 The output 'out' needs to be deallocated using 'gnutls_free()' .
5215 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5216 otherwise a negative error value.
5220 gnutls_pubkey_set_key_usage
5221 ---------------------------
5223 -- Function: int gnutls_pubkey_set_key_usage (gnutls_pubkey_t KEY,
5225 KEY: a certificate of type 'gnutls_x509_crt_t'
5227 USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
5229 This function will set the key usage flags of the public key. This
5230 is only useful if the key is to be exported to a certificate or
5231 certificate request.
5233 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5234 otherwise a negative error value.
5238 gnutls_pubkey_set_pin_function
5239 ------------------------------
5241 -- Function: void gnutls_pubkey_set_pin_function (gnutls_pubkey_t KEY,
5242 gnutls_pin_callback_t FN, void * USERDATA)
5243 KEY: A key of type 'gnutls_pubkey_t'
5247 USERDATA: data associated with the callback
5249 This function will set a callback function to be used when required
5250 to access the object. This function overrides any other global PIN
5253 Note that this function must be called right after initialization
5258 gnutls_pubkey_verify_data
5259 -------------------------
5261 -- Function: int gnutls_pubkey_verify_data (gnutls_pubkey_t PUBKEY,
5262 unsigned int FLAGS, const gnutls_datum_t * DATA, const
5263 gnutls_datum_t * SIGNATURE)
5264 PUBKEY: Holds the public key
5266 FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5268 DATA: holds the signed data
5270 SIGNATURE: contains the signature
5272 This function will verify the given signed data, using the
5273 parameters from the certificate.
5275 Deprecated. This function cannot be easily used securely. Use
5276 'gnutls_pubkey_verify_data2()' instead.
5278 *Returns:* In case of a verification failure
5279 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5284 gnutls_pubkey_verify_data2
5285 --------------------------
5287 -- Function: int gnutls_pubkey_verify_data2 (gnutls_pubkey_t PUBKEY,
5288 gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const
5289 gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE)
5290 PUBKEY: Holds the public key
5292 ALGO: The signature algorithm used
5294 FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5296 DATA: holds the signed data
5298 SIGNATURE: contains the signature
5300 This function will verify the given signed data, using the
5301 parameters from the certificate.
5303 *Returns:* In case of a verification failure
5304 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5309 gnutls_pubkey_verify_hash
5310 -------------------------
5312 -- Function: int gnutls_pubkey_verify_hash (gnutls_pubkey_t KEY,
5313 unsigned int FLAGS, const gnutls_datum_t * HASH, const
5314 gnutls_datum_t * SIGNATURE)
5315 KEY: Holds the public key
5317 FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5319 HASH: holds the hash digest to be verified
5321 SIGNATURE: contains the signature
5323 This function will verify the given signed digest, using the
5324 parameters from the public key.
5326 Deprecated. This function cannot be easily used securely. Use
5327 'gnutls_pubkey_verify_hash2()' instead.
5329 *Returns:* In case of a verification failure
5330 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5335 gnutls_pubkey_verify_hash2
5336 --------------------------
5338 -- Function: int gnutls_pubkey_verify_hash2 (gnutls_pubkey_t KEY,
5339 gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const
5340 gnutls_datum_t * HASH, const gnutls_datum_t * SIGNATURE)
5341 KEY: Holds the public key
5343 ALGO: The signature algorithm used
5345 FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5347 HASH: holds the hash digest to be verified
5349 SIGNATURE: contains the signature
5351 This function will verify the given signed digest, using the
5352 parameters from the public key. Note that unlike
5353 'gnutls_privkey_sign_hash()' , this function accepts a signature
5354 algorithm instead of a digest algorithm. You can use
5355 'gnutls_pk_to_sign()' to get the appropriate value.
5357 *Returns:* In case of a verification failure
5358 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5363 gnutls_pubkey_verify_params
5364 ---------------------------
5366 -- Function: int gnutls_pubkey_verify_params (gnutls_pubkey_t KEY)
5367 KEY: should contain a 'gnutls_pubkey_t' structure
5369 This function will verify the private key parameters.
5371 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5372 otherwise a negative error value.
5376 gnutls_x509_crl_privkey_sign
5377 ----------------------------
5379 -- Function: int gnutls_x509_crl_privkey_sign (gnutls_x509_crl_t CRL,
5380 gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY,
5381 gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
5382 CRL: should contain a gnutls_x509_crl_t structure
5384 ISSUER: is the certificate of the certificate issuer
5386 ISSUER_KEY: holds the issuer's private key
5388 DIG: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice
5389 unless you know what you're doing.
5393 This function will sign the CRL with the issuer's private key, and
5394 will copy the issuer's information into the CRL.
5396 This must be the last step in a certificate CRL since all the
5397 previously set parameters are now signed.
5399 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5400 otherwise a negative error value.
5404 gnutls_x509_crq_privkey_sign
5405 ----------------------------
5407 -- Function: int gnutls_x509_crq_privkey_sign (gnutls_x509_crq_t CRQ,
5408 gnutls_privkey_t KEY, gnutls_digest_algorithm_t DIG, unsigned
5410 CRQ: should contain a 'gnutls_x509_crq_t' structure
5412 KEY: holds a private key
5414 DIG: The message digest to use, i.e., 'GNUTLS_DIG_SHA1'
5418 This function will sign the certificate request with a private key.
5419 This must be the same key as the one used in
5420 'gnutls_x509_crt_set_key()' since a certificate request is self
5423 This must be the last step in a certificate request generation
5424 since all the previously set parameters are now signed.
5426 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
5427 error code. 'GNUTLS_E_ASN1_VALUE_NOT_FOUND' is returned if you
5428 didn't set all information in the certificate request (e.g., the
5429 version using 'gnutls_x509_crq_set_version()' ).
5433 gnutls_x509_crq_set_pubkey
5434 --------------------------
5436 -- Function: int gnutls_x509_crq_set_pubkey (gnutls_x509_crq_t CRQ,
5437 gnutls_pubkey_t KEY)
5438 CRQ: should contain a 'gnutls_x509_crq_t' structure
5440 KEY: holds a public key
5442 This function will set the public parameters from the given public
5445 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5446 otherwise a negative error value.
5450 gnutls_x509_crt_privkey_sign
5451 ----------------------------
5453 -- Function: int gnutls_x509_crt_privkey_sign (gnutls_x509_crt_t CRT,
5454 gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY,
5455 gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
5456 CRT: a certificate of type 'gnutls_x509_crt_t'
5458 ISSUER: is the certificate of the certificate issuer
5460 ISSUER_KEY: holds the issuer's private key
5462 DIG: The message digest to use, 'GNUTLS_DIG_SHA1' is a safe choice
5466 This function will sign the certificate with the issuer's private
5467 key, and will copy the issuer's information into the certificate.
5469 This must be the last step in a certificate generation since all
5470 the previously set parameters are now signed.
5472 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5473 otherwise a negative error value.
5475 gnutls_x509_crt_set_pubkey
5476 --------------------------
5478 -- Function: int gnutls_x509_crt_set_pubkey (gnutls_x509_crt_t CRT,
5479 gnutls_pubkey_t KEY)
5480 CRT: should contain a 'gnutls_x509_crt_t' structure
5482 KEY: holds a public key
5484 This function will set the public parameters from the given public
5487 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5488 otherwise a negative error value.