doc/gnutls.info-4

   1 This is gnutls.info, produced by makeinfo version 6.0 from gnutls.texi.
   2
   3 This manual is last updated 4 March 2015 for version 3.4.11 of GnuTLS.
   4
   5 Copyright (C) 2001-2015 Free Software Foundation, Inc.\\ Copyright (C)
   6 2001-2015 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: Datagram TLS API,  Next: X509 certificate API,  Prev: Core TLS API,  Up: API reference
  31
  32 E.2 Datagram TLS API
  33 ====================
  34
  35 The prototypes for the following functions lie in 'gnutls/dtls.h'.
  36
  37 gnutls_dtls_cookie_send
  38 -----------------------
  39
  40  -- Function: int gnutls_dtls_cookie_send (gnutls_datum_t * KEY, void *
  41           CLIENT_DATA, size_t CLIENT_DATA_SIZE, gnutls_dtls_prestate_st
  42           * PRESTATE, gnutls_transport_ptr_t PTR, gnutls_push_func
  43           PUSH_FUNC)
  44      KEY: is a random key to be used at cookie generation
  45
  46      CLIENT_DATA: contains data identifying the client (i.e.  address)
  47
  48      CLIENT_DATA_SIZE: The size of client's data
  49
  50      PRESTATE: The previous cookie returned by
  51      'gnutls_dtls_cookie_verify()'
  52
  53      PTR: A transport pointer to be used by 'push_func'
  54
  55      PUSH_FUNC: A function that will be used to reply
  56
  57      This function can be used to prevent denial of service attacks to a
  58      DTLS server by requiring the client to reply using a cookie sent by
  59      this function.  That way it can be ensured that a client we
  60      allocated resources for (i.e.  'gnutls_session_t' ) is the one that
  61      the original incoming packet was originated from.
  62
  63      This function must be called at the first incoming packet, prior to
  64      allocating any resources and must be succeeded by
  65      'gnutls_dtls_cookie_verify()' .
  66
  67      *Returns:* the number of bytes sent, or a negative error code.
  68
  69      *Since:* 3.0
  70
  71 gnutls_dtls_cookie_verify
  72 -------------------------
  73
  74  -- Function: int gnutls_dtls_cookie_verify (gnutls_datum_t * KEY, void
  75           * CLIENT_DATA, size_t CLIENT_DATA_SIZE, void * _MSG, size_t
  76           MSG_SIZE, gnutls_dtls_prestate_st * PRESTATE)
  77      KEY: is a random key to be used at cookie generation
  78
  79      CLIENT_DATA: contains data identifying the client (i.e.  address)
  80
  81      CLIENT_DATA_SIZE: The size of client's data
  82
  83      _MSG: An incoming message that initiates a connection.
  84
  85      MSG_SIZE: The size of the message.
  86
  87      PRESTATE: The cookie of this client.
  88
  89      This function will verify the received message for a valid cookie.
  90      If a valid cookie is returned then it should be associated with the
  91      session using 'gnutls_dtls_prestate_set()' ;
  92
  93      This function must be called after 'gnutls_dtls_cookie_send()' .
  94
  95      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
  96      code.
  97
  98      *Since:* 3.0
  99
 100 gnutls_dtls_get_data_mtu
 101 ------------------------
 102
 103  -- Function: unsigned int gnutls_dtls_get_data_mtu (gnutls_session_t
 104           SESSION)
 105      SESSION: is a 'gnutls_session_t' type.
 106
 107      This function will return the actual maximum transfer unit for
 108      application data.  I.e.  DTLS headers are subtracted from the
 109      actual MTU which is set using 'gnutls_dtls_set_mtu()' .
 110
 111      *Returns:* the maximum allowed transfer unit.
 112
 113      *Since:* 3.0
 114
 115 gnutls_dtls_get_mtu
 116 -------------------
 117
 118  -- Function: unsigned int gnutls_dtls_get_mtu (gnutls_session_t
 119           SESSION)
 120      SESSION: is a 'gnutls_session_t' type.
 121
 122      This function will return the MTU size as set with
 123      'gnutls_dtls_set_mtu()' .  This is not the actual MTU of data you
 124      can transmit.  Use 'gnutls_dtls_get_data_mtu()' for that reason.
 125
 126      *Returns:* the set maximum transfer unit.
 127
 128      *Since:* 3.0
 129
 130 gnutls_dtls_get_timeout
 131 -----------------------
 132
 133  -- Function: unsigned int gnutls_dtls_get_timeout (gnutls_session_t
 134           SESSION)
 135      SESSION: is a 'gnutls_session_t' type.
 136
 137      This function will return the milliseconds remaining for a
 138      retransmission of the previously sent handshake message.  This
 139      function is useful when DTLS is used in non-blocking mode, to
 140      estimate when to call 'gnutls_handshake()' if no packets have been
 141      received.
 142
 143      *Returns:* the remaining time in milliseconds.
 144
 145      *Since:* 3.0
 146
 147 gnutls_dtls_prestate_set
 148 ------------------------
 149
 150  -- Function: void gnutls_dtls_prestate_set (gnutls_session_t SESSION,
 151           gnutls_dtls_prestate_st * PRESTATE)
 152      SESSION: a new session
 153
 154      PRESTATE: contains the client's prestate
 155
 156      This function will associate the prestate acquired by the cookie
 157      authentication with the client, with the newly established session.
 158
 159      This functions must be called after a successful
 160      'gnutls_dtls_cookie_verify()' and should be succeeded by the actual
 161      DTLS handshake using 'gnutls_handshake()' .
 162
 163      *Since:* 3.0
 164
 165 gnutls_dtls_set_data_mtu
 166 ------------------------
 167
 168  -- Function: int gnutls_dtls_set_data_mtu (gnutls_session_t SESSION,
 169           unsigned int MTU)
 170      SESSION: is a 'gnutls_session_t' type.
 171
 172      MTU: The maximum unencrypted transfer unit of the session
 173
 174      This function will set the maximum size of the *unencrypted*
 175      records which will be sent over a DTLS session.  It is equivalent
 176      to calculating the DTLS packet overhead with the current encryption
 177      parameters, and calling 'gnutls_dtls_set_mtu()' with that value.
 178      In particular, this means that you may need to call this function
 179      again after any negotiation or renegotiation, in order to ensure
 180      that the MTU is still sufficient to account for the new protocol
 181      overhead.
 182
 183      In most cases you only need to call 'gnutls_dtls_set_mtu()' with
 184      the maximum MTU of your transport layer.
 185
 186      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
 187      code.
 188
 189      *Since:* 3.1
 190
 191 gnutls_dtls_set_mtu
 192 -------------------
 193
 194  -- Function: void gnutls_dtls_set_mtu (gnutls_session_t SESSION,
 195           unsigned int MTU)
 196      SESSION: is a 'gnutls_session_t' type.
 197
 198      MTU: The maximum transfer unit of the transport
 199
 200      This function will set the maximum transfer unit of the transport
 201      that DTLS packets are sent over.  Note that this should exclude the
 202      IP (or IPv6) and UDP headers.  So for DTLS over IPv6 on an Ethernet
 203      device with MTU 1500, the DTLS MTU set with this function would be
 204      1500 - 40 (IPV6 header) - 8 (UDP header) = 1452.
 205
 206      *Since:* 3.0
 207
 208 gnutls_dtls_set_timeouts
 209 ------------------------
 210
 211  -- Function: void gnutls_dtls_set_timeouts (gnutls_session_t SESSION,
 212           unsigned int RETRANS_TIMEOUT, unsigned int TOTAL_TIMEOUT)
 213      SESSION: is a 'gnutls_session_t' type.
 214
 215      RETRANS_TIMEOUT: The time at which a retransmission will occur in
 216      milliseconds
 217
 218      TOTAL_TIMEOUT: The time at which the connection will be aborted, in
 219      milliseconds.
 220
 221      This function will set the timeouts required for the DTLS handshake
 222      protocol.  The retransmission timeout is the time after which a
 223      message from the peer is not received, the previous messages will
 224      be retransmitted.  The total timeout is the time after which the
 225      handshake will be aborted with 'GNUTLS_E_TIMEDOUT' .
 226
 227      The DTLS protocol recommends the values of 1 sec and 60 seconds
 228      respectively, and these are the default values.
 229
 230      To disable retransmissions set a 'retrans_timeout' larger than the
 231      'total_timeout' .
 232
 233      *Since:* 3.0
 234
 235 gnutls_record_get_discarded
 236 ---------------------------
 237
 238  -- Function: unsigned int gnutls_record_get_discarded (gnutls_session_t
 239           SESSION)
 240      SESSION: is a 'gnutls_session_t' type.
 241
 242      Returns the number of discarded packets in a DTLS connection.
 243
 244      *Returns:* The number of discarded packets.
 245
 246      *Since:* 3.0
 247
 248 \1f
 249 File: gnutls.info,  Node: X509 certificate API,  Next: PKCS 7 API,  Prev: Datagram TLS API,  Up: API reference
 250
 251 E.3 X.509 certificate API
 252 =========================
 253
 254 The following functions are to be used for X.509 certificate handling.
 255 Their prototypes lie in 'gnutls/x509.h'.
 256
 257 gnutls_certificate_get_trust_list
 258 ---------------------------------
 259
 260  -- Function: void gnutls_certificate_get_trust_list
 261           (gnutls_certificate_credentials_t RES,
 262           gnutls_x509_trust_list_t * TLIST)
 263      RES: is a 'gnutls_certificate_credentials_t' type.
 264
 265      TLIST: Location where to store the trust list.
 266
 267      Obtains the list of trusted certificates stored in 'res' and writes
 268      a pointer to it to the location 'tlist' .  The pointer will point
 269      to memory internal to 'res' , and must not be deinitialized.  It
 270      will be automatically deallocated when the 'res' structure is
 271      deinitialized.
 272
 273      *Since:* 3.4.0
 274
 275 gnutls_certificate_set_trust_list
 276 ---------------------------------
 277
 278  -- Function: void gnutls_certificate_set_trust_list
 279           (gnutls_certificate_credentials_t RES,
 280           gnutls_x509_trust_list_t TLIST, unsigned FLAGS)
 281      RES: is a 'gnutls_certificate_credentials_t' type.
 282
 283      TLIST: is a 'gnutls_x509_trust_list_t' type
 284
 285      FLAGS: must be zero
 286
 287      This function sets a trust list in the
 288      gnutls_certificate_credentials_t type.
 289
 290      Note that the 'tlist' will become part of the credentials structure
 291      and must not be deallocated.  It will be automatically deallocated
 292      when the 'res' structure is deinitialized.
 293
 294      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
 295      code.
 296
 297      *Since:* 3.2.2
 298
 299 gnutls_pkcs8_info
 300 -----------------
 301
 302  -- Function: int gnutls_pkcs8_info (const gnutls_datum_t * DATA,
 303           gnutls_x509_crt_fmt_t FORMAT, unsigned int * SCHEMA, unsigned
 304           int * CIPHER, void * SALT, unsigned int * SALT_SIZE, unsigned
 305           int * ITER_COUNT, char ** OID)
 306      DATA: Holds the PKCS '8' data
 307
 308      FORMAT: the format of the PKCS '8' data
 309
 310      SCHEMA: indicate the schema as one of 'gnutls_pkcs_encrypt_flags_t'
 311
 312      CIPHER: the cipher used as 'gnutls_cipher_algorithm_t'
 313
 314      SALT: PBKDF2 salt (if non-NULL then 'salt_size' initially holds its
 315      size)
 316
 317      SALT_SIZE: PBKDF2 salt size
 318
 319      ITER_COUNT: PBKDF2 iteration count
 320
 321      OID: if non-NULL it will contain an allocated null-terminated
 322      variable with the OID
 323
 324      This function will provide information on the algorithms used in a
 325      particular PKCS '8' structure.  If the structure algorithms are
 326      unknown the code 'GNUTLS_E_UNKNOWN_CIPHER_TYPE' will be returned,
 327      and only 'oid' , will be set.  That is, 'oid' will be set on
 328      encrypted PKCS '8' structures whether supported or not.  It must be
 329      deinitialized using 'gnutls_free()' .  The other variables are only
 330      set on supported structures.
 331
 332      *Returns:* 'GNUTLS_E_INVALID_REQUEST' if the provided structure
 333      isn't encrypted, 'GNUTLS_E_UNKNOWN_CIPHER_TYPE' if the structure's
 334      encryption isn't supported, or another negative error code in case
 335      of a failure.  Zero on success.
 336
 337 gnutls_pkcs_schema_get_name
 338 ---------------------------
 339
 340  -- Function: const char * gnutls_pkcs_schema_get_name (unsigned int
 341           SCHEMA)
 342      SCHEMA: Holds the PKCS '12' or PBES2 schema
 343      ('gnutls_pkcs_encrypt_flags_t' )
 344
 345      This function will return a human readable description of the
 346      PKCS12 or PBES2 schema.
 347
 348      *Returns:* a constrant string or 'NULL' on error.
 349
 350      *Since:* 3.4.0
 351
 352 gnutls_pkcs_schema_get_oid
 353 --------------------------
 354
 355  -- Function: const char * gnutls_pkcs_schema_get_oid (unsigned int
 356           SCHEMA)
 357      SCHEMA: Holds the PKCS '12' or PBES2 schema
 358      ('gnutls_pkcs_encrypt_flags_t' )
 359
 360      This function will return the object identifier of the PKCS12 or
 361      PBES2 schema.
 362
 363      *Returns:* a constrant string or 'NULL' on error.
 364
 365      *Since:* 3.4.0
 366
 367 gnutls_subject_alt_names_deinit
 368 -------------------------------
 369
 370  -- Function: void gnutls_subject_alt_names_deinit
 371           (gnutls_subject_alt_names_t SANS)
 372      SANS: The alternative names
 373
 374      This function will deinitialize an alternative names structure.
 375
 376      *Since:* 3.3.0
 377
 378 gnutls_subject_alt_names_get
 379 ----------------------------
 380
 381  -- Function: int gnutls_subject_alt_names_get
 382           (gnutls_subject_alt_names_t SANS, unsigned int SEQ, unsigned
 383           int * SAN_TYPE, gnutls_datum_t * SAN, gnutls_datum_t *
 384           OTHERNAME_OID)
 385      SANS: The alternative names
 386
 387      SEQ: The index of the name to get
 388
 389      SAN_TYPE: Will hold the type of the name (of
 390      'gnutls_subject_alt_names_t' )
 391
 392      SAN: The alternative name data (should be treated as constant)
 393
 394      OTHERNAME_OID: The object identifier if 'san_type' is
 395      'GNUTLS_SAN_OTHERNAME' (should be treated as constant)
 396
 397      This function will return a specific alternative name as stored in
 398      the 'sans' type.  The returned values should be treated as constant
 399      and valid for the lifetime of 'sans' .
 400
 401      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 402      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
 403      bounds, otherwise a negative error value.
 404
 405      *Since:* 3.3.0
 406
 407 gnutls_subject_alt_names_init
 408 -----------------------------
 409
 410  -- Function: int gnutls_subject_alt_names_init
 411           (gnutls_subject_alt_names_t * SANS)
 412      SANS: The alternative names
 413
 414      This function will initialize an alternative names structure.
 415
 416      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 417      otherwise a negative error value.
 418
 419      *Since:* 3.3.0
 420
 421 gnutls_subject_alt_names_set
 422 ----------------------------
 423
 424  -- Function: int gnutls_subject_alt_names_set
 425           (gnutls_subject_alt_names_t SANS, unsigned int SAN_TYPE, const
 426           gnutls_datum_t * SAN, const char * OTHERNAME_OID)
 427      SANS: The alternative names
 428
 429      SAN_TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
 430
 431      SAN: The alternative name data
 432
 433      OTHERNAME_OID: The object identifier if 'san_type' is
 434      'GNUTLS_SAN_OTHERNAME'
 435
 436      This function will store the specified alternative name in the
 437      'sans' .
 438
 439      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
 440      error value.
 441
 442      *Since:* 3.3.0
 443
 444 gnutls_x509_aia_deinit
 445 ----------------------
 446
 447  -- Function: void gnutls_x509_aia_deinit (gnutls_x509_aia_t AIA)
 448      AIA: The authority info access
 449
 450      This function will deinitialize an authority info access type.
 451
 452      *Since:* 3.3.0
 453
 454 gnutls_x509_aia_get
 455 -------------------
 456
 457  -- Function: int gnutls_x509_aia_get (gnutls_x509_aia_t AIA, unsigned
 458           int SEQ, gnutls_datum_t * OID, unsigned * SAN_TYPE,
 459           gnutls_datum_t * SAN)
 460      AIA: The authority info access
 461
 462      SEQ: specifies the sequence number of the access descriptor (0 for
 463      the first one, 1 for the second etc.)
 464
 465      OID: the type of available data; to be treated as constant.
 466
 467      SAN_TYPE: Will hold the type of the name of
 468      'gnutls_subject_alt_names_t' (may be null).
 469
 470      SAN: the access location name; to be treated as constant (may be
 471      null).
 472
 473      This function reads from the Authority Information Access type.
 474
 475      The 'seq' input parameter is used to indicate which member of the
 476      sequence the caller is interested in.  The first member is 0, the
 477      second member 1 and so on.  When the 'seq' value is out of bounds,
 478      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
 479
 480      Typically 'oid' is 'GNUTLS_OID_AD_CAISSUERS' or
 481      'GNUTLS_OID_AD_OCSP' .
 482
 483      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 484      otherwise a negative error value.
 485
 486      *Since:* 3.3.0
 487
 488 gnutls_x509_aia_init
 489 --------------------
 490
 491  -- Function: int gnutls_x509_aia_init (gnutls_x509_aia_t * AIA)
 492      AIA: The authority info access
 493
 494      This function will initialize an authority info access type.
 495
 496      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 497      otherwise a negative error value.
 498
 499      *Since:* 3.3.0
 500
 501 gnutls_x509_aia_set
 502 -------------------
 503
 504  -- Function: int gnutls_x509_aia_set (gnutls_x509_aia_t AIA, const char
 505           * OID, unsigned SAN_TYPE, const gnutls_datum_t * SAN)
 506      AIA: The authority info access
 507
 508      OID: the type of data.
 509
 510      SAN_TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
 511
 512      SAN: The alternative name data
 513
 514      This function will store the specified alternative name in the
 515      'aia' type.
 516
 517      Typically the value for 'oid' should be 'GNUTLS_OID_AD_OCSP' , or
 518      'GNUTLS_OID_AD_CAISSUERS' .
 519
 520      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
 521      error value.
 522
 523      *Since:* 3.3.0
 524
 525 gnutls_x509_aki_deinit
 526 ----------------------
 527
 528  -- Function: void gnutls_x509_aki_deinit (gnutls_x509_aki_t AKI)
 529      AKI: The authority key identifier type
 530
 531      This function will deinitialize an authority key identifier.
 532
 533      *Since:* 3.3.0
 534
 535 gnutls_x509_aki_get_cert_issuer
 536 -------------------------------
 537
 538  -- Function: int gnutls_x509_aki_get_cert_issuer (gnutls_x509_aki_t
 539           AKI, unsigned int SEQ, unsigned int * SAN_TYPE, gnutls_datum_t
 540           * SAN, gnutls_datum_t * OTHERNAME_OID, gnutls_datum_t *
 541           SERIAL)
 542      AKI: The authority key ID
 543
 544      SEQ: The index of the name to get
 545
 546      SAN_TYPE: Will hold the type of the name (of
 547      'gnutls_subject_alt_names_t' )
 548
 549      SAN: The alternative name data
 550
 551      OTHERNAME_OID: The object identifier if 'san_type' is
 552      'GNUTLS_SAN_OTHERNAME'
 553
 554      SERIAL: The authorityCertSerialNumber number
 555
 556      This function will return a specific authorityCertIssuer name as
 557      stored in the 'aki' type, as well as the authorityCertSerialNumber.
 558      All the returned values should be treated as constant, and may be
 559      set to 'NULL' when are not required.
 560
 561      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 562      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
 563      bounds, otherwise a negative error value.
 564
 565      *Since:* 3.3.0
 566
 567 gnutls_x509_aki_get_id
 568 ----------------------
 569
 570  -- Function: int gnutls_x509_aki_get_id (gnutls_x509_aki_t AKI,
 571           gnutls_datum_t * ID)
 572      AKI: The authority key ID
 573
 574      ID: Will hold the identifier
 575
 576      This function will return the key identifier as stored in the 'aki'
 577      type.  The identifier should be treated as constant.
 578
 579      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 580      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
 581      bounds, otherwise a negative error value.
 582
 583      *Since:* 3.3.0
 584
 585 gnutls_x509_aki_init
 586 --------------------
 587
 588  -- Function: int gnutls_x509_aki_init (gnutls_x509_aki_t * AKI)
 589      AKI: The authority key ID type
 590
 591      This function will initialize an authority key ID.
 592
 593      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 594      otherwise a negative error value.
 595
 596      *Since:* 3.3.0
 597
 598 gnutls_x509_aki_set_cert_issuer
 599 -------------------------------
 600
 601  -- Function: int gnutls_x509_aki_set_cert_issuer (gnutls_x509_aki_t
 602           AKI, unsigned int SAN_TYPE, const gnutls_datum_t * SAN, const
 603           char * OTHERNAME_OID, const gnutls_datum_t * SERIAL)
 604      AKI: The authority key ID
 605
 606      SAN_TYPE: the type of the name (of 'gnutls_subject_alt_names_t' ),
 607      may be null
 608
 609      SAN: The alternative name data
 610
 611      OTHERNAME_OID: The object identifier if 'san_type' is
 612      'GNUTLS_SAN_OTHERNAME'
 613
 614      SERIAL: The authorityCertSerialNumber number (may be null)
 615
 616      This function will set the authorityCertIssuer name and the
 617      authorityCertSerialNumber to be stored in the 'aki' type.  When
 618      storing multiple names, the serial should be set on the first call,
 619      and subsequent calls should use a 'NULL' serial.
 620
 621      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 622      otherwise a negative error value.
 623
 624      *Since:* 3.3.0
 625
 626 gnutls_x509_aki_set_id
 627 ----------------------
 628
 629  -- Function: int gnutls_x509_aki_set_id (gnutls_x509_aki_t AKI, const
 630           gnutls_datum_t * ID)
 631      AKI: The authority key ID
 632
 633      ID: the key identifier
 634
 635      This function will set the keyIdentifier to be stored in the 'aki'
 636      type.
 637
 638      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 639      otherwise a negative error value.
 640
 641      *Since:* 3.3.0
 642
 643 gnutls_x509_crl_check_issuer
 644 ----------------------------
 645
 646  -- Function: int gnutls_x509_crl_check_issuer (gnutls_x509_crl_t CRL,
 647           gnutls_x509_crt_t ISSUER)
 648      CRL: is the CRL to be checked
 649
 650      ISSUER: is the certificate of a possible issuer
 651
 652      This function will check if the given CRL was issued by the given
 653      issuer certificate.
 654
 655      *Returns:* true (1) if the given CRL was issued by the given
 656      issuer, and false (0) if not.
 657
 658 gnutls_x509_crl_deinit
 659 ----------------------
 660
 661  -- Function: void gnutls_x509_crl_deinit (gnutls_x509_crl_t CRL)
 662      CRL: The data to be deinitialized
 663
 664      This function will deinitialize a CRL structure.
 665
 666 gnutls_x509_crl_dist_points_deinit
 667 ----------------------------------
 668
 669  -- Function: void gnutls_x509_crl_dist_points_deinit
 670           (gnutls_x509_crl_dist_points_t CDP)
 671      CDP: The CRL distribution points
 672
 673      This function will deinitialize a CRL distribution points type.
 674
 675      *Since:* 3.3.0
 676
 677 gnutls_x509_crl_dist_points_get
 678 -------------------------------
 679
 680  -- Function: int gnutls_x509_crl_dist_points_get
 681           (gnutls_x509_crl_dist_points_t CDP, unsigned int SEQ, unsigned
 682           int * TYPE, gnutls_datum_t * SAN, unsigned int * REASONS)
 683      CDP: The CRL distribution points
 684
 685      SEQ: specifies the sequence number of the distribution point (0 for
 686      the first one, 1 for the second etc.)
 687
 688      TYPE: The name type of the corresponding name
 689      (gnutls_x509_subject_alt_name_t)
 690
 691      SAN: The distribution point names (to be treated as constant)
 692
 693      REASONS: Revocation reasons.  An ORed sequence of flags from
 694      'gnutls_x509_crl_reason_flags_t' .
 695
 696      This function retrieves the individual CRL distribution points
 697      (2.5.29.31), contained in provided type.
 698
 699      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 700      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
 701      bounds, otherwise a negative error value.
 702
 703 gnutls_x509_crl_dist_points_init
 704 --------------------------------
 705
 706  -- Function: int gnutls_x509_crl_dist_points_init
 707           (gnutls_x509_crl_dist_points_t * CDP)
 708      CDP: The CRL distribution points
 709
 710      This function will initialize a CRL distribution points type.
 711
 712      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 713      otherwise a negative error value.
 714
 715      *Since:* 3.3.0
 716
 717 gnutls_x509_crl_dist_points_set
 718 -------------------------------
 719
 720  -- Function: int gnutls_x509_crl_dist_points_set
 721           (gnutls_x509_crl_dist_points_t CDP,
 722           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
 723           SAN, unsigned int REASONS)
 724      CDP: The CRL distribution points
 725
 726      TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
 727
 728      SAN: The point name data
 729
 730      REASONS: Revocation reasons.  An ORed sequence of flags from
 731      'gnutls_x509_crl_reason_flags_t' .
 732
 733      This function will store the specified CRL distribution point value
 734      the 'cdp' type.
 735
 736      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
 737      error value.
 738
 739      *Since:* 3.3.0
 740
 741 gnutls_x509_crl_export
 742 ----------------------
 743
 744  -- Function: int gnutls_x509_crl_export (gnutls_x509_crl_t CRL,
 745           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
 746           OUTPUT_DATA_SIZE)
 747      CRL: Holds the revocation list
 748
 749      FORMAT: the format of output params.  One of PEM or DER.
 750
 751      OUTPUT_DATA: will contain a private key PEM or DER encoded
 752
 753      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
 754      replaced by the actual size of parameters)
 755
 756      This function will export the revocation list to DER or PEM format.
 757
 758      If the buffer provided is not long enough to hold the output, then
 759      'GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned.
 760
 761      If the structure is PEM encoded, it will have a header of "BEGIN
 762      X509 CRL".
 763
 764      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 765      otherwise a negative error value.
 766
 767 gnutls_x509_crl_export2
 768 -----------------------
 769
 770  -- Function: int gnutls_x509_crl_export2 (gnutls_x509_crl_t CRL,
 771           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
 772      CRL: Holds the revocation list
 773
 774      FORMAT: the format of output params.  One of PEM or DER.
 775
 776      OUT: will contain a private key PEM or DER encoded
 777
 778      This function will export the revocation list to DER or PEM format.
 779
 780      The output buffer is allocated using 'gnutls_malloc()' .
 781
 782      If the structure is PEM encoded, it will have a header of "BEGIN
 783      X509 CRL".
 784
 785      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 786      otherwise a negative error value.
 787
 788      Since 3.1.3
 789
 790 gnutls_x509_crl_get_authority_key_gn_serial
 791 -------------------------------------------
 792
 793  -- Function: int gnutls_x509_crl_get_authority_key_gn_serial
 794           (gnutls_x509_crl_t CRL, unsigned int SEQ, void * ALT, size_t *
 795           ALT_SIZE, unsigned int * ALT_TYPE, void * SERIAL, size_t *
 796           SERIAL_SIZE, unsigned int * CRITICAL)
 797      CRL: should contain a 'gnutls_x509_crl_t' type
 798
 799      SEQ: specifies the sequence number of the alt name (0 for the first
 800      one, 1 for the second etc.)
 801
 802      ALT: is the place where the alternative name will be copied to
 803
 804      ALT_SIZE: holds the size of alt.
 805
 806      ALT_TYPE: holds the type of the alternative name (one of
 807      gnutls_x509_subject_alt_name_t).
 808
 809      SERIAL: buffer to store the serial number (may be null)
 810
 811      SERIAL_SIZE: Holds the size of the serial field (may be null)
 812
 813      CRITICAL: will be non-zero if the extension is marked as critical
 814      (may be null)
 815
 816      This function will return the X.509 authority key identifier when
 817      stored as a general name (authorityCertIssuer) and serial number.
 818
 819      Because more than one general names might be stored 'seq' can be
 820      used as a counter to request them all until
 821      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
 822
 823      *Returns:* Returns 0 on success, or an error code.
 824
 825      *Since:* 3.0
 826
 827 gnutls_x509_crl_get_authority_key_id
 828 ------------------------------------
 829
 830  -- Function: int gnutls_x509_crl_get_authority_key_id
 831           (gnutls_x509_crl_t CRL, void * ID, size_t * ID_SIZE, unsigned
 832           int * CRITICAL)
 833      CRL: should contain a 'gnutls_x509_crl_t' type
 834
 835      ID: The place where the identifier will be copied
 836
 837      ID_SIZE: Holds the size of the result field.
 838
 839      CRITICAL: will be non-zero if the extension is marked as critical
 840      (may be null)
 841
 842      This function will return the CRL authority's key identifier.  This
 843      is obtained by the X.509 Authority Key identifier extension field
 844      (2.5.29.35).  Note that this function only returns the
 845      keyIdentifier field of the extension and
 846      'GNUTLS_E_X509_UNSUPPORTED_EXTENSION' , if the extension contains
 847      the name and serial number of the certificate.  In that case
 848      'gnutls_x509_crl_get_authority_key_gn_serial()' may be used.
 849
 850      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 851      otherwise a negative error code in case of an error.
 852
 853      *Since:* 2.8.0
 854
 855 gnutls_x509_crl_get_crt_count
 856 -----------------------------
 857
 858  -- Function: int gnutls_x509_crl_get_crt_count (gnutls_x509_crl_t CRL)
 859      CRL: should contain a 'gnutls_x509_crl_t' type
 860
 861      This function will return the number of revoked certificates in the
 862      given CRL.
 863
 864      *Returns:* number of certificates, a negative error code on
 865      failure.
 866
 867 gnutls_x509_crl_get_crt_serial
 868 ------------------------------
 869
 870  -- Function: int gnutls_x509_crl_get_crt_serial (gnutls_x509_crl_t CRL,
 871           int INDX, unsigned char * SERIAL, size_t * SERIAL_SIZE, time_t
 872           * T)
 873      CRL: should contain a 'gnutls_x509_crl_t' type
 874
 875      INDX: the index of the certificate to extract (starting from 0)
 876
 877      SERIAL: where the serial number will be copied
 878
 879      SERIAL_SIZE: initially holds the size of serial
 880
 881      T: if non null, will hold the time this certificate was revoked
 882
 883      This function will retrieve the serial number of the specified, by
 884      the index, revoked certificate.
 885
 886      Note that this function will have performance issues in large
 887      sequences of revoked certificates.  In that case use
 888      'gnutls_x509_crl_iter_crt_serial()' .
 889
 890      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 891      otherwise a negative error value.
 892
 893 gnutls_x509_crl_get_dn_oid
 894 --------------------------
 895
 896  -- Function: int gnutls_x509_crl_get_dn_oid (gnutls_x509_crl_t CRL, int
 897           INDX, void * OID, size_t * SIZEOF_OID)
 898      CRL: should contain a gnutls_x509_crl_t type
 899
 900      INDX: Specifies which DN OID to send.  Use (0) to get the first
 901      one.
 902
 903      OID: a pointer to store the OID (may be null)
 904
 905      SIZEOF_OID: initially holds the size of 'oid'
 906
 907      This function will extract the requested OID of the name of the CRL
 908      issuer, specified by the given index.
 909
 910      If oid is null then only the size will be filled.
 911
 912      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
 913      not long enough, and in that case the sizeof_oid will be updated
 914      with the required size.  On success 0 is returned.
 915
 916 gnutls_x509_crl_get_extension_data
 917 ----------------------------------
 918
 919  -- Function: int gnutls_x509_crl_get_extension_data (gnutls_x509_crl_t
 920           CRL, int INDX, void * DATA, size_t * SIZEOF_DATA)
 921      CRL: should contain a 'gnutls_x509_crl_t' type
 922
 923      INDX: Specifies which extension OID to send.  Use (0) to get the
 924      first one.
 925
 926      DATA: a pointer to a structure to hold the data (may be null)
 927
 928      SIZEOF_DATA: initially holds the size of 'oid'
 929
 930      This function will return the requested extension data in the CRL.
 931      The extension data will be stored as a string in the provided
 932      buffer.
 933
 934      Use 'gnutls_x509_crl_get_extension_info()' to extract the OID and
 935      critical flag.  Use 'gnutls_x509_crl_get_extension_info()' instead,
 936      if you want to get data indexed by the extension OID rather than
 937      sequence.
 938
 939      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 940      otherwise a negative error code in case of an error.  If your have
 941      reached the last extension available
 942      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
 943
 944      *Since:* 2.8.0
 945
 946 gnutls_x509_crl_get_extension_data2
 947 -----------------------------------
 948
 949  -- Function: int gnutls_x509_crl_get_extension_data2 (gnutls_x509_crl_t
 950           CRL, unsigned INDX, gnutls_datum_t * DATA)
 951      CRL: should contain a 'gnutls_x509_crl_t' type
 952
 953      INDX: Specifies which extension OID to read.  Use (0) to get the
 954      first one.
 955
 956      DATA: will contain the extension DER-encoded data
 957
 958      This function will return the requested by the index extension data
 959      in the certificate revocation list.  The extension data will be
 960      allocated using 'gnutls_malloc()' .
 961
 962      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID.
 963
 964      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 965      otherwise a negative error code is returned.  If you have reached
 966      the last extension available
 967      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
 968
 969 gnutls_x509_crl_get_extension_info
 970 ----------------------------------
 971
 972  -- Function: int gnutls_x509_crl_get_extension_info (gnutls_x509_crl_t
 973           CRL, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
 974           CRITICAL)
 975      CRL: should contain a 'gnutls_x509_crl_t' type
 976
 977      INDX: Specifies which extension OID to send, use (0) to get the
 978      first one.
 979
 980      OID: a pointer to store the OID
 981
 982      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
 983      holds actual size of 'oid' .
 984
 985      CRITICAL: output variable with critical flag, may be NULL.
 986
 987      This function will return the requested extension OID in the CRL,
 988      and the critical flag for it.  The extension OID will be stored as
 989      a string in the provided buffer.  Use
 990      'gnutls_x509_crl_get_extension_data()' to extract the data.
 991
 992      If the buffer provided is not long enough to hold the output, then
 993      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
 994      be returned.
 995
 996      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 997      otherwise a negative error code in case of an error.  If your have
 998      reached the last extension available
 999      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1000
1001      *Since:* 2.8.0
1002
1003 gnutls_x509_crl_get_extension_oid
1004 ---------------------------------
1005
1006  -- Function: int gnutls_x509_crl_get_extension_oid (gnutls_x509_crl_t
1007           CRL, int INDX, void * OID, size_t * SIZEOF_OID)
1008      CRL: should contain a 'gnutls_x509_crl_t' type
1009
1010      INDX: Specifies which extension OID to send, use (0) to get the
1011      first one.
1012
1013      OID: a pointer to store the OID (may be null)
1014
1015      SIZEOF_OID: initially holds the size of 'oid'
1016
1017      This function will return the requested extension OID in the CRL.
1018      The extension OID will be stored as a string in the provided
1019      buffer.
1020
1021      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1022      otherwise a negative error code in case of an error.  If your have
1023      reached the last extension available
1024      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1025
1026      *Since:* 2.8.0
1027
1028 gnutls_x509_crl_get_issuer_dn
1029 -----------------------------
1030
1031  -- Function: int gnutls_x509_crl_get_issuer_dn (const gnutls_x509_crl_t
1032           CRL, char * BUF, size_t * SIZEOF_BUF)
1033      CRL: should contain a gnutls_x509_crl_t type
1034
1035      BUF: a pointer to a structure to hold the peer's name (may be null)
1036
1037      SIZEOF_BUF: initially holds the size of 'buf'
1038
1039      This function will copy the name of the CRL issuer in the provided
1040      buffer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
1041      described in RFC4514.  The output string will be ASCII or UTF-8
1042      encoded, depending on the certificate data.
1043
1044      If buf is 'NULL' then only the size will be filled.
1045
1046      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
1047      not long enough, and in that case the sizeof_buf will be updated
1048      with the required size, and 0 on success.
1049
1050 gnutls_x509_crl_get_issuer_dn2
1051 ------------------------------
1052
1053  -- Function: int gnutls_x509_crl_get_issuer_dn2 (gnutls_x509_crl_t CRL,
1054           gnutls_datum_t * DN)
1055      CRL: should contain a 'gnutls_x509_crl_t' type
1056
1057      DN: a pointer to a structure to hold the name
1058
1059      This function will allocate buffer and copy the name of the CRL
1060      issuer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
1061      described in RFC4514.  The output string will be ASCII or UTF-8
1062      encoded, depending on the certificate data.
1063
1064      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1065      otherwise a negative error value.
1066
1067      *Since:* 3.1.10
1068
1069 gnutls_x509_crl_get_issuer_dn_by_oid
1070 ------------------------------------
1071
1072  -- Function: int gnutls_x509_crl_get_issuer_dn_by_oid
1073           (gnutls_x509_crl_t CRL, const char * OID, int INDX, unsigned
1074           int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF)
1075      CRL: should contain a gnutls_x509_crl_t type
1076
1077      OID: holds an Object Identified in null terminated string
1078
1079      INDX: In case multiple same OIDs exist in the RDN, this specifies
1080      which to send.  Use (0) to get the first one.
1081
1082      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
1083
1084      BUF: a pointer to a structure to hold the peer's name (may be null)
1085
1086      SIZEOF_BUF: initially holds the size of 'buf'
1087
1088      This function will extract the part of the name of the CRL issuer
1089      specified by the given OID. The output will be encoded as described
1090      in RFC4514.  The output string will be ASCII or UTF-8 encoded,
1091      depending on the certificate data.
1092
1093      Some helper macros with popular OIDs can be found in gnutls/x509.h
1094      If raw flag is (0), this function will only return known OIDs as
1095      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
1096      hex format with a '#' prefix.  You can check about known OIDs using
1097      'gnutls_x509_dn_oid_known()' .
1098
1099      If buf is null then only the size will be filled.
1100
1101      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
1102      not long enough, and in that case the sizeof_buf will be updated
1103      with the required size, and 0 on success.
1104
1105 gnutls_x509_crl_get_next_update
1106 -------------------------------
1107
1108  -- Function: time_t gnutls_x509_crl_get_next_update (gnutls_x509_crl_t
1109           CRL)
1110      CRL: should contain a 'gnutls_x509_crl_t' type
1111
1112      This function will return the time the next CRL will be issued.
1113      This field is optional in a CRL so it might be normal to get an
1114      error instead.
1115
1116      *Returns:* when the next CRL will be issued, or (time_t)-1 on
1117      error.
1118
1119 gnutls_x509_crl_get_number
1120 --------------------------
1121
1122  -- Function: int gnutls_x509_crl_get_number (gnutls_x509_crl_t CRL,
1123           void * RET, size_t * RET_SIZE, unsigned int * CRITICAL)
1124      CRL: should contain a 'gnutls_x509_crl_t' type
1125
1126      RET: The place where the number will be copied
1127
1128      RET_SIZE: Holds the size of the result field.
1129
1130      CRITICAL: will be non-zero if the extension is marked as critical
1131      (may be null)
1132
1133      This function will return the CRL number extension.  This is
1134      obtained by the CRL Number extension field (2.5.29.20).
1135
1136      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1137      otherwise a negative error code in case of an error.
1138
1139      *Since:* 2.8.0
1140
1141 gnutls_x509_crl_get_raw_issuer_dn
1142 ---------------------------------
1143
1144  -- Function: int gnutls_x509_crl_get_raw_issuer_dn (gnutls_x509_crl_t
1145           CRL, gnutls_datum_t * DN)
1146      CRL: should contain a gnutls_x509_crl_t type
1147
1148      DN: will hold the starting point of the DN
1149
1150      This function will return a pointer to the DER encoded DN structure
1151      and the length.
1152
1153      *Returns:* a negative error code on error, and (0) on success.
1154
1155      *Since:* 2.12.0
1156
1157 gnutls_x509_crl_get_signature
1158 -----------------------------
1159
1160  -- Function: int gnutls_x509_crl_get_signature (gnutls_x509_crl_t CRL,
1161           char * SIG, size_t * SIZEOF_SIG)
1162      CRL: should contain a gnutls_x509_crl_t type
1163
1164      SIG: a pointer where the signature part will be copied (may be
1165      null).
1166
1167      SIZEOF_SIG: initially holds the size of 'sig'
1168
1169      This function will extract the signature field of a CRL.
1170
1171      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1172      otherwise a negative error value.
1173
1174 gnutls_x509_crl_get_signature_algorithm
1175 ---------------------------------------
1176
1177  -- Function: int gnutls_x509_crl_get_signature_algorithm
1178           (gnutls_x509_crl_t CRL)
1179      CRL: should contain a 'gnutls_x509_crl_t' type
1180
1181      This function will return a value of the 'gnutls_sign_algorithm_t'
1182      enumeration that is the signature algorithm.
1183
1184      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1185      otherwise a negative error value.
1186
1187 gnutls_x509_crl_get_this_update
1188 -------------------------------
1189
1190  -- Function: time_t gnutls_x509_crl_get_this_update (gnutls_x509_crl_t
1191           CRL)
1192      CRL: should contain a 'gnutls_x509_crl_t' type
1193
1194      This function will return the time this CRL was issued.
1195
1196      *Returns:* when the CRL was issued, or (time_t)-1 on error.
1197
1198 gnutls_x509_crl_get_version
1199 ---------------------------
1200
1201  -- Function: int gnutls_x509_crl_get_version (gnutls_x509_crl_t CRL)
1202      CRL: should contain a 'gnutls_x509_crl_t' type
1203
1204      This function will return the version of the specified CRL.
1205
1206      *Returns:* The version number, or a negative error code on error.
1207
1208 gnutls_x509_crl_import
1209 ----------------------
1210
1211  -- Function: int gnutls_x509_crl_import (gnutls_x509_crl_t CRL, const
1212           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
1213      CRL: The data to store the parsed CRL.
1214
1215      DATA: The DER or PEM encoded CRL.
1216
1217      FORMAT: One of DER or PEM
1218
1219      This function will convert the given DER or PEM encoded CRL to the
1220      native 'gnutls_x509_crl_t' format.  The output will be stored in
1221      'crl'.
1222
1223      If the CRL is PEM encoded it should have a header of "X509 CRL".
1224
1225      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1226      otherwise a negative error value.
1227
1228 gnutls_x509_crl_init
1229 --------------------
1230
1231  -- Function: int gnutls_x509_crl_init (gnutls_x509_crl_t * CRL)
1232      CRL: A pointer to the type to be initialized
1233
1234      This function will initialize a CRL structure.  CRL stands for
1235      Certificate Revocation List.  A revocation list usually contains
1236      lists of certificate serial numbers that have been revoked by an
1237      Authority.  The revocation lists are always signed with the
1238      authority's private key.
1239
1240      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1241      otherwise a negative error value.
1242
1243 gnutls_x509_crl_iter_crt_serial
1244 -------------------------------
1245
1246  -- Function: int gnutls_x509_crl_iter_crt_serial (gnutls_x509_crl_t
1247           CRL, gnutls_x509_crl_iter_t * ITER, unsigned char * SERIAL,
1248           size_t * SERIAL_SIZE, time_t * T)
1249      CRL: should contain a 'gnutls_x509_crl_t' type
1250
1251      ITER: A pointer to an iterator (initially the iterator should be
1252      'NULL' )
1253
1254      SERIAL: where the serial number will be copied
1255
1256      SERIAL_SIZE: initially holds the size of serial
1257
1258      T: if non null, will hold the time this certificate was revoked
1259
1260      This function performs the same as
1261      'gnutls_x509_crl_get_crt_serial()' , but reads sequentially and
1262      keeps state in the iterator between calls.  That allows it to
1263      provide better performance in sequences with many elements
1264      (50000+).
1265
1266      When past the last element is accessed
1267      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned and the
1268      iterator is reset.
1269
1270      After use, the iterator must be deinitialized using
1271      'gnutls_x509_crl_iter_deinit()' .
1272
1273      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1274      otherwise a negative error value.
1275
1276 gnutls_x509_crl_iter_deinit
1277 ---------------------------
1278
1279  -- Function: void gnutls_x509_crl_iter_deinit (gnutls_x509_crl_iter_t
1280           ITER)
1281      ITER: The iterator to be deinitialized
1282
1283      This function will deinitialize an iterator type.
1284
1285 gnutls_x509_crl_list_import
1286 ---------------------------
1287
1288  -- Function: int gnutls_x509_crl_list_import (gnutls_x509_crl_t * CRLS,
1289           unsigned int * CRL_MAX, const gnutls_datum_t * DATA,
1290           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
1291      CRLS: Indicates where the parsed CRLs will be copied to.  Must not
1292      be initialized.
1293
1294      CRL_MAX: Initially must hold the maximum number of crls.  It will
1295      be updated with the number of crls available.
1296
1297      DATA: The PEM encoded CRLs
1298
1299      FORMAT: One of DER or PEM.
1300
1301      FLAGS: must be (0) or an OR'd sequence of
1302      gnutls_certificate_import_flags.
1303
1304      This function will convert the given PEM encoded CRL list to the
1305      native gnutls_x509_crl_t format.  The output will be stored in
1306      'crls' .  They will be automatically initialized.
1307
1308      If the Certificate is PEM encoded it should have a header of "X509
1309      CRL".
1310
1311      *Returns:* the number of certificates read or a negative error
1312      value.
1313
1314      *Since:* 3.0
1315
1316 gnutls_x509_crl_list_import2
1317 ----------------------------
1318
1319  -- Function: int gnutls_x509_crl_list_import2 (gnutls_x509_crl_t **
1320           CRLS, unsigned int * SIZE, const gnutls_datum_t * DATA,
1321           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
1322      CRLS: Will contain the parsed crl list.
1323
1324      SIZE: It will contain the size of the list.
1325
1326      DATA: The PEM encoded CRL.
1327
1328      FORMAT: One of DER or PEM.
1329
1330      FLAGS: must be (0) or an OR'd sequence of
1331      gnutls_certificate_import_flags.
1332
1333      This function will convert the given PEM encoded CRL list to the
1334      native gnutls_x509_crl_t format.  The output will be stored in
1335      'crls' .  They will be automatically initialized.
1336
1337      If the Certificate is PEM encoded it should have a header of "X509
1338      CRL".
1339
1340      *Returns:* the number of certificates read or a negative error
1341      value.
1342
1343      *Since:* 3.0
1344
1345 gnutls_x509_crl_print
1346 ---------------------
1347
1348  -- Function: int gnutls_x509_crl_print (gnutls_x509_crl_t CRL,
1349           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
1350           OUT)
1351      CRL: The data to be printed
1352
1353      FORMAT: Indicate the format to use
1354
1355      OUT: Newly allocated datum with null terminated string.
1356
1357      This function will pretty print a X.509 certificate revocation
1358      list, suitable for display to a human.
1359
1360      The output 'out' needs to be deallocated using 'gnutls_free()' .
1361
1362      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1363      otherwise a negative error value.
1364
1365 gnutls_x509_crl_set_authority_key_id
1366 ------------------------------------
1367
1368  -- Function: int gnutls_x509_crl_set_authority_key_id
1369           (gnutls_x509_crl_t CRL, const void * ID, size_t ID_SIZE)
1370      CRL: a CRL of type 'gnutls_x509_crl_t'
1371
1372      ID: The key ID
1373
1374      ID_SIZE: Holds the size of the serial field.
1375
1376      This function will set the CRL's authority key ID extension.  Only
1377      the keyIdentifier field can be set with this function.  This may be
1378      used by an authority that holds multiple private keys, to
1379      distinguish the used key.
1380
1381      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1382      otherwise a negative error value.
1383
1384      *Since:* 2.8.0
1385
1386 gnutls_x509_crl_set_crt
1387 -----------------------
1388
1389  -- Function: int gnutls_x509_crl_set_crt (gnutls_x509_crl_t CRL,
1390           gnutls_x509_crt_t CRT, time_t REVOCATION_TIME)
1391      CRL: should contain a gnutls_x509_crl_t type
1392
1393      CRT: a certificate of type 'gnutls_x509_crt_t' with the revoked
1394      certificate
1395
1396      REVOCATION_TIME: The time this certificate was revoked
1397
1398      This function will set a revoked certificate's serial number to the
1399      CRL.
1400
1401      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1402      otherwise a negative error value.
1403
1404 gnutls_x509_crl_set_crt_serial
1405 ------------------------------
1406
1407  -- Function: int gnutls_x509_crl_set_crt_serial (gnutls_x509_crl_t CRL,
1408           const void * SERIAL, size_t SERIAL_SIZE, time_t
1409           REVOCATION_TIME)
1410      CRL: should contain a gnutls_x509_crl_t type
1411
1412      SERIAL: The revoked certificate's serial number
1413
1414      SERIAL_SIZE: Holds the size of the serial field.
1415
1416      REVOCATION_TIME: The time this certificate was revoked
1417
1418      This function will set a revoked certificate's serial number to the
1419      CRL.
1420
1421      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1422      otherwise a negative error value.
1423
1424 gnutls_x509_crl_set_next_update
1425 -------------------------------
1426
1427  -- Function: int gnutls_x509_crl_set_next_update (gnutls_x509_crl_t
1428           CRL, time_t EXP_TIME)
1429      CRL: should contain a gnutls_x509_crl_t type
1430
1431      EXP_TIME: The actual time
1432
1433      This function will set the time this CRL will be updated.
1434
1435      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1436      otherwise a negative error value.
1437
1438 gnutls_x509_crl_set_number
1439 --------------------------
1440
1441  -- Function: int gnutls_x509_crl_set_number (gnutls_x509_crl_t CRL,
1442           const void * NR, size_t NR_SIZE)
1443      CRL: a CRL of type 'gnutls_x509_crl_t'
1444
1445      NR: The CRL number
1446
1447      NR_SIZE: Holds the size of the nr field.
1448
1449      This function will set the CRL's number extension.  This is to be
1450      used as a unique and monotonic number assigned to the CRL by the
1451      authority.
1452
1453      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1454      otherwise a negative error value.
1455
1456      *Since:* 2.8.0
1457
1458 gnutls_x509_crl_set_this_update
1459 -------------------------------
1460
1461  -- Function: int gnutls_x509_crl_set_this_update (gnutls_x509_crl_t
1462           CRL, time_t ACT_TIME)
1463      CRL: should contain a gnutls_x509_crl_t type
1464
1465      ACT_TIME: The actual time
1466
1467      This function will set the time this CRL was issued.
1468
1469      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1470      otherwise a negative error value.
1471
1472 gnutls_x509_crl_set_version
1473 ---------------------------
1474
1475  -- Function: int gnutls_x509_crl_set_version (gnutls_x509_crl_t CRL,
1476           unsigned int VERSION)
1477      CRL: should contain a gnutls_x509_crl_t type
1478
1479      VERSION: holds the version number.  For CRLv1 crls must be 1.
1480
1481      This function will set the version of the CRL. This must be one for
1482      CRL version 1, and so on.  The CRLs generated by gnutls should have
1483      a version number of 2.
1484
1485      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1486      otherwise a negative error value.
1487
1488 gnutls_x509_crl_sign2
1489 ---------------------
1490
1491  -- Function: int gnutls_x509_crl_sign2 (gnutls_x509_crl_t CRL,
1492           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY,
1493           gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
1494      CRL: should contain a gnutls_x509_crl_t type
1495
1496      ISSUER: is the certificate of the certificate issuer
1497
1498      ISSUER_KEY: holds the issuer's private key
1499
1500      DIG: The message digest to use.  GNUTLS_DIG_SHA1 is the safe choice
1501      unless you know what you're doing.
1502
1503      FLAGS: must be 0
1504
1505      This function will sign the CRL with the issuer's private key, and
1506      will copy the issuer's information into the CRL.
1507
1508      This must be the last step in a certificate CRL since all the
1509      previously set parameters are now signed.
1510
1511      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1512      otherwise a negative error value.
1513
1514 gnutls_x509_crl_verify
1515 ----------------------
1516
1517  -- Function: int gnutls_x509_crl_verify (gnutls_x509_crl_t CRL, const
1518           gnutls_x509_crt_t * TRUSTED_CAS, int TCAS_SIZE, unsigned int
1519           FLAGS, unsigned int * VERIFY)
1520      CRL: is the crl to be verified
1521
1522      TRUSTED_CAS: is a certificate list that is considered to be trusted
1523      one
1524
1525      TCAS_SIZE: holds the number of CA certificates in CA_list
1526
1527      FLAGS: Flags that may be used to change the verification algorithm.
1528      Use OR of the gnutls_certificate_verify_flags enumerations.
1529
1530      VERIFY: will hold the crl verification output.
1531
1532      This function will try to verify the given crl and return its
1533      verification status.  See 'gnutls_x509_crt_list_verify()' for a
1534      detailed description of return values.  Note that since GnuTLS
1535      3.1.4 this function includes the time checks.
1536
1537      Note that value in 'verify' is set only when the return value of
1538      this function is success (i.e, failure to trust a CRL a certificate
1539      does not imply a negative return value).
1540
1541      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1542      otherwise a negative error value.
1543
1544 gnutls_x509_crq_deinit
1545 ----------------------
1546
1547  -- Function: void gnutls_x509_crq_deinit (gnutls_x509_crq_t CRQ)
1548      CRQ: the type to be deinitialized
1549
1550      This function will deinitialize a PKCS'10' certificate request
1551      structure.
1552
1553 gnutls_x509_crq_export
1554 ----------------------
1555
1556  -- Function: int gnutls_x509_crq_export (gnutls_x509_crq_t CRQ,
1557           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
1558           OUTPUT_DATA_SIZE)
1559      CRQ: should contain a 'gnutls_x509_crq_t' type
1560
1561      FORMAT: the format of output params.  One of PEM or DER.
1562
1563      OUTPUT_DATA: will contain a certificate request PEM or DER encoded
1564
1565      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
1566      replaced by the actual size of parameters)
1567
1568      This function will export the certificate request to a PEM or DER
1569      encoded PKCS10 structure.
1570
1571      If the buffer provided is not long enough to hold the output, then
1572      'GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned and *
1573      'output_data_size' will be updated.
1574
1575      If the structure is PEM encoded, it will have a header of "BEGIN
1576      NEW CERTIFICATE REQUEST".
1577
1578      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1579      otherwise a negative error value.
1580
1581 gnutls_x509_crq_export2
1582 -----------------------
1583
1584  -- Function: int gnutls_x509_crq_export2 (gnutls_x509_crq_t CRQ,
1585           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
1586      CRQ: should contain a 'gnutls_x509_crq_t' type
1587
1588      FORMAT: the format of output params.  One of PEM or DER.
1589
1590      OUT: will contain a certificate request PEM or DER encoded
1591
1592      This function will export the certificate request to a PEM or DER
1593      encoded PKCS10 structure.
1594
1595      The output buffer is allocated using 'gnutls_malloc()' .
1596
1597      If the structure is PEM encoded, it will have a header of "BEGIN
1598      NEW CERTIFICATE REQUEST".
1599
1600      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1601      otherwise a negative error value.
1602
1603      Since 3.1.3
1604
1605 gnutls_x509_crq_get_attribute_by_oid
1606 ------------------------------------
1607
1608  -- Function: int gnutls_x509_crq_get_attribute_by_oid
1609           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
1610           BUF, size_t * BUF_SIZE)
1611      CRQ: should contain a 'gnutls_x509_crq_t' type
1612
1613      OID: holds an Object Identifier in null-terminated string
1614
1615      INDX: In case multiple same OIDs exist in the attribute list, this
1616      specifies which to get, use (0) to get the first one
1617
1618      BUF: a pointer to a structure to hold the attribute data (may be
1619      'NULL' )
1620
1621      BUF_SIZE: initially holds the size of 'buf'
1622
1623      This function will return the attribute in the certificate request
1624      specified by the given Object ID. The attribute will be DER
1625      encoded.
1626
1627      Attributes in a certificate request is an optional set of data
1628      appended to the request.  Their interpretation depends on the CA
1629      policy.
1630
1631      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1632      otherwise a negative error value.
1633
1634 gnutls_x509_crq_get_attribute_data
1635 ----------------------------------
1636
1637  -- Function: int gnutls_x509_crq_get_attribute_data (gnutls_x509_crq_t
1638           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
1639      CRQ: should contain a 'gnutls_x509_crq_t' type
1640
1641      INDX: Specifies which attribute number to get.  Use (0) to get the
1642      first one.
1643
1644      DATA: a pointer to a structure to hold the data (may be null)
1645
1646      SIZEOF_DATA: initially holds the size of 'oid'
1647
1648      This function will return the requested attribute data in the
1649      certificate request.  The attribute data will be stored as a string
1650      in the provided buffer.
1651
1652      Use 'gnutls_x509_crq_get_attribute_info()' to extract the OID. Use
1653      'gnutls_x509_crq_get_attribute_by_oid()' instead, if you want to
1654      get data indexed by the attribute OID rather than sequence.
1655
1656      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1657      otherwise a negative error code in case of an error.  If your have
1658      reached the last extension available
1659      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1660
1661      *Since:* 2.8.0
1662
1663 gnutls_x509_crq_get_attribute_info
1664 ----------------------------------
1665
1666  -- Function: int gnutls_x509_crq_get_attribute_info (gnutls_x509_crq_t
1667           CRQ, int INDX, void * OID, size_t * SIZEOF_OID)
1668      CRQ: should contain a 'gnutls_x509_crq_t' type
1669
1670      INDX: Specifies which attribute number to get.  Use (0) to get the
1671      first one.
1672
1673      OID: a pointer to a structure to hold the OID
1674
1675      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
1676      holds actual size of 'oid' .
1677
1678      This function will return the requested attribute OID in the
1679      certificate, and the critical flag for it.  The attribute OID will
1680      be stored as a string in the provided buffer.  Use
1681      'gnutls_x509_crq_get_attribute_data()' to extract the data.
1682
1683      If the buffer provided is not long enough to hold the output, then
1684      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
1685      be returned.
1686
1687      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1688      otherwise a negative error code in case of an error.  If your have
1689      reached the last extension available
1690      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1691
1692      *Since:* 2.8.0
1693
1694 gnutls_x509_crq_get_basic_constraints
1695 -------------------------------------
1696
1697  -- Function: int gnutls_x509_crq_get_basic_constraints
1698           (gnutls_x509_crq_t CRQ, unsigned int * CRITICAL, unsigned int
1699           * CA, int * PATHLEN)
1700      CRQ: should contain a 'gnutls_x509_crq_t' type
1701
1702      CRITICAL: will be non-zero if the extension is marked as critical
1703
1704      CA: pointer to output integer indicating CA status, may be NULL,
1705      value is 1 if the certificate CA flag is set, 0 otherwise.
1706
1707      PATHLEN: pointer to output integer indicating path length (may be
1708      NULL), non-negative error codes indicate a present
1709      pathLenConstraint field and the actual value, -1 indicate that the
1710      field is absent.
1711
1712      This function will read the certificate's basic constraints, and
1713      return the certificates CA status.  It reads the basicConstraints
1714      X.509 extension (2.5.29.19).
1715
1716      *Returns:* If the certificate is a CA a positive value will be
1717      returned, or (0) if the certificate does not have CA flag set.  A
1718      negative error code may be returned in case of errors.  If the
1719      certificate does not contain the basicConstraints extension
1720      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1721
1722      *Since:* 2.8.0
1723
1724 gnutls_x509_crq_get_challenge_password
1725 --------------------------------------
1726
1727  -- Function: int gnutls_x509_crq_get_challenge_password
1728           (gnutls_x509_crq_t CRQ, char * PASS, size_t * PASS_SIZE)
1729      CRQ: should contain a 'gnutls_x509_crq_t' type
1730
1731      PASS: will hold a (0)-terminated password string
1732
1733      PASS_SIZE: Initially holds the size of 'pass' .
1734
1735      This function will return the challenge password in the request.
1736      The challenge password is intended to be used for requesting a
1737      revocation of the certificate.
1738
1739      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1740      otherwise a negative error value.
1741
1742 gnutls_x509_crq_get_dn
1743 ----------------------
1744
1745  -- Function: int gnutls_x509_crq_get_dn (gnutls_x509_crq_t CRQ, char *
1746           BUF, size_t * BUF_SIZE)
1747      CRQ: should contain a 'gnutls_x509_crq_t' type
1748
1749      BUF: a pointer to a structure to hold the name (may be 'NULL' )
1750
1751      BUF_SIZE: initially holds the size of 'buf'
1752
1753      This function will copy the name of the Certificate request subject
1754      to the provided buffer.  The name will be in the form
1755      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253.  The output
1756      string 'buf' will be ASCII or UTF-8 encoded, depending on the
1757      certificate data.
1758
1759      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
1760      not long enough, and in that case the * 'buf_size' will be updated
1761      with the required size.  On success 0 is returned.
1762
1763 gnutls_x509_crq_get_dn2
1764 -----------------------
1765
1766  -- Function: int gnutls_x509_crq_get_dn2 (gnutls_x509_crq_t CRQ,
1767           gnutls_datum_t * DN)
1768      CRQ: should contain a 'gnutls_x509_crq_t' type
1769
1770      DN: a pointer to a structure to hold the name
1771
1772      This function will allocate buffer and copy the name of the
1773      Certificate request.  The name will be in the form
1774      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
1775      will be ASCII or UTF-8 encoded, depending on the certificate data.
1776
1777      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1778      otherwise a negative error value.  and a negative error code on
1779      error.
1780
1781      *Since:* 3.1.10
1782
1783 gnutls_x509_crq_get_dn_by_oid
1784 -----------------------------
1785
1786  -- Function: int gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t CRQ,
1787           const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF,
1788           size_t * BUF_SIZE)
1789      CRQ: should contain a gnutls_x509_crq_t type
1790
1791      OID: holds an Object Identifier in a null terminated string
1792
1793      INDX: In case multiple same OIDs exist in the RDN, this specifies
1794      which to get.  Use (0) to get the first one.
1795
1796      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
1797
1798      BUF: a pointer to a structure to hold the name (may be 'NULL' )
1799
1800      BUF_SIZE: initially holds the size of 'buf'
1801
1802      This function will extract the part of the name of the Certificate
1803      request subject, specified by the given OID. The output will be
1804      encoded as described in RFC2253.  The output string will be ASCII
1805      or UTF-8 encoded, depending on the certificate data.
1806
1807      Some helper macros with popular OIDs can be found in gnutls/x509.h
1808      If raw flag is (0), this function will only return known OIDs as
1809      text.  Other OIDs will be DER encoded, as described in RFC2253 - in
1810      hex format with a '\#' prefix.  You can check about known OIDs
1811      using 'gnutls_x509_dn_oid_known()' .
1812
1813      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
1814      not long enough, and in that case the * 'buf_size' will be updated
1815      with the required size.  On success 0 is returned.
1816
1817 gnutls_x509_crq_get_dn_oid
1818 --------------------------
1819
1820  -- Function: int gnutls_x509_crq_get_dn_oid (gnutls_x509_crq_t CRQ, int
1821           INDX, void * OID, size_t * SIZEOF_OID)
1822      CRQ: should contain a gnutls_x509_crq_t type
1823
1824      INDX: Specifies which DN OID to get.  Use (0) to get the first one.
1825
1826      OID: a pointer to a structure to hold the name (may be 'NULL' )
1827
1828      SIZEOF_OID: initially holds the size of 'oid'
1829
1830      This function will extract the requested OID of the name of the
1831      certificate request subject, specified by the given index.
1832
1833      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
1834      not long enough, and in that case the * 'sizeof_oid' will be
1835      updated with the required size.  On success 0 is returned.
1836
1837 gnutls_x509_crq_get_extension_by_oid
1838 ------------------------------------
1839
1840  -- Function: int gnutls_x509_crq_get_extension_by_oid
1841           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
1842           BUF, size_t * BUF_SIZE, unsigned int * CRITICAL)
1843      CRQ: should contain a 'gnutls_x509_crq_t' type
1844
1845      OID: holds an Object Identifier in a null terminated string
1846
1847      INDX: In case multiple same OIDs exist in the extensions, this
1848      specifies which to get.  Use (0) to get the first one.
1849
1850      BUF: a pointer to a structure to hold the name (may be null)
1851
1852      BUF_SIZE: initially holds the size of 'buf'
1853
1854      CRITICAL: will be non-zero if the extension is marked as critical
1855
1856      This function will return the extension specified by the OID in the
1857      certificate.  The extensions will be returned as binary data DER
1858      encoded, in the provided buffer.
1859
1860      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1861      otherwise a negative error code in case of an error.  If the
1862      certificate does not contain the specified extension
1863      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1864
1865      *Since:* 2.8.0
1866
1867 gnutls_x509_crq_get_extension_by_oid2
1868 -------------------------------------
1869
1870  -- Function: int gnutls_x509_crq_get_extension_by_oid2
1871           (gnutls_x509_crq_t CRQ, const char * OID, int INDX,
1872           gnutls_datum_t * OUTPUT, unsigned int * CRITICAL)
1873      CRQ: should contain a 'gnutls_x509_crq_t' type
1874
1875      OID: holds an Object Identifier in a null terminated string
1876
1877      INDX: In case multiple same OIDs exist in the extensions, this
1878      specifies which to get.  Use (0) to get the first one.
1879
1880      OUTPUT: will hold the allocated extension data
1881
1882      CRITICAL: will be non-zero if the extension is marked as critical
1883
1884      This function will return the extension specified by the OID in the
1885      certificate.  The extensions will be returned as binary data DER
1886      encoded, in the provided buffer.
1887
1888      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1889      otherwise a negative error code in case of an error.  If the
1890      certificate does not contain the specified extension
1891      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1892
1893      *Since:* 3.3.8
1894
1895 gnutls_x509_crq_get_extension_data
1896 ----------------------------------
1897
1898  -- Function: int gnutls_x509_crq_get_extension_data (gnutls_x509_crq_t
1899           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
1900      CRQ: should contain a 'gnutls_x509_crq_t' type
1901
1902      INDX: Specifies which extension number to get.  Use (0) to get the
1903      first one.
1904
1905      DATA: a pointer to a structure to hold the data (may be null)
1906
1907      SIZEOF_DATA: initially holds the size of 'oid'
1908
1909      This function will return the requested extension data in the
1910      certificate.  The extension data will be stored as a string in the
1911      provided buffer.
1912
1913      Use 'gnutls_x509_crq_get_extension_info()' to extract the OID and
1914      critical flag.  Use 'gnutls_x509_crq_get_extension_by_oid()'
1915      instead, if you want to get data indexed by the extension OID
1916      rather than sequence.
1917
1918      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1919      otherwise a negative error code in case of an error.  If your have
1920      reached the last extension available
1921      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1922
1923      *Since:* 2.8.0
1924
1925 gnutls_x509_crq_get_extension_data2
1926 -----------------------------------
1927
1928  -- Function: int gnutls_x509_crq_get_extension_data2 (gnutls_x509_crq_t
1929           CRQ, unsigned INDX, gnutls_datum_t * DATA)
1930      CRQ: should contain a 'gnutls_x509_crq_t' type
1931
1932      INDX: Specifies which extension OID to read.  Use (0) to get the
1933      first one.
1934
1935      DATA: will contain the extension DER-encoded data
1936
1937      This function will return the requested extension data in the
1938      certificate request.  The extension data will be allocated using
1939      'gnutls_malloc()' .
1940
1941      Use 'gnutls_x509_crq_get_extension_info()' to extract the OID.
1942
1943      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1944      otherwise a negative error code is returned.  If you have reached
1945      the last extension available
1946      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1947
1948      *Since:* 3.3.0
1949
1950 gnutls_x509_crq_get_extension_info
1951 ----------------------------------
1952
1953  -- Function: int gnutls_x509_crq_get_extension_info (gnutls_x509_crq_t
1954           CRQ, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
1955           CRITICAL)
1956      CRQ: should contain a 'gnutls_x509_crq_t' type
1957
1958      INDX: Specifies which extension number to get.  Use (0) to get the
1959      first one.
1960
1961      OID: a pointer to store the OID
1962
1963      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
1964      holds actual size of 'oid' .
1965
1966      CRITICAL: output variable with critical flag, may be NULL.
1967
1968      This function will return the requested extension OID in the
1969      certificate, and the critical flag for it.  The extension OID will
1970      be stored as a string in the provided buffer.  Use
1971      'gnutls_x509_crq_get_extension_data()' to extract the data.
1972
1973      If the buffer provided is not long enough to hold the output, then
1974      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
1975      be returned.
1976
1977      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1978      otherwise a negative error code in case of an error.  If your have
1979      reached the last extension available
1980      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
1981
1982      *Since:* 2.8.0
1983
1984 gnutls_x509_crq_get_key_id
1985 --------------------------
1986
1987  -- Function: int gnutls_x509_crq_get_key_id (gnutls_x509_crq_t CRQ,
1988           unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
1989           OUTPUT_DATA_SIZE)
1990      CRQ: a certificate of type 'gnutls_x509_crq_t'
1991
1992      FLAGS: should be one of the flags from 'gnutls_keyid_flags_t'
1993
1994      OUTPUT_DATA: will contain the key ID
1995
1996      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
1997      replaced by the actual size of parameters)
1998
1999      This function will return a unique ID that depends on the public
2000      key parameters.  This ID can be used in checking whether a
2001      certificate corresponds to the given private key.
2002
2003      If the buffer provided is not long enough to hold the output, then
2004      * 'output_data_size' is updated and GNUTLS_E_SHORT_MEMORY_BUFFER
2005      will be returned.  The output will normally be a SHA-1 hash output,
2006      which is 20 bytes.
2007
2008      *Returns:* In case of failure a negative error code will be
2009      returned, and 0 on success.
2010
2011      *Since:* 2.8.0
2012
2013 gnutls_x509_crq_get_key_purpose_oid
2014 -----------------------------------
2015
2016  -- Function: int gnutls_x509_crq_get_key_purpose_oid (gnutls_x509_crq_t
2017           CRQ, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
2018           CRITICAL)
2019      CRQ: should contain a 'gnutls_x509_crq_t' type
2020
2021      INDX: This specifies which OID to return, use (0) to get the first
2022      one
2023
2024      OID: a pointer to store the OID (may be 'NULL' )
2025
2026      SIZEOF_OID: initially holds the size of 'oid'
2027
2028      CRITICAL: output variable with critical flag, may be 'NULL' .
2029
2030      This function will extract the key purpose OIDs of the Certificate
2031      specified by the given index.  These are stored in the Extended Key
2032      Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions for
2033      human readable names.
2034
2035      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
2036      not long enough, and in that case the * 'sizeof_oid' will be
2037      updated with the required size.  On success 0 is returned.
2038
2039      *Since:* 2.8.0
2040
2041 gnutls_x509_crq_get_key_rsa_raw
2042 -------------------------------
2043
2044  -- Function: int gnutls_x509_crq_get_key_rsa_raw (gnutls_x509_crq_t
2045           CRQ, gnutls_datum_t * M, gnutls_datum_t * E)
2046      CRQ: Holds the certificate
2047
2048      M: will hold the modulus
2049
2050      E: will hold the public exponent
2051
2052      This function will export the RSA public key's parameters found in
2053      the given structure.  The new parameters will be allocated using
2054      'gnutls_malloc()' and will be stored in the appropriate datum.
2055
2056      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2057      otherwise a negative error value.
2058
2059      *Since:* 2.8.0
2060
2061 gnutls_x509_crq_get_key_usage
2062 -----------------------------
2063
2064  -- Function: int gnutls_x509_crq_get_key_usage (gnutls_x509_crq_t CRQ,
2065           unsigned int * KEY_USAGE, unsigned int * CRITICAL)
2066      CRQ: should contain a 'gnutls_x509_crq_t' type
2067
2068      KEY_USAGE: where the key usage bits will be stored
2069
2070      CRITICAL: will be non-zero if the extension is marked as critical
2071
2072      This function will return certificate's key usage, by reading the
2073      keyUsage X.509 extension (2.5.29.15).  The key usage value will
2074      ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE' ,
2075      'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
2076      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
2077      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
2078      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
2079
2080      *Returns:* the certificate key usage, or a negative error code in
2081      case of parsing error.  If the certificate does not contain the
2082      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
2083      returned.
2084
2085      *Since:* 2.8.0
2086
2087 gnutls_x509_crq_get_pk_algorithm
2088 --------------------------------
2089
2090  -- Function: int gnutls_x509_crq_get_pk_algorithm (gnutls_x509_crq_t
2091           CRQ, unsigned int * BITS)
2092      CRQ: should contain a 'gnutls_x509_crq_t' type
2093
2094      BITS: if bits is non-'NULL' it will hold the size of the
2095      parameters' in bits
2096
2097      This function will return the public key algorithm of a PKCS'10'
2098      certificate request.
2099
2100      If bits is non-'NULL' , it should have enough size to hold the
2101      parameters size in bits.  For RSA the bits returned is the modulus.
2102      For DSA the bits returned are of the public exponent.
2103
2104      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
2105      success, or a negative error code on error.
2106
2107 gnutls_x509_crq_get_private_key_usage_period
2108 --------------------------------------------
2109
2110  -- Function: int gnutls_x509_crq_get_private_key_usage_period
2111           (gnutls_x509_crq_t CRQ, time_t * ACTIVATION, time_t *
2112           EXPIRATION, unsigned int * CRITICAL)
2113      CRQ: should contain a 'gnutls_x509_crq_t' type
2114
2115      ACTIVATION: The activation time
2116
2117      EXPIRATION: The expiration time
2118
2119      CRITICAL: the extension status
2120
2121      This function will return the expiration and activation times of
2122      the private key of the certificate.
2123
2124      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2125      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
2126      present, otherwise a negative error value.
2127
2128 gnutls_x509_crq_get_signature_algorithm
2129 ---------------------------------------
2130
2131  -- Function: int gnutls_x509_crq_get_signature_algorithm
2132           (gnutls_x509_crq_t CRQ)
2133      CRQ: should contain a 'gnutls_x509_cr_t' type
2134
2135      This function will return a value of the 'gnutls_sign_algorithm_t'
2136      enumeration that is the signature algorithm that has been used to
2137      sign this certificate request.
2138
2139      *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
2140      code on error.
2141
2142      *Since:* 3.4.0
2143
2144 gnutls_x509_crq_get_subject_alt_name
2145 ------------------------------------
2146
2147  -- Function: int gnutls_x509_crq_get_subject_alt_name
2148           (gnutls_x509_crq_t CRQ, unsigned int SEQ, void * RET, size_t *
2149           RET_SIZE, unsigned int * RET_TYPE, unsigned int * CRITICAL)
2150      CRQ: should contain a 'gnutls_x509_crq_t' type
2151
2152      SEQ: specifies the sequence number of the alt name, 0 for the first
2153      one, 1 for the second etc.
2154
2155      RET: is the place where the alternative name will be copied to
2156
2157      RET_SIZE: holds the size of ret.
2158
2159      RET_TYPE: holds the 'gnutls_x509_subject_alt_name_t' name type
2160
2161      CRITICAL: will be non-zero if the extension is marked as critical
2162      (may be null)
2163
2164      This function will return the alternative names, contained in the
2165      given certificate.  It is the same as
2166      'gnutls_x509_crq_get_subject_alt_name()' except for the fact that
2167      it will return the type of the alternative name in 'ret_type' even
2168      if the function fails for some reason (i.e.  the buffer provided is
2169      not enough).
2170
2171      *Returns:* the alternative subject name type on success, one of the
2172      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
2173      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ret_size' is not large enough to
2174      hold the value.  In that case 'ret_size' will be updated with the
2175      required size.  If the certificate request does not have an
2176      Alternative name with the specified sequence number then
2177      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
2178
2179      *Since:* 2.8.0
2180
2181 gnutls_x509_crq_get_subject_alt_othername_oid
2182 ---------------------------------------------
2183
2184  -- Function: int gnutls_x509_crq_get_subject_alt_othername_oid
2185           (gnutls_x509_crq_t CRQ, unsigned int SEQ, void * RET, size_t *
2186           RET_SIZE)
2187      CRQ: should contain a 'gnutls_x509_crq_t' type
2188
2189      SEQ: specifies the sequence number of the alt name (0 for the first
2190      one, 1 for the second etc.)
2191
2192      RET: is the place where the otherName OID will be copied to
2193
2194      RET_SIZE: holds the size of ret.
2195
2196      This function will extract the type OID of an otherName Subject
2197      Alternative Name, contained in the given certificate, and return
2198      the type as an enumerated element.
2199
2200      This function is only useful if
2201      'gnutls_x509_crq_get_subject_alt_name()' returned
2202      'GNUTLS_SAN_OTHERNAME' .
2203
2204      *Returns:* the alternative subject name type on success, one of the
2205      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
2206      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
2207      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
2208      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
2209      'ret_size' is not large enough to hold the value.  In that case
2210      'ret_size' will be updated with the required size.  If the
2211      certificate does not have an Alternative name with the specified
2212      sequence number and with the otherName type then
2213      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
2214
2215      *Since:* 2.8.0
2216
2217 gnutls_x509_crq_get_version
2218 ---------------------------
2219
2220  -- Function: int gnutls_x509_crq_get_version (gnutls_x509_crq_t CRQ)
2221      CRQ: should contain a 'gnutls_x509_crq_t' type
2222
2223      This function will return the version of the specified Certificate
2224      request.
2225
2226      *Returns:* version of certificate request, or a negative error code
2227      on error.
2228
2229 gnutls_x509_crq_import
2230 ----------------------
2231
2232  -- Function: int gnutls_x509_crq_import (gnutls_x509_crq_t CRQ, const
2233           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
2234      CRQ: The data to store the parsed certificate request.
2235
2236      DATA: The DER or PEM encoded certificate.
2237
2238      FORMAT: One of DER or PEM
2239
2240      This function will convert the given DER or PEM encoded certificate
2241      request to a 'gnutls_x509_crq_t' type.  The output will be stored
2242      in 'crq' .
2243
2244      If the Certificate is PEM encoded it should have a header of "NEW
2245      CERTIFICATE REQUEST".
2246
2247      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2248      otherwise a negative error value.
2249
2250 gnutls_x509_crq_init
2251 --------------------
2252
2253  -- Function: int gnutls_x509_crq_init (gnutls_x509_crq_t * CRQ)
2254      CRQ: A pointer to the type to be initialized
2255
2256      This function will initialize a PKCS'10' certificate request
2257      structure.
2258
2259      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2260      otherwise a negative error value.
2261
2262 gnutls_x509_crq_print
2263 ---------------------
2264
2265  -- Function: int gnutls_x509_crq_print (gnutls_x509_crq_t CRQ,
2266           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
2267           OUT)
2268      CRQ: The data to be printed
2269
2270      FORMAT: Indicate the format to use
2271
2272      OUT: Newly allocated datum with null terminated string.
2273
2274      This function will pretty print a certificate request, suitable for
2275      display to a human.
2276
2277      The output 'out' needs to be deallocated using 'gnutls_free()' .
2278
2279      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2280      otherwise a negative error value.
2281
2282      *Since:* 2.8.0
2283
2284 gnutls_x509_crq_set_attribute_by_oid
2285 ------------------------------------
2286
2287  -- Function: int gnutls_x509_crq_set_attribute_by_oid
2288           (gnutls_x509_crq_t CRQ, const char * OID, void * BUF, size_t
2289           BUF_SIZE)
2290      CRQ: should contain a 'gnutls_x509_crq_t' type
2291
2292      OID: holds an Object Identifier in a null-terminated string
2293
2294      BUF: a pointer to a structure that holds the attribute data
2295
2296      BUF_SIZE: holds the size of 'buf'
2297
2298      This function will set the attribute in the certificate request
2299      specified by the given Object ID. The provided attribute must be be
2300      DER encoded.
2301
2302      Attributes in a certificate request is an optional set of data
2303      appended to the request.  Their interpretation depends on the CA
2304      policy.
2305
2306      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2307      otherwise a negative error value.
2308
2309 gnutls_x509_crq_set_basic_constraints
2310 -------------------------------------
2311
2312  -- Function: int gnutls_x509_crq_set_basic_constraints
2313           (gnutls_x509_crq_t CRQ, unsigned int CA, int
2314           PATHLENCONSTRAINT)
2315      CRQ: a certificate request of type 'gnutls_x509_crq_t'
2316
2317      CA: true(1) or false(0) depending on the Certificate authority
2318      status.
2319
2320      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
2321      of path, and negative error codes indicate that the
2322      pathLenConstraints field should not be present.
2323
2324      This function will set the basicConstraints certificate extension.
2325
2326      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2327      otherwise a negative error value.
2328
2329      *Since:* 2.8.0
2330
2331 gnutls_x509_crq_set_challenge_password
2332 --------------------------------------
2333
2334  -- Function: int gnutls_x509_crq_set_challenge_password
2335           (gnutls_x509_crq_t CRQ, const char * PASS)
2336      CRQ: should contain a 'gnutls_x509_crq_t' type
2337
2338      PASS: holds a (0)-terminated password
2339
2340      This function will set a challenge password to be used when
2341      revoking the request.
2342
2343      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2344      otherwise a negative error value.
2345
2346 gnutls_x509_crq_set_dn
2347 ----------------------
2348
2349  -- Function: int gnutls_x509_crq_set_dn (gnutls_x509_crq_t CRQ, const
2350           char * DN, const char ** ERR)
2351      CRQ: a certificate of type 'gnutls_x509_crq_t'
2352
2353      DN: a comma separated DN string (RFC4514)
2354
2355      ERR: indicates the error position (if any)
2356
2357      This function will set the DN on the provided certificate.  The
2358      input string should be plain ASCII or UTF-8 encoded.
2359
2360      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2361      otherwise a negative error value.
2362
2363 gnutls_x509_crq_set_dn_by_oid
2364 -----------------------------
2365
2366  -- Function: int gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t CRQ,
2367           const char * OID, unsigned int RAW_FLAG, const void * DATA,
2368           unsigned int SIZEOF_DATA)
2369      CRQ: should contain a 'gnutls_x509_crq_t' type
2370
2371      OID: holds an Object Identifier in a (0)-terminated string
2372
2373      RAW_FLAG: must be 0, or 1 if the data are DER encoded
2374
2375      DATA: a pointer to the input data
2376
2377      SIZEOF_DATA: holds the size of 'data'
2378
2379      This function will set the part of the name of the Certificate
2380      request subject, specified by the given OID. The input string
2381      should be ASCII or UTF-8 encoded.
2382
2383      Some helper macros with popular OIDs can be found in gnutls/x509.h
2384      With this function you can only set the known OIDs.  You can test
2385      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
2386      are not known (by gnutls) you should properly DER encode your data,
2387      and call this function with raw_flag set.
2388
2389      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2390      otherwise a negative error value.
2391
2392 gnutls_x509_crq_set_key
2393 -----------------------
2394
2395  -- Function: int gnutls_x509_crq_set_key (gnutls_x509_crq_t CRQ,
2396           gnutls_x509_privkey_t KEY)
2397      CRQ: should contain a 'gnutls_x509_crq_t' type
2398
2399      KEY: holds a private key
2400
2401      This function will set the public parameters from the given private
2402      key to the request.
2403
2404      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2405      otherwise a negative error value.
2406
2407 gnutls_x509_crq_set_key_purpose_oid
2408 -----------------------------------
2409
2410  -- Function: int gnutls_x509_crq_set_key_purpose_oid (gnutls_x509_crq_t
2411           CRQ, const void * OID, unsigned int CRITICAL)
2412      CRQ: a certificate of type 'gnutls_x509_crq_t'
2413
2414      OID: a pointer to a null-terminated string that holds the OID
2415
2416      CRITICAL: Whether this extension will be critical or not
2417
2418      This function will set the key purpose OIDs of the Certificate.
2419      These are stored in the Extended Key Usage extension (2.5.29.37)
2420      See the GNUTLS_KP_* definitions for human readable names.
2421
2422      Subsequent calls to this function will append OIDs to the OID list.
2423
2424      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2425      otherwise a negative error value.
2426
2427      *Since:* 2.8.0
2428
2429 gnutls_x509_crq_set_key_rsa_raw
2430 -------------------------------
2431
2432  -- Function: int gnutls_x509_crq_set_key_rsa_raw (gnutls_x509_crq_t
2433           CRQ, const gnutls_datum_t * M, const gnutls_datum_t * E)
2434      CRQ: should contain a 'gnutls_x509_crq_t' type
2435
2436      M: holds the modulus
2437
2438      E: holds the public exponent
2439
2440      This function will set the public parameters from the given private
2441      key to the request.  Only RSA keys are currently supported.
2442
2443      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2444      otherwise a negative error value.
2445
2446      *Since:* 2.6.0
2447
2448 gnutls_x509_crq_set_key_usage
2449 -----------------------------
2450
2451  -- Function: int gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t CRQ,
2452           unsigned int USAGE)
2453      CRQ: a certificate request of type 'gnutls_x509_crq_t'
2454
2455      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
2456
2457      This function will set the keyUsage certificate extension.
2458
2459      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2460      otherwise a negative error value.
2461
2462      *Since:* 2.8.0
2463
2464 gnutls_x509_crq_set_private_key_usage_period
2465 --------------------------------------------
2466
2467  -- Function: int gnutls_x509_crq_set_private_key_usage_period
2468           (gnutls_x509_crq_t CRQ, time_t ACTIVATION, time_t EXPIRATION)
2469      CRQ: a certificate of type 'gnutls_x509_crq_t'
2470
2471      ACTIVATION: The activation time
2472
2473      EXPIRATION: The expiration time
2474
2475      This function will set the private key usage period extension
2476      (2.5.29.16).
2477
2478      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2479      otherwise a negative error value.
2480
2481 gnutls_x509_crq_set_subject_alt_name
2482 ------------------------------------
2483
2484  -- Function: int gnutls_x509_crq_set_subject_alt_name
2485           (gnutls_x509_crq_t CRQ, gnutls_x509_subject_alt_name_t NT,
2486           const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS)
2487      CRQ: a certificate request of type 'gnutls_x509_crq_t'
2488
2489      NT: is one of the 'gnutls_x509_subject_alt_name_t' enumerations
2490
2491      DATA: The data to be set
2492
2493      DATA_SIZE: The size of data to be set
2494
2495      FLAGS: 'GNUTLS_FSAN_SET' to clear previous data or
2496      'GNUTLS_FSAN_APPEND' to append.
2497
2498      This function will set the subject alternative name certificate
2499      extension.  It can set the following types:
2500
2501      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2502      otherwise a negative error value.
2503
2504      *Since:* 2.8.0
2505
2506 gnutls_x509_crq_set_version
2507 ---------------------------
2508
2509  -- Function: int gnutls_x509_crq_set_version (gnutls_x509_crq_t CRQ,
2510           unsigned int VERSION)
2511      CRQ: should contain a 'gnutls_x509_crq_t' type
2512
2513      VERSION: holds the version number, for v1 Requests must be 1
2514
2515      This function will set the version of the certificate request.  For
2516      version 1 requests this must be one.
2517
2518      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2519      otherwise a negative error value.
2520
2521 gnutls_x509_crq_sign2
2522 ---------------------
2523
2524  -- Function: int gnutls_x509_crq_sign2 (gnutls_x509_crq_t CRQ,
2525           gnutls_x509_privkey_t KEY, gnutls_digest_algorithm_t DIG,
2526           unsigned int FLAGS)
2527      CRQ: should contain a 'gnutls_x509_crq_t' type
2528
2529      KEY: holds a private key
2530
2531      DIG: The message digest to use, i.e., 'GNUTLS_DIG_SHA1'
2532
2533      FLAGS: must be 0
2534
2535      This function will sign the certificate request with a private key.
2536      This must be the same key as the one used in
2537      'gnutls_x509_crt_set_key()' since a certificate request is self
2538      signed.
2539
2540      This must be the last step in a certificate request generation
2541      since all the previously set parameters are now signed.
2542
2543      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
2544      error code.  'GNUTLS_E_ASN1_VALUE_NOT_FOUND' is returned if you
2545      didn't set all information in the certificate request (e.g., the
2546      version using 'gnutls_x509_crq_set_version()' ).
2547
2548 gnutls_x509_crq_verify
2549 ----------------------
2550
2551  -- Function: int gnutls_x509_crq_verify (gnutls_x509_crq_t CRQ,
2552           unsigned int FLAGS)
2553      CRQ: is the crq to be verified
2554
2555      FLAGS: Flags that may be used to change the verification algorithm.
2556      Use OR of the gnutls_certificate_verify_flags enumerations.
2557
2558      This function will verify self signature in the certificate request
2559      and return its status.
2560
2561      *Returns:* In case of a verification failure
2562      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
2563      code on success.
2564
2565      Since 2.12.0
2566
2567 gnutls_x509_crt_check_email
2568 ---------------------------
2569
2570  -- Function: int gnutls_x509_crt_check_email (gnutls_x509_crt_t CERT,
2571           const char * EMAIL, unsigned int FLAGS)
2572      CERT: should contain an gnutls_x509_crt_t type
2573
2574      EMAIL: A null terminated string that contains an email address
2575      (RFC822)
2576
2577      FLAGS: should be zero
2578
2579      This function will check if the given certificate's subject matches
2580      the given email address.
2581
2582      *Returns:* non-zero for a successful match, and zero on failure.
2583
2584 gnutls_x509_crt_check_hostname
2585 ------------------------------
2586
2587  -- Function: int gnutls_x509_crt_check_hostname (gnutls_x509_crt_t
2588           CERT, const char * HOSTNAME)
2589      CERT: should contain an gnutls_x509_crt_t type
2590
2591      HOSTNAME: A null terminated string that contains a DNS name
2592
2593      This function will check if the given certificate's subject matches
2594      the given hostname.  This is a basic implementation of the matching
2595      described in RFC6125, and takes into account wildcards, and the
2596      DNSName/IPAddress subject alternative name PKIX extension.
2597
2598      For details see also 'gnutls_x509_crt_check_hostname2()' .
2599
2600      *Returns:* non-zero for a successful match, and zero on failure.
2601
2602 gnutls_x509_crt_check_hostname2
2603 -------------------------------
2604
2605  -- Function: int gnutls_x509_crt_check_hostname2 (gnutls_x509_crt_t
2606           CERT, const char * HOSTNAME, unsigned int FLAGS)
2607      CERT: should contain an gnutls_x509_crt_t type
2608
2609      HOSTNAME: A null terminated string that contains a DNS name
2610
2611      FLAGS: gnutls_certificate_verify_flags
2612
2613      This function will check if the given certificate's subject matches
2614      the given hostname.  This is a basic implementation of the matching
2615      described in RFC6125, and takes into account wildcards, and the
2616      DNSName/IPAddress subject alternative name PKIX extension.
2617
2618      IPv4 addresses are accepted by this function in the dotted-decimal
2619      format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the
2620      hexadecimal x:x:x:x:x:x:x:x format.  For them the IPAddress subject
2621      alternative name extension is consulted, as well as the DNSNames in
2622      case of a non-match.  The latter fallback exists due to
2623      misconfiguration of many servers which place an IPAddress inside
2624      the DNSName extension.
2625
2626      When the flag 'GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS' is specified
2627      no wildcards are considered.  Otherwise they are only considered if
2628      the domain name consists of three components or more, and the
2629      wildcard starts at the leftmost position.
2630
2631      *Returns:* non-zero for a successful match, and zero on failure.
2632
2633 gnutls_x509_crt_check_issuer
2634 ----------------------------
2635
2636  -- Function: int gnutls_x509_crt_check_issuer (gnutls_x509_crt_t CERT,
2637           gnutls_x509_crt_t ISSUER)
2638      CERT: is the certificate to be checked
2639
2640      ISSUER: is the certificate of a possible issuer
2641
2642      This function will check if the given certificate was issued by the
2643      given issuer.  It checks the DN fields and the authority key
2644      identifier and subject key identifier fields match.
2645
2646      If the same certificate is provided at the 'cert' and 'issuer'
2647      fields, it will check whether the certificate is self-signed.
2648
2649      *Returns:* It will return true (1) if the given certificate is
2650      issued by the given issuer, and false (0) if not.
2651
2652 gnutls_x509_crt_check_revocation
2653 --------------------------------
2654
2655  -- Function: int gnutls_x509_crt_check_revocation (gnutls_x509_crt_t
2656           CERT, const gnutls_x509_crl_t * CRL_LIST, int CRL_LIST_LENGTH)
2657      CERT: should contain a 'gnutls_x509_crt_t' type
2658
2659      CRL_LIST: should contain a list of gnutls_x509_crl_t types
2660
2661      CRL_LIST_LENGTH: the length of the crl_list
2662
2663      This function will return check if the given certificate is
2664      revoked.  It is assumed that the CRLs have been verified before.
2665
2666      *Returns:* 0 if the certificate is NOT revoked, and 1 if it is.  A
2667      negative error code is returned on error.
2668
2669 gnutls_x509_crt_cpy_crl_dist_points
2670 -----------------------------------
2671
2672  -- Function: int gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t
2673           DST, gnutls_x509_crt_t SRC)
2674      DST: a certificate of type 'gnutls_x509_crt_t'
2675
2676      SRC: the certificate where the dist points will be copied from
2677
2678      This function will copy the CRL distribution points certificate
2679      extension, from the source to the destination certificate.  This
2680      may be useful to copy from a CA certificate to issued ones.
2681
2682      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2683      otherwise a negative error value.
2684
2685 gnutls_x509_crt_deinit
2686 ----------------------
2687
2688  -- Function: void gnutls_x509_crt_deinit (gnutls_x509_crt_t CERT)
2689      CERT: The data to be deinitialized
2690
2691      This function will deinitialize a certificate structure.
2692
2693 gnutls_x509_crt_export
2694 ----------------------
2695
2696  -- Function: int gnutls_x509_crt_export (gnutls_x509_crt_t CERT,
2697           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
2698           OUTPUT_DATA_SIZE)
2699      CERT: Holds the certificate
2700
2701      FORMAT: the format of output params.  One of PEM or DER.
2702
2703      OUTPUT_DATA: will contain a certificate PEM or DER encoded
2704
2705      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
2706      replaced by the actual size of parameters)
2707
2708      This function will export the certificate to DER or PEM format.
2709
2710      If the buffer provided is not long enough to hold the output, then
2711      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2712      be returned.
2713
2714      If the structure is PEM encoded, it will have a header of "BEGIN
2715      CERTIFICATE".
2716
2717      *Returns:* In case of failure a negative error code will be
2718      returned, and 0 on success.
2719
2720 gnutls_x509_crt_export2
2721 -----------------------
2722
2723  -- Function: int gnutls_x509_crt_export2 (gnutls_x509_crt_t CERT,
2724           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
2725      CERT: Holds the certificate
2726
2727      FORMAT: the format of output params.  One of PEM or DER.
2728
2729      OUT: will contain a certificate PEM or DER encoded
2730
2731      This function will export the certificate to DER or PEM format.
2732      The output buffer is allocated using 'gnutls_malloc()' .
2733
2734      If the structure is PEM encoded, it will have a header of "BEGIN
2735      CERTIFICATE".
2736
2737      *Returns:* In case of failure a negative error code will be
2738      returned, and 0 on success.
2739
2740      *Since:* 3.1.3
2741
2742 gnutls_x509_crt_get_activation_time
2743 -----------------------------------
2744
2745  -- Function: time_t gnutls_x509_crt_get_activation_time
2746           (gnutls_x509_crt_t CERT)
2747      CERT: should contain a 'gnutls_x509_crt_t' type
2748
2749      This function will return the time this Certificate was or will be
2750      activated.
2751
2752      *Returns:* activation time, or (time_t)-1 on error.
2753
2754 gnutls_x509_crt_get_authority_info_access
2755 -----------------------------------------
2756
2757  -- Function: int gnutls_x509_crt_get_authority_info_access
2758           (gnutls_x509_crt_t CRT, unsigned int SEQ, int WHAT,
2759           gnutls_datum_t * DATA, unsigned int * CRITICAL)
2760      CRT: Holds the certificate
2761
2762      SEQ: specifies the sequence number of the access descriptor (0 for
2763      the first one, 1 for the second etc.)
2764
2765      WHAT: what data to get, a 'gnutls_info_access_what_t' type.
2766
2767      DATA: output data to be freed with 'gnutls_free()' .
2768
2769      CRITICAL: pointer to output integer that is set to non-zero if the
2770      extension is marked as critical (may be 'NULL' )
2771
2772      Note that a simpler API to access the authority info data is
2773      provided by 'gnutls_x509_aia_get()' and
2774      'gnutls_x509_ext_import_aia()' .
2775
2776      This function extracts the Authority Information Access (AIA)
2777      extension, see RFC 5280 section 4.2.2.1 for more information.  The
2778      AIA extension holds a sequence of AccessDescription (AD) data.
2779
2780      The 'seq' input parameter is used to indicate which member of the
2781      sequence the caller is interested in.  The first member is 0, the
2782      second member 1 and so on.  When the 'seq' value is out of bounds,
2783      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
2784
2785      The type of data returned in 'data' is specified via 'what' which
2786      should be 'gnutls_info_access_what_t' values.
2787
2788      If 'what' is 'GNUTLS_IA_ACCESSMETHOD_OID' then 'data' will hold the
2789      accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
2790
2791      If 'what' is 'GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE' , 'data'
2792      will hold the accessLocation GeneralName type (e.g.,
2793      "uniformResourceIdentifier").
2794
2795      If 'what' is 'GNUTLS_IA_URI' , 'data' will hold the accessLocation
2796      URI data.  Requesting this 'what' value leads to an error if the
2797      accessLocation is not of the "uniformResourceIdentifier" type.
2798
2799      If 'what' is 'GNUTLS_IA_OCSP_URI' , 'data' will hold the OCSP URI.
2800      Requesting this 'what' value leads to an error if the accessMethod
2801      is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
2802      the "uniformResourceIdentifier" type.  In that case
2803      'GNUTLS_E_UNKNOWN_ALGORITHM' will be returned, and 'seq' should be
2804      increased and this function called again.
2805
2806      If 'what' is 'GNUTLS_IA_CAISSUERS_URI' , 'data' will hold the
2807      caIssuers URI. Requesting this 'what' value leads to an error if
2808      the accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
2809      accessLocation is not of the "uniformResourceIdentifier" type.  In
2810      that case handle as in 'GNUTLS_IA_OCSP_URI' .
2811
2812      More 'what' values may be allocated in the future as needed.
2813
2814      If 'data' is NULL, the function does the same without storing the
2815      output data, that is, it will set 'critical' and do error checking
2816      as usual.
2817
2818      The value of the critical flag is returned in * 'critical' .
2819      Supply a NULL 'critical' if you want the function to make sure the
2820      extension is non-critical, as required by RFC 5280.
2821
2822      *Returns:* 'GNUTLS_E_SUCCESS' on success,
2823      'GNUTLS_E_INVALID_REQUEST' on invalid 'crt' ,
2824      'GNUTLS_E_CONSTRAINT_ERROR' if the extension is incorrectly marked
2825      as critical (use a non-NULL 'critical' to override),
2826      'GNUTLS_E_UNKNOWN_ALGORITHM' if the requested OID does not match
2827      (e.g., when using 'GNUTLS_IA_OCSP_URI' ), otherwise a negative
2828      error code.
2829
2830      *Since:* 3.0
2831
2832 gnutls_x509_crt_get_authority_key_gn_serial
2833 -------------------------------------------
2834
2835  -- Function: int gnutls_x509_crt_get_authority_key_gn_serial
2836           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * ALT, size_t
2837           * ALT_SIZE, unsigned int * ALT_TYPE, void * SERIAL, size_t *
2838           SERIAL_SIZE, unsigned int * CRITICAL)
2839      CERT: should contain a 'gnutls_x509_crt_t' type
2840
2841      SEQ: specifies the sequence number of the alt name (0 for the first
2842      one, 1 for the second etc.)
2843
2844      ALT: is the place where the alternative name will be copied to
2845
2846      ALT_SIZE: holds the size of alt.
2847
2848      ALT_TYPE: holds the type of the alternative name (one of
2849      gnutls_x509_subject_alt_name_t).
2850
2851      SERIAL: buffer to store the serial number (may be null)
2852
2853      SERIAL_SIZE: Holds the size of the serial field (may be null)
2854
2855      CRITICAL: will be non-zero if the extension is marked as critical
2856      (may be null)
2857
2858      This function will return the X.509 authority key identifier when
2859      stored as a general name (authorityCertIssuer) and serial number.
2860
2861      Because more than one general names might be stored 'seq' can be
2862      used as a counter to request them all until
2863      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
2864
2865      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2866      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
2867      present, otherwise a negative error value.
2868
2869      *Since:* 3.0
2870
2871 gnutls_x509_crt_get_authority_key_id
2872 ------------------------------------
2873
2874  -- Function: int gnutls_x509_crt_get_authority_key_id
2875           (gnutls_x509_crt_t CERT, void * ID, size_t * ID_SIZE, unsigned
2876           int * CRITICAL)
2877      CERT: should contain a 'gnutls_x509_crt_t' type
2878
2879      ID: The place where the identifier will be copied
2880
2881      ID_SIZE: Holds the size of the id field.
2882
2883      CRITICAL: will be non-zero if the extension is marked as critical
2884      (may be null)
2885
2886      This function will return the X.509v3 certificate authority's key
2887      identifier.  This is obtained by the X.509 Authority Key identifier
2888      extension field (2.5.29.35).  Note that this function only returns
2889      the keyIdentifier field of the extension and
2890      'GNUTLS_E_X509_UNSUPPORTED_EXTENSION' , if the extension contains
2891      the name and serial number of the certificate.  In that case
2892      'gnutls_x509_crt_get_authority_key_gn_serial()' may be used.
2893
2894      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2895      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
2896      present, otherwise a negative error value.
2897
2898 gnutls_x509_crt_get_basic_constraints
2899 -------------------------------------
2900
2901  -- Function: int gnutls_x509_crt_get_basic_constraints
2902           (gnutls_x509_crt_t CERT, unsigned int * CRITICAL, unsigned int
2903           * CA, int * PATHLEN)
2904      CERT: should contain a 'gnutls_x509_crt_t' type
2905
2906      CRITICAL: will be non-zero if the extension is marked as critical
2907
2908      CA: pointer to output integer indicating CA status, may be NULL,
2909      value is 1 if the certificate CA flag is set, 0 otherwise.
2910
2911      PATHLEN: pointer to output integer indicating path length (may be
2912      NULL), non-negative error codes indicate a present
2913      pathLenConstraint field and the actual value, -1 indicate that the
2914      field is absent.
2915
2916      This function will read the certificate's basic constraints, and
2917      return the certificates CA status.  It reads the basicConstraints
2918      X.509 extension (2.5.29.19).
2919
2920      *Returns:* If the certificate is a CA a positive value will be
2921      returned, or (0) if the certificate does not have CA flag set.  A
2922      negative error code may be returned in case of errors.  If the
2923      certificate does not contain the basicConstraints extension
2924      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2925
2926 gnutls_x509_crt_get_ca_status
2927 -----------------------------
2928
2929  -- Function: int gnutls_x509_crt_get_ca_status (gnutls_x509_crt_t CERT,
2930           unsigned int * CRITICAL)
2931      CERT: should contain a 'gnutls_x509_crt_t' type
2932
2933      CRITICAL: will be non-zero if the extension is marked as critical
2934
2935      This function will return certificates CA status, by reading the
2936      basicConstraints X.509 extension (2.5.29.19).  If the certificate
2937      is a CA a positive value will be returned, or (0) if the
2938      certificate does not have CA flag set.
2939
2940      Use 'gnutls_x509_crt_get_basic_constraints()' if you want to read
2941      the pathLenConstraint field too.
2942
2943      *Returns:* If the certificate is a CA a positive value will be
2944      returned, or (0) if the certificate does not have CA flag set.  A
2945      negative error code may be returned in case of errors.  If the
2946      certificate does not contain the basicConstraints extension
2947      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
2948
2949 gnutls_x509_crt_get_crl_dist_points
2950 -----------------------------------
2951
2952  -- Function: int gnutls_x509_crt_get_crl_dist_points (gnutls_x509_crt_t
2953           CERT, unsigned int SEQ, void * SAN, size_t * SAN_SIZE,
2954           unsigned int * REASON_FLAGS, unsigned int * CRITICAL)
2955      CERT: should contain a 'gnutls_x509_crt_t' type
2956
2957      SEQ: specifies the sequence number of the distribution point (0 for
2958      the first one, 1 for the second etc.)
2959
2960      SAN: is the place where the distribution point will be copied to
2961
2962      SAN_SIZE: holds the size of ret.
2963
2964      REASON_FLAGS: Revocation reasons.  An ORed sequence of flags from
2965      'gnutls_x509_crl_reason_flags_t' .
2966
2967      CRITICAL: will be non-zero if the extension is marked as critical
2968      (may be null)
2969
2970      This function retrieves the CRL distribution points (2.5.29.31),
2971      contained in the given certificate in the X509v3 Certificate
2972      Extensions.
2973
2974      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' and updates 'ret_size' if
2975      'ret_size' is not enough to hold the distribution point, or the
2976      type of the distribution point if everything was ok.  The type is
2977      one of the enumerated 'gnutls_x509_subject_alt_name_t' .  If the
2978      certificate does not have an Alternative name with the specified
2979      sequence number then 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is
2980      returned.
2981
2982 gnutls_x509_crt_get_dn
2983 ----------------------
2984
2985  -- Function: int gnutls_x509_crt_get_dn (gnutls_x509_crt_t CERT, char *
2986           BUF, size_t * BUF_SIZE)
2987      CERT: should contain a 'gnutls_x509_crt_t' type
2988
2989      BUF: a pointer to a structure to hold the name (may be null)
2990
2991      BUF_SIZE: initially holds the size of 'buf'
2992
2993      This function will copy the name of the Certificate in the provided
2994      buffer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
2995      described in RFC4514.  The output string will be ASCII or UTF-8
2996      encoded, depending on the certificate data.
2997
2998      If 'buf' is null then only the size will be filled.
2999
3000      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3001      not long enough, and in that case the 'buf_size' will be updated
3002      with the required size.  On success 0 is returned.
3003
3004 gnutls_x509_crt_get_dn2
3005 -----------------------
3006
3007  -- Function: int gnutls_x509_crt_get_dn2 (gnutls_x509_crt_t CERT,
3008           gnutls_datum_t * DN)
3009      CERT: should contain a 'gnutls_x509_crt_t' type
3010
3011      DN: a pointer to a structure to hold the name
3012
3013      This function will allocate buffer and copy the name of the
3014      Certificate.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz"
3015      as described in RFC4514.  The output string will be ASCII or UTF-8
3016      encoded, depending on the certificate data.
3017
3018      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3019      otherwise a negative error value.
3020
3021      *Since:* 3.1.10
3022
3023 gnutls_x509_crt_get_dn_by_oid
3024 -----------------------------
3025
3026  -- Function: int gnutls_x509_crt_get_dn_by_oid (gnutls_x509_crt_t CERT,
3027           const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF,
3028           size_t * BUF_SIZE)
3029      CERT: should contain a 'gnutls_x509_crt_t' type
3030
3031      OID: holds an Object Identified in null terminated string
3032
3033      INDX: In case multiple same OIDs exist in the RDN, this specifies
3034      which to send.  Use (0) to get the first one.
3035
3036      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
3037
3038      BUF: a pointer where the DN part will be copied (may be null).
3039
3040      BUF_SIZE: initially holds the size of 'buf'
3041
3042      This function will extract the part of the name of the Certificate
3043      subject specified by the given OID. The output, if the raw flag is
3044      not used, will be encoded as described in RFC4514.  Thus a string
3045      that is ASCII or UTF-8 encoded, depending on the certificate data.
3046
3047      Some helper macros with popular OIDs can be found in gnutls/x509.h
3048      If raw flag is (0), this function will only return known OIDs as
3049      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
3050      hex format with a '#' prefix.  You can check about known OIDs using
3051      'gnutls_x509_dn_oid_known()' .
3052
3053      If 'buf' is null then only the size will be filled.  If the
3054      'raw_flag' is not specified the output is always null terminated,
3055      although the 'buf_size' will not include the null character.
3056
3057      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3058      not long enough, and in that case the 'buf_size' will be updated
3059      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
3060      there are no data in the current index.  On success 0 is returned.
3061
3062 gnutls_x509_crt_get_dn_oid
3063 --------------------------
3064
3065  -- Function: int gnutls_x509_crt_get_dn_oid (gnutls_x509_crt_t CERT,
3066           int INDX, void * OID, size_t * OID_SIZE)
3067      CERT: should contain a 'gnutls_x509_crt_t' type
3068
3069      INDX: This specifies which OID to return.  Use (0) to get the first
3070      one.
3071
3072      OID: a pointer to a buffer to hold the OID (may be null)
3073
3074      OID_SIZE: initially holds the size of 'oid'
3075
3076      This function will extract the OIDs of the name of the Certificate
3077      subject specified by the given index.
3078
3079      If 'oid' is null then only the size will be filled.  The 'oid'
3080      returned will be null terminated, although 'oid_size' will not
3081      account for the trailing null.
3082
3083      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3084      not long enough, and in that case the 'buf_size' will be updated
3085      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
3086      there are no data in the current index.  On success 0 is returned.
3087
3088 gnutls_x509_crt_get_expiration_time
3089 -----------------------------------
3090
3091  -- Function: time_t gnutls_x509_crt_get_expiration_time
3092           (gnutls_x509_crt_t CERT)
3093      CERT: should contain a 'gnutls_x509_crt_t' type
3094
3095      This function will return the time this Certificate was or will be
3096      expired.
3097
3098      The no well defined expiration time can be checked against with the
3099      'GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION' macro.
3100
3101      *Returns:* expiration time, or (time_t)-1 on error.
3102
3103 gnutls_x509_crt_get_extension_by_oid
3104 ------------------------------------
3105
3106  -- Function: int gnutls_x509_crt_get_extension_by_oid
3107           (gnutls_x509_crt_t CERT, const char * OID, int INDX, void *
3108           BUF, size_t * BUF_SIZE, unsigned int * CRITICAL)
3109      CERT: should contain a 'gnutls_x509_crt_t' type
3110
3111      OID: holds an Object Identified in null terminated string
3112
3113      INDX: In case multiple same OIDs exist in the extensions, this
3114      specifies which to send.  Use (0) to get the first one.
3115
3116      BUF: a pointer to a structure to hold the name (may be null)
3117
3118      BUF_SIZE: initially holds the size of 'buf'
3119
3120      CRITICAL: will be non-zero if the extension is marked as critical
3121
3122      This function will return the extension specified by the OID in the
3123      certificate.  The extensions will be returned as binary data DER
3124      encoded, in the provided buffer.
3125
3126      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3127      otherwise a negative error code is returned.  If the certificate
3128      does not contain the specified extension
3129      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
3130
3131 gnutls_x509_crt_get_extension_by_oid2
3132 -------------------------------------
3133
3134  -- Function: int gnutls_x509_crt_get_extension_by_oid2
3135           (gnutls_x509_crt_t CERT, const char * OID, int INDX,
3136           gnutls_datum_t * OUTPUT, unsigned int * CRITICAL)
3137      CERT: should contain a 'gnutls_x509_crt_t' type
3138
3139      OID: holds an Object Identified in null terminated string
3140
3141      INDX: In case multiple same OIDs exist in the extensions, this
3142      specifies which to send.  Use (0) to get the first one.
3143
3144      OUTPUT: will hold the allocated extension data
3145
3146      CRITICAL: will be non-zero if the extension is marked as critical
3147
3148      This function will return the extension specified by the OID in the
3149      certificate.  The extensions will be returned as binary data DER
3150      encoded, in the provided buffer.
3151
3152      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3153      otherwise a negative error code is returned.  If the certificate
3154      does not contain the specified extension
3155      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
3156
3157      *Since:* 3.3.8
3158
3159 gnutls_x509_crt_get_extension_data
3160 ----------------------------------
3161
3162  -- Function: int gnutls_x509_crt_get_extension_data (gnutls_x509_crt_t
3163           CERT, int INDX, void * DATA, size_t * SIZEOF_DATA)
3164      CERT: should contain a 'gnutls_x509_crt_t' type
3165
3166      INDX: Specifies which extension OID to send.  Use (0) to get the
3167      first one.
3168
3169      DATA: a pointer to a structure to hold the data (may be null)
3170
3171      SIZEOF_DATA: initially holds the size of 'data'
3172
3173      This function will return the requested extension data in the
3174      certificate.  The extension data will be stored in the provided
3175      buffer.
3176
3177      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID and
3178      critical flag.  Use 'gnutls_x509_crt_get_extension_by_oid()'
3179      instead, if you want to get data indexed by the extension OID
3180      rather than sequence.
3181
3182      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3183      otherwise a negative error code is returned.  If you have reached
3184      the last extension available
3185      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
3186
3187 gnutls_x509_crt_get_extension_data2
3188 -----------------------------------
3189
3190  -- Function: int gnutls_x509_crt_get_extension_data2 (gnutls_x509_crt_t
3191           CERT, unsigned INDX, gnutls_datum_t * DATA)
3192      CERT: should contain a 'gnutls_x509_crt_t' type
3193
3194      INDX: Specifies which extension OID to read.  Use (0) to get the
3195      first one.
3196
3197      DATA: will contain the extension DER-encoded data
3198
3199      This function will return the requested by the index extension data
3200      in the certificate.  The extension data will be allocated using
3201      'gnutls_malloc()' .
3202
3203      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID.
3204
3205      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3206      otherwise a negative error code is returned.  If you have reached
3207      the last extension available
3208      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
3209
3210 gnutls_x509_crt_get_extension_info
3211 ----------------------------------
3212
3213  -- Function: int gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t
3214           CERT, int INDX, void * OID, size_t * OID_SIZE, unsigned int *
3215           CRITICAL)
3216      CERT: should contain a 'gnutls_x509_crt_t' type
3217
3218      INDX: Specifies which extension OID to send.  Use (0) to get the
3219      first one.
3220
3221      OID: a pointer to a structure to hold the OID
3222
3223      OID_SIZE: initially holds the maximum size of 'oid' , on return
3224      holds actual size of 'oid' .
3225
3226      CRITICAL: output variable with critical flag, may be NULL.
3227
3228      This function will return the requested extension OID in the
3229      certificate, and the critical flag for it.  The extension OID will
3230      be stored as a string in the provided buffer.  Use
3231      'gnutls_x509_crt_get_extension()' to extract the data.
3232
3233      If the buffer provided is not long enough to hold the output, then
3234      'oid_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will be
3235      returned.  The 'oid' returned will be null terminated, although
3236      'oid_size' will not account for the trailing null.
3237
3238      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3239      otherwise a negative error code is returned.  If you have reached
3240      the last extension available
3241      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
3242
3243 gnutls_x509_crt_get_extension_oid
3244 ---------------------------------
3245
3246  -- Function: int gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t
3247           CERT, int INDX, void * OID, size_t * OID_SIZE)
3248      CERT: should contain a 'gnutls_x509_crt_t' type
3249
3250      INDX: Specifies which extension OID to send.  Use (0) to get the
3251      first one.
3252
3253      OID: a pointer to a structure to hold the OID (may be null)
3254
3255      OID_SIZE: initially holds the size of 'oid'
3256
3257      This function will return the requested extension OID in the
3258      certificate.  The extension OID will be stored as a string in the
3259      provided buffer.
3260
3261      The 'oid' returned will be null terminated, although 'oid_size'
3262      will not account for the trailing null.
3263
3264      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3265      otherwise a negative error code is returned.  If you have reached
3266      the last extension available
3267      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
3268
3269 gnutls_x509_crt_get_fingerprint
3270 -------------------------------
3271
3272  -- Function: int gnutls_x509_crt_get_fingerprint (gnutls_x509_crt_t
3273           CERT, gnutls_digest_algorithm_t ALGO, void * BUF, size_t *
3274           BUF_SIZE)
3275      CERT: should contain a 'gnutls_x509_crt_t' type
3276
3277      ALGO: is a digest algorithm
3278
3279      BUF: a pointer to a structure to hold the fingerprint (may be null)
3280
3281      BUF_SIZE: initially holds the size of 'buf'
3282
3283      This function will calculate and copy the certificate's fingerprint
3284      in the provided buffer.  The fingerprint is a hash of the
3285      DER-encoded data of the certificate.
3286
3287      If the buffer is null then only the size will be filled.
3288
3289      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3290      not long enough, and in that case the *buf_size will be updated
3291      with the required size.  On success 0 is returned.
3292
3293 gnutls_x509_crt_get_issuer
3294 --------------------------
3295
3296  -- Function: int gnutls_x509_crt_get_issuer (gnutls_x509_crt_t CERT,
3297           gnutls_x509_dn_t * DN)
3298      CERT: should contain a 'gnutls_x509_crt_t' type
3299
3300      DN: output variable with pointer to uint8_t DN
3301
3302      Return the Certificate's Issuer DN as a 'gnutls_x509_dn_t' data
3303      type, that can be decoded using 'gnutls_x509_dn_get_rdn_ava()' .
3304
3305      Note that 'dn' should be treated as constant.  Because it points
3306      into the 'cert' object, you should not use 'dn' after 'cert' is
3307      deallocated.
3308
3309      *Returns:* Returns 0 on success, or an error code.
3310
3311 gnutls_x509_crt_get_issuer_alt_name
3312 -----------------------------------
3313
3314  -- Function: int gnutls_x509_crt_get_issuer_alt_name (gnutls_x509_crt_t
3315           CERT, unsigned int SEQ, void * IAN, size_t * IAN_SIZE,
3316           unsigned int * CRITICAL)
3317      CERT: should contain a 'gnutls_x509_crt_t' type
3318
3319      SEQ: specifies the sequence number of the alt name (0 for the first
3320      one, 1 for the second etc.)
3321
3322      IAN: is the place where the alternative name will be copied to
3323
3324      IAN_SIZE: holds the size of ian.
3325
3326      CRITICAL: will be non-zero if the extension is marked as critical
3327      (may be null)
3328
3329      This function retrieves the Issuer Alternative Name (2.5.29.18),
3330      contained in the given certificate in the X509v3 Certificate
3331      Extensions.
3332
3333      When the SAN type is otherName, it will extract the data in the
3334      otherName's value field, and 'GNUTLS_SAN_OTHERNAME' is returned.
3335      You may use 'gnutls_x509_crt_get_subject_alt_othername_oid()' to
3336      get the corresponding OID and the "virtual" SAN types (e.g.,
3337      'GNUTLS_SAN_OTHERNAME_XMPP' ).
3338
3339      If an otherName OID is known, the data will be decoded.  Otherwise
3340      the returned data will be DER encoded, and you will have to decode
3341      it yourself.  Currently, only the RFC 3920 id-on-xmppAddr Issuer
3342      AltName is recognized.
3343
3344      *Returns:* the alternative issuer name type on success, one of the
3345      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
3346      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ian_size' is not large enough to
3347      hold the value.  In that case 'ian_size' will be updated with the
3348      required size.  If the certificate does not have an Alternative
3349      name with the specified sequence number then
3350      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3351
3352      *Since:* 2.10.0
3353
3354 gnutls_x509_crt_get_issuer_alt_name2
3355 ------------------------------------
3356
3357  -- Function: int gnutls_x509_crt_get_issuer_alt_name2
3358           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * IAN, size_t
3359           * IAN_SIZE, unsigned int * IAN_TYPE, unsigned int * CRITICAL)
3360      CERT: should contain a 'gnutls_x509_crt_t' type
3361
3362      SEQ: specifies the sequence number of the alt name (0 for the first
3363      one, 1 for the second etc.)
3364
3365      IAN: is the place where the alternative name will be copied to
3366
3367      IAN_SIZE: holds the size of ret.
3368
3369      IAN_TYPE: holds the type of the alternative name (one of
3370      gnutls_x509_subject_alt_name_t).
3371
3372      CRITICAL: will be non-zero if the extension is marked as critical
3373      (may be null)
3374
3375      This function will return the alternative names, contained in the
3376      given certificate.  It is the same as
3377      'gnutls_x509_crt_get_issuer_alt_name()' except for the fact that it
3378      will return the type of the alternative name in 'ian_type' even if
3379      the function fails for some reason (i.e.  the buffer provided is
3380      not enough).
3381
3382      *Returns:* the alternative issuer name type on success, one of the
3383      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
3384      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ian_size' is not large enough to
3385      hold the value.  In that case 'ian_size' will be updated with the
3386      required size.  If the certificate does not have an Alternative
3387      name with the specified sequence number then
3388      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3389
3390      *Since:* 2.10.0
3391
3392 gnutls_x509_crt_get_issuer_alt_othername_oid
3393 --------------------------------------------
3394
3395  -- Function: int gnutls_x509_crt_get_issuer_alt_othername_oid
3396           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t
3397           * RET_SIZE)
3398      CERT: should contain a 'gnutls_x509_crt_t' type
3399
3400      SEQ: specifies the sequence number of the alt name (0 for the first
3401      one, 1 for the second etc.)
3402
3403      RET: is the place where the otherName OID will be copied to
3404
3405      RET_SIZE: holds the size of ret.
3406
3407      This function will extract the type OID of an otherName Subject
3408      Alternative Name, contained in the given certificate, and return
3409      the type as an enumerated element.
3410
3411      If 'oid' is null then only the size will be filled.  The 'oid'
3412      returned will be null terminated, although 'oid_size' will not
3413      account for the trailing null.
3414
3415      This function is only useful if
3416      'gnutls_x509_crt_get_issuer_alt_name()' returned
3417      'GNUTLS_SAN_OTHERNAME' .
3418
3419      *Returns:* the alternative issuer name type on success, one of the
3420      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
3421      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
3422      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
3423      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
3424      'ret_size' is not large enough to hold the value.  In that case
3425      'ret_size' will be updated with the required size.  If the
3426      certificate does not have an Alternative name with the specified
3427      sequence number and with the otherName type then
3428      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3429
3430      *Since:* 2.10.0
3431
3432 gnutls_x509_crt_get_issuer_dn
3433 -----------------------------
3434
3435  -- Function: int gnutls_x509_crt_get_issuer_dn (gnutls_x509_crt_t CERT,
3436           char * BUF, size_t * BUF_SIZE)
3437      CERT: should contain a 'gnutls_x509_crt_t' type
3438
3439      BUF: a pointer to a structure to hold the name (may be null)
3440
3441      BUF_SIZE: initially holds the size of 'buf'
3442
3443      This function will copy the name of the Certificate issuer in the
3444      provided buffer.  The name will be in the form
3445      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
3446      will be ASCII or UTF-8 encoded, depending on the certificate data.
3447
3448      If 'buf' is null then only the size will be filled.
3449
3450      *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is
3451      not long enough, and in that case the 'buf_size' will be updated
3452      with the required size.  On success 0 is returned.
3453
3454 gnutls_x509_crt_get_issuer_dn2
3455 ------------------------------
3456
3457  -- Function: int gnutls_x509_crt_get_issuer_dn2 (gnutls_x509_crt_t
3458           CERT, gnutls_datum_t * DN)
3459      CERT: should contain a 'gnutls_x509_crt_t' type
3460
3461      DN: a pointer to a structure to hold the name
3462
3463      This function will allocate buffer and copy the name of issuer of
3464      the Certificate.  The name will be in the form
3465      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
3466      will be ASCII or UTF-8 encoded, depending on the certificate data.
3467
3468      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3469      otherwise a negative error value.
3470
3471      *Since:* 3.1.10
3472
3473 gnutls_x509_crt_get_issuer_dn_by_oid
3474 ------------------------------------
3475
3476  -- Function: int gnutls_x509_crt_get_issuer_dn_by_oid
3477           (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned
3478           int RAW_FLAG, void * BUF, size_t * BUF_SIZE)
3479      CERT: should contain a 'gnutls_x509_crt_t' type
3480
3481      OID: holds an Object Identified in null terminated string
3482
3483      INDX: In case multiple same OIDs exist in the RDN, this specifies
3484      which to send.  Use (0) to get the first one.
3485
3486      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
3487
3488      BUF: a pointer to a structure to hold the name (may be null)
3489
3490      BUF_SIZE: initially holds the size of 'buf'
3491
3492      This function will extract the part of the name of the Certificate
3493      issuer specified by the given OID. The output, if the raw flag is
3494      not used, will be encoded as described in RFC4514.  Thus a string
3495      that is ASCII or UTF-8 encoded, depending on the certificate data.
3496
3497      Some helper macros with popular OIDs can be found in gnutls/x509.h
3498      If raw flag is (0), this function will only return known OIDs as
3499      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
3500      hex format with a '#' prefix.  You can check about known OIDs using
3501      'gnutls_x509_dn_oid_known()' .
3502
3503      If 'buf' is null then only the size will be filled.  If the
3504      'raw_flag' is not specified the output is always null terminated,
3505      although the 'buf_size' will not include the null character.
3506
3507      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3508      not long enough, and in that case the 'buf_size' will be updated
3509      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
3510      there are no data in the current index.  On success 0 is returned.
3511
3512 gnutls_x509_crt_get_issuer_dn_oid
3513 ---------------------------------
3514
3515  -- Function: int gnutls_x509_crt_get_issuer_dn_oid (gnutls_x509_crt_t
3516           CERT, int INDX, void * OID, size_t * OID_SIZE)
3517      CERT: should contain a 'gnutls_x509_crt_t' type
3518
3519      INDX: This specifies which OID to return.  Use (0) to get the first
3520      one.
3521
3522      OID: a pointer to a buffer to hold the OID (may be null)
3523
3524      OID_SIZE: initially holds the size of 'oid'
3525
3526      This function will extract the OIDs of the name of the Certificate
3527      issuer specified by the given index.
3528
3529      If 'oid' is null then only the size will be filled.  The 'oid'
3530      returned will be null terminated, although 'oid_size' will not
3531      account for the trailing null.
3532
3533      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3534      not long enough, and in that case the 'buf_size' will be updated
3535      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
3536      there are no data in the current index.  On success 0 is returned.
3537
3538 gnutls_x509_crt_get_issuer_unique_id
3539 ------------------------------------
3540
3541  -- Function: int gnutls_x509_crt_get_issuer_unique_id
3542           (gnutls_x509_crt_t CRT, char * BUF, size_t * BUF_SIZE)
3543      CRT: Holds the certificate
3544
3545      BUF: user allocated memory buffer, will hold the unique id
3546
3547      BUF_SIZE: size of user allocated memory buffer (on input), will
3548      hold actual size of the unique ID on return.
3549
3550      This function will extract the issuerUniqueID value (if present)
3551      for the given certificate.
3552
3553      If the user allocated memory buffer is not large enough to hold the
3554      full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error
3555      will be returned, and buf_size will be set to the actual length.
3556
3557      This function had a bug prior to 3.4.8 that prevented the setting
3558      of 'NULL' 'buf' to discover the 'buf_size' .  To use this function
3559      safely with the older versions the 'buf' must be a valid buffer
3560      that can hold at least a single byte if 'buf_size' is zero.
3561
3562      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3563      error code.
3564
3565      *Since:* 2.12.0
3566
3567 gnutls_x509_crt_get_key_id
3568 --------------------------
3569
3570  -- Function: int gnutls_x509_crt_get_key_id (gnutls_x509_crt_t CRT,
3571           unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
3572           OUTPUT_DATA_SIZE)
3573      CRT: Holds the certificate
3574
3575      FLAGS: should be one of the flags from 'gnutls_keyid_flags_t'
3576
3577      OUTPUT_DATA: will contain the key ID
3578
3579      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
3580      replaced by the actual size of parameters)
3581
3582      This function will return a unique ID that depends on the public
3583      key parameters.  This ID can be used in checking whether a
3584      certificate corresponds to the given private key.
3585
3586      If the buffer provided is not long enough to hold the output, then
3587      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3588      be returned.  The output will normally be a SHA-1 hash output,
3589      which is 20 bytes.
3590
3591      *Returns:* In case of failure a negative error code will be
3592      returned, and 0 on success.
3593
3594 gnutls_x509_crt_get_key_purpose_oid
3595 -----------------------------------
3596
3597  -- Function: int gnutls_x509_crt_get_key_purpose_oid (gnutls_x509_crt_t
3598           CERT, int INDX, void * OID, size_t * OID_SIZE, unsigned int *
3599           CRITICAL)
3600      CERT: should contain a 'gnutls_x509_crt_t' type
3601
3602      INDX: This specifies which OID to return.  Use (0) to get the first
3603      one.
3604
3605      OID: a pointer to a buffer to hold the OID (may be null)
3606
3607      OID_SIZE: initially holds the size of 'oid'
3608
3609      CRITICAL: output flag to indicate criticality of extension
3610
3611      This function will extract the key purpose OIDs of the Certificate
3612      specified by the given index.  These are stored in the Extended Key
3613      Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
3614      human readable names.
3615
3616      If 'oid' is null then only the size will be filled.  The 'oid'
3617      returned will be null terminated, although 'oid_size' will not
3618      account for the trailing null.
3619
3620      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
3621      not long enough, and in that case the *oid_size will be updated
3622      with the required size.  On success 0 is returned.
3623
3624 gnutls_x509_crt_get_key_usage
3625 -----------------------------
3626
3627  -- Function: int gnutls_x509_crt_get_key_usage (gnutls_x509_crt_t CERT,
3628           unsigned int * KEY_USAGE, unsigned int * CRITICAL)
3629      CERT: should contain a 'gnutls_x509_crt_t' type
3630
3631      KEY_USAGE: where the key usage bits will be stored
3632
3633      CRITICAL: will be non-zero if the extension is marked as critical
3634
3635      This function will return certificate's key usage, by reading the
3636      keyUsage X.509 extension (2.5.29.15).  The key usage value will
3637      ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE' ,
3638      'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
3639      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
3640      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
3641      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
3642
3643      *Returns:* the certificate key usage, or a negative error code in
3644      case of parsing error.  If the certificate does not contain the
3645      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
3646      returned.
3647
3648 gnutls_x509_crt_get_name_constraints
3649 ------------------------------------
3650
3651  -- Function: int gnutls_x509_crt_get_name_constraints
3652           (gnutls_x509_crt_t CRT, gnutls_x509_name_constraints_t NC,
3653           unsigned int FLAGS, unsigned int * CRITICAL)
3654      CRT: should contain a 'gnutls_x509_crt_t' type
3655
3656      NC: The nameconstraints intermediate type
3657
3658      FLAGS: zero or 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND'
3659
3660      CRITICAL: the extension status
3661
3662      This function will return an intermediate type containing the name
3663      constraints of the provided CA certificate.  That structure can be
3664      used in combination with 'gnutls_x509_name_constraints_check()' to
3665      verify whether a server's name is in accordance with the
3666      constraints.
3667
3668      When the 'flags' is set to 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND' ,
3669      then if the 'nc' structure is empty this function will behave
3670      identically as if the flag was not set.  Otherwise if there are
3671      elements in the 'nc' structure then only the excluded constraints
3672      will be appended to the constraints.
3673
3674      Note that 'nc' must be initialized prior to calling this function.
3675
3676      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3677      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
3678      present, otherwise a negative error value.
3679
3680      *Since:* 3.3.0
3681
3682 gnutls_x509_crt_get_pk_algorithm
3683 --------------------------------
3684
3685  -- Function: int gnutls_x509_crt_get_pk_algorithm (gnutls_x509_crt_t
3686           CERT, unsigned int * BITS)
3687      CERT: should contain a 'gnutls_x509_crt_t' type
3688
3689      BITS: if bits is non null it will hold the size of the parameters'
3690      in bits
3691
3692      This function will return the public key algorithm of an X.509
3693      certificate.
3694
3695      If bits is non null, it should have enough size to hold the
3696      parameters size in bits.  For RSA the bits returned is the modulus.
3697      For DSA the bits returned are of the public exponent.
3698
3699      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
3700      success, or a negative error code on error.
3701
3702 gnutls_x509_crt_get_pk_dsa_raw
3703 ------------------------------
3704
3705  -- Function: int gnutls_x509_crt_get_pk_dsa_raw (gnutls_x509_crt_t CRT,
3706           gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G,
3707           gnutls_datum_t * Y)
3708      CRT: Holds the certificate
3709
3710      P: will hold the p
3711
3712      Q: will hold the q
3713
3714      G: will hold the g
3715
3716      Y: will hold the y
3717
3718      This function will export the DSA public key's parameters found in
3719      the given certificate.  The new parameters will be allocated using
3720      'gnutls_malloc()' and will be stored in the appropriate datum.
3721
3722      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3723      error code.
3724
3725 gnutls_x509_crt_get_pk_ecc_raw
3726 ------------------------------
3727
3728  -- Function: int gnutls_x509_crt_get_pk_ecc_raw (gnutls_x509_crt_t CRT,
3729           gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t
3730           * Y)
3731      CRT: Holds the certificate
3732
3733      CURVE: will hold the curve
3734
3735      X: will hold x
3736
3737      Y: will hold y
3738
3739      This function will export the ECC public key's parameters found in
3740      the given certificate.  The new parameters will be allocated using
3741      'gnutls_malloc()' and will be stored in the appropriate datum.
3742
3743      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3744      error code.
3745
3746      *Since:* 3.4.1
3747
3748 gnutls_x509_crt_get_pk_rsa_raw
3749 ------------------------------
3750
3751  -- Function: int gnutls_x509_crt_get_pk_rsa_raw (gnutls_x509_crt_t CRT,
3752           gnutls_datum_t * M, gnutls_datum_t * E)
3753      CRT: Holds the certificate
3754
3755      M: will hold the modulus
3756
3757      E: will hold the public exponent
3758
3759      This function will export the RSA public key's parameters found in
3760      the given structure.  The new parameters will be allocated using
3761      'gnutls_malloc()' and will be stored in the appropriate datum.
3762
3763      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3764      error code.
3765
3766 gnutls_x509_crt_get_policy
3767 --------------------------
3768
3769  -- Function: int gnutls_x509_crt_get_policy (gnutls_x509_crt_t CRT, int
3770           INDX, struct gnutls_x509_policy_st * POLICY, unsigned int *
3771           CRITICAL)
3772      CRT: should contain a 'gnutls_x509_crt_t' type
3773
3774      INDX: This specifies which policy to return.  Use (0) to get the
3775      first one.
3776
3777      POLICY: A pointer to a policy structure.
3778
3779      CRITICAL: will be non-zero if the extension is marked as critical
3780
3781      This function will extract the certificate policy (extension
3782      2.5.29.32) specified by the given index.
3783
3784      The policy returned by this function must be deinitialized by using
3785      'gnutls_x509_policy_release()' .
3786
3787      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3788      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
3789      present, otherwise a negative error value.
3790
3791      *Since:* 3.1.5
3792
3793 gnutls_x509_crt_get_private_key_usage_period
3794 --------------------------------------------
3795
3796  -- Function: int gnutls_x509_crt_get_private_key_usage_period
3797           (gnutls_x509_crt_t CERT, time_t * ACTIVATION, time_t *
3798           EXPIRATION, unsigned int * CRITICAL)
3799      CERT: should contain a 'gnutls_x509_crt_t' type
3800
3801      ACTIVATION: The activation time
3802
3803      EXPIRATION: The expiration time
3804
3805      CRITICAL: the extension status
3806
3807      This function will return the expiration and activation times of
3808      the private key of the certificate.  It relies on the PKIX
3809      extension 2.5.29.16 being present.
3810
3811      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3812      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
3813      present, otherwise a negative error value.
3814
3815 gnutls_x509_crt_get_proxy
3816 -------------------------
3817
3818  -- Function: int gnutls_x509_crt_get_proxy (gnutls_x509_crt_t CERT,
3819           unsigned int * CRITICAL, int * PATHLEN, char **
3820           POLICYLANGUAGE, char ** POLICY, size_t * SIZEOF_POLICY)
3821      CERT: should contain a 'gnutls_x509_crt_t' type
3822
3823      CRITICAL: will be non-zero if the extension is marked as critical
3824
3825      PATHLEN: pointer to output integer indicating path length (may be
3826      NULL), non-negative error codes indicate a present
3827      pCPathLenConstraint field and the actual value, -1 indicate that
3828      the field is absent.
3829
3830      POLICYLANGUAGE: output variable with OID of policy language
3831
3832      POLICY: output variable with policy data
3833
3834      SIZEOF_POLICY: output variable size of policy data
3835
3836      This function will get information from a proxy certificate.  It
3837      reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
3838
3839      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3840      otherwise a negative error code is returned.
3841
3842 gnutls_x509_crt_get_raw_dn
3843 --------------------------
3844
3845  -- Function: int gnutls_x509_crt_get_raw_dn (gnutls_x509_crt_t CERT,
3846           gnutls_datum_t * DN)
3847      CERT: should contain a 'gnutls_x509_crt_t' type
3848
3849      DN: will hold the starting point of the DN
3850
3851      This function will return a pointer to the DER encoded DN structure
3852      and the length.  This points to allocated data that must be free'd
3853      using 'gnutls_free()' .
3854
3855      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3856      otherwise a negative error value.  or a negative error code on
3857      error.
3858
3859 gnutls_x509_crt_get_raw_issuer_dn
3860 ---------------------------------
3861
3862  -- Function: int gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t
3863           CERT, gnutls_datum_t * DN)
3864      CERT: should contain a 'gnutls_x509_crt_t' type
3865
3866      DN: will hold the starting point of the DN
3867
3868      This function will return a pointer to the DER encoded DN structure
3869      and the length.  This points to allocated data that must be free'd
3870      using 'gnutls_free()' .
3871
3872      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3873      otherwise a negative error value.or a negative error code on error.
3874
3875 gnutls_x509_crt_get_serial
3876 --------------------------
3877
3878  -- Function: int gnutls_x509_crt_get_serial (gnutls_x509_crt_t CERT,
3879           void * RESULT, size_t * RESULT_SIZE)
3880      CERT: should contain a 'gnutls_x509_crt_t' type
3881
3882      RESULT: The place where the serial number will be copied
3883
3884      RESULT_SIZE: Holds the size of the result field.
3885
3886      This function will return the X.509 certificate's serial number.
3887      This is obtained by the X509 Certificate serialNumber field.
3888      Serial is not always a 32 or 64bit number.  Some CAs use large
3889      serial numbers, thus it may be wise to handle it as something
3890      uint8_t.
3891
3892      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3893      otherwise a negative error value.
3894
3895 gnutls_x509_crt_get_signature
3896 -----------------------------
3897
3898  -- Function: int gnutls_x509_crt_get_signature (gnutls_x509_crt_t CERT,
3899           char * SIG, size_t * SIG_SIZE)
3900      CERT: should contain a 'gnutls_x509_crt_t' type
3901
3902      SIG: a pointer where the signature part will be copied (may be
3903      null).
3904
3905      SIG_SIZE: initially holds the size of 'sig'
3906
3907      This function will extract the signature field of a certificate.
3908
3909      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3910      otherwise a negative error value.
3911
3912 gnutls_x509_crt_get_signature_algorithm
3913 ---------------------------------------
3914
3915  -- Function: int gnutls_x509_crt_get_signature_algorithm
3916           (gnutls_x509_crt_t CERT)
3917      CERT: should contain a 'gnutls_x509_crt_t' type
3918
3919      This function will return a value of the 'gnutls_sign_algorithm_t'
3920      enumeration that is the signature algorithm that has been used to
3921      sign this certificate.
3922
3923      *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
3924      code on error.
3925
3926 gnutls_x509_crt_get_subject
3927 ---------------------------
3928
3929  -- Function: int gnutls_x509_crt_get_subject (gnutls_x509_crt_t CERT,
3930           gnutls_x509_dn_t * DN)
3931      CERT: should contain a 'gnutls_x509_crt_t' type
3932
3933      DN: output variable with pointer to uint8_t DN.
3934
3935      Return the Certificate's Subject DN as a 'gnutls_x509_dn_t' data
3936      type, that can be decoded using 'gnutls_x509_dn_get_rdn_ava()' .
3937
3938      Note that 'dn' should be treated as constant.  Because it points
3939      into the 'cert' object, you should not use 'dn' after 'cert' is
3940      deallocated.
3941
3942      *Returns:* Returns 0 on success, or an error code.
3943
3944 gnutls_x509_crt_get_subject_alt_name
3945 ------------------------------------
3946
3947  -- Function: int gnutls_x509_crt_get_subject_alt_name
3948           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * SAN, size_t
3949           * SAN_SIZE, unsigned int * CRITICAL)
3950      CERT: should contain a 'gnutls_x509_crt_t' type
3951
3952      SEQ: specifies the sequence number of the alt name (0 for the first
3953      one, 1 for the second etc.)
3954
3955      SAN: is the place where the alternative name will be copied to
3956
3957      SAN_SIZE: holds the size of san.
3958
3959      CRITICAL: will be non-zero if the extension is marked as critical
3960      (may be null)
3961
3962      This function retrieves the Alternative Name (2.5.29.17), contained
3963      in the given certificate in the X509v3 Certificate Extensions.
3964
3965      When the SAN type is otherName, it will extract the data in the
3966      otherName's value field, and 'GNUTLS_SAN_OTHERNAME' is returned.
3967      You may use 'gnutls_x509_crt_get_subject_alt_othername_oid()' to
3968      get the corresponding OID and the "virtual" SAN types (e.g.,
3969      'GNUTLS_SAN_OTHERNAME_XMPP' ).
3970
3971      If an otherName OID is known, the data will be decoded.  Otherwise
3972      the returned data will be DER encoded, and you will have to decode
3973      it yourself.  Currently, only the RFC 3920 id-on-xmppAddr SAN is
3974      recognized.
3975
3976      *Returns:* the alternative subject name type on success, one of the
3977      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
3978      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'san_size' is not large enough to
3979      hold the value.  In that case 'san_size' will be updated with the
3980      required size.  If the certificate does not have an Alternative
3981      name with the specified sequence number then
3982      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3983
3984 gnutls_x509_crt_get_subject_alt_name2
3985 -------------------------------------
3986
3987  -- Function: int gnutls_x509_crt_get_subject_alt_name2
3988           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * SAN, size_t
3989           * SAN_SIZE, unsigned int * SAN_TYPE, unsigned int * CRITICAL)
3990      CERT: should contain a 'gnutls_x509_crt_t' type
3991
3992      SEQ: specifies the sequence number of the alt name (0 for the first
3993      one, 1 for the second etc.)
3994
3995      SAN: is the place where the alternative name will be copied to
3996
3997      SAN_SIZE: holds the size of ret.
3998
3999      SAN_TYPE: holds the type of the alternative name (one of
4000      gnutls_x509_subject_alt_name_t).
4001
4002      CRITICAL: will be non-zero if the extension is marked as critical
4003      (may be null)
4004
4005      This function will return the alternative names, contained in the
4006      given certificate.  It is the same as
4007      'gnutls_x509_crt_get_subject_alt_name()' except for the fact that
4008      it will return the type of the alternative name in 'san_type' even
4009      if the function fails for some reason (i.e.  the buffer provided is
4010      not enough).
4011
4012      *Returns:* the alternative subject name type on success, one of the
4013      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
4014      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'san_size' is not large enough to
4015      hold the value.  In that case 'san_size' will be updated with the
4016      required size.  If the certificate does not have an Alternative
4017      name with the specified sequence number then
4018      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
4019
4020 gnutls_x509_crt_get_subject_alt_othername_oid
4021 ---------------------------------------------
4022
4023  -- Function: int gnutls_x509_crt_get_subject_alt_othername_oid
4024           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * OID, size_t
4025           * OID_SIZE)
4026      CERT: should contain a 'gnutls_x509_crt_t' type
4027
4028      SEQ: specifies the sequence number of the alt name (0 for the first
4029      one, 1 for the second etc.)
4030
4031      OID: is the place where the otherName OID will be copied to
4032
4033      OID_SIZE: holds the size of ret.
4034
4035      This function will extract the type OID of an otherName Subject
4036      Alternative Name, contained in the given certificate, and return
4037      the type as an enumerated element.
4038
4039      This function is only useful if
4040      'gnutls_x509_crt_get_subject_alt_name()' returned
4041      'GNUTLS_SAN_OTHERNAME' .
4042
4043      If 'oid' is null then only the size will be filled.  The 'oid'
4044      returned will be null terminated, although 'oid_size' will not
4045      account for the trailing null.
4046
4047      *Returns:* the alternative subject name type on success, one of the
4048      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
4049      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
4050      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
4051      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
4052      'ian_size' is not large enough to hold the value.  In that case
4053      'ian_size' will be updated with the required size.  If the
4054      certificate does not have an Alternative name with the specified
4055      sequence number and with the otherName type then
4056      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
4057
4058 gnutls_x509_crt_get_subject_key_id
4059 ----------------------------------
4060
4061  -- Function: int gnutls_x509_crt_get_subject_key_id (gnutls_x509_crt_t
4062           CERT, void * RET, size_t * RET_SIZE, unsigned int * CRITICAL)
4063      CERT: should contain a 'gnutls_x509_crt_t' type
4064
4065      RET: The place where the identifier will be copied
4066
4067      RET_SIZE: Holds the size of the result field.
4068
4069      CRITICAL: will be non-zero if the extension is marked as critical
4070      (may be null)
4071
4072      This function will return the X.509v3 certificate's subject key
4073      identifier.  This is obtained by the X.509 Subject Key identifier
4074      extension field (2.5.29.14).
4075
4076      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4077      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
4078      present, otherwise a negative error value.
4079
4080 gnutls_x509_crt_get_subject_unique_id
4081 -------------------------------------
4082
4083  -- Function: int gnutls_x509_crt_get_subject_unique_id
4084           (gnutls_x509_crt_t CRT, char * BUF, size_t * BUF_SIZE)
4085      CRT: Holds the certificate
4086
4087      BUF: user allocated memory buffer, will hold the unique id
4088
4089      BUF_SIZE: size of user allocated memory buffer (on input), will
4090      hold actual size of the unique ID on return.
4091
4092      This function will extract the subjectUniqueID value (if present)
4093      for the given certificate.
4094
4095      If the user allocated memory buffer is not large enough to hold the
4096      full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error
4097      will be returned, and buf_size will be set to the actual length.
4098
4099      This function had a bug prior to 3.4.8 that prevented the setting
4100      of 'NULL' 'buf' to discover the 'buf_size' .  To use this function
4101      safely with the older versions the 'buf' must be a valid buffer
4102      that can hold at least a single byte if 'buf_size' is zero.
4103
4104      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4105      error code.
4106
4107 gnutls_x509_crt_get_version
4108 ---------------------------
4109
4110  -- Function: int gnutls_x509_crt_get_version (gnutls_x509_crt_t CERT)
4111      CERT: should contain a 'gnutls_x509_crt_t' type
4112
4113      This function will return the version of the specified Certificate.
4114
4115      *Returns:* version of certificate, or a negative error code on
4116      error.
4117
4118 gnutls_x509_crt_import
4119 ----------------------
4120
4121  -- Function: int gnutls_x509_crt_import (gnutls_x509_crt_t CERT, const
4122           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
4123      CERT: The data to store the parsed certificate.
4124
4125      DATA: The DER or PEM encoded certificate.
4126
4127      FORMAT: One of DER or PEM
4128
4129      This function will convert the given DER or PEM encoded Certificate
4130      to the native gnutls_x509_crt_t format.  The output will be stored
4131      in 'cert' .
4132
4133      If the Certificate is PEM encoded it should have a header of "X509
4134      CERTIFICATE", or "CERTIFICATE".
4135
4136      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4137      otherwise a negative error value.
4138
4139 gnutls_x509_crt_import_url
4140 --------------------------
4141
4142  -- Function: int gnutls_x509_crt_import_url (gnutls_x509_crt_t CRT,
4143           const char * URL, unsigned int FLAGS)
4144      CRT: A certificate of type 'gnutls_x509_crt_t'
4145
4146      URL: A PKCS 11 url
4147
4148      FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
4149
4150      This function will import a PKCS 11 certificate directly from a
4151      token without involving the 'gnutls_pkcs11_obj_t' type.  This
4152      function will fail if the certificate stored is not of X.509 type.
4153
4154      Despite its name this function will attempt to import any kind of
4155      URL to certificate.  In previous versions of gnutls this function
4156      was named gnutls_x509_crt_import_pkcs11_url, and the old name is an
4157      alias to this one.
4158
4159      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4160      otherwise a negative error value.
4161
4162      *Since:* 3.4.0
4163
4164 gnutls_x509_crt_init
4165 --------------------
4166
4167  -- Function: int gnutls_x509_crt_init (gnutls_x509_crt_t * CERT)
4168      CERT: A pointer to the type to be initialized
4169
4170      This function will initialize an X.509 certificate structure.
4171
4172      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4173      otherwise a negative error value.
4174
4175 gnutls_x509_crt_list_import
4176 ---------------------------
4177
4178  -- Function: int gnutls_x509_crt_list_import (gnutls_x509_crt_t *
4179           CERTS, unsigned int * CERT_MAX, const gnutls_datum_t * DATA,
4180           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
4181      CERTS: Indicates where the parsed list will be copied to.  Must not
4182      be initialized.
4183
4184      CERT_MAX: Initially must hold the maximum number of certs.  It will
4185      be updated with the number of certs available.
4186
4187      DATA: The PEM encoded certificate.
4188
4189      FORMAT: One of DER or PEM.
4190
4191      FLAGS: must be (0) or an OR'd sequence of
4192      gnutls_certificate_import_flags.
4193
4194      This function will convert the given PEM encoded certificate list
4195      to the native gnutls_x509_crt_t format.  The output will be stored
4196      in 'certs' .  They will be automatically initialized.
4197
4198      The flag 'GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED' will cause
4199      import to fail if the certificates in the provided buffer are more
4200      than the available structures.  The
4201      'GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED' flag will cause the
4202      function to fail if the provided list is not sorted from subject to
4203      issuer.
4204
4205      If the Certificate is PEM encoded it should have a header of "X509
4206      CERTIFICATE", or "CERTIFICATE".
4207
4208      *Returns:* the number of certificates read or a negative error
4209      value.
4210
4211 gnutls_x509_crt_list_import2
4212 ----------------------------
4213
4214  -- Function: int gnutls_x509_crt_list_import2 (gnutls_x509_crt_t **
4215           CERTS, unsigned int * SIZE, const gnutls_datum_t * DATA,
4216           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
4217      CERTS: Will hold the parsed certificate list.
4218
4219      SIZE: It will contain the size of the list.
4220
4221      DATA: The PEM encoded certificate.
4222
4223      FORMAT: One of DER or PEM.
4224
4225      FLAGS: must be (0) or an OR'd sequence of
4226      gnutls_certificate_import_flags.
4227
4228      This function will convert the given PEM encoded certificate list
4229      to the native gnutls_x509_crt_t format.  The output will be stored
4230      in 'certs' which will allocated and initialized.
4231
4232      If the Certificate is PEM encoded it should have a header of "X509
4233      CERTIFICATE", or "CERTIFICATE".
4234
4235      To deinitialize 'certs' , you need to deinitialize each crt
4236      structure independently, and use 'gnutls_free()' at
4237
4238      *Returns:* the number of certificates read or a negative error
4239      value.
4240
4241      *Since:* 3.0
4242
4243 gnutls_x509_crt_list_verify
4244 ---------------------------
4245
4246  -- Function: int gnutls_x509_crt_list_verify (const gnutls_x509_crt_t *
4247           CERT_LIST, int CERT_LIST_LENGTH, const gnutls_x509_crt_t *
4248           CA_LIST, int CA_LIST_LENGTH, const gnutls_x509_crl_t *
4249           CRL_LIST, int CRL_LIST_LENGTH, unsigned int FLAGS, unsigned
4250           int * VERIFY)
4251      CERT_LIST: is the certificate list to be verified
4252
4253      CERT_LIST_LENGTH: holds the number of certificate in cert_list
4254
4255      CA_LIST: is the CA list which will be used in verification
4256
4257      CA_LIST_LENGTH: holds the number of CA certificate in CA_list
4258
4259      CRL_LIST: holds a list of CRLs.
4260
4261      CRL_LIST_LENGTH: the length of CRL list.
4262
4263      FLAGS: Flags that may be used to change the verification algorithm.
4264      Use OR of the gnutls_certificate_verify_flags enumerations.
4265
4266      VERIFY: will hold the certificate verification output.
4267
4268      This function will try to verify the given certificate list and
4269      return its status.  The details of the verification are the same as
4270      in 'gnutls_x509_trust_list_verify_crt2()' .
4271
4272      You must check the peer's name in order to check if the verified
4273      certificate belongs to the actual peer.
4274
4275      The certificate verification output will be put in 'verify' and
4276      will be one or more of the gnutls_certificate_status_t enumerated
4277      elements bitwise or'd.  For a more detailed verification status use
4278      'gnutls_x509_crt_verify()' per list element.
4279
4280      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4281      otherwise a negative error value.
4282
4283 gnutls_x509_crt_print
4284 ---------------------
4285
4286  -- Function: int gnutls_x509_crt_print (gnutls_x509_crt_t CERT,
4287           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
4288           OUT)
4289      CERT: The data to be printed
4290
4291      FORMAT: Indicate the format to use
4292
4293      OUT: Newly allocated datum with null terminated string.
4294
4295      This function will pretty print a X.509 certificate, suitable for
4296      display to a human.
4297
4298      If the format is 'GNUTLS_CRT_PRINT_FULL' then all fields of the
4299      certificate will be output, on multiple lines.  The
4300      'GNUTLS_CRT_PRINT_ONELINE' format will generate one line with some
4301      selected fields, which is useful for logging purposes.
4302
4303      The output 'out' needs to be deallocated using 'gnutls_free()' .
4304
4305      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4306      otherwise a negative error value.
4307
4308 gnutls_x509_crt_set_activation_time
4309 -----------------------------------
4310
4311  -- Function: int gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t
4312           CERT, time_t ACT_TIME)
4313      CERT: a certificate of type 'gnutls_x509_crt_t'
4314
4315      ACT_TIME: The actual time
4316
4317      This function will set the time this Certificate was or will be
4318      activated.
4319
4320      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4321      otherwise a negative error value.
4322
4323 gnutls_x509_crt_set_authority_info_access
4324 -----------------------------------------
4325
4326  -- Function: int gnutls_x509_crt_set_authority_info_access
4327           (gnutls_x509_crt_t CRT, int WHAT, gnutls_datum_t * DATA)
4328      CRT: Holds the certificate
4329
4330      WHAT: what data to get, a 'gnutls_info_access_what_t' type.
4331
4332      DATA: output data to be freed with 'gnutls_free()' .
4333
4334      This function sets the Authority Information Access (AIA)
4335      extension, see RFC 5280 section 4.2.2.1 for more information.
4336
4337      The type of data stored in 'data' is specified via 'what' which
4338      should be 'gnutls_info_access_what_t' values.
4339
4340      If 'what' is 'GNUTLS_IA_OCSP_URI' , 'data' will hold the OCSP URI.
4341      If 'what' is 'GNUTLS_IA_CAISSUERS_URI' , 'data' will hold the
4342      caIssuers URI.
4343
4344      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4345      otherwise a negative error value.
4346
4347      *Since:* 3.0
4348
4349 gnutls_x509_crt_set_authority_key_id
4350 ------------------------------------
4351
4352  -- Function: int gnutls_x509_crt_set_authority_key_id
4353           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
4354      CERT: a certificate of type 'gnutls_x509_crt_t'
4355
4356      ID: The key ID
4357
4358      ID_SIZE: Holds the size of the key ID field.
4359
4360      This function will set the X.509 certificate's authority key ID
4361      extension.  Only the keyIdentifier field can be set with this
4362      function.
4363
4364      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4365      otherwise a negative error value.
4366
4367 gnutls_x509_crt_set_basic_constraints
4368 -------------------------------------
4369
4370  -- Function: int gnutls_x509_crt_set_basic_constraints
4371           (gnutls_x509_crt_t CRT, unsigned int CA, int
4372           PATHLENCONSTRAINT)
4373      CRT: a certificate of type 'gnutls_x509_crt_t'
4374
4375      CA: true(1) or false(0).  Depending on the Certificate authority
4376      status.
4377
4378      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
4379      of path, and negative error codes indicate that the
4380      pathLenConstraints field should not be present.
4381
4382      This function will set the basicConstraints certificate extension.
4383
4384      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4385      otherwise a negative error value.
4386
4387 gnutls_x509_crt_set_ca_status
4388 -----------------------------
4389
4390  -- Function: int gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t CRT,
4391           unsigned int CA)
4392      CRT: a certificate of type 'gnutls_x509_crt_t'
4393
4394      CA: true(1) or false(0).  Depending on the Certificate authority
4395      status.
4396
4397      This function will set the basicConstraints certificate extension.
4398      Use 'gnutls_x509_crt_set_basic_constraints()' if you want to
4399      control the pathLenConstraint field too.
4400
4401      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4402      otherwise a negative error value.
4403
4404 gnutls_x509_crt_set_crl_dist_points
4405 -----------------------------------
4406
4407  -- Function: int gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t
4408           CRT, gnutls_x509_subject_alt_name_t TYPE, const void *
4409           DATA_STRING, unsigned int REASON_FLAGS)
4410      CRT: a certificate of type 'gnutls_x509_crt_t'
4411
4412      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
4413
4414      DATA_STRING: The data to be set
4415
4416      REASON_FLAGS: revocation reasons
4417
4418      This function will set the CRL distribution points certificate
4419      extension.
4420
4421      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4422      otherwise a negative error value.
4423
4424 gnutls_x509_crt_set_crl_dist_points2
4425 ------------------------------------
4426
4427  -- Function: int gnutls_x509_crt_set_crl_dist_points2
4428           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
4429           const void * DATA, unsigned int DATA_SIZE, unsigned int
4430           REASON_FLAGS)
4431      CRT: a certificate of type 'gnutls_x509_crt_t'
4432
4433      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
4434
4435      DATA: The data to be set
4436
4437      DATA_SIZE: The data size
4438
4439      REASON_FLAGS: revocation reasons
4440
4441      This function will set the CRL distribution points certificate
4442      extension.
4443
4444      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4445      otherwise a negative error value.
4446
4447      *Since:* 2.6.0
4448
4449 gnutls_x509_crt_set_crq
4450 -----------------------
4451
4452  -- Function: int gnutls_x509_crt_set_crq (gnutls_x509_crt_t CRT,
4453           gnutls_x509_crq_t CRQ)
4454      CRT: a certificate of type 'gnutls_x509_crt_t'
4455
4456      CRQ: holds a certificate request
4457
4458      This function will set the name and public parameters as well as
4459      the extensions from the given certificate request to the
4460      certificate.  Only RSA keys are currently supported.
4461
4462      Note that this function will only set the 'crq' if it is self
4463      signed and the signature is correct.  See 'gnutls_x509_crq_sign2()'
4464      .
4465
4466      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4467      otherwise a negative error value.
4468
4469 gnutls_x509_crt_set_crq_extensions
4470 ----------------------------------
4471
4472  -- Function: int gnutls_x509_crt_set_crq_extensions (gnutls_x509_crt_t
4473           CRT, gnutls_x509_crq_t CRQ)
4474      CRT: a certificate of type 'gnutls_x509_crt_t'
4475
4476      CRQ: holds a certificate request
4477
4478      This function will set extensions from the given request to the
4479      certificate.
4480
4481      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4482      otherwise a negative error value.
4483
4484      *Since:* 2.8.0
4485
4486 gnutls_x509_crt_set_dn
4487 ----------------------
4488
4489  -- Function: int gnutls_x509_crt_set_dn (gnutls_x509_crt_t CRT, const
4490           char * DN, const char ** ERR)
4491      CRT: a certificate of type 'gnutls_x509_crt_t'
4492
4493      DN: a comma separated DN string (RFC4514)
4494
4495      ERR: indicates the error position (if any)
4496
4497      This function will set the DN on the provided certificate.  The
4498      input string should be plain ASCII or UTF-8 encoded.
4499
4500      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4501      otherwise a negative error value.
4502
4503 gnutls_x509_crt_set_dn_by_oid
4504 -----------------------------
4505
4506  -- Function: int gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t CRT,
4507           const char * OID, unsigned int RAW_FLAG, const void * NAME,
4508           unsigned int SIZEOF_NAME)
4509      CRT: a certificate of type 'gnutls_x509_crt_t'
4510
4511      OID: holds an Object Identifier in a null terminated string
4512
4513      RAW_FLAG: must be 0, or 1 if the data are DER encoded
4514
4515      NAME: a pointer to the name
4516
4517      SIZEOF_NAME: holds the size of 'name'
4518
4519      This function will set the part of the name of the Certificate
4520      subject, specified by the given OID. The input string should be
4521      ASCII or UTF-8 encoded.
4522
4523      Some helper macros with popular OIDs can be found in gnutls/x509.h
4524      With this function you can only set the known OIDs.  You can test
4525      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
4526      are not known (by gnutls) you should properly DER encode your data,
4527      and call this function with 'raw_flag' set.
4528
4529      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4530      otherwise a negative error value.
4531
4532 gnutls_x509_crt_set_expiration_time
4533 -----------------------------------
4534
4535  -- Function: int gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t
4536           CERT, time_t EXP_TIME)
4537      CERT: a certificate of type 'gnutls_x509_crt_t'
4538
4539      EXP_TIME: The actual time
4540
4541      This function will set the time this Certificate will expire.
4542      Setting an expiration time to (time_t)-1 or to
4543      'GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION' will set to the no
4544      well-defined expiration date value.
4545
4546      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4547      otherwise a negative error value.
4548
4549 gnutls_x509_crt_set_extension_by_oid
4550 ------------------------------------
4551
4552  -- Function: int gnutls_x509_crt_set_extension_by_oid
4553           (gnutls_x509_crt_t CRT, const char * OID, const void * BUF,
4554           size_t SIZEOF_BUF, unsigned int CRITICAL)
4555      CRT: a certificate of type 'gnutls_x509_crt_t'
4556
4557      OID: holds an Object Identified in null terminated string
4558
4559      BUF: a pointer to a DER encoded data
4560
4561      SIZEOF_BUF: holds the size of 'buf'
4562
4563      CRITICAL: should be non-zero if the extension is to be marked as
4564      critical
4565
4566      This function will set an the extension, by the specified OID, in
4567      the certificate.  The extension data should be binary data DER
4568      encoded.
4569
4570      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4571      otherwise a negative error value.
4572
4573 gnutls_x509_crt_set_issuer_alt_name
4574 -----------------------------------
4575
4576  -- Function: int gnutls_x509_crt_set_issuer_alt_name (gnutls_x509_crt_t
4577           CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA,
4578           unsigned int DATA_SIZE, unsigned int FLAGS)
4579      CRT: a certificate of type 'gnutls_x509_crt_t'
4580
4581      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
4582
4583      DATA: The data to be set
4584
4585      DATA_SIZE: The size of data to be set
4586
4587      FLAGS: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND
4588      to append.
4589
4590      This function will set the issuer alternative name certificate
4591      extension.  It can set the same types as
4592      'gnutls_x509_crt_set_subject_alt_name()' .
4593
4594      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4595      otherwise a negative error value.
4596
4597      *Since:* 3.3.0
4598
4599 gnutls_x509_crt_set_issuer_dn
4600 -----------------------------
4601
4602  -- Function: int gnutls_x509_crt_set_issuer_dn (gnutls_x509_crt_t CRT,
4603           const char * DN, const char ** ERR)
4604      CRT: a certificate of type 'gnutls_x509_crt_t'
4605
4606      DN: a comma separated DN string (RFC4514)
4607
4608      ERR: indicates the error position (if any)
4609
4610      This function will set the DN on the provided certificate.  The
4611      input string should be plain ASCII or UTF-8 encoded.
4612
4613      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4614      otherwise a negative error value.
4615
4616 gnutls_x509_crt_set_issuer_dn_by_oid
4617 ------------------------------------
4618
4619  -- Function: int gnutls_x509_crt_set_issuer_dn_by_oid
4620           (gnutls_x509_crt_t CRT, const char * OID, unsigned int
4621           RAW_FLAG, const void * NAME, unsigned int SIZEOF_NAME)
4622      CRT: a certificate of type 'gnutls_x509_crt_t'
4623
4624      OID: holds an Object Identifier in a null terminated string
4625
4626      RAW_FLAG: must be 0, or 1 if the data are DER encoded
4627
4628      NAME: a pointer to the name
4629
4630      SIZEOF_NAME: holds the size of 'name'
4631
4632      This function will set the part of the name of the Certificate
4633      issuer, specified by the given OID. The input string should be
4634      ASCII or UTF-8 encoded.
4635
4636      Some helper macros with popular OIDs can be found in gnutls/x509.h
4637      With this function you can only set the known OIDs.  You can test
4638      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
4639      are not known (by gnutls) you should properly DER encode your data,
4640      and call this function with 'raw_flag' set.
4641
4642      Normally you do not need to call this function, since the signing
4643      operation will copy the signer's name as the issuer of the
4644      certificate.
4645
4646      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4647      otherwise a negative error value.
4648
4649 gnutls_x509_crt_set_issuer_unique_id
4650 ------------------------------------
4651
4652  -- Function: int gnutls_x509_crt_set_issuer_unique_id
4653           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
4654      CERT: a certificate of type 'gnutls_x509_crt_t'
4655
4656      ID: The unique ID
4657
4658      ID_SIZE: Holds the size of the unique ID.
4659
4660      This function will set the X.509 certificate's issuer unique ID
4661      field.
4662
4663      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4664      otherwise a negative error value.
4665
4666      *Since:* 3.4.7
4667
4668 gnutls_x509_crt_set_key
4669 -----------------------
4670
4671  -- Function: int gnutls_x509_crt_set_key (gnutls_x509_crt_t CRT,
4672           gnutls_x509_privkey_t KEY)
4673      CRT: a certificate of type 'gnutls_x509_crt_t'
4674
4675      KEY: holds a private key
4676
4677      This function will set the public parameters from the given private
4678      key to the certificate.
4679
4680      To export the public key (i.e., the SubjectPublicKeyInfo part),
4681      check 'gnutls_pubkey_import_x509()' .
4682
4683      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4684      otherwise a negative error value.
4685
4686 gnutls_x509_crt_set_key_purpose_oid
4687 -----------------------------------
4688
4689  -- Function: int gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t
4690           CERT, const void * OID, unsigned int CRITICAL)
4691      CERT: a certificate of type 'gnutls_x509_crt_t'
4692
4693      OID: a pointer to a null terminated string that holds the OID
4694
4695      CRITICAL: Whether this extension will be critical or not
4696
4697      This function will set the key purpose OIDs of the Certificate.
4698      These are stored in the Extended Key Usage extension (2.5.29.37)
4699      See the GNUTLS_KP_* definitions for human readable names.
4700
4701      Subsequent calls to this function will append OIDs to the OID list.
4702
4703      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4704      otherwise a negative error code is returned.
4705
4706 gnutls_x509_crt_set_key_usage
4707 -----------------------------
4708
4709  -- Function: int gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t CRT,
4710           unsigned int USAGE)
4711      CRT: a certificate of type 'gnutls_x509_crt_t'
4712
4713      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
4714
4715      This function will set the keyUsage certificate extension.
4716
4717      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4718      otherwise a negative error value.
4719
4720 gnutls_x509_crt_set_name_constraints
4721 ------------------------------------
4722
4723  -- Function: int gnutls_x509_crt_set_name_constraints
4724           (gnutls_x509_crt_t CRT, gnutls_x509_name_constraints_t NC,
4725           unsigned int CRITICAL)
4726      CRT: The certificate
4727
4728      NC: The nameconstraints structure
4729
4730      CRITICAL: whether this extension will be critical
4731
4732      This function will set the provided name constraints to the
4733      certificate extension list.  This extension is always marked as
4734      critical.
4735
4736      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4737      otherwise a negative error value.
4738
4739      *Since:* 3.3.0
4740
4741 gnutls_x509_crt_set_pin_function
4742 --------------------------------
4743
4744  -- Function: void gnutls_x509_crt_set_pin_function (gnutls_x509_crt_t
4745           CRT, gnutls_pin_callback_t FN, void * USERDATA)
4746      CRT: The certificate structure
4747
4748      FN: the callback
4749
4750      USERDATA: data associated with the callback
4751
4752      This function will set a callback function to be used when it is
4753      required to access a protected object.  This function overrides the
4754      global function set using 'gnutls_pkcs11_set_pin_function()' .
4755
4756      Note that this callback is currently used only during the import of
4757      a PKCS '11' certificate with 'gnutls_x509_crt_import_url()' .
4758
4759      *Since:* 3.1.0
4760
4761 gnutls_x509_crt_set_policy
4762 --------------------------
4763
4764  -- Function: int gnutls_x509_crt_set_policy (gnutls_x509_crt_t CRT,
4765           const struct gnutls_x509_policy_st * POLICY, unsigned int
4766           CRITICAL)
4767      CRT: should contain a 'gnutls_x509_crt_t' type
4768
4769      POLICY: A pointer to a policy
4770
4771      CRITICAL: use non-zero if the extension is marked as critical
4772
4773      This function will set the certificate policy extension
4774      (2.5.29.32).  Multiple calls to this function append a new policy.
4775
4776      Note the maximum text size for the qualifier
4777      'GNUTLS_X509_QUALIFIER_NOTICE' is 200 characters.  This function
4778      will fail with 'GNUTLS_E_INVALID_REQUEST' if this is exceeded.
4779
4780      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4781      otherwise a negative error value.
4782
4783      *Since:* 3.1.5
4784
4785 gnutls_x509_crt_set_private_key_usage_period
4786 --------------------------------------------
4787
4788  -- Function: int gnutls_x509_crt_set_private_key_usage_period
4789           (gnutls_x509_crt_t CRT, time_t ACTIVATION, time_t EXPIRATION)
4790      CRT: a certificate of type 'gnutls_x509_crt_t'
4791
4792      ACTIVATION: The activation time
4793
4794      EXPIRATION: The expiration time
4795
4796      This function will set the private key usage period extension
4797      (2.5.29.16).
4798
4799      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4800      otherwise a negative error value.
4801
4802 gnutls_x509_crt_set_proxy
4803 -------------------------
4804
4805  -- Function: int gnutls_x509_crt_set_proxy (gnutls_x509_crt_t CRT, int
4806           PATHLENCONSTRAINT, const char * POLICYLANGUAGE, const char *
4807           POLICY, size_t SIZEOF_POLICY)
4808      CRT: a certificate of type 'gnutls_x509_crt_t'
4809
4810      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
4811      of path, and negative error codes indicate that the
4812      pathLenConstraints field should not be present.
4813
4814      POLICYLANGUAGE: OID describing the language of 'policy' .
4815
4816      POLICY: uint8_t byte array with policy language, can be 'NULL'
4817
4818      SIZEOF_POLICY: size of 'policy' .
4819
4820      This function will set the proxyCertInfo extension.
4821
4822      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4823      otherwise a negative error value.
4824
4825 gnutls_x509_crt_set_proxy_dn
4826 ----------------------------
4827
4828  -- Function: int gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t CRT,
4829           gnutls_x509_crt_t EECRT, unsigned int RAW_FLAG, const void *
4830           NAME, unsigned int SIZEOF_NAME)
4831      CRT: a gnutls_x509_crt_t type with the new proxy cert
4832
4833      EECRT: the end entity certificate that will be issuing the proxy
4834
4835      RAW_FLAG: must be 0, or 1 if the CN is DER encoded
4836
4837      NAME: a pointer to the CN name, may be NULL (but MUST then be added
4838      later)
4839
4840      SIZEOF_NAME: holds the size of 'name'
4841
4842      This function will set the subject in 'crt' to the end entity's
4843      'eecrt' subject name, and add a single Common Name component 'name'
4844      of size 'sizeof_name' .  This corresponds to the required proxy
4845      certificate naming style.  Note that if 'name' is 'NULL' , you MUST
4846      set it later by using 'gnutls_x509_crt_set_dn_by_oid()' or similar.
4847
4848      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4849      otherwise a negative error value.
4850
4851 gnutls_x509_crt_set_serial
4852 --------------------------
4853
4854  -- Function: int gnutls_x509_crt_set_serial (gnutls_x509_crt_t CERT,
4855           const void * SERIAL, size_t SERIAL_SIZE)
4856      CERT: a certificate of type 'gnutls_x509_crt_t'
4857
4858      SERIAL: The serial number
4859
4860      SERIAL_SIZE: Holds the size of the serial field.
4861
4862      This function will set the X.509 certificate's serial number.
4863      While the serial number is an integer, it is often handled as an
4864      opaque field by several CAs.  For this reason this function accepts
4865      any kind of data as a serial number.  To be consistent with the
4866      X.509/PKIX specifications the provided 'serial' should be a
4867      big-endian positive number (i.e.  it's leftmost bit should be
4868      zero).
4869
4870      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4871      otherwise a negative error value.
4872
4873 gnutls_x509_crt_set_subject_alt_name
4874 ------------------------------------
4875
4876  -- Function: int gnutls_x509_crt_set_subject_alt_name
4877           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
4878           const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS)
4879      CRT: a certificate of type 'gnutls_x509_crt_t'
4880
4881      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
4882
4883      DATA: The data to be set
4884
4885      DATA_SIZE: The size of data to be set
4886
4887      FLAGS: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND
4888      to append.
4889
4890      This function will set the subject alternative name certificate
4891      extension.  It can set the following types:
4892
4893      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4894      otherwise a negative error value.
4895
4896      *Since:* 2.6.0
4897
4898 gnutls_x509_crt_set_subject_alternative_name
4899 --------------------------------------------
4900
4901  -- Function: int gnutls_x509_crt_set_subject_alternative_name
4902           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
4903           const char * DATA_STRING)
4904      CRT: a certificate of type 'gnutls_x509_crt_t'
4905
4906      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
4907
4908      DATA_STRING: The data to be set, a (0) terminated string
4909
4910      This function will set the subject alternative name certificate
4911      extension.  This function assumes that data can be expressed as a
4912      null terminated string.
4913
4914      The name of the function is unfortunate since it is incosistent
4915      with 'gnutls_x509_crt_get_subject_alt_name()' .
4916
4917      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4918      otherwise a negative error value.
4919
4920 gnutls_x509_crt_set_subject_key_id
4921 ----------------------------------
4922
4923  -- Function: int gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t
4924           CERT, const void * ID, size_t ID_SIZE)
4925      CERT: a certificate of type 'gnutls_x509_crt_t'
4926
4927      ID: The key ID
4928
4929      ID_SIZE: Holds the size of the subject key ID field.
4930
4931      This function will set the X.509 certificate's subject key ID
4932      extension.
4933
4934      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4935      otherwise a negative error value.
4936
4937 gnutls_x509_crt_set_subject_unique_id
4938 -------------------------------------
4939
4940  -- Function: int gnutls_x509_crt_set_subject_unique_id
4941           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
4942      CERT: a certificate of type 'gnutls_x509_crt_t'
4943
4944      ID: The unique ID
4945
4946      ID_SIZE: Holds the size of the unique ID.
4947
4948      This function will set the X.509 certificate's subject unique ID
4949      field.
4950
4951      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4952      otherwise a negative error value.
4953
4954      *Since:* 3.4.7
4955
4956 gnutls_x509_crt_set_version
4957 ---------------------------
4958
4959  -- Function: int gnutls_x509_crt_set_version (gnutls_x509_crt_t CRT,
4960           unsigned int VERSION)
4961      CRT: a certificate of type 'gnutls_x509_crt_t'
4962
4963      VERSION: holds the version number.  For X.509v1 certificates must
4964      be 1.
4965
4966      This function will set the version of the certificate.  This must
4967      be one for X.509 version 1, and so on.  Plain certificates without
4968      extensions must have version set to one.
4969
4970      To create well-formed certificates, you must specify version 3 if
4971      you use any certificate extensions.  Extensions are created by
4972      functions such as 'gnutls_x509_crt_set_subject_alt_name()' or
4973      'gnutls_x509_crt_set_key_usage()' .
4974
4975      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4976      otherwise a negative error value.
4977
4978 gnutls_x509_crt_sign
4979 --------------------
4980
4981  -- Function: int gnutls_x509_crt_sign (gnutls_x509_crt_t CRT,
4982           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY)
4983      CRT: a certificate of type 'gnutls_x509_crt_t'
4984
4985      ISSUER: is the certificate of the certificate issuer
4986
4987      ISSUER_KEY: holds the issuer's private key
4988
4989      This function is the same a 'gnutls_x509_crt_sign2()' with no
4990      flags, and SHA1 as the hash algorithm.
4991
4992      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4993      otherwise a negative error value.
4994
4995 gnutls_x509_crt_sign2
4996 ---------------------
4997
4998  -- Function: int gnutls_x509_crt_sign2 (gnutls_x509_crt_t CRT,
4999           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY,
5000           gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
5001      CRT: a certificate of type 'gnutls_x509_crt_t'
5002
5003      ISSUER: is the certificate of the certificate issuer
5004
5005      ISSUER_KEY: holds the issuer's private key
5006
5007      DIG: The message digest to use, 'GNUTLS_DIG_SHA1' is a safe choice
5008
5009      FLAGS: must be 0
5010
5011      This function will sign the certificate with the issuer's private
5012      key, and will copy the issuer's information into the certificate.
5013
5014      This must be the last step in a certificate generation since all
5015      the previously set parameters are now signed.
5016
5017      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5018      otherwise a negative error value.
5019
5020 gnutls_x509_crt_verify
5021 ----------------------
5022
5023  -- Function: int gnutls_x509_crt_verify (gnutls_x509_crt_t CERT, const
5024           gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, unsigned int
5025           FLAGS, unsigned int * VERIFY)
5026      CERT: is the certificate to be verified
5027
5028      CA_LIST: is one certificate that is considered to be trusted one
5029
5030      CA_LIST_LENGTH: holds the number of CA certificate in CA_list
5031
5032      FLAGS: Flags that may be used to change the verification algorithm.
5033      Use OR of the gnutls_certificate_verify_flags enumerations.
5034
5035      VERIFY: will hold the certificate verification output.
5036
5037      This function will try to verify the given certificate and return
5038      its status.  Note that a verification error does not imply a
5039      negative return status.  In that case the 'verify' status is set.
5040
5041      The details of the verification are the same as in
5042      'gnutls_x509_trust_list_verify_crt2()' .
5043
5044      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5045      otherwise a negative error value.
5046
5047 gnutls_x509_crt_verify_data2
5048 ----------------------------
5049
5050  -- Function: int gnutls_x509_crt_verify_data2 (gnutls_x509_crt_t CRT,
5051           gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const
5052           gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE)
5053      CRT: Holds the certificate to verify with
5054
5055      ALGO: The signature algorithm used
5056
5057      FLAGS: Zero or an OR list of 'gnutls_certificate_verify_flags'
5058
5059      DATA: holds the signed data
5060
5061      SIGNATURE: contains the signature
5062
5063      This function will verify the given signed data, using the
5064      parameters from the certificate.
5065
5066      *Returns:* In case of a verification failure
5067      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5068      code on success.
5069
5070      *Since:* 3.4.0
5071
5072 gnutls_x509_dn_deinit
5073 ---------------------
5074
5075  -- Function: void gnutls_x509_dn_deinit (gnutls_x509_dn_t DN)
5076      DN: a DN uint8_t object pointer.
5077
5078      This function deallocates the DN object as returned by
5079      'gnutls_x509_dn_import()' .
5080
5081      *Since:* 2.4.0
5082
5083 gnutls_x509_dn_export
5084 ---------------------
5085
5086  -- Function: int gnutls_x509_dn_export (gnutls_x509_dn_t DN,
5087           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
5088           OUTPUT_DATA_SIZE)
5089      DN: Holds the uint8_t DN object
5090
5091      FORMAT: the format of output params.  One of PEM or DER.
5092
5093      OUTPUT_DATA: will contain a DN PEM or DER encoded
5094
5095      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
5096      replaced by the actual size of parameters)
5097
5098      This function will export the DN to DER or PEM format.
5099
5100      If the buffer provided is not long enough to hold the output, then
5101      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
5102      will be returned.
5103
5104      If the structure is PEM encoded, it will have a header of "BEGIN
5105      NAME".
5106
5107      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5108      otherwise a negative error value.
5109
5110 gnutls_x509_dn_export2
5111 ----------------------
5112
5113  -- Function: int gnutls_x509_dn_export2 (gnutls_x509_dn_t DN,
5114           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
5115      DN: Holds the uint8_t DN object
5116
5117      FORMAT: the format of output params.  One of PEM or DER.
5118
5119      OUT: will contain a DN PEM or DER encoded
5120
5121      This function will export the DN to DER or PEM format.
5122
5123      The output buffer is allocated using 'gnutls_malloc()' .
5124
5125      If the structure is PEM encoded, it will have a header of "BEGIN
5126      NAME".
5127
5128      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5129      otherwise a negative error value.
5130
5131      *Since:* 3.1.3
5132
5133 gnutls_x509_dn_get_rdn_ava
5134 --------------------------
5135
5136  -- Function: int gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t DN, int
5137           IRDN, int IAVA, gnutls_x509_ava_st * AVA)
5138      DN: a pointer to DN
5139
5140      IRDN: index of RDN
5141
5142      IAVA: index of AVA.
5143
5144      AVA: Pointer to structure which will hold output information.
5145
5146      Get pointers to data within the DN. The format of the 'ava'
5147      structure is shown below.
5148
5149      struct gnutls_x509_ava_st { gnutls_datum_t oid; gnutls_datum_t
5150      value; unsigned long value_tag; };
5151
5152      The X.509 distinguished name is a sequence of sequences of strings
5153      and this is what the 'irdn' and 'iava' indexes model.
5154
5155      Note that 'ava' will contain pointers into the 'dn' structure which
5156      in turns points to the original certificate.  Thus you should not
5157      modify any data or deallocate any of those.
5158
5159      This is a low-level function that requires the caller to do the
5160      value conversions when necessary (e.g.  from UCS-2).
5161
5162      *Returns:* Returns 0 on success, or an error code.
5163
5164 gnutls_x509_dn_get_str
5165 ----------------------
5166
5167  -- Function: int gnutls_x509_dn_get_str (gnutls_x509_dn_t DN,
5168           gnutls_datum_t * STR)
5169      DN: a pointer to DN
5170
5171      STR: a datum that will hold the name
5172
5173      This function will allocate buffer and copy the name in the
5174      provided DN. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz"
5175      as described in RFC4514.  The output string will be ASCII or UTF-8
5176      encoded, depending on the certificate data.
5177
5178      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5179      otherwise a negative error value.
5180
5181      *Since:* 3.4.2
5182
5183 gnutls_x509_dn_import
5184 ---------------------
5185
5186  -- Function: int gnutls_x509_dn_import (gnutls_x509_dn_t DN, const
5187           gnutls_datum_t * DATA)
5188      DN: the structure that will hold the imported DN
5189
5190      DATA: should contain a DER encoded RDN sequence
5191
5192      This function parses an RDN sequence and stores the result to a
5193      'gnutls_x509_dn_t' type.  The data must have been initialized with
5194      'gnutls_x509_dn_init()' .  You may use
5195      'gnutls_x509_dn_get_rdn_ava()' to decode the DN.
5196
5197      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5198      otherwise a negative error value.
5199
5200      *Since:* 2.4.0
5201
5202 gnutls_x509_dn_init
5203 -------------------
5204
5205  -- Function: int gnutls_x509_dn_init (gnutls_x509_dn_t * DN)
5206      DN: the object to be initialized
5207
5208      This function initializes a 'gnutls_x509_dn_t' type.
5209
5210      The object returned must be deallocated using
5211      'gnutls_x509_dn_deinit()' .
5212
5213      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5214      otherwise a negative error value.
5215
5216      *Since:* 2.4.0
5217
5218 gnutls_x509_dn_oid_known
5219 ------------------------
5220
5221  -- Function: int gnutls_x509_dn_oid_known (const char * OID)
5222      OID: holds an Object Identifier in a null terminated string
5223
5224      This function will inform about known DN OIDs.  This is useful
5225      since functions like 'gnutls_x509_crt_set_dn_by_oid()' use the
5226      information on known OIDs to properly encode their input.  Object
5227      Identifiers that are not known are not encoded by these functions,
5228      and their input is stored directly into the ASN.1 structure.  In
5229      that case of unknown OIDs, you have the responsibility of DER
5230      encoding your data.
5231
5232      *Returns:* 1 on known OIDs and 0 otherwise.
5233
5234 gnutls_x509_dn_oid_name
5235 -----------------------
5236
5237  -- Function: const char * gnutls_x509_dn_oid_name (const char * OID,
5238           unsigned int FLAGS)
5239      OID: holds an Object Identifier in a null terminated string
5240
5241      FLAGS: 0 or GNUTLS_X509_DN_OID_*
5242
5243      This function will return the name of a known DN OID. If
5244      'GNUTLS_X509_DN_OID_RETURN_OID' is specified this function will
5245      return the given OID if no descriptive name has been found.
5246
5247      *Returns:* A null terminated string or NULL otherwise.
5248
5249      *Since:* 3.0
5250
5251 gnutls_x509_ext_deinit
5252 ----------------------
5253
5254  -- Function: void gnutls_x509_ext_deinit (gnutls_x509_ext_st * EXT)
5255      EXT: The extensions structure
5256
5257      This function will deinitialize an extensions structure.
5258
5259      *Since:* 3.3.8
5260
5261 gnutls_x509_ext_export_aia
5262 --------------------------
5263
5264  -- Function: int gnutls_x509_ext_export_aia (gnutls_x509_aia_t AIA,
5265           gnutls_datum_t * EXT)
5266      AIA: The authority info access
5267
5268      EXT: The DER-encoded extension data; must be freed using
5269      'gnutls_free()' .
5270
5271      This function will DER encode the Authority Information Access
5272      (AIA) extension; see RFC 5280 section 4.2.2.1 for more information
5273      on the extension.
5274
5275      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5276      otherwise a negative error value.
5277
5278      *Since:* 3.3.0
5279
5280 gnutls_x509_ext_export_authority_key_id
5281 ---------------------------------------
5282
5283  -- Function: int gnutls_x509_ext_export_authority_key_id
5284           (gnutls_x509_aki_t AKI, gnutls_datum_t * EXT)
5285      AKI: An initialized authority key identifier
5286
5287      EXT: The DER-encoded extension data; must be freed using
5288      'gnutls_free()' .
5289
5290      This function will convert the provided key identifier to a
5291      DER-encoded PKIX AuthorityKeyIdentifier extension.  The output data
5292      in 'ext' will be allocated using 'gnutls_malloc()' .
5293
5294      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5295      otherwise a negative error value.
5296
5297      *Since:* 3.3.0
5298
5299 gnutls_x509_ext_export_basic_constraints
5300 ----------------------------------------
5301
5302  -- Function: int gnutls_x509_ext_export_basic_constraints (unsigned int
5303           CA, int PATHLEN, gnutls_datum_t * EXT)
5304      CA: non-zero for a CA
5305
5306      PATHLEN: The path length constraint (set to -1 for no constraint)
5307
5308      EXT: The DER-encoded extension data; must be freed using
5309      'gnutls_free()' .
5310
5311      This function will convert the parameters provided to a basic
5312      constraints DER encoded extension (2.5.29.19).  The 'ext' data will
5313      be allocated using 'gnutls_malloc()' .
5314
5315      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5316      otherwise a negative error value.
5317
5318      *Since:* 3.3.0
5319
5320 gnutls_x509_ext_export_crl_dist_points
5321 --------------------------------------
5322
5323  -- Function: int gnutls_x509_ext_export_crl_dist_points
5324           (gnutls_x509_crl_dist_points_t CDP, gnutls_datum_t * EXT)
5325      CDP: A pointer to an initialized CRL distribution points.
5326
5327      EXT: The DER-encoded extension data; must be freed using
5328      'gnutls_free()' .
5329
5330      This function will convert the provided policies, to a certificate
5331      policy DER encoded extension (2.5.29.31).
5332
5333      The 'ext' data will be allocated using 'gnutls_malloc()' .
5334
5335      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5336      otherwise a negative error value.
5337
5338      *Since:* 3.3.0
5339
5340 gnutls_x509_ext_export_key_purposes
5341 -----------------------------------
5342
5343  -- Function: int gnutls_x509_ext_export_key_purposes
5344           (gnutls_x509_key_purposes_t P, gnutls_datum_t * EXT)
5345      P: The key purposes
5346
5347      EXT: The DER-encoded extension data; must be freed using
5348      'gnutls_free()' .
5349
5350      This function will convert the key purposes type to a DER-encoded
5351      PKIX ExtKeyUsageSyntax (2.5.29.37) extension.  The output data in
5352      'ext' will be allocated usin 'gnutls_malloc()' .
5353
5354      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5355      otherwise a negative error value.
5356
5357      *Since:* 3.3.0
5358
5359 gnutls_x509_ext_export_key_usage
5360 --------------------------------
5361
5362  -- Function: int gnutls_x509_ext_export_key_usage (unsigned int USAGE,
5363           gnutls_datum_t * EXT)
5364      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
5365
5366      EXT: The DER-encoded extension data; must be freed using
5367      'gnutls_free()' .
5368
5369      This function will convert the keyUsage bit string to a DER encoded
5370      PKIX extension.  The 'ext' data will be allocated using
5371      'gnutls_malloc()' .
5372
5373      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5374      otherwise a negative error value.
5375
5376      *Since:* 3.3.0
5377
5378 gnutls_x509_ext_export_name_constraints
5379 ---------------------------------------
5380
5381  -- Function: int gnutls_x509_ext_export_name_constraints
5382           (gnutls_x509_name_constraints_t NC, gnutls_datum_t * EXT)
5383      NC: The nameconstraints
5384
5385      EXT: The DER-encoded extension data; must be freed using
5386      'gnutls_free()' .
5387
5388      This function will convert the provided name constraints type to a
5389      DER-encoded PKIX NameConstraints (2.5.29.30) extension.  The output
5390      data in 'ext' will be allocated usin 'gnutls_malloc()' .
5391
5392      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5393      otherwise a negative error value.
5394
5395      *Since:* 3.3.0
5396
5397 gnutls_x509_ext_export_policies
5398 -------------------------------
5399
5400  -- Function: int gnutls_x509_ext_export_policies
5401           (gnutls_x509_policies_t POLICIES, gnutls_datum_t * EXT)
5402      POLICIES: A pointer to an initialized policies.
5403
5404      EXT: The DER-encoded extension data; must be freed using
5405      'gnutls_free()' .
5406
5407      This function will convert the provided policies, to a certificate
5408      policy DER encoded extension (2.5.29.32).
5409
5410      The 'ext' data will be allocated using 'gnutls_malloc()' .
5411
5412      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5413      otherwise a negative error value.
5414
5415      *Since:* 3.3.0
5416
5417 gnutls_x509_ext_export_private_key_usage_period
5418 -----------------------------------------------
5419
5420  -- Function: int gnutls_x509_ext_export_private_key_usage_period
5421           (time_t ACTIVATION, time_t EXPIRATION, gnutls_datum_t * EXT)
5422      ACTIVATION: The activation time
5423
5424      EXPIRATION: The expiration time
5425
5426      EXT: The DER-encoded extension data; must be freed using
5427      'gnutls_free()' .
5428
5429      This function will convert the periods provided to a private key
5430      usage DER encoded extension (2.5.29.16).  The 'ext' data will be
5431      allocated using 'gnutls_malloc()' .
5432
5433      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5434      otherwise a negative error value.
5435
5436      *Since:* 3.3.0
5437
5438 gnutls_x509_ext_export_proxy
5439 ----------------------------
5440
5441  -- Function: int gnutls_x509_ext_export_proxy (int PATHLENCONSTRAINT,
5442           const char * POLICYLANGUAGE, const char * POLICY, size_t
5443           SIZEOF_POLICY, gnutls_datum_t * EXT)
5444      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
5445      of path, and negative error codes indicate that the
5446      pathLenConstraints field should not be present.
5447
5448      POLICYLANGUAGE: OID describing the language of 'policy' .
5449
5450      POLICY: uint8_t byte array with policy language, can be 'NULL'
5451
5452      SIZEOF_POLICY: size of 'policy' .
5453
5454      EXT: The DER-encoded extension data; must be freed using
5455      'gnutls_free()' .
5456
5457      This function will convert the parameters provided to a
5458      proxyCertInfo extension.
5459
5460      The 'ext' data will be allocated using 'gnutls_malloc()' .
5461
5462      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5463      otherwise a negative error value.
5464
5465      *Since:* 3.3.0
5466
5467 gnutls_x509_ext_export_subject_alt_names
5468 ----------------------------------------
5469
5470  -- Function: int gnutls_x509_ext_export_subject_alt_names
5471           (gnutls_subject_alt_names_t SANS, gnutls_datum_t * EXT)
5472      SANS: The alternative names
5473
5474      EXT: The DER-encoded extension data; must be freed using
5475      'gnutls_free()' .
5476
5477      This function will convert the provided alternative names structure
5478      to a DER-encoded SubjectAltName PKIX extension.  The output data in
5479      'ext' will be allocated using 'gnutls_malloc()' .
5480
5481      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5482      otherwise a negative error value.
5483
5484      *Since:* 3.3.0
5485
5486 gnutls_x509_ext_export_subject_key_id
5487 -------------------------------------
5488
5489  -- Function: int gnutls_x509_ext_export_subject_key_id (const
5490           gnutls_datum_t * ID, gnutls_datum_t * EXT)
5491      ID: The key identifier
5492
5493      EXT: The DER-encoded extension data; must be freed using
5494      'gnutls_free()' .
5495
5496      This function will convert the provided key identifier to a
5497      DER-encoded PKIX SubjectKeyIdentifier extension.  The output data
5498      in 'ext' will be allocated using 'gnutls_malloc()' .
5499
5500      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5501      otherwise a negative error value.
5502
5503      *Since:* 3.3.0
5504
5505 gnutls_x509_ext_import_aia
5506 --------------------------
5507
5508  -- Function: int gnutls_x509_ext_import_aia (const gnutls_datum_t *
5509           EXT, gnutls_x509_aia_t AIA, unsigned int FLAGS)
5510      EXT: The DER-encoded extension data
5511
5512      AIA: The authority info access
5513
5514      FLAGS: should be zero
5515
5516      This function extracts the Authority Information Access (AIA)
5517      extension from the provided DER-encoded data; see RFC 5280 section
5518      4.2.2.1 for more information on the extension.  The AIA extension
5519      holds a sequence of AccessDescription (AD) data.
5520
5521      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5522      otherwise a negative error value.
5523
5524      *Since:* 3.3.0
5525
5526 gnutls_x509_ext_import_authority_key_id
5527 ---------------------------------------
5528
5529  -- Function: int gnutls_x509_ext_import_authority_key_id (const
5530           gnutls_datum_t * EXT, gnutls_x509_aki_t AKI, unsigned int
5531           FLAGS)
5532      EXT: a DER encoded extension
5533
5534      AKI: An initialized authority key identifier type
5535
5536      FLAGS: should be zero
5537
5538      This function will return the subject key ID stored in the provided
5539      AuthorityKeyIdentifier extension.
5540
5541      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5542      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
5543      present, otherwise a negative error value.
5544
5545      *Since:* 3.3.0
5546
5547 gnutls_x509_ext_import_basic_constraints
5548 ----------------------------------------
5549
5550  -- Function: int gnutls_x509_ext_import_basic_constraints (const
5551           gnutls_datum_t * EXT, unsigned int * CA, int * PATHLEN)
5552      EXT: the DER encoded extension data
5553
5554      CA: will be non zero if the CA status is true
5555
5556      PATHLEN: the path length constraint; will be set to -1 for no limit
5557
5558      This function will return the CA status and path length constraint
5559      as written in the PKIX extension 2.5.29.19.
5560
5561      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5562      otherwise a negative error value.
5563
5564      *Since:* 3.3.0
5565
5566 gnutls_x509_ext_import_crl_dist_points
5567 --------------------------------------
5568
5569  -- Function: int gnutls_x509_ext_import_crl_dist_points (const
5570           gnutls_datum_t * EXT, gnutls_x509_crl_dist_points_t CDP,
5571           unsigned int FLAGS)
5572      EXT: the DER encoded extension data
5573
5574      CDP: A pointer to an initialized CRL distribution points.
5575
5576      FLAGS: should be zero
5577
5578      This function will extract the CRL distribution points extension
5579      (2.5.29.31) and store it into the provided type.
5580
5581      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5582      otherwise a negative error value.
5583
5584      *Since:* 3.3.0
5585
5586 gnutls_x509_ext_import_key_purposes
5587 -----------------------------------
5588
5589  -- Function: int gnutls_x509_ext_import_key_purposes (const
5590           gnutls_datum_t * EXT, gnutls_x509_key_purposes_t P, unsigned
5591           int FLAGS)
5592      EXT: The DER-encoded extension data
5593
5594      P: The key purposes
5595
5596      FLAGS: should be zero
5597
5598      This function will extract the key purposes in the provided
5599      DER-encoded ExtKeyUsageSyntax PKIX extension, to a
5600      'gnutls_x509_key_purposes_t' type.  The data must be initialized.
5601
5602      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5603      otherwise a negative error value.
5604
5605      *Since:* 3.3.0
5606
5607 gnutls_x509_ext_import_key_usage
5608 --------------------------------
5609
5610  -- Function: int gnutls_x509_ext_import_key_usage (const gnutls_datum_t
5611           * EXT, unsigned int * KEY_USAGE)
5612      EXT: the DER encoded extension data
5613
5614      KEY_USAGE: where the key usage bits will be stored
5615
5616      This function will return certificate's key usage, by reading the
5617      DER data of the keyUsage X.509 extension (2.5.29.15).  The key
5618      usage value will ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE'
5619      , 'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
5620      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
5621      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
5622      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
5623
5624      *Returns:* the certificate key usage, or a negative error code in
5625      case of parsing error.  If the certificate does not contain the
5626      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
5627      returned.
5628
5629      *Since:* 3.3.0
5630
5631 gnutls_x509_ext_import_name_constraints
5632 ---------------------------------------
5633
5634  -- Function: int gnutls_x509_ext_import_name_constraints (const
5635           gnutls_datum_t * EXT, gnutls_x509_name_constraints_t NC,
5636           unsigned int FLAGS)
5637      EXT: a DER encoded extension
5638
5639      NC: The nameconstraints
5640
5641      FLAGS: zero or 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND'
5642
5643      This function will return an intermediate type containing the name
5644      constraints of the provided NameConstraints extension.  That can be
5645      used in combination with 'gnutls_x509_name_constraints_check()' to
5646      verify whether a server's name is in accordance with the
5647      constraints.
5648
5649      When the 'flags' is set to 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND' ,
5650      then if the 'nc' type is empty this function will behave
5651      identically as if the flag was not set.  Otherwise if there are
5652      elements in the 'nc' type then only the excluded constraints will
5653      be appended to the constraints.
5654
5655      Note that 'nc' must be initialized prior to calling this function.
5656
5657      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5658      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
5659      present, otherwise a negative error value.
5660
5661      *Since:* 3.3.0
5662
5663 gnutls_x509_ext_import_policies
5664 -------------------------------
5665
5666  -- Function: int gnutls_x509_ext_import_policies (const gnutls_datum_t
5667           * EXT, gnutls_x509_policies_t POLICIES, unsigned int FLAGS)
5668      EXT: the DER encoded extension data
5669
5670      POLICIES: A pointer to an initialized policies.
5671
5672      FLAGS: should be zero
5673
5674      This function will extract the certificate policy extension
5675      (2.5.29.32) and store it the provided policies.
5676
5677      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5678      otherwise a negative error value.
5679
5680      *Since:* 3.3.0
5681
5682 gnutls_x509_ext_import_private_key_usage_period
5683 -----------------------------------------------
5684
5685  -- Function: int gnutls_x509_ext_import_private_key_usage_period (const
5686           gnutls_datum_t * EXT, time_t * ACTIVATION, time_t *
5687           EXPIRATION)
5688      EXT: the DER encoded extension data
5689
5690      ACTIVATION: Will hold the activation time
5691
5692      EXPIRATION: Will hold the expiration time
5693
5694      This function will return the expiration and activation times of
5695      the private key as written in the PKIX extension 2.5.29.16.
5696
5697      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5698      otherwise a negative error value.
5699
5700      *Since:* 3.3.0
5701
5702 gnutls_x509_ext_import_proxy
5703 ----------------------------
5704
5705  -- Function: int gnutls_x509_ext_import_proxy (const gnutls_datum_t *
5706           EXT, int * PATHLEN, char ** POLICYLANGUAGE, char ** POLICY,
5707           size_t * SIZEOF_POLICY)
5708      EXT: the DER encoded extension data
5709
5710      PATHLEN: pointer to output integer indicating path length (may be
5711      NULL), non-negative error codes indicate a present
5712      pCPathLenConstraint field and the actual value, -1 indicate that
5713      the field is absent.
5714
5715      POLICYLANGUAGE: output variable with OID of policy language
5716
5717      POLICY: output variable with policy data
5718
5719      SIZEOF_POLICY: output variable size of policy data
5720
5721      This function will return the information from a proxy certificate
5722      extension.  It reads the ProxyCertInfo X.509 extension
5723      (1.3.6.1.5.5.7.1.14).  The 'policyLanguage' and 'policy' values
5724      must be deinitialized using 'gnutls_free()' after use.
5725
5726      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5727      otherwise a negative error value.
5728
5729      *Since:* 3.3.0
5730
5731 gnutls_x509_ext_import_subject_alt_names
5732 ----------------------------------------
5733
5734  -- Function: int gnutls_x509_ext_import_subject_alt_names (const
5735           gnutls_datum_t * EXT, gnutls_subject_alt_names_t SANS,
5736           unsigned int FLAGS)
5737      EXT: The DER-encoded extension data
5738
5739      SANS: The alternative names
5740
5741      FLAGS: should be zero
5742
5743      This function will export the alternative names in the provided
5744      DER-encoded SubjectAltName PKIX extension, to a
5745      'gnutls_subject_alt_names_t' type.  'sans' must be initialized.
5746
5747      This function will succeed even if there no subject alternative
5748      names in the structure.
5749
5750      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5751      otherwise a negative error value.
5752
5753      *Since:* 3.3.0
5754
5755 gnutls_x509_ext_import_subject_key_id
5756 -------------------------------------
5757
5758  -- Function: int gnutls_x509_ext_import_subject_key_id (const
5759           gnutls_datum_t * EXT, gnutls_datum_t * ID)
5760      EXT: a DER encoded extension
5761
5762      ID: will contain the subject key ID
5763
5764      This function will return the subject key ID stored in the provided
5765      SubjectKeyIdentifier extension.  The ID will be allocated using
5766      'gnutls_malloc()' .
5767
5768      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5769      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
5770      present, otherwise a negative error value.
5771
5772      *Since:* 3.3.0
5773
5774 gnutls_x509_ext_print
5775 ---------------------
5776
5777  -- Function: int gnutls_x509_ext_print (gnutls_x509_ext_st * EXTS,
5778           unsigned int EXTS_SIZE, gnutls_certificate_print_formats_t
5779           FORMAT, gnutls_datum_t * OUT)
5780      EXTS: The data to be printed
5781
5782      EXTS_SIZE: the number of available structures
5783
5784      FORMAT: Indicate the format to use
5785
5786      OUT: Newly allocated datum with null terminated string.
5787
5788      This function will pretty print X.509 certificate extensions,
5789      suitable for display to a human.
5790
5791      The output 'out' needs to be deallocated using 'gnutls_free()' .
5792
5793      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5794      otherwise a negative error value.
5795
5796 gnutls_x509_key_purpose_deinit
5797 ------------------------------
5798
5799  -- Function: void gnutls_x509_key_purpose_deinit
5800           (gnutls_x509_key_purposes_t P)
5801      P: The key purposes
5802
5803      This function will deinitialize a key purposes type.
5804
5805      *Since:* 3.3.0
5806
5807 gnutls_x509_key_purpose_get
5808 ---------------------------
5809
5810  -- Function: int gnutls_x509_key_purpose_get
5811           (gnutls_x509_key_purposes_t P, unsigned IDX, gnutls_datum_t *
5812           OID)
5813      P: The key purposes
5814
5815      IDX: The index of the key purpose to retrieve
5816
5817      OID: Will hold the object identifier of the key purpose (to be
5818      treated as constant)
5819
5820      This function will retrieve the specified by the index key purpose
5821      in the purposes type.  The object identifier will be a null
5822      terminated string.
5823
5824      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5825      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
5826      bounds, otherwise a negative error value.
5827
5828      *Since:* 3.3.0
5829
5830 gnutls_x509_key_purpose_init
5831 ----------------------------
5832
5833  -- Function: int gnutls_x509_key_purpose_init
5834           (gnutls_x509_key_purposes_t * P)
5835      P: The key purposes
5836
5837      This function will initialize an alternative names type.
5838
5839      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5840      otherwise a negative error value.
5841
5842      *Since:* 3.3.0
5843
5844 gnutls_x509_key_purpose_set
5845 ---------------------------
5846
5847  -- Function: int gnutls_x509_key_purpose_set
5848           (gnutls_x509_key_purposes_t P, const char * OID)
5849      P: The key purposes
5850
5851      OID: The object identifier of the key purpose
5852
5853      This function will store the specified key purpose in the purposes.
5854
5855      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
5856      error value.
5857
5858      *Since:* 3.3.0
5859
5860 gnutls_x509_name_constraints_add_excluded
5861 -----------------------------------------
5862
5863  -- Function: int gnutls_x509_name_constraints_add_excluded
5864           (gnutls_x509_name_constraints_t NC,
5865           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
5866           NAME)
5867      NC: The nameconstraints
5868
5869      TYPE: The type of the constraints
5870
5871      NAME: The data of the constraints
5872
5873      This function will add a name constraint to the list of excluded
5874      constraints.
5875
5876      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5877      otherwise a negative error value.
5878
5879      *Since:* 3.3.0
5880
5881 gnutls_x509_name_constraints_add_permitted
5882 ------------------------------------------
5883
5884  -- Function: int gnutls_x509_name_constraints_add_permitted
5885           (gnutls_x509_name_constraints_t NC,
5886           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
5887           NAME)
5888      NC: The nameconstraints
5889
5890      TYPE: The type of the constraints
5891
5892      NAME: The data of the constraints
5893
5894      This function will add a name constraint to the list of permitted
5895      constraints.
5896
5897      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5898      otherwise a negative error value.
5899
5900      *Since:* 3.3.0
5901
5902 gnutls_x509_name_constraints_check
5903 ----------------------------------
5904
5905  -- Function: unsigned gnutls_x509_name_constraints_check
5906           (gnutls_x509_name_constraints_t NC,
5907           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
5908           NAME)
5909      NC: the extracted name constraints
5910
5911      TYPE: the type of the constraint to check (of type
5912      gnutls_x509_subject_alt_name_t)
5913
5914      NAME: the name to be checked
5915
5916      This function will check the provided name against the constraints
5917      in 'nc' using the RFC5280 rules.  Currently this function is
5918      limited to DNS names and emails (of type 'GNUTLS_SAN_DNSNAME' and
5919      'GNUTLS_SAN_RFC822NAME' ).
5920
5921      *Returns:* zero if the provided name is not acceptable, and
5922      non-zero otherwise.
5923
5924      *Since:* 3.3.0
5925
5926 gnutls_x509_name_constraints_check_crt
5927 --------------------------------------
5928
5929  -- Function: unsigned gnutls_x509_name_constraints_check_crt
5930           (gnutls_x509_name_constraints_t NC,
5931           gnutls_x509_subject_alt_name_t TYPE, gnutls_x509_crt_t CERT)
5932      NC: the extracted name constraints
5933
5934      TYPE: the type of the constraint to check (of type
5935      gnutls_x509_subject_alt_name_t)
5936
5937      CERT: the certificate to be checked
5938
5939      This function will check the provided certificate names against the
5940      constraints in 'nc' using the RFC5280 rules.  It will traverse all
5941      the certificate's names and alternative names.
5942
5943      Currently this function is limited to DNS names and emails (of type
5944      'GNUTLS_SAN_DNSNAME' and 'GNUTLS_SAN_RFC822NAME' ).
5945
5946      *Returns:* zero if the provided name is not acceptable, and
5947      non-zero otherwise.
5948
5949      *Since:* 3.3.0
5950
5951 gnutls_x509_name_constraints_deinit
5952 -----------------------------------
5953
5954  -- Function: void gnutls_x509_name_constraints_deinit
5955           (gnutls_x509_name_constraints_t NC)
5956      NC: The nameconstraints
5957
5958      This function will deinitialize a name constraints type.
5959
5960      *Since:* 3.3.0
5961
5962 gnutls_x509_name_constraints_get_excluded
5963 -----------------------------------------
5964
5965  -- Function: int gnutls_x509_name_constraints_get_excluded
5966           (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned *
5967           TYPE, gnutls_datum_t * NAME)
5968      NC: the extracted name constraints
5969
5970      IDX: the index of the constraint
5971
5972      TYPE: the type of the constraint (of type
5973      gnutls_x509_subject_alt_name_t)
5974
5975      NAME: the name in the constraint (of the specific type)
5976
5977      This function will return an intermediate type containing the name
5978      constraints of the provided CA certificate.  That structure can be
5979      used in combination with 'gnutls_x509_name_constraints_check()' to
5980      verify whether a server's name is in accordance with the
5981      constraints.
5982
5983      The name should be treated as constant and valid for the lifetime
5984      of 'nc' .
5985
5986      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5987      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
5988      present, otherwise a negative error value.
5989
5990      *Since:* 3.3.0
5991
5992 gnutls_x509_name_constraints_get_permitted
5993 ------------------------------------------
5994
5995  -- Function: int gnutls_x509_name_constraints_get_permitted
5996           (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned *
5997           TYPE, gnutls_datum_t * NAME)
5998      NC: the extracted name constraints
5999
6000      IDX: the index of the constraint
6001
6002      TYPE: the type of the constraint (of type
6003      gnutls_x509_subject_alt_name_t)
6004
6005      NAME: the name in the constraint (of the specific type)
6006
6007      This function will return an intermediate type containing the name
6008      constraints of the provided CA certificate.  That structure can be
6009      used in combination with 'gnutls_x509_name_constraints_check()' to
6010      verify whether a server's name is in accordance with the
6011      constraints.
6012
6013      The name should be treated as constant and valid for the lifetime
6014      of 'nc' .
6015
6016      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6017      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
6018      present, otherwise a negative error value.
6019
6020      *Since:* 3.3.0
6021
6022 gnutls_x509_name_constraints_init
6023 ---------------------------------
6024
6025  -- Function: int gnutls_x509_name_constraints_init
6026           (gnutls_x509_name_constraints_t * NC)
6027      NC: The nameconstraints
6028
6029      This function will initialize a name constraints type.
6030
6031      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6032      otherwise a negative error value.
6033
6034      *Since:* 3.3.0
6035
6036 gnutls_x509_othername_to_virtual
6037 --------------------------------
6038
6039  -- Function: int gnutls_x509_othername_to_virtual (const char * OID,
6040           const gnutls_datum_t * OTHERNAME, unsigned int * VIRT_TYPE,
6041           gnutls_datum_t * VIRT)
6042      OID: The othername object identifier
6043
6044      OTHERNAME: The othername data
6045
6046      VIRT_TYPE: GNUTLS_SAN_OTHERNAME_XXX
6047
6048      VIRT: allocated printable data
6049
6050      This function will parse and convert the othername data to a
6051      virtual type supported by gnutls.
6052
6053      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6054      otherwise a negative error value.
6055
6056      *Since:* 3.3.8
6057
6058 gnutls_x509_policies_deinit
6059 ---------------------------
6060
6061  -- Function: void gnutls_x509_policies_deinit (gnutls_x509_policies_t
6062           POLICIES)
6063      POLICIES: The authority key identifier
6064
6065      This function will deinitialize an authority key identifier type.
6066
6067      *Since:* 3.3.0
6068
6069 gnutls_x509_policies_get
6070 ------------------------
6071
6072  -- Function: int gnutls_x509_policies_get (gnutls_x509_policies_t
6073           POLICIES, unsigned int SEQ, struct gnutls_x509_policy_st *
6074           POLICY)
6075      POLICIES: The policies
6076
6077      SEQ: The index of the name to get
6078
6079      POLICY: Will hold the policy
6080
6081      This function will return a specific policy as stored in the
6082      'policies' type.  The returned values should be treated as constant
6083      and valid for the lifetime of 'policies' .
6084
6085      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6086      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
6087      bounds, otherwise a negative error value.
6088
6089      *Since:* 3.3.0
6090
6091 gnutls_x509_policies_init
6092 -------------------------
6093
6094  -- Function: int gnutls_x509_policies_init (gnutls_x509_policies_t *
6095           POLICIES)
6096      POLICIES: The authority key ID
6097
6098      This function will initialize an authority key ID type.
6099
6100      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6101      otherwise a negative error value.
6102
6103      *Since:* 3.3.0
6104
6105 gnutls_x509_policies_set
6106 ------------------------
6107
6108  -- Function: int gnutls_x509_policies_set (gnutls_x509_policies_t
6109           POLICIES, const struct gnutls_x509_policy_st * POLICY)
6110      POLICIES: An initialized policies
6111
6112      POLICY: Contains the policy to set
6113
6114      This function will store the specified policy in the provided
6115      'policies' .
6116
6117      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
6118      error value.
6119
6120      *Since:* 3.3.0
6121
6122 gnutls_x509_policy_release
6123 --------------------------
6124
6125  -- Function: void gnutls_x509_policy_release (struct
6126           gnutls_x509_policy_st * POLICY)
6127      POLICY: a certificate policy
6128
6129      This function will deinitialize all memory associated with the
6130      provided 'policy' .  The policy is allocated using
6131      'gnutls_x509_crt_get_policy()' .
6132
6133      *Since:* 3.1.5
6134
6135 gnutls_x509_privkey_cpy
6136 -----------------------
6137
6138  -- Function: int gnutls_x509_privkey_cpy (gnutls_x509_privkey_t DST,
6139           gnutls_x509_privkey_t SRC)
6140      DST: The destination key, which should be initialized.
6141
6142      SRC: The source key
6143
6144      This function will copy a private key from source to destination
6145      key.  Destination has to be initialized.
6146
6147      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6148      otherwise a negative error value.
6149
6150 gnutls_x509_privkey_deinit
6151 --------------------------
6152
6153  -- Function: void gnutls_x509_privkey_deinit (gnutls_x509_privkey_t
6154           KEY)
6155      KEY: The key to be deinitialized
6156
6157      This function will deinitialize a private key structure.
6158
6159 gnutls_x509_privkey_export
6160 --------------------------
6161
6162  -- Function: int gnutls_x509_privkey_export (gnutls_x509_privkey_t KEY,
6163           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
6164           OUTPUT_DATA_SIZE)
6165      KEY: Holds the key
6166
6167      FORMAT: the format of output params.  One of PEM or DER.
6168
6169      OUTPUT_DATA: will contain a private key PEM or DER encoded
6170
6171      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
6172      replaced by the actual size of parameters)
6173
6174      This function will export the private key to a PKCS1 structure for
6175      RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
6176      the same format with the parameters used by openssl.
6177
6178      If the buffer provided is not long enough to hold the output, then
6179      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
6180      will be returned.
6181
6182      If the structure is PEM encoded, it will have a header of "BEGIN
6183      RSA PRIVATE KEY".
6184
6185      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6186      otherwise a negative error value.
6187
6188 gnutls_x509_privkey_export2
6189 ---------------------------
6190
6191  -- Function: int gnutls_x509_privkey_export2 (gnutls_x509_privkey_t
6192           KEY, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
6193      KEY: Holds the key
6194
6195      FORMAT: the format of output params.  One of PEM or DER.
6196
6197      OUT: will contain a private key PEM or DER encoded
6198
6199      This function will export the private key to a PKCS1 structure for
6200      RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
6201      the same format with the parameters used by openssl.
6202
6203      The output buffer is allocated using 'gnutls_malloc()' .
6204
6205      If the structure is PEM encoded, it will have a header of "BEGIN
6206      RSA PRIVATE KEY".
6207
6208      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6209      otherwise a negative error value.
6210
6211      Since 3.1.3
6212
6213 gnutls_x509_privkey_export2_pkcs8
6214 ---------------------------------
6215
6216  -- Function: int gnutls_x509_privkey_export2_pkcs8
6217           (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT,
6218           const char * PASSWORD, unsigned int FLAGS, gnutls_datum_t *
6219           OUT)
6220      KEY: Holds the key
6221
6222      FORMAT: the format of output params.  One of PEM or DER.
6223
6224      PASSWORD: the password that will be used to encrypt the key.
6225
6226      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
6227
6228      OUT: will contain a private key PEM or DER encoded
6229
6230      This function will export the private key to a PKCS8 structure.
6231      Both RSA and DSA keys can be exported.  For DSA keys we use PKCS
6232      '11' definitions.  If the flags do not specify the encryption
6233      cipher, then the default 3DES (PBES2) will be used.
6234
6235      The 'password' can be either ASCII or UTF-8 in the default PBES2
6236      encryption schemas, or ASCII for the PKCS12 schemas.
6237
6238      The output buffer is allocated using 'gnutls_malloc()' .
6239
6240      If the structure is PEM encoded, it will have a header of "BEGIN
6241      ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if encryption is not
6242      used.
6243
6244      *Returns:* In case of failure a negative error code will be
6245      returned, and 0 on success.
6246
6247      Since 3.1.3
6248
6249 gnutls_x509_privkey_export_dsa_raw
6250 ----------------------------------
6251
6252  -- Function: int gnutls_x509_privkey_export_dsa_raw
6253           (gnutls_x509_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t
6254           * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t *
6255           X)
6256      KEY: a key
6257
6258      P: will hold the p
6259
6260      Q: will hold the q
6261
6262      G: will hold the g
6263
6264      Y: will hold the y
6265
6266      X: will hold the x
6267
6268      This function will export the DSA private key's parameters found in
6269      the given structure.  The new parameters will be allocated using
6270      'gnutls_malloc()' and will be stored in the appropriate datum.
6271
6272      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6273      otherwise a negative error value.
6274
6275 gnutls_x509_privkey_export_ecc_raw
6276 ----------------------------------
6277
6278  -- Function: int gnutls_x509_privkey_export_ecc_raw
6279           (gnutls_x509_privkey_t KEY, gnutls_ecc_curve_t * CURVE,
6280           gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K)
6281      KEY: a key
6282
6283      CURVE: will hold the curve
6284
6285      X: will hold the x coordinate
6286
6287      Y: will hold the y coordinate
6288
6289      K: will hold the private key
6290
6291      This function will export the ECC private key's parameters found in
6292      the given structure.  The new parameters will be allocated using
6293      'gnutls_malloc()' and will be stored in the appropriate datum.
6294
6295      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6296      otherwise a negative error value.
6297
6298      *Since:* 3.0
6299
6300 gnutls_x509_privkey_export_pkcs8
6301 --------------------------------
6302
6303  -- Function: int gnutls_x509_privkey_export_pkcs8
6304           (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT,
6305           const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA,
6306           size_t * OUTPUT_DATA_SIZE)
6307      KEY: Holds the key
6308
6309      FORMAT: the format of output params.  One of PEM or DER.
6310
6311      PASSWORD: the password that will be used to encrypt the key.
6312
6313      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
6314
6315      OUTPUT_DATA: will contain a private key PEM or DER encoded
6316
6317      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
6318      replaced by the actual size of parameters)
6319
6320      This function will export the private key to a PKCS8 structure.
6321      Both RSA and DSA keys can be exported.  For DSA keys we use PKCS
6322      '11' definitions.  If the flags do not specify the encryption
6323      cipher, then the default 3DES (PBES2) will be used.
6324
6325      The 'password' can be either ASCII or UTF-8 in the default PBES2
6326      encryption schemas, or ASCII for the PKCS12 schemas.
6327
6328      If the buffer provided is not long enough to hold the output, then
6329      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
6330      be returned.
6331
6332      If the structure is PEM encoded, it will have a header of "BEGIN
6333      ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if encryption is not
6334      used.
6335
6336      *Returns:* In case of failure a negative error code will be
6337      returned, and 0 on success.
6338
6339 gnutls_x509_privkey_export_rsa_raw
6340 ----------------------------------
6341
6342  -- Function: int gnutls_x509_privkey_export_rsa_raw
6343           (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t
6344           * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t *
6345           Q, gnutls_datum_t * U)
6346      KEY: a key
6347
6348      M: will hold the modulus
6349
6350      E: will hold the public exponent
6351
6352      D: will hold the private exponent
6353
6354      P: will hold the first prime (p)
6355
6356      Q: will hold the second prime (q)
6357
6358      U: will hold the coefficient
6359
6360      This function will export the RSA private key's parameters found in
6361      the given structure.  The new parameters will be allocated using
6362      'gnutls_malloc()' and will be stored in the appropriate datum.
6363
6364      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6365      otherwise a negative error value.
6366
6367 gnutls_x509_privkey_export_rsa_raw2
6368 -----------------------------------
6369
6370  -- Function: int gnutls_x509_privkey_export_rsa_raw2
6371           (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t
6372           * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t *
6373           Q, gnutls_datum_t * U, gnutls_datum_t * E1, gnutls_datum_t *
6374           E2)
6375      KEY: a key
6376
6377      M: will hold the modulus
6378
6379      E: will hold the public exponent
6380
6381      D: will hold the private exponent
6382
6383      P: will hold the first prime (p)
6384
6385      Q: will hold the second prime (q)
6386
6387      U: will hold the coefficient
6388
6389      E1: will hold e1 = d mod (p-1)
6390
6391      E2: will hold e2 = d mod (q-1)
6392
6393      This function will export the RSA private key's parameters found in
6394      the given structure.  The new parameters will be allocated using
6395      'gnutls_malloc()' and will be stored in the appropriate datum.
6396
6397      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6398      otherwise a negative error value.
6399
6400      *Since:* 2.12.0
6401
6402 gnutls_x509_privkey_fix
6403 -----------------------
6404
6405  -- Function: int gnutls_x509_privkey_fix (gnutls_x509_privkey_t KEY)
6406      KEY: a key
6407
6408      This function will recalculate the secondary parameters in a key.
6409      In RSA keys, this can be the coefficient and exponent1,2.
6410
6411      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6412      otherwise a negative error value.
6413
6414 gnutls_x509_privkey_generate
6415 ----------------------------
6416
6417  -- Function: int gnutls_x509_privkey_generate (gnutls_x509_privkey_t
6418           KEY, gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned
6419           int FLAGS)
6420      KEY: a key
6421
6422      ALGO: is one of the algorithms in 'gnutls_pk_algorithm_t' .
6423
6424      BITS: the size of the modulus
6425
6426      FLAGS: unused for now.  Must be 0.
6427
6428      This function will generate a random private key.  Note that this
6429      function must be called on an empty private key.
6430
6431      Note that when generating an elliptic curve key, the curve can be
6432      substituted in the place of the bits parameter using the
6433      'GNUTLS_CURVE_TO_BITS()' macro.
6434
6435      For DSA keys, if the subgroup size needs to be specified check the
6436      'GNUTLS_SUBGROUP_TO_BITS()' macro.
6437
6438      Do not set the number of bits directly, use
6439      'gnutls_sec_param_to_pk_bits()' .
6440
6441      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6442      otherwise a negative error value.
6443
6444 gnutls_x509_privkey_get_key_id
6445 ------------------------------
6446
6447  -- Function: int gnutls_x509_privkey_get_key_id (gnutls_x509_privkey_t
6448           KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
6449           OUTPUT_DATA_SIZE)
6450      KEY: a key
6451
6452      FLAGS: should be one of the flags from 'gnutls_keyid_flags_t'
6453
6454      OUTPUT_DATA: will contain the key ID
6455
6456      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
6457      replaced by the actual size of parameters)
6458
6459      This function will return a unique ID that depends on the public
6460      key parameters.  This ID can be used in checking whether a
6461      certificate corresponds to the given key.
6462
6463      If the buffer provided is not long enough to hold the output, then
6464      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
6465      will be returned.  The output will normally be a SHA-1 hash output,
6466      which is 20 bytes.
6467
6468      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6469      otherwise a negative error value.
6470
6471 gnutls_x509_privkey_get_pk_algorithm
6472 ------------------------------------
6473
6474  -- Function: int gnutls_x509_privkey_get_pk_algorithm
6475           (gnutls_x509_privkey_t KEY)
6476      KEY: should contain a 'gnutls_x509_privkey_t' type
6477
6478      This function will return the public key algorithm of a private
6479      key.
6480
6481      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
6482      success, or a negative error code on error.
6483
6484 gnutls_x509_privkey_get_pk_algorithm2
6485 -------------------------------------
6486
6487  -- Function: int gnutls_x509_privkey_get_pk_algorithm2
6488           (gnutls_x509_privkey_t KEY, unsigned int * BITS)
6489      KEY: should contain a 'gnutls_x509_privkey_t' type
6490
6491      BITS: The number of bits in the public key algorithm
6492
6493      This function will return the public key algorithm of a private
6494      key.
6495
6496      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
6497      success, or a negative error code on error.
6498
6499 gnutls_x509_privkey_import
6500 --------------------------
6501
6502  -- Function: int gnutls_x509_privkey_import (gnutls_x509_privkey_t KEY,
6503           const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
6504      KEY: The data to store the parsed key
6505
6506      DATA: The DER or PEM encoded certificate.
6507
6508      FORMAT: One of DER or PEM
6509
6510      This function will convert the given DER or PEM encoded key to the
6511      native 'gnutls_x509_privkey_t' format.  The output will be stored
6512      in 'key' .
6513
6514      If the key is PEM encoded it should have a header that contains
6515      "PRIVATE KEY". Note that this function falls back to PKCS '8'
6516      decoding without password, if the default format fails to import.
6517
6518      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6519      otherwise a negative error value.
6520
6521 gnutls_x509_privkey_import2
6522 ---------------------------
6523
6524  -- Function: int gnutls_x509_privkey_import2 (gnutls_x509_privkey_t
6525           KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t
6526           FORMAT, const char * PASSWORD, unsigned int FLAGS)
6527      KEY: The data to store the parsed key
6528
6529      DATA: The DER or PEM encoded key.
6530
6531      FORMAT: One of DER or PEM
6532
6533      PASSWORD: A password (optional)
6534
6535      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
6536
6537      This function will import the given DER or PEM encoded key, to the
6538      native 'gnutls_x509_privkey_t' format, irrespective of the input
6539      format.  The input format is auto-detected.
6540
6541      The supported formats are basic unencrypted key, PKCS8, PKCS12, and
6542      the openssl format.
6543
6544      If the provided key is encrypted but no password was given, then
6545      'GNUTLS_E_DECRYPTION_FAILED' is returned.  Since GnuTLS 3.4.0 this
6546      function will utilize the PIN callbacks if any.
6547
6548      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6549      otherwise a negative error value.
6550
6551 gnutls_x509_privkey_import_dsa_raw
6552 ----------------------------------
6553
6554  -- Function: int gnutls_x509_privkey_import_dsa_raw
6555           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * P, const
6556           gnutls_datum_t * Q, const gnutls_datum_t * G, const
6557           gnutls_datum_t * Y, const gnutls_datum_t * X)
6558      KEY: The data to store the parsed key
6559
6560      P: holds the p
6561
6562      Q: holds the q
6563
6564      G: holds the g
6565
6566      Y: holds the y
6567
6568      X: holds the x
6569
6570      This function will convert the given DSA raw parameters to the
6571      native 'gnutls_x509_privkey_t' format.  The output will be stored
6572      in 'key' .
6573
6574      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6575      otherwise a negative error value.
6576
6577 gnutls_x509_privkey_import_ecc_raw
6578 ----------------------------------
6579
6580  -- Function: int gnutls_x509_privkey_import_ecc_raw
6581           (gnutls_x509_privkey_t KEY, gnutls_ecc_curve_t CURVE, const
6582           gnutls_datum_t * X, const gnutls_datum_t * Y, const
6583           gnutls_datum_t * K)
6584      KEY: The data to store the parsed key
6585
6586      CURVE: holds the curve
6587
6588      X: holds the x
6589
6590      Y: holds the y
6591
6592      K: holds the k
6593
6594      This function will convert the given elliptic curve parameters to
6595      the native 'gnutls_x509_privkey_t' format.  The output will be
6596      stored in 'key' .
6597
6598      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6599      otherwise a negative error value.
6600
6601      *Since:* 3.0
6602
6603 gnutls_x509_privkey_import_openssl
6604 ----------------------------------
6605
6606  -- Function: int gnutls_x509_privkey_import_openssl
6607           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, const
6608           char * PASSWORD)
6609      KEY: The data to store the parsed key
6610
6611      DATA: The DER or PEM encoded key.
6612
6613      PASSWORD: the password to decrypt the key (if it is encrypted).
6614
6615      This function will convert the given PEM encrypted to the native
6616      gnutls_x509_privkey_t format.  The output will be stored in 'key' .
6617
6618      The 'password' should be in ASCII. If the password is not provided
6619      or wrong then 'GNUTLS_E_DECRYPTION_FAILED' will be returned.
6620
6621      If the Certificate is PEM encoded it should have a header of
6622      "PRIVATE KEY" and the "DEK-Info" header.
6623
6624      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6625      otherwise a negative error value.
6626
6627 gnutls_x509_privkey_import_pkcs8
6628 --------------------------------
6629
6630  -- Function: int gnutls_x509_privkey_import_pkcs8
6631           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA,
6632           gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned
6633           int FLAGS)
6634      KEY: The data to store the parsed key
6635
6636      DATA: The DER or PEM encoded key.
6637
6638      FORMAT: One of DER or PEM
6639
6640      PASSWORD: the password to decrypt the key (if it is encrypted).
6641
6642      FLAGS: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
6643
6644      This function will convert the given DER or PEM encoded PKCS8 2.0
6645      encrypted key to the native gnutls_x509_privkey_t format.  The
6646      output will be stored in 'key' .  Both RSA and DSA keys can be
6647      imported, and flags can only be used to indicate an unencrypted
6648      key.
6649
6650      The 'password' can be either ASCII or UTF-8 in the default PBES2
6651      encryption schemas, or ASCII for the PKCS12 schemas.
6652
6653      If the Certificate is PEM encoded it should have a header of
6654      "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to specify
6655      the flags if the key is DER encoded, since in that case the
6656      encryption status cannot be auto-detected.
6657
6658      If the 'GNUTLS_PKCS_PLAIN' flag is specified and the supplied data
6659      are encrypted then 'GNUTLS_E_DECRYPTION_FAILED' is returned.
6660
6661      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6662      otherwise a negative error value.
6663
6664 gnutls_x509_privkey_import_rsa_raw
6665 ----------------------------------
6666
6667  -- Function: int gnutls_x509_privkey_import_rsa_raw
6668           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * M, const
6669           gnutls_datum_t * E, const gnutls_datum_t * D, const
6670           gnutls_datum_t * P, const gnutls_datum_t * Q, const
6671           gnutls_datum_t * U)
6672      KEY: The data to store the parsed key
6673
6674      M: holds the modulus
6675
6676      E: holds the public exponent
6677
6678      D: holds the private exponent
6679
6680      P: holds the first prime (p)
6681
6682      Q: holds the second prime (q)
6683
6684      U: holds the coefficient
6685
6686      This function will convert the given RSA raw parameters to the
6687      native 'gnutls_x509_privkey_t' format.  The output will be stored
6688      in 'key' .
6689
6690      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6691      otherwise a negative error value.
6692
6693 gnutls_x509_privkey_import_rsa_raw2
6694 -----------------------------------
6695
6696  -- Function: int gnutls_x509_privkey_import_rsa_raw2
6697           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * M, const
6698           gnutls_datum_t * E, const gnutls_datum_t * D, const
6699           gnutls_datum_t * P, const gnutls_datum_t * Q, const
6700           gnutls_datum_t * U, const gnutls_datum_t * E1, const
6701           gnutls_datum_t * E2)
6702      KEY: The data to store the parsed key
6703
6704      M: holds the modulus
6705
6706      E: holds the public exponent
6707
6708      D: holds the private exponent
6709
6710      P: holds the first prime (p)
6711
6712      Q: holds the second prime (q)
6713
6714      U: holds the coefficient (optional)
6715
6716      E1: holds e1 = d mod (p-1) (optional)
6717
6718      E2: holds e2 = d mod (q-1) (optional)
6719
6720      This function will convert the given RSA raw parameters to the
6721      native 'gnutls_x509_privkey_t' format.  The output will be stored
6722      in 'key' .
6723
6724      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6725      otherwise a negative error value.
6726
6727 gnutls_x509_privkey_init
6728 ------------------------
6729
6730  -- Function: int gnutls_x509_privkey_init (gnutls_x509_privkey_t * KEY)
6731      KEY: A pointer to the type to be initialized
6732
6733      This function will initialize a private key type.
6734
6735      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6736      otherwise a negative error value.
6737
6738 gnutls_x509_privkey_sec_param
6739 -----------------------------
6740
6741  -- Function: gnutls_sec_param_t gnutls_x509_privkey_sec_param
6742           (gnutls_x509_privkey_t KEY)
6743      KEY: a key
6744
6745      This function will return the security parameter appropriate with
6746      this private key.
6747
6748      *Returns:* On success, a valid security parameter is returned
6749      otherwise 'GNUTLS_SEC_PARAM_UNKNOWN' is returned.
6750
6751      *Since:* 2.12.0
6752
6753 gnutls_x509_privkey_set_pin_function
6754 ------------------------------------
6755
6756  -- Function: void gnutls_x509_privkey_set_pin_function
6757           (gnutls_x509_privkey_t PRIVKEY, gnutls_pin_callback_t FN, void
6758           * USERDATA)
6759      PRIVKEY: The certificate structure
6760
6761      FN: the callback
6762
6763      USERDATA: data associated with the callback
6764
6765      This function will set a callback function to be used when it is
6766      required to access a protected object.  This function overrides the
6767      global function set using 'gnutls_pkcs11_set_pin_function()' .
6768
6769      Note that this callback is used when decrypting a key.
6770
6771      *Since:* 3.4.0
6772
6773 gnutls_x509_privkey_sign_data
6774 -----------------------------
6775
6776  -- Function: int gnutls_x509_privkey_sign_data (gnutls_x509_privkey_t
6777           KEY, gnutls_digest_algorithm_t DIGEST, unsigned int FLAGS,
6778           const gnutls_datum_t * DATA, void * SIGNATURE, size_t *
6779           SIGNATURE_SIZE)
6780      KEY: a key
6781
6782      DIGEST: should be MD5 or SHA1
6783
6784      FLAGS: should be 0 for now
6785
6786      DATA: holds the data to be signed
6787
6788      SIGNATURE: will contain the signature
6789
6790      SIGNATURE_SIZE: holds the size of signature (and will be replaced
6791      by the new size)
6792
6793      This function will sign the given data using a signature algorithm
6794      supported by the private key.  Signature algorithms are always used
6795      together with a hash functions.  Different hash functions may be
6796      used for the RSA algorithm, but only SHA-1 for the DSA keys.
6797
6798      If the buffer provided is not long enough to hold the output, then
6799      * 'signature_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
6800      will be returned.
6801
6802      Use 'gnutls_x509_crt_get_preferred_hash_algorithm()' to determine
6803      the hash algorithm.
6804
6805      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6806      otherwise a negative error value.
6807
6808 gnutls_x509_privkey_verify_params
6809 ---------------------------------
6810
6811  -- Function: int gnutls_x509_privkey_verify_params
6812           (gnutls_x509_privkey_t KEY)
6813      KEY: a key
6814
6815      This function will verify the private key parameters.
6816
6817      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6818      otherwise a negative error value.
6819
6820 gnutls_x509_rdn_get
6821 -------------------
6822
6823  -- Function: int gnutls_x509_rdn_get (const gnutls_datum_t * IDN, char
6824           * BUF, size_t * BUF_SIZE)
6825      IDN: should contain a DER encoded RDN sequence
6826
6827      BUF: a pointer to a structure to hold the peer's name
6828
6829      BUF_SIZE: holds the size of 'buf'
6830
6831      This function will return the name of the given RDN sequence.  The
6832      name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
6833      RFC4514.
6834
6835      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
6836      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
6837      updated if the provided buffer is not long enough, otherwise a
6838      negative error value.
6839
6840 gnutls_x509_rdn_get_by_oid
6841 --------------------------
6842
6843  -- Function: int gnutls_x509_rdn_get_by_oid (const gnutls_datum_t *
6844           IDN, const char * OID, int INDX, unsigned int RAW_FLAG, void *
6845           BUF, size_t * BUF_SIZE)
6846      IDN: should contain a DER encoded RDN sequence
6847
6848      OID: an Object Identifier
6849
6850      INDX: In case multiple same OIDs exist in the RDN indicates which
6851      to send.  Use 0 for the first one.
6852
6853      RAW_FLAG: If non-zero then the raw DER data are returned.
6854
6855      BUF: a pointer to a structure to hold the peer's name
6856
6857      BUF_SIZE: holds the size of 'buf'
6858
6859      This function will return the name of the given Object identifier,
6860      of the RDN sequence.  The name will be encoded using the rules from
6861      RFC4514.
6862
6863      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
6864      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
6865      updated if the provided buffer is not long enough, otherwise a
6866      negative error value.
6867
6868 gnutls_x509_rdn_get_oid
6869 -----------------------
6870
6871  -- Function: int gnutls_x509_rdn_get_oid (const gnutls_datum_t * IDN,
6872           int INDX, void * BUF, size_t * BUF_SIZE)
6873      IDN: should contain a DER encoded RDN sequence
6874
6875      INDX: Indicates which OID to return.  Use 0 for the first one.
6876
6877      BUF: a pointer to a structure to hold the peer's name OID
6878
6879      BUF_SIZE: holds the size of 'buf'
6880
6881      This function will return the specified Object identifier, of the
6882      RDN sequence.
6883
6884      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
6885      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
6886      updated if the provided buffer is not long enough, otherwise a
6887      negative error value.
6888
6889      *Since:* 2.4.0
6890
6891 gnutls_x509_trust_list_add_cas
6892 ------------------------------
6893
6894  -- Function: int gnutls_x509_trust_list_add_cas
6895           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
6896           CLIST, unsigned CLIST_SIZE, unsigned int FLAGS)
6897      LIST: The list
6898
6899      CLIST: A list of CAs
6900
6901      CLIST_SIZE: The length of the CA list
6902
6903      FLAGS: should be 0 or an or'ed sequence of 'GNUTLS_TL' options.
6904
6905      This function will add the given certificate authorities to the
6906      trusted list.  The list of CAs must not be deinitialized during
6907      this structure's lifetime.
6908
6909      If the flag 'GNUTLS_TL_NO_DUPLICATES' is specified, then the
6910      provided 'clist' entries that are duplicates will not be added to
6911      the list and will be deinitialized.
6912
6913      *Returns:* The number of added elements is returned.
6914
6915      *Since:* 3.0.0
6916
6917 gnutls_x509_trust_list_add_crls
6918 -------------------------------
6919
6920  -- Function: int gnutls_x509_trust_list_add_crls
6921           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crl_t *
6922           CRL_LIST, int CRL_SIZE, unsigned int FLAGS, unsigned int
6923           VERIFICATION_FLAGS)
6924      LIST: The list
6925
6926      CRL_LIST: A list of CRLs
6927
6928      CRL_SIZE: The length of the CRL list
6929
6930      FLAGS: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified
6931      before being added.
6932
6933      VERIFICATION_FLAGS: gnutls_certificate_verify_flags if flags
6934      specifies GNUTLS_TL_VERIFY_CRL
6935
6936      This function will add the given certificate revocation lists to
6937      the trusted list.  The list of CRLs must not be deinitialized
6938      during this structure's lifetime.
6939
6940      This function must be called after
6941      'gnutls_x509_trust_list_add_cas()' to allow verifying the CRLs for
6942      validity.  If the flag 'GNUTLS_TL_NO_DUPLICATES' is given, then any
6943      provided CRLs that are a duplicate, will be deinitialized and not
6944      added to the list (that assumes that
6945      'gnutls_x509_trust_list_deinit()' will be called with all=1).
6946
6947      *Returns:* The number of added elements is returned.
6948
6949      *Since:* 3.0
6950
6951 gnutls_x509_trust_list_add_named_crt
6952 ------------------------------------
6953
6954  -- Function: int gnutls_x509_trust_list_add_named_crt
6955           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
6956           void * NAME, size_t NAME_SIZE, unsigned int FLAGS)
6957      LIST: The list
6958
6959      CERT: A certificate
6960
6961      NAME: An identifier for the certificate
6962
6963      NAME_SIZE: The size of the identifier
6964
6965      FLAGS: should be 0.
6966
6967      This function will add the given certificate to the trusted list
6968      and associate it with a name.  The certificate will not be be used
6969      for verification with 'gnutls_x509_trust_list_verify_crt()' but
6970      with 'gnutls_x509_trust_list_verify_named_crt()' or
6971      'gnutls_x509_trust_list_verify_crt2()' - the latter only since
6972      GnuTLS 3.4.0 and if a hostname is provided.
6973
6974      In principle this function can be used to set individual "server"
6975      certificates that are trusted by the user for that specific server
6976      but for no other purposes.
6977
6978      The certificate must not be deinitialized during the lifetime of
6979      the trusted list.
6980
6981      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6982      otherwise a negative error value.
6983
6984      *Since:* 3.0.0
6985
6986 gnutls_x509_trust_list_add_system_trust
6987 ---------------------------------------
6988
6989  -- Function: int gnutls_x509_trust_list_add_system_trust
6990           (gnutls_x509_trust_list_t LIST, unsigned int TL_FLAGS,
6991           unsigned int TL_VFLAGS)
6992      LIST: The structure of the list
6993
6994      TL_FLAGS: GNUTLS_TL_*
6995
6996      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
6997      GNUTLS_TL_VERIFY_CRL
6998
6999      This function adds the system's default trusted certificate
7000      authorities to the trusted list.  Note that on unsupported systems
7001      this function returns 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .
7002
7003      This function implies the flag 'GNUTLS_TL_NO_DUPLICATES' .
7004
7005      *Returns:* The number of added elements or a negative error code on
7006      error.
7007
7008      *Since:* 3.1
7009
7010 gnutls_x509_trust_list_add_trust_dir
7011 ------------------------------------
7012
7013  -- Function: int gnutls_x509_trust_list_add_trust_dir
7014           (gnutls_x509_trust_list_t LIST, const char * CA_DIR, const
7015           char * CRL_DIR, gnutls_x509_crt_fmt_t TYPE, unsigned int
7016           TL_FLAGS, unsigned int TL_VFLAGS)
7017      LIST: The list
7018
7019      CA_DIR: A directory containing the CAs (optional)
7020
7021      CRL_DIR: A directory containing a list of CRLs (optional)
7022
7023      TYPE: The format of the certificates
7024
7025      TL_FLAGS: GNUTLS_TL_*
7026
7027      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
7028      GNUTLS_TL_VERIFY_CRL
7029
7030      This function will add the given certificate authorities to the
7031      trusted list.  Only directories are accepted by this function.
7032
7033      *Returns:* The number of added elements is returned.
7034
7035      *Since:* 3.3.6
7036
7037 gnutls_x509_trust_list_add_trust_file
7038 -------------------------------------
7039
7040  -- Function: int gnutls_x509_trust_list_add_trust_file
7041           (gnutls_x509_trust_list_t LIST, const char * CA_FILE, const
7042           char * CRL_FILE, gnutls_x509_crt_fmt_t TYPE, unsigned int
7043           TL_FLAGS, unsigned int TL_VFLAGS)
7044      LIST: The list
7045
7046      CA_FILE: A file containing a list of CAs (optional)
7047
7048      CRL_FILE: A file containing a list of CRLs (optional)
7049
7050      TYPE: The format of the certificates
7051
7052      TL_FLAGS: GNUTLS_TL_*
7053
7054      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
7055      GNUTLS_TL_VERIFY_CRL
7056
7057      This function will add the given certificate authorities to the
7058      trusted list.  PKCS '11' URLs are also accepted, instead of files,
7059      by this function.  A PKCS '11' URL implies a trust database (a
7060      specially marked module in p11-kit); the URL "pkcs11:" implies all
7061      trust databases in the system.  Only a single URL specifying trust
7062      databases can be set; they cannot be stacked with multiple calls.
7063
7064      *Returns:* The number of added elements is returned.
7065
7066      *Since:* 3.1
7067
7068 gnutls_x509_trust_list_add_trust_mem
7069 ------------------------------------
7070
7071  -- Function: int gnutls_x509_trust_list_add_trust_mem
7072           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
7073           const gnutls_datum_t * CRLS, gnutls_x509_crt_fmt_t TYPE,
7074           unsigned int TL_FLAGS, unsigned int TL_VFLAGS)
7075      LIST: The list
7076
7077      CAS: A buffer containing a list of CAs (optional)
7078
7079      CRLS: A buffer containing a list of CRLs (optional)
7080
7081      TYPE: The format of the certificates
7082
7083      TL_FLAGS: GNUTLS_TL_*
7084
7085      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
7086      GNUTLS_TL_VERIFY_CRL
7087
7088      This function will add the given certificate authorities to the
7089      trusted list.
7090
7091      *Returns:* The number of added elements is returned.
7092
7093      *Since:* 3.1
7094
7095 gnutls_x509_trust_list_deinit
7096 -----------------------------
7097
7098  -- Function: void gnutls_x509_trust_list_deinit
7099           (gnutls_x509_trust_list_t LIST, unsigned int ALL)
7100      LIST: The list to be deinitialized
7101
7102      ALL: if non-zero it will deinitialize all the certificates and CRLs
7103      contained in the structure.
7104
7105      This function will deinitialize a trust list.  Note that the 'all'
7106      flag should be typically non-zero unless you have specified your
7107      certificates using 'gnutls_x509_trust_list_add_cas()' and you want
7108      to prevent them from being deinitialized by this function.
7109
7110      *Since:* 3.0.0
7111
7112 gnutls_x509_trust_list_get_issuer
7113 ---------------------------------
7114
7115  -- Function: int gnutls_x509_trust_list_get_issuer
7116           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT,
7117           gnutls_x509_crt_t * ISSUER, unsigned int FLAGS)
7118      LIST: The list
7119
7120      CERT: is the certificate to find issuer for
7121
7122      ISSUER: Will hold the issuer if any.  Should be treated as
7123      constant.
7124
7125      FLAGS: Use zero or 'GNUTLS_TL_GET_COPY'
7126
7127      This function will find the issuer of the given certificate.  If
7128      the flag 'GNUTLS_TL_GET_COPY' is specified a copy of the issuer
7129      will be returned which must be freed using
7130      'gnutls_x509_crt_deinit()' .  Note that the flag
7131      'GNUTLS_TL_GET_COPY' is required for this function to work with
7132      PKCS '11' trust lists in a thread-safe way.
7133
7134      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7135      otherwise a negative error value.
7136
7137      *Since:* 3.0
7138
7139 gnutls_x509_trust_list_get_issuer_by_dn
7140 ---------------------------------------
7141
7142  -- Function: int gnutls_x509_trust_list_get_issuer_by_dn
7143           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * DN,
7144           gnutls_x509_crt_t * ISSUER, unsigned int FLAGS)
7145      LIST: The list
7146
7147      DN: is the issuer's DN
7148
7149      ISSUER: Will hold the issuer if any.  Should be deallocated after
7150      use.
7151
7152      FLAGS: Use zero
7153
7154      This function will find the issuer with the given name, and return
7155      a copy of the issuer, which must be freed using
7156      'gnutls_x509_crt_deinit()' .
7157
7158      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7159      otherwise a negative error value.
7160
7161      *Since:* 3.4.0
7162
7163 gnutls_x509_trust_list_get_issuer_by_subject_key_id
7164 ---------------------------------------------------
7165
7166  -- Function: int gnutls_x509_trust_list_get_issuer_by_subject_key_id
7167           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * DN,
7168           const gnutls_datum_t * SPKI, gnutls_x509_crt_t * ISSUER,
7169           unsigned int FLAGS)
7170      LIST: The list
7171
7172      DN: is the issuer's DN (may be 'NULL' )
7173
7174      SPKI: is the subject key ID
7175
7176      ISSUER: Will hold the issuer if any.  Should be deallocated after
7177      use.
7178
7179      FLAGS: Use zero
7180
7181      This function will find the issuer with the given name and subject
7182      key ID, and return a copy of the issuer, which must be freed using
7183      'gnutls_x509_crt_deinit()' .
7184
7185      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7186      otherwise a negative error value.
7187
7188      *Since:* 3.4.2
7189
7190 gnutls_x509_trust_list_init
7191 ---------------------------
7192
7193  -- Function: int gnutls_x509_trust_list_init (gnutls_x509_trust_list_t
7194           * LIST, unsigned int SIZE)
7195      LIST: A pointer to the type to be initialized
7196
7197      SIZE: The size of the internal hash table.  Use (0) for default
7198      size.
7199
7200      This function will initialize an X.509 trust list structure.
7201
7202      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7203      otherwise a negative error value.
7204
7205      *Since:* 3.0.0
7206
7207 gnutls_x509_trust_list_iter_deinit
7208 ----------------------------------
7209
7210  -- Function: void gnutls_x509_trust_list_iter_deinit
7211           (gnutls_x509_trust_list_iter_t ITER)
7212      ITER: The iterator structure to be deinitialized
7213
7214      This function will deinitialize an iterator structure.
7215
7216      *Since:* 3.4.0
7217
7218 gnutls_x509_trust_list_iter_get_ca
7219 ----------------------------------
7220
7221  -- Function: int gnutls_x509_trust_list_iter_get_ca
7222           (gnutls_x509_trust_list_t LIST, gnutls_x509_trust_list_iter_t
7223           * ITER, gnutls_x509_crt_t * CRT)
7224      LIST: The list
7225
7226      ITER: A pointer to an iterator (initially the iterator should be
7227      'NULL' )
7228
7229      CRT: where the certificate will be copied
7230
7231      This function obtains a certificate in the trust list and advances
7232      the iterator to the next certificate.  The certificate returned in
7233      'crt' must be deallocated with 'gnutls_x509_crt_deinit()' .
7234
7235      When past the last element is accessed
7236      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned and the
7237      iterator is reset.
7238
7239      After use, the iterator must be deinitialized usin
7240      'gnutls_x509_trust_list_iter_deinit()' .
7241
7242      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7243      otherwise a negative error value.
7244
7245      *Since:* 3.4.0
7246
7247 gnutls_x509_trust_list_remove_cas
7248 ---------------------------------
7249
7250  -- Function: int gnutls_x509_trust_list_remove_cas
7251           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
7252           CLIST, int CLIST_SIZE)
7253      LIST: The list
7254
7255      CLIST: A list of CAs
7256
7257      CLIST_SIZE: The length of the CA list
7258
7259      This function will remove the given certificate authorities from
7260      the trusted list.
7261
7262      Note that this function can accept certificates and authorities not
7263      yet known.  In that case they will be kept in a separate black list
7264      that will be used during certificate verification.  Unlike
7265      'gnutls_x509_trust_list_add_cas()' there is no deinitialization
7266      restriction for certificate list provided in this function.
7267
7268      *Returns:* The number of removed elements is returned.
7269
7270      *Since:* 3.1.10
7271
7272 gnutls_x509_trust_list_remove_trust_file
7273 ----------------------------------------
7274
7275  -- Function: int gnutls_x509_trust_list_remove_trust_file
7276           (gnutls_x509_trust_list_t LIST, const char * CA_FILE,
7277           gnutls_x509_crt_fmt_t TYPE)
7278      LIST: The list
7279
7280      CA_FILE: A file containing a list of CAs
7281
7282      TYPE: The format of the certificates
7283
7284      This function will remove the given certificate authorities from
7285      the trusted list, and add them into a black list when needed.  PKCS
7286      11 URLs are also accepted, instead of files, by this function.
7287
7288      See also 'gnutls_x509_trust_list_remove_cas()' .
7289
7290      *Returns:* The number of added elements is returned.
7291
7292      *Since:* 3.1.10
7293
7294 gnutls_x509_trust_list_remove_trust_mem
7295 ---------------------------------------
7296
7297  -- Function: int gnutls_x509_trust_list_remove_trust_mem
7298           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
7299           gnutls_x509_crt_fmt_t TYPE)
7300      LIST: The list
7301
7302      CAS: A buffer containing a list of CAs (optional)
7303
7304      TYPE: The format of the certificates
7305
7306      This function will remove the provided certificate authorities from
7307      the trusted list, and add them into a black list when needed.
7308
7309      See also 'gnutls_x509_trust_list_remove_cas()' .
7310
7311      *Returns:* The number of removed elements is returned.
7312
7313      *Since:* 3.1.10
7314
7315 gnutls_x509_trust_list_verify_crt
7316 ---------------------------------
7317
7318  -- Function: int gnutls_x509_trust_list_verify_crt
7319           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
7320           unsigned int CERT_LIST_SIZE, unsigned int FLAGS, unsigned int
7321           * VOUTPUT, gnutls_verify_output_function FUNC)
7322      LIST: The list
7323
7324      CERT_LIST: is the certificate list to be verified
7325
7326      CERT_LIST_SIZE: is the certificate list size
7327
7328      FLAGS: Flags that may be used to change the verification algorithm.
7329      Use OR of the gnutls_certificate_verify_flags enumerations.
7330
7331      VOUTPUT: will hold the certificate verification output.
7332
7333      FUNC: If non-null will be called on each chain element verification
7334      with the output.
7335
7336      This function will try to verify the given certificate and return
7337      its status.  The 'voutput' parameter will hold an OR'ed sequence of
7338      'gnutls_certificate_status_t' flags.
7339
7340      The details of the verification are the same as in
7341      'gnutls_x509_trust_list_verify_crt2()' .
7342
7343      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7344      otherwise a negative error value.
7345
7346      *Since:* 3.0
7347
7348 gnutls_x509_trust_list_verify_crt2
7349 ----------------------------------
7350
7351  -- Function: int gnutls_x509_trust_list_verify_crt2
7352           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
7353           unsigned int CERT_LIST_SIZE, gnutls_typed_vdata_st * DATA,
7354           unsigned int ELEMENTS, unsigned int FLAGS, unsigned int *
7355           VOUTPUT, gnutls_verify_output_function FUNC)
7356      LIST: The list
7357
7358      CERT_LIST: is the certificate list to be verified
7359
7360      CERT_LIST_SIZE: is the certificate list size
7361
7362      DATA: an array of typed data
7363
7364      ELEMENTS: the number of data elements
7365
7366      FLAGS: Flags that may be used to change the verification algorithm.
7367      Use OR of the gnutls_certificate_verify_flags enumerations.
7368
7369      VOUTPUT: will hold the certificate verification output.
7370
7371      FUNC: If non-null will be called on each chain element verification
7372      with the output.
7373
7374      This function will attempt to verify the given certificate and
7375      return its status.  The 'voutput' parameter will hold an OR'ed
7376      sequence of 'gnutls_certificate_status_t' flags.  When a chain of
7377      'cert_list_size' with more than one certificates is provided, the
7378      verification status will apply to the first certificate in the
7379      chain that failed verification.  The verification process starts
7380      from the end of the chain (from CA to end certificate).
7381
7382      Additionally a certificate verification profile can be specified
7383      from the ones in 'gnutls_certificate_verification_profiles_t' by
7384      ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
7385      verification flags.
7386
7387      The acceptable 'data' types are 'GNUTLS_DT_DNS_HOSTNAME' and
7388      'GNUTLS_DT_KEY_PURPOSE_OID' .  The former accepts as data a
7389      null-terminated hostname, and the latter a null-terminated object
7390      identifier (e.g., 'GNUTLS_KP_TLS_WWW_SERVER' ).  If a DNS hostname
7391      is provided then this function will compare the hostname in the
7392      certificate against the given.  If names do not match the
7393      'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.  In
7394      addition it will consider certificates provided with
7395      'gnutls_x509_trust_list_add_named_crt()' .
7396
7397      If a key purpose OID is provided and the end-certificate contains
7398      the extended key usage PKIX extension, it will be required to match
7399      the provided OID or be marked for any purpose, otherwise
7400      verification will fail with 'GNUTLS_CERT_PURPOSE_MISMATCH' status.
7401
7402      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7403      otherwise a negative error value.  Note that verification failure
7404      will not result to an error code, only 'voutput' will be updated.
7405
7406      *Since:* 3.3.8
7407
7408 gnutls_x509_trust_list_verify_named_crt
7409 ---------------------------------------
7410
7411  -- Function: int gnutls_x509_trust_list_verify_named_crt
7412           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
7413           void * NAME, size_t NAME_SIZE, unsigned int FLAGS, unsigned
7414           int * VOUTPUT, gnutls_verify_output_function FUNC)
7415      LIST: The list
7416
7417      CERT: is the certificate to be verified
7418
7419      NAME: is the certificate's name
7420
7421      NAME_SIZE: is the certificate's name size
7422
7423      FLAGS: Flags that may be used to change the verification algorithm.
7424      Use OR of the gnutls_certificate_verify_flags enumerations.
7425
7426      VOUTPUT: will hold the certificate verification output.
7427
7428      FUNC: If non-null will be called on each chain element verification
7429      with the output.
7430
7431      This function will try to find a certificate that is associated
7432      with the provided name -see
7433      'gnutls_x509_trust_list_add_named_crt()' .  If a match is found the
7434      certificate is considered valid.  In addition to that this function
7435      will also check CRLs.  The 'voutput' parameter will hold an OR'ed
7436      sequence of 'gnutls_certificate_status_t' flags.
7437
7438      Additionally a certificate verification profile can be specified
7439      from the ones in 'gnutls_certificate_verification_profiles_t' by
7440      ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
7441      verification flags.
7442
7443      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7444      otherwise a negative error value.
7445
7446      *Since:* 3.0.0
7447
7448 \1f
7449 File: gnutls.info,  Node: PKCS 7 API,  Next: OCSP API,  Prev: X509 certificate API,  Up: API reference
7450
7451 E.4 PKCS 7 API
7452 ==============
7453
7454 The following functions are to be used for PKCS 7 structures handling.
7455 Their prototypes lie in 'gnutls/pkcs7.h'.
7456
7457 gnutls_pkcs7_add_attr
7458 ---------------------
7459
7460  -- Function: int gnutls_pkcs7_add_attr (gnutls_pkcs7_attrs_t * LIST,
7461           const char * OID, gnutls_datum_t * DATA, unsigned FLAGS)
7462      LIST: A list of existing attributes or pointer to 'NULL' for the
7463      first one
7464
7465      OID: the OID of the attribute to be set
7466
7467      DATA: the raw (DER-encoded) data of the attribute to be set
7468
7469      FLAGS: zero or 'GNUTLS_PKCS7_ATTR_ENCODE_OCTET_STRING'
7470
7471      This function will set a PKCS '7' attribute in the provided list.
7472      If this function fails, the previous list would be deallocated.
7473
7474      Note that any attributes set with this function must either be DER
7475      or BER encoded, unless a special flag is present.
7476
7477      *Returns:* On success, the new list head, otherwise 'NULL' .
7478
7479      *Since:* 3.4.2
7480
7481 gnutls_pkcs7_attrs_deinit
7482 -------------------------
7483
7484  -- Function: void gnutls_pkcs7_attrs_deinit (gnutls_pkcs7_attrs_t LIST)
7485      LIST: A list of existing attributes
7486
7487      This function will clear a PKCS '7' attribute list.
7488
7489      *Since:* 3.4.2
7490
7491 gnutls_pkcs7_deinit
7492 -------------------
7493
7494  -- Function: void gnutls_pkcs7_deinit (gnutls_pkcs7_t PKCS7)
7495      PKCS7: the type to be deinitialized
7496
7497      This function will deinitialize a PKCS7 type.
7498
7499 gnutls_pkcs7_delete_crl
7500 -----------------------
7501
7502  -- Function: int gnutls_pkcs7_delete_crl (gnutls_pkcs7_t PKCS7, int
7503           INDX)
7504      PKCS7: The pkcs7 type
7505
7506      INDX: the index of the crl to delete
7507
7508      This function will delete a crl from a PKCS7 or RFC2630 crl set.
7509      Index starts from 0.  Returns 0 on success.
7510
7511      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7512      otherwise a negative error value.
7513
7514 gnutls_pkcs7_delete_crt
7515 -----------------------
7516
7517  -- Function: int gnutls_pkcs7_delete_crt (gnutls_pkcs7_t PKCS7, int
7518           INDX)
7519      PKCS7: The pkcs7 type
7520
7521      INDX: the index of the certificate to delete
7522
7523      This function will delete a certificate from a PKCS7 or RFC2630
7524      certificate set.  Index starts from 0.  Returns 0 on success.
7525
7526      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7527      otherwise a negative error value.
7528
7529 gnutls_pkcs7_export
7530 -------------------
7531
7532  -- Function: int gnutls_pkcs7_export (gnutls_pkcs7_t PKCS7,
7533           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
7534           OUTPUT_DATA_SIZE)
7535      PKCS7: The pkcs7 type
7536
7537      FORMAT: the format of output params.  One of PEM or DER.
7538
7539      OUTPUT_DATA: will contain a structure PEM or DER encoded
7540
7541      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
7542      replaced by the actual size of parameters)
7543
7544      This function will export the pkcs7 structure to DER or PEM format.
7545
7546      If the buffer provided is not long enough to hold the output, then
7547      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
7548      will be returned.
7549
7550      If the structure is PEM encoded, it will have a header of "BEGIN
7551      PKCS7".
7552
7553      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7554      otherwise a negative error value.
7555
7556 gnutls_pkcs7_export2
7557 --------------------
7558
7559  -- Function: int gnutls_pkcs7_export2 (gnutls_pkcs7_t PKCS7,
7560           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
7561      PKCS7: The pkcs7 type
7562
7563      FORMAT: the format of output params.  One of PEM or DER.
7564
7565      OUT: will contain a structure PEM or DER encoded
7566
7567      This function will export the pkcs7 structure to DER or PEM format.
7568
7569      The output buffer is allocated using 'gnutls_malloc()' .
7570
7571      If the structure is PEM encoded, it will have a header of "BEGIN
7572      PKCS7".
7573
7574      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7575      otherwise a negative error value.
7576
7577      *Since:* 3.1.3
7578
7579 gnutls_pkcs7_get_attr
7580 ---------------------
7581
7582  -- Function: int gnutls_pkcs7_get_attr (gnutls_pkcs7_attrs_t LIST,
7583           unsigned IDX, char ** OID, gnutls_datum_t * DATA, unsigned
7584           FLAGS)
7585      LIST: A list of existing attributes or 'NULL' for the first one
7586
7587      IDX: the index of the attribute to get
7588
7589      OID: the OID of the attribute (read-only)
7590
7591      DATA: the raw data of the attribute
7592
7593      FLAGS: zero or 'GNUTLS_PKCS7_ATTR_ENCODE_OCTET_STRING'
7594
7595      This function will get a PKCS '7' attribute from the provided list.
7596      The OID is a constant string, but data will be allocated and must
7597      be deinitialized by the caller.
7598
7599      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7600      otherwise a negative error value.
7601      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned if there are no
7602      data in the current index.
7603
7604      *Since:* 3.4.2
7605
7606 gnutls_pkcs7_get_crl_count
7607 --------------------------
7608
7609  -- Function: int gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t PKCS7)
7610      PKCS7: The pkcs7 type
7611
7612      This function will return the number of certificates in the PKCS7
7613      or RFC2630 crl set.
7614
7615      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7616      otherwise a negative error value.
7617
7618 gnutls_pkcs7_get_crl_raw
7619 ------------------------
7620
7621  -- Function: int gnutls_pkcs7_get_crl_raw (gnutls_pkcs7_t PKCS7, int
7622           INDX, void * CRL, size_t * CRL_SIZE)
7623      PKCS7: The pkcs7 type
7624
7625      INDX: contains the index of the crl to extract
7626
7627      CRL: the contents of the crl will be copied there (may be null)
7628
7629      CRL_SIZE: should hold the size of the crl
7630
7631      This function will return a crl of the PKCS7 or RFC2630 crl set.
7632
7633      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7634      otherwise a negative error value.  If the provided buffer is not
7635      long enough, then 'crl_size' is updated and
7636      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned.  After the last crl has
7637      been read 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7638
7639 gnutls_pkcs7_get_crl_raw2
7640 -------------------------
7641
7642  -- Function: int gnutls_pkcs7_get_crl_raw2 (gnutls_pkcs7_t PKCS7, int
7643           INDX, gnutls_datum_t * CRL)
7644      PKCS7: The pkcs7 type
7645
7646      INDX: contains the index of the crl to extract
7647
7648      CRL: will contain the contents of the CRL in an allocated buffer
7649
7650      This function will return a DER encoded CRL of the PKCS7 or RFC2630
7651      crl set.
7652
7653      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7654      otherwise a negative error value.  After the last crl has been read
7655      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7656
7657      *Since:* 3.4.2
7658
7659 gnutls_pkcs7_get_crt_count
7660 --------------------------
7661
7662  -- Function: int gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t PKCS7)
7663      PKCS7: should contain a 'gnutls_pkcs7_t' type
7664
7665      This function will return the number of certificates in the PKCS7
7666      or RFC2630 certificate set.
7667
7668      *Returns:* On success, a positive number is returned, otherwise a
7669      negative error value.
7670
7671 gnutls_pkcs7_get_crt_raw
7672 ------------------------
7673
7674  -- Function: int gnutls_pkcs7_get_crt_raw (gnutls_pkcs7_t PKCS7, int
7675           INDX, void * CERTIFICATE, size_t * CERTIFICATE_SIZE)
7676      PKCS7: should contain a gnutls_pkcs7_t type
7677
7678      INDX: contains the index of the certificate to extract
7679
7680      CERTIFICATE: the contents of the certificate will be copied there
7681      (may be null)
7682
7683      CERTIFICATE_SIZE: should hold the size of the certificate
7684
7685      This function will return a certificate of the PKCS7 or RFC2630
7686      certificate set.
7687
7688      After the last certificate has been read
7689      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7690
7691      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7692      otherwise a negative error value.  If the provided buffer is not
7693      long enough, then 'certificate_size' is updated and
7694      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned.
7695
7696 gnutls_pkcs7_get_crt_raw2
7697 -------------------------
7698
7699  -- Function: int gnutls_pkcs7_get_crt_raw2 (gnutls_pkcs7_t PKCS7, int
7700           INDX, gnutls_datum_t * CERT)
7701      PKCS7: should contain a gnutls_pkcs7_t type
7702
7703      INDX: contains the index of the certificate to extract
7704
7705      CERT: will hold the contents of the certificate; must be
7706      deallocated with 'gnutls_free()'
7707
7708      This function will return a certificate of the PKCS7 or RFC2630
7709      certificate set.
7710
7711      After the last certificate has been read
7712      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7713
7714      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7715      otherwise a negative error value.  If the provided buffer is not
7716      long enough, then 'certificate_size' is updated and
7717      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned.
7718
7719      *Since:* 3.4.2
7720
7721 gnutls_pkcs7_get_embedded_data
7722 ------------------------------
7723
7724  -- Function: int gnutls_pkcs7_get_embedded_data (gnutls_pkcs7_t PKCS7,
7725           unsigned IDX, gnutls_datum_t * DATA)
7726      PKCS7: should contain a gnutls_pkcs7_t type
7727
7728      IDX: the index of the signature info to get the data from
7729
7730      DATA: will hold the embedded data in the provided structure
7731
7732      This function will return the data embedded in the signature of the
7733      PKCS7 structure.  If no data are available then
7734      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7735
7736      Note, that since a PKCS'7' structure may contain embedded data for
7737      each attached signature, this function accepts and index which
7738      corresponds to the signature index to get the data from.
7739
7740      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7741      otherwise a negative error value.
7742
7743      *Since:* 3.4.8
7744
7745 gnutls_pkcs7_get_signature_count
7746 --------------------------------
7747
7748  -- Function: int gnutls_pkcs7_get_signature_count (gnutls_pkcs7_t
7749           PKCS7)
7750      PKCS7: should contain a 'gnutls_pkcs7_t' type
7751
7752      This function will return the number of signatures in the PKCS7
7753      structure.
7754
7755      *Returns:* On success, a positive number is returned, otherwise a
7756      negative error value.
7757
7758      *Since:* 3.4.3
7759
7760 gnutls_pkcs7_get_signature_info
7761 -------------------------------
7762
7763  -- Function: int gnutls_pkcs7_get_signature_info (gnutls_pkcs7_t PKCS7,
7764           unsigned IDX, gnutls_pkcs7_signature_info_st * INFO)
7765      PKCS7: should contain a 'gnutls_pkcs7_t' type
7766
7767      IDX: the index of the signature info to check
7768
7769      INFO: will contain the output signature
7770
7771      This function will return information about the signature
7772      identified by idx in the provided PKCS '7' structure.  The
7773      information should be deinitialized using
7774      'gnutls_pkcs7_signature_info_deinit()' .
7775
7776      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7777      otherwise a negative error value.
7778
7779      *Since:* 3.4.2
7780
7781 gnutls_pkcs7_import
7782 -------------------
7783
7784  -- Function: int gnutls_pkcs7_import (gnutls_pkcs7_t PKCS7, const
7785           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
7786      PKCS7: The data to store the parsed PKCS7.
7787
7788      DATA: The DER or PEM encoded PKCS7.
7789
7790      FORMAT: One of DER or PEM
7791
7792      This function will convert the given DER or PEM encoded PKCS7 to
7793      the native 'gnutls_pkcs7_t' format.  The output will be stored in
7794      'pkcs7' .
7795
7796      If the PKCS7 is PEM encoded it should have a header of "PKCS7".
7797
7798      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7799      otherwise a negative error value.
7800
7801 gnutls_pkcs7_init
7802 -----------------
7803
7804  -- Function: int gnutls_pkcs7_init (gnutls_pkcs7_t * PKCS7)
7805      PKCS7: A pointer to the type to be initialized
7806
7807      This function will initialize a PKCS7 structure.  PKCS7 structures
7808      usually contain lists of X.509 Certificates and X.509 Certificate
7809      revocation lists.
7810
7811      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7812      otherwise a negative error value.
7813
7814 gnutls_pkcs7_print
7815 ------------------
7816
7817  -- Function: int gnutls_pkcs7_print (gnutls_pkcs7_t PKCS7,
7818           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
7819           OUT)
7820      PKCS7: The PKCS7 struct to be printed
7821
7822      FORMAT: Indicate the format to use
7823
7824      OUT: Newly allocated datum with null terminated string.
7825
7826      This function will pretty print a signed PKCS '7' structure,
7827      suitable for display to a human.
7828
7829      Currently the supported formats are 'GNUTLS_CRT_PRINT_FULL' and
7830      'GNUTLS_CRT_PRINT_COMPACT' .
7831
7832      The output 'out' needs to be deallocated using 'gnutls_free()' .
7833
7834      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7835      otherwise a negative error value.
7836
7837 gnutls_pkcs7_set_crl
7838 --------------------
7839
7840  -- Function: int gnutls_pkcs7_set_crl (gnutls_pkcs7_t PKCS7,
7841           gnutls_x509_crl_t CRL)
7842      PKCS7: The pkcs7 type
7843
7844      CRL: the DER encoded crl to be added
7845
7846      This function will add a parsed CRL to the PKCS7 or RFC2630 crl
7847      set.
7848
7849      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7850      otherwise a negative error value.
7851
7852 gnutls_pkcs7_set_crl_raw
7853 ------------------------
7854
7855  -- Function: int gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t PKCS7, const
7856           gnutls_datum_t * CRL)
7857      PKCS7: The pkcs7 type
7858
7859      CRL: the DER encoded crl to be added
7860
7861      This function will add a crl to the PKCS7 or RFC2630 crl set.
7862
7863      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7864      otherwise a negative error value.
7865
7866 gnutls_pkcs7_set_crt
7867 --------------------
7868
7869  -- Function: int gnutls_pkcs7_set_crt (gnutls_pkcs7_t PKCS7,
7870           gnutls_x509_crt_t CRT)
7871      PKCS7: The pkcs7 type
7872
7873      CRT: the certificate to be copied.
7874
7875      This function will add a parsed certificate to the PKCS7 or RFC2630
7876      certificate set.  This is a wrapper function over
7877      'gnutls_pkcs7_set_crt_raw()' .
7878
7879      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7880      otherwise a negative error value.
7881
7882 gnutls_pkcs7_set_crt_raw
7883 ------------------------
7884
7885  -- Function: int gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t PKCS7, const
7886           gnutls_datum_t * CRT)
7887      PKCS7: The pkcs7 type
7888
7889      CRT: the DER encoded certificate to be added
7890
7891      This function will add a certificate to the PKCS7 or RFC2630
7892      certificate set.
7893
7894      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7895      otherwise a negative error value.
7896
7897 gnutls_pkcs7_sign
7898 -----------------
7899
7900  -- Function: int gnutls_pkcs7_sign (gnutls_pkcs7_t PKCS7,
7901           gnutls_x509_crt_t SIGNER, gnutls_privkey_t SIGNER_KEY, const
7902           gnutls_datum_t * DATA, gnutls_pkcs7_attrs_t SIGNED_ATTRS,
7903           gnutls_pkcs7_attrs_t UNSIGNED_ATTRS, gnutls_digest_algorithm_t
7904           DIG, unsigned FLAGS)
7905      PKCS7: should contain a 'gnutls_pkcs7_t' type
7906
7907      SIGNER: the certificate to sign the structure
7908
7909      SIGNER_KEY: the key to sign the structure
7910
7911      DATA: The data to be signed or 'NULL' if the data are already
7912      embedded
7913
7914      SIGNED_ATTRS: Any additional attributes to be included in the
7915      signed ones (or 'NULL' )
7916
7917      UNSIGNED_ATTRS: Any additional attributes to be included in the
7918      unsigned ones (or 'NULL' )
7919
7920      DIG: The digest algorithm to use for signing
7921
7922      FLAGS: Should be zero or one of 'GNUTLS_PKCS7' flags
7923
7924      This function will add a signature in the provided PKCS '7'
7925      structure for the provided data.  Multiple signatures can be made
7926      with different signers.
7927
7928      The available flags are: 'GNUTLS_PKCS7_EMBED_DATA' ,
7929      'GNUTLS_PKCS7_INCLUDE_TIME' , 'GNUTLS_PKCS7_INCLUDE_CERT' , and
7930      'GNUTLS_PKCS7_WRITE_SPKI' .  They are explained in the
7931      'gnutls_pkcs7_sign_flags' definition.
7932
7933      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7934      otherwise a negative error value.
7935
7936      *Since:* 3.4.2
7937
7938 gnutls_pkcs7_signature_info_deinit
7939 ----------------------------------
7940
7941  -- Function: void gnutls_pkcs7_signature_info_deinit
7942           (gnutls_pkcs7_signature_info_st * INFO)
7943      INFO: should point to a 'gnutls_pkcs7_signature_info_st' structure
7944
7945      This function will deinitialize any allocated value in the provided
7946      'gnutls_pkcs7_signature_info_st' .
7947
7948      *Since:* 3.4.2
7949
7950 gnutls_pkcs7_verify
7951 -------------------
7952
7953  -- Function: int gnutls_pkcs7_verify (gnutls_pkcs7_t PKCS7,
7954           gnutls_x509_trust_list_t TL, gnutls_typed_vdata_st * VDATA,
7955           unsigned int VDATA_SIZE, unsigned IDX, const gnutls_datum_t *
7956           DATA, unsigned FLAGS)
7957      PKCS7: should contain a 'gnutls_pkcs7_t' type
7958
7959      TL: A list of trusted certificates
7960
7961      VDATA: an array of typed data
7962
7963      VDATA_SIZE: the number of data elements
7964
7965      IDX: the index of the signature info to check
7966
7967      DATA: The data to be verified or 'NULL'
7968
7969      FLAGS: Zero or an OR list of 'gnutls_certificate_verify_flags'
7970
7971      This function will verify the provided data against the signature
7972      present in the SignedData of the PKCS '7' structure.  If the data
7973      provided are NULL then the data in the encapsulatedContent field
7974      will be used instead.
7975
7976      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7977      otherwise a negative error value.  A verification error results to
7978      a 'GNUTLS_E_PK_SIG_VERIFY_FAILED' and the lack of encapsulated data
7979      to verify to a 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .
7980
7981      *Since:* 3.4.2
7982
7983 gnutls_pkcs7_verify_direct
7984 --------------------------
7985
7986  -- Function: int gnutls_pkcs7_verify_direct (gnutls_pkcs7_t PKCS7,
7987           gnutls_x509_crt_t SIGNER, unsigned IDX, const gnutls_datum_t *
7988           DATA, unsigned FLAGS)
7989      PKCS7: should contain a 'gnutls_pkcs7_t' type
7990
7991      SIGNER: the certificate believed to have signed the structure
7992
7993      IDX: the index of the signature info to check
7994
7995      DATA: The data to be verified or 'NULL'
7996
7997      FLAGS: Zero or an OR list of 'gnutls_certificate_verify_flags'
7998
7999      This function will verify the provided data against the signature
8000      present in the SignedData of the PKCS '7' structure.  If the data
8001      provided are NULL then the data in the encapsulatedContent field
8002      will be used instead.
8003
8004      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8005      otherwise a negative error value.  A verification error results to
8006      a 'GNUTLS_E_PK_SIG_VERIFY_FAILED' and the lack of encapsulated data
8007      to verify to a 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .
8008
8009      *Since:* 3.4.2
8010
8011 \1f
8012 File: gnutls.info,  Node: OCSP API,  Next: OpenPGP API,  Prev: PKCS 7 API,  Up: API reference
8013
8014 E.5 OCSP API
8015 ============
8016
8017 The following functions are for OCSP certificate status checking.  Their
8018 prototypes lie in 'gnutls/ocsp.h'.
8019
8020 gnutls_ocsp_req_add_cert
8021 ------------------------
8022
8023  -- Function: int gnutls_ocsp_req_add_cert (gnutls_ocsp_req_t REQ,
8024           gnutls_digest_algorithm_t DIGEST, gnutls_x509_crt_t ISSUER,
8025           gnutls_x509_crt_t CERT)
8026      REQ: should contain a 'gnutls_ocsp_req_t' type
8027
8028      DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
8029
8030      ISSUER: issuer of 'subject' certificate
8031
8032      CERT: certificate to request status for
8033
8034      This function will add another request to the OCSP request for a
8035      particular certificate.  The issuer name hash, issuer key hash, and
8036      serial number fields is populated as follows.  The issuer name and
8037      the serial number is taken from 'cert' .  The issuer key is taken
8038      from 'issuer' .  The hashed values will be hashed using the
8039      'digest' algorithm, normally 'GNUTLS_DIG_SHA1' .
8040
8041      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8042      otherwise a negative error code is returned.
8043
8044 gnutls_ocsp_req_add_cert_id
8045 ---------------------------
8046
8047  -- Function: int gnutls_ocsp_req_add_cert_id (gnutls_ocsp_req_t REQ,
8048           gnutls_digest_algorithm_t DIGEST, const gnutls_datum_t *
8049           ISSUER_NAME_HASH, const gnutls_datum_t * ISSUER_KEY_HASH,
8050           const gnutls_datum_t * SERIAL_NUMBER)
8051      REQ: should contain a 'gnutls_ocsp_req_t' type
8052
8053      DIGEST: hash algorithm, a 'gnutls_digest_algorithm_t' value
8054
8055      ISSUER_NAME_HASH: hash of issuer's DN
8056
8057      ISSUER_KEY_HASH: hash of issuer's public key
8058
8059      SERIAL_NUMBER: serial number of certificate to check
8060
8061      This function will add another request to the OCSP request for a
8062      particular certificate having the issuer name hash of
8063      'issuer_name_hash' and issuer key hash of 'issuer_key_hash' (both
8064      hashed using 'digest' ) and serial number 'serial_number' .
8065
8066      The information needed corresponds to the CertID structure:
8067
8068      <informalexample><programlisting> CertID ::= SEQUENCE {
8069      hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, -
8070      Hash of Issuer's DN issuerKeyHash OCTET STRING, - Hash of Issuers
8071      public key serialNumber CertificateSerialNumber }
8072      </programlisting></informalexample>
8073
8074      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8075      otherwise a negative error code is returned.
8076
8077 gnutls_ocsp_req_deinit
8078 ----------------------
8079
8080  -- Function: void gnutls_ocsp_req_deinit (gnutls_ocsp_req_t REQ)
8081      REQ: The data to be deinitialized
8082
8083      This function will deinitialize a OCSP request structure.
8084
8085 gnutls_ocsp_req_export
8086 ----------------------
8087
8088  -- Function: int gnutls_ocsp_req_export (gnutls_ocsp_req_t REQ,
8089           gnutls_datum_t * DATA)
8090      REQ: Holds the OCSP request
8091
8092      DATA: newly allocate buffer holding DER encoded OCSP request
8093
8094      This function will export the OCSP request to DER format.
8095
8096      *Returns:* In case of failure a negative error code will be
8097      returned, and 0 on success.
8098
8099 gnutls_ocsp_req_get_cert_id
8100 ---------------------------
8101
8102  -- Function: int gnutls_ocsp_req_get_cert_id (gnutls_ocsp_req_t REQ,
8103           unsigned INDX, gnutls_digest_algorithm_t * DIGEST,
8104           gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t *
8105           ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER)
8106      REQ: should contain a 'gnutls_ocsp_req_t' type
8107
8108      INDX: Specifies which extension OID to get.  Use (0) to get the
8109      first one.
8110
8111      DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
8112      algorithm
8113
8114      ISSUER_NAME_HASH: output buffer with hash of issuer's DN
8115
8116      ISSUER_KEY_HASH: output buffer with hash of issuer's public key
8117
8118      SERIAL_NUMBER: output buffer with serial number of certificate to
8119      check
8120
8121      This function will return the certificate information of the 'indx'
8122      'ed request in the OCSP request.  The information returned
8123      corresponds to the CertID structure:
8124
8125      <informalexample><programlisting> CertID ::= SEQUENCE {
8126      hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, -
8127      Hash of Issuer's DN issuerKeyHash OCTET STRING, - Hash of Issuers
8128      public key serialNumber CertificateSerialNumber }
8129      </programlisting></informalexample>
8130
8131      Each of the pointers to output variables may be NULL to indicate
8132      that the caller is not interested in that value.
8133
8134      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8135      otherwise a negative error code is returned.  If you have reached
8136      the last CertID available 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE'
8137      will be returned.
8138
8139 gnutls_ocsp_req_get_extension
8140 -----------------------------
8141
8142  -- Function: int gnutls_ocsp_req_get_extension (gnutls_ocsp_req_t REQ,
8143           unsigned INDX, gnutls_datum_t * OID, unsigned int * CRITICAL,
8144           gnutls_datum_t * DATA)
8145      REQ: should contain a 'gnutls_ocsp_req_t' type
8146
8147      INDX: Specifies which extension OID to get.  Use (0) to get the
8148      first one.
8149
8150      OID: will hold newly allocated buffer with OID of extension, may be
8151      NULL
8152
8153      CRITICAL: output variable with critical flag, may be NULL.
8154
8155      DATA: will hold newly allocated buffer with extension data, may be
8156      NULL
8157
8158      This function will return all information about the requested
8159      extension in the OCSP request.  The information returned is the
8160      OID, the critical flag, and the data itself.  The extension OID
8161      will be stored as a string.  Any of 'oid' , 'critical' , and 'data'
8162      may be NULL which means that the caller is not interested in
8163      getting that information back.
8164
8165      The caller needs to deallocate memory by calling 'gnutls_free()' on
8166      'oid' ->data and 'data' ->data.
8167
8168      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8169      otherwise a negative error code is returned.  If you have reached
8170      the last extension available
8171      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8172
8173 gnutls_ocsp_req_get_nonce
8174 -------------------------
8175
8176  -- Function: int gnutls_ocsp_req_get_nonce (gnutls_ocsp_req_t REQ,
8177           unsigned int * CRITICAL, gnutls_datum_t * NONCE)
8178      REQ: should contain a 'gnutls_ocsp_req_t' type
8179
8180      CRITICAL: whether nonce extension is marked critical, or NULL
8181
8182      NONCE: will hold newly allocated buffer with nonce data
8183
8184      This function will return the OCSP request nonce extension data.
8185
8186      The caller needs to deallocate memory by calling 'gnutls_free()' on
8187      'nonce' ->data.
8188
8189      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8190      otherwise a negative error code is returned.
8191
8192 gnutls_ocsp_req_get_version
8193 ---------------------------
8194
8195  -- Function: int gnutls_ocsp_req_get_version (gnutls_ocsp_req_t REQ)
8196      REQ: should contain a 'gnutls_ocsp_req_t' type
8197
8198      This function will return the version of the OCSP request.
8199      Typically this is always 1 indicating version 1.
8200
8201      *Returns:* version of OCSP request, or a negative error code on
8202      error.
8203
8204 gnutls_ocsp_req_import
8205 ----------------------
8206
8207  -- Function: int gnutls_ocsp_req_import (gnutls_ocsp_req_t REQ, const
8208           gnutls_datum_t * DATA)
8209      REQ: The data to store the parsed request.
8210
8211      DATA: DER encoded OCSP request.
8212
8213      This function will convert the given DER encoded OCSP request to
8214      the native 'gnutls_ocsp_req_t' format.  The output will be stored
8215      in 'req' .
8216
8217      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8218      otherwise a negative error value.
8219
8220 gnutls_ocsp_req_init
8221 --------------------
8222
8223  -- Function: int gnutls_ocsp_req_init (gnutls_ocsp_req_t * REQ)
8224      REQ: A pointer to the type to be initialized
8225
8226      This function will initialize an OCSP request structure.
8227
8228      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8229      otherwise a negative error value.
8230
8231 gnutls_ocsp_req_print
8232 ---------------------
8233
8234  -- Function: int gnutls_ocsp_req_print (gnutls_ocsp_req_t REQ,
8235           gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)
8236      REQ: The data to be printed
8237
8238      FORMAT: Indicate the format to use
8239
8240      OUT: Newly allocated datum with (0) terminated string.
8241
8242      This function will pretty print a OCSP request, suitable for
8243      display to a human.
8244
8245      If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
8246      request will be output, on multiple lines.
8247
8248      The output 'out' ->data needs to be deallocate using
8249      'gnutls_free()' .
8250
8251      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8252      otherwise a negative error value.
8253
8254 gnutls_ocsp_req_randomize_nonce
8255 -------------------------------
8256
8257  -- Function: int gnutls_ocsp_req_randomize_nonce (gnutls_ocsp_req_t
8258           REQ)
8259      REQ: should contain a 'gnutls_ocsp_req_t' type
8260
8261      This function will add or update an nonce extension to the OCSP
8262      request with a newly generated random value.
8263
8264      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8265      otherwise a negative error code is returned.
8266
8267 gnutls_ocsp_req_set_extension
8268 -----------------------------
8269
8270  -- Function: int gnutls_ocsp_req_set_extension (gnutls_ocsp_req_t REQ,
8271           const char * OID, unsigned int CRITICAL, const gnutls_datum_t
8272           * DATA)
8273      REQ: should contain a 'gnutls_ocsp_req_t' type
8274
8275      OID: buffer with OID of extension as a string.
8276
8277      CRITICAL: critical flag, normally false.
8278
8279      DATA: the extension data
8280
8281      This function will add an extension to the OCSP request.  Calling
8282      this function multiple times for the same OID will overwrite values
8283      from earlier calls.
8284
8285      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8286      otherwise a negative error code is returned.
8287
8288 gnutls_ocsp_req_set_nonce
8289 -------------------------
8290
8291  -- Function: int gnutls_ocsp_req_set_nonce (gnutls_ocsp_req_t REQ,
8292           unsigned int CRITICAL, const gnutls_datum_t * NONCE)
8293      REQ: should contain a 'gnutls_ocsp_req_t' type
8294
8295      CRITICAL: critical flag, normally false.
8296
8297      NONCE: the nonce data
8298
8299      This function will add an nonce extension to the OCSP request.
8300      Calling this function multiple times will overwrite values from
8301      earlier calls.
8302
8303      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8304      otherwise a negative error code is returned.
8305
8306 gnutls_ocsp_resp_check_crt
8307 --------------------------
8308
8309  -- Function: int gnutls_ocsp_resp_check_crt (gnutls_ocsp_resp_t RESP,
8310           unsigned int INDX, gnutls_x509_crt_t CRT)
8311      RESP: should contain a 'gnutls_ocsp_resp_t' type
8312
8313      INDX: Specifies response number to get.  Use (0) to get the first
8314      one.
8315
8316      CRT: The certificate to check
8317
8318      This function will check whether the OCSP response is about the
8319      provided certificate.
8320
8321      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8322      otherwise a negative error code is returned.
8323
8324      *Since:* 3.1.3
8325
8326 gnutls_ocsp_resp_deinit
8327 -----------------------
8328
8329  -- Function: void gnutls_ocsp_resp_deinit (gnutls_ocsp_resp_t RESP)
8330      RESP: The data to be deinitialized
8331
8332      This function will deinitialize a OCSP response structure.
8333
8334 gnutls_ocsp_resp_export
8335 -----------------------
8336
8337  -- Function: int gnutls_ocsp_resp_export (gnutls_ocsp_resp_t RESP,
8338           gnutls_datum_t * DATA)
8339      RESP: Holds the OCSP response
8340
8341      DATA: newly allocate buffer holding DER encoded OCSP response
8342
8343      This function will export the OCSP response to DER format.
8344
8345      *Returns:* In case of failure a negative error code will be
8346      returned, and 0 on success.
8347
8348 gnutls_ocsp_resp_get_certs
8349 --------------------------
8350
8351  -- Function: int gnutls_ocsp_resp_get_certs (gnutls_ocsp_resp_t RESP,
8352           gnutls_x509_crt_t ** CERTS, size_t * NCERTS)
8353      RESP: should contain a 'gnutls_ocsp_resp_t' type
8354
8355      CERTS: newly allocated array with 'gnutls_x509_crt_t' certificates
8356
8357      NCERTS: output variable with number of allocated certs.
8358
8359      This function will extract the X.509 certificates found in the
8360      Basic OCSP Response.  The 'certs' output variable will hold a newly
8361      allocated zero-terminated array with X.509 certificates.
8362
8363      Every certificate in the array needs to be de-allocated with
8364      'gnutls_x509_crt_deinit()' and the array itself must be freed using
8365      'gnutls_free()' .
8366
8367      Both the 'certs' and 'ncerts' variables may be NULL. Then the
8368      function will work as normal but will not return the NULL:d
8369      information.  This can be used to get the number of certificates
8370      only, or to just get the certificate array without its size.
8371
8372      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8373      otherwise a negative error value.
8374
8375 gnutls_ocsp_resp_get_extension
8376 ------------------------------
8377
8378  -- Function: int gnutls_ocsp_resp_get_extension (gnutls_ocsp_resp_t
8379           RESP, unsigned INDX, gnutls_datum_t * OID, unsigned int *
8380           CRITICAL, gnutls_datum_t * DATA)
8381      RESP: should contain a 'gnutls_ocsp_resp_t' type
8382
8383      INDX: Specifies which extension OID to get.  Use (0) to get the
8384      first one.
8385
8386      OID: will hold newly allocated buffer with OID of extension, may be
8387      NULL
8388
8389      CRITICAL: output variable with critical flag, may be NULL.
8390
8391      DATA: will hold newly allocated buffer with extension data, may be
8392      NULL
8393
8394      This function will return all information about the requested
8395      extension in the OCSP response.  The information returned is the
8396      OID, the critical flag, and the data itself.  The extension OID
8397      will be stored as a string.  Any of 'oid' , 'critical' , and 'data'
8398      may be NULL which means that the caller is not interested in
8399      getting that information back.
8400
8401      The caller needs to deallocate memory by calling 'gnutls_free()' on
8402      'oid' ->data and 'data' ->data.
8403
8404      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8405      otherwise a negative error code is returned.  If you have reached
8406      the last extension available
8407      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8408
8409 gnutls_ocsp_resp_get_nonce
8410 --------------------------
8411
8412  -- Function: int gnutls_ocsp_resp_get_nonce (gnutls_ocsp_resp_t RESP,
8413           unsigned int * CRITICAL, gnutls_datum_t * NONCE)
8414      RESP: should contain a 'gnutls_ocsp_resp_t' type
8415
8416      CRITICAL: whether nonce extension is marked critical
8417
8418      NONCE: will hold newly allocated buffer with nonce data
8419
8420      This function will return the Basic OCSP Response nonce extension
8421      data.
8422
8423      The caller needs to deallocate memory by calling 'gnutls_free()' on
8424      'nonce' ->data.
8425
8426      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8427      otherwise a negative error code is returned.
8428
8429 gnutls_ocsp_resp_get_produced
8430 -----------------------------
8431
8432  -- Function: time_t gnutls_ocsp_resp_get_produced (gnutls_ocsp_resp_t
8433           RESP)
8434      RESP: should contain a 'gnutls_ocsp_resp_t' type
8435
8436      This function will return the time when the OCSP response was
8437      signed.
8438
8439      *Returns:* signing time, or (time_t)-1 on error.
8440
8441 gnutls_ocsp_resp_get_responder
8442 ------------------------------
8443
8444  -- Function: int gnutls_ocsp_resp_get_responder (gnutls_ocsp_resp_t
8445           RESP, gnutls_datum_t * DN)
8446      RESP: should contain a 'gnutls_ocsp_resp_t' type
8447
8448      DN: newly allocated buffer with name
8449
8450      This function will extract the name of the Basic OCSP Response in
8451      the provided buffer.  The name will be in the form
8452      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253.  The output string
8453      will be ASCII or UTF-8 encoded, depending on the certificate data.
8454
8455      If the responder ID is not a name but a hash, this function will
8456      return zero and the 'dn' elements will be set to 'NULL' .
8457
8458      The caller needs to deallocate memory by calling 'gnutls_free()' on
8459      'dn' ->data.
8460
8461      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8462      otherwise a negative error code is returned.
8463
8464 gnutls_ocsp_resp_get_responder_raw_id
8465 -------------------------------------
8466
8467  -- Function: int gnutls_ocsp_resp_get_responder_raw_id
8468           (gnutls_ocsp_resp_t RESP, unsigned TYPE, gnutls_datum_t * RAW)
8469      RESP: should contain a 'gnutls_ocsp_resp_t' type
8470
8471      TYPE: should be 'GNUTLS_OCSP_RESP_ID_KEY' or
8472      'GNUTLS_OCSP_RESP_ID_DN'
8473
8474      RAW: newly allocated buffer with the raw ID
8475
8476      This function will extract the raw key (or DN) ID of the Basic OCSP
8477      Response in the provided buffer.  If the responder ID is not a key
8478      ID then this function will return
8479      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .
8480
8481      The caller needs to deallocate memory by calling 'gnutls_free()' on
8482      'dn' ->data.
8483
8484      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8485      otherwise a negative error code is returned.
8486
8487 gnutls_ocsp_resp_get_response
8488 -----------------------------
8489
8490  -- Function: int gnutls_ocsp_resp_get_response (gnutls_ocsp_resp_t
8491           RESP, gnutls_datum_t * RESPONSE_TYPE_OID, gnutls_datum_t *
8492           RESPONSE)
8493      RESP: should contain a 'gnutls_ocsp_resp_t' type
8494
8495      RESPONSE_TYPE_OID: newly allocated output buffer with response type
8496      OID
8497
8498      RESPONSE: newly allocated output buffer with DER encoded response
8499
8500      This function will extract the response type OID in and the
8501      response data from an OCSP response.  Normally the
8502      'response_type_oid' is always "1.3.6.1.5.5.7.48.1.1" which means
8503      the 'response' should be decoded as a Basic OCSP Response, but
8504      technically other response types could be used.
8505
8506      This function is typically only useful when you want to extract the
8507      response type OID of an response for diagnostic purposes.
8508      Otherwise 'gnutls_ocsp_resp_import()' will decode the basic OCSP
8509      response part and the caller need not worry about that aspect.
8510
8511      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8512      otherwise a negative error value.
8513
8514 gnutls_ocsp_resp_get_signature
8515 ------------------------------
8516
8517  -- Function: int gnutls_ocsp_resp_get_signature (gnutls_ocsp_resp_t
8518           RESP, gnutls_datum_t * SIG)
8519      RESP: should contain a 'gnutls_ocsp_resp_t' type
8520
8521      SIG: newly allocated output buffer with signature data
8522
8523      This function will extract the signature field of a OCSP response.
8524
8525      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8526      otherwise a negative error value.
8527
8528 gnutls_ocsp_resp_get_signature_algorithm
8529 ----------------------------------------
8530
8531  -- Function: int gnutls_ocsp_resp_get_signature_algorithm
8532           (gnutls_ocsp_resp_t RESP)
8533      RESP: should contain a 'gnutls_ocsp_resp_t' type
8534
8535      This function will return a value of the 'gnutls_sign_algorithm_t'
8536      enumeration that is the signature algorithm that has been used to
8537      sign the OCSP response.
8538
8539      *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
8540      code on error.
8541
8542 gnutls_ocsp_resp_get_single
8543 ---------------------------
8544
8545  -- Function: int gnutls_ocsp_resp_get_single (gnutls_ocsp_resp_t RESP,
8546           unsigned INDX, gnutls_digest_algorithm_t * DIGEST,
8547           gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t *
8548           ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER, unsigned int
8549           * CERT_STATUS, time_t * THIS_UPDATE, time_t * NEXT_UPDATE,
8550           time_t * REVOCATION_TIME, unsigned int * REVOCATION_REASON)
8551      RESP: should contain a 'gnutls_ocsp_resp_t' type
8552
8553      INDX: Specifies response number to get.  Use (0) to get the first
8554      one.
8555
8556      DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
8557      algorithm
8558
8559      ISSUER_NAME_HASH: output buffer with hash of issuer's DN
8560
8561      ISSUER_KEY_HASH: output buffer with hash of issuer's public key
8562
8563      SERIAL_NUMBER: output buffer with serial number of certificate to
8564      check
8565
8566      CERT_STATUS: a certificate status, a 'gnutls_ocsp_cert_status_t'
8567      enum.
8568
8569      THIS_UPDATE: time at which the status is known to be correct.
8570
8571      NEXT_UPDATE: when newer information will be available, or
8572      (time_t)-1 if unspecified
8573
8574      REVOCATION_TIME: when 'cert_status' is 'GNUTLS_OCSP_CERT_REVOKED' ,
8575      holds time of revocation.
8576
8577      REVOCATION_REASON: revocation reason, a 'gnutls_x509_crl_reason_t'
8578      enum.
8579
8580      This function will return the certificate information of the 'indx'
8581      'ed response in the Basic OCSP Response 'resp' .  The information
8582      returned corresponds to the OCSP SingleResponse structure except
8583      the final singleExtensions.
8584
8585      Each of the pointers to output variables may be NULL to indicate
8586      that the caller is not interested in that value.
8587
8588      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8589      otherwise a negative error code is returned.  If you have reached
8590      the last CertID available 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE'
8591      will be returned.
8592
8593 gnutls_ocsp_resp_get_status
8594 ---------------------------
8595
8596  -- Function: int gnutls_ocsp_resp_get_status (gnutls_ocsp_resp_t RESP)
8597      RESP: should contain a 'gnutls_ocsp_resp_t' type
8598
8599      This function will return the status of a OCSP response, an
8600      'gnutls_ocsp_resp_status_t' enumeration.
8601
8602      *Returns:* status of OCSP request as a 'gnutls_ocsp_resp_status_t'
8603      , or a negative error code on error.
8604
8605 gnutls_ocsp_resp_get_version
8606 ----------------------------
8607
8608  -- Function: int gnutls_ocsp_resp_get_version (gnutls_ocsp_resp_t RESP)
8609      RESP: should contain a 'gnutls_ocsp_resp_t' type
8610
8611      This function will return the version of the Basic OCSP Response.
8612      Typically this is always 1 indicating version 1.
8613
8614      *Returns:* version of Basic OCSP response, or a negative error code
8615      on error.
8616
8617 gnutls_ocsp_resp_import
8618 -----------------------
8619
8620  -- Function: int gnutls_ocsp_resp_import (gnutls_ocsp_resp_t RESP,
8621           const gnutls_datum_t * DATA)
8622      RESP: The data to store the parsed response.
8623
8624      DATA: DER encoded OCSP response.
8625
8626      This function will convert the given DER encoded OCSP response to
8627      the native 'gnutls_ocsp_resp_t' format.  It also decodes the Basic
8628      OCSP Response part, if any.  The output will be stored in 'resp' .
8629
8630      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8631      otherwise a negative error value.
8632
8633 gnutls_ocsp_resp_init
8634 ---------------------
8635
8636  -- Function: int gnutls_ocsp_resp_init (gnutls_ocsp_resp_t * RESP)
8637      RESP: A pointer to the type to be initialized
8638
8639      This function will initialize an OCSP response structure.
8640
8641      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8642      otherwise a negative error value.
8643
8644 gnutls_ocsp_resp_print
8645 ----------------------
8646
8647  -- Function: int gnutls_ocsp_resp_print (gnutls_ocsp_resp_t RESP,
8648           gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)
8649      RESP: The data to be printed
8650
8651      FORMAT: Indicate the format to use
8652
8653      OUT: Newly allocated datum with (0) terminated string.
8654
8655      This function will pretty print a OCSP response, suitable for
8656      display to a human.
8657
8658      If the format is 'GNUTLS_OCSP_PRINT_FULL' then all fields of the
8659      response will be output, on multiple lines.
8660
8661      The output 'out' ->data needs to be deallocate using
8662      'gnutls_free()' .
8663
8664      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8665      otherwise a negative error value.
8666
8667 gnutls_ocsp_resp_verify
8668 -----------------------
8669
8670  -- Function: int gnutls_ocsp_resp_verify (gnutls_ocsp_resp_t RESP,
8671           gnutls_x509_trust_list_t TRUSTLIST, unsigned int * VERIFY,
8672           unsigned int FLAGS)
8673      RESP: should contain a 'gnutls_ocsp_resp_t' type
8674
8675      TRUSTLIST: trust anchors as a 'gnutls_x509_trust_list_t' type
8676
8677      VERIFY: output variable with verification status, an
8678      'gnutls_ocsp_verify_reason_t'
8679
8680      FLAGS: verification flags, 0 for now.
8681
8682      Verify signature of the Basic OCSP Response against the public key
8683      in the certificate of a trusted signer.  The 'trustlist' should be
8684      populated with trust anchors.  The function will extract the signer
8685      certificate from the Basic OCSP Response and will verify it against
8686      the 'trustlist' .  A trusted signer is a certificate that is either
8687      in 'trustlist' , or it is signed directly by a certificate in
8688      'trustlist' and has the id-ad-ocspSigning Extended Key Usage bit
8689      set.
8690
8691      The output 'verify' variable will hold verification status codes
8692      (e.g., 'GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND' ,
8693      'GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM' ) which are only valid if
8694      the function returned 'GNUTLS_E_SUCCESS' .
8695
8696      Note that the function returns 'GNUTLS_E_SUCCESS' even when
8697      verification failed.  The caller must always inspect the 'verify'
8698      variable to find out the verification status.
8699
8700      The 'flags' variable should be 0 for now.
8701
8702      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8703      otherwise a negative error value.
8704
8705 gnutls_ocsp_resp_verify_direct
8706 ------------------------------
8707
8708  -- Function: int gnutls_ocsp_resp_verify_direct (gnutls_ocsp_resp_t
8709           RESP, gnutls_x509_crt_t ISSUER, unsigned int * VERIFY,
8710           unsigned int FLAGS)
8711      RESP: should contain a 'gnutls_ocsp_resp_t' type
8712
8713      ISSUER: certificate believed to have signed the response
8714
8715      VERIFY: output variable with verification status, an
8716      'gnutls_ocsp_verify_reason_t'
8717
8718      FLAGS: verification flags, 0 for now.
8719
8720      Verify signature of the Basic OCSP Response against the public key
8721      in the 'issuer' certificate.
8722
8723      The output 'verify' variable will hold verification status codes
8724      (e.g., 'GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND' ,
8725      'GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM' ) which are only valid if
8726      the function returned 'GNUTLS_E_SUCCESS' .
8727
8728      Note that the function returns 'GNUTLS_E_SUCCESS' even when
8729      verification failed.  The caller must always inspect the 'verify'
8730      variable to find out the verification status.
8731
8732      The 'flags' variable should be 0 for now.
8733
8734      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8735      otherwise a negative error value.
8736