doc/gnutls.info-4

   1 This is gnutls.info, produced by makeinfo version 6.3 from gnutls.texi.
   2
   3 This manual is last updated 23 March 2015 for version 3.3.27 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: A pointer to the type 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' type
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: A pointer to the type 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: should contain a gnutls_pkcs12_t structure
2496
2497      PASSWORD: optional password used to decrypt the structure, 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 structure (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 structure in 'pkcs12' and extracts
2519      the private key, the corresponding certificate chain, any
2520      additional certificates and a CRL.
2521
2522      The 'extra_certs' and 'extra_certs_len' parameters are optional and
2523      both may be set to 'NULL' .  If either is non-'NULL' , then both
2524      must be set.  The value for 'extra_certs' is allocated using
2525      'gnutls_malloc()' .
2526
2527      Encrypted PKCS12 bags and PKCS8 private keys are supported, but
2528      only with password based security and the same password for all
2529      operations.
2530
2531      Note that a PKCS12 structure may contain many keys and/or
2532      certificates, and there is no way to identify which key/certificate
2533      pair you want.  For this reason this function is useful for PKCS12
2534      files that contain only one key/certificate pair and/or one CRL.
2535
2536      If the provided structure has encrypted fields but no password is
2537      provided then this function returns 'GNUTLS_E_DECRYPTION_FAILED' .
2538
2539      Note that normally the chain constructed does not include self
2540      signed certificates, to comply with TLS' requirements.  If,
2541      however, the flag 'GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED' is
2542      specified then self signed certificates will be included in the
2543      chain.
2544
2545      Prior to using this function the PKCS '12' structure integrity must
2546      be verified using 'gnutls_pkcs12_verify_mac()' .
2547
2548      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2549      otherwise a negative error value.
2550
2551      *Since:* 3.1.0
2552
2553 gnutls_pkcs12_verify_mac
2554 ------------------------
2555
2556  -- Function: int gnutls_pkcs12_verify_mac (gnutls_pkcs12_t PKCS12,
2557           const char * PASS)
2558      PKCS12: should contain a gnutls_pkcs12_t structure
2559
2560      PASS: The password for the MAC
2561
2562      This function will verify the MAC for the PKCS12 structure.
2563
2564      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2565      otherwise a negative error value.
2566
2567 \1f
2568 File: gnutls.info,  Node: PKCS 11 API,  Next: TPM API,  Prev: PKCS 12 API,  Up: API reference
2569
2570 E.7 Hardware token via PKCS 11 API
2571 ==================================
2572
2573 The following functions are to be used for PKCS 11 handling.  Their
2574 prototypes lie in 'gnutls/pkcs11.h'.
2575
2576 gnutls_pkcs11_add_provider
2577 --------------------------
2578
2579  -- Function: int gnutls_pkcs11_add_provider (const char * NAME, const
2580           char * PARAMS)
2581      NAME: The filename of the module
2582
2583      PARAMS: should be NULL
2584
2585      This function will load and add a PKCS 11 module to the module list
2586      used in gnutls.  After this function is called the module will be
2587      used for PKCS 11 operations.
2588
2589      When loading a module to be used for certificate verification, use
2590      the string 'trusted' as 'params' .
2591
2592      Note that this function is not thread safe.
2593
2594      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2595      otherwise a negative error value.
2596
2597      *Since:* 2.12.0
2598
2599 gnutls_pkcs11_copy_secret_key
2600 -----------------------------
2601
2602  -- Function: int gnutls_pkcs11_copy_secret_key (const char * TOKEN_URL,
2603           gnutls_datum_t * KEY, const char * LABEL, unsigned int
2604           KEY_USAGE, unsigned int FLAGS)
2605      TOKEN_URL: A PKCS '11' URL specifying a token
2606
2607      KEY: The raw key
2608
2609      LABEL: A name to be used for the stored data
2610
2611      KEY_USAGE: One of GNUTLS_KEY_*
2612
2613      FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2614
2615      This function will copy a raw secret (symmetric) key into a PKCS
2616      '11' token specified by a URL. The key can be marked as sensitive
2617      or not.
2618
2619      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2620      otherwise a negative error value.
2621
2622      *Since:* 2.12.0
2623
2624 gnutls_pkcs11_copy_x509_crt
2625 ---------------------------
2626
2627  -- Function: int gnutls_pkcs11_copy_x509_crt (const char * TOKEN_URL,
2628           gnutls_x509_crt_t CRT, const char * LABEL, unsigned int FLAGS)
2629      TOKEN_URL: A PKCS '11' URL specifying a token
2630
2631      CRT: The certificate to copy
2632
2633      LABEL: The name to be used for the stored data
2634
2635      FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2636
2637      This function will copy a certificate into a PKCS '11' token
2638      specified by a URL. The certificate can be marked as trusted or
2639      not.
2640
2641      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2642      otherwise a negative error value.
2643
2644      *Since:* 2.12.0
2645
2646 gnutls_pkcs11_copy_x509_crt2
2647 ----------------------------
2648
2649  -- Function: int gnutls_pkcs11_copy_x509_crt2 (const char * TOKEN_URL,
2650           gnutls_x509_crt_t CRT, const char * LABEL, const
2651           gnutls_datum_t * CID, unsigned int FLAGS)
2652      TOKEN_URL: A PKCS '11' URL specifying a token
2653
2654      CRT: The certificate to copy
2655
2656      LABEL: The name to be used for the stored data
2657
2658      CID: The CKA_ID to set for the object -if NULL, the ID will be
2659      derived from the public key
2660
2661      FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
2662
2663      This function will copy a certificate into a PKCS '11' token
2664      specified by a URL. The certificate can be marked as trusted or
2665      not.
2666
2667      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2668      otherwise a negative error value.
2669
2670      *Since:* 3.3.26
2671
2672 gnutls_pkcs11_copy_x509_privkey
2673 -------------------------------
2674
2675  -- Function: int gnutls_pkcs11_copy_x509_privkey (const char *
2676           TOKEN_URL, gnutls_x509_privkey_t KEY, const char * LABEL,
2677           unsigned int KEY_USAGE, unsigned int FLAGS)
2678      TOKEN_URL: A PKCS '11' URL specifying a token
2679
2680      KEY: A private key
2681
2682      LABEL: A name to be used for the stored data
2683
2684      KEY_USAGE: One of GNUTLS_KEY_*
2685
2686      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2687
2688      This function will copy a private key into a PKCS '11' token
2689      specified by a URL. It is highly recommended flags to contain
2690      'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' unless there is a strong
2691      reason not to.
2692
2693      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2694      otherwise a negative error value.
2695
2696      *Since:* 2.12.0
2697
2698 gnutls_pkcs11_copy_x509_privkey2
2699 --------------------------------
2700
2701  -- Function: int gnutls_pkcs11_copy_x509_privkey2 (const char *
2702           TOKEN_URL, gnutls_x509_privkey_t KEY, const char * LABEL,
2703           const gnutls_datum_t * CID, unsigned int KEY_USAGE, unsigned
2704           int FLAGS)
2705      TOKEN_URL: A PKCS '11' URL specifying a token
2706
2707      KEY: A private key
2708
2709      LABEL: A name to be used for the stored data
2710
2711      CID: The CKA_ID to set for the object -if NULL, the ID will be
2712      derived from the public key
2713
2714      KEY_USAGE: One of GNUTLS_KEY_*
2715
2716      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2717
2718      This function will copy a private key into a PKCS '11' token
2719      specified by a URL. It is highly recommended flags to contain
2720      'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' unless there is a strong
2721      reason not to.
2722
2723      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2724      otherwise a negative error value.
2725
2726      *Since:* 3.3.26
2727
2728 gnutls_pkcs11_crt_is_known
2729 --------------------------
2730
2731  -- Function: int gnutls_pkcs11_crt_is_known (const char * URL,
2732           gnutls_x509_crt_t CERT, unsigned int FLAGS)
2733      URL: A PKCS 11 url identifying a token
2734
2735      CERT: is the certificate to find issuer for
2736
2737      FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2738
2739      This function will check whether the provided certificate is stored
2740      in the specified token.  This is useful in combination with
2741      'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED' or
2742      'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED' , to check whether a
2743      CA is present or a certificate is blacklisted in a trust PKCS '11'
2744      module.
2745
2746      This function can be used with a 'url' of "pkcs11:", and in that
2747      case all modules will be searched.  To restrict the modules to the
2748      marked as trusted in p11-kit use the
2749      'GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE' flag.
2750
2751      Note that the flag 'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED' is
2752      specific to p11-kit trust modules.
2753
2754      *Returns:* If the certificate exists non-zero is returned,
2755      otherwise zero.
2756
2757      *Since:* 3.3.0
2758
2759 gnutls_pkcs11_deinit
2760 --------------------
2761
2762  -- Function: void gnutls_pkcs11_deinit ( VOID)
2763
2764      This function will deinitialize the PKCS 11 subsystem in gnutls.
2765      This function is only needed if you need to deinitialize the
2766      subsystem without calling 'gnutls_global_deinit()' .
2767
2768      *Since:* 2.12.0
2769
2770 gnutls_pkcs11_delete_url
2771 ------------------------
2772
2773  -- Function: int gnutls_pkcs11_delete_url (const char * OBJECT_URL,
2774           unsigned int FLAGS)
2775      OBJECT_URL: The URL of the object to delete.
2776
2777      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
2778
2779      This function will delete objects matching the given URL. Note that
2780      not all tokens support the delete operation.
2781
2782      *Returns:* On success, the number of objects deleted is returned,
2783      otherwise a negative error value.
2784
2785      *Since:* 2.12.0
2786
2787 gnutls_pkcs11_get_pin_function
2788 ------------------------------
2789
2790  -- Function: gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void
2791           ** USERDATA)
2792      USERDATA: data to be supplied to callback
2793
2794      This function will return the callback function set using
2795      'gnutls_pkcs11_set_pin_function()' .
2796
2797      *Returns:* The function set or NULL otherwise.
2798
2799      *Since:* 3.1.0
2800
2801 gnutls_pkcs11_get_raw_issuer
2802 ----------------------------
2803
2804  -- Function: int gnutls_pkcs11_get_raw_issuer (const char * URL,
2805           gnutls_x509_crt_t CERT, gnutls_datum_t * ISSUER,
2806           gnutls_x509_crt_fmt_t FMT, unsigned int FLAGS)
2807      URL: A PKCS 11 url identifying a token
2808
2809      CERT: is the certificate to find issuer for
2810
2811      ISSUER: Will hold the issuer if any in an allocated buffer.
2812
2813      FMT: The format of the exported issuer.
2814
2815      FLAGS: Use zero or flags from 'GNUTLS_PKCS11_OBJ_FLAG' .
2816
2817      This function will return the issuer of a given certificate, if it
2818      is stored in the token.  By default only marked as trusted issuers
2819      are retuned.  If any issuer should be returned specify
2820      'GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY' in 'flags' .
2821
2822      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2823      otherwise a negative error value.
2824
2825      *Since:* 3.2.7
2826
2827 gnutls_pkcs11_init
2828 ------------------
2829
2830  -- Function: int gnutls_pkcs11_init (unsigned int FLAGS, const char *
2831           DEPRECATED_CONFIG_FILE)
2832      FLAGS: An ORed sequence of 'GNUTLS_PKCS11_FLAG_' *
2833
2834      DEPRECATED_CONFIG_FILE: either NULL or the location of a deprecated
2835      configuration file
2836
2837      This function will initialize the PKCS 11 subsystem in gnutls.  It
2838      will read configuration files if 'GNUTLS_PKCS11_FLAG_AUTO' is used
2839      or allow you to independently load PKCS 11 modules using
2840      'gnutls_pkcs11_add_provider()' if 'GNUTLS_PKCS11_FLAG_MANUAL' is
2841      specified.
2842
2843      Normally you don't need to call this function since it is being
2844      called when the first PKCS 11 operation is requested using the
2845      'GNUTLS_PKCS11_FLAG_AUTO' flag.  If another flags are required then
2846      it must be called independently prior to any PKCS 11 operation.
2847
2848      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2849      otherwise a negative error value.
2850
2851      *Since:* 2.12.0
2852
2853 gnutls_pkcs11_obj_deinit
2854 ------------------------
2855
2856  -- Function: void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t OBJ)
2857      OBJ: The structure to be initialized
2858
2859      This function will deinitialize a certificate structure.
2860
2861      *Since:* 2.12.0
2862
2863 gnutls_pkcs11_obj_export
2864 ------------------------
2865
2866  -- Function: int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t OBJ,
2867           void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)
2868      OBJ: Holds the object
2869
2870      OUTPUT_DATA: will contain the object data
2871
2872      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2873      replaced by the actual size of parameters)
2874
2875      This function will export the PKCS11 object data.  It is normal for
2876      data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2877      will be returned.
2878
2879      If the buffer provided is not long enough to hold the output, then
2880      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2881      be returned.
2882
2883      *Returns:* In case of failure a negative error code will be
2884      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2885
2886      *Since:* 2.12.0
2887
2888 gnutls_pkcs11_obj_export2
2889 -------------------------
2890
2891  -- Function: int gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t OBJ,
2892           gnutls_datum_t * OUT)
2893      OBJ: Holds the object
2894
2895      OUT: will contain the object data
2896
2897      This function will export the PKCS11 object data.  It is normal for
2898      data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2899      will be returned.
2900
2901      The output buffer is allocated using 'gnutls_malloc()' .
2902
2903      *Returns:* In case of failure a negative error code will be
2904      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2905
2906      *Since:* 3.1.3
2907
2908 gnutls_pkcs11_obj_export3
2909 -------------------------
2910
2911  -- Function: int gnutls_pkcs11_obj_export3 (gnutls_pkcs11_obj_t OBJ,
2912           gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * OUT)
2913      OBJ: Holds the object
2914
2915      FMT: The format of the exported data
2916
2917      OUT: will contain the object data
2918
2919      This function will export the PKCS11 object data.  It is normal for
2920      data to be inaccesible and in that case 'GNUTLS_E_INVALID_REQUEST'
2921      will be returned.
2922
2923      The output buffer is allocated using 'gnutls_malloc()' .
2924
2925      *Returns:* In case of failure a negative error code will be
2926      returned, and 'GNUTLS_E_SUCCESS' (0) on success.
2927
2928      *Since:* 3.2.7
2929
2930 gnutls_pkcs11_obj_export_url
2931 ----------------------------
2932
2933  -- Function: int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t OBJ,
2934           gnutls_pkcs11_url_type_t DETAILED, char ** URL)
2935      OBJ: Holds the PKCS 11 certificate
2936
2937      DETAILED: non zero if a detailed URL is required
2938
2939      URL: will contain an allocated url
2940
2941      This function will export a URL identifying the given certificate.
2942
2943      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2944      otherwise a negative error value.
2945
2946      *Since:* 2.12.0
2947
2948 gnutls_pkcs11_obj_flags_get_str
2949 -------------------------------
2950
2951  -- Function: char * gnutls_pkcs11_obj_flags_get_str (unsigned int
2952           FLAGS)
2953      FLAGS: holds the flags
2954
2955      This function given an or-sequence of 'GNUTLS_PKCS11_OBJ_FLAG_MARK'
2956      , will return an allocated string with its description.  The string
2957      needs to be deallocated using 'gnutls_free()' .
2958
2959      *Returns:* If flags is zero 'NULL' is returned, otherwise an
2960      allocated string.
2961
2962      *Since:* 3.3.7
2963
2964 gnutls_pkcs11_obj_get_exts
2965 --------------------------
2966
2967  -- Function: int gnutls_pkcs11_obj_get_exts (gnutls_pkcs11_obj_t OBJ,
2968           gnutls_x509_ext_st ** EXTS, unsigned int * EXTS_SIZE, unsigned
2969           int FLAGS)
2970      OBJ: should contain a 'gnutls_pkcs11_obj_t' type
2971
2972      EXTS: a pointer to a 'gnutls_x509_ext_st' pointer
2973
2974      EXTS_SIZE: will be updated with the number of 'exts'
2975
2976      FLAGS: Or sequence of 'GNUTLS_PKCS11_OBJ_' * flags
2977
2978      This function will return information about attached extensions
2979      that associate to the provided object (which should be a
2980      certificate).  The extensions are the attached p11-kit trust module
2981      extensions.
2982
2983      Each element of 'exts' must be deinitialized using
2984      'gnutls_x509_ext_deinit()' while 'exts' should be deallocated using
2985      'gnutls_free()' .
2986
2987      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
2988      code on error.
2989
2990      *Since:* 3.3.8
2991
2992 gnutls_pkcs11_obj_get_flags
2993 ---------------------------
2994
2995  -- Function: int gnutls_pkcs11_obj_get_flags (gnutls_pkcs11_obj_t OBJ,
2996           unsigned int * OFLAGS)
2997      OBJ: The structure that holds the object
2998
2999      OFLAGS: Will hold the output flags
3000
3001      This function will return the flags of the object being stored in
3002      the structure.  The 'oflags' are the 'GNUTLS_PKCS11_OBJ_FLAG_MARK'
3003      flags.
3004
3005      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3006      otherwise a negative error value.
3007
3008      *Since:* 3.3.7
3009
3010 gnutls_pkcs11_obj_get_info
3011 --------------------------
3012
3013  -- Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t OBJ,
3014           gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t *
3015           OUTPUT_SIZE)
3016      OBJ: should contain a 'gnutls_pkcs11_obj_t' structure
3017
3018      ITYPE: Denotes the type of information requested
3019
3020      OUTPUT: where output will be stored
3021
3022      OUTPUT_SIZE: contains the maximum size of the output and will be
3023      overwritten with actual
3024
3025      This function will return information about the PKCS11 certificate
3026      such as the label, id as well as token information where the key is
3027      stored.  When output is text it returns null terminated string
3028      although 'output_size' contains the size of the actual data only.
3029
3030      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3031      code on error.
3032
3033      *Since:* 2.12.0
3034
3035 gnutls_pkcs11_obj_get_type
3036 --------------------------
3037
3038  -- Function: gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type
3039           (gnutls_pkcs11_obj_t OBJ)
3040      OBJ: Holds the PKCS 11 object
3041
3042      This function will return the type of the object being stored in
3043      the structure.
3044
3045      *Returns:* The type of the object
3046
3047      *Since:* 2.12.0
3048
3049 gnutls_pkcs11_obj_import_url
3050 ----------------------------
3051
3052  -- Function: int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t OBJ,
3053           const char * URL, unsigned int FLAGS)
3054      OBJ: The structure to store the object
3055
3056      URL: a PKCS 11 url identifying the key
3057
3058      FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags
3059
3060      This function will "import" a PKCS 11 URL identifying an object
3061      (e.g.  certificate) to the 'gnutls_pkcs11_obj_t' structure.  This
3062      does not involve any parsing (such as X.509 or OpenPGP) since the
3063      'gnutls_pkcs11_obj_t' is format agnostic.  Only data are
3064      transferred.
3065
3066      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3067      otherwise a negative error value.
3068
3069      *Since:* 2.12.0
3070
3071 gnutls_pkcs11_obj_init
3072 ----------------------
3073
3074  -- Function: int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * OBJ)
3075      OBJ: The structure to be initialized
3076
3077      This function will initialize a pkcs11 certificate structure.
3078
3079      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3080      otherwise a negative error value.
3081
3082      *Since:* 2.12.0
3083
3084 gnutls_pkcs11_obj_list_import_url
3085 ---------------------------------
3086
3087  -- Function: int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t
3088           * P_LIST, unsigned int * N_LIST, const char * URL,
3089           gnutls_pkcs11_obj_attr_t ATTRS, unsigned int FLAGS)
3090      P_LIST: An uninitialized object list (may be NULL)
3091
3092      N_LIST: initially should hold the maximum size of the list.  Will
3093      contain the actual size.
3094
3095      URL: A PKCS 11 url identifying a set of objects
3096
3097      ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
3098      used to limit output
3099
3100      FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags
3101
3102      This function will initialize and set values to an object list by
3103      using all objects identified by a PKCS 11 URL.
3104
3105      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3106      otherwise a negative error value.
3107
3108      *Since:* 2.12.0
3109
3110 gnutls_pkcs11_obj_list_import_url2
3111 ----------------------------------
3112
3113  -- Function: int gnutls_pkcs11_obj_list_import_url2
3114           (gnutls_pkcs11_obj_t ** P_LIST, unsigned int * N_LIST, const
3115           char * URL, gnutls_pkcs11_obj_attr_t ATTRS, unsigned int
3116           FLAGS)
3117      P_LIST: An uninitialized object list (may be NULL)
3118
3119      N_LIST: It will contain the size of the list.
3120
3121      URL: A PKCS 11 url identifying a set of objects
3122
3123      ATTRS: Attributes of type 'gnutls_pkcs11_obj_attr_t' that can be
3124      used to limit output
3125
3126      FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags
3127
3128      This function will initialize and set values to an object list by
3129      using all objects identified by the PKCS 11 URL. The output is
3130      stored in 'p_list' , which will be initialized.
3131
3132      All returned objects must be deinitialized using
3133      'gnutls_pkcs11_obj_deinit()' , and 'p_list' must be free'd using
3134      'gnutls_free()' .
3135
3136      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3137      otherwise a negative error value.
3138
3139      *Since:* 3.1.0
3140
3141 gnutls_pkcs11_obj_set_info
3142 --------------------------
3143
3144  -- Function: int gnutls_pkcs11_obj_set_info (gnutls_pkcs11_obj_t OBJ,
3145           gnutls_pkcs11_obj_info_t ITYPE, const void * DATA, size_t
3146           DATA_SIZE, unsigned FLAGS)
3147      OBJ: should contain a 'gnutls_pkcs11_obj_t' structure
3148
3149      ITYPE: Denotes the type of information to be set
3150
3151      DATA: the data to set
3152
3153      DATA_SIZE: the size of data
3154
3155      FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags
3156
3157      This function will set attributes on the provided object.
3158      Available options for 'itype' are 'GNUTLS_PKCS11_OBJ_LABEL' ,
3159      'GNUTLS_PKCS11_OBJ_ID_HEX' , and 'GNUTLS_PKCS11_OBJ_ID' .
3160
3161      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3162      code on error.
3163
3164      *Since:* 3.3.26
3165
3166 gnutls_pkcs11_obj_set_pin_function
3167 ----------------------------------
3168
3169  -- Function: void gnutls_pkcs11_obj_set_pin_function
3170           (gnutls_pkcs11_obj_t OBJ, gnutls_pin_callback_t FN, void *
3171           USERDATA)
3172      OBJ: The object structure
3173
3174      FN: the callback
3175
3176      USERDATA: data associated with the callback
3177
3178      This function will set a callback function to be used when required
3179      to access the object.  This function overrides the global set using
3180      'gnutls_pkcs11_set_pin_function()' .
3181
3182      *Since:* 3.1.0
3183
3184 gnutls_pkcs11_privkey_deinit
3185 ----------------------------
3186
3187  -- Function: void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t
3188           KEY)
3189      KEY: The structure to be initialized
3190
3191      This function will deinitialize a private key structure.
3192
3193 gnutls_pkcs11_privkey_export_pubkey
3194 -----------------------------------
3195
3196  -- Function: int gnutls_pkcs11_privkey_export_pubkey
3197           (gnutls_pkcs11_privkey_t PKEY, gnutls_x509_crt_fmt_t FMT,
3198           gnutls_datum_t * DATA, unsigned int FLAGS)
3199      PKEY: The private key
3200
3201      FMT: the format of output params.  PEM or DER.
3202
3203      DATA: will hold the public key
3204
3205      FLAGS: should be zero
3206
3207      This function will extract the public key (modulus and public
3208      exponent) from the private key specified by the 'url' private key.
3209      This public key will be stored in 'pubkey' in the format specified
3210      by 'fmt' .  'pubkey' should be deinitialized using 'gnutls_free()'
3211      .
3212
3213      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3214      otherwise a negative error value.
3215
3216      *Since:* 3.3.7
3217
3218 gnutls_pkcs11_privkey_export_url
3219 --------------------------------
3220
3221  -- Function: int gnutls_pkcs11_privkey_export_url
3222           (gnutls_pkcs11_privkey_t KEY, gnutls_pkcs11_url_type_t
3223           DETAILED, char ** URL)
3224      KEY: Holds the PKCS 11 key
3225
3226      DETAILED: non zero if a detailed URL is required
3227
3228      URL: will contain an allocated url
3229
3230      This function will export a URL identifying the given key.
3231
3232      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3233      otherwise a negative error value.
3234
3235 gnutls_pkcs11_privkey_generate
3236 ------------------------------
3237
3238  -- Function: int gnutls_pkcs11_privkey_generate (const char * URL,
3239           gnutls_pk_algorithm_t PK, unsigned int BITS, const char *
3240           LABEL, unsigned int FLAGS)
3241      URL: a token URL
3242
3243      PK: the public key algorithm
3244
3245      BITS: the security bits
3246
3247      LABEL: a label
3248
3249      FLAGS: should be zero
3250
3251      This function will generate a private key in the specified by the
3252      'url' token.  The private key will be generate within the token and
3253      will not be exportable.
3254
3255      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3256      otherwise a negative error value.
3257
3258      *Since:* 3.0
3259
3260 gnutls_pkcs11_privkey_generate2
3261 -------------------------------
3262
3263  -- Function: int gnutls_pkcs11_privkey_generate2 (const char * URL,
3264           gnutls_pk_algorithm_t PK, unsigned int BITS, const char *
3265           LABEL, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * PUBKEY,
3266           unsigned int FLAGS)
3267      URL: a token URL
3268
3269      PK: the public key algorithm
3270
3271      BITS: the security bits
3272
3273      LABEL: a label
3274
3275      FMT: the format of output params.  PEM or DER
3276
3277      PUBKEY: will hold the public key (may be 'NULL' )
3278
3279      FLAGS: zero or an OR'ed sequence of 'GNUTLS_PKCS11_OBJ_FLAGs'
3280
3281      This function will generate a private key in the specified by the
3282      'url' token.  The private key will be generate within the token and
3283      will not be exportable.  This function will store the DER-encoded
3284      public key in the SubjectPublicKeyInfo format in 'pubkey' .  The
3285      'pubkey' should be deinitialized using 'gnutls_free()' .
3286
3287      Note that when generating an elliptic curve key, the curve can be
3288      substituted in the place of the bits parameter using the
3289      'GNUTLS_CURVE_TO_BITS()' macro.
3290
3291      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3292      otherwise a negative error value.
3293
3294      *Since:* 3.1.5
3295
3296 gnutls_pkcs11_privkey_generate3
3297 -------------------------------
3298
3299  -- Function: int gnutls_pkcs11_privkey_generate3 (const char * URL,
3300           gnutls_pk_algorithm_t PK, unsigned int BITS, const char *
3301           LABEL, const gnutls_datum_t * CID, gnutls_x509_crt_fmt_t FMT,
3302           gnutls_datum_t * PUBKEY, unsigned int FLAGS)
3303      URL: a token URL
3304
3305      PK: the public key algorithm
3306
3307      BITS: the security bits
3308
3309      LABEL: a label
3310
3311      CID: The CKA_ID to use for the new object
3312
3313      FMT: the format of output params.  PEM or DER
3314
3315      PUBKEY: will hold the public key (may be 'NULL' )
3316
3317      FLAGS: zero or an OR'ed sequence of 'GNUTLS_PKCS11_OBJ_FLAGs'
3318
3319      This function will generate a private key in the specified by the
3320      'url' token.  The private key will be generate within the token and
3321      will not be exportable.  This function will store the DER-encoded
3322      public key in the SubjectPublicKeyInfo format in 'pubkey' .  The
3323      'pubkey' should be deinitialized using 'gnutls_free()' .
3324
3325      Note that when generating an elliptic curve key, the curve can be
3326      substituted in the place of the bits parameter using the
3327      'GNUTLS_CURVE_TO_BITS()' macro.
3328
3329      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3330      otherwise a negative error value.
3331
3332      *Since:* 3.3.26
3333
3334 gnutls_pkcs11_privkey_get_info
3335 ------------------------------
3336
3337  -- Function: int gnutls_pkcs11_privkey_get_info
3338           (gnutls_pkcs11_privkey_t PKEY, gnutls_pkcs11_obj_info_t ITYPE,
3339           void * OUTPUT, size_t * OUTPUT_SIZE)
3340      PKEY: should contain a 'gnutls_pkcs11_privkey_t' structure
3341
3342      ITYPE: Denotes the type of information requested
3343
3344      OUTPUT: where output will be stored
3345
3346      OUTPUT_SIZE: contains the maximum size of the output and will be
3347      overwritten with actual
3348
3349      This function will return information about the PKCS 11 private key
3350      such as the label, id as well as token information where the key is
3351      stored.  When output is text it returns null terminated string
3352      although 'output_size' contains the size of the actual data only.
3353
3354      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3355      code on error.
3356
3357 gnutls_pkcs11_privkey_get_pk_algorithm
3358 --------------------------------------
3359
3360  -- Function: int gnutls_pkcs11_privkey_get_pk_algorithm
3361           (gnutls_pkcs11_privkey_t KEY, unsigned int * BITS)
3362      KEY: should contain a 'gnutls_pkcs11_privkey_t' structure
3363
3364      BITS: if bits is non null it will hold the size of the parameters'
3365      in bits
3366
3367      This function will return the public key algorithm of a private
3368      key.
3369
3370      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3371      success, or a negative error code on error.
3372
3373 gnutls_pkcs11_privkey_import_url
3374 --------------------------------
3375
3376  -- Function: int gnutls_pkcs11_privkey_import_url
3377           (gnutls_pkcs11_privkey_t PKEY, const char * URL, unsigned int
3378           FLAGS)
3379      PKEY: The structure to store the parsed key
3380
3381      URL: a PKCS 11 url identifying the key
3382
3383      FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags
3384
3385      This function will "import" a PKCS 11 URL identifying a private key
3386      to the 'gnutls_pkcs11_privkey_t' structure.  In reality since in
3387      most cases keys cannot be exported, the private key structure is
3388      being associated with the available operations on the token.
3389
3390      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3391      otherwise a negative error value.
3392
3393 gnutls_pkcs11_privkey_init
3394 --------------------------
3395
3396  -- Function: int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *
3397           KEY)
3398      KEY: The structure to be initialized
3399
3400      This function will initialize an private key structure.
3401
3402      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3403      otherwise a negative error value.
3404
3405 gnutls_pkcs11_privkey_set_pin_function
3406 --------------------------------------
3407
3408  -- Function: void gnutls_pkcs11_privkey_set_pin_function
3409           (gnutls_pkcs11_privkey_t KEY, gnutls_pin_callback_t FN, void *
3410           USERDATA)
3411      KEY: The private key
3412
3413      FN: the callback
3414
3415      USERDATA: data associated with the callback
3416
3417      This function will set a callback function to be used when required
3418      to access the object.  This function overrides the global set using
3419      'gnutls_pkcs11_set_pin_function()' .
3420
3421      *Since:* 3.1.0
3422
3423 gnutls_pkcs11_privkey_status
3424 ----------------------------
3425
3426  -- Function: int gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t
3427           KEY)
3428      KEY: Holds the key
3429
3430      Checks the status of the private key token.
3431
3432      *Returns:* this function will return non-zero if the token holding
3433      the private key is still available (inserted), and zero otherwise.
3434
3435      *Since:* 3.1.9
3436
3437 gnutls_pkcs11_reinit
3438 --------------------
3439
3440  -- Function: int gnutls_pkcs11_reinit ( VOID)
3441
3442      This function will reinitialize the PKCS 11 subsystem in gnutls.
3443      This is required by PKCS 11 when an application uses 'fork()' .
3444      The reinitialization function must be called on the child.
3445
3446      Note that since GnuTLS 3.3.0, the reinitialization of the PKCS '11'
3447      subsystem occurs automatically after fork.
3448
3449      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3450      otherwise a negative error value.
3451
3452      *Since:* 3.0
3453
3454 gnutls_pkcs11_set_pin_function
3455 ------------------------------
3456
3457  -- Function: void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t
3458           FN, void * USERDATA)
3459      FN: The PIN callback, a 'gnutls_pin_callback_t()' function.
3460
3461      USERDATA: data to be supplied to callback
3462
3463      This function will set a callback function to be used when a PIN is
3464      required for PKCS 11 operations.  See 'gnutls_pin_callback_t()' on
3465      how the callback should behave.
3466
3467      *Since:* 2.12.0
3468
3469 gnutls_pkcs11_set_token_function
3470 --------------------------------
3471
3472  -- Function: void gnutls_pkcs11_set_token_function
3473           (gnutls_pkcs11_token_callback_t FN, void * USERDATA)
3474      FN: The token callback
3475
3476      USERDATA: data to be supplied to callback
3477
3478      This function will set a callback function to be used when a token
3479      needs to be inserted to continue PKCS 11 operations.
3480
3481      *Since:* 2.12.0
3482
3483 gnutls_pkcs11_token_get_flags
3484 -----------------------------
3485
3486  -- Function: int gnutls_pkcs11_token_get_flags (const char * URL,
3487           unsigned int * FLAGS)
3488      URL: should contain a PKCS 11 URL
3489
3490      FLAGS: The output flags (GNUTLS_PKCS11_TOKEN_*)
3491
3492      This function will return information about the PKCS 11 token
3493      flags.
3494
3495      The supported flags are: 'GNUTLS_PKCS11_TOKEN_HW' and
3496      'GNUTLS_PKCS11_TOKEN_TRUSTED' .
3497
3498      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3499      code on error.
3500
3501      *Since:* 2.12.0
3502
3503 gnutls_pkcs11_token_get_info
3504 ----------------------------
3505
3506  -- Function: int gnutls_pkcs11_token_get_info (const char * URL,
3507           gnutls_pkcs11_token_info_t TTYPE, void * OUTPUT, size_t *
3508           OUTPUT_SIZE)
3509      URL: should contain a PKCS 11 URL
3510
3511      TTYPE: Denotes the type of information requested
3512
3513      OUTPUT: where output will be stored
3514
3515      OUTPUT_SIZE: contains the maximum size of the output and will be
3516      overwritten with actual
3517
3518      This function will return information about the PKCS 11 token such
3519      as the label, id, etc.
3520
3521      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3522      code on error.
3523
3524      *Since:* 2.12.0
3525
3526 gnutls_pkcs11_token_get_mechanism
3527 ---------------------------------
3528
3529  -- Function: int gnutls_pkcs11_token_get_mechanism (const char * URL,
3530           unsigned int IDX, unsigned long * MECHANISM)
3531      URL: should contain a PKCS 11 URL
3532
3533      IDX: The index of the mechanism
3534
3535      MECHANISM: The PKCS '11' mechanism ID
3536
3537      This function will return the names of the supported mechanisms by
3538      the token.  It should be called with an increasing index until it
3539      return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
3540
3541      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
3542      code on error.
3543
3544      *Since:* 2.12.0
3545
3546 gnutls_pkcs11_token_get_random
3547 ------------------------------
3548
3549  -- Function: int gnutls_pkcs11_token_get_random (const char *
3550           TOKEN_URL, void * RNDDATA, size_t LEN)
3551      TOKEN_URL: A PKCS '11' URL specifying a token
3552
3553      RNDDATA: A pointer to the memory area to be filled with random data
3554
3555      LEN: The number of bytes of randomness to request
3556
3557      This function will get random data from the given token.  It will
3558      store rnddata and fill the memory pointed to by rnddata with len
3559      random bytes from the token.
3560
3561      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3562      otherwise a negative error value.
3563
3564 gnutls_pkcs11_token_get_url
3565 ---------------------------
3566
3567  -- Function: int gnutls_pkcs11_token_get_url (unsigned int SEQ,
3568           gnutls_pkcs11_url_type_t DETAILED, char ** URL)
3569      SEQ: sequence number starting from 0
3570
3571      DETAILED: non zero if a detailed URL is required
3572
3573      URL: will contain an allocated url
3574
3575      This function will return the URL for each token available in
3576      system.  The url has to be released using 'gnutls_free()'
3577
3578      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3579      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the sequence number
3580      exceeds the available tokens, otherwise a negative error value.
3581
3582      *Since:* 2.12.0
3583
3584 gnutls_pkcs11_token_init
3585 ------------------------
3586
3587  -- Function: int gnutls_pkcs11_token_init (const char * TOKEN_URL,
3588           const char * SO_PIN, const char * LABEL)
3589      TOKEN_URL: A PKCS '11' URL specifying a token
3590
3591      SO_PIN: Security Officer's PIN
3592
3593      LABEL: A name to be used for the token
3594
3595      This function will initialize (format) a token.  If the token is at
3596      a factory defaults state the security officer's PIN given will be
3597      set to be the default.  Otherwise it should match the officer's
3598      PIN.
3599
3600      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3601      otherwise a negative error value.
3602
3603 gnutls_pkcs11_token_set_pin
3604 ---------------------------
3605
3606  -- Function: int gnutls_pkcs11_token_set_pin (const char * TOKEN_URL,
3607           const char * OLDPIN, const char * NEWPIN, unsigned int FLAGS)
3608      TOKEN_URL: A PKCS '11' URL specifying a token
3609
3610      OLDPIN: old user's PIN
3611
3612      NEWPIN: new user's PIN
3613
3614      FLAGS: one of 'gnutls_pin_flag_t' .
3615
3616      This function will modify or set a user's PIN for the given token.
3617      If it is called to set a user pin for first time the oldpin must be
3618      NULL.
3619
3620      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3621      otherwise a negative error value.
3622
3623 gnutls_pkcs11_type_get_name
3624 ---------------------------
3625
3626  -- Function: const char * gnutls_pkcs11_type_get_name
3627           (gnutls_pkcs11_obj_type_t TYPE)
3628      TYPE: Holds the PKCS 11 object type, a 'gnutls_pkcs11_obj_type_t' .
3629
3630      This function will return a human readable description of the
3631      PKCS11 object type 'obj' .  It will return "Unknown" for unknown
3632      types.
3633
3634      *Returns:* human readable string labeling the PKCS11 object type
3635      'type' .
3636
3637      *Since:* 2.12.0
3638
3639 gnutls_x509_crt_import_pkcs11
3640 -----------------------------
3641
3642  -- Function: int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t CRT,
3643           gnutls_pkcs11_obj_t PKCS11_CRT)
3644      CRT: A certificate of type 'gnutls_x509_crt_t'
3645
3646      PKCS11_CRT: A PKCS 11 object that contains a certificate
3647
3648      This function will import a PKCS 11 certificate to a
3649      'gnutls_x509_crt_t' structure.
3650
3651      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3652      otherwise a negative error value.
3653
3654      *Since:* 2.12.0
3655
3656 gnutls_x509_crt_import_pkcs11_url
3657 ---------------------------------
3658
3659  -- Function: int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t
3660           CRT, const char * URL, unsigned int FLAGS)
3661      CRT: A certificate of type 'gnutls_x509_crt_t'
3662
3663      URL: A PKCS 11 url
3664
3665      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
3666
3667      This function will import a PKCS 11 certificate directly from a
3668      token without involving the 'gnutls_pkcs11_obj_t' structure.  This
3669      function will fail if the certificate stored is not of X.509 type.
3670
3671      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3672      otherwise a negative error value.
3673
3674      *Since:* 2.12.0
3675
3676 gnutls_x509_crt_list_import_pkcs11
3677 ----------------------------------
3678
3679  -- Function: int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t
3680           * CERTS, unsigned int CERT_MAX, gnutls_pkcs11_obj_t * const
3681           OBJS, unsigned int FLAGS)
3682      CERTS: A list of certificates of type 'gnutls_x509_crt_t'
3683
3684      CERT_MAX: The maximum size of the list
3685
3686      OBJS: A list of PKCS 11 objects
3687
3688      FLAGS: 0 for now
3689
3690      This function will import a PKCS 11 certificate list to a list of
3691      'gnutls_x509_crt_t' structure.  These must not be initialized.
3692
3693      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3694      otherwise a negative error value.
3695
3696      *Since:* 2.12.0
3697