Revert "Imported Upstream version 3.4.11"
[platform/upstream/gnutls.git] / doc / gnutls.info-4
1 This is gnutls.info, produced by makeinfo version 5.2 from gnutls.texi.
2
3 This manual is last updated 5 April 2014 for version 3.3.5 of GnuTLS.
4
5 Copyright (C) 2001-2013 Free Software Foundation, Inc.\\ Copyright (C)
6 2001-2013 Nikos Mavrogiannopoulos
7
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
15 START-INFO-DIR-ENTRY
16 * GnuTLS: (gnutls).             GNU Transport Layer Security Library.
17 END-INFO-DIR-ENTRY
18
19 INFO-DIR-SECTION System Administration
20 START-INFO-DIR-ENTRY
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.
27 END-INFO-DIR-ENTRY
28
29 \1f
30 File: gnutls.info,  Node: OCSP API,  Next: OpenPGP API,  Prev: X509 certificate API,  Up: API reference
31
32 E.4 OCSP API
33 ============
34
35 The following functions are for OCSP certificate status checking.  Their
36 prototypes lie in 'gnutls/ocsp.h'.
37
38 gnutls_ocsp_req_add_cert
39 ------------------------
40
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
45
46      DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
47
48      ISSUER: issuer of 'subject' certificate
49
50      CERT: certificate to request status for
51
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' .
58
59      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
60      otherwise a negative error code is returned.
61
62 gnutls_ocsp_req_add_cert_id
63 ---------------------------
64
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
70
71      DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
72
73      ISSUER_NAME_HASH: hash of issuer's DN
74
75      ISSUER_KEY_HASH: hash of issuer's public key
76
77      SERIAL_NUMBER: serial number of certificate to check
78
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' .
83
84      The information needed corresponds to the CertID structure:
85
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>
91
92      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
93      otherwise a negative error code is returned.
94
95 gnutls_ocsp_req_deinit
96 ----------------------
97
98  -- Function: void gnutls_ocsp_req_deinit (gnutls_ocsp_req_t REQ)
99      REQ: The structure to be deinitialized
100
101      This function will deinitialize a OCSP request structure.
102
103 gnutls_ocsp_req_export
104 ----------------------
105
106  -- Function: int gnutls_ocsp_req_export (gnutls_ocsp_req_t REQ,
107           gnutls_datum_t * DATA)
108      REQ: Holds the OCSP request
109
110      DATA: newly allocate buffer holding DER encoded OCSP request
111
112      This function will export the OCSP request to DER format.
113
114      *Returns:* In case of failure a negative error code will be
115      returned, and 0 on success.
116
117 gnutls_ocsp_req_get_cert_id
118 ---------------------------
119
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
125
126      INDX: Specifies which extension OID to get.  Use (0) to get the
127      first one.
128
129      DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
130      algorithm
131
132      ISSUER_NAME_HASH: output buffer with hash of issuer's DN
133
134      ISSUER_KEY_HASH: output buffer with hash of issuer's public key
135
136      SERIAL_NUMBER: output buffer with serial number of certificate to
137      check
138
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:
142
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>
148
149      Each of the pointers to output variables may be NULL to indicate
150      that the caller is not interested in that value.
151
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'
155      will be returned.
156
157 gnutls_ocsp_req_get_extension
158 -----------------------------
159
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
164
165      INDX: Specifies which extension OID to get.  Use (0) to get the
166      first one.
167
168      OID: will hold newly allocated buffer with OID of extension, may be
169      NULL
170
171      CRITICAL: output variable with critical flag, may be NULL.
172
173      DATA: will hold newly allocated buffer with extension data, may be
174      NULL
175
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.
182
183      The caller needs to deallocate memory by calling 'gnutls_free()' on
184      'oid' ->data and 'data' ->data.
185
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.
190
191 gnutls_ocsp_req_get_nonce
192 -------------------------
193
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
197
198      CRITICAL: whether nonce extension is marked critical, or NULL
199
200      NONCE: will hold newly allocated buffer with nonce data
201
202      This function will return the OCSP request nonce extension data.
203
204      The caller needs to deallocate memory by calling 'gnutls_free()' on
205      'nonce' ->data.
206
207      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
208      otherwise a negative error code is returned.
209
210 gnutls_ocsp_req_get_version
211 ---------------------------
212
213  -- Function: int gnutls_ocsp_req_get_version (gnutls_ocsp_req_t REQ)
214      REQ: should contain a 'gnutls_ocsp_req_t' structure
215
216      This function will return the version of the OCSP request.
217      Typically this is always 1 indicating version 1.
218
219      *Returns:* version of OCSP request, or a negative error code on
220      error.
221
222 gnutls_ocsp_req_import
223 ----------------------
224
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.
228
229      DATA: DER encoded OCSP request.
230
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
233      in 'req' .
234
235      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
236      otherwise a negative error value.
237
238 gnutls_ocsp_req_init
239 --------------------
240
241  -- Function: int gnutls_ocsp_req_init (gnutls_ocsp_req_t * REQ)
242      REQ: The structure to be initialized
243
244      This function will initialize an OCSP request structure.
245
246      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
247      otherwise a negative error value.
248
249 gnutls_ocsp_req_print
250 ---------------------
251
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
255
256      FORMAT: Indicate the format to use
257
258      OUT: Newly allocated datum with (0) terminated string.
259
260      This function will pretty print a OCSP request, suitable for
261      display to a human.
262
263      If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
264      request will be output, on multiple lines.
265
266      The output 'out' ->data needs to be deallocate using
267      'gnutls_free()' .
268
269      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
270      otherwise a negative error value.
271
272 gnutls_ocsp_req_randomize_nonce
273 -------------------------------
274
275  -- Function: int gnutls_ocsp_req_randomize_nonce (gnutls_ocsp_req_t
276           REQ)
277      REQ: should contain a 'gnutls_ocsp_req_t' structure
278
279      This function will add or update an nonce extension to the OCSP
280      request with a newly generated random value.
281
282      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
283      otherwise a negative error code is returned.
284
285 gnutls_ocsp_req_set_extension
286 -----------------------------
287
288  -- Function: int gnutls_ocsp_req_set_extension (gnutls_ocsp_req_t REQ,
289           const char * OID, unsigned int CRITICAL, const gnutls_datum_t
290           * DATA)
291      REQ: should contain a 'gnutls_ocsp_req_t' structure
292
293      OID: buffer with OID of extension as a string.
294
295      CRITICAL: critical flag, normally false.
296
297      DATA: the extension data
298
299      This function will add an extension to the OCSP request.  Calling
300      this function multiple times for the same OID will overwrite values
301      from earlier calls.
302
303      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
304      otherwise a negative error code is returned.
305
306 gnutls_ocsp_req_set_nonce
307 -------------------------
308
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
312
313      CRITICAL: critical flag, normally false.
314
315      NONCE: the nonce data
316
317      This function will add an nonce extension to the OCSP request.
318      Calling this function multiple times will overwrite values from
319      earlier calls.
320
321      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
322      otherwise a negative error code is returned.
323
324 gnutls_ocsp_resp_check_crt
325 --------------------------
326
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
330
331      INDX: Specifies response number to get.  Use (0) to get the first
332      one.
333
334      CRT: The certificate to check
335
336      This function will check whether the OCSP response is about the
337      provided certificate.
338
339      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
340      otherwise a negative error code is returned.
341
342      *Since:* 3.1.3
343
344 gnutls_ocsp_resp_deinit
345 -----------------------
346
347  -- Function: void gnutls_ocsp_resp_deinit (gnutls_ocsp_resp_t RESP)
348      RESP: The structure to be deinitialized
349
350      This function will deinitialize a OCSP response structure.
351
352 gnutls_ocsp_resp_export
353 -----------------------
354
355  -- Function: int gnutls_ocsp_resp_export (gnutls_ocsp_resp_t RESP,
356           gnutls_datum_t * DATA)
357      RESP: Holds the OCSP response
358
359      DATA: newly allocate buffer holding DER encoded OCSP response
360
361      This function will export the OCSP response to DER format.
362
363      *Returns:* In case of failure a negative error code will be
364      returned, and 0 on success.
365
366 gnutls_ocsp_resp_get_certs
367 --------------------------
368
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
372
373      CERTS: newly allocated array with 'gnutls_x509_crt_t' certificates
374
375      NCERTS: output variable with number of allocated certs.
376
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.
380
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
383      'gnutls_free()' .
384
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.
389
390      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
391      otherwise a negative error value.
392
393 gnutls_ocsp_resp_get_extension
394 ------------------------------
395
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
400
401      INDX: Specifies which extension OID to get.  Use (0) to get the
402      first one.
403
404      OID: will hold newly allocated buffer with OID of extension, may be
405      NULL
406
407      CRITICAL: output variable with critical flag, may be NULL.
408
409      DATA: will hold newly allocated buffer with extension data, may be
410      NULL
411
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.
418
419      The caller needs to deallocate memory by calling 'gnutls_free()' on
420      'oid' ->data and 'data' ->data.
421
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.
426
427 gnutls_ocsp_resp_get_nonce
428 --------------------------
429
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
433
434      CRITICAL: whether nonce extension is marked critical
435
436      NONCE: will hold newly allocated buffer with nonce data
437
438      This function will return the Basic OCSP Response nonce extension
439      data.
440
441      The caller needs to deallocate memory by calling 'gnutls_free()' on
442      'nonce' ->data.
443
444      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
445      otherwise a negative error code is returned.
446
447 gnutls_ocsp_resp_get_produced
448 -----------------------------
449
450  -- Function: time_t gnutls_ocsp_resp_get_produced (gnutls_ocsp_resp_t
451           RESP)
452      RESP: should contain a 'gnutls_ocsp_resp_t' structure
453
454      This function will return the time when the OCSP response was
455      signed.
456
457      *Returns:* signing time, or (time_t)-1 on error.
458
459 gnutls_ocsp_resp_get_responder
460 ------------------------------
461
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
465
466      DN: newly allocated buffer with name
467
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.
472
473      The caller needs to deallocate memory by calling 'gnutls_free()' on
474      'dn' ->data.
475
476      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
477      otherwise a negative error code is returned.
478
479 gnutls_ocsp_resp_get_response
480 -----------------------------
481
482  -- Function: int gnutls_ocsp_resp_get_response (gnutls_ocsp_resp_t
483           RESP, gnutls_datum_t * RESPONSE_TYPE_OID, gnutls_datum_t *
484           RESPONSE)
485      RESP: should contain a 'gnutls_ocsp_resp_t' structure
486
487      RESPONSE_TYPE_OID: newly allocated output buffer with response type
488      OID
489
490      RESPONSE: newly allocated output buffer with DER encoded response
491
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.
497
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.
502
503      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
504      otherwise a negative error value.
505
506 gnutls_ocsp_resp_get_signature
507 ------------------------------
508
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
512
513      SIG: newly allocated output buffer with signature data
514
515      This function will extract the signature field of a OCSP response.
516
517      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
518      otherwise a negative error value.
519
520 gnutls_ocsp_resp_get_signature_algorithm
521 ----------------------------------------
522
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
526
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.
530
531      *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
532      code on error.
533
534 gnutls_ocsp_resp_get_single
535 ---------------------------
536
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
544
545      INDX: Specifies response number to get.  Use (0) to get the first
546      one.
547
548      DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
549      algorithm
550
551      ISSUER_NAME_HASH: output buffer with hash of issuer's DN
552
553      ISSUER_KEY_HASH: output buffer with hash of issuer's public key
554
555      SERIAL_NUMBER: output buffer with serial number of certificate to
556      check
557
558      CERT_STATUS: a certificate status, a 'gnutls_ocsp_cert_status_t'
559      enum.
560
561      THIS_UPDATE: time at which the status is known to be correct.
562
563      NEXT_UPDATE: when newer information will be available, or
564      (time_t)-1 if unspecified
565
566      REVOCATION_TIME: when 'cert_status' is 'GNUTLS_OCSP_CERT_REVOKED' ,
567      holds time of revocation.
568
569      REVOCATION_REASON: revocation reason, a 'gnutls_x509_crl_reason_t'
570      enum.
571
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.
576
577      Each of the pointers to output variables may be NULL to indicate
578      that the caller is not interested in that value.
579
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'
583      will be returned.
584
585 gnutls_ocsp_resp_get_status
586 ---------------------------
587
588  -- Function: int gnutls_ocsp_resp_get_status (gnutls_ocsp_resp_t RESP)
589      RESP: should contain a 'gnutls_ocsp_resp_t' structure
590
591      This function will return the status of a OCSP response, an
592      'gnutls_ocsp_resp_status_t' enumeration.
593
594      *Returns:* status of OCSP request as a 'gnutls_ocsp_resp_status_t'
595      , or a negative error code on error.
596
597 gnutls_ocsp_resp_get_version
598 ----------------------------
599
600  -- Function: int gnutls_ocsp_resp_get_version (gnutls_ocsp_resp_t RESP)
601      RESP: should contain a 'gnutls_ocsp_resp_t' structure
602
603      This function will return the version of the Basic OCSP Response.
604      Typically this is always 1 indicating version 1.
605
606      *Returns:* version of Basic OCSP response, or a negative error code
607      on error.
608
609 gnutls_ocsp_resp_import
610 -----------------------
611
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.
615
616      DATA: DER encoded OCSP response.
617
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' .
621
622      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
623      otherwise a negative error value.
624
625 gnutls_ocsp_resp_init
626 ---------------------
627
628  -- Function: int gnutls_ocsp_resp_init (gnutls_ocsp_resp_t * RESP)
629      RESP: The structure to be initialized
630
631      This function will initialize an OCSP response structure.
632
633      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
634      otherwise a negative error value.
635
636 gnutls_ocsp_resp_print
637 ----------------------
638
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
642
643      FORMAT: Indicate the format to use
644
645      OUT: Newly allocated datum with (0) terminated string.
646
647      This function will pretty print a OCSP response, suitable for
648      display to a human.
649
650      If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
651      response will be output, on multiple lines.
652
653      The output 'out' ->data needs to be deallocate using
654      'gnutls_free()' .
655
656      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
657      otherwise a negative error value.
658
659 gnutls_ocsp_resp_verify
660 -----------------------
661
662  -- Function: int gnutls_ocsp_resp_verify (gnutls_ocsp_resp_t RESP,
663           gnutls_x509_trust_list_t TRUSTLIST, unsigned int * VERIFY,
664           unsigned int FLAGS)
665      RESP: should contain a 'gnutls_ocsp_resp_t' structure
666
667      TRUSTLIST: trust anchors as a 'gnutls_x509_trust_list_t' structure
668
669      VERIFY: output variable with verification status, an
670      'gnutls_ocsp_cert_status_t'
671
672      FLAGS: verification flags, 0 for now.
673
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
681      set.
682
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' .
687
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.
691
692      The 'flags' variable should be 0 for now.
693
694      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
695      otherwise a negative error value.
696
697 gnutls_ocsp_resp_verify_direct
698 ------------------------------
699
700  -- Function: int gnutls_ocsp_resp_verify_direct (gnutls_ocsp_resp_t
701           RESP, gnutls_x509_crt_t ISSUER, unsigned int * VERIFY,
702           unsigned int FLAGS)
703      RESP: should contain a 'gnutls_ocsp_resp_t' structure
704
705      ISSUER: certificate believed to have signed the response
706
707      VERIFY: output variable with verification status, an
708      'gnutls_ocsp_cert_status_t'
709
710      FLAGS: verification flags, 0 for now.
711
712      Verify signature of the Basic OCSP Response against the public key
713      in the 'issuer' certificate.
714
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' .
719
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.
723
724      The 'flags' variable should be 0 for now.
725
726      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
727      otherwise a negative error value.
728
729 \1f
730 File: gnutls.info,  Node: OpenPGP API,  Next: PKCS 12 API,  Prev: OCSP API,  Up: API reference
731
732 E.5 OpenPGP API
733 ===============
734
735 The following functions are to be used for OpenPGP certificate handling.
736 Their prototypes lie in 'gnutls/openpgp.h'.
737
738 gnutls_certificate_set_openpgp_key
739 ----------------------------------
740
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.
745
746      CRT: contains an openpgp public key
747
748      PKEY: is an openpgp private key
749
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
753      the server).
754
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
758      key will be used.
759
760      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
761      otherwise a negative error code is returned.
762
763 gnutls_certificate_set_openpgp_key_file
764 ---------------------------------------
765
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.
770
771      CERTFILE: the file that contains the public key.
772
773      KEYFILE: the file that contains the secret key.
774
775      FORMAT: the format of the keys
776
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.
780
781      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
782      otherwise a negative error value.
783
784 gnutls_certificate_set_openpgp_key_file2
785 ----------------------------------------
786
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.
792
793      CERTFILE: the file that contains the public key.
794
795      KEYFILE: the file that contains the secret key.
796
797      SUBKEY_ID: a hex encoded subkey id
798
799      FORMAT: the format of the keys
800
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.
804
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.
808
809      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
810      otherwise a negative error value.
811
812      *Since:* 2.4.0
813
814 gnutls_certificate_set_openpgp_key_mem
815 --------------------------------------
816
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
820           FORMAT)
821      RES: the destination context to save the data.
822
823      CERT: the datum that contains the public key.
824
825      KEY: the datum that contains the secret key.
826
827      FORMAT: the format of the keys
828
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.
832
833      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
834      otherwise a negative error value.
835
836 gnutls_certificate_set_openpgp_key_mem2
837 ---------------------------------------
838
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.
844
845      CERT: the datum that contains the public key.
846
847      KEY: the datum that contains the secret key.
848
849      SUBKEY_ID: a hex encoded subkey id
850
851      FORMAT: the format of the keys
852
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.
856
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.
860
861      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
862      otherwise a negative error value.
863
864      *Since:* 2.4.0
865
866 gnutls_certificate_set_openpgp_keyring_file
867 -------------------------------------------
868
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
873
874      FILE: filename of the keyring.
875
876      FORMAT: format of keyring.
877
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.
882
883      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
884      otherwise a negative error value.
885
886 gnutls_certificate_set_openpgp_keyring_mem
887 ------------------------------------------
888
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
893
894      DATA: buffer with keyring data.
895
896      DLEN: length of data buffer.
897
898      FORMAT: the format of the keyring
899
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.
904
905      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
906      otherwise a negative error value.
907
908 gnutls_openpgp_crt_check_hostname
909 ---------------------------------
910
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
914
915      HOSTNAME: A null terminated string that contains a DNS name
916
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.
920
921      *Returns:* non-zero for a successful match, and zero on failure.
922
923 gnutls_openpgp_crt_check_hostname2
924 ----------------------------------
925
926  -- Function: int gnutls_openpgp_crt_check_hostname2
927           (gnutls_openpgp_crt_t KEY, const char * HOSTNAME, unsigned
928           FLAGS)
929      KEY: should contain a 'gnutls_openpgp_crt_t' structure
930
931      HOSTNAME: A null terminated string that contains a DNS name
932
933      FLAGS: gnutls_certificate_verify_flags
934
935      This function will check if the given key's owner matches the given
936      hostname.
937
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.
942
943      *Returns:* non-zero for a successful match, and zero on failure.
944
945 gnutls_openpgp_crt_deinit
946 -------------------------
947
948  -- Function: void gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t KEY)
949      KEY: The structure to be initialized
950
951      This function will deinitialize a key structure.
952
953 gnutls_openpgp_crt_export
954 -------------------------
955
956  -- Function: int gnutls_openpgp_crt_export (gnutls_openpgp_crt_t KEY,
957           gnutls_openpgp_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
958           OUTPUT_DATA_SIZE)
959      KEY: Holds the key.
960
961      FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
962
963      OUTPUT_DATA: will contain the raw or base64 encoded key
964
965      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
966      replaced by the actual size of parameters)
967
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.
971
972      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
973
974 gnutls_openpgp_crt_export2
975 --------------------------
976
977  -- Function: int gnutls_openpgp_crt_export2 (gnutls_openpgp_crt_t KEY,
978           gnutls_openpgp_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
979      KEY: Holds the key.
980
981      FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
982
983      OUT: will contain the raw or base64 encoded key
984
985      This function will convert the given key to RAW or Base64 format.
986      The output buffer is allocated using 'gnutls_malloc()' .
987
988      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
989
990      *Since:* 3.1.3
991
992 gnutls_openpgp_crt_get_auth_subkey
993 ----------------------------------
994
995  -- Function: int gnutls_openpgp_crt_get_auth_subkey
996           (gnutls_openpgp_crt_t CRT, gnutls_openpgp_keyid_t KEYID,
997           unsigned int FLAG)
998      CRT: the structure that contains the OpenPGP public key.
999
1000      KEYID: the struct to save the keyid.
1001
1002      FLAG: Non-zero indicates that a valid subkey is always returned.
1003
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.
1008
1009      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1010
1011 gnutls_openpgp_crt_get_creation_time
1012 ------------------------------------
1013
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.
1017
1018      Get key creation time.
1019
1020      *Returns:* the timestamp when the OpenPGP key was created.
1021
1022 gnutls_openpgp_crt_get_expiration_time
1023 --------------------------------------
1024
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.
1028
1029      Get key expiration time.  A value of '0' means that the key doesn't
1030      expire at all.
1031
1032      *Returns:* the time when the OpenPGP key expires.
1033
1034 gnutls_openpgp_crt_get_fingerprint
1035 ----------------------------------
1036
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.
1040
1041      FPR: the buffer to save the fingerprint, must hold at least 20
1042      bytes.
1043
1044      FPRLEN: the integer to save the length of the fingerprint.
1045
1046      Get key fingerprint.  Depending on the algorithm, the fingerprint
1047      can be 16 or 20 bytes.
1048
1049      *Returns:* On success, 0 is returned.  Otherwise, an error code.
1050
1051 gnutls_openpgp_crt_get_key_id
1052 -----------------------------
1053
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.
1057
1058      KEYID: the buffer to save the keyid.
1059
1060      Get key id string.
1061
1062      *Returns:* the 64-bit keyID of the OpenPGP key.
1063
1064      *Since:* 2.4.0
1065
1066 gnutls_openpgp_crt_get_key_usage
1067 --------------------------------
1068
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
1072
1073      KEY_USAGE: where the key usage bits will be stored
1074
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' .
1078
1079      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1080
1081 gnutls_openpgp_crt_get_name
1082 ---------------------------
1083
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.
1087
1088      IDX: the index of the ID to extract
1089
1090      BUF: a pointer to a structure to hold the name, may be 'NULL' to
1091      only get the 'sizeof_buf' .
1092
1093      SIZEOF_BUF: holds the maximum size of 'buf' , on return hold the
1094      actual/required size of 'buf' .
1095
1096      Extracts the userID from the parsed OpenPGP key.
1097
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
1100      error code.
1101
1102 gnutls_openpgp_crt_get_pk_algorithm
1103 -----------------------------------
1104
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
1108
1109      BITS: if bits is non null it will hold the size of the parameters'
1110      in bits
1111
1112      This function will return the public key algorithm of an OpenPGP
1113      certificate.
1114
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.
1118
1119      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1120      success, or GNUTLS_PK_UNKNOWN on error.
1121
1122 gnutls_openpgp_crt_get_pk_dsa_raw
1123 ---------------------------------
1124
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
1129
1130      P: will hold the p
1131
1132      Q: will hold the q
1133
1134      G: will hold the g
1135
1136      Y: will hold the y
1137
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.
1141
1142      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1143      error code.
1144
1145      *Since:* 2.4.0
1146
1147 gnutls_openpgp_crt_get_pk_rsa_raw
1148 ---------------------------------
1149
1150  -- Function: int gnutls_openpgp_crt_get_pk_rsa_raw
1151           (gnutls_openpgp_crt_t CRT, gnutls_datum_t * M, gnutls_datum_t
1152           * E)
1153      CRT: Holds the certificate
1154
1155      M: will hold the modulus
1156
1157      E: will hold the public exponent
1158
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.
1162
1163      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1164      error code.
1165
1166      *Since:* 2.4.0
1167
1168 gnutls_openpgp_crt_get_preferred_key_id
1169 ---------------------------------------
1170
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.
1174
1175      KEYID: the struct to save the keyid.
1176
1177      Get preferred key id.  If it hasn't been set it returns
1178      'GNUTLS_E_INVALID_REQUEST' .
1179
1180      *Returns:* the 64-bit preferred keyID of the OpenPGP key.
1181
1182 gnutls_openpgp_crt_get_revoked_status
1183 -------------------------------------
1184
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.
1188
1189      Get revocation status of key.
1190
1191      *Returns:* true (1) if the key has been revoked, or false (0) if it
1192      has not.
1193
1194      *Since:* 2.4.0
1195
1196 gnutls_openpgp_crt_get_subkey_count
1197 -----------------------------------
1198
1199  -- Function: int gnutls_openpgp_crt_get_subkey_count
1200           (gnutls_openpgp_crt_t KEY)
1201      KEY: is an OpenPGP key
1202
1203      This function will return the number of subkeys present in the
1204      given OpenPGP certificate.
1205
1206      *Returns:* the number of subkeys, or a negative error code on
1207      error.
1208
1209      *Since:* 2.4.0
1210
1211 gnutls_openpgp_crt_get_subkey_creation_time
1212 -------------------------------------------
1213
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.
1217
1218      IDX: the subkey index
1219
1220      Get subkey creation time.
1221
1222      *Returns:* the timestamp when the OpenPGP sub-key was created.
1223
1224      *Since:* 2.4.0
1225
1226 gnutls_openpgp_crt_get_subkey_expiration_time
1227 ---------------------------------------------
1228
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.
1232
1233      IDX: the subkey index
1234
1235      Get subkey expiration time.  A value of '0' means that the key
1236      doesn't expire at all.
1237
1238      *Returns:* the time when the OpenPGP key expires.
1239
1240      *Since:* 2.4.0
1241
1242 gnutls_openpgp_crt_get_subkey_fingerprint
1243 -----------------------------------------
1244
1245  -- Function: int gnutls_openpgp_crt_get_subkey_fingerprint
1246           (gnutls_openpgp_crt_t KEY, unsigned int IDX, void * FPR,
1247           size_t * FPRLEN)
1248      KEY: the raw data that contains the OpenPGP public key.
1249
1250      IDX: the subkey index
1251
1252      FPR: the buffer to save the fingerprint, must hold at least 20
1253      bytes.
1254
1255      FPRLEN: the integer to save the length of the fingerprint.
1256
1257      Get key fingerprint of a subkey.  Depending on the algorithm, the
1258      fingerprint can be 16 or 20 bytes.
1259
1260      *Returns:* On success, 0 is returned.  Otherwise, an error code.
1261
1262      *Since:* 2.4.0
1263
1264 gnutls_openpgp_crt_get_subkey_id
1265 --------------------------------
1266
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.
1270
1271      IDX: the subkey index
1272
1273      KEYID: the buffer to save the keyid.
1274
1275      Get the subkey's key-id.
1276
1277      *Returns:* the 64-bit keyID of the OpenPGP key.
1278
1279 gnutls_openpgp_crt_get_subkey_idx
1280 ---------------------------------
1281
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.
1285
1286      KEYID: the keyid.
1287
1288      Get subkey's index.
1289
1290      *Returns:* the index of the subkey or a negative error value.
1291
1292      *Since:* 2.4.0
1293
1294 gnutls_openpgp_crt_get_subkey_pk_algorithm
1295 ------------------------------------------
1296
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 *
1300           BITS)
1301      KEY: is an OpenPGP key
1302
1303      IDX: is the subkey index
1304
1305      BITS: if bits is non null it will hold the size of the parameters'
1306      in bits
1307
1308      This function will return the public key algorithm of a subkey of
1309      an OpenPGP certificate.
1310
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.
1314
1315      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1316      success, or GNUTLS_PK_UNKNOWN on error.
1317
1318      *Since:* 2.4.0
1319
1320 gnutls_openpgp_crt_get_subkey_pk_dsa_raw
1321 ----------------------------------------
1322
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
1327
1328      IDX: Is the subkey index
1329
1330      P: will hold the p
1331
1332      Q: will hold the q
1333
1334      G: will hold the g
1335
1336      Y: will hold the y
1337
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.
1341
1342      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1343      error code.
1344
1345      *Since:* 2.4.0
1346
1347 gnutls_openpgp_crt_get_subkey_pk_rsa_raw
1348 ----------------------------------------
1349
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
1354
1355      IDX: Is the subkey index
1356
1357      M: will hold the modulus
1358
1359      E: will hold the public exponent
1360
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.
1364
1365      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1366      error code.
1367
1368      *Since:* 2.4.0
1369
1370 gnutls_openpgp_crt_get_subkey_revoked_status
1371 --------------------------------------------
1372
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.
1376
1377      IDX: is the subkey index
1378
1379      Get subkey revocation status.  A negative error code indicates an
1380      error.
1381
1382      *Returns:* true (1) if the key has been revoked, or false (0) if it
1383      has not.
1384
1385      *Since:* 2.4.0
1386
1387 gnutls_openpgp_crt_get_subkey_usage
1388 -----------------------------------
1389
1390  -- Function: int gnutls_openpgp_crt_get_subkey_usage
1391           (gnutls_openpgp_crt_t KEY, unsigned int IDX, unsigned int *
1392           KEY_USAGE)
1393      KEY: should contain a gnutls_openpgp_crt_t structure
1394
1395      IDX: the subkey index
1396
1397      KEY_USAGE: where the key usage bits will be stored
1398
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' .
1402
1403      A negative error code may be returned in case of parsing error.
1404
1405      *Returns:* key usage value.
1406
1407      *Since:* 2.4.0
1408
1409 gnutls_openpgp_crt_get_version
1410 ------------------------------
1411
1412  -- Function: int gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t
1413           KEY)
1414      KEY: the structure that contains the OpenPGP public key.
1415
1416      Extract the version of the OpenPGP key.
1417
1418      *Returns:* the version number is returned, or a negative error code
1419      on errors.
1420
1421 gnutls_openpgp_crt_import
1422 -------------------------
1423
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.
1427
1428      DATA: The RAW or BASE64 encoded key.
1429
1430      FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1431
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
1434      stored in 'key'.
1435
1436      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1437
1438 gnutls_openpgp_crt_init
1439 -----------------------
1440
1441  -- Function: int gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * KEY)
1442      KEY: The structure to be initialized
1443
1444      This function will initialize an OpenPGP key structure.
1445
1446      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1447
1448 gnutls_openpgp_crt_print
1449 ------------------------
1450
1451  -- Function: int gnutls_openpgp_crt_print (gnutls_openpgp_crt_t CERT,
1452           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
1453           OUT)
1454      CERT: The structure to be printed
1455
1456      FORMAT: Indicate the format to use
1457
1458      OUT: Newly allocated datum with (0) terminated string.
1459
1460      This function will pretty print an OpenPGP certificate, suitable
1461      for display to a human.
1462
1463      The format should be (0) for future compatibility.
1464
1465      The output 'out' needs to be deallocate using 'gnutls_free()' .
1466
1467      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1468
1469 gnutls_openpgp_crt_set_preferred_key_id
1470 ---------------------------------------
1471
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.
1475
1476      KEYID: the selected keyid
1477
1478      This allows setting a preferred key id for the given certificate.
1479      This key will be used by functions that involve key handling.
1480
1481      If the provided 'keyid' is 'NULL' then the master key is set as
1482      preferred.
1483
1484      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1485      otherwise a negative error code is returned.
1486
1487 gnutls_openpgp_crt_verify_ring
1488 ------------------------------
1489
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.
1494
1495      KEYRING: holds the keyring to check against
1496
1497      FLAGS: unused (should be 0)
1498
1499      VERIFY: will hold the certificate verification output.
1500
1501      Verify all signatures in the key, using the given set of keys
1502      (keyring).
1503
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
1506      bitwise or'd.
1507
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
1510      application.
1511
1512      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1513
1514 gnutls_openpgp_crt_verify_self
1515 ------------------------------
1516
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.
1520
1521      FLAGS: unused (should be 0)
1522
1523      VERIFY: will hold the key verification output.
1524
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.
1528
1529      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1530
1531 gnutls_openpgp_keyring_check_id
1532 -------------------------------
1533
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
1538
1539      KEYID: will hold the keyid to check for.
1540
1541      FLAGS: unused (should be 0)
1542
1543      Check if a given key ID exists in the keyring.
1544
1545      *Returns:* 'GNUTLS_E_SUCCESS' on success (if keyid exists) and a
1546      negative error code on failure.
1547
1548 gnutls_openpgp_keyring_deinit
1549 -----------------------------
1550
1551  -- Function: void gnutls_openpgp_keyring_deinit
1552           (gnutls_openpgp_keyring_t KEYRING)
1553      KEYRING: The structure to be initialized
1554
1555      This function will deinitialize a keyring structure.
1556
1557 gnutls_openpgp_keyring_get_crt
1558 ------------------------------
1559
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.
1564
1565      IDX: the index of the certificate to export
1566
1567      CERT: An uninitialized 'gnutls_openpgp_crt_t' structure
1568
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.
1573
1574      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1575
1576 gnutls_openpgp_keyring_get_crt_count
1577 ------------------------------------
1578
1579  -- Function: int gnutls_openpgp_keyring_get_crt_count
1580           (gnutls_openpgp_keyring_t RING)
1581      RING: is an OpenPGP key ring
1582
1583      This function will return the number of OpenPGP certificates
1584      present in the given keyring.
1585
1586      *Returns:* the number of subkeys, or a negative error code on
1587      error.
1588
1589 gnutls_openpgp_keyring_import
1590 -----------------------------
1591
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.
1596
1597      DATA: The RAW or BASE64 encoded keyring.
1598
1599      FORMAT: One of 'gnutls_openpgp_keyring_fmt' elements.
1600
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'.
1604
1605      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1606
1607 gnutls_openpgp_keyring_init
1608 ---------------------------
1609
1610  -- Function: int gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t
1611           * KEYRING)
1612      KEYRING: The structure to be initialized
1613
1614      This function will initialize an keyring structure.
1615
1616      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1617
1618 gnutls_openpgp_privkey_deinit
1619 -----------------------------
1620
1621  -- Function: void gnutls_openpgp_privkey_deinit
1622           (gnutls_openpgp_privkey_t KEY)
1623      KEY: The structure to be initialized
1624
1625      This function will deinitialize a key structure.
1626
1627 gnutls_openpgp_privkey_export
1628 -----------------------------
1629
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)
1634      KEY: Holds the key.
1635
1636      FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1637
1638      PASSWORD: the password that will be used to encrypt the key.
1639      (unused for now)
1640
1641      FLAGS: (0) for future compatibility
1642
1643      OUTPUT_DATA: will contain the key base64 encoded or raw
1644
1645      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
1646      replaced by the actual size of parameters)
1647
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.
1651
1652      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1653
1654      *Since:* 2.4.0
1655
1656 gnutls_openpgp_privkey_export2
1657 ------------------------------
1658
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)
1663      KEY: Holds the key.
1664
1665      FORMAT: One of gnutls_openpgp_crt_fmt_t elements.
1666
1667      PASSWORD: the password that will be used to encrypt the key.
1668      (unused for now)
1669
1670      FLAGS: (0) for future compatibility
1671
1672      OUT: will contain the raw or based64 encoded key
1673
1674      This function will convert the given key to RAW or Base64 format.
1675      The output buffer is allocated using 'gnutls_malloc()' .
1676
1677      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
1678
1679      *Since:* 3.1.3
1680
1681 gnutls_openpgp_privkey_export_dsa_raw
1682 -------------------------------------
1683
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,
1687           gnutls_datum_t * X)
1688      PKEY: Holds the certificate
1689
1690      P: will hold the p
1691
1692      Q: will hold the q
1693
1694      G: will hold the g
1695
1696      Y: will hold the y
1697
1698      X: will hold the x
1699
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.
1703
1704      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1705      error code.
1706
1707      *Since:* 2.4.0
1708
1709 gnutls_openpgp_privkey_export_rsa_raw
1710 -------------------------------------
1711
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
1717
1718      M: will hold the modulus
1719
1720      E: will hold the public exponent
1721
1722      D: will hold the private exponent
1723
1724      P: will hold the first prime (p)
1725
1726      Q: will hold the second prime (q)
1727
1728      U: will hold the coefficient
1729
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.
1733
1734      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1735      error code.
1736
1737      *Since:* 2.4.0
1738
1739 gnutls_openpgp_privkey_export_subkey_dsa_raw
1740 --------------------------------------------
1741
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
1747
1748      IDX: Is the subkey index
1749
1750      P: will hold the p
1751
1752      Q: will hold the q
1753
1754      G: will hold the g
1755
1756      Y: will hold the y
1757
1758      X: will hold the x
1759
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.
1763
1764      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1765      error code.
1766
1767      *Since:* 2.4.0
1768
1769 gnutls_openpgp_privkey_export_subkey_rsa_raw
1770 --------------------------------------------
1771
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
1777
1778      IDX: Is the subkey index
1779
1780      M: will hold the modulus
1781
1782      E: will hold the public exponent
1783
1784      D: will hold the private exponent
1785
1786      P: will hold the first prime (p)
1787
1788      Q: will hold the second prime (q)
1789
1790      U: will hold the coefficient
1791
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.
1795
1796      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
1797      error code.
1798
1799      *Since:* 2.4.0
1800
1801 gnutls_openpgp_privkey_get_fingerprint
1802 --------------------------------------
1803
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.
1807
1808      FPR: the buffer to save the fingerprint, must hold at least 20
1809      bytes.
1810
1811      FPRLEN: the integer to save the length of the fingerprint.
1812
1813      Get the fingerprint of the OpenPGP key.  Depends on the algorithm,
1814      the fingerprint can be 16 or 20 bytes.
1815
1816      *Returns:* On success, 0 is returned, or an error code.
1817
1818      *Since:* 2.4.0
1819
1820 gnutls_openpgp_privkey_get_key_id
1821 ---------------------------------
1822
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.
1826
1827      KEYID: the buffer to save the keyid.
1828
1829      Get key-id.
1830
1831      *Returns:* the 64-bit keyID of the OpenPGP key.
1832
1833      *Since:* 2.4.0
1834
1835 gnutls_openpgp_privkey_get_pk_algorithm
1836 ---------------------------------------
1837
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
1842
1843      BITS: if bits is non null it will hold the size of the parameters'
1844      in bits
1845
1846      This function will return the public key algorithm of an OpenPGP
1847      certificate.
1848
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.
1852
1853      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
1854      success, or a negative error code on error.
1855
1856      *Since:* 2.4.0
1857
1858 gnutls_openpgp_privkey_get_preferred_key_id
1859 -------------------------------------------
1860
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.
1864
1865      KEYID: the struct to save the keyid.
1866
1867      Get the preferred key-id for the key.
1868
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' .
1871
1872 gnutls_openpgp_privkey_get_revoked_status
1873 -----------------------------------------
1874
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.
1878
1879      Get revocation status of key.
1880
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.
1883
1884      *Since:* 2.4.0
1885
1886 gnutls_openpgp_privkey_get_subkey_count
1887 ---------------------------------------
1888
1889  -- Function: int gnutls_openpgp_privkey_get_subkey_count
1890           (gnutls_openpgp_privkey_t KEY)
1891      KEY: is an OpenPGP key
1892
1893      This function will return the number of subkeys present in the
1894      given OpenPGP certificate.
1895
1896      *Returns:* the number of subkeys, or a negative error code on
1897      error.
1898
1899      *Since:* 2.4.0
1900
1901 gnutls_openpgp_privkey_get_subkey_creation_time
1902 -----------------------------------------------
1903
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.
1907
1908      IDX: the subkey index
1909
1910      Get subkey creation time.
1911
1912      *Returns:* the timestamp when the OpenPGP key was created.
1913
1914      *Since:* 2.4.0
1915
1916 gnutls_openpgp_privkey_get_subkey_expiration_time
1917 -------------------------------------------------
1918
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.
1922
1923      IDX: the subkey index
1924
1925      Get subkey expiration time.  A value of '0' means that the key
1926      doesn't expire at all.
1927
1928      *Returns:* the time when the OpenPGP key expires.
1929
1930      *Since:* 2.4.0
1931
1932 gnutls_openpgp_privkey_get_subkey_fingerprint
1933 ---------------------------------------------
1934
1935  -- Function: int gnutls_openpgp_privkey_get_subkey_fingerprint
1936           (gnutls_openpgp_privkey_t KEY, unsigned int IDX, void * FPR,
1937           size_t * FPRLEN)
1938      KEY: the raw data that contains the OpenPGP secret key.
1939
1940      IDX: the subkey index
1941
1942      FPR: the buffer to save the fingerprint, must hold at least 20
1943      bytes.
1944
1945      FPRLEN: the integer to save the length of the fingerprint.
1946
1947      Get the fingerprint of an OpenPGP subkey.  Depends on the
1948      algorithm, the fingerprint can be 16 or 20 bytes.
1949
1950      *Returns:* On success, 0 is returned, or an error code.
1951
1952      *Since:* 2.4.0
1953
1954 gnutls_openpgp_privkey_get_subkey_id
1955 ------------------------------------
1956
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.
1961
1962      IDX: the subkey index
1963
1964      KEYID: the buffer to save the keyid.
1965
1966      Get the key-id for the subkey.
1967
1968      *Returns:* the 64-bit keyID of the OpenPGP key.
1969
1970      *Since:* 2.4.0
1971
1972 gnutls_openpgp_privkey_get_subkey_idx
1973 -------------------------------------
1974
1975  -- Function: int gnutls_openpgp_privkey_get_subkey_idx
1976           (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t
1977           KEYID)
1978      KEY: the structure that contains the OpenPGP private key.
1979
1980      KEYID: the keyid.
1981
1982      Get index of subkey.
1983
1984      *Returns:* the index of the subkey or a negative error value.
1985
1986      *Since:* 2.4.0
1987
1988 gnutls_openpgp_privkey_get_subkey_pk_algorithm
1989 ----------------------------------------------
1990
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
1994           * BITS)
1995      KEY: is an OpenPGP key
1996
1997      IDX: is the subkey index
1998
1999      BITS: if bits is non null it will hold the size of the parameters'
2000      in bits
2001
2002      This function will return the public key algorithm of a subkey of
2003      an OpenPGP certificate.
2004
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.
2008
2009      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
2010      success, or a negative error code on error.
2011
2012      *Since:* 2.4.0
2013
2014 gnutls_openpgp_privkey_get_subkey_revoked_status
2015 ------------------------------------------------
2016
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.
2020
2021      IDX: is the subkey index
2022
2023      Get revocation status of key.
2024
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.
2027
2028      *Since:* 2.4.0
2029
2030 gnutls_openpgp_privkey_import
2031 -----------------------------
2032
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,
2036           unsigned int FLAGS)
2037      KEY: The structure to store the parsed key.
2038
2039      DATA: The RAW or BASE64 encoded key.
2040
2041      FORMAT: One of 'gnutls_openpgp_crt_fmt_t' elements.
2042
2043      PASSWORD: not used for now
2044
2045      FLAGS: should be (0)
2046
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
2049      stored in 'key'.
2050
2051      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2052
2053 gnutls_openpgp_privkey_init
2054 ---------------------------
2055
2056  -- Function: int gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t
2057           * KEY)
2058      KEY: The structure to be initialized
2059
2060      This function will initialize an OpenPGP key structure.
2061
2062      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2063
2064 gnutls_openpgp_privkey_sec_param
2065 --------------------------------
2066
2067  -- Function: gnutls_sec_param_t gnutls_openpgp_privkey_sec_param
2068           (gnutls_openpgp_privkey_t KEY)
2069      KEY: a key structure
2070
2071      This function will return the security parameter appropriate with
2072      this private key.
2073
2074      *Returns:* On success, a valid security parameter is returned
2075      otherwise 'GNUTLS_SEC_PARAM_UNKNOWN' is returned.
2076
2077      *Since:* 2.12.0
2078
2079 gnutls_openpgp_privkey_set_preferred_key_id
2080 -------------------------------------------
2081
2082  -- Function: int gnutls_openpgp_privkey_set_preferred_key_id
2083           (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t
2084           KEYID)
2085      KEY: the structure that contains the OpenPGP public key.
2086
2087      KEYID: the selected keyid
2088
2089      This allows setting a preferred key id for the given certificate.
2090      This key will be used by functions that involve key handling.
2091
2092      If the provided 'keyid' is 'NULL' then the master key is set as
2093      preferred.
2094
2095      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2096      otherwise a negative error code is returned.
2097
2098 gnutls_openpgp_set_recv_key_function
2099 ------------------------------------
2100
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
2104
2105      FUNC: the callback
2106
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.
2110
2111      The retrieved key must be allocated using 'gnutls_malloc()' .
2112
2113 \1f
2114 File: gnutls.info,  Node: PKCS 12 API,  Next: PKCS 11 API,  Prev: OpenPGP API,  Up: API reference
2115
2116 E.6 PKCS 12 API
2117 ===============
2118
2119 The following functions are to be used for PKCS 12 handling.  Their
2120 prototypes lie in 'gnutls/pkcs12.h'.
2121
2122 gnutls_pkcs12_bag_decrypt
2123 -------------------------
2124
2125  -- Function: int gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t BAG,
2126           const char * PASS)
2127      BAG: The bag
2128
2129      PASS: The password used for encryption, must be ASCII.
2130
2131      This function will decrypt the given encrypted bag and return 0 on
2132      success.
2133
2134      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2135      otherwise a negative error code is returned.
2136
2137 gnutls_pkcs12_bag_deinit
2138 ------------------------
2139
2140  -- Function: void gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t BAG)
2141      BAG: The structure to be initialized
2142
2143      This function will deinitialize a PKCS12 Bag structure.
2144
2145 gnutls_pkcs12_bag_encrypt
2146 -------------------------
2147
2148  -- Function: int gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t BAG,
2149           const char * PASS, unsigned int FLAGS)
2150      BAG: The bag
2151
2152      PASS: The password used for encryption, must be ASCII
2153
2154      FLAGS: should be one of 'gnutls_pkcs_encrypt_flags_t' elements
2155      bitwise or'd
2156
2157      This function will encrypt the given bag.
2158
2159      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2160      otherwise a negative error code is returned.
2161
2162 gnutls_pkcs12_bag_get_count
2163 ---------------------------
2164
2165  -- Function: int gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t BAG)
2166      BAG: The bag
2167
2168      This function will return the number of the elements withing the
2169      bag.
2170
2171      *Returns:* Number of elements in bag, or an negative error code on
2172      error.
2173
2174 gnutls_pkcs12_bag_get_data
2175 --------------------------
2176
2177  -- Function: int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t BAG,
2178           int INDX, gnutls_datum_t * DATA)
2179      BAG: The bag
2180
2181      INDX: The element of the bag to get the data from
2182
2183      DATA: where the bag's data will be.  Should be treated as constant.
2184
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
2187      is deleted.
2188
2189      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2190      otherwise a negative error value.
2191
2192 gnutls_pkcs12_bag_get_friendly_name
2193 -----------------------------------
2194
2195  -- Function: int gnutls_pkcs12_bag_get_friendly_name
2196           (gnutls_pkcs12_bag_t BAG, int INDX, char ** NAME)
2197      BAG: The bag
2198
2199      INDX: The bag's element to add the id
2200
2201      NAME: will hold a pointer to the name (to be treated as const)
2202
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.
2206
2207      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2208      otherwise a negative error value.  or a negative error code on
2209      error.
2210
2211 gnutls_pkcs12_bag_get_key_id
2212 ----------------------------
2213
2214  -- Function: int gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t BAG,
2215           int INDX, gnutls_datum_t * ID)
2216      BAG: The bag
2217
2218      INDX: The bag's element to add the id
2219
2220      ID: where the ID will be copied (to be treated as const)
2221
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.
2225
2226      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2227      otherwise a negative error value.  or a negative error code on
2228      error.
2229
2230 gnutls_pkcs12_bag_get_type
2231 --------------------------
2232
2233  -- Function: gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type
2234           (gnutls_pkcs12_bag_t BAG, int INDX)
2235      BAG: The bag
2236
2237      INDX: The element of the bag to get the type
2238
2239      This function will return the bag's type.
2240
2241      *Returns:* One of the 'gnutls_pkcs12_bag_type_t' enumerations.
2242
2243 gnutls_pkcs12_bag_init
2244 ----------------------
2245
2246  -- Function: int gnutls_pkcs12_bag_init (gnutls_pkcs12_bag_t * BAG)
2247      BAG: The structure to be initialized
2248
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.
2252
2253      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2254      otherwise a negative error value.
2255
2256 gnutls_pkcs12_bag_set_crl
2257 -------------------------
2258
2259  -- Function: int gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t BAG,
2260           gnutls_x509_crl_t CRL)
2261      BAG: The bag
2262
2263      CRL: the CRL to be copied.
2264
2265      This function will insert the given CRL into the bag.  This is just
2266      a wrapper over 'gnutls_pkcs12_bag_set_data()' .
2267
2268      *Returns:* the index of the added bag on success, or a negative
2269      error code on failure.
2270
2271 gnutls_pkcs12_bag_set_crt
2272 -------------------------
2273
2274  -- Function: int gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t BAG,
2275           gnutls_x509_crt_t CRT)
2276      BAG: The bag
2277
2278      CRT: the certificate to be copied.
2279
2280      This function will insert the given certificate into the bag.  This
2281      is just a wrapper over 'gnutls_pkcs12_bag_set_data()' .
2282
2283      *Returns:* the index of the added bag on success, or a negative
2284      value on failure.
2285
2286 gnutls_pkcs12_bag_set_data
2287 --------------------------
2288
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)
2291      BAG: The bag
2292
2293      TYPE: The data's type
2294
2295      DATA: the data to be copied.
2296
2297      This function will insert the given data of the given type into the
2298      bag.
2299
2300      *Returns:* the index of the added bag on success, or a negative
2301      value on error.
2302
2303 gnutls_pkcs12_bag_set_friendly_name
2304 -----------------------------------
2305
2306  -- Function: int gnutls_pkcs12_bag_set_friendly_name
2307           (gnutls_pkcs12_bag_t BAG, int INDX, const char * NAME)
2308      BAG: The bag
2309
2310      INDX: The bag's element to add the id
2311
2312      NAME: the name
2313
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.
2318
2319      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2320      otherwise a negative error value.  or a negative error code on
2321      error.
2322
2323 gnutls_pkcs12_bag_set_key_id
2324 ----------------------------
2325
2326  -- Function: int gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t BAG,
2327           int INDX, const gnutls_datum_t * ID)
2328      BAG: The bag
2329
2330      INDX: The bag's element to add the id
2331
2332      ID: the ID
2333
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.
2338
2339      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2340      otherwise a negative error value.  or a negative error code on
2341      error.
2342
2343 gnutls_pkcs12_deinit
2344 --------------------
2345
2346  -- Function: void gnutls_pkcs12_deinit (gnutls_pkcs12_t PKCS12)
2347      PKCS12: The structure to be initialized
2348
2349      This function will deinitialize a PKCS12 structure.
2350
2351 gnutls_pkcs12_export
2352 --------------------
2353
2354  -- Function: int gnutls_pkcs12_export (gnutls_pkcs12_t PKCS12,
2355           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
2356           OUTPUT_DATA_SIZE)
2357      PKCS12: Holds the pkcs12 structure
2358
2359      FORMAT: the format of output params.  One of PEM or DER.
2360
2361      OUTPUT_DATA: will contain a structure PEM or DER encoded
2362
2363      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2364      replaced by the actual size of parameters)
2365
2366      This function will export the pkcs12 structure to DER or PEM
2367      format.
2368
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
2371      will be returned.
2372
2373      If the structure is PEM encoded, it will have a header of "BEGIN
2374      PKCS12".
2375
2376      *Returns:* In case of failure a negative error code will be
2377      returned, and 0 on success.
2378
2379 gnutls_pkcs12_export2
2380 ---------------------
2381
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
2385
2386      FORMAT: the format of output params.  One of PEM or DER.
2387
2388      OUT: will contain a structure PEM or DER encoded
2389
2390      This function will export the pkcs12 structure to DER or PEM
2391      format.
2392
2393      The output buffer is allocated using 'gnutls_malloc()' .
2394
2395      If the structure is PEM encoded, it will have a header of "BEGIN
2396      PKCS12".
2397
2398      *Returns:* In case of failure a negative error code will be
2399      returned, and 0 on success.
2400
2401      *Since:* 3.1.3
2402
2403 gnutls_pkcs12_generate_mac
2404 --------------------------
2405
2406  -- Function: int gnutls_pkcs12_generate_mac (gnutls_pkcs12_t PKCS12,
2407           const char * PASS)
2408      PKCS12: should contain a gnutls_pkcs12_t structure
2409
2410      PASS: The password for the MAC
2411
2412      This function will generate a MAC for the PKCS12 structure.
2413
2414      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2415      otherwise a negative error value.
2416
2417 gnutls_pkcs12_get_bag
2418 ---------------------
2419
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
2423
2424      INDX: contains the index of the bag to extract
2425
2426      BAG: An initialized bag, where the contents of the bag will be
2427      copied
2428
2429      This function will return a Bag from the PKCS12 structure.
2430
2431      After the last Bag has been read
2432      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
2433
2434      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2435      otherwise a negative error value.
2436
2437 gnutls_pkcs12_import
2438 --------------------
2439
2440  -- Function: int gnutls_pkcs12_import (gnutls_pkcs12_t PKCS12, const
2441           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned
2442           int FLAGS)
2443      PKCS12: The structure to store the parsed PKCS12.
2444
2445      DATA: The DER or PEM encoded PKCS12.
2446
2447      FORMAT: One of DER or PEM
2448
2449      FLAGS: an ORed sequence of gnutls_privkey_pkcs8_flags
2450
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
2453      'pkcs12'.
2454
2455      If the PKCS12 is PEM encoded it should have a header of "PKCS12".
2456
2457      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2458      otherwise a negative error value.
2459
2460 gnutls_pkcs12_init
2461 ------------------
2462
2463  -- Function: int gnutls_pkcs12_init (gnutls_pkcs12_t * PKCS12)
2464      PKCS12: The structure to be initialized
2465
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.
2469
2470      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2471      otherwise a negative error value.
2472
2473 gnutls_pkcs12_set_bag
2474 ---------------------
2475
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
2479
2480      BAG: An initialized bag
2481
2482      This function will insert a Bag into the PKCS12 structure.
2483
2484      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2485      otherwise a negative error value.
2486
2487 gnutls_pkcs12_simple_parse
2488 --------------------------
2489
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.
2496
2497      PASSWORD: optional password used to decrypt PKCS12 blob, bags and
2498      keys.
2499
2500      KEY: a structure to store the parsed private key.
2501
2502      CHAIN: the corresponding to key certificate chain (may be 'NULL' )
2503
2504      CHAIN_LEN: will be updated with the number of additional (may be
2505      'NULL' )
2506
2507      EXTRA_CERTS: optional pointer to receive an array of additional
2508      certificates found in the PKCS12 blob (may be 'NULL' ).
2509
2510      EXTRA_CERTS_LEN: will be updated with the number of additional
2511      certs (may be 'NULL' ).
2512
2513      CRL: an optional structure to store the parsed CRL (may be 'NULL'
2514      ).
2515
2516      FLAGS: should be zero or one of GNUTLS_PKCS12_SP_*
2517
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.
2521
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
2524      both must be set.
2525
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.
2529
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.
2534
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
2538      all.
2539
2540      If the provided structure has encrypted fields but no password is
2541      provided then this function returns 'GNUTLS_E_DECRYPTION_FAILED' .
2542
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
2547      chain.
2548
2549      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2550      otherwise a negative error value.
2551
2552      *Since:* 3.1
2553
2554 gnutls_pkcs12_verify_mac
2555 ------------------------
2556
2557  -- Function: int gnutls_pkcs12_verify_mac (gnutls_pkcs12_t PKCS12,
2558           const char * PASS)
2559      PKCS12: should contain a gnutls_pkcs12_t structure
2560
2561      PASS: The password for the MAC
2562
2563      This function will verify the MAC for the PKCS12 structure.
2564
2565      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2566      otherwise a negative error value.
2567
2568 \1f
2569 File: gnutls.info,  Node: PKCS 11 API,  Next: TPM API,  Prev: PKCS 12 API,  Up: API reference
2570
2571 E.7 Hardware token via PKCS 11 API
2572 ==================================
2573
2574 The following functions are to be used for PKCS 11 handling.  Their
2575 prototypes lie in 'gnutls/pkcs11.h'.
2576
2577 gnutls_pkcs11_add_provider
2578 --------------------------
2579
2580  -- Function: int gnutls_pkcs11_add_provider (const char * NAME, const
2581           char * PARAMS)
2582      NAME: The filename of the module
2583
2584      PARAMS: should be NULL
2585
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.
2589
2590      When loading a module to be used for certificate verification, use
2591      the string 'trusted' as 'params' .
2592
2593      Note that this function is not thread safe.
2594
2595      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2596      otherwise a negative error value.
2597
2598      *Since:* 2.12.0
2599
2600 gnutls_pkcs11_copy_secret_key
2601 -----------------------------
2602
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
2607
2608      KEY: The raw key
2609
2610      LABEL: A name to be used for the stored data
2611
2612      KEY_USAGE: One of GNUTLS_KEY_*
2613
2614      FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2615
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
2618      or not.
2619
2620      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2621      otherwise a negative error value.
2622
2623      *Since:* 2.12.0
2624
2625 gnutls_pkcs11_copy_x509_crt
2626 ---------------------------
2627
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
2631
2632      CRT: A certificate
2633
2634      LABEL: A name to be used for the stored data
2635
2636      FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2637
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
2640      not.
2641
2642      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2643      otherwise a negative error value.
2644
2645      *Since:* 2.12.0
2646
2647 gnutls_pkcs11_copy_x509_privkey
2648 -------------------------------
2649
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
2654
2655      KEY: A private key
2656
2657      LABEL: A name to be used for the stored data
2658
2659      KEY_USAGE: One of GNUTLS_KEY_*
2660
2661      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2662
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
2666      reason not to.
2667
2668      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2669      otherwise a negative error value.
2670
2671      *Since:* 2.12.0
2672
2673 gnutls_pkcs11_crt_is_known
2674 --------------------------
2675
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
2679
2680      CERT: is the certificate to find issuer for
2681
2682      FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2683
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'
2689      module.
2690
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.
2695
2696      Note that the flag 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED' is
2697      specific to p11-kit trust modules.
2698
2699      *Returns:* If the certificate exists non-zero is returned,
2700      otherwise zero.
2701
2702      *Since:* 3.3.0
2703
2704 gnutls_pkcs11_deinit
2705 --------------------
2706
2707  -- Function: void gnutls_pkcs11_deinit ( VOID)
2708
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()' .
2712
2713      *Since:* 2.12.0
2714
2715 gnutls_pkcs11_delete_url
2716 ------------------------
2717
2718  -- Function: int gnutls_pkcs11_delete_url (const char * OBJECT_URL,
2719           unsigned int FLAGS)
2720      OBJECT_URL: The URL of the object to delete.
2721
2722      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2723
2724      This function will delete objects matching the given URL. Note that
2725      not all tokens support the delete operation.
2726
2727      *Returns:* On success, the number of objects deleted is returned,
2728      otherwise a negative error value.
2729
2730      *Since:* 2.12.0
2731
2732 gnutls_pkcs11_get_pin_function
2733 ------------------------------
2734
2735  -- Function: gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void
2736           ** USERDATA)
2737      USERDATA: data to be supplied to callback
2738
2739      This function will return the callback function set using
2740      'gnutls_pkcs11_set_pin_function()' .
2741
2742      *Returns:* The function set or NULL otherwise.
2743
2744      *Since:* 3.1.0
2745
2746 gnutls_pkcs11_get_raw_issuer
2747 ----------------------------
2748
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
2753
2754      CERT: is the certificate to find issuer for
2755
2756      ISSUER: Will hold the issuer if any in an allocated buffer.
2757
2758      FMT: The format of the exported issuer.
2759
2760      FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2761
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' .
2766
2767      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2768      otherwise a negative error value.
2769
2770      *Since:* 3.2.7
2771
2772 gnutls_pkcs11_init
2773 ------------------
2774
2775  -- Function: int gnutls_pkcs11_init (unsigned int FLAGS, const char *
2776           DEPRECATED_CONFIG_FILE)
2777      FLAGS: An ORed sequence of 'GNUTLS_PKCS11_FLAG_' *
2778
2779      DEPRECATED_CONFIG_FILE: either NULL or the location of a deprecated
2780      configuration file
2781
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
2786      specified.
2787
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.
2792
2793      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2794      otherwise a negative error value.
2795
2796      *Since:* 2.12.0
2797
2798 gnutls_pkcs11_obj_deinit
2799 ------------------------
2800
2801  -- Function: void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t OBJ)
2802      OBJ: The structure to be initialized
2803
2804      This function will deinitialize a certificate structure.
2805
2806      *Since:* 2.12.0
2807
2808 gnutls_pkcs11_obj_export
2809 ------------------------
2810
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
2814
2815      OUTPUT_DATA: will contain the object data
2816
2817      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2818      replaced by the actual size of parameters)
2819
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'
2822      will be returned.
2823
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
2826      be returned.
2827
2828      *Returns:* In case of failure a negative error code will be
2829      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2830
2831      *Since:* 2.12.0
2832
2833 gnutls_pkcs11_obj_export2
2834 -------------------------
2835
2836  -- Function: int gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t OBJ,
2837           gnutls_datum_t * OUT)
2838      OBJ: Holds the object
2839
2840      OUT: will contain the object data
2841
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'
2844      will be returned.
2845
2846      The output buffer is allocated using 'gnutls_malloc()' .
2847
2848      *Returns:* In case of failure a negative error code will be
2849      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2850
2851      *Since:* 3.1.3
2852
2853 gnutls_pkcs11_obj_export3
2854 -------------------------
2855
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
2859
2860      FMT: The format of the exported data
2861
2862      OUT: will contain the object data
2863
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'
2866      will be returned.
2867
2868      The output buffer is allocated using 'gnutls_malloc()' .
2869
2870      *Returns:* In case of failure a negative error code will be
2871      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2872
2873      *Since:* 3.2.7
2874
2875 gnutls_pkcs11_obj_export_url
2876 ----------------------------
2877
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
2881
2882      DETAILED: non zero if a detailed URL is required
2883
2884      URL: will contain an allocated url
2885
2886      This function will export a URL identifying the given certificate.
2887
2888      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2889      otherwise a negative error value.
2890
2891      *Since:* 2.12.0
2892
2893 gnutls_pkcs11_obj_get_info
2894 --------------------------
2895
2896  -- Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t CRT,
2897           gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t *
2898           OUTPUT_SIZE)
2899      CRT: should contain a 'gnutls_pkcs11_obj_t' structure
2900
2901      ITYPE: Denotes the type of information requested
2902
2903      OUTPUT: where output will be stored
2904
2905      OUTPUT_SIZE: contains the maximum size of the output and will be
2906      overwritten with actual
2907
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.
2912
2913      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
2914      code on error.
2915
2916      *Since:* 2.12.0
2917
2918 gnutls_pkcs11_obj_get_type
2919 --------------------------
2920
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
2924
2925      This function will return the type of the certificate being stored
2926      in the structure.
2927
2928      *Returns:* The type of the certificate.
2929
2930      *Since:* 2.12.0
2931
2932 gnutls_pkcs11_obj_import_url
2933 ----------------------------
2934
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
2938
2939      URL: a PKCS 11 url identifying the key
2940
2941      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2942
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
2947      transferred.
2948
2949      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2950      otherwise a negative error value.
2951
2952      *Since:* 2.12.0
2953
2954 gnutls_pkcs11_obj_init
2955 ----------------------
2956
2957  -- Function: int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * OBJ)
2958      OBJ: The structure to be initialized
2959
2960      This function will initialize a pkcs11 certificate structure.
2961
2962      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2963      otherwise a negative error value.
2964
2965      *Since:* 2.12.0
2966
2967 gnutls_pkcs11_obj_list_import_url
2968 ---------------------------------
2969
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)
2974
2975      N_LIST: initially should hold the maximum size of the list.  Will
2976      contain the actual size.
2977
2978      URL: A PKCS 11 url identifying a set of objects
2979
2980      ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
2981      used to limit output
2982
2983      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2984
2985      This function will initialize and set values to an object list by
2986      using all objects identified by a PKCS 11 URL.
2987
2988      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2989      otherwise a negative error value.
2990
2991      *Since:* 2.12.0
2992
2993 gnutls_pkcs11_obj_list_import_url2
2994 ----------------------------------
2995
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
2999           FLAGS)
3000      P_LIST: An uninitialized object list (may be NULL)
3001
3002      N_LIST: It will contain the size of the list.
3003
3004      URL: A PKCS 11 url identifying a set of objects
3005
3006      ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
3007      used to limit output
3008
3009      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
3010
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.
3014
3015      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3016      otherwise a negative error value.
3017
3018      *Since:* 3.1.0
3019
3020 gnutls_pkcs11_obj_set_pin_function
3021 ----------------------------------
3022
3023  -- Function: void gnutls_pkcs11_obj_set_pin_function
3024           (gnutls_pkcs11_obj_t OBJ, gnutls_pin_callback_t FN, void *
3025           USERDATA)
3026      OBJ: The object structure
3027
3028      FN: the callback
3029
3030      USERDATA: data associated with the callback
3031
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()' .
3035
3036      *Since:* 3.1.0
3037
3038 gnutls_pkcs11_privkey_deinit
3039 ----------------------------
3040
3041  -- Function: void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t
3042           KEY)
3043      KEY: The structure to be initialized
3044
3045      This function will deinitialize a private key structure.
3046
3047 gnutls_pkcs11_privkey_export_url
3048 --------------------------------
3049
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
3054
3055      DETAILED: non zero if a detailed URL is required
3056
3057      URL: will contain an allocated url
3058
3059      This function will export a URL identifying the given key.
3060
3061      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3062      otherwise a negative error value.
3063
3064 gnutls_pkcs11_privkey_generate
3065 ------------------------------
3066
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)
3070      URL: a token URL
3071
3072      PK: the public key algorithm
3073
3074      BITS: the security bits
3075
3076      LABEL: a label
3077
3078      FLAGS: should be zero
3079
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.
3083
3084      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3085      otherwise a negative error value.
3086
3087      *Since:* 3.0
3088
3089 gnutls_pkcs11_privkey_generate2
3090 -------------------------------
3091
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,
3095           unsigned int FLAGS)
3096      URL: a token URL
3097
3098      PK: the public key algorithm
3099
3100      BITS: the security bits
3101
3102      LABEL: a label
3103
3104      FMT: the format of output params.  PEM or DER.
3105
3106      PUBKEY: will hold the public key (may be 'NULL' )
3107
3108      FLAGS: should be zero
3109
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()' .
3115
3116      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3117      otherwise a negative error value.
3118
3119      *Since:* 3.1.5
3120
3121 gnutls_pkcs11_privkey_get_info
3122 ------------------------------
3123
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
3128
3129      ITYPE: Denotes the type of information requested
3130
3131      OUTPUT: where output will be stored
3132
3133      OUTPUT_SIZE: contains the maximum size of the output and will be
3134      overwritten with actual
3135
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.
3140
3141      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3142      code on error.
3143
3144 gnutls_pkcs11_privkey_get_pk_algorithm
3145 --------------------------------------
3146
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
3150
3151      BITS: if bits is non null it will hold the size of the parameters'
3152      in bits
3153
3154      This function will return the public key algorithm of a private
3155      key.
3156
3157      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3158      success, or a negative error code on error.
3159
3160 gnutls_pkcs11_privkey_import_url
3161 --------------------------------
3162
3163  -- Function: int gnutls_pkcs11_privkey_import_url
3164           (gnutls_pkcs11_privkey_t PKEY, const char * URL, unsigned int
3165           FLAGS)
3166      PKEY: The structure to store the parsed key
3167
3168      URL: a PKCS 11 url identifying the key
3169
3170      FLAGS: sequence of GNUTLS_PKCS_PRIVKEY_*
3171
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.
3176
3177      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3178      otherwise a negative error value.
3179
3180 gnutls_pkcs11_privkey_init
3181 --------------------------
3182
3183  -- Function: int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *
3184           KEY)
3185      KEY: The structure to be initialized
3186
3187      This function will initialize an private key structure.
3188
3189      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3190      otherwise a negative error value.
3191
3192 gnutls_pkcs11_privkey_set_pin_function
3193 --------------------------------------
3194
3195  -- Function: void gnutls_pkcs11_privkey_set_pin_function
3196           (gnutls_pkcs11_privkey_t KEY, gnutls_pin_callback_t FN, void *
3197           USERDATA)
3198      KEY: The private key
3199
3200      FN: the callback
3201
3202      USERDATA: data associated with the callback
3203
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()' .
3207
3208      *Since:* 3.1.0
3209
3210 gnutls_pkcs11_privkey_status
3211 ----------------------------
3212
3213  -- Function: int gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t
3214           KEY)
3215      KEY: Holds the key
3216
3217      Checks the status of the private key token.
3218
3219      *Returns:* this function will return non-zero if the token holding
3220      the private key is still available (inserted), and zero otherwise.
3221
3222      *Since:* 3.1.9
3223
3224 gnutls_pkcs11_reinit
3225 --------------------
3226
3227  -- Function: int gnutls_pkcs11_reinit ( VOID)
3228
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.
3232
3233      Note that since GnuTLS 3.3.0, the reinitialization of the PKCS '11'
3234      subsystem occurs automatically after fork.
3235
3236      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3237      otherwise a negative error value.
3238
3239      *Since:* 3.0
3240
3241 gnutls_pkcs11_set_pin_function
3242 ------------------------------
3243
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.
3247
3248      USERDATA: data to be supplied to callback
3249
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.
3253
3254      *Since:* 2.12.0
3255
3256 gnutls_pkcs11_set_token_function
3257 --------------------------------
3258
3259  -- Function: void gnutls_pkcs11_set_token_function
3260           (gnutls_pkcs11_token_callback_t FN, void * USERDATA)
3261      FN: The token callback
3262
3263      USERDATA: data to be supplied to callback
3264
3265      This function will set a callback function to be used when a token
3266      needs to be inserted to continue PKCS 11 operations.
3267
3268      *Since:* 2.12.0
3269
3270 gnutls_pkcs11_token_get_flags
3271 -----------------------------
3272
3273  -- Function: int gnutls_pkcs11_token_get_flags (const char * URL,
3274           unsigned int * FLAGS)
3275      URL: should contain a PKCS 11 URL
3276
3277      FLAGS: The output flags (GNUTLS_PKCS11_TOKEN_*)
3278
3279      This function will return information about the PKCS 11 token
3280      flags.
3281
3282      The supported flags are: 'GNUTLS_PKCS11_TOKEN_HW' and
3283      'GNUTLS_PKCS11_TOKEN_TRUSTED' .
3284
3285      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3286      code on error.
3287
3288      *Since:* 2.12.0
3289
3290 gnutls_pkcs11_token_get_info
3291 ----------------------------
3292
3293  -- Function: int gnutls_pkcs11_token_get_info (const char * URL,
3294           gnutls_pkcs11_token_info_t TTYPE, void * OUTPUT, size_t *
3295           OUTPUT_SIZE)
3296      URL: should contain a PKCS 11 URL
3297
3298      TTYPE: Denotes the type of information requested
3299
3300      OUTPUT: where output will be stored
3301
3302      OUTPUT_SIZE: contains the maximum size of the output and will be
3303      overwritten with actual
3304
3305      This function will return information about the PKCS 11 token such
3306      as the label, id, etc.
3307
3308      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3309      code on error.
3310
3311      *Since:* 2.12.0
3312
3313 gnutls_pkcs11_token_get_mechanism
3314 ---------------------------------
3315
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
3319
3320      IDX: The index of the mechanism
3321
3322      MECHANISM: The PKCS '11' mechanism ID
3323
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.
3327
3328      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3329      code on error.
3330
3331      *Since:* 2.12.0
3332
3333 gnutls_pkcs11_token_get_random
3334 ------------------------------
3335
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
3339
3340      RNDDATA: A pointer to the memory area to be filled with random data
3341
3342      LEN: The number of bytes of randomness to request
3343
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.
3347
3348      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3349      otherwise a negative error value.
3350
3351 gnutls_pkcs11_token_get_url
3352 ---------------------------
3353
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
3357
3358      DETAILED: non zero if a detailed URL is required
3359
3360      URL: will contain an allocated url
3361
3362      This function will return the URL for each token available in
3363      system.  The url has to be released using 'gnutls_free()'
3364
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.
3368
3369      *Since:* 2.12.0
3370
3371 gnutls_pkcs11_token_init
3372 ------------------------
3373
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
3377
3378      SO_PIN: Security Officer's PIN
3379
3380      LABEL: A name to be used for the token
3381
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
3385      PIN.
3386
3387      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3388      otherwise a negative error value.
3389
3390 gnutls_pkcs11_token_set_pin
3391 ---------------------------
3392
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
3396
3397      OLDPIN: old user's PIN
3398
3399      NEWPIN: new user's PIN
3400
3401      FLAGS: one of 'gnutls_pin_flag_t' .
3402
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
3405      NULL.
3406
3407      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3408      otherwise a negative error value.
3409
3410 gnutls_pkcs11_type_get_name
3411 ---------------------------
3412
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' .
3416
3417      This function will return a human readable description of the
3418      PKCS11 object type 'obj' .  It will return "Unknown" for unknown
3419      types.
3420
3421      *Returns:* human readable string labeling the PKCS11 object type
3422      'type' .
3423
3424      *Since:* 2.12.0
3425
3426 gnutls_x509_crt_import_pkcs11
3427 -----------------------------
3428
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'
3432
3433      PKCS11_CRT: A PKCS 11 object that contains a certificate
3434
3435      This function will import a PKCS 11 certificate to a
3436      'gnutls_x509_crt_t' structure.
3437
3438      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3439      otherwise a negative error value.
3440
3441      *Since:* 2.12.0
3442
3443 gnutls_x509_crt_import_pkcs11_url
3444 ---------------------------------
3445
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'
3449
3450      URL: A PKCS 11 url
3451
3452      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
3453
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.
3457
3458      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3459      otherwise a negative error value.
3460
3461      *Since:* 2.12.0
3462
3463 gnutls_x509_crt_list_import_pkcs11
3464 ----------------------------------
3465
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'
3470
3471      CERT_MAX: The maximum size of the list
3472
3473      OBJS: A list of PKCS 11 objects
3474
3475      FLAGS: 0 for now
3476
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.
3479
3480      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3481      otherwise a negative error value.
3482
3483      *Since:* 2.12.0
3484
3485 \1f
3486 File: gnutls.info,  Node: TPM API,  Next: Abstract key API,  Prev: PKCS 11 API,  Up: API reference
3487
3488 E.8 TPM API
3489 ===========
3490
3491 The following functions are to be used for TPM handling.  Their
3492 prototypes lie in 'gnutls/tpm.h'.
3493
3494 gnutls_tpm_get_registered
3495 -------------------------
3496
3497  -- Function: int gnutls_tpm_get_registered (gnutls_tpm_key_list_t *
3498           LIST)
3499      LIST: a list to store the keys
3500
3501      This function will get a list of stored keys in the TPM. The uuid
3502      of those keys
3503
3504      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3505      otherwise a negative error value.
3506
3507      *Since:* 3.1.0
3508
3509 gnutls_tpm_key_list_deinit
3510 --------------------------
3511
3512  -- Function: void gnutls_tpm_key_list_deinit (gnutls_tpm_key_list_t
3513           LIST)
3514      LIST: a list of the keys
3515
3516      This function will deinitialize the list of stored keys in the TPM.
3517
3518      *Since:* 3.1.0
3519
3520 gnutls_tpm_key_list_get_url
3521 ---------------------------
3522
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
3526
3527      IDX: The index of the key (starting from zero)
3528
3529      URL: The URL to be returned
3530
3531      FLAGS: should be zero
3532
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.
3536
3537      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3538      otherwise a negative error value.
3539
3540      *Since:* 3.1.0
3541
3542 gnutls_tpm_privkey_delete
3543 -------------------------
3544
3545  -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
3546           char * SRK_PASSWORD)
3547      URL: the URL describing the key
3548
3549      SRK_PASSWORD: a password for the SRK key
3550
3551      This function will unregister the private key from the TPM chip.
3552
3553      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3554      otherwise a negative error value.
3555
3556      *Since:* 3.1.0
3557
3558 gnutls_tpm_privkey_generate
3559 ---------------------------
3560
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
3567
3568      BITS: the security bits
3569
3570      SRK_PASSWORD: a password to protect the exported key (optional)
3571
3572      KEY_PASSWORD: the password for the TPM (optional)
3573
3574      FORMAT: the format of the private key
3575
3576      PUB_FORMAT: the format of the public key
3577
3578      PRIVKEY: the generated key
3579
3580      PUBKEY: the corresponding public key (may be null)
3581
3582      FLAGS: should be a list of GNUTLS_TPM_* flags
3583
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' .
3588
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.
3592
3593      Allowed flags are:
3594
3595      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3596      otherwise a negative error value.
3597
3598      *Since:* 3.1.0
3599
3600 \1f
3601 File: gnutls.info,  Node: Abstract key API,  Next: DANE API,  Prev: TPM API,  Up: API reference
3602
3603 E.9 Abstract key API
3604 ====================
3605
3606 The following functions are to be used for abstract key handling.  Their
3607 prototypes lie in 'gnutls/abstract.h'.
3608
3609 gnutls_certificate_set_key
3610 --------------------------
3611
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.
3617
3618      NAMES: is an array of DNS name of the certificate (NULL if none)
3619
3620      NAMES_SIZE: holds the size of the names list
3621
3622      PCERT_LIST: contains a certificate list (path) for the specified
3623      private key
3624
3625      PCERT_LIST_SIZE: holds the size of the certificate list
3626
3627      KEY: is a 'gnutls_privkey_t' key
3628
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' .
3635
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
3639      deinitialized.
3640
3641      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
3642      code.
3643
3644      *Since:* 3.0
3645
3646 gnutls_certificate_set_retrieve_function2
3647 -----------------------------------------
3648
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.
3653
3654      FUNC: is the callback function
3655
3656      This function sets a callback to be called in order to retrieve the
3657      certificate to be used in the handshake.
3658
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);
3664
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()' .
3670
3671      'pk_algos' contains a list with server's acceptable signature
3672      algorithms.  The certificate returned should support the server's
3673      given algorithms.
3674
3675      'pcert' should contain a single certificate and public or a list of
3676      them.
3677
3678      'pcert_length' is the size of the previous list.
3679
3680      'pkey' is the private key.
3681
3682      If the callback function is provided then gnutls will call it, in
3683      the handshake, after the certificate request message has been
3684      received.
3685
3686      In server side pk_algos and req_ca_dn are NULL.
3687
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.
3692
3693      *Since:* 3.0
3694
3695 gnutls_pcert_deinit
3696 -------------------
3697
3698  -- Function: void gnutls_pcert_deinit (gnutls_pcert_st * PCERT)
3699      PCERT: The structure to be deinitialized
3700
3701      This function will deinitialize a pcert structure.
3702
3703      *Since:* 3.0
3704
3705 gnutls_pcert_import_openpgp
3706 ---------------------------
3707
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
3711
3712      CRT: The raw certificate to be imported
3713
3714      FLAGS: zero for now
3715
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()' ;
3719
3720      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3721      otherwise a negative error value.
3722
3723      *Since:* 3.0
3724
3725 gnutls_pcert_import_openpgp_raw
3726 -------------------------------
3727
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
3732
3733      CERT: The raw certificate to be imported
3734
3735      FORMAT: The format of the certificate
3736
3737      KEYID: The key ID to use (NULL for the master key)
3738
3739      FLAGS: zero for now
3740
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()' ;
3744
3745      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3746      otherwise a negative error value.
3747
3748      *Since:* 3.0
3749
3750 gnutls_pcert_import_x509
3751 ------------------------
3752
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
3756
3757      CRT: The raw certificate to be imported
3758
3759      FLAGS: zero for now
3760
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()' ;
3764
3765      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3766      otherwise a negative error value.
3767
3768      *Since:* 3.0
3769
3770 gnutls_pcert_import_x509_raw
3771 ----------------------------
3772
3773  -- Function: int gnutls_pcert_import_x509_raw (gnutls_pcert_st * PCERT,
3774           const gnutls_datum_t * CERT, gnutls_x509_crt_fmt_t FORMAT,
3775           unsigned int FLAGS)
3776      PCERT: The pcert structure
3777
3778      CERT: The raw certificate to be imported
3779
3780      FORMAT: The format of the certificate
3781
3782      FLAGS: zero for now
3783
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()' ;
3787
3788      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3789      otherwise a negative error value.
3790
3791      *Since:* 3.0
3792
3793 gnutls_pcert_list_import_x509_raw
3794 ---------------------------------
3795
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
3800      be initialized.
3801
3802      PCERT_MAX: Initially must hold the maximum number of certs.  It
3803      will be updated with the number of certs available.
3804
3805      DATA: The certificates.
3806
3807      FORMAT: One of DER or PEM.
3808
3809      FLAGS: must be (0) or an OR'd sequence of
3810      gnutls_certificate_import_flags.
3811
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.
3815
3816      If the Certificate is PEM encoded it should have a header of "X509
3817      CERTIFICATE", or "CERTIFICATE".
3818
3819      *Returns:* the number of certificates read or a negative error
3820      value.
3821
3822      *Since:* 3.0
3823
3824 gnutls_privkey_decrypt_data
3825 ---------------------------
3826
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)
3830      KEY: Holds the key
3831
3832      FLAGS: zero for now
3833
3834      CIPHERTEXT: holds the data to be decrypted
3835
3836      PLAINTEXT: will contain the decrypted data, allocated with
3837      'gnutls_malloc()'
3838
3839      This function will decrypt the given data using the algorithm
3840      supported by the private key.
3841
3842      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3843      otherwise a negative error value.
3844
3845      *Since:* 2.12.0
3846
3847 gnutls_privkey_deinit
3848 ---------------------
3849
3850  -- Function: void gnutls_privkey_deinit (gnutls_privkey_t KEY)
3851      KEY: The structure to be deinitialized
3852
3853      This function will deinitialize a private key structure.
3854
3855      *Since:* 2.12.0
3856
3857 gnutls_privkey_export_dsa_raw
3858 -----------------------------
3859
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
3864
3865      P: will hold the p
3866
3867      Q: will hold the q
3868
3869      G: will hold the g
3870
3871      Y: will hold the y
3872
3873      X: will hold the x
3874
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.
3878
3879      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3880      error code.
3881
3882      *Since:* 3.3.0
3883
3884 gnutls_privkey_export_ecc_raw
3885 -----------------------------
3886
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
3891
3892      CURVE: will hold the curve
3893
3894      X: will hold the x coordinate
3895
3896      Y: will hold the y coordinate
3897
3898      K: will hold the private key
3899
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.
3903
3904      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3905      error code.
3906
3907      *Since:* 3.3.0
3908
3909 gnutls_privkey_export_rsa_raw
3910 -----------------------------
3911
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
3917
3918      M: will hold the modulus
3919
3920      E: will hold the public exponent
3921
3922      D: will hold the private exponent
3923
3924      P: will hold the first prime (p)
3925
3926      Q: will hold the second prime (q)
3927
3928      U: will hold the coefficient
3929
3930      E1: will hold e1 = d mod (p-1)
3931
3932      E2: will hold e2 = d mod (q-1)
3933
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.
3937
3938      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3939      error code.
3940
3941      *Since:* 3.3.0
3942
3943 gnutls_privkey_generate
3944 -----------------------
3945
3946  -- Function: int gnutls_privkey_generate (gnutls_privkey_t PKEY,
3947           gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int
3948           FLAGS)
3949      PKEY: The private key
3950
3951      ALGO: is one of the algorithms in 'gnutls_pk_algorithm_t' .
3952
3953      BITS: the size of the modulus
3954
3955      FLAGS: unused for now.  Must be 0.
3956
3957      This function will generate a random private key.  Note that this
3958      function must be called on an empty private key.
3959
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.
3963
3964      Do not set the number of bits directly, use
3965      'gnutls_sec_param_to_pk_bits()' .
3966
3967      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3968      otherwise a negative error value.
3969
3970      *Since:* 3.3.0
3971
3972 gnutls_privkey_get_pk_algorithm
3973 -------------------------------
3974
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
3978
3979      BITS: If set will return the number of bits of the parameters (may
3980      be NULL)
3981
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.
3985
3986      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3987      success, or a negative error code on error.
3988
3989      *Since:* 2.12.0
3990
3991 gnutls_privkey_get_type
3992 -----------------------
3993
3994  -- Function: gnutls_privkey_type_t gnutls_privkey_get_type
3995           (gnutls_privkey_t KEY)
3996      KEY: should contain a 'gnutls_privkey_t' structure
3997
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.
4000
4001      *Returns:* a member of the 'gnutls_privkey_type_t' enumeration on
4002      success, or a negative error code on error.
4003
4004      *Since:* 2.12.0
4005
4006 gnutls_privkey_import_dsa_raw
4007 -----------------------------
4008
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
4012           gnutls_datum_t * X)
4013      KEY: The structure to store the parsed key
4014
4015      P: holds the p
4016
4017      Q: holds the q
4018
4019      G: holds the g
4020
4021      Y: holds the y
4022
4023      X: holds the x
4024
4025      This function will convert the given DSA raw parameters to the
4026      native 'gnutls_privkey_t' format.  The output will be stored in
4027      'key' .
4028
4029      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4030      otherwise a negative error value.
4031
4032 gnutls_privkey_import_ecc_raw
4033 -----------------------------
4034
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
4039
4040      CURVE: holds the curve
4041
4042      X: holds the x
4043
4044      Y: holds the y
4045
4046      K: holds the k
4047
4048      This function will convert the given elliptic curve parameters to
4049      the native 'gnutls_privkey_t' format.  The output will be stored in
4050      'key' .
4051
4052      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4053      otherwise a negative error value.
4054
4055      *Since:* 3.0
4056
4057 gnutls_privkey_import_ext
4058 -------------------------
4059
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
4065
4066      PK: The public key algorithm
4067
4068      USERDATA: private data to be provided to the callbacks
4069
4070      SIGN_FUNC: callback for signature operations
4071
4072      DECRYPT_FUNC: callback for decryption operations
4073
4074      FLAGS: Flags for the import
4075
4076      This function will associate the given callbacks with the
4077      'gnutls_privkey_t' structure.  At least one of the two callbacks
4078      must be non-null.
4079
4080      See also 'gnutls_privkey_import_ext2()' .
4081
4082      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4083      otherwise a negative error value.
4084
4085      *Since:* 3.0
4086
4087 gnutls_privkey_import_ext2
4088 --------------------------
4089
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
4096
4097      PK: The public key algorithm
4098
4099      USERDATA: private data to be provided to the callbacks
4100
4101      SIGN_FUNC: callback for signature operations
4102
4103      DECRYPT_FUNC: callback for decryption operations
4104
4105      DEINIT_FUNC: a deinitialization function
4106
4107      FLAGS: Flags for the import
4108
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' .
4113
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.
4118
4119      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4120      otherwise a negative error value.
4121
4122      *Since:* 3.1
4123
4124 gnutls_privkey_import_openpgp
4125 -----------------------------
4126
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
4130
4131      KEY: The private key to be imported
4132
4133      FLAGS: Flags for the import
4134
4135      This function will import the given private key to the abstract
4136      'gnutls_privkey_t' structure.
4137
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.
4141
4142      'flags' might be zero or one of
4143      'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4144      'GNUTLS_PRIVKEY_IMPORT_COPY' .
4145
4146      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4147      otherwise a negative error value.
4148
4149      *Since:* 2.12.0
4150
4151 gnutls_privkey_import_openpgp_raw
4152 ---------------------------------
4153
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 *
4157           PASSWORD)
4158      PKEY: The private key
4159
4160      DATA: The private key data to be imported
4161
4162      FORMAT: The format of the private key
4163
4164      KEYID: The key id to use (optional)
4165
4166      PASSWORD: A password (optional)
4167
4168      This function will import the given private key to the abstract
4169      'gnutls_privkey_t' structure.
4170
4171      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4172      otherwise a negative error value.
4173
4174      *Since:* 3.1.0
4175
4176 gnutls_privkey_import_pkcs11
4177 ----------------------------
4178
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
4182
4183      KEY: The private key to be imported
4184
4185      FLAGS: Flags for the import
4186
4187      This function will import the given private key to the abstract
4188      'gnutls_privkey_t' structure.
4189
4190      The 'gnutls_pkcs11_privkey_t' object must not be deallocated during
4191      the lifetime of this structure.
4192
4193      'flags' might be zero or one of
4194      'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4195      'GNUTLS_PRIVKEY_IMPORT_COPY' .
4196
4197      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4198      otherwise a negative error value.
4199
4200      *Since:* 2.12.0
4201
4202 gnutls_privkey_import_pkcs11_url
4203 --------------------------------
4204
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'
4208
4209      URL: A PKCS 11 url
4210
4211      This function will import a PKCS 11 private key to a
4212      'gnutls_private_key_t' structure.
4213
4214      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4215      otherwise a negative error value.
4216
4217      *Since:* 3.1.0
4218
4219 gnutls_privkey_import_rsa_raw
4220 -----------------------------
4221
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
4228
4229      M: holds the modulus
4230
4231      E: holds the public exponent
4232
4233      D: holds the private exponent
4234
4235      P: holds the first prime (p)
4236
4237      Q: holds the second prime (q)
4238
4239      U: holds the coefficient (optional)
4240
4241      E1: holds e1 = d mod (p-1) (optional)
4242
4243      E2: holds e2 = d mod (q-1) (optional)
4244
4245      This function will convert the given RSA raw parameters to the
4246      native 'gnutls_privkey_t' format.  The output will be stored in
4247      'key' .
4248
4249      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4250      otherwise a negative error value.
4251
4252 gnutls_privkey_import_tpm_raw
4253 -----------------------------
4254
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
4258           int FLAGS)
4259      PKEY: The private key
4260
4261      FDATA: The TPM key to be imported
4262
4263      FORMAT: The format of the private key
4264
4265      SRK_PASSWORD: The password for the SRK key (optional)
4266
4267      KEY_PASSWORD: A password for the key (optional)
4268
4269      FLAGS: should be zero
4270
4271      This function will import the given private key to the abstract
4272      'gnutls_privkey_t' structure.
4273
4274      With respect to passwords the same as in
4275      'gnutls_privkey_import_tpm_url()' apply.
4276
4277      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4278      otherwise a negative error value.
4279
4280      *Since:* 3.1.0
4281
4282 gnutls_privkey_import_tpm_url
4283 -----------------------------
4284
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
4289
4290      URL: The URL of the TPM key to be imported
4291
4292      SRK_PASSWORD: The password for the SRK key (optional)
4293
4294      KEY_PASSWORD: A password for the key (optional)
4295
4296      FLAGS: One of the GNUTLS_PRIVKEY_* flags
4297
4298      This function will import the given private key to the abstract
4299      'gnutls_privkey_t' structure.
4300
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.
4307
4308      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4309      otherwise a negative error value.
4310
4311      *Since:* 3.1.0
4312
4313 gnutls_privkey_import_url
4314 -------------------------
4315
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'
4319
4320      URL: A PKCS 11 url
4321
4322      FLAGS: should be zero
4323
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()' .
4327
4328      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4329      otherwise a negative error value.
4330
4331      *Since:* 3.1.0
4332
4333 gnutls_privkey_import_x509
4334 --------------------------
4335
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
4339
4340      KEY: The private key to be imported
4341
4342      FLAGS: Flags for the import
4343
4344      This function will import the given private key to the abstract
4345      'gnutls_privkey_t' structure.
4346
4347      The 'gnutls_x509_privkey_t' object must not be deallocated during
4348      the lifetime of this structure.
4349
4350      'flags' might be zero or one of
4351      'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' and
4352      'GNUTLS_PRIVKEY_IMPORT_COPY' .
4353
4354      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4355      otherwise a negative error value.
4356
4357      *Since:* 2.12.0
4358
4359 gnutls_privkey_import_x509_raw
4360 ------------------------------
4361
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
4366
4367      DATA: The private key data to be imported
4368
4369      FORMAT: The format of the private key
4370
4371      PASSWORD: A password (optional)
4372
4373      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
4374
4375      This function will import the given private key to the abstract
4376      'gnutls_privkey_t' structure.
4377
4378      The supported formats are basic unencrypted key, PKCS8, PKCS12, and
4379      the openssl format.
4380
4381      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4382      otherwise a negative error value.
4383
4384      *Since:* 3.1.0
4385
4386 gnutls_privkey_init
4387 -------------------
4388
4389  -- Function: int gnutls_privkey_init (gnutls_privkey_t * KEY)
4390      KEY: The structure to be initialized
4391
4392      This function will initialize an private key structure.
4393
4394      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4395      otherwise a negative error value.
4396
4397      *Since:* 2.12.0
4398
4399 gnutls_privkey_set_pin_function
4400 -------------------------------
4401
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'
4405
4406      FN: the callback
4407
4408      USERDATA: data associated with the callback
4409
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
4412      functions.
4413
4414      Note that this function must be called right after initialization
4415      to have effect.
4416
4417      *Since:* 3.1.0
4418
4419 gnutls_privkey_sign_data
4420 ------------------------
4421
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
4426
4427      HASH: should be a digest algorithm
4428
4429      FLAGS: Zero or one of 'gnutls_privkey_flags_t'
4430
4431      DATA: holds the data to be signed
4432
4433      SIGNATURE: will contain the signature allocate with
4434      'gnutls_malloc()'
4435
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
4440      keys.
4441
4442      You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
4443      determine the hash algorithm.
4444
4445      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4446      otherwise a negative error value.
4447
4448      *Since:* 2.12.0
4449
4450 gnutls_privkey_sign_hash
4451 ------------------------
4452
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
4457
4458      HASH_ALGO: The hash algorithm used
4459
4460      FLAGS: Zero or one of 'gnutls_privkey_flags_t'
4461
4462      HASH_DATA: holds the data to be signed
4463
4464      SIGNATURE: will contain newly allocated signature
4465
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
4470      the DSA keys.
4471
4472      You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
4473      determine the hash algorithm.
4474
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
4477      signature.
4478
4479      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4480      otherwise a negative error value.
4481
4482      *Since:* 2.12.0
4483
4484 gnutls_privkey_status
4485 ---------------------
4486
4487  -- Function: int gnutls_privkey_status (gnutls_privkey_t KEY)
4488      KEY: Holds the key
4489
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
4493      inserted or not.
4494
4495      *Returns:* this function will return non-zero if the token holding
4496      the private key is still available (inserted), and zero otherwise.
4497
4498      *Since:* 3.1.10
4499
4500 gnutls_privkey_verify_params
4501 ----------------------------
4502
4503  -- Function: int gnutls_privkey_verify_params (gnutls_privkey_t KEY)
4504      KEY: should contain a 'gnutls_privkey_t' structure
4505
4506      This function will verify the private key parameters.
4507
4508      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4509      otherwise a negative error value.
4510
4511      *Since:* 3.3.0
4512
4513 gnutls_pubkey_deinit
4514 --------------------
4515
4516  -- Function: void gnutls_pubkey_deinit (gnutls_pubkey_t KEY)
4517      KEY: The structure to be deinitialized
4518
4519      This function will deinitialize a public key structure.
4520
4521      *Since:* 2.12.0
4522
4523 gnutls_pubkey_encrypt_data
4524 --------------------------
4525
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
4530
4531      FLAGS: should be 0 for now
4532
4533      PLAINTEXT: The data to be encrypted
4534
4535      CIPHERTEXT: contains the encrypted data
4536
4537      This function will encrypt the given data, using the public key.
4538
4539      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4540      otherwise a negative error value.
4541
4542      *Since:* 3.0
4543
4544 gnutls_pubkey_export
4545 --------------------
4546
4547  -- Function: int gnutls_pubkey_export (gnutls_pubkey_t KEY,
4548           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
4549           OUTPUT_DATA_SIZE)
4550      KEY: Holds the certificate
4551
4552      FORMAT: the format of output params.  One of PEM or DER.
4553
4554      OUTPUT_DATA: will contain a certificate PEM or DER encoded
4555
4556      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4557      replaced by the actual size of parameters)
4558
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
4561      structure.
4562
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'
4565      will be returned.
4566
4567      If the structure is PEM encoded, it will have a header of "BEGIN
4568      CERTIFICATE".
4569
4570      *Returns:* In case of failure a negative error code will be
4571      returned, and 0 on success.
4572
4573      *Since:* 2.12.0
4574
4575 gnutls_pubkey_export2
4576 ---------------------
4577
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
4581
4582      FORMAT: the format of output params.  One of PEM or DER.
4583
4584      OUT: will contain a certificate PEM or DER encoded
4585
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
4588      structure.
4589
4590      The output buffer will be allocated using 'gnutls_malloc()' .
4591
4592      If the structure is PEM encoded, it will have a header of "BEGIN
4593      CERTIFICATE".
4594
4595      *Returns:* In case of failure a negative error code will be
4596      returned, and 0 on success.
4597
4598      *Since:* 3.1.3
4599
4600 gnutls_pubkey_export_dsa_raw
4601 ----------------------------
4602
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,
4605           gnutls_datum_t * Y)
4606      KEY: Holds the public key
4607
4608      P: will hold the p
4609
4610      Q: will hold the q
4611
4612      G: will hold the g
4613
4614      Y: will hold the y
4615
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.
4619
4620      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4621      error code.
4622
4623      *Since:* 3.3.0
4624
4625 gnutls_pubkey_export_ecc_raw
4626 ----------------------------
4627
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
4630           * Y)
4631      KEY: Holds the public key
4632
4633      CURVE: will hold the curve
4634
4635      X: will hold x
4636
4637      Y: will hold y
4638
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.
4642
4643      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4644      error code.
4645
4646      *Since:* 3.0
4647
4648 gnutls_pubkey_export_ecc_x962
4649 -----------------------------
4650
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
4654
4655      PARAMETERS: DER encoding of an ANSI X9.62 parameters
4656
4657      ECPOINT: DER encoding of ANSI X9.62 ECPoint
4658
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.
4662
4663      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4664      error code.
4665
4666      *Since:* 3.3.0
4667
4668 gnutls_pubkey_export_rsa_raw
4669 ----------------------------
4670
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
4674
4675      M: will hold the modulus
4676
4677      E: will hold the public exponent
4678
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.
4682
4683      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4684      error code.
4685
4686      *Since:* 3.3.0
4687
4688 gnutls_pubkey_get_key_id
4689 ------------------------
4690
4691  -- Function: int gnutls_pubkey_get_key_id (gnutls_pubkey_t KEY,
4692           unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
4693           OUTPUT_DATA_SIZE)
4694      KEY: Holds the public key
4695
4696      FLAGS: should be 0 for now
4697
4698      OUTPUT_DATA: will contain the key ID
4699
4700      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4701      replaced by the actual size of parameters)
4702
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.
4706
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,
4710      which is 20 bytes.
4711
4712      *Returns:* In case of failure a negative error code will be
4713      returned, and 0 on success.
4714
4715      *Since:* 2.12.0
4716
4717 gnutls_pubkey_get_key_usage
4718 ---------------------------
4719
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
4723
4724      USAGE: If set will return the number of bits of the parameters (may
4725      be NULL)
4726
4727      This function will return the key usage of the public key.
4728
4729      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4730      otherwise a negative error value.
4731
4732      *Since:* 2.12.0
4733
4734 gnutls_pubkey_get_openpgp_key_id
4735 --------------------------------
4736
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
4741
4742      FLAGS: should be 0 or 'GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT'
4743
4744      OUTPUT_DATA: will contain the key ID
4745
4746      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
4747      replaced by the actual size of parameters)
4748
4749      SUBKEY: Will be non zero if the key ID corresponds to a subkey
4750
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.
4753
4754      If the flag 'GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT' is specified
4755      this function returns the fingerprint of the master key.
4756
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
4760      long.
4761
4762      *Returns:* In case of failure a negative error code will be
4763      returned, and 0 on success.
4764
4765      *Since:* 3.0
4766
4767 gnutls_pubkey_get_pk_algorithm
4768 ------------------------------
4769
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
4773
4774      BITS: If set will return the number of bits of the parameters (may
4775      be NULL)
4776
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.
4780
4781      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
4782      success, or a negative error code on error.
4783
4784      *Since:* 2.12.0
4785
4786 gnutls_pubkey_get_preferred_hash_algorithm
4787 ------------------------------------------
4788
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
4793
4794      HASH: The result of the call with the hash algorithm used for
4795      signature
4796
4797      MAND: If non zero it means that the algorithm MUST use this hash.
4798      May be NULL.
4799
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).
4804
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' .
4808
4809      *Returns:* the 0 if the hash algorithm is found.  A negative error
4810      code is returned on error.
4811
4812      *Since:* 2.12.0
4813
4814 gnutls_pubkey_get_verify_algorithm
4815 ----------------------------------
4816
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
4821
4822      SIGNATURE: contains the signature
4823
4824      HASH: The result of the call with the hash algorithm used for
4825      signature
4826
4827      This function will read the certifcate and the signed data to
4828      determine the hash algorithm used to generate the signature.
4829
4830      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4831      otherwise a negative error value.
4832
4833      *Since:* 2.12.0
4834
4835 gnutls_pubkey_import
4836 --------------------
4837
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.
4841
4842      DATA: The DER or PEM encoded certificate.
4843
4844      FORMAT: One of DER or PEM
4845
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".
4850
4851      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4852      otherwise a negative error value.
4853
4854      *Since:* 2.12.0
4855
4856 gnutls_pubkey_import_dsa_raw
4857 ----------------------------
4858
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
4863
4864      P: holds the p
4865
4866      Q: holds the q
4867
4868      G: holds the g
4869
4870      Y: holds the y
4871
4872      This function will convert the given DSA raw parameters to the
4873      native 'gnutls_pubkey_t' format.  The output will be stored in
4874      'key' .
4875
4876      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4877      otherwise a negative error value.
4878
4879      *Since:* 2.12.0
4880
4881 gnutls_pubkey_import_ecc_raw
4882 ----------------------------
4883
4884  -- Function: int gnutls_pubkey_import_ecc_raw (gnutls_pubkey_t KEY,
4885           gnutls_ecc_curve_t CURVE, const gnutls_datum_t * X, const
4886           gnutls_datum_t * Y)
4887      KEY: The structure to store the parsed key
4888
4889      CURVE: holds the curve
4890
4891      X: holds the x
4892
4893      Y: holds the y
4894
4895      This function will convert the given elliptic curve parameters to a
4896      'gnutls_pubkey_t' .  The output will be stored in 'key' .
4897
4898      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4899      otherwise a negative error value.
4900
4901      *Since:* 3.0
4902
4903 gnutls_pubkey_import_ecc_x962
4904 -----------------------------
4905
4906  -- Function: int gnutls_pubkey_import_ecc_x962 (gnutls_pubkey_t KEY,
4907           const gnutls_datum_t * PARAMETERS, const gnutls_datum_t *
4908           ECPOINT)
4909      KEY: The structure to store the parsed key
4910
4911      PARAMETERS: DER encoding of an ANSI X9.62 parameters
4912
4913      ECPOINT: DER encoding of ANSI X9.62 ECPoint
4914
4915      This function will convert the given elliptic curve parameters to a
4916      'gnutls_pubkey_t' .  The output will be stored in 'key' .
4917
4918      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4919      otherwise a negative error value.
4920
4921      *Since:* 3.0
4922
4923 gnutls_pubkey_import_openpgp
4924 ----------------------------
4925
4926  -- Function: int gnutls_pubkey_import_openpgp (gnutls_pubkey_t KEY,
4927           gnutls_openpgp_crt_t CRT, unsigned int FLAGS)
4928      KEY: The public key
4929
4930      CRT: The certificate to be imported
4931
4932      FLAGS: should be zero
4933
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.
4938
4939      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4940      otherwise a negative error value.
4941
4942      *Since:* 2.12.0
4943
4944 gnutls_pubkey_import_openpgp_raw
4945 --------------------------------
4946
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
4950           FLAGS)
4951      PKEY: The public key
4952
4953      DATA: The public key data to be imported
4954
4955      FORMAT: The format of the public key
4956
4957      KEYID: The key id to use (optional)
4958
4959      FLAGS: Should be zero
4960
4961      This function will import the given public key to the abstract
4962      'gnutls_pubkey_t' structure.
4963
4964      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4965      otherwise a negative error value.
4966
4967      *Since:* 3.1.3
4968
4969 gnutls_pubkey_import_pkcs11
4970 ---------------------------
4971
4972  -- Function: int gnutls_pubkey_import_pkcs11 (gnutls_pubkey_t KEY,
4973           gnutls_pkcs11_obj_t OBJ, unsigned int FLAGS)
4974      KEY: The public key
4975
4976      OBJ: The parameters to be imported
4977
4978      FLAGS: should be zero
4979
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.
4982
4983      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4984      otherwise a negative error value.
4985
4986      *Since:* 2.12.0
4987
4988 gnutls_pubkey_import_pkcs11_url
4989 -------------------------------
4990
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'
4994
4995      URL: A PKCS 11 url
4996
4997      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
4998
4999      This function will import a PKCS 11 certificate to a
5000      'gnutls_pubkey_t' structure.
5001
5002      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5003      otherwise a negative error value.
5004
5005      *Since:* 2.12.0
5006
5007 gnutls_pubkey_import_privkey
5008 ----------------------------
5009
5010  -- Function: int gnutls_pubkey_import_privkey (gnutls_pubkey_t KEY,
5011           gnutls_privkey_t PKEY, unsigned int USAGE, unsigned int FLAGS)
5012      KEY: The public key
5013
5014      PKEY: The private key
5015
5016      USAGE: GNUTLS_KEY_* key usage flags.
5017
5018      FLAGS: should be zero
5019
5020      Imports the public key from a private.  This function will import
5021      the given public key to the abstract 'gnutls_pubkey_t' structure.
5022
5023      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5024      otherwise a negative error value.
5025
5026      *Since:* 2.12.0
5027
5028 gnutls_pubkey_import_rsa_raw
5029 ----------------------------
5030
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
5034
5035      M: holds the modulus
5036
5037      E: holds the public exponent
5038
5039      This function will replace the parameters in the given structure.
5040      The new parameters should be stored in the appropriate
5041      gnutls_datum.
5042
5043      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an negative error
5044      code.
5045
5046      *Since:* 2.12.0
5047
5048 gnutls_pubkey_import_tpm_raw
5049 ----------------------------
5050
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
5055
5056      FDATA: The TPM key to be imported
5057
5058      FORMAT: The format of the private key
5059
5060      SRK_PASSWORD: The password for the SRK key (optional)
5061
5062      FLAGS: One of the GNUTLS_PUBKEY_* flags
5063
5064      This function will import the public key from the provided TPM key
5065      structure.
5066
5067      With respect to passwords the same as in
5068      'gnutls_pubkey_import_tpm_url()' apply.
5069
5070      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5071      otherwise a negative error value.
5072
5073      *Since:* 3.1.0
5074
5075 gnutls_pubkey_import_tpm_url
5076 ----------------------------
5077
5078  -- Function: int gnutls_pubkey_import_tpm_url (gnutls_pubkey_t PKEY,
5079           const char * URL, const char * SRK_PASSWORD, unsigned int
5080           FLAGS)
5081      PKEY: The public key
5082
5083      URL: The URL of the TPM key to be imported
5084
5085      SRK_PASSWORD: The password for the SRK key (optional)
5086
5087      FLAGS: should be zero
5088
5089      This function will import the given private key to the abstract
5090      'gnutls_privkey_t' structure.
5091
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
5096      returned.
5097
5098      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5099      otherwise a negative error value.
5100
5101      *Since:* 3.1.0
5102
5103 gnutls_pubkey_import_url
5104 ------------------------
5105
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'
5109
5110      URL: A PKCS 11 url
5111
5112      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
5113
5114      This function will import a PKCS11 certificate or a TPM key as a
5115      public key.
5116
5117      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5118      otherwise a negative error value.
5119
5120      *Since:* 3.1.0
5121
5122 gnutls_pubkey_import_x509
5123 -------------------------
5124
5125  -- Function: int gnutls_pubkey_import_x509 (gnutls_pubkey_t KEY,
5126           gnutls_x509_crt_t CRT, unsigned int FLAGS)
5127      KEY: The public key
5128
5129      CRT: The certificate to be imported
5130
5131      FLAGS: should be zero
5132
5133      This function will import the given public key to the abstract
5134      'gnutls_pubkey_t' structure.
5135
5136      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5137      otherwise a negative error value.
5138
5139      *Since:* 2.12.0
5140
5141 gnutls_pubkey_import_x509_crq
5142 -----------------------------
5143
5144  -- Function: int gnutls_pubkey_import_x509_crq (gnutls_pubkey_t KEY,
5145           gnutls_x509_crq_t CRQ, unsigned int FLAGS)
5146      KEY: The public key
5147
5148      CRQ: The certificate to be imported
5149
5150      FLAGS: should be zero
5151
5152      This function will import the given public key to the abstract
5153      'gnutls_pubkey_t' structure.
5154
5155      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5156      otherwise a negative error value.
5157
5158      *Since:* 3.1.5
5159
5160 gnutls_pubkey_import_x509_raw
5161 -----------------------------
5162
5163  -- Function: int gnutls_pubkey_import_x509_raw (gnutls_pubkey_t PKEY,
5164           const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT,
5165           unsigned int FLAGS)
5166      PKEY: The public key
5167
5168      DATA: The public key data to be imported
5169
5170      FORMAT: The format of the public key
5171
5172      FLAGS: should be zero
5173
5174      This function will import the given public key to the abstract
5175      'gnutls_pubkey_t' structure.
5176
5177      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5178      otherwise a negative error value.
5179
5180      *Since:* 3.1.3
5181
5182 gnutls_pubkey_init
5183 ------------------
5184
5185  -- Function: int gnutls_pubkey_init (gnutls_pubkey_t * KEY)
5186      KEY: The structure to be initialized
5187
5188      This function will initialize an public key structure.
5189
5190      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5191      otherwise a negative error value.
5192
5193      *Since:* 2.12.0
5194
5195 gnutls_pubkey_print
5196 -------------------
5197
5198  -- Function: int gnutls_pubkey_print (gnutls_pubkey_t PUBKEY,
5199           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
5200           OUT)
5201      PUBKEY: The structure to be printed
5202
5203      FORMAT: Indicate the format to use
5204
5205      OUT: Newly allocated datum with (0) terminated string.
5206
5207      This function will pretty print public key information, suitable
5208      for display to a human.
5209
5210      Only 'GNUTLS_CRT_PRINT_FULL' and 'GNUTLS_CRT_PRINT_FULL_NUMBERS'
5211      are implemented.
5212
5213      The output 'out' needs to be deallocated using 'gnutls_free()' .
5214
5215      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5216      otherwise a negative error value.
5217
5218      *Since:* 3.1.5
5219
5220 gnutls_pubkey_set_key_usage
5221 ---------------------------
5222
5223  -- Function: int gnutls_pubkey_set_key_usage (gnutls_pubkey_t KEY,
5224           unsigned int USAGE)
5225      KEY: a certificate of type 'gnutls_x509_crt_t'
5226
5227      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
5228
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.
5232
5233      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5234      otherwise a negative error value.
5235
5236      *Since:* 2.12.0
5237
5238 gnutls_pubkey_set_pin_function
5239 ------------------------------
5240
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'
5244
5245      FN: the callback
5246
5247      USERDATA: data associated with the callback
5248
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
5251      functions.
5252
5253      Note that this function must be called right after initialization
5254      to have effect.
5255
5256      *Since:* 3.1.0
5257
5258 gnutls_pubkey_verify_data
5259 -------------------------
5260
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
5265
5266      FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5267
5268      DATA: holds the signed data
5269
5270      SIGNATURE: contains the signature
5271
5272      This function will verify the given signed data, using the
5273      parameters from the certificate.
5274
5275      Deprecated.  This function cannot be easily used securely.  Use
5276      'gnutls_pubkey_verify_data2()' instead.
5277
5278      *Returns:* In case of a verification failure
5279      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5280      code on success.
5281
5282      *Since:* 2.12.0
5283
5284 gnutls_pubkey_verify_data2
5285 --------------------------
5286
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
5291
5292      ALGO: The signature algorithm used
5293
5294      FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5295
5296      DATA: holds the signed data
5297
5298      SIGNATURE: contains the signature
5299
5300      This function will verify the given signed data, using the
5301      parameters from the certificate.
5302
5303      *Returns:* In case of a verification failure
5304      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5305      code on success.
5306
5307      *Since:* 3.0
5308
5309 gnutls_pubkey_verify_hash
5310 -------------------------
5311
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
5316
5317      FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5318
5319      HASH: holds the hash digest to be verified
5320
5321      SIGNATURE: contains the signature
5322
5323      This function will verify the given signed digest, using the
5324      parameters from the public key.
5325
5326      Deprecated.  This function cannot be easily used securely.  Use
5327      'gnutls_pubkey_verify_hash2()' instead.
5328
5329      *Returns:* In case of a verification failure
5330      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5331      code on success.
5332
5333      *Since:* 2.12.0
5334
5335 gnutls_pubkey_verify_hash2
5336 --------------------------
5337
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
5342
5343      ALGO: The signature algorithm used
5344
5345      FLAGS: Zero or one of 'gnutls_pubkey_flags_t'
5346
5347      HASH: holds the hash digest to be verified
5348
5349      SIGNATURE: contains the signature
5350
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.
5356
5357      *Returns:* In case of a verification failure
5358      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5359      code on success.
5360
5361      *Since:* 3.0
5362
5363 gnutls_pubkey_verify_params
5364 ---------------------------
5365
5366  -- Function: int gnutls_pubkey_verify_params (gnutls_pubkey_t KEY)
5367      KEY: should contain a 'gnutls_pubkey_t' structure
5368
5369      This function will verify the private key parameters.
5370
5371      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5372      otherwise a negative error value.
5373
5374      *Since:* 3.3.0
5375
5376 gnutls_x509_crl_privkey_sign
5377 ----------------------------
5378
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
5383
5384      ISSUER: is the certificate of the certificate issuer
5385
5386      ISSUER_KEY: holds the issuer's private key
5387
5388      DIG: The message digest to use.  GNUTLS_DIG_SHA1 is the safe choice
5389      unless you know what you're doing.
5390
5391      FLAGS: must be 0
5392
5393      This function will sign the CRL with the issuer's private key, and
5394      will copy the issuer's information into the CRL.
5395
5396      This must be the last step in a certificate CRL since all the
5397      previously set parameters are now signed.
5398
5399      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5400      otherwise a negative error value.
5401
5402      Since 2.12.0
5403
5404 gnutls_x509_crq_privkey_sign
5405 ----------------------------
5406
5407  -- Function: int gnutls_x509_crq_privkey_sign (gnutls_x509_crq_t CRQ,
5408           gnutls_privkey_t KEY, gnutls_digest_algorithm_t DIG, unsigned
5409           int FLAGS)
5410      CRQ: should contain a 'gnutls_x509_crq_t' structure
5411
5412      KEY: holds a private key
5413
5414      DIG: The message digest to use, i.e., 'GNUTLS_DIG_SHA1'
5415
5416      FLAGS: must be 0
5417
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
5421      signed.
5422
5423      This must be the last step in a certificate request generation
5424      since all the previously set parameters are now signed.
5425
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()' ).
5430
5431      *Since:* 2.12.0
5432
5433 gnutls_x509_crq_set_pubkey
5434 --------------------------
5435
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
5439
5440      KEY: holds a public key
5441
5442      This function will set the public parameters from the given public
5443      key to the request.
5444
5445      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5446      otherwise a negative error value.
5447
5448      *Since:* 2.12.0
5449
5450 gnutls_x509_crt_privkey_sign
5451 ----------------------------
5452
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'
5457
5458      ISSUER: is the certificate of the certificate issuer
5459
5460      ISSUER_KEY: holds the issuer's private key
5461
5462      DIG: The message digest to use, 'GNUTLS_DIG_SHA1' is a safe choice
5463
5464      FLAGS: must be 0
5465
5466      This function will sign the certificate with the issuer's private
5467      key, and will copy the issuer's information into the certificate.
5468
5469      This must be the last step in a certificate generation since all
5470      the previously set parameters are now signed.
5471
5472      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5473      otherwise a negative error value.
5474
5475 gnutls_x509_crt_set_pubkey
5476 --------------------------
5477
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
5481
5482      KEY: holds a public key
5483
5484      This function will set the public parameters from the given public
5485      key to the request.
5486
5487      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5488      otherwise a negative error value.
5489
5490      *Since:* 2.12.0
5491