doc/gnutls.info-3

   1 This is gnutls.info, produced by makeinfo version 6.3 from gnutls.texi.
   2
   3 This manual is last updated 23 March 2015 for version 3.3.27 of GnuTLS.
   4
   5 Copyright (C) 2001-2013 Free Software Foundation, Inc.\\ Copyright (C)
   6 2001-2013 Nikos Mavrogiannopoulos
   7
   8      Permission is granted to copy, distribute and/or modify this
   9      document under the terms of the GNU Free Documentation License,
  10      Version 1.3 or any later version published by the Free Software
  11      Foundation; with no Invariant Sections, no Front-Cover Texts, and
  12      no Back-Cover Texts.  A copy of the license is included in the
  13      section entitled "GNU Free Documentation License".
  14 INFO-DIR-SECTION Software libraries
  15 START-INFO-DIR-ENTRY
  16 * GnuTLS: (gnutls).             GNU Transport Layer Security Library.
  17 END-INFO-DIR-ENTRY
  18
  19 INFO-DIR-SECTION System Administration
  20 START-INFO-DIR-ENTRY
  21 * certtool: (gnutls)Invoking certtool.  Manipulate certificates and keys.
  22 * gnutls-serv: (gnutls)Invoking gnutls-serv.    GnuTLS test server.
  23 * gnutls-cli: (gnutls)Invoking gnutls-cli.      GnuTLS test client.
  24 * gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug.  GnuTLS debug client.
  25 * psktool: (gnutls)Invoking psktool.    Simple TLS-Pre-Shared-Keys manager.
  26 * srptool: (gnutls)Invoking srptool.    Simple SRP password tool.
  27 END-INFO-DIR-ENTRY
  28
  29 \1f
  30 File: gnutls.info,  Node: Supported ciphersuites,  Next: API reference,  Prev: Error codes,  Up: Top
  31
  32 Appendix D Supported Ciphersuites
  33 *********************************
  34
  35 Ciphersuites
  36 ============
  37
  38 Ciphersuite name                            TLS ID         Since
  39 --------------------------------------------------------------------------
  40 TLS_RSA_NULL_MD5                            0x00 0x01      SSL3.0
  41 TLS_RSA_NULL_SHA1                           0x00 0x02      SSL3.0
  42 TLS_RSA_NULL_SHA256                         0x00 0x3B      TLS1.2
  43 TLS_RSA_ARCFOUR_128_SHA1                    0x00 0x05      SSL3.0
  44 TLS_RSA_ARCFOUR_128_MD5                     0x00 0x04      SSL3.0
  45 TLS_RSA_3DES_EDE_CBC_SHA1                   0x00 0x0A      SSL3.0
  46 TLS_RSA_AES_128_CBC_SHA1                    0x00 0x2F      SSL3.0
  47 TLS_RSA_AES_256_CBC_SHA1                    0x00 0x35      SSL3.0
  48 TLS_RSA_CAMELLIA_128_CBC_SHA256             0x00 0xBA      TLS1.2
  49 TLS_RSA_CAMELLIA_256_CBC_SHA256             0x00 0xC0      TLS1.2
  50 TLS_RSA_CAMELLIA_128_CBC_SHA1               0x00 0x41      SSL3.0
  51 TLS_RSA_CAMELLIA_256_CBC_SHA1               0x00 0x84      SSL3.0
  52 TLS_RSA_AES_128_CBC_SHA256                  0x00 0x3C      TLS1.2
  53 TLS_RSA_AES_256_CBC_SHA256                  0x00 0x3D      TLS1.2
  54 TLS_RSA_AES_128_GCM_SHA256                  0x00 0x9C      TLS1.2
  55 TLS_RSA_AES_256_GCM_SHA384                  0x00 0x9D      TLS1.2
  56 TLS_RSA_CAMELLIA_128_GCM_SHA256             0xC0 0x7A      TLS1.2
  57 TLS_RSA_CAMELLIA_256_GCM_SHA384             0xC0 0x7B      TLS1.2
  58 TLS_RSA_SALSA20_256_SHA1                    0xE4 0x11      SSL3.0
  59 TLS_RSA_ESTREAM_SALSA20_256_SHA1            0xE4 0x10      SSL3.0
  60 TLS_DHE_DSS_ARCFOUR_128_SHA1                0x00 0x66      SSL3.0
  61 TLS_DHE_DSS_3DES_EDE_CBC_SHA1               0x00 0x13      SSL3.0
  62 TLS_DHE_DSS_AES_128_CBC_SHA1                0x00 0x32      SSL3.0
  63 TLS_DHE_DSS_AES_256_CBC_SHA1                0x00 0x38      SSL3.0
  64 TLS_DHE_DSS_CAMELLIA_128_CBC_SHA256         0x00 0xBD      TLS1.2
  65 TLS_DHE_DSS_CAMELLIA_256_CBC_SHA256         0x00 0xC3      TLS1.2
  66 TLS_DHE_DSS_CAMELLIA_128_CBC_SHA1           0x00 0x44      SSL3.0
  67 TLS_DHE_DSS_CAMELLIA_256_CBC_SHA1           0x00 0x87      SSL3.0
  68 TLS_DHE_DSS_AES_128_CBC_SHA256              0x00 0x40      TLS1.2
  69 TLS_DHE_DSS_AES_256_CBC_SHA256              0x00 0x6A      TLS1.2
  70 TLS_DHE_DSS_AES_128_GCM_SHA256              0x00 0xA2      TLS1.2
  71 TLS_DHE_DSS_AES_256_GCM_SHA384              0x00 0xA3      TLS1.2
  72 TLS_DHE_DSS_CAMELLIA_128_GCM_SHA256         0xC0 0x80      TLS1.2
  73 TLS_DHE_DSS_CAMELLIA_256_GCM_SHA384         0xC0 0x81      TLS1.2
  74 TLS_DHE_RSA_3DES_EDE_CBC_SHA1               0x00 0x16      SSL3.0
  75 TLS_DHE_RSA_AES_128_CBC_SHA1                0x00 0x33      SSL3.0
  76 TLS_DHE_RSA_AES_256_CBC_SHA1                0x00 0x39      SSL3.0
  77 TLS_DHE_RSA_CAMELLIA_128_CBC_SHA256         0x00 0xBE      TLS1.2
  78 TLS_DHE_RSA_CAMELLIA_256_CBC_SHA256         0x00 0xC4      TLS1.2
  79 TLS_DHE_RSA_CAMELLIA_128_CBC_SHA1           0x00 0x45      SSL3.0
  80 TLS_DHE_RSA_CAMELLIA_256_CBC_SHA1           0x00 0x88      SSL3.0
  81 TLS_DHE_RSA_AES_128_CBC_SHA256              0x00 0x67      TLS1.2
  82 TLS_DHE_RSA_AES_256_CBC_SHA256              0x00 0x6B      TLS1.2
  83 TLS_DHE_RSA_AES_128_GCM_SHA256              0x00 0x9E      TLS1.2
  84 TLS_DHE_RSA_AES_256_GCM_SHA384              0x00 0x9F      TLS1.2
  85 TLS_DHE_RSA_CAMELLIA_128_GCM_SHA256         0xC0 0x7C      TLS1.2
  86 TLS_DHE_RSA_CAMELLIA_256_GCM_SHA384         0xC0 0x7D      TLS1.2
  87 TLS_ECDHE_RSA_NULL_SHA1                     0xC0 0x10      SSL3.0
  88 TLS_ECDHE_RSA_3DES_EDE_CBC_SHA1             0xC0 0x12      SSL3.0
  89 TLS_ECDHE_RSA_AES_128_CBC_SHA1              0xC0 0x13      SSL3.0
  90 TLS_ECDHE_RSA_AES_256_CBC_SHA1              0xC0 0x14      SSL3.0
  91 TLS_ECDHE_RSA_AES_256_CBC_SHA384            0xC0 0x28      TLS1.2
  92 TLS_ECDHE_RSA_ARCFOUR_128_SHA1              0xC0 0x11      SSL3.0
  93 TLS_ECDHE_RSA_CAMELLIA_128_CBC_SHA256       0xC0 0x76      TLS1.2
  94 TLS_ECDHE_RSA_CAMELLIA_256_CBC_SHA384       0xC0 0x77      TLS1.2
  95 TLS_ECDHE_ECDSA_NULL_SHA1                   0xC0 0x06      SSL3.0
  96 TLS_ECDHE_ECDSA_3DES_EDE_CBC_SHA1           0xC0 0x08      SSL3.0
  97 TLS_ECDHE_ECDSA_AES_128_CBC_SHA1            0xC0 0x09      SSL3.0
  98 TLS_ECDHE_ECDSA_AES_256_CBC_SHA1            0xC0 0x0A      SSL3.0
  99 TLS_ECDHE_ECDSA_ARCFOUR_128_SHA1            0xC0 0x07      SSL3.0
 100 TLS_ECDHE_ECDSA_CAMELLIA_128_CBC_SHA256     0xC0 0x72      TLS1.2
 101 TLS_ECDHE_ECDSA_CAMELLIA_256_CBC_SHA384     0xC0 0x73      TLS1.2
 102 TLS_ECDHE_ECDSA_AES_128_CBC_SHA256          0xC0 0x23      TLS1.2
 103 TLS_ECDHE_RSA_AES_128_CBC_SHA256            0xC0 0x27      TLS1.2
 104 TLS_ECDHE_ECDSA_CAMELLIA_128_GCM_SHA256     0xC0 0x86      TLS1.2
 105 TLS_ECDHE_ECDSA_CAMELLIA_256_GCM_SHA384     0xC0 0x87      TLS1.2
 106 TLS_ECDHE_ECDSA_AES_128_GCM_SHA256          0xC0 0x2B      TLS1.2
 107 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384          0xC0 0x2C      TLS1.2
 108 TLS_ECDHE_RSA_AES_128_GCM_SHA256            0xC0 0x2F      TLS1.2
 109 TLS_ECDHE_RSA_AES_256_GCM_SHA384            0xC0 0x30      TLS1.2
 110 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384          0xC0 0x24      TLS1.2
 111 TLS_ECDHE_RSA_CAMELLIA_128_GCM_SHA256       0xC0 0x8A      TLS1.2
 112 TLS_ECDHE_RSA_CAMELLIA_256_GCM_SHA384       0xC0 0x8B      TLS1.2
 113 TLS_ECDHE_RSA_SALSA20_256_SHA1              0xE4 0x13      SSL3.0
 114 TLS_ECDHE_ECDSA_SALSA20_256_SHA1            0xE4 0x15      SSL3.0
 115 TLS_ECDHE_RSA_ESTREAM_SALSA20_256_SHA1      0xE4 0x12      SSL3.0
 116 TLS_ECDHE_ECDSA_ESTREAM_SALSA20_256_SHA1    0xE4 0x14      SSL3.0
 117 TLS_ECDHE_PSK_3DES_EDE_CBC_SHA1             0xC0 0x34      SSL3.0
 118 TLS_ECDHE_PSK_AES_128_CBC_SHA1              0xC0 0x35      SSL3.0
 119 TLS_ECDHE_PSK_AES_256_CBC_SHA1              0xC0 0x36      SSL3.0
 120 TLS_ECDHE_PSK_AES_128_CBC_SHA256            0xC0 0x37      TLS1.2
 121 TLS_ECDHE_PSK_AES_256_CBC_SHA384            0xC0 0x38      TLS1.2
 122 TLS_ECDHE_PSK_ARCFOUR_128_SHA1              0xC0 0x33      SSL3.0
 123 TLS_ECDHE_PSK_NULL_SHA1                     0xC0 0x39      SSL3.0
 124 TLS_ECDHE_PSK_NULL_SHA256                   0xC0 0x3A      TLS1.2
 125 TLS_ECDHE_PSK_NULL_SHA384                   0xC0 0x3B      TLS1.0
 126 TLS_ECDHE_PSK_CAMELLIA_128_CBC_SHA256       0xC0 0x9A      TLS1.2
 127 TLS_ECDHE_PSK_CAMELLIA_256_CBC_SHA384       0xC0 0x9B      TLS1.2
 128 TLS_ECDHE_PSK_SALSA20_256_SHA1              0xE4 0x19      SSL3.0
 129 TLS_ECDHE_PSK_ESTREAM_SALSA20_256_SHA1      0xE4 0x18      SSL3.0
 130 TLS_PSK_ARCFOUR_128_SHA1                    0x00 0x8A      SSL3.0
 131 TLS_PSK_3DES_EDE_CBC_SHA1                   0x00 0x8B      SSL3.0
 132 TLS_PSK_AES_128_CBC_SHA1                    0x00 0x8C      SSL3.0
 133 TLS_PSK_AES_256_CBC_SHA1                    0x00 0x8D      SSL3.0
 134 TLS_PSK_AES_128_CBC_SHA256                  0x00 0xAE      TLS1.2
 135 TLS_PSK_AES_256_GCM_SHA384                  0x00 0xA9      TLS1.2
 136 TLS_PSK_CAMELLIA_128_GCM_SHA256             0xC0 0x8E      TLS1.2
 137 TLS_PSK_CAMELLIA_256_GCM_SHA384             0xC0 0x8F      TLS1.2
 138 TLS_PSK_AES_128_GCM_SHA256                  0x00 0xA8      TLS1.2
 139 TLS_PSK_NULL_SHA1                           0x00 0x2C      SSL3.0
 140 TLS_PSK_NULL_SHA256                         0x00 0xB0      TLS1.2
 141 TLS_PSK_CAMELLIA_128_CBC_SHA256             0xC0 0x94      TLS1.2
 142 TLS_PSK_CAMELLIA_256_CBC_SHA384             0xC0 0x95      TLS1.2
 143 TLS_PSK_SALSA20_256_SHA1                    0xE4 0x17      SSL3.0
 144 TLS_PSK_ESTREAM_SALSA20_256_SHA1            0xE4 0x16      SSL3.0
 145 TLS_PSK_AES_256_CBC_SHA384                  0x00 0xAF      TLS1.2
 146 TLS_PSK_NULL_SHA384                         0x00 0xB1      TLS1.2
 147 TLS_RSA_PSK_ARCFOUR_128_SHA1                0x00 0x92      TLS1.0
 148 TLS_RSA_PSK_3DES_EDE_CBC_SHA1               0x00 0x93      TLS1.0
 149 TLS_RSA_PSK_AES_128_CBC_SHA1                0x00 0x94      TLS1.0
 150 TLS_RSA_PSK_AES_256_CBC_SHA1                0x00 0x95      TLS1.0
 151 TLS_RSA_PSK_CAMELLIA_128_GCM_SHA256         0xC0 0x92      TLS1.2
 152 TLS_RSA_PSK_CAMELLIA_256_GCM_SHA384         0xC0 0x93      TLS1.2
 153 TLS_RSA_PSK_AES_128_GCM_SHA256              0x00 0xAC      TLS1.2
 154 TLS_RSA_PSK_AES_128_CBC_SHA256              0x00 0xB6      TLS1.2
 155 TLS_RSA_PSK_NULL_SHA1                       0x00 0x2E      TLS1.0
 156 TLS_RSA_PSK_NULL_SHA256                     0x00 0xB8      TLS1.2
 157 TLS_RSA_PSK_AES_256_GCM_SHA384              0x00 0xAD      TLS1.2
 158 TLS_RSA_PSK_AES_256_CBC_SHA384              0x00 0xB7      TLS1.2
 159 TLS_RSA_PSK_NULL_SHA384                     0x00 0xB9      TLS1.2
 160 TLS_RSA_PSK_CAMELLIA_128_CBC_SHA256         0xC0 0x98      TLS1.2
 161 TLS_RSA_PSK_CAMELLIA_256_CBC_SHA384         0xC0 0x99      TLS1.2
 162 TLS_DHE_PSK_ARCFOUR_128_SHA1                0x00 0x8E      SSL3.0
 163 TLS_DHE_PSK_3DES_EDE_CBC_SHA1               0x00 0x8F      SSL3.0
 164 TLS_DHE_PSK_AES_128_CBC_SHA1                0x00 0x90      SSL3.0
 165 TLS_DHE_PSK_AES_256_CBC_SHA1                0x00 0x91      SSL3.0
 166 TLS_DHE_PSK_AES_128_CBC_SHA256              0x00 0xB2      TLS1.2
 167 TLS_DHE_PSK_AES_128_GCM_SHA256              0x00 0xAA      TLS1.2
 168 TLS_DHE_PSK_NULL_SHA1                       0x00 0x2D      SSL3.0
 169 TLS_DHE_PSK_NULL_SHA256                     0x00 0xB4      TLS1.2
 170 TLS_DHE_PSK_NULL_SHA384                     0x00 0xB5      TLS1.2
 171 TLS_DHE_PSK_AES_256_CBC_SHA384              0x00 0xB3      TLS1.2
 172 TLS_DHE_PSK_AES_256_GCM_SHA384              0x00 0xAB      TLS1.2
 173 TLS_DHE_PSK_CAMELLIA_128_CBC_SHA256         0xC0 0x96      TLS1.2
 174 TLS_DHE_PSK_CAMELLIA_256_CBC_SHA384         0xC0 0x97      TLS1.2
 175 TLS_DHE_PSK_CAMELLIA_128_GCM_SHA256         0xC0 0x90      TLS1.2
 176 TLS_DHE_PSK_CAMELLIA_256_GCM_SHA384         0xC0 0x91      TLS1.2
 177 TLS_DH_ANON_ARCFOUR_128_MD5                 0x00 0x18      SSL3.0
 178 TLS_DH_ANON_3DES_EDE_CBC_SHA1               0x00 0x1B      SSL3.0
 179 TLS_DH_ANON_AES_128_CBC_SHA1                0x00 0x34      SSL3.0
 180 TLS_DH_ANON_AES_256_CBC_SHA1                0x00 0x3A      SSL3.0
 181 TLS_DH_ANON_CAMELLIA_128_CBC_SHA256         0x00 0xBF      TLS1.2
 182 TLS_DH_ANON_CAMELLIA_256_CBC_SHA256         0x00 0xC5      TLS1.2
 183 TLS_DH_ANON_CAMELLIA_128_CBC_SHA1           0x00 0x46      SSL3.0
 184 TLS_DH_ANON_CAMELLIA_256_CBC_SHA1           0x00 0x89      SSL3.0
 185 TLS_DH_ANON_AES_128_CBC_SHA256              0x00 0x6C      TLS1.2
 186 TLS_DH_ANON_AES_256_CBC_SHA256              0x00 0x6D      TLS1.2
 187 TLS_DH_ANON_AES_128_GCM_SHA256              0x00 0xA6      TLS1.2
 188 TLS_DH_ANON_AES_256_GCM_SHA384              0x00 0xA7      TLS1.2
 189 TLS_DH_ANON_CAMELLIA_128_GCM_SHA256         0xC0 0x84      TLS1.2
 190 TLS_DH_ANON_CAMELLIA_256_GCM_SHA384         0xC0 0x85      TLS1.2
 191 TLS_ECDH_ANON_NULL_SHA1                     0xC0 0x15      SSL3.0
 192 TLS_ECDH_ANON_3DES_EDE_CBC_SHA1             0xC0 0x17      SSL3.0
 193 TLS_ECDH_ANON_AES_128_CBC_SHA1              0xC0 0x18      SSL3.0
 194 TLS_ECDH_ANON_AES_256_CBC_SHA1              0xC0 0x19      SSL3.0
 195 TLS_ECDH_ANON_ARCFOUR_128_SHA1              0xC0 0x16      SSL3.0
 196 TLS_SRP_SHA_3DES_EDE_CBC_SHA1               0xC0 0x1A      SSL3.0
 197 TLS_SRP_SHA_AES_128_CBC_SHA1                0xC0 0x1D      SSL3.0
 198 TLS_SRP_SHA_AES_256_CBC_SHA1                0xC0 0x20      SSL3.0
 199 TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA1           0xC0 0x1C      SSL3.0
 200 TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA1           0xC0 0x1B      SSL3.0
 201 TLS_SRP_SHA_DSS_AES_128_CBC_SHA1            0xC0 0x1F      SSL3.0
 202 TLS_SRP_SHA_RSA_AES_128_CBC_SHA1            0xC0 0x1E      SSL3.0
 203 TLS_SRP_SHA_DSS_AES_256_CBC_SHA1            0xC0 0x22      SSL3.0
 204 TLS_SRP_SHA_RSA_AES_256_CBC_SHA1            0xC0 0x21      SSL3.0
 205
 206 Certificate types
 207 =================
 208
 209 'X.509'
 210 'OPENPGP'
 211
 212 Protocols
 213 =========
 214
 215 'SSL3.0'
 216 'TLS1.0'
 217 'TLS1.1'
 218 'TLS1.2'
 219 'DTLS0.9'
 220 'DTLS1.0'
 221 'DTLS1.2'
 222
 223 Ciphers
 224 =======
 225
 226 'AES-256-CBC'
 227 'AES-192-CBC'
 228 'AES-128-CBC'
 229 'AES-128-GCM'
 230 'AES-256-GCM'
 231 'ARCFOUR-128'
 232 'ESTREAM-SALSA20-256'
 233 'SALSA20-256'
 234 'CAMELLIA-256-CBC'
 235 'CAMELLIA-192-CBC'
 236 'CAMELLIA-128-CBC'
 237 'CAMELLIA-128-GCM'
 238 'CAMELLIA-256-GCM'
 239 '3DES-CBC'
 240 'DES-CBC'
 241 'ARCFOUR-40'
 242 'RC2-40'
 243 'NULL'
 244
 245 MAC algorithms
 246 ==============
 247
 248 'SHA1'
 249 'MD5'
 250 'SHA256'
 251 'SHA384'
 252 'SHA512'
 253 'SHA224'
 254 'UMAC-96'
 255 'UMAC-128'
 256 'AEAD'
 257
 258 Key exchange methods
 259 ====================
 260
 261 'ANON-DH'
 262 'ANON-ECDH'
 263 'RSA'
 264 'DHE-RSA'
 265 'DHE-DSS'
 266 'ECDHE-RSA'
 267 'ECDHE-ECDSA'
 268 'SRP-DSS'
 269 'SRP-RSA'
 270 'SRP'
 271 'PSK'
 272 'RSA-PSK'
 273 'DHE-PSK'
 274 'ECDHE-PSK'
 275 'RSA-EXPORT'
 276
 277 Public key algorithms
 278 =====================
 279
 280 'RSA'
 281 'DSA'
 282 'EC'
 283
 284 Public key signature algorithms
 285 ===============================
 286
 287 'RSA-SHA1'
 288 'RSA-SHA1'
 289 'RSA-SHA224'
 290 'RSA-SHA256'
 291 'RSA-SHA384'
 292 'RSA-SHA512'
 293 'RSA-RMD160'
 294 'DSA-SHA1'
 295 'DSA-SHA1'
 296 'DSA-SHA224'
 297 'DSA-SHA256'
 298 'RSA-MD5'
 299 'RSA-MD5'
 300 'RSA-MD2'
 301 'ECDSA-SHA1'
 302 'ECDSA-SHA224'
 303 'ECDSA-SHA256'
 304 'ECDSA-SHA384'
 305 'ECDSA-SHA512'
 306
 307 Elliptic curves
 308 ===============
 309
 310 'SECP192R1'
 311 'SECP224R1'
 312 'SECP256R1'
 313 'SECP384R1'
 314 'SECP521R1'
 315
 316 Compression methods
 317 ===================
 318
 319 'DEFLATE'
 320 'NULL'
 321
 322 \1f
 323 File: gnutls.info,  Node: API reference,  Next: Copying Information,  Prev: Supported ciphersuites,  Up: Top
 324
 325 Appendix E API reference
 326 ************************
 327
 328 * Menu:
 329
 330 * Core TLS API::
 331 * Datagram TLS API::
 332 * X509 certificate API::
 333 * OCSP API::
 334 * OpenPGP API::
 335 * PKCS 12 API::
 336 * PKCS 11 API::
 337 * TPM API::
 338 * Abstract key API::
 339 * DANE API::
 340 * Cryptographic API::
 341 * Compatibility API::
 342
 343 \1f
 344 File: gnutls.info,  Node: Core TLS API,  Next: Datagram TLS API,  Up: API reference
 345
 346 E.1 Core TLS API
 347 ================
 348
 349 The prototypes for the following functions lie in 'gnutls/gnutls.h'.
 350
 351 gnutls_alert_get
 352 ----------------
 353
 354  -- Function: gnutls_alert_description_t gnutls_alert_get
 355           (gnutls_session_t SESSION)
 356      SESSION: is a 'gnutls_session_t' structure.
 357
 358      This function will return the last alert number received.  This
 359      function should be called when 'GNUTLS_E_WARNING_ALERT_RECEIVED' or
 360      'GNUTLS_E_FATAL_ALERT_RECEIVED' errors are returned by a gnutls
 361      function.  The peer may send alerts if he encounters an error.  If
 362      no alert has been received the returned value is undefined.
 363
 364      *Returns:* the last alert received, a 'gnutls_alert_description_t'
 365      value.
 366
 367 gnutls_alert_get_name
 368 ---------------------
 369
 370  -- Function: const char * gnutls_alert_get_name
 371           (gnutls_alert_description_t ALERT)
 372      ALERT: is an alert number.
 373
 374      This function will return a string that describes the given alert
 375      number, or 'NULL' .  See 'gnutls_alert_get()' .
 376
 377      *Returns:* string corresponding to 'gnutls_alert_description_t'
 378      value.
 379
 380 gnutls_alert_get_strname
 381 ------------------------
 382
 383  -- Function: const char * gnutls_alert_get_strname
 384           (gnutls_alert_description_t ALERT)
 385      ALERT: is an alert number.
 386
 387      This function will return a string of the name of the alert.
 388
 389      *Returns:* string corresponding to 'gnutls_alert_description_t'
 390      value.
 391
 392      *Since:* 3.0
 393
 394 gnutls_alert_send
 395 -----------------
 396
 397  -- Function: int gnutls_alert_send (gnutls_session_t SESSION,
 398           gnutls_alert_level_t LEVEL, gnutls_alert_description_t DESC)
 399      SESSION: is a 'gnutls_session_t' structure.
 400
 401      LEVEL: is the level of the alert
 402
 403      DESC: is the alert description
 404
 405      This function will send an alert to the peer in order to inform him
 406      of something important (eg.  his Certificate could not be
 407      verified).  If the alert level is Fatal then the peer is expected
 408      to close the connection, otherwise he may ignore the alert and
 409      continue.
 410
 411      The error code of the underlying record send function will be
 412      returned, so you may also receive 'GNUTLS_E_INTERRUPTED' or
 413      'GNUTLS_E_AGAIN' as well.
 414
 415      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 416      otherwise an error code is returned.
 417
 418 gnutls_alert_send_appropriate
 419 -----------------------------
 420
 421  -- Function: int gnutls_alert_send_appropriate (gnutls_session_t
 422           SESSION, int ERR)
 423      SESSION: is a 'gnutls_session_t' structure.
 424
 425      ERR: is an integer
 426
 427      Sends an alert to the peer depending on the error code returned by
 428      a gnutls function.  This function will call
 429      'gnutls_error_to_alert()' to determine the appropriate alert to
 430      send.
 431
 432      This function may also return 'GNUTLS_E_AGAIN' , or
 433      'GNUTLS_E_INTERRUPTED' .
 434
 435      If the return value is 'GNUTLS_E_INVALID_REQUEST' , then no alert
 436      has been sent to the peer.
 437
 438      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 439      otherwise an error code is returned.
 440
 441 gnutls_alpn_get_selected_protocol
 442 ---------------------------------
 443
 444  -- Function: int gnutls_alpn_get_selected_protocol (gnutls_session_t
 445           SESSION, gnutls_datum_t * PROTOCOL)
 446      SESSION: is a 'gnutls_session_t' structure.
 447
 448      PROTOCOL: will hold the protocol name
 449
 450      This function allows you to get the negotiated protocol name.  The
 451      returned protocol should be treated as opaque, constant value and
 452      only valid during the session life.
 453
 454      The selected protocol is the first supported by the list sent by
 455      the client.
 456
 457      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 458      otherwise a negative error code is returned.
 459
 460      Since 3.2.0
 461
 462 gnutls_alpn_set_protocols
 463 -------------------------
 464
 465  -- Function: int gnutls_alpn_set_protocols (gnutls_session_t SESSION,
 466           const gnutls_datum_t * PROTOCOLS, unsigned PROTOCOLS_SIZE,
 467           unsigned int FLAGS)
 468      SESSION: is a 'gnutls_session_t' structure.
 469
 470      PROTOCOLS: is the protocol names to add.
 471
 472      PROTOCOLS_SIZE: the number of protocols to add.
 473
 474      FLAGS: zero or 'GNUTLS_ALPN_' *
 475
 476      This function is to be used by both clients and servers, to declare
 477      the supported ALPN protocols, which are used during negotiation
 478      with peer.
 479
 480      If 'GNUTLS_ALPN_MAND' is specified the connection will be aborted
 481      if no matching ALPN protocol is found.
 482
 483      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 484      otherwise a negative error code is returned.
 485
 486      Since 3.2.0
 487
 488 gnutls_anon_allocate_client_credentials
 489 ---------------------------------------
 490
 491  -- Function: int gnutls_anon_allocate_client_credentials
 492           (gnutls_anon_client_credentials_t * SC)
 493      SC: is a pointer to a 'gnutls_anon_client_credentials_t' structure.
 494
 495      This structure is complex enough to manipulate directly thus this
 496      helper function is provided in order to allocate it.
 497
 498      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
 499
 500 gnutls_anon_allocate_server_credentials
 501 ---------------------------------------
 502
 503  -- Function: int gnutls_anon_allocate_server_credentials
 504           (gnutls_anon_server_credentials_t * SC)
 505      SC: is a pointer to a 'gnutls_anon_server_credentials_t' structure.
 506
 507      This structure is complex enough to manipulate directly thus this
 508      helper function is provided in order to allocate it.
 509
 510      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
 511
 512 gnutls_anon_free_client_credentials
 513 -----------------------------------
 514
 515  -- Function: void gnutls_anon_free_client_credentials
 516           (gnutls_anon_client_credentials_t SC)
 517      SC: is a 'gnutls_anon_client_credentials_t' structure.
 518
 519      This structure is complex enough to manipulate directly thus this
 520      helper function is provided in order to free (deallocate) it.
 521
 522 gnutls_anon_free_server_credentials
 523 -----------------------------------
 524
 525  -- Function: void gnutls_anon_free_server_credentials
 526           (gnutls_anon_server_credentials_t SC)
 527      SC: is a 'gnutls_anon_server_credentials_t' structure.
 528
 529      This structure is complex enough to manipulate directly thus this
 530      helper function is provided in order to free (deallocate) it.
 531
 532 gnutls_anon_set_params_function
 533 -------------------------------
 534
 535  -- Function: void gnutls_anon_set_params_function
 536           (gnutls_anon_server_credentials_t RES, gnutls_params_function
 537           * FUNC)
 538      RES: is a gnutls_anon_server_credentials_t structure
 539
 540      FUNC: is the function to be called
 541
 542      This function will set a callback in order for the server to get
 543      the Diffie-Hellman or RSA parameters for anonymous authentication.
 544      The callback should return 'GNUTLS_E_SUCCESS' (0) on success.
 545
 546 gnutls_anon_set_server_dh_params
 547 --------------------------------
 548
 549  -- Function: void gnutls_anon_set_server_dh_params
 550           (gnutls_anon_server_credentials_t RES, gnutls_dh_params_t
 551           DH_PARAMS)
 552      RES: is a gnutls_anon_server_credentials_t structure
 553
 554      DH_PARAMS: is a structure that holds Diffie-Hellman parameters.
 555
 556      This function will set the Diffie-Hellman parameters for an
 557      anonymous server to use.  These parameters will be used in
 558      Anonymous Diffie-Hellman cipher suites.
 559
 560 gnutls_anon_set_server_params_function
 561 --------------------------------------
 562
 563  -- Function: void gnutls_anon_set_server_params_function
 564           (gnutls_anon_server_credentials_t RES, gnutls_params_function
 565           * FUNC)
 566      RES: is a gnutls_certificate_credentials_t structure
 567
 568      FUNC: is the function to be called
 569
 570      This function will set a callback in order for the server to get
 571      the Diffie-Hellman parameters for anonymous authentication.  The
 572      callback should return 'GNUTLS_E_SUCCESS' (0) on success.
 573
 574 gnutls_auth_client_get_type
 575 ---------------------------
 576
 577  -- Function: gnutls_credentials_type_t gnutls_auth_client_get_type
 578           (gnutls_session_t SESSION)
 579      SESSION: is a 'gnutls_session_t' structure.
 580
 581      Returns the type of credentials that were used for client
 582      authentication.  The returned information is to be used to
 583      distinguish the function used to access authentication data.
 584
 585      *Returns:* The type of credentials for the client authentication
 586      schema, a 'gnutls_credentials_type_t' type.
 587
 588 gnutls_auth_get_type
 589 --------------------
 590
 591  -- Function: gnutls_credentials_type_t gnutls_auth_get_type
 592           (gnutls_session_t SESSION)
 593      SESSION: is a 'gnutls_session_t' structure.
 594
 595      Returns type of credentials for the current authentication schema.
 596      The returned information is to be used to distinguish the function
 597      used to access authentication data.
 598
 599      Eg.  for CERTIFICATE ciphersuites (key exchange algorithms:
 600      'GNUTLS_KX_RSA' , 'GNUTLS_KX_DHE_RSA' ), the same function are to
 601      be used to access the authentication data.
 602
 603      *Returns:* The type of credentials for the current authentication
 604      schema, a 'gnutls_credentials_type_t' type.
 605
 606 gnutls_auth_server_get_type
 607 ---------------------------
 608
 609  -- Function: gnutls_credentials_type_t gnutls_auth_server_get_type
 610           (gnutls_session_t SESSION)
 611      SESSION: is a 'gnutls_session_t' structure.
 612
 613      Returns the type of credentials that were used for server
 614      authentication.  The returned information is to be used to
 615      distinguish the function used to access authentication data.
 616
 617      *Returns:* The type of credentials for the server authentication
 618      schema, a 'gnutls_credentials_type_t' type.
 619
 620 gnutls_bye
 621 ----------
 622
 623  -- Function: int gnutls_bye (gnutls_session_t SESSION,
 624           gnutls_close_request_t HOW)
 625      SESSION: is a 'gnutls_session_t' structure.
 626
 627      HOW: is an integer
 628
 629      Terminates the current TLS/SSL connection.  The connection should
 630      have been initiated using 'gnutls_handshake()' .  'how' should be
 631      one of 'GNUTLS_SHUT_RDWR' , 'GNUTLS_SHUT_WR' .
 632
 633      In case of 'GNUTLS_SHUT_RDWR' the TLS session gets terminated and
 634      further receives and sends will be disallowed.  If the return value
 635      is zero you may continue using the underlying transport layer.
 636      'GNUTLS_SHUT_RDWR' sends an alert containing a close request and
 637      waits for the peer to reply with the same message.
 638
 639      In case of 'GNUTLS_SHUT_WR' the TLS session gets terminated and
 640      further sends will be disallowed.  In order to reuse the connection
 641      you should wait for an EOF from the peer.  'GNUTLS_SHUT_WR' sends
 642      an alert containing a close request.
 643
 644      Note that not all implementations will properly terminate a TLS
 645      connection.  Some of them, usually for performance reasons, will
 646      terminate only the underlying transport layer, and thus not
 647      distinguishing between a malicious party prematurely terminating
 648      the connection and normal termination.
 649
 650      This function may also return 'GNUTLS_E_AGAIN' or
 651      'GNUTLS_E_INTERRUPTED' ; cf.  'gnutls_record_get_direction()' .
 652
 653      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code, see
 654      function documentation for entire semantics.
 655
 656 gnutls_certificate_activation_time_peers
 657 ----------------------------------------
 658
 659  -- Function: time_t gnutls_certificate_activation_time_peers
 660           (gnutls_session_t SESSION)
 661      SESSION: is a gnutls session
 662
 663      This function will return the peer's certificate activation time.
 664      This is the creation time for openpgp keys.
 665
 666      *Returns:* (time_t)-1 on error.
 667
 668      *Deprecated:* 'gnutls_certificate_verify_peers2()' now verifies
 669      activation times.
 670
 671 gnutls_certificate_allocate_credentials
 672 ---------------------------------------
 673
 674  -- Function: int gnutls_certificate_allocate_credentials
 675           (gnutls_certificate_credentials_t * RES)
 676      RES: is a pointer to a 'gnutls_certificate_credentials_t'
 677      structure.
 678
 679      This structure is complex enough to manipulate directly thus this
 680      helper function is provided in order to allocate it.
 681
 682      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
 683
 684 gnutls_certificate_client_get_request_status
 685 --------------------------------------------
 686
 687  -- Function: int gnutls_certificate_client_get_request_status
 688           (gnutls_session_t SESSION)
 689      SESSION: is a gnutls session
 690
 691      Get whether client certificate is requested or not.
 692
 693      *Returns:* 0 if the peer (server) did not request client
 694      authentication or 1 otherwise.
 695
 696 gnutls_certificate_expiration_time_peers
 697 ----------------------------------------
 698
 699  -- Function: time_t gnutls_certificate_expiration_time_peers
 700           (gnutls_session_t SESSION)
 701      SESSION: is a gnutls session
 702
 703      This function will return the peer's certificate expiration time.
 704
 705      *Returns:* (time_t)-1 on error.
 706
 707      *Deprecated:* 'gnutls_certificate_verify_peers2()' now verifies
 708      expiration times.
 709
 710 gnutls_certificate_free_ca_names
 711 --------------------------------
 712
 713  -- Function: void gnutls_certificate_free_ca_names
 714           (gnutls_certificate_credentials_t SC)
 715      SC: is a 'gnutls_certificate_credentials_t' structure.
 716
 717      This function will delete all the CA name in the given credentials.
 718      Clients may call this to save some memory since in client side the
 719      CA names are not used.  Servers might want to use this function if
 720      a large list of trusted CAs is present and sending the names of it
 721      would just consume bandwidth without providing information to
 722      client.
 723
 724      CA names are used by servers to advertise the CAs they support to
 725      clients.
 726
 727 gnutls_certificate_free_cas
 728 ---------------------------
 729
 730  -- Function: void gnutls_certificate_free_cas
 731           (gnutls_certificate_credentials_t SC)
 732      SC: is a 'gnutls_certificate_credentials_t' structure.
 733
 734      This function will delete all the CAs associated with the given
 735      credentials.  Servers that do not use
 736      'gnutls_certificate_verify_peers2()' may call this to save some
 737      memory.
 738
 739 gnutls_certificate_free_credentials
 740 -----------------------------------
 741
 742  -- Function: void gnutls_certificate_free_credentials
 743           (gnutls_certificate_credentials_t SC)
 744      SC: is a 'gnutls_certificate_credentials_t' structure.
 745
 746      This structure is complex enough to manipulate directly thus this
 747      helper function is provided in order to free (deallocate) it.
 748
 749      This function does not free any temporary parameters associated
 750      with this structure (ie RSA and DH parameters are not freed by this
 751      function).
 752
 753 gnutls_certificate_free_crls
 754 ----------------------------
 755
 756  -- Function: void gnutls_certificate_free_crls
 757           (gnutls_certificate_credentials_t SC)
 758      SC: is a 'gnutls_certificate_credentials_t' structure.
 759
 760      This function will delete all the CRLs associated with the given
 761      credentials.
 762
 763 gnutls_certificate_free_keys
 764 ----------------------------
 765
 766  -- Function: void gnutls_certificate_free_keys
 767           (gnutls_certificate_credentials_t SC)
 768      SC: is a 'gnutls_certificate_credentials_t' structure.
 769
 770      This function will delete all the keys and the certificates
 771      associated with the given credentials.  This function must not be
 772      called when a TLS negotiation that uses the credentials is in
 773      progress.
 774
 775 gnutls_certificate_get_crt_raw
 776 ------------------------------
 777
 778  -- Function: int gnutls_certificate_get_crt_raw
 779           (gnutls_certificate_credentials_t SC, unsigned IDX1, unsigned
 780           IDX2, gnutls_datum_t * CERT)
 781      SC: is a 'gnutls_certificate_credentials_t' structure.
 782
 783      IDX1: the index of the certificate if multiple are present
 784
 785      IDX2: the index in the certificate list.  Zero gives the server's
 786      certificate.
 787
 788      CERT: Will hold the DER encoded certificate.
 789
 790      This function will return the DER encoded certificate of the server
 791      or any other certificate on its certificate chain (based on 'idx2'
 792      ).  The returned data should be treated as constant and only
 793      accessible during the lifetime of 'sc' .
 794
 795      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 796      otherwise a negative error value.  In case the indexes are out of
 797      bounds 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
 798
 799      *Since:* 3.2.5
 800
 801 gnutls_certificate_get_issuer
 802 -----------------------------
 803
 804  -- Function: int gnutls_certificate_get_issuer
 805           (gnutls_certificate_credentials_t SC, gnutls_x509_crt_t CERT,
 806           gnutls_x509_crt_t * ISSUER, unsigned int FLAGS)
 807      SC: is a 'gnutls_certificate_credentials_t' structure.
 808
 809      CERT: is the certificate to find issuer for
 810
 811      ISSUER: Will hold the issuer if any.  Should be treated as
 812      constant.
 813
 814      FLAGS: Use zero or 'GNUTLS_TL_GET_COPY'
 815
 816      This function will return the issuer of a given certificate.  As
 817      with 'gnutls_x509_trust_list_get_issuer()' this function requires
 818      the 'GNUTLS_TL_GET_COPY' flag in order to operate with PKCS '11'
 819      trust lists.  In that case the issuer must be freed using
 820      'gnutls_x509_crt_deinit()' .
 821
 822      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 823      otherwise a negative error value.
 824
 825      *Since:* 3.0
 826
 827 gnutls_certificate_get_ours
 828 ---------------------------
 829
 830  -- Function: const gnutls_datum_t * gnutls_certificate_get_ours
 831           (gnutls_session_t SESSION)
 832      SESSION: is a gnutls session
 833
 834      Gets the certificate as sent to the peer in the last handshake.
 835      The certificate is in raw (DER) format.  No certificate list is
 836      being returned.  Only the first certificate.
 837
 838      *Returns:* a pointer to a 'gnutls_datum_t' containing our
 839      certificate, or 'NULL' in case of an error or if no certificate was
 840      used.
 841
 842 gnutls_certificate_get_peers
 843 ----------------------------
 844
 845  -- Function: const gnutls_datum_t * gnutls_certificate_get_peers
 846           (gnutls_session_t SESSION, unsigned int * LIST_SIZE)
 847      SESSION: is a gnutls session
 848
 849      LIST_SIZE: is the length of the certificate list (may be 'NULL' )
 850
 851      Get the peer's raw certificate (chain) as sent by the peer.  These
 852      certificates are in raw format (DER encoded for X.509).  In case of
 853      a X.509 then a certificate list may be present.  The first
 854      certificate in the list is the peer's certificate, following the
 855      issuer's certificate, then the issuer's issuer etc.
 856
 857      In case of OpenPGP keys a single key will be returned in raw
 858      format.
 859
 860      *Returns:* a pointer to a 'gnutls_datum_t' containing the peer's
 861      certificates, or 'NULL' in case of an error or if no certificate
 862      was used.
 863
 864 gnutls_certificate_get_peers_subkey_id
 865 --------------------------------------
 866
 867  -- Function: int gnutls_certificate_get_peers_subkey_id
 868           (gnutls_session_t SESSION, gnutls_datum_t * ID)
 869      SESSION: is a gnutls session
 870
 871      ID: will contain the ID
 872
 873      Get the peer's subkey ID when OpenPGP certificates are used.  The
 874      returned 'id' should be treated as constant.
 875
 876      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 877      otherwise an error code is returned.
 878
 879      *Since:* 3.1.3
 880
 881 gnutls_certificate_send_x509_rdn_sequence
 882 -----------------------------------------
 883
 884  -- Function: void gnutls_certificate_send_x509_rdn_sequence
 885           (gnutls_session_t SESSION, int STATUS)
 886      SESSION: is a pointer to a 'gnutls_session_t' structure.
 887
 888      STATUS: is 0 or 1
 889
 890      If status is non zero, this function will order gnutls not to send
 891      the rdnSequence in the certificate request message.  That is the
 892      server will not advertise its trusted CAs to the peer.  If status
 893      is zero then the default behaviour will take effect, which is to
 894      advertise the server's trusted CAs.
 895
 896      This function has no effect in clients, and in authentication
 897      methods other than certificate with X.509 certificates.
 898
 899 gnutls_certificate_server_set_request
 900 -------------------------------------
 901
 902  -- Function: void gnutls_certificate_server_set_request
 903           (gnutls_session_t SESSION, gnutls_certificate_request_t REQ)
 904      SESSION: is a 'gnutls_session_t' structure.
 905
 906      REQ: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
 907
 908      This function specifies if we (in case of a server) are going to
 909      send a certificate request message to the client.  If 'req' is
 910      GNUTLS_CERT_REQUIRE then the server will return an error if the
 911      peer does not provide a certificate.  If you do not call this
 912      function then the client will not be asked to send a certificate.
 913
 914 gnutls_certificate_set_dh_params
 915 --------------------------------
 916
 917  -- Function: void gnutls_certificate_set_dh_params
 918           (gnutls_certificate_credentials_t RES, gnutls_dh_params_t
 919           DH_PARAMS)
 920      RES: is a gnutls_certificate_credentials_t structure
 921
 922      DH_PARAMS: is a structure that holds Diffie-Hellman parameters.
 923
 924      This function will set the Diffie-Hellman parameters for a
 925      certificate server to use.  These parameters will be used in
 926      Ephemeral Diffie-Hellman cipher suites.  Note that only a pointer
 927      to the parameters are stored in the certificate handle, so you must
 928      not deallocate the parameters before the certificate is
 929      deallocated.
 930
 931 gnutls_certificate_set_ocsp_status_request_file
 932 -----------------------------------------------
 933
 934  -- Function: int gnutls_certificate_set_ocsp_status_request_file
 935           (gnutls_certificate_credentials_t SC, const char *
 936           RESPONSE_FILE, unsigned int FLAGS)
 937      SC: is a credentials structure.
 938
 939      RESPONSE_FILE: a filename of the OCSP response
 940
 941      FLAGS: should be zero
 942
 943      This function sets the filename of an OCSP response, that will be
 944      sent to the client if requests an OCSP certificate status.  This is
 945      a convenience function which is inefficient on busy servers since
 946      the file is opened on every access.  Use
 947      'gnutls_certificate_set_ocsp_status_request_function()' to
 948      fine-tune file accesses.
 949
 950      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 951      otherwise a negative error code is returned.
 952
 953      *Since:* 3.1.3
 954
 955 gnutls_certificate_set_ocsp_status_request_function
 956 ---------------------------------------------------
 957
 958  -- Function: void gnutls_certificate_set_ocsp_status_request_function
 959           (gnutls_certificate_credentials_t SC,
 960           gnutls_status_request_ocsp_func OCSP_FUNC, void * PTR)
 961      SC: is a 'gnutls_certificate_credentials_t' structure.
 962
 963      OCSP_FUNC: function pointer to OCSP status request callback.
 964
 965      PTR: opaque pointer passed to callback function
 966
 967      This function is to be used by server to register a callback to
 968      handle OCSP status requests from the client.  The callback will be
 969      invoked if the client supplied a status-request OCSP extension.
 970      The callback function prototype is:
 971
 972      typedef int (*gnutls_status_request_ocsp_func) (gnutls_session_t
 973      session, void *ptr, gnutls_datum_t *ocsp_response);
 974
 975      The callback will be invoked if the client requests an OCSP
 976      certificate status.  The callback may return
 977      'GNUTLS_E_NO_CERTIFICATE_STATUS' , if there is no recent OCSP
 978      response.  If the callback returns 'GNUTLS_E_SUCCESS' , the server
 979      will provide the client with the ocsp_response.
 980
 981      The response must be a value allocated using 'gnutls_malloc()' ,
 982      and will be deinitialized when needed.
 983
 984      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
 985      otherwise a negative error code is returned.
 986
 987      *Since:* 3.1.3
 988
 989 gnutls_certificate_set_params_function
 990 --------------------------------------
 991
 992  -- Function: void gnutls_certificate_set_params_function
 993           (gnutls_certificate_credentials_t RES, gnutls_params_function
 994           * FUNC)
 995      RES: is a gnutls_certificate_credentials_t structure
 996
 997      FUNC: is the function to be called
 998
 999      This function will set a callback in order for the server to get
1000      the Diffie-Hellman or RSA parameters for certificate
1001      authentication.  The callback should return 'GNUTLS_E_SUCCESS' (0)
1002      on success.
1003
1004 gnutls_certificate_set_pin_function
1005 -----------------------------------
1006
1007  -- Function: void gnutls_certificate_set_pin_function
1008           (gnutls_certificate_credentials_t CRED, gnutls_pin_callback_t
1009           FN, void * USERDATA)
1010      CRED: is a 'gnutls_certificate_credentials_t' structure.
1011
1012      FN: A PIN callback
1013
1014      USERDATA: Data to be passed in the callback
1015
1016      This function will set a callback function to be used when required
1017      to access a protected object.  This function overrides any other
1018      global PIN functions.
1019
1020      Note that this function must be called right after initialization
1021      to have effect.
1022
1023      *Since:* 3.1.0
1024
1025 gnutls_certificate_set_retrieve_function
1026 ----------------------------------------
1027
1028  -- Function: void gnutls_certificate_set_retrieve_function
1029           (gnutls_certificate_credentials_t CRED,
1030           gnutls_certificate_retrieve_function * FUNC)
1031      CRED: is a 'gnutls_certificate_credentials_t' structure.
1032
1033      FUNC: is the callback function
1034
1035      This function sets a callback to be called in order to retrieve the
1036      certificate to be used in the handshake.  You are advised to use
1037      'gnutls_certificate_set_retrieve_function2()' because it is much
1038      more efficient in the processing it requires from gnutls.
1039
1040      The callback's function prototype is: int
1041      (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int
1042      nreqs, const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length,
1043      gnutls_retr2_st* st);
1044
1045      'req_ca_dn' is only used in X.509 certificates.  Contains a list
1046      with the CA names that the server considers trusted.  Normally we
1047      should send a certificate that is signed by one of these CAs.
1048      These names are DER encoded.  To get a more meaningful value use
1049      the function 'gnutls_x509_rdn_get()' .
1050
1051      'pk_algos' contains a list with server's acceptable signature
1052      algorithms.  The certificate returned should support the server's
1053      given algorithms.
1054
1055      'st' should contain the certificates and private keys.
1056
1057      If the callback function is provided then gnutls will call it, in
1058      the handshake, after the certificate request message has been
1059      received.
1060
1061      In server side pk_algos and req_ca_dn are NULL.
1062
1063      The callback function should set the certificate list to be sent,
1064      and return 0 on success.  If no certificate was selected then the
1065      number of certificates should be set to zero.  The value (-1)
1066      indicates error and the handshake will be terminated.
1067
1068      *Since:* 3.0
1069
1070 gnutls_certificate_set_verify_flags
1071 -----------------------------------
1072
1073  -- Function: void gnutls_certificate_set_verify_flags
1074           (gnutls_certificate_credentials_t RES, unsigned int FLAGS)
1075      RES: is a gnutls_certificate_credentials_t structure
1076
1077      FLAGS: are the flags
1078
1079      This function will set the flags to be used for verification of
1080      certificates and override any defaults.  The provided flags must be
1081      an OR of the 'gnutls_certificate_verify_flags' enumerations.
1082
1083 gnutls_certificate_set_verify_function
1084 --------------------------------------
1085
1086  -- Function: void gnutls_certificate_set_verify_function
1087           (gnutls_certificate_credentials_t CRED,
1088           gnutls_certificate_verify_function * FUNC)
1089      CRED: is a 'gnutls_certificate_credentials_t' structure.
1090
1091      FUNC: is the callback function
1092
1093      This function sets a callback to be called when peer's certificate
1094      has been received in order to verify it on receipt rather than
1095      doing after the handshake is completed.
1096
1097      The callback's function prototype is: int
1098      (*callback)(gnutls_session_t);
1099
1100      If the callback function is provided then gnutls will call it, in
1101      the handshake, just after the certificate message has been
1102      received.  To verify or obtain the certificate the
1103      'gnutls_certificate_verify_peers2()' ,
1104      'gnutls_certificate_type_get()' , 'gnutls_certificate_get_peers()'
1105      functions can be used.
1106
1107      The callback function should return 0 for the handshake to continue
1108      or non-zero to terminate.
1109
1110      *Since:* 2.10.0
1111
1112 gnutls_certificate_set_verify_limits
1113 ------------------------------------
1114
1115  -- Function: void gnutls_certificate_set_verify_limits
1116           (gnutls_certificate_credentials_t RES, unsigned int MAX_BITS,
1117           unsigned int MAX_DEPTH)
1118      RES: is a gnutls_certificate_credentials structure
1119
1120      MAX_BITS: is the number of bits of an acceptable certificate
1121      (default 8200)
1122
1123      MAX_DEPTH: is maximum depth of the verification of a certificate
1124      chain (default 5)
1125
1126      This function will set some upper limits for the default
1127      verification function, 'gnutls_certificate_verify_peers2()' , to
1128      avoid denial of service attacks.  You can set them to zero to
1129      disable limits.
1130
1131 gnutls_certificate_set_x509_crl
1132 -------------------------------
1133
1134  -- Function: int gnutls_certificate_set_x509_crl
1135           (gnutls_certificate_credentials_t RES, gnutls_x509_crl_t *
1136           CRL_LIST, int CRL_LIST_SIZE)
1137      RES: is a 'gnutls_certificate_credentials_t' structure.
1138
1139      CRL_LIST: is a list of trusted CRLs.  They should have been
1140      verified before.
1141
1142      CRL_LIST_SIZE: holds the size of the crl_list
1143
1144      This function adds the trusted CRLs in order to verify client or
1145      server certificates.  In case of a client this is not required to
1146      be called if the certificates are not verified using
1147      'gnutls_certificate_verify_peers2()' .  This function may be called
1148      multiple times.
1149
1150      *Returns:* number of CRLs processed, or a negative error code on
1151      error.
1152
1153      *Since:* 2.4.0
1154
1155 gnutls_certificate_set_x509_crl_file
1156 ------------------------------------
1157
1158  -- Function: int gnutls_certificate_set_x509_crl_file
1159           (gnutls_certificate_credentials_t RES, const char * CRLFILE,
1160           gnutls_x509_crt_fmt_t TYPE)
1161      RES: is a 'gnutls_certificate_credentials_t' structure.
1162
1163      CRLFILE: is a file containing the list of verified CRLs (DER or PEM
1164      list)
1165
1166      TYPE: is PEM or DER
1167
1168      This function adds the trusted CRLs in order to verify client or
1169      server certificates.  In case of a client this is not required to
1170      be called if the certificates are not verified using
1171      'gnutls_certificate_verify_peers2()' .  This function may be called
1172      multiple times.
1173
1174      *Returns:* number of CRLs processed or a negative error code on
1175      error.
1176
1177 gnutls_certificate_set_x509_crl_mem
1178 -----------------------------------
1179
1180  -- Function: int gnutls_certificate_set_x509_crl_mem
1181           (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
1182           CRL, gnutls_x509_crt_fmt_t TYPE)
1183      RES: is a 'gnutls_certificate_credentials_t' structure.
1184
1185      CRL: is a list of trusted CRLs.  They should have been verified
1186      before.
1187
1188      TYPE: is DER or PEM
1189
1190      This function adds the trusted CRLs in order to verify client or
1191      server certificates.  In case of a client this is not required to
1192      be called if the certificates are not verified using
1193      'gnutls_certificate_verify_peers2()' .  This function may be called
1194      multiple times.
1195
1196      *Returns:* number of CRLs processed, or a negative error code on
1197      error.
1198
1199 gnutls_certificate_set_x509_key
1200 -------------------------------
1201
1202  -- Function: int gnutls_certificate_set_x509_key
1203           (gnutls_certificate_credentials_t RES, gnutls_x509_crt_t *
1204           CERT_LIST, int CERT_LIST_SIZE, gnutls_x509_privkey_t KEY)
1205      RES: is a 'gnutls_certificate_credentials_t' structure.
1206
1207      CERT_LIST: contains a certificate list (path) for the specified
1208      private key
1209
1210      CERT_LIST_SIZE: holds the size of the certificate list
1211
1212      KEY: is a 'gnutls_x509_privkey_t' key
1213
1214      This function sets a certificate/private key pair in the
1215      gnutls_certificate_credentials_t structure.  This function may be
1216      called more than once, in case multiple keys/certificates exist for
1217      the server.  For clients that wants to send more than their own end
1218      entity certificate (e.g., also an intermediate CA cert) then put
1219      the certificate chain in 'cert_list' .
1220
1221      Note that the certificates and keys provided, can be safely
1222      deinitialized after this function is called.
1223
1224      If that function fails to load the 'res' structure is at an
1225      undefined state, it must not be reused to load other keys or
1226      certificates.
1227
1228      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1229      code.
1230
1231      *Since:* 2.4.0
1232
1233 gnutls_certificate_set_x509_key_file
1234 ------------------------------------
1235
1236  -- Function: int gnutls_certificate_set_x509_key_file
1237           (gnutls_certificate_credentials_t RES, const char * CERTFILE,
1238           const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE)
1239      RES: is a 'gnutls_certificate_credentials_t' structure.
1240
1241      CERTFILE: is a file that containing the certificate list (path) for
1242      the specified private key, in PKCS7 format, or a list of
1243      certificates
1244
1245      KEYFILE: is a file that contains the private key
1246
1247      TYPE: is PEM or DER
1248
1249      This function sets a certificate/private key pair in the
1250      gnutls_certificate_credentials_t structure.  This function may be
1251      called more than once, in case multiple keys/certificates exist for
1252      the server.  For clients that need to send more than its own end
1253      entity certificate, e.g., also an intermediate CA cert, then the
1254      'certfile' must contain the ordered certificate chain.
1255
1256      Note that the names in the certificate provided will be considered
1257      when selecting the appropriate certificate to use (in case of
1258      multiple certificate/key pairs).
1259
1260      This function can also accept URLs at 'keyfile' and 'certfile' .
1261      In that case it will import the private key and certificate
1262      indicated by the URLs.  Note that the supported URLs are the ones
1263      indicated by 'gnutls_url_is_supported()' .
1264
1265      In case the 'certfile' is provided as a PKCS '11' URL, then the
1266      certificate, and its present issuers in the token are are imported
1267      (i.e., the required trust chain).
1268
1269      If that function fails to load the 'res' structure is at an
1270      undefined state, it must not be reused to load other keys or
1271      certificates.
1272
1273      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1274      code.
1275
1276 gnutls_certificate_set_x509_key_file2
1277 -------------------------------------
1278
1279  -- Function: int gnutls_certificate_set_x509_key_file2
1280           (gnutls_certificate_credentials_t RES, const char * CERTFILE,
1281           const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE, const char *
1282           PASS, unsigned int FLAGS)
1283      RES: is a 'gnutls_certificate_credentials_t' structure.
1284
1285      CERTFILE: is a file that containing the certificate list (path) for
1286      the specified private key, in PKCS7 format, or a list of
1287      certificates
1288
1289      KEYFILE: is a file that contains the private key
1290
1291      TYPE: is PEM or DER
1292
1293      PASS: is the password of the key
1294
1295      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
1296
1297      This function sets a certificate/private key pair in the
1298      gnutls_certificate_credentials_t structure.  This function may be
1299      called more than once, in case multiple keys/certificates exist for
1300      the server.  For clients that need to send more than its own end
1301      entity certificate, e.g., also an intermediate CA cert, then the
1302      'certfile' must contain the ordered certificate chain.
1303
1304      Note that the names in the certificate provided will be considered
1305      when selecting the appropriate certificate to use (in case of
1306      multiple certificate/key pairs).
1307
1308      This function can also accept URLs at 'keyfile' and 'certfile' .
1309      In that case it will import the private key and certificate
1310      indicated by the URLs.  Note that the supported URLs are the ones
1311      indicated by 'gnutls_url_is_supported()' .
1312
1313      In case the 'certfile' is provided as a PKCS '11' URL, then the
1314      certificate, and its present issuers in the token are are imported
1315      (i.e., the required trust chain).
1316
1317      If that function fails to load the 'res' structure is at an
1318      undefined state, it must not be reused to load other keys or
1319      certificates.
1320
1321      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1322      code.
1323
1324 gnutls_certificate_set_x509_key_mem
1325 -----------------------------------
1326
1327  -- Function: int gnutls_certificate_set_x509_key_mem
1328           (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
1329           CERT, const gnutls_datum_t * KEY, gnutls_x509_crt_fmt_t TYPE)
1330      RES: is a 'gnutls_certificate_credentials_t' structure.
1331
1332      CERT: contains a certificate list (path) for the specified private
1333      key
1334
1335      KEY: is the private key, or 'NULL'
1336
1337      TYPE: is PEM or DER
1338
1339      This function sets a certificate/private key pair in the
1340      gnutls_certificate_credentials_t structure.  This function may be
1341      called more than once, in case multiple keys/certificates exist for
1342      the server.
1343
1344      Note that the keyUsage (2.5.29.15) PKIX extension in X.509
1345      certificates is supported.  This means that certificates intended
1346      for signing cannot be used for ciphersuites that require
1347      encryption.
1348
1349      If the certificate and the private key are given in PEM encoding
1350      then the strings that hold their values must be null terminated.
1351
1352      The 'key' may be 'NULL' if you are using a sign callback, see
1353      'gnutls_sign_callback_set()' .
1354
1355      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1356      code.
1357
1358 gnutls_certificate_set_x509_key_mem2
1359 ------------------------------------
1360
1361  -- Function: int gnutls_certificate_set_x509_key_mem2
1362           (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
1363           CERT, const gnutls_datum_t * KEY, gnutls_x509_crt_fmt_t TYPE,
1364           const char * PASS, unsigned int FLAGS)
1365      RES: is a 'gnutls_certificate_credentials_t' structure.
1366
1367      CERT: contains a certificate list (path) for the specified private
1368      key
1369
1370      KEY: is the private key, or 'NULL'
1371
1372      TYPE: is PEM or DER
1373
1374      PASS: is the key's password
1375
1376      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
1377
1378      This function sets a certificate/private key pair in the
1379      gnutls_certificate_credentials_t structure.  This function may be
1380      called more than once, in case multiple keys/certificates exist for
1381      the server.
1382
1383      Note that the keyUsage (2.5.29.15) PKIX extension in X.509
1384      certificates is supported.  This means that certificates intended
1385      for signing cannot be used for ciphersuites that require
1386      encryption.
1387
1388      If the certificate and the private key are given in PEM encoding
1389      then the strings that hold their values must be null terminated.
1390
1391      The 'key' may be 'NULL' if you are using a sign callback, see
1392      'gnutls_sign_callback_set()' .
1393
1394      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1395      code.
1396
1397 gnutls_certificate_set_x509_simple_pkcs12_file
1398 ----------------------------------------------
1399
1400  -- Function: int gnutls_certificate_set_x509_simple_pkcs12_file
1401           (gnutls_certificate_credentials_t RES, const char *
1402           PKCS12FILE, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)
1403      RES: is a 'gnutls_certificate_credentials_t' structure.
1404
1405      PKCS12FILE: filename of file containing PKCS'12' blob.
1406
1407      TYPE: is PEM or DER of the 'pkcs12file' .
1408
1409      PASSWORD: optional password used to decrypt PKCS'12' file, bags and
1410      keys.
1411
1412      This function sets a certificate/private key pair and/or a CRL in
1413      the gnutls_certificate_credentials_t structure.  This function may
1414      be called more than once (in case multiple keys/certificates exist
1415      for the server).
1416
1417      PKCS'12' files with a MAC, encrypted bags and PKCS '8' private keys
1418      are supported.  However, only password based security, and the same
1419      password for all operations, are supported.
1420
1421      PKCS'12' file may contain many keys and/or certificates, and this
1422      function will try to auto-detect based on the key ID the
1423      certificate and key pair to use.  If the PKCS'12' file contain the
1424      issuer of the selected certificate, it will be appended to the
1425      certificate to form a chain.
1426
1427      If more than one private keys are stored in the PKCS'12' file, then
1428      only one key will be read (and it is undefined which one).
1429
1430      It is believed that the limitations of this function is acceptable
1431      for most usage, and that any more flexibility would introduce
1432      complexity that would make it harder to use this functionality at
1433      all.
1434
1435      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1436      code.
1437
1438 gnutls_certificate_set_x509_simple_pkcs12_mem
1439 ---------------------------------------------
1440
1441  -- Function: int gnutls_certificate_set_x509_simple_pkcs12_mem
1442           (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
1443           P12BLOB, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)
1444      RES: is a 'gnutls_certificate_credentials_t' structure.
1445
1446      P12BLOB: the PKCS'12' blob.
1447
1448      TYPE: is PEM or DER of the 'pkcs12file' .
1449
1450      PASSWORD: optional password used to decrypt PKCS'12' file, bags and
1451      keys.
1452
1453      This function sets a certificate/private key pair and/or a CRL in
1454      the gnutls_certificate_credentials_t structure.  This function may
1455      be called more than once (in case multiple keys/certificates exist
1456      for the server).
1457
1458      Encrypted PKCS'12' bags and PKCS'8' private keys are supported.
1459      However, only password based security, and the same password for
1460      all operations, are supported.
1461
1462      PKCS'12' file may contain many keys and/or certificates, and this
1463      function will try to auto-detect based on the key ID the
1464      certificate and key pair to use.  If the PKCS'12' file contain the
1465      issuer of the selected certificate, it will be appended to the
1466      certificate to form a chain.
1467
1468      If more than one private keys are stored in the PKCS'12' file, then
1469      only one key will be read (and it is undefined which one).
1470
1471      It is believed that the limitations of this function is acceptable
1472      for most usage, and that any more flexibility would introduce
1473      complexity that would make it harder to use this functionality at
1474      all.
1475
1476      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
1477      code.
1478
1479      *Since:* 2.8.0
1480
1481 gnutls_certificate_set_x509_system_trust
1482 ----------------------------------------
1483
1484  -- Function: int gnutls_certificate_set_x509_system_trust
1485           (gnutls_certificate_credentials_t CRED)
1486      CRED: is a 'gnutls_certificate_credentials_t' structure.
1487
1488      This function adds the system's default trusted CAs in order to
1489      verify client or server certificates.
1490
1491      In the case the system is currently unsupported
1492      'GNUTLS_E_UNIMPLEMENTED_FEATURE' is returned.
1493
1494      *Returns:* the number of certificates processed or a negative error
1495      code on error.
1496
1497      *Since:* 3.0.20
1498
1499 gnutls_certificate_set_x509_trust
1500 ---------------------------------
1501
1502  -- Function: int gnutls_certificate_set_x509_trust
1503           (gnutls_certificate_credentials_t RES, gnutls_x509_crt_t *
1504           CA_LIST, int CA_LIST_SIZE)
1505      RES: is a 'gnutls_certificate_credentials_t' structure.
1506
1507      CA_LIST: is a list of trusted CAs
1508
1509      CA_LIST_SIZE: holds the size of the CA list
1510
1511      This function adds the trusted CAs in order to verify client or
1512      server certificates.  In case of a client this is not required to
1513      be called if the certificates are not verified using
1514      'gnutls_certificate_verify_peers2()' .  This function may be called
1515      multiple times.
1516
1517      In case of a server the CAs set here will be sent to the client if
1518      a certificate request is sent.  This can be disabled using
1519      'gnutls_certificate_send_x509_rdn_sequence()' .
1520
1521      *Returns:* the number of certificates processed or a negative error
1522      code on error.
1523
1524      *Since:* 2.4.0
1525
1526 gnutls_certificate_set_x509_trust_dir
1527 -------------------------------------
1528
1529  -- Function: int gnutls_certificate_set_x509_trust_dir
1530           (gnutls_certificate_credentials_t CRED, const char * CA_DIR,
1531           gnutls_x509_crt_fmt_t TYPE)
1532      CRED: is a 'gnutls_certificate_credentials_t' structure.
1533
1534      CA_DIR: is a directory containing the list of trusted CAs (DER or
1535      PEM list)
1536
1537      TYPE: is PEM or DER
1538
1539      This function adds the trusted CAs present in the directory in
1540      order to verify client or server certificates.  This function is
1541      identical to 'gnutls_certificate_set_x509_trust_file()' but loads
1542      all certificates in a directory.
1543
1544      *Returns:* the number of certificates processed
1545
1546      *Since:* 3.3.6
1547
1548 gnutls_certificate_set_x509_trust_file
1549 --------------------------------------
1550
1551  -- Function: int gnutls_certificate_set_x509_trust_file
1552           (gnutls_certificate_credentials_t CRED, const char * CAFILE,
1553           gnutls_x509_crt_fmt_t TYPE)
1554      CRED: is a 'gnutls_certificate_credentials_t' structure.
1555
1556      CAFILE: is a file containing the list of trusted CAs (DER or PEM
1557      list)
1558
1559      TYPE: is PEM or DER
1560
1561      This function adds the trusted CAs in order to verify client or
1562      server certificates.  In case of a client this is not required to
1563      be called if the certificates are not verified using
1564      'gnutls_certificate_verify_peers2()' .  This function may be called
1565      multiple times.
1566
1567      In case of a server the names of the CAs set here will be sent to
1568      the client if a certificate request is sent.  This can be disabled
1569      using 'gnutls_certificate_send_x509_rdn_sequence()' .
1570
1571      This function can also accept URLs.  In that case it will import
1572      all certificates that are marked as trusted.  Note that the
1573      supported URLs are the ones indicated by
1574      'gnutls_url_is_supported()' .
1575
1576      *Returns:* the number of certificates processed
1577
1578 gnutls_certificate_set_x509_trust_mem
1579 -------------------------------------
1580
1581  -- Function: int gnutls_certificate_set_x509_trust_mem
1582           (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
1583           CA, gnutls_x509_crt_fmt_t TYPE)
1584      RES: is a 'gnutls_certificate_credentials_t' structure.
1585
1586      CA: is a list of trusted CAs or a DER certificate
1587
1588      TYPE: is DER or PEM
1589
1590      This function adds the trusted CAs in order to verify client or
1591      server certificates.  In case of a client this is not required to
1592      be called if the certificates are not verified using
1593      'gnutls_certificate_verify_peers2()' .  This function may be called
1594      multiple times.
1595
1596      In case of a server the CAs set here will be sent to the client if
1597      a certificate request is sent.  This can be disabled using
1598      'gnutls_certificate_send_x509_rdn_sequence()' .
1599
1600      *Returns:* the number of certificates processed or a negative error
1601      code on error.
1602
1603 gnutls_certificate_type_get
1604 ---------------------------
1605
1606  -- Function: gnutls_certificate_type_t gnutls_certificate_type_get
1607           (gnutls_session_t SESSION)
1608      SESSION: is a 'gnutls_session_t' structure.
1609
1610      The certificate type is by default X.509, unless it is negotiated
1611      as a TLS extension.
1612
1613      *Returns:* the currently used 'gnutls_certificate_type_t'
1614      certificate type.
1615
1616 gnutls_certificate_type_get_id
1617 ------------------------------
1618
1619  -- Function: gnutls_certificate_type_t gnutls_certificate_type_get_id
1620           (const char * NAME)
1621      NAME: is a certificate type name
1622
1623      The names are compared in a case insensitive way.
1624
1625      *Returns:* a 'gnutls_certificate_type_t' for the specified in a
1626      string certificate type, or 'GNUTLS_CRT_UNKNOWN' on error.
1627
1628 gnutls_certificate_type_get_name
1629 --------------------------------
1630
1631  -- Function: const char * gnutls_certificate_type_get_name
1632           (gnutls_certificate_type_t TYPE)
1633      TYPE: is a certificate type
1634
1635      Convert a 'gnutls_certificate_type_t' type to a string.
1636
1637      *Returns:* a string that contains the name of the specified
1638      certificate type, or 'NULL' in case of unknown types.
1639
1640 gnutls_certificate_type_list
1641 ----------------------------
1642
1643  -- Function: const gnutls_certificate_type_t *
1644           gnutls_certificate_type_list ( VOID)
1645
1646      Get a list of certificate types.
1647
1648      *Returns:* a (0)-terminated list of 'gnutls_certificate_type_t'
1649      integers indicating the available certificate types.
1650
1651 gnutls_certificate_verification_status_print
1652 --------------------------------------------
1653
1654  -- Function: int gnutls_certificate_verification_status_print (unsigned
1655           int STATUS, gnutls_certificate_type_t TYPE, gnutls_datum_t *
1656           OUT, unsigned int FLAGS)
1657      STATUS: The status flags to be printed
1658
1659      TYPE: The certificate type
1660
1661      OUT: Newly allocated datum with (0) terminated string.
1662
1663      FLAGS: should be zero
1664
1665      This function will pretty print the status of a verification
1666      process - eg.  the one obtained by
1667      'gnutls_certificate_verify_peers3()' .
1668
1669      The output 'out' needs to be deallocated using 'gnutls_free()' .
1670
1671      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1672      otherwise a negative error value.
1673
1674      *Since:* 3.1.4
1675
1676 gnutls_certificate_verify_peers
1677 -------------------------------
1678
1679  -- Function: int gnutls_certificate_verify_peers (gnutls_session_t
1680           SESSION, gnutls_typed_vdata_st * DATA, unsigned int ELEMENTS,
1681           unsigned int * STATUS)
1682      SESSION: is a gnutls session
1683
1684      DATA: an array of typed data
1685
1686      ELEMENTS: the number of data elements
1687
1688      STATUS: is the output of the verification
1689
1690      This function will verify the peer's certificate and store the
1691      status in the 'status' variable as a bitwise or'd
1692      gnutls_certificate_status_t values or zero if the certificate is
1693      trusted.  Note that value in 'status' is set only when the return
1694      value of this function is success (i.e, failure to trust a
1695      certificate does not imply a negative return value).  The default
1696      verification flags used by this function can be overridden using
1697      'gnutls_certificate_set_verify_flags()' .  See the documentation of
1698      'gnutls_certificate_verify_peers2()' for details in the
1699      verification process.
1700
1701      The acceptable 'data' types are 'GNUTLS_DT_DNS_HOSTNAME' and
1702      'GNUTLS_DT_KEY_PURPOSE_OID' .  The former accepts as data a
1703      null-terminated hostname, and the latter a null-terminated object
1704      identifier (e.g., 'GNUTLS_KP_TLS_WWW_SERVER' ).  If a DNS hostname
1705      is provided then this function will compare the hostname in the
1706      certificate against the given.  If names do not match the
1707      'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.  If a key
1708      purpose OID is provided and the end-certificate contains the
1709      extended key usage PKIX extension, it will be required to be have
1710      the provided key purpose or be marked for any purpose, otherwise
1711      verification will fail with
1712      'GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE' status.
1713
1714      *Returns:* a negative error code on error and 'GNUTLS_E_SUCCESS'
1715      (0) when the peer's certificate was successfully parsed,
1716      irrespective of whether it was verified.
1717
1718      *Since:* 3.3.0
1719
1720 gnutls_certificate_verify_peers2
1721 --------------------------------
1722
1723  -- Function: int gnutls_certificate_verify_peers2 (gnutls_session_t
1724           SESSION, unsigned int * STATUS)
1725      SESSION: is a gnutls session
1726
1727      STATUS: is the output of the verification
1728
1729      This function will verify the peer's certificate and store the
1730      status in the 'status' variable as a bitwise or'd
1731      gnutls_certificate_status_t values or zero if the certificate is
1732      trusted.  Note that value in 'status' is set only when the return
1733      value of this function is success (i.e, failure to trust a
1734      certificate does not imply a negative return value).  The default
1735      verification flags used by this function can be overridden using
1736      'gnutls_certificate_set_verify_flags()' .
1737
1738      This function will take into account the OCSP Certificate Status
1739      TLS extension, as well as the following X.509 certificate
1740      extensions: Name Constraints, Key Usage, and Basic Constraints
1741      (pathlen).
1742
1743      To avoid denial of service attacks some default upper limits
1744      regarding the certificate key size and chain size are set.  To
1745      override them use 'gnutls_certificate_set_verify_limits()' .
1746
1747      Note that you must also check the peer's name in order to check if
1748      the verified certificate belongs to the actual peer, see
1749      'gnutls_x509_crt_check_hostname()' , or use
1750      'gnutls_certificate_verify_peers3()' .
1751
1752      *Returns:* a negative error code on error and 'GNUTLS_E_SUCCESS'
1753      (0) when the peer's certificate was successfully parsed,
1754      irrespective of whether it was verified.
1755
1756 gnutls_certificate_verify_peers3
1757 --------------------------------
1758
1759  -- Function: int gnutls_certificate_verify_peers3 (gnutls_session_t
1760           SESSION, const char * HOSTNAME, unsigned int * STATUS)
1761      SESSION: is a gnutls session
1762
1763      HOSTNAME: is the expected name of the peer; may be 'NULL'
1764
1765      STATUS: is the output of the verification
1766
1767      This function will verify the peer's certificate and store the
1768      status in the 'status' variable as a bitwise or'd
1769      gnutls_certificate_status_t values or zero if the certificate is
1770      trusted.  Note that value in 'status' is set only when the return
1771      value of this function is success (i.e, failure to trust a
1772      certificate does not imply a negative return value).  The default
1773      verification flags used by this function can be overridden using
1774      'gnutls_certificate_set_verify_flags()' .  See the documentation of
1775      'gnutls_certificate_verify_peers2()' for details in the
1776      verification process.
1777
1778      If the 'hostname' provided is non-NULL then this function will
1779      compare the hostname in the certificate against the given.  The
1780      comparison will be accurate for ascii names; non-ascii names are
1781      compared byte-by-byte.  If names do not match the
1782      'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.
1783
1784      In order to verify the purpose of the end-certificate (by checking
1785      the extended key usage), use 'gnutls_certificate_verify_peers()' .
1786
1787      *Returns:* a negative error code on error and 'GNUTLS_E_SUCCESS'
1788      (0) when the peer's certificate was successfully parsed,
1789      irrespective of whether it was verified.
1790
1791      *Since:* 3.1.4
1792
1793 gnutls_check_version
1794 --------------------
1795
1796  -- Function: const char * gnutls_check_version (const char *
1797           REQ_VERSION)
1798      REQ_VERSION: version string to compare with, or 'NULL' .
1799
1800      Check GnuTLS Library version.
1801
1802      See 'GNUTLS_VERSION' for a suitable 'req_version' string.
1803
1804      *Returns:* Check that the version of the library is at minimum the
1805      one given as a string in 'req_version' and return the actual
1806      version string of the library; return 'NULL' if the condition is
1807      not met.  If 'NULL' is passed to this function no check is done and
1808      only the version string is returned.
1809
1810 gnutls_cipher_get
1811 -----------------
1812
1813  -- Function: gnutls_cipher_algorithm_t gnutls_cipher_get
1814           (gnutls_session_t SESSION)
1815      SESSION: is a 'gnutls_session_t' structure.
1816
1817      Get currently used cipher.
1818
1819      *Returns:* the currently used cipher, a 'gnutls_cipher_algorithm_t'
1820      type.
1821
1822 gnutls_cipher_get_id
1823 --------------------
1824
1825  -- Function: gnutls_cipher_algorithm_t gnutls_cipher_get_id (const char
1826           * NAME)
1827      NAME: is a cipher algorithm name
1828
1829      The names are compared in a case insensitive way.
1830
1831      *Returns:* return a 'gnutls_cipher_algorithm_t' value corresponding
1832      to the specified cipher, or 'GNUTLS_CIPHER_UNKNOWN' on error.
1833
1834 gnutls_cipher_get_key_size
1835 --------------------------
1836
1837  -- Function: size_t gnutls_cipher_get_key_size
1838           (gnutls_cipher_algorithm_t ALGORITHM)
1839      ALGORITHM: is an encryption algorithm
1840
1841      Get key size for cipher.
1842
1843      *Returns:* length (in bytes) of the given cipher's key size, or 0
1844      if the given cipher is invalid.
1845
1846 gnutls_cipher_get_name
1847 ----------------------
1848
1849  -- Function: const char * gnutls_cipher_get_name
1850           (gnutls_cipher_algorithm_t ALGORITHM)
1851      ALGORITHM: is an encryption algorithm
1852
1853      Convert a 'gnutls_cipher_algorithm_t' type to a string.
1854
1855      *Returns:* a pointer to a string that contains the name of the
1856      specified cipher, or 'NULL' .
1857
1858 gnutls_cipher_list
1859 ------------------
1860
1861  -- Function: const gnutls_cipher_algorithm_t * gnutls_cipher_list (
1862           VOID)
1863
1864      Get a list of supported cipher algorithms.  Note that not
1865      necessarily all ciphers are supported as TLS cipher suites.  For
1866      example, DES is not supported as a cipher suite, but is supported
1867      for other purposes (e.g., PKCS'8' or similar).
1868
1869      This function is not thread safe.
1870
1871      *Returns:* a (0)-terminated list of 'gnutls_cipher_algorithm_t'
1872      integers indicating the available ciphers.
1873
1874 gnutls_cipher_suite_get_name
1875 ----------------------------
1876
1877  -- Function: const char * gnutls_cipher_suite_get_name
1878           (gnutls_kx_algorithm_t KX_ALGORITHM, gnutls_cipher_algorithm_t
1879           CIPHER_ALGORITHM, gnutls_mac_algorithm_t MAC_ALGORITHM)
1880      KX_ALGORITHM: is a Key exchange algorithm
1881
1882      CIPHER_ALGORITHM: is a cipher algorithm
1883
1884      MAC_ALGORITHM: is a MAC algorithm
1885
1886      Note that the full cipher suite name must be prepended by TLS or
1887      SSL depending of the protocol in use.
1888
1889      *Returns:* a string that contains the name of a TLS cipher suite,
1890      specified by the given algorithms, or 'NULL' .
1891
1892 gnutls_cipher_suite_info
1893 ------------------------
1894
1895  -- Function: const char * gnutls_cipher_suite_info (size_t IDX,
1896           unsigned char * CS_ID, gnutls_kx_algorithm_t * KX,
1897           gnutls_cipher_algorithm_t * CIPHER, gnutls_mac_algorithm_t *
1898           MAC, gnutls_protocol_t * MIN_VERSION)
1899      IDX: index of cipher suite to get information about, starts on 0.
1900
1901      CS_ID: output buffer with room for 2 bytes, indicating cipher suite
1902      value
1903
1904      KX: output variable indicating key exchange algorithm, or 'NULL' .
1905
1906      CIPHER: output variable indicating cipher, or 'NULL' .
1907
1908      MAC: output variable indicating MAC algorithm, or 'NULL' .
1909
1910      MIN_VERSION: output variable indicating TLS protocol version, or
1911      'NULL' .
1912
1913      Get information about supported cipher suites.  Use the function
1914      iteratively to get information about all supported cipher suites.
1915      Call with idx=0 to get information about first cipher suite, then
1916      idx=1 and so on until the function returns NULL.
1917
1918      *Returns:* the name of 'idx' cipher suite, and set the information
1919      about the cipher suite in the output variables.  If 'idx' is out of
1920      bounds, 'NULL' is returned.
1921
1922 gnutls_compression_get
1923 ----------------------
1924
1925  -- Function: gnutls_compression_method_t gnutls_compression_get
1926           (gnutls_session_t SESSION)
1927      SESSION: is a 'gnutls_session_t' structure.
1928
1929      Get currently used compression algorithm.
1930
1931      *Returns:* the currently used compression method, a
1932      'gnutls_compression_method_t' value.
1933
1934 gnutls_compression_get_id
1935 -------------------------
1936
1937  -- Function: gnutls_compression_method_t gnutls_compression_get_id
1938           (const char * NAME)
1939      NAME: is a compression method name
1940
1941      The names are compared in a case insensitive way.
1942
1943      *Returns:* an id of the specified in a string compression method,
1944      or 'GNUTLS_COMP_UNKNOWN' on error.
1945
1946 gnutls_compression_get_name
1947 ---------------------------
1948
1949  -- Function: const char * gnutls_compression_get_name
1950           (gnutls_compression_method_t ALGORITHM)
1951      ALGORITHM: is a Compression algorithm
1952
1953      Convert a 'gnutls_compression_method_t' value to a string.
1954
1955      *Returns:* a pointer to a string that contains the name of the
1956      specified compression algorithm, or 'NULL' .
1957
1958 gnutls_compression_list
1959 -----------------------
1960
1961  -- Function: const gnutls_compression_method_t *
1962           gnutls_compression_list ( VOID)
1963
1964      Get a list of compression methods.
1965
1966      *Returns:* a zero-terminated list of 'gnutls_compression_method_t'
1967      integers indicating the available compression methods.
1968
1969 gnutls_credentials_clear
1970 ------------------------
1971
1972  -- Function: void gnutls_credentials_clear (gnutls_session_t SESSION)
1973      SESSION: is a 'gnutls_session_t' structure.
1974
1975      Clears all the credentials previously set in this session.
1976
1977 gnutls_credentials_get
1978 ----------------------
1979
1980  -- Function: int gnutls_credentials_get (gnutls_session_t SESSION,
1981           gnutls_credentials_type_t TYPE, void ** CRED)
1982      SESSION: is a 'gnutls_session_t' structure.
1983
1984      TYPE: is the type of the credentials to return
1985
1986      CRED: will contain the pointer to the credentials structure.
1987
1988      Returns the previously provided credentials structures.
1989
1990      For 'GNUTLS_CRD_ANON' , 'cred' will be
1991      'gnutls_anon_client_credentials_t' in case of a client.  In case of
1992      a server it should be 'gnutls_anon_server_credentials_t' .
1993
1994      For 'GNUTLS_CRD_SRP' , 'cred' will be
1995      'gnutls_srp_client_credentials_t' in case of a client, and
1996      'gnutls_srp_server_credentials_t' , in case of a server.
1997
1998      For 'GNUTLS_CRD_CERTIFICATE' , 'cred' will be
1999      'gnutls_certificate_credentials_t' .
2000
2001      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2002      otherwise a negative error code is returned.
2003
2004 gnutls_credentials_set
2005 ----------------------
2006
2007  -- Function: int gnutls_credentials_set (gnutls_session_t SESSION,
2008           gnutls_credentials_type_t TYPE, void * CRED)
2009      SESSION: is a 'gnutls_session_t' structure.
2010
2011      TYPE: is the type of the credentials
2012
2013      CRED: is a pointer to a structure.
2014
2015      Sets the needed credentials for the specified type.  Eg username,
2016      password - or public and private keys etc.  The 'cred' parameter is
2017      a structure that depends on the specified type and on the current
2018      session (client or server).
2019
2020      In order to minimize memory usage, and share credentials between
2021      several threads gnutls keeps a pointer to cred, and not the whole
2022      cred structure.  Thus you will have to keep the structure allocated
2023      until you call 'gnutls_deinit()' .
2024
2025      For 'GNUTLS_CRD_ANON' , 'cred' should be
2026      'gnutls_anon_client_credentials_t' in case of a client.  In case of
2027      a server it should be 'gnutls_anon_server_credentials_t' .
2028
2029      For 'GNUTLS_CRD_SRP' , 'cred' should be
2030      'gnutls_srp_client_credentials_t' in case of a client, and
2031      'gnutls_srp_server_credentials_t' , in case of a server.
2032
2033      For 'GNUTLS_CRD_CERTIFICATE' , 'cred' should be
2034      'gnutls_certificate_credentials_t' .
2035
2036      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2037      otherwise a negative error code is returned.
2038
2039 gnutls_db_check_entry
2040 ---------------------
2041
2042  -- Function: int gnutls_db_check_entry (gnutls_session_t SESSION,
2043           gnutls_datum_t SESSION_ENTRY)
2044      SESSION: is a 'gnutls_session_t' structure.
2045
2046      SESSION_ENTRY: is the session data (not key)
2047
2048      This function has no effect.
2049
2050      *Returns:* Returns 'GNUTLS_E_EXPIRED' , if the database entry has
2051      expired or 0 otherwise.
2052
2053 gnutls_db_check_entry_time
2054 --------------------------
2055
2056  -- Function: time_t gnutls_db_check_entry_time (gnutls_datum_t * ENTRY)
2057      ENTRY: is a pointer to a 'gnutls_datum_t' structure.
2058
2059      This function returns the time that this entry was active.  It can
2060      be used for database entry expiration.
2061
2062      *Returns:* The time this entry was created, or zero on error.
2063
2064 gnutls_db_get_default_cache_expiration
2065 --------------------------------------
2066
2067  -- Function: unsigned gnutls_db_get_default_cache_expiration ( VOID)
2068
2069      Returns the expiration time (in seconds) of stored sessions for
2070      resumption.
2071
2072 gnutls_db_get_ptr
2073 -----------------
2074
2075  -- Function: void * gnutls_db_get_ptr (gnutls_session_t SESSION)
2076      SESSION: is a 'gnutls_session_t' structure.
2077
2078      Get db function pointer.
2079
2080      *Returns:* the pointer that will be sent to db store, retrieve and
2081      delete functions, as the first argument.
2082
2083 gnutls_db_remove_session
2084 ------------------------
2085
2086  -- Function: void gnutls_db_remove_session (gnutls_session_t SESSION)
2087      SESSION: is a 'gnutls_session_t' structure.
2088
2089      This function will remove the current session data from the session
2090      database.  This will prevent future handshakes reusing these
2091      session data.  This function should be called if a session was
2092      terminated abnormally, and before 'gnutls_deinit()' is called.
2093
2094      Normally 'gnutls_deinit()' will remove abnormally terminated
2095      sessions.
2096
2097 gnutls_db_set_cache_expiration
2098 ------------------------------
2099
2100  -- Function: void gnutls_db_set_cache_expiration (gnutls_session_t
2101           SESSION, int SECONDS)
2102      SESSION: is a 'gnutls_session_t' structure.
2103
2104      SECONDS: is the number of seconds.
2105
2106      Set the expiration time for resumed sessions.  The default is 3600
2107      (one hour) at the time of this writing.
2108
2109 gnutls_db_set_ptr
2110 -----------------
2111
2112  -- Function: void gnutls_db_set_ptr (gnutls_session_t SESSION, void *
2113           PTR)
2114      SESSION: is a 'gnutls_session_t' structure.
2115
2116      PTR: is the pointer
2117
2118      Sets the pointer that will be provided to db store, retrieve and
2119      delete functions, as the first argument.
2120
2121 gnutls_db_set_remove_function
2122 -----------------------------
2123
2124  -- Function: void gnutls_db_set_remove_function (gnutls_session_t
2125           SESSION, gnutls_db_remove_func REM_FUNC)
2126      SESSION: is a 'gnutls_session_t' structure.
2127
2128      REM_FUNC: is the function.
2129
2130      Sets the function that will be used to remove data from the resumed
2131      sessions database.  This function must return 0 on success.
2132
2133      The first argument to 'rem_func' will be null unless
2134      'gnutls_db_set_ptr()' has been called.
2135
2136 gnutls_db_set_retrieve_function
2137 -------------------------------
2138
2139  -- Function: void gnutls_db_set_retrieve_function (gnutls_session_t
2140           SESSION, gnutls_db_retr_func RETR_FUNC)
2141      SESSION: is a 'gnutls_session_t' structure.
2142
2143      RETR_FUNC: is the function.
2144
2145      Sets the function that will be used to retrieve data from the
2146      resumed sessions database.  This function must return a
2147      gnutls_datum_t containing the data on success, or a gnutls_datum_t
2148      containing null and 0 on failure.
2149
2150      The datum's data must be allocated using the function
2151      'gnutls_malloc()' .
2152
2153      The first argument to 'retr_func' will be null unless
2154      'gnutls_db_set_ptr()' has been called.
2155
2156 gnutls_db_set_store_function
2157 ----------------------------
2158
2159  -- Function: void gnutls_db_set_store_function (gnutls_session_t
2160           SESSION, gnutls_db_store_func STORE_FUNC)
2161      SESSION: is a 'gnutls_session_t' structure.
2162
2163      STORE_FUNC: is the function
2164
2165      Sets the function that will be used to store data in the resumed
2166      sessions database.  This function must return 0 on success.
2167
2168      The first argument to 'store_func' will be null unless
2169      'gnutls_db_set_ptr()' has been called.
2170
2171 gnutls_deinit
2172 -------------
2173
2174  -- Function: void gnutls_deinit (gnutls_session_t SESSION)
2175      SESSION: is a 'gnutls_session_t' structure.
2176
2177      This function clears all buffers associated with the 'session' .
2178      This function will also remove session data from the session
2179      database if the session was terminated abnormally.
2180
2181 gnutls_dh_get_group
2182 -------------------
2183
2184  -- Function: int gnutls_dh_get_group (gnutls_session_t SESSION,
2185           gnutls_datum_t * RAW_GEN, gnutls_datum_t * RAW_PRIME)
2186      SESSION: is a gnutls session
2187
2188      RAW_GEN: will hold the generator.
2189
2190      RAW_PRIME: will hold the prime.
2191
2192      This function will return the group parameters used in the last
2193      Diffie-Hellman key exchange with the peer.  These are the prime and
2194      the generator used.  This function should be used for both
2195      anonymous and ephemeral Diffie-Hellman.  The output parameters must
2196      be freed with 'gnutls_free()' .
2197
2198      Note, that the prime and generator are exported as non-negative
2199      integers and may include a leading zero byte.
2200
2201      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2202      otherwise an error code is returned.
2203
2204 gnutls_dh_get_peers_public_bits
2205 -------------------------------
2206
2207  -- Function: int gnutls_dh_get_peers_public_bits (gnutls_session_t
2208           SESSION)
2209      SESSION: is a gnutls session
2210
2211      Get the Diffie-Hellman public key bit size.  Can be used for both
2212      anonymous and ephemeral Diffie-Hellman.
2213
2214      *Returns:* The public key bit size used in the last Diffie-Hellman
2215      key exchange with the peer, or a negative error code in case of
2216      error.
2217
2218 gnutls_dh_get_prime_bits
2219 ------------------------
2220
2221  -- Function: int gnutls_dh_get_prime_bits (gnutls_session_t SESSION)
2222      SESSION: is a gnutls session
2223
2224      This function will return the bits of the prime used in the last
2225      Diffie-Hellman key exchange with the peer.  Should be used for both
2226      anonymous and ephemeral Diffie-Hellman.  Note that some ciphers,
2227      like RSA and DSA without DHE, do not use a Diffie-Hellman key
2228      exchange, and then this function will return 0.
2229
2230      *Returns:* The Diffie-Hellman bit strength is returned, or 0 if no
2231      Diffie-Hellman key exchange was done, or a negative error code on
2232      failure.
2233
2234 gnutls_dh_get_pubkey
2235 --------------------
2236
2237  -- Function: int gnutls_dh_get_pubkey (gnutls_session_t SESSION,
2238           gnutls_datum_t * RAW_KEY)
2239      SESSION: is a gnutls session
2240
2241      RAW_KEY: will hold the public key.
2242
2243      This function will return the peer's public key used in the last
2244      Diffie-Hellman key exchange.  This function should be used for both
2245      anonymous and ephemeral Diffie-Hellman.  The output parameters must
2246      be freed with 'gnutls_free()' .
2247
2248      Note, that public key is exported as non-negative integer and may
2249      include a leading zero byte.
2250
2251      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2252      otherwise an error code is returned.
2253
2254 gnutls_dh_get_secret_bits
2255 -------------------------
2256
2257  -- Function: int gnutls_dh_get_secret_bits (gnutls_session_t SESSION)
2258      SESSION: is a gnutls session
2259
2260      This function will return the bits used in the last Diffie-Hellman
2261      key exchange with the peer.  Should be used for both anonymous and
2262      ephemeral Diffie-Hellman.
2263
2264      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2265      otherwise an error code is returned.
2266
2267 gnutls_dh_params_cpy
2268 --------------------
2269
2270  -- Function: int gnutls_dh_params_cpy (gnutls_dh_params_t DST,
2271           gnutls_dh_params_t SRC)
2272      DST: Is the destination structure, which should be initialized.
2273
2274      SRC: Is the source structure
2275
2276      This function will copy the DH parameters structure from source to
2277      destination.
2278
2279      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2280      otherwise a negative error code is returned.
2281
2282 gnutls_dh_params_deinit
2283 -----------------------
2284
2285  -- Function: void gnutls_dh_params_deinit (gnutls_dh_params_t
2286           DH_PARAMS)
2287      DH_PARAMS: Is a structure that holds the prime numbers
2288
2289      This function will deinitialize the DH parameters structure.
2290
2291 gnutls_dh_params_export2_pkcs3
2292 ------------------------------
2293
2294  -- Function: int gnutls_dh_params_export2_pkcs3 (gnutls_dh_params_t
2295           PARAMS, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
2296      PARAMS: Holds the DH parameters
2297
2298      FORMAT: the format of output params.  One of PEM or DER.
2299
2300      OUT: will contain a PKCS3 DHParams structure PEM or DER encoded
2301
2302      This function will export the given dh parameters to a PKCS3
2303      DHParams structure.  This is the format generated by "openssl
2304      dhparam" tool.  The data in 'out' will be allocated using
2305      'gnutls_malloc()' .
2306
2307      If the structure is PEM encoded, it will have a header of "BEGIN DH
2308      PARAMETERS".
2309
2310      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2311      otherwise a negative error code is returned.
2312
2313      *Since:* 3.1.3
2314
2315 gnutls_dh_params_export_pkcs3
2316 -----------------------------
2317
2318  -- Function: int gnutls_dh_params_export_pkcs3 (gnutls_dh_params_t
2319           PARAMS, gnutls_x509_crt_fmt_t FORMAT, unsigned char *
2320           PARAMS_DATA, size_t * PARAMS_DATA_SIZE)
2321      PARAMS: Holds the DH parameters
2322
2323      FORMAT: the format of output params.  One of PEM or DER.
2324
2325      PARAMS_DATA: will contain a PKCS3 DHParams structure PEM or DER
2326      encoded
2327
2328      PARAMS_DATA_SIZE: holds the size of params_data (and will be
2329      replaced by the actual size of parameters)
2330
2331      This function will export the given dh parameters to a PKCS3
2332      DHParams structure.  This is the format generated by "openssl
2333      dhparam" tool.  If the buffer provided is not long enough to hold
2334      the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
2335
2336      If the structure is PEM encoded, it will have a header of "BEGIN DH
2337      PARAMETERS".
2338
2339      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2340      otherwise a negative error code is returned.
2341
2342 gnutls_dh_params_export_raw
2343 ---------------------------
2344
2345  -- Function: int gnutls_dh_params_export_raw (gnutls_dh_params_t
2346           PARAMS, gnutls_datum_t * PRIME, gnutls_datum_t * GENERATOR,
2347           unsigned int * BITS)
2348      PARAMS: Holds the DH parameters
2349
2350      PRIME: will hold the new prime
2351
2352      GENERATOR: will hold the new generator
2353
2354      BITS: if non null will hold the secret key's number of bits
2355
2356      This function will export the pair of prime and generator for use
2357      in the Diffie-Hellman key exchange.  The new parameters will be
2358      allocated using 'gnutls_malloc()' and will be stored in the
2359      appropriate datum.
2360
2361      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2362      otherwise a negative error code is returned.
2363
2364 gnutls_dh_params_generate2
2365 --------------------------
2366
2367  -- Function: int gnutls_dh_params_generate2 (gnutls_dh_params_t
2368           DPARAMS, unsigned int BITS)
2369      DPARAMS: Is the structure that the DH parameters will be stored
2370
2371      BITS: is the prime's number of bits
2372
2373      This function will generate a new pair of prime and generator for
2374      use in the Diffie-Hellman key exchange.  The new parameters will be
2375      allocated using 'gnutls_malloc()' and will be stored in the
2376      appropriate datum.  This function is normally slow.
2377
2378      Do not set the number of bits directly, use
2379      'gnutls_sec_param_to_pk_bits()' to get bits for 'GNUTLS_PK_DSA' .
2380      Also note that the DH parameters are only useful to servers.  Since
2381      clients use the parameters sent by the server, it's of no use to
2382      call this in client side.
2383
2384      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2385      otherwise a negative error code is returned.
2386
2387 gnutls_dh_params_import_pkcs3
2388 -----------------------------
2389
2390  -- Function: int gnutls_dh_params_import_pkcs3 (gnutls_dh_params_t
2391           PARAMS, const gnutls_datum_t * PKCS3_PARAMS,
2392           gnutls_x509_crt_fmt_t FORMAT)
2393      PARAMS: A structure where the parameters will be copied to
2394
2395      PKCS3_PARAMS: should contain a PKCS3 DHParams structure PEM or DER
2396      encoded
2397
2398      FORMAT: the format of params.  PEM or DER.
2399
2400      This function will extract the DHParams found in a PKCS3 formatted
2401      structure.  This is the format generated by "openssl dhparam" tool.
2402
2403      If the structure is PEM encoded, it should have a header of "BEGIN
2404      DH PARAMETERS".
2405
2406      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2407      otherwise a negative error code is returned.
2408
2409 gnutls_dh_params_import_raw
2410 ---------------------------
2411
2412  -- Function: int gnutls_dh_params_import_raw (gnutls_dh_params_t
2413           DH_PARAMS, const gnutls_datum_t * PRIME, const gnutls_datum_t
2414           * GENERATOR)
2415      DH_PARAMS: Is a structure that will hold the prime numbers
2416
2417      PRIME: holds the new prime
2418
2419      GENERATOR: holds the new generator
2420
2421      This function will replace the pair of prime and generator for use
2422      in the Diffie-Hellman key exchange.  The new parameters should be
2423      stored in the appropriate gnutls_datum.
2424
2425      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2426      otherwise a negative error code is returned.
2427
2428 gnutls_dh_params_init
2429 ---------------------
2430
2431  -- Function: int gnutls_dh_params_init (gnutls_dh_params_t * DH_PARAMS)
2432      DH_PARAMS: Is a structure that will hold the prime numbers
2433
2434      This function will initialize the DH parameters structure.
2435
2436      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2437      otherwise a negative error code is returned.
2438
2439 gnutls_dh_set_prime_bits
2440 ------------------------
2441
2442  -- Function: void gnutls_dh_set_prime_bits (gnutls_session_t SESSION,
2443           unsigned int BITS)
2444      SESSION: is a 'gnutls_session_t' structure.
2445
2446      BITS: is the number of bits
2447
2448      This function sets the number of bits, for use in a Diffie-Hellman
2449      key exchange.  This is used both in DH ephemeral and DH anonymous
2450      cipher suites.  This will set the minimum size of the prime that
2451      will be used for the handshake.
2452
2453      In the client side it sets the minimum accepted number of bits.  If
2454      a server sends a prime with less bits than that
2455      'GNUTLS_E_DH_PRIME_UNACCEPTABLE' will be returned by the handshake.
2456
2457      Note that this function will warn via the audit log for value that
2458      are believed to be weak.
2459
2460      The function has no effect in server side.
2461
2462      Note that since 3.1.7 this function is deprecated.  The minimum
2463      number of bits is set by the priority string level.  Also this
2464      function must be called after 'gnutls_priority_set_direct()' or the
2465      set value may be overridden by the selected priority options.
2466
2467 gnutls_digest_get_id
2468 --------------------
2469
2470  -- Function: gnutls_digest_algorithm_t gnutls_digest_get_id (const char
2471           * NAME)
2472      NAME: is a digest algorithm name
2473
2474      Convert a string to a 'gnutls_digest_algorithm_t' value.  The names
2475      are compared in a case insensitive way.
2476
2477      *Returns:* a 'gnutls_digest_algorithm_t' id of the specified MAC
2478      algorithm string, or 'GNUTLS_DIG_UNKNOWN' on failures.
2479
2480 gnutls_digest_get_name
2481 ----------------------
2482
2483  -- Function: const char * gnutls_digest_get_name
2484           (gnutls_digest_algorithm_t ALGORITHM)
2485      ALGORITHM: is a digest algorithm
2486
2487      Convert a 'gnutls_digest_algorithm_t' value to a string.
2488
2489      *Returns:* a string that contains the name of the specified digest
2490      algorithm, or 'NULL' .
2491
2492 gnutls_digest_list
2493 ------------------
2494
2495  -- Function: const gnutls_digest_algorithm_t * gnutls_digest_list (
2496           VOID)
2497
2498      Get a list of hash (digest) algorithms supported by GnuTLS.
2499
2500      This function is not thread safe.
2501
2502      *Returns:* Return a (0)-terminated list of
2503      'gnutls_digest_algorithm_t' integers indicating the available
2504      digests.
2505
2506 gnutls_ecc_curve_get
2507 --------------------
2508
2509  -- Function: gnutls_ecc_curve_t gnutls_ecc_curve_get (gnutls_session_t
2510           SESSION)
2511      SESSION: is a 'gnutls_session_t' structure.
2512
2513      Returns the currently used elliptic curve.  Only valid when using
2514      an elliptic curve ciphersuite.
2515
2516      *Returns:* the currently used curve, a 'gnutls_ecc_curve_t' type.
2517
2518      *Since:* 3.0
2519
2520 gnutls_ecc_curve_get_name
2521 -------------------------
2522
2523  -- Function: const char * gnutls_ecc_curve_get_name (gnutls_ecc_curve_t
2524           CURVE)
2525      CURVE: is an ECC curve
2526
2527      Convert a 'gnutls_ecc_curve_t' value to a string.
2528
2529      *Returns:* a string that contains the name of the specified curve
2530      or 'NULL' .
2531
2532      *Since:* 3.0
2533
2534 gnutls_ecc_curve_get_size
2535 -------------------------
2536
2537  -- Function: int gnutls_ecc_curve_get_size (gnutls_ecc_curve_t CURVE)
2538      CURVE: is an ECC curve
2539
2540      Returns the size in bytes of the curve.
2541
2542      *Returns:* a the size or (0).
2543
2544      *Since:* 3.0
2545
2546 gnutls_ecc_curve_list
2547 ---------------------
2548
2549  -- Function: const gnutls_ecc_curve_t * gnutls_ecc_curve_list ( VOID)
2550
2551      Get the list of supported elliptic curves.
2552
2553      This function is not thread safe.
2554
2555      *Returns:* Return a (0)-terminated list of 'gnutls_ecc_curve_t'
2556      integers indicating the available curves.
2557
2558 gnutls_error_is_fatal
2559 ---------------------
2560
2561  -- Function: int gnutls_error_is_fatal (int ERROR)
2562      ERROR: is a GnuTLS error code, a negative error code
2563
2564      If a GnuTLS function returns a negative error code you may feed
2565      that value to this function to see if the error condition is fatal
2566      to a TLS session (i.e., must be terminated).
2567
2568      Note that you may also want to check the error code manually, since
2569      some non-fatal errors to the protocol (such as a warning alert or a
2570      rehandshake request) may be fatal for your program.
2571
2572      This function is only useful if you are dealing with errors from
2573      functions that relate to a TLS session (e.g., record layer or
2574      handshake layer handling functions).
2575
2576      *Returns:* Non-zero value on fatal errors or zero on non-fatal.
2577
2578 gnutls_error_to_alert
2579 ---------------------
2580
2581  -- Function: int gnutls_error_to_alert (int ERR, int * LEVEL)
2582      ERR: is a negative integer
2583
2584      LEVEL: the alert level will be stored there
2585
2586      Get an alert depending on the error code returned by a gnutls
2587      function.  All alerts sent by this function should be considered
2588      fatal.  The only exception is when 'err' is 'GNUTLS_E_REHANDSHAKE'
2589      , where a warning alert should be sent to the peer indicating that
2590      no renegotiation will be performed.
2591
2592      If there is no mapping to a valid alert the alert to indicate
2593      internal error is returned.
2594
2595      *Returns:* the alert code to use for a particular error code.
2596
2597 gnutls_est_record_overhead_size
2598 -------------------------------
2599
2600  -- Function: size_t gnutls_est_record_overhead_size (gnutls_protocol_t
2601           VERSION, gnutls_cipher_algorithm_t CIPHER,
2602           gnutls_mac_algorithm_t MAC, gnutls_compression_method_t COMP,
2603           unsigned int FLAGS)
2604      VERSION: is a 'gnutls_protocol_t' value
2605
2606      CIPHER: is a 'gnutls_cipher_algorithm_t' value
2607
2608      MAC: is a 'gnutls_mac_algorithm_t' value
2609
2610      COMP: is a 'gnutls_compression_method_t' value
2611
2612      FLAGS: must be zero
2613
2614      This function will return the set size in bytes of the overhead due
2615      to TLS (or DTLS) per record.
2616
2617      Note that this function may provide inacurate values when TLS
2618      extensions that modify the record format are negotiated.  In these
2619      cases a more accurate value can be obtained using
2620      'gnutls_record_overhead_size()' after a completed handshake.
2621
2622      *Since:* 3.2.2
2623
2624 gnutls_fingerprint
2625 ------------------
2626
2627  -- Function: int gnutls_fingerprint (gnutls_digest_algorithm_t ALGO,
2628           const gnutls_datum_t * DATA, void * RESULT, size_t *
2629           RESULT_SIZE)
2630      ALGO: is a digest algorithm
2631
2632      DATA: is the data
2633
2634      RESULT: is the place where the result will be copied (may be null).
2635
2636      RESULT_SIZE: should hold the size of the result.  The actual size
2637      of the returned result will also be copied there.
2638
2639      This function will calculate a fingerprint (actually a hash), of
2640      the given data.  The result is not printable data.  You should
2641      convert it to hex, or to something else printable.
2642
2643      This is the usual way to calculate a fingerprint of an X.509 DER
2644      encoded certificate.  Note however that the fingerprint of an
2645      OpenPGP certificate is not just a hash and cannot be calculated
2646      with this function.
2647
2648      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2649      otherwise an error code is returned.
2650
2651 gnutls_fips140_mode_enabled
2652 ---------------------------
2653
2654  -- Function: int gnutls_fips140_mode_enabled ( VOID)
2655
2656      Checks whether this library is in FIPS140 mode.
2657
2658      *Returns:* return non-zero if true or zero if false.
2659
2660      *Since:* 3.3.0
2661
2662 gnutls_global_deinit
2663 --------------------
2664
2665  -- Function: void gnutls_global_deinit ( VOID)
2666
2667      This function deinitializes the global data, that were initialized
2668      using 'gnutls_global_init()' .
2669
2670 gnutls_global_init
2671 ------------------
2672
2673  -- Function: int gnutls_global_init ( VOID)
2674
2675      This function performs any required precalculations, detects the
2676      supported CPU capabilities and initializes the underlying
2677      cryptographic backend.  In order to free any resources taken by
2678      this call you should 'gnutls_global_deinit()' when gnutls usage is
2679      no longer needed.
2680
2681      This function increments a global counter, so that
2682      'gnutls_global_deinit()' only releases resources when it has been
2683      called as many times as 'gnutls_global_init()' .  This is useful
2684      when GnuTLS is used by more than one library in an application.
2685      This function can be called many times, but will only do something
2686      the first time.
2687
2688      Since GnuTLS 3.3.0 this function is only required in systems that
2689      do not support library constructors and static linking.  This
2690      function also became thread safe.
2691
2692      A subsequent call of this function if the initial has failed will
2693      return the same error code.
2694
2695      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2696      otherwise a negative error code is returned.
2697
2698 gnutls_global_set_audit_log_function
2699 ------------------------------------
2700
2701  -- Function: void gnutls_global_set_audit_log_function
2702           (gnutls_audit_log_func LOG_FUNC)
2703      LOG_FUNC: it is the audit log function
2704
2705      This is the function to set the audit logging function.  This is a
2706      function to report important issues, such as possible attacks in
2707      the protocol.  This is different from
2708      'gnutls_global_set_log_function()' because it will report also
2709      session-specific events.  The session parameter will be null if
2710      there is no corresponding TLS session.
2711
2712      'gnutls_audit_log_func' is of the form, void
2713      (*gnutls_audit_log_func)( gnutls_session_t, const char*);
2714
2715      *Since:* 3.0
2716
2717 gnutls_global_set_log_function
2718 ------------------------------
2719
2720  -- Function: void gnutls_global_set_log_function (gnutls_log_func
2721           LOG_FUNC)
2722      LOG_FUNC: it's a log function
2723
2724      This is the function where you set the logging function gnutls is
2725      going to use.  This function only accepts a character array.
2726      Normally you may not use this function since it is only used for
2727      debugging purposes.
2728
2729      'gnutls_log_func' is of the form, void (*gnutls_log_func)( int
2730      level, const char*);
2731
2732 gnutls_global_set_log_level
2733 ---------------------------
2734
2735  -- Function: void gnutls_global_set_log_level (int LEVEL)
2736      LEVEL: it's an integer from 0 to 99.
2737
2738      This is the function that allows you to set the log level.  The
2739      level is an integer between 0 and 9.  Higher values mean more
2740      verbosity.  The default value is 0.  Larger values should only be
2741      used with care, since they may reveal sensitive information.
2742
2743      Use a log level over 10 to enable all debugging options.
2744
2745 gnutls_global_set_mutex
2746 -----------------------
2747
2748  -- Function: void gnutls_global_set_mutex (mutex_init_func INIT,
2749           mutex_deinit_func DEINIT, mutex_lock_func LOCK,
2750           mutex_unlock_func UNLOCK)
2751      INIT: mutex initialization function
2752
2753      DEINIT: mutex deinitialization function
2754
2755      LOCK: mutex locking function
2756
2757      UNLOCK: mutex unlocking function
2758
2759      With this function you are allowed to override the default mutex
2760      locks used in some parts of gnutls and dependent libraries.  This
2761      function should be used if you have complete control of your
2762      program and libraries.  Do not call this function from a library,
2763      or preferrably from any application unless really needed to.
2764      GnuTLS will use the appropriate locks for the running system.
2765
2766      This function must be called prior to any other gnutls function.
2767
2768      *Since:* 2.12.0
2769
2770 gnutls_global_set_time_function
2771 -------------------------------
2772
2773  -- Function: void gnutls_global_set_time_function (gnutls_time_func
2774           TIME_FUNC)
2775      TIME_FUNC: it's the system time function, a 'gnutls_time_func()'
2776      callback.
2777
2778      This is the function where you can override the default system time
2779      function.  The application provided function should behave the same
2780      as the standard function.
2781
2782      *Since:* 2.12.0
2783
2784 gnutls_handshake
2785 ----------------
2786
2787  -- Function: int gnutls_handshake (gnutls_session_t SESSION)
2788      SESSION: is a 'gnutls_session_t' structure.
2789
2790      This function does the handshake of the TLS/SSL protocol, and
2791      initializes the TLS connection.
2792
2793      This function will fail if any problem is encountered, and will
2794      return a negative error code.  In case of a client, if the client
2795      has asked to resume a session, but the server couldn't, then a full
2796      handshake will be performed.
2797
2798      The non-fatal errors expected by this function are:
2799      'GNUTLS_E_INTERRUPTED' , 'GNUTLS_E_AGAIN' ,
2800      'GNUTLS_E_WARNING_ALERT_RECEIVED' , and
2801      'GNUTLS_E_GOT_APPLICATION_DATA' , the latter only in a case of
2802      rehandshake.
2803
2804      The former two interrupt the handshake procedure due to the lower
2805      layer being interrupted, and the latter because of an alert that
2806      may be sent by a server (it is always a good idea to check any
2807      received alerts).  On these errors call this function again, until
2808      it returns 0; cf.  'gnutls_record_get_direction()' and
2809      'gnutls_error_is_fatal()' .  In DTLS sessions the non-fatal error
2810      'GNUTLS_E_LARGE_PACKET' is also possible, and indicates that the
2811      MTU should be adjusted.
2812
2813      If this function is called by a server after a rehandshake request
2814      then 'GNUTLS_E_GOT_APPLICATION_DATA' or
2815      'GNUTLS_E_WARNING_ALERT_RECEIVED' may be returned.  Note that these
2816      are non fatal errors, only in the specific case of a rehandshake.
2817      Their meaning is that the client rejected the rehandshake request
2818      or in the case of 'GNUTLS_E_GOT_APPLICATION_DATA' it could also
2819      mean that some data were pending.
2820
2821      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
2822      error code.
2823
2824 gnutls_handshake_description_get_name
2825 -------------------------------------
2826
2827  -- Function: const char * gnutls_handshake_description_get_name
2828           (gnutls_handshake_description_t TYPE)
2829      TYPE: is a handshake message description
2830
2831      Convert a 'gnutls_handshake_description_t' value to a string.
2832
2833      *Returns:* a string that contains the name of the specified
2834      handshake message or 'NULL' .
2835
2836 gnutls_handshake_get_last_in
2837 ----------------------------
2838
2839  -- Function: gnutls_handshake_description_t
2840           gnutls_handshake_get_last_in (gnutls_session_t SESSION)
2841      SESSION: is a 'gnutls_session_t' structure.
2842
2843      This function is only useful to check where the last performed
2844      handshake failed.  If the previous handshake succeed or was not
2845      performed at all then no meaningful value will be returned.
2846
2847      Check 'gnutls_handshake_description_t' in gnutls.h for the
2848      available handshake descriptions.
2849
2850      *Returns:* the last handshake message type received, a
2851      'gnutls_handshake_description_t' .
2852
2853 gnutls_handshake_get_last_out
2854 -----------------------------
2855
2856  -- Function: gnutls_handshake_description_t
2857           gnutls_handshake_get_last_out (gnutls_session_t SESSION)
2858      SESSION: is a 'gnutls_session_t' structure.
2859
2860      This function is only useful to check where the last performed
2861      handshake failed.  If the previous handshake succeed or was not
2862      performed at all then no meaningful value will be returned.
2863
2864      Check 'gnutls_handshake_description_t' in gnutls.h for the
2865      available handshake descriptions.
2866
2867      *Returns:* the last handshake message type sent, a
2868      'gnutls_handshake_description_t' .
2869
2870 gnutls_handshake_set_hook_function
2871 ----------------------------------
2872
2873  -- Function: void gnutls_handshake_set_hook_function (gnutls_session_t
2874           SESSION, unsigned int HTYPE, int POST,
2875           gnutls_handshake_hook_func FUNC)
2876      SESSION: is a 'gnutls_session_t' structure
2877
2878      HTYPE: the 'gnutls_handshake_description_t' of the message to hook
2879      at
2880
2881      POST: 'GNUTLS_HOOK_' * depending on when the hook function should
2882      be called
2883
2884      FUNC: is the function to be called
2885
2886      This function will set a callback to be called after or before the
2887      specified handshake message has been received or generated.  This
2888      is a generalization of
2889      'gnutls_handshake_set_post_client_hello_function()' .
2890
2891      To call the hook function prior to the message being sent/generated
2892      use 'GNUTLS_HOOK_PRE' as 'post' parameter, 'GNUTLS_HOOK_POST' to
2893      call after, and 'GNUTLS_HOOK_BOTH' for both cases.
2894
2895      This callback must return 0 on success or a gnutls error code to
2896      terminate the handshake.
2897
2898      Note to hook at all handshake messages use an 'htype' of
2899      'GNUTLS_HANDSHAKE_ANY' .
2900
2901      *Warning:* You should not use this function to terminate the
2902      handshake based on client input unless you know what you are doing.
2903      Before the handshake is finished there is no way to know if there
2904      is a man-in-the-middle attack being performed.
2905
2906 gnutls_handshake_set_max_packet_length
2907 --------------------------------------
2908
2909  -- Function: void gnutls_handshake_set_max_packet_length
2910           (gnutls_session_t SESSION, size_t MAX)
2911      SESSION: is a 'gnutls_session_t' structure.
2912
2913      MAX: is the maximum number.
2914
2915      This function will set the maximum size of all handshake messages.
2916      Handshakes over this size are rejected with
2917      'GNUTLS_E_HANDSHAKE_TOO_LARGE' error code.  The default value is
2918      128kb which is typically large enough.  Set this to 0 if you do not
2919      want to set an upper limit.
2920
2921      The reason for restricting the handshake message sizes are to limit
2922      Denial of Service attacks.
2923
2924      Note that the maximum handshake size was increased to 128kb from
2925      48kb in GnuTLS 3.3.25.
2926
2927 gnutls_handshake_set_post_client_hello_function
2928 -----------------------------------------------
2929
2930  -- Function: void gnutls_handshake_set_post_client_hello_function
2931           (gnutls_session_t SESSION,
2932           gnutls_handshake_post_client_hello_func FUNC)
2933      SESSION: is a 'gnutls_session_t' structure.
2934
2935      FUNC: is the function to be called
2936
2937      This function will set a callback to be called after the client
2938      hello has been received (callback valid in server side only).  This
2939      allows the server to adjust settings based on received extensions.
2940
2941      Those settings could be ciphersuites, requesting certificate, or
2942      anything else except for version negotiation (this is done before
2943      the hello message is parsed).
2944
2945      This callback must return 0 on success or a gnutls error code to
2946      terminate the handshake.
2947
2948      Since GnuTLS 3.3.5 the callback is allowed to return
2949      'GNUTLS_E_AGAIN' or 'GNUTLS_E_INTERRUPTED' to put the handshake on
2950      hold.  In that case 'gnutls_handshake()' will return
2951      'GNUTLS_E_INTERRUPTED' and can be resumed when needed.
2952
2953      *Warning:* You should not use this function to terminate the
2954      handshake based on client input unless you know what you are doing.
2955      Before the handshake is finished there is no way to know if there
2956      is a man-in-the-middle attack being performed.
2957
2958 gnutls_handshake_set_private_extensions
2959 ---------------------------------------
2960
2961  -- Function: void gnutls_handshake_set_private_extensions
2962           (gnutls_session_t SESSION, int ALLOW)
2963      SESSION: is a 'gnutls_session_t' structure.
2964
2965      ALLOW: is an integer (0 or 1)
2966
2967      This function will enable or disable the use of private cipher
2968      suites (the ones that start with 0xFF). By default or if 'allow' is
2969      0 then these cipher suites will not be advertised nor used.
2970
2971      Currently GnuTLS does not include such cipher-suites or compression
2972      algorithms.
2973
2974      Enabling the private ciphersuites when talking to other than gnutls
2975      servers and clients may cause interoperability problems.
2976
2977 gnutls_handshake_set_random
2978 ---------------------------
2979
2980  -- Function: int gnutls_handshake_set_random (gnutls_session_t SESSION,
2981           const gnutls_datum_t * RANDOM)
2982      SESSION: is a 'gnutls_session_t' structure.
2983
2984      RANDOM: a random value of 32-bytes
2985
2986      This function will explicitly set the server or client hello random
2987      value in the subsequent TLS handshake.  The random value should be
2988      a 32-byte value.
2989
2990      Note that this function should not normally be used as gnutls will
2991      select automatically a random value for the handshake.
2992
2993      This function should not be used when resuming a session.
2994
2995      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2996
2997      Since 3.1.9
2998
2999 gnutls_handshake_set_timeout
3000 ----------------------------
3001
3002  -- Function: void gnutls_handshake_set_timeout (gnutls_session_t
3003           SESSION, unsigned int MS)
3004      SESSION: is a 'gnutls_session_t' structure.
3005
3006      MS: is a timeout value in milliseconds
3007
3008      This function sets the timeout for the handshake process to the
3009      provided value.  Use an 'ms' value of zero to disable timeout, or
3010      'GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT' for a reasonable default value.
3011
3012      *Since:* 3.1.0
3013
3014 gnutls_heartbeat_allowed
3015 ------------------------
3016
3017  -- Function: int gnutls_heartbeat_allowed (gnutls_session_t SESSION,
3018           unsigned int TYPE)
3019      SESSION: is a 'gnutls_session_t' structure.
3020
3021      TYPE: one of 'GNUTLS_HB_LOCAL_ALLOWED_TO_SEND' and
3022      'GNUTLS_HB_PEER_ALLOWED_TO_SEND'
3023
3024      This function will check whether heartbeats are allowed to be sent
3025      or received in this session.
3026
3027      *Returns:* Non zero if heartbeats are allowed.
3028
3029      *Since:* 3.1.2
3030
3031 gnutls_heartbeat_enable
3032 -----------------------
3033
3034  -- Function: void gnutls_heartbeat_enable (gnutls_session_t SESSION,
3035           unsigned int TYPE)
3036      SESSION: is a 'gnutls_session_t' structure.
3037
3038      TYPE: one of the GNUTLS_HB_* flags
3039
3040      If this function is called with the
3041      'GNUTLS_HB_PEER_ALLOWED_TO_SEND' 'type' , GnuTLS will allow
3042      heartbeat messages to be received.  Moreover it also request the
3043      peer to accept heartbeat messages.
3044
3045      If the 'type' used is 'GNUTLS_HB_LOCAL_ALLOWED_TO_SEND' , then the
3046      peer will be asked to accept heartbeat messages but not send ones.
3047
3048      The function 'gnutls_heartbeat_allowed()' can be used to test
3049      Whether locally generated heartbeat messages can be accepted by the
3050      peer.
3051
3052      *Since:* 3.1.2
3053
3054 gnutls_heartbeat_get_timeout
3055 ----------------------------
3056
3057  -- Function: unsigned int gnutls_heartbeat_get_timeout
3058           (gnutls_session_t SESSION)
3059      SESSION: is a 'gnutls_session_t' structure.
3060
3061      This function will return the milliseconds remaining for a
3062      retransmission of the previously sent ping message.  This function
3063      is useful when ping is used in non-blocking mode, to estimate when
3064      to call 'gnutls_heartbeat_ping()' if no packets have been received.
3065
3066      *Returns:* the remaining time in milliseconds.
3067
3068      *Since:* 3.1.2
3069
3070 gnutls_heartbeat_ping
3071 ---------------------
3072
3073  -- Function: int gnutls_heartbeat_ping (gnutls_session_t SESSION,
3074           size_t DATA_SIZE, unsigned int MAX_TRIES, unsigned int FLAGS)
3075      SESSION: is a 'gnutls_session_t' structure.
3076
3077      DATA_SIZE: is the length of the ping payload.
3078
3079      MAX_TRIES: if flags is 'GNUTLS_HEARTBEAT_WAIT' then this sets the
3080      number of retransmissions.  Use zero for indefinite (until
3081      timeout).
3082
3083      FLAGS: if 'GNUTLS_HEARTBEAT_WAIT' then wait for pong or timeout
3084      instead of returning immediately.
3085
3086      This function sends a ping to the peer.  If the 'flags' is set to
3087      'GNUTLS_HEARTBEAT_WAIT' then it waits for a reply from the peer.
3088
3089      Note that it is highly recommended to use this function with the
3090      flag 'GNUTLS_HEARTBEAT_WAIT' , or you need to handle
3091      retransmissions and timeouts manually.
3092
3093      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3094      error code.
3095
3096      *Since:* 3.1.2
3097
3098 gnutls_heartbeat_pong
3099 ---------------------
3100
3101  -- Function: int gnutls_heartbeat_pong (gnutls_session_t SESSION,
3102           unsigned int FLAGS)
3103      SESSION: is a 'gnutls_session_t' structure.
3104
3105      FLAGS: should be zero
3106
3107      This function replies to a ping by sending a pong to the peer.
3108
3109      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3110      error code.
3111
3112      *Since:* 3.1.2
3113
3114 gnutls_heartbeat_set_timeouts
3115 -----------------------------
3116
3117  -- Function: void gnutls_heartbeat_set_timeouts (gnutls_session_t
3118           SESSION, unsigned int RETRANS_TIMEOUT, unsigned int
3119           TOTAL_TIMEOUT)
3120      SESSION: is a 'gnutls_session_t' structure.
3121
3122      RETRANS_TIMEOUT: The time at which a retransmission will occur in
3123      milliseconds
3124
3125      TOTAL_TIMEOUT: The time at which the connection will be aborted, in
3126      milliseconds.
3127
3128      This function will override the timeouts for the DTLS heartbeat
3129      protocol.  The retransmission timeout is the time after which a
3130      message from the peer is not received, the previous request will be
3131      retransmitted.  The total timeout is the time after which the
3132      handshake will be aborted with 'GNUTLS_E_TIMEDOUT' .
3133
3134      If the retransmission timeout is zero then the handshake will
3135      operate in a non-blocking way, i.e., return 'GNUTLS_E_AGAIN' .
3136
3137      *Since:* 3.1.2
3138
3139 gnutls_hex2bin
3140 --------------
3141
3142  -- Function: int gnutls_hex2bin (const char * HEX_DATA, size_t
3143           HEX_SIZE, void * BIN_DATA, size_t * BIN_SIZE)
3144      HEX_DATA: string with data in hex format
3145
3146      HEX_SIZE: size of hex data
3147
3148      BIN_DATA: output array with binary data
3149
3150      BIN_SIZE: when calling should hold maximum size of 'bin_data' , on
3151      return will hold actual length of 'bin_data' .
3152
3153      Convert a buffer with hex data to binary data.
3154
3155      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
3156      error code.
3157
3158      *Since:* 2.4.0
3159
3160 gnutls_hex_decode
3161 -----------------
3162
3163  -- Function: int gnutls_hex_decode (const gnutls_datum_t * HEX_DATA,
3164           void * RESULT, size_t * RESULT_SIZE)
3165      HEX_DATA: contain the encoded data
3166
3167      RESULT: the place where decoded data will be copied
3168
3169      RESULT_SIZE: holds the size of the result
3170
3171      This function will decode the given encoded data, using the hex
3172      encoding used by PSK password files.
3173
3174      Note that hex_data should be null terminated.
3175
3176      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
3177      not long enough, or 0 on success.
3178
3179 gnutls_hex_encode
3180 -----------------
3181
3182  -- Function: int gnutls_hex_encode (const gnutls_datum_t * DATA, char *
3183           RESULT, size_t * RESULT_SIZE)
3184      DATA: contain the raw data
3185
3186      RESULT: the place where hex data will be copied
3187
3188      RESULT_SIZE: holds the size of the result
3189
3190      This function will convert the given data to printable data, using
3191      the hex encoding, as used in the PSK password files.
3192
3193      Note that the size of the result includes the null terminator.
3194
3195      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
3196      not long enough, or 0 on success.
3197
3198 gnutls_init
3199 -----------
3200
3201  -- Function: int gnutls_init (gnutls_session_t * SESSION, unsigned int
3202           FLAGS)
3203      SESSION: is a pointer to a 'gnutls_session_t' structure.
3204
3205      FLAGS: indicate if this session is to be used for server or client.
3206
3207      This function initializes the current session to null.  Every
3208      session must be initialized before use, so internal structures can
3209      be allocated.  This function allocates structures which can only be
3210      free'd by calling 'gnutls_deinit()' .  Returns 'GNUTLS_E_SUCCESS'
3211      (0) on success.
3212
3213      'flags' can be one of 'GNUTLS_CLIENT' and 'GNUTLS_SERVER' .  For a
3214      DTLS entity, the flags 'GNUTLS_DATAGRAM' and 'GNUTLS_NONBLOCK' are
3215      also available.  The latter flag will enable a non-blocking
3216      operation of the DTLS timers.
3217
3218      The flag 'GNUTLS_NO_REPLAY_PROTECTION' will disable any replay
3219      protection in DTLS mode.  That must only used when replay
3220      protection is achieved using other means.
3221
3222      Note that since version 3.1.2 this function enables some common TLS
3223      extensions such as session tickets and OCSP certificate status
3224      request in client side by default.  To prevent that use the
3225      'GNUTLS_NO_EXTENSIONS' flag.
3226
3227      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
3228
3229 gnutls_key_generate
3230 -------------------
3231
3232  -- Function: int gnutls_key_generate (gnutls_datum_t * KEY, unsigned
3233           int KEY_SIZE)
3234      KEY: is a pointer to a 'gnutls_datum_t' which will contain a newly
3235      created key.
3236
3237      KEY_SIZE: The number of bytes of the key.
3238
3239      Generates a random key of 'key_size' bytes.
3240
3241      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
3242      error code.
3243
3244      *Since:* 3.0
3245
3246 gnutls_kx_get
3247 -------------
3248
3249  -- Function: gnutls_kx_algorithm_t gnutls_kx_get (gnutls_session_t
3250           SESSION)
3251      SESSION: is a 'gnutls_session_t' structure.
3252
3253      Get currently used key exchange algorithm.
3254
3255      *Returns:* the key exchange algorithm used in the last handshake, a
3256      'gnutls_kx_algorithm_t' value.
3257
3258 gnutls_kx_get_id
3259 ----------------
3260
3261  -- Function: gnutls_kx_algorithm_t gnutls_kx_get_id (const char * NAME)
3262      NAME: is a KX name
3263
3264      Convert a string to a 'gnutls_kx_algorithm_t' value.  The names are
3265      compared in a case insensitive way.
3266
3267      *Returns:* an id of the specified KX algorithm, or
3268      'GNUTLS_KX_UNKNOWN' on error.
3269
3270 gnutls_kx_get_name
3271 ------------------
3272
3273  -- Function: const char * gnutls_kx_get_name (gnutls_kx_algorithm_t
3274           ALGORITHM)
3275      ALGORITHM: is a key exchange algorithm
3276
3277      Convert a 'gnutls_kx_algorithm_t' value to a string.
3278
3279      *Returns:* a pointer to a string that contains the name of the
3280      specified key exchange algorithm, or 'NULL' .
3281
3282 gnutls_kx_list
3283 --------------
3284
3285  -- Function: const gnutls_kx_algorithm_t * gnutls_kx_list ( VOID)
3286
3287      Get a list of supported key exchange algorithms.
3288
3289      This function is not thread safe.
3290
3291      *Returns:* a (0)-terminated list of 'gnutls_kx_algorithm_t'
3292      integers indicating the available key exchange algorithms.
3293
3294 gnutls_load_file
3295 ----------------
3296
3297  -- Function: int gnutls_load_file (const char * FILENAME,
3298           gnutls_datum_t * DATA)
3299      FILENAME: the name of the file to load
3300
3301      DATA: Where the file will be stored
3302
3303      This function will load a file into a datum.  The data are zero
3304      terminated but the terminating null is not included in length.  The
3305      returned data are allocated using 'gnutls_malloc()' .
3306
3307      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3308      otherwise an error code is returned.
3309
3310      Since 3.1.0
3311
3312 gnutls_mac_get
3313 --------------
3314
3315  -- Function: gnutls_mac_algorithm_t gnutls_mac_get (gnutls_session_t
3316           SESSION)
3317      SESSION: is a 'gnutls_session_t' structure.
3318
3319      Get currently used MAC algorithm.
3320
3321      *Returns:* the currently used mac algorithm, a
3322      'gnutls_mac_algorithm_t' value.
3323
3324 gnutls_mac_get_id
3325 -----------------
3326
3327  -- Function: gnutls_mac_algorithm_t gnutls_mac_get_id (const char *
3328           NAME)
3329      NAME: is a MAC algorithm name
3330
3331      Convert a string to a 'gnutls_mac_algorithm_t' value.  The names
3332      are compared in a case insensitive way.
3333
3334      *Returns:* a 'gnutls_mac_algorithm_t' id of the specified MAC
3335      algorithm string, or 'GNUTLS_MAC_UNKNOWN' on failures.
3336
3337 gnutls_mac_get_key_size
3338 -----------------------
3339
3340  -- Function: size_t gnutls_mac_get_key_size (gnutls_mac_algorithm_t
3341           ALGORITHM)
3342      ALGORITHM: is an encryption algorithm
3343
3344      Returns the size of the MAC key used in TLS.
3345
3346      *Returns:* length (in bytes) of the given MAC key size, or 0 if the
3347      given MAC algorithm is invalid.
3348
3349 gnutls_mac_get_name
3350 -------------------
3351
3352  -- Function: const char * gnutls_mac_get_name (gnutls_mac_algorithm_t
3353           ALGORITHM)
3354      ALGORITHM: is a MAC algorithm
3355
3356      Convert a 'gnutls_mac_algorithm_t' value to a string.
3357
3358      *Returns:* a string that contains the name of the specified MAC
3359      algorithm, or 'NULL' .
3360
3361 gnutls_mac_list
3362 ---------------
3363
3364  -- Function: const gnutls_mac_algorithm_t * gnutls_mac_list ( VOID)
3365
3366      Get a list of hash algorithms for use as MACs.  Note that not
3367      necessarily all MACs are supported in TLS cipher suites.  This
3368      function is not thread safe.
3369
3370      *Returns:* Return a (0)-terminated list of 'gnutls_mac_algorithm_t'
3371      integers indicating the available MACs.
3372
3373 gnutls_ocsp_status_request_enable_client
3374 ----------------------------------------
3375
3376  -- Function: int gnutls_ocsp_status_request_enable_client
3377           (gnutls_session_t SESSION, gnutls_datum_t * RESPONDER_ID,
3378           size_t RESPONDER_ID_SIZE, gnutls_datum_t * EXTENSIONS)
3379      SESSION: is a 'gnutls_session_t' structure.
3380
3381      RESPONDER_ID: array with 'gnutls_datum_t' with DER data of
3382      responder id
3383
3384      RESPONDER_ID_SIZE: number of members in 'responder_id' array
3385
3386      EXTENSIONS: a 'gnutls_datum_t' with DER encoded OCSP extensions
3387
3388      This function is to be used by clients to request OCSP response
3389      from the server, using the "status_request" TLS extension.  Only
3390      OCSP status type is supported.  A typical server has a single OCSP
3391      response cached, so 'responder_id' and 'extensions' should be null.
3392
3393      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3394      otherwise a negative error code is returned.
3395
3396      *Since:* 3.1.3
3397
3398 gnutls_ocsp_status_request_get
3399 ------------------------------
3400
3401  -- Function: int gnutls_ocsp_status_request_get (gnutls_session_t
3402           SESSION, gnutls_datum_t * RESPONSE)
3403      SESSION: is a 'gnutls_session_t' structure.
3404
3405      RESPONSE: a 'gnutls_datum_t' with DER encoded OCSP response
3406
3407      This function returns the OCSP status response received from the
3408      TLS server.  The 'response' should be treated as constant.  If no
3409      OCSP response is available then
3410      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
3411
3412      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3413      otherwise a negative error code is returned.
3414
3415      *Since:* 3.1.3
3416
3417 gnutls_ocsp_status_request_is_checked
3418 -------------------------------------
3419
3420  -- Function: int gnutls_ocsp_status_request_is_checked
3421           (gnutls_session_t SESSION, unsigned int FLAGS)
3422      SESSION: is a gnutls session
3423
3424      FLAGS: should be zero
3425
3426      Check whether an OCSP status response was included in the handshake
3427      and whether it was checked and valid (not too old or superseded).
3428      This is a helper function when needing to decide whether to perform
3429      an OCSP validity check on the peer's certificate.  Must be called
3430      after 'gnutls_certificate_verify_peers3()' is called.
3431
3432      *Returns:* non zero it was valid, or a zero if it wasn't sent, or
3433      sent and was invalid.
3434
3435 gnutls_openpgp_send_cert
3436 ------------------------
3437
3438  -- Function: void gnutls_openpgp_send_cert (gnutls_session_t SESSION,
3439           gnutls_openpgp_crt_status_t STATUS)
3440      SESSION: is a pointer to a 'gnutls_session_t' structure.
3441
3442      STATUS: is one of GNUTLS_OPENPGP_CERT, or
3443      GNUTLS_OPENPGP_CERT_FINGERPRINT
3444
3445      This function will order gnutls to send the key fingerprint instead
3446      of the key in the initial handshake procedure.  This should be used
3447      with care and only when there is indication or knowledge that the
3448      server can obtain the client's key.
3449
3450 gnutls_packet_deinit
3451 --------------------
3452
3453  -- Function: void gnutls_packet_deinit (gnutls_packet_t PACKET)
3454      PACKET: is a pointer to a 'gnutls_packet_st' structure.
3455
3456      This function will deinitialize all data associated with the
3457      received packet.
3458
3459      *Since:* 3.3.5
3460
3461 gnutls_packet_get
3462 -----------------
3463
3464  -- Function: void gnutls_packet_get (gnutls_packet_t PACKET,
3465           gnutls_datum_t * DATA, unsigned char * SEQUENCE)
3466      PACKET: is a 'gnutls_packet_t' structure.
3467
3468      DATA: will contain the data present in the 'packet' structure (may
3469      be 'NULL' )
3470
3471      SEQUENCE: the 8-bytes of the packet sequence number (may be 'NULL'
3472      )
3473
3474      This function returns the data and sequence number associated with
3475      the received packet.
3476
3477      *Since:* 3.3.5
3478
3479 gnutls_pem_base64_decode
3480 ------------------------
3481
3482  -- Function: int gnutls_pem_base64_decode (const char * HEADER, const
3483           gnutls_datum_t * B64_DATA, unsigned char * RESULT, size_t *
3484           RESULT_SIZE)
3485      HEADER: A null terminated string with the PEM header (eg.
3486      CERTIFICATE)
3487
3488      B64_DATA: contain the encoded data
3489
3490      RESULT: the place where decoded data will be copied
3491
3492      RESULT_SIZE: holds the size of the result
3493
3494      This function will decode the given encoded data.  If the header
3495      given is non null this function will search for "---BEGIN header"
3496      and decode only this part.  Otherwise it will decode the first PEM
3497      packet found.
3498
3499      *Returns:* On success 'GNUTLS_E_SUCCESS' (0) is returned,
3500      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned if the buffer given is
3501      not long enough, or 0 on success.
3502
3503 gnutls_pem_base64_decode_alloc
3504 ------------------------------
3505
3506  -- Function: int gnutls_pem_base64_decode_alloc (const char * HEADER,
3507           const gnutls_datum_t * B64_DATA, gnutls_datum_t * RESULT)
3508      HEADER: The PEM header (eg.  CERTIFICATE)
3509
3510      B64_DATA: contains the encoded data
3511
3512      RESULT: the place where decoded data lie
3513
3514      This function will decode the given encoded data.  The decoded data
3515      will be allocated, and stored into result.  If the header given is
3516      non null this function will search for "---BEGIN header" and decode
3517      only this part.  Otherwise it will decode the first PEM packet
3518      found.
3519
3520      You should use 'gnutls_free()' to free the returned data.
3521
3522      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3523      otherwise an error code is returned.
3524
3525 gnutls_pem_base64_encode
3526 ------------------------
3527
3528  -- Function: int gnutls_pem_base64_encode (const char * MSG, const
3529           gnutls_datum_t * DATA, char * RESULT, size_t * RESULT_SIZE)
3530      MSG: is a message to be put in the header
3531
3532      DATA: contain the raw data
3533
3534      RESULT: the place where base64 data will be copied
3535
3536      RESULT_SIZE: holds the size of the result
3537
3538      This function will convert the given data to printable data, using
3539      the base64 encoding.  This is the encoding used in PEM messages.
3540
3541      The output string will be null terminated, although the size will
3542      not include the terminating null.
3543
3544      *Returns:* On success 'GNUTLS_E_SUCCESS' (0) is returned,
3545      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned if the buffer given is
3546      not long enough, or 0 on success.
3547
3548 gnutls_pem_base64_encode_alloc
3549 ------------------------------
3550
3551  -- Function: int gnutls_pem_base64_encode_alloc (const char * MSG,
3552           const gnutls_datum_t * DATA, gnutls_datum_t * RESULT)
3553      MSG: is a message to be put in the encoded header
3554
3555      DATA: contains the raw data
3556
3557      RESULT: will hold the newly allocated encoded data
3558
3559      This function will convert the given data to printable data, using
3560      the base64 encoding.  This is the encoding used in PEM messages.
3561      This function will allocate the required memory to hold the encoded
3562      data.
3563
3564      You should use 'gnutls_free()' to free the returned data.
3565
3566      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3567      otherwise an error code is returned.
3568
3569 gnutls_perror
3570 -------------
3571
3572  -- Function: void gnutls_perror (int ERROR)
3573      ERROR: is a GnuTLS error code, a negative error code
3574
3575      This function is like 'perror()' .  The only difference is that it
3576      accepts an error number returned by a gnutls function.
3577
3578 gnutls_pk_algorithm_get_name
3579 ----------------------------
3580
3581  -- Function: const char * gnutls_pk_algorithm_get_name
3582           (gnutls_pk_algorithm_t ALGORITHM)
3583      ALGORITHM: is a pk algorithm
3584
3585      Convert a 'gnutls_pk_algorithm_t' value to a string.
3586
3587      *Returns:* a string that contains the name of the specified public
3588      key algorithm, or 'NULL' .
3589
3590 gnutls_pk_bits_to_sec_param
3591 ---------------------------
3592
3593  -- Function: gnutls_sec_param_t gnutls_pk_bits_to_sec_param
3594           (gnutls_pk_algorithm_t ALGO, unsigned int BITS)
3595      ALGO: is a public key algorithm
3596
3597      BITS: is the number of bits
3598
3599      This is the inverse of 'gnutls_sec_param_to_pk_bits()' .  Given an
3600      algorithm and the number of bits, it will return the security
3601      parameter.  This is a rough indication.
3602
3603      *Returns:* The security parameter.
3604
3605      *Since:* 2.12.0
3606
3607 gnutls_pk_get_id
3608 ----------------
3609
3610  -- Function: gnutls_pk_algorithm_t gnutls_pk_get_id (const char * NAME)
3611      NAME: is a string containing a public key algorithm name.
3612
3613      Convert a string to a 'gnutls_pk_algorithm_t' value.  The names are
3614      compared in a case insensitive way.  For example,
3615      gnutls_pk_get_id("RSA") will return 'GNUTLS_PK_RSA' .
3616
3617      *Returns:* a 'gnutls_pk_algorithm_t' id of the specified public key
3618      algorithm string, or 'GNUTLS_PK_UNKNOWN' on failures.
3619
3620      *Since:* 2.6.0
3621
3622 gnutls_pk_get_name
3623 ------------------
3624
3625  -- Function: const char * gnutls_pk_get_name (gnutls_pk_algorithm_t
3626           ALGORITHM)
3627      ALGORITHM: is a public key algorithm
3628
3629      Convert a 'gnutls_pk_algorithm_t' value to a string.
3630
3631      *Returns:* a pointer to a string that contains the name of the
3632      specified public key algorithm, or 'NULL' .
3633
3634      *Since:* 2.6.0
3635
3636 gnutls_pk_list
3637 --------------
3638
3639  -- Function: const gnutls_pk_algorithm_t * gnutls_pk_list ( VOID)
3640
3641      Get a list of supported public key algorithms.
3642
3643      This function is not thread safe.
3644
3645      *Returns:* a (0)-terminated list of 'gnutls_pk_algorithm_t'
3646      integers indicating the available ciphers.
3647
3648      *Since:* 2.6.0
3649
3650 gnutls_pk_to_sign
3651 -----------------
3652
3653  -- Function: gnutls_sign_algorithm_t gnutls_pk_to_sign
3654           (gnutls_pk_algorithm_t PK, gnutls_digest_algorithm_t HASH)
3655      PK: is a public key algorithm
3656
3657      HASH: a hash algorithm
3658
3659      This function maps public key and hash algorithms combinations to
3660      signature algorithms.
3661
3662      *Returns:* return a 'gnutls_sign_algorithm_t' value, or
3663      'GNUTLS_SIGN_UNKNOWN' on error.
3664
3665 gnutls_prf
3666 ----------
3667
3668  -- Function: int gnutls_prf (gnutls_session_t SESSION, size_t
3669           LABEL_SIZE, const char * LABEL, int SERVER_RANDOM_FIRST,
3670           size_t EXTRA_SIZE, const char * EXTRA, size_t OUTSIZE, char *
3671           OUT)
3672      SESSION: is a 'gnutls_session_t' structure.
3673
3674      LABEL_SIZE: length of the 'label' variable.
3675
3676      LABEL: label used in PRF computation, typically a short string.
3677
3678      SERVER_RANDOM_FIRST: non-zero if server random field should be
3679      first in seed
3680
3681      EXTRA_SIZE: length of the 'extra' variable.
3682
3683      EXTRA: optional extra data to seed the PRF with.
3684
3685      OUTSIZE: size of pre-allocated output buffer to hold the output.
3686
3687      OUT: pre-allocated buffer to hold the generated data.
3688
3689      Applies the TLS Pseudo-Random-Function (PRF) on the master secret
3690      and the provided data, seeded with the client and server random
3691      fields.
3692
3693      The output of this function is identical to RFC5705 extractor if
3694      'extra' and 'extra_size' are set to zero.  Otherwise, 'extra'
3695      should contain the context value prefixed by a two-byte length.
3696
3697      The 'label' variable usually contains a string denoting the purpose
3698      for the generated data.  The 'server_random_first' indicates
3699      whether the client random field or the server random field should
3700      be first in the seed.  Non-zero indicates that the server random
3701      field is first, 0 that the client random field is first.
3702
3703      The 'extra' variable can be used to add more data to the seed,
3704      after the random variables.  It can be used to make sure the
3705      generated output is strongly connected to some additional data
3706      (e.g., a string used in user authentication).
3707
3708      The output is placed in 'out' , which must be pre-allocated.
3709
3710      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
3711
3712 gnutls_prf_raw
3713 --------------
3714
3715  -- Function: int gnutls_prf_raw (gnutls_session_t SESSION, size_t
3716           LABEL_SIZE, const char * LABEL, size_t SEED_SIZE, const char *
3717           SEED, size_t OUTSIZE, char * OUT)
3718      SESSION: is a 'gnutls_session_t' structure.
3719
3720      LABEL_SIZE: length of the 'label' variable.
3721
3722      LABEL: label used in PRF computation, typically a short string.
3723
3724      SEED_SIZE: length of the 'seed' variable.
3725
3726      SEED: optional extra data to seed the PRF with.
3727
3728      OUTSIZE: size of pre-allocated output buffer to hold the output.
3729
3730      OUT: pre-allocated buffer to hold the generated data.
3731
3732      Apply the TLS Pseudo-Random-Function (PRF) on the master secret and
3733      the provided data.
3734
3735      The 'label' variable usually contains a string denoting the purpose
3736      for the generated data.  The 'seed' usually contains data such as
3737      the client and server random, perhaps together with some additional
3738      data that is added to guarantee uniqueness of the output for a
3739      particular purpose.
3740
3741      Because the output is not guaranteed to be unique for a particular
3742      session unless 'seed' includes the client random and server random
3743      fields (the PRF would output the same data on another connection
3744      resumed from the first one), it is not recommended to use this
3745      function directly.  The 'gnutls_prf()' function seeds the PRF with
3746      the client and server random fields directly, and is recommended if
3747      you want to generate pseudo random data unique for each session.
3748
3749      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
3750
3751 gnutls_priority_certificate_type_list
3752 -------------------------------------
3753
3754  -- Function: int gnutls_priority_certificate_type_list
3755           (gnutls_priority_t PCACHE, const unsigned int ** LIST)
3756      PCACHE: is a 'gnutls_prioritity_t' structure.
3757
3758      LIST: will point to an integer list
3759
3760      Get a list of available certificate types in the priority
3761      structure.
3762
3763      *Returns:* the number of certificate types, or an error code.
3764
3765      *Since:* 3.0
3766
3767 gnutls_priority_cipher_list
3768 ---------------------------
3769
3770  -- Function: int gnutls_priority_cipher_list (gnutls_priority_t PCACHE,
3771           const unsigned int ** LIST)
3772      PCACHE: is a 'gnutls_prioritity_t' structure.
3773
3774      LIST: will point to an integer list
3775
3776      Get a list of available ciphers in the priority structure.
3777
3778      *Returns:* the number of curves, or an error code.
3779
3780      *Since:* 3.2.3
3781
3782 gnutls_priority_compression_list
3783 --------------------------------
3784
3785  -- Function: int gnutls_priority_compression_list (gnutls_priority_t
3786           PCACHE, const unsigned int ** LIST)
3787      PCACHE: is a 'gnutls_prioritity_t' structure.
3788
3789      LIST: will point to an integer list
3790
3791      Get a list of available compression method in the priority
3792      structure.
3793
3794      *Returns:* the number of methods, or an error code.
3795
3796      *Since:* 3.0
3797
3798 gnutls_priority_deinit
3799 ----------------------
3800
3801  -- Function: void gnutls_priority_deinit (gnutls_priority_t
3802           PRIORITY_CACHE)
3803      PRIORITY_CACHE: is a 'gnutls_prioritity_t' structure.
3804
3805      Deinitializes the priority cache.
3806
3807 gnutls_priority_ecc_curve_list
3808 ------------------------------
3809
3810  -- Function: int gnutls_priority_ecc_curve_list (gnutls_priority_t
3811           PCACHE, const unsigned int ** LIST)
3812      PCACHE: is a 'gnutls_prioritity_t' structure.
3813
3814      LIST: will point to an integer list
3815
3816      Get a list of available elliptic curves in the priority structure.
3817
3818      *Returns:* the number of curves, or an error code.
3819
3820      *Since:* 3.0
3821
3822 gnutls_priority_get_cipher_suite_index
3823 --------------------------------------
3824
3825  -- Function: int gnutls_priority_get_cipher_suite_index
3826           (gnutls_priority_t PCACHE, unsigned int IDX, unsigned int *
3827           SIDX)
3828      PCACHE: is a 'gnutls_prioritity_t' structure.
3829
3830      IDX: is an index number.
3831
3832      SIDX: internal index of cipher suite to get information about.
3833
3834      Provides the internal ciphersuite index to be used with
3835      'gnutls_cipher_suite_info()' .  The index 'idx' provided is an
3836      index kept at the priorities structure.  It might be that a valid
3837      priorities index does not correspond to a ciphersuite and in that
3838      case 'GNUTLS_E_UNKNOWN_CIPHER_SUITE' will be returned.  Once the
3839      last available index is crossed then
3840      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
3841
3842      *Returns:* On success it returns 'GNUTLS_E_SUCCESS' (0), or a
3843      negative error value otherwise.
3844
3845 gnutls_priority_init
3846 --------------------
3847
3848  -- Function: int gnutls_priority_init (gnutls_priority_t *
3849           PRIORITY_CACHE, const char * PRIORITIES, const char **
3850           ERR_POS)
3851      PRIORITY_CACHE: is a 'gnutls_prioritity_t' structure.
3852
3853      PRIORITIES: is a string describing priorities (may be 'NULL' )
3854
3855      ERR_POS: In case of an error this will have the position in the
3856      string the error occurred
3857
3858      Sets priorities for the ciphers, key exchange methods, macs and
3859      compression methods.
3860
3861      The 'priorities' option allows you to specify a colon separated
3862      list of the cipher priorities to enable.  Some keywords are defined
3863      to provide quick access to common preferences.
3864
3865      Unless there is a special need, use the "NORMAL" keyword to apply a
3866      reasonable security level, or "NORMAL:'COMPAT' " for compatibility.
3867
3868      "PERFORMANCE" means all the "secure" ciphersuites are enabled,
3869      limited to 128 bit ciphers and sorted by terms of speed
3870      performance.
3871
3872      "LEGACY" the NORMAL settings for GnuTLS 3.2.x or earlier.  There is
3873      no verification profile set, and the allowed DH primes are
3874      considered weak today.
3875
3876      "NORMAL" means all "secure" ciphersuites.  The 256-bit ciphers are
3877      included as a fallback only.  The ciphers are sorted by security
3878      margin.
3879
3880      "PFS" means all "secure" ciphersuites that support perfect forward
3881      secrecy.  The 256-bit ciphers are included as a fallback only.  The
3882      ciphers are sorted by security margin.
3883
3884      "SECURE128" means all "secure" ciphersuites of security level
3885      128-bit or more.
3886
3887      "SECURE192" means all "secure" ciphersuites of security level
3888      192-bit or more.
3889
3890      "SUITEB128" means all the NSA SuiteB ciphersuites with security
3891      level of 128.
3892
3893      "SUITEB192" means all the NSA SuiteB ciphersuites with security
3894      level of 192.
3895
3896      "EXPORT" means all ciphersuites are enabled, including the
3897      low-security 40 bit ciphers.
3898
3899      "NONE" means nothing is enabled.  This disables even protocols and
3900      compression methods.
3901
3902      " 'KEYWORD' " The system administrator imposed settings.  The
3903      provided keywords will be expanded from a configuration-time
3904      provided file - default is: /etc/gnutls/default-priorities.  Any
3905      keywords that follow it, will be appended to the expanded string.
3906      If there is no system string, then the function will fail.  The
3907      system file should be formatted as "KEYWORD=VALUE", e.g.,
3908      "SYSTEM=NORMAL:-ARCFOUR-128".
3909
3910      Special keywords are "!", "-" and "+".  "!"  or "-" appended with
3911      an algorithm will remove this algorithm.  "+" appended with an
3912      algorithm will add this algorithm.
3913
3914      Check the GnuTLS manual section "Priority strings" for detailed
3915      information.
3916
3917      *Examples:*
3918      "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
3919
3920      "NORMAL:-ARCFOUR-128" means normal ciphers except for ARCFOUR-128.
3921
3922      "SECURE128:-VERS-SSL3.0:+COMP-DEFLATE" means that only secure
3923      ciphers are enabled, SSL3.0 is disabled, and libz compression
3924      enabled.
3925
3926      "NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1",
3927
3928      "NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1",
3929
3930      "SECURE256:+SECURE128",
3931
3932      Note that "NORMAL:'COMPAT' " is the most compatible mode.
3933
3934      A 'NULL' 'priorities' string indicates the default priorities to be
3935      used (this is available since GnuTLS 3.3.0).
3936
3937      *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
3938      'GNUTLS_E_SUCCESS' on success, or an error code.
3939
3940 gnutls_priority_kx_list
3941 -----------------------
3942
3943  -- Function: int gnutls_priority_kx_list (gnutls_priority_t PCACHE,
3944           const unsigned int ** LIST)
3945      PCACHE: is a 'gnutls_prioritity_t' structure.
3946
3947      LIST: will point to an integer list
3948
3949      Get a list of available key exchange methods in the priority
3950      structure.
3951
3952      *Returns:* the number of curves, or an error code.
3953
3954      *Since:* 3.2.3
3955
3956 gnutls_priority_mac_list
3957 ------------------------
3958
3959  -- Function: int gnutls_priority_mac_list (gnutls_priority_t PCACHE,
3960           const unsigned int ** LIST)
3961      PCACHE: is a 'gnutls_prioritity_t' structure.
3962
3963      LIST: will point to an integer list
3964
3965      Get a list of available MAC algorithms in the priority structure.
3966
3967      *Returns:* the number of curves, or an error code.
3968
3969      *Since:* 3.2.3
3970
3971 gnutls_priority_protocol_list
3972 -----------------------------
3973
3974  -- Function: int gnutls_priority_protocol_list (gnutls_priority_t
3975           PCACHE, const unsigned int ** LIST)
3976      PCACHE: is a 'gnutls_prioritity_t' structure.
3977
3978      LIST: will point to an integer list
3979
3980      Get a list of available TLS version numbers in the priority
3981      structure.
3982
3983      *Returns:* the number of protocols, or an error code.
3984
3985      *Since:* 3.0
3986
3987 gnutls_priority_set
3988 -------------------
3989
3990  -- Function: int gnutls_priority_set (gnutls_session_t SESSION,
3991           gnutls_priority_t PRIORITY)
3992      SESSION: is a 'gnutls_session_t' structure.
3993
3994      PRIORITY: is a 'gnutls_priority_t' structure.
3995
3996      Sets the priorities to use on the ciphers, key exchange methods,
3997      macs and compression methods.
3998
3999      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
4000
4001 gnutls_priority_set_direct
4002 --------------------------
4003
4004  -- Function: int gnutls_priority_set_direct (gnutls_session_t SESSION,
4005           const char * PRIORITIES, const char ** ERR_POS)
4006      SESSION: is a 'gnutls_session_t' structure.
4007
4008      PRIORITIES: is a string describing priorities
4009
4010      ERR_POS: In case of an error this will have the position in the
4011      string the error occured
4012
4013      Sets the priorities to use on the ciphers, key exchange methods,
4014      macs and compression methods.  This function avoids keeping a
4015      priority cache and is used to directly set string priorities to a
4016      TLS session.  For documentation check the 'gnutls_priority_init()'
4017      .
4018
4019      To simply use a reasonable default, consider using
4020      'gnutls_set_default_priority()' .
4021
4022      *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
4023      'GNUTLS_E_SUCCESS' on success, or an error code.
4024
4025 gnutls_priority_sign_list
4026 -------------------------
4027
4028  -- Function: int gnutls_priority_sign_list (gnutls_priority_t PCACHE,
4029           const unsigned int ** LIST)
4030      PCACHE: is a 'gnutls_prioritity_t' structure.
4031
4032      LIST: will point to an integer list
4033
4034      Get a list of available signature algorithms in the priority
4035      structure.
4036
4037      *Returns:* the number of algorithms, or an error code.
4038
4039      *Since:* 3.0
4040
4041 gnutls_protocol_get_id
4042 ----------------------
4043
4044  -- Function: gnutls_protocol_t gnutls_protocol_get_id (const char *
4045           NAME)
4046      NAME: is a protocol name
4047
4048      The names are compared in a case insensitive way.
4049
4050      *Returns:* an id of the specified protocol, or
4051      'GNUTLS_VERSION_UNKNOWN' on error.
4052
4053 gnutls_protocol_get_name
4054 ------------------------
4055
4056  -- Function: const char * gnutls_protocol_get_name (gnutls_protocol_t
4057           VERSION)
4058      VERSION: is a (gnutls) version number
4059
4060      Convert a 'gnutls_protocol_t' value to a string.
4061
4062      *Returns:* a string that contains the name of the specified TLS
4063      version (e.g., "TLS1.0"), or 'NULL' .
4064
4065 gnutls_protocol_get_version
4066 ---------------------------
4067
4068  -- Function: gnutls_protocol_t gnutls_protocol_get_version
4069           (gnutls_session_t SESSION)
4070      SESSION: is a 'gnutls_session_t' structure.
4071
4072      Get TLS version, a 'gnutls_protocol_t' value.
4073
4074      *Returns:* The version of the currently used protocol.
4075
4076 gnutls_protocol_list
4077 --------------------
4078
4079  -- Function: const gnutls_protocol_t * gnutls_protocol_list ( VOID)
4080
4081      Get a list of supported protocols, e.g.  SSL 3.0, TLS 1.0 etc.
4082
4083      This function is not thread safe.
4084
4085      *Returns:* a (0)-terminated list of 'gnutls_protocol_t' integers
4086      indicating the available protocols.
4087
4088 gnutls_psk_allocate_client_credentials
4089 --------------------------------------
4090
4091  -- Function: int gnutls_psk_allocate_client_credentials
4092           (gnutls_psk_client_credentials_t * SC)
4093      SC: is a pointer to a 'gnutls_psk_server_credentials_t' structure.
4094
4095      This structure is complex enough to manipulate directly thus this
4096      helper function is provided in order to allocate it.
4097
4098      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4099      otherwise an error code is returned.
4100
4101 gnutls_psk_allocate_server_credentials
4102 --------------------------------------
4103
4104  -- Function: int gnutls_psk_allocate_server_credentials
4105           (gnutls_psk_server_credentials_t * SC)
4106      SC: is a pointer to a 'gnutls_psk_server_credentials_t' structure.
4107
4108      This structure is complex enough to manipulate directly thus this
4109      helper function is provided in order to allocate it.
4110
4111      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4112      otherwise an error code is returned.
4113
4114 gnutls_psk_client_get_hint
4115 --------------------------
4116
4117  -- Function: const char * gnutls_psk_client_get_hint (gnutls_session_t
4118           SESSION)
4119      SESSION: is a gnutls session
4120
4121      The PSK identity hint may give the client help in deciding which
4122      username to use.  This should only be called in case of PSK
4123      authentication and in case of a client.
4124
4125      *Returns:* the identity hint of the peer, or 'NULL' in case of an
4126      error.
4127
4128      *Since:* 2.4.0
4129
4130 gnutls_psk_free_client_credentials
4131 ----------------------------------
4132
4133  -- Function: void gnutls_psk_free_client_credentials
4134           (gnutls_psk_client_credentials_t SC)
4135      SC: is a 'gnutls_psk_client_credentials_t' structure.
4136
4137      This structure is complex enough to manipulate directly thus this
4138      helper function is provided in order to free (deallocate) it.
4139
4140 gnutls_psk_free_server_credentials
4141 ----------------------------------
4142
4143  -- Function: void gnutls_psk_free_server_credentials
4144           (gnutls_psk_server_credentials_t SC)
4145      SC: is a 'gnutls_psk_server_credentials_t' structure.
4146
4147      This structure is complex enough to manipulate directly thus this
4148      helper function is provided in order to free (deallocate) it.
4149
4150 gnutls_psk_server_get_username
4151 ------------------------------
4152
4153  -- Function: const char * gnutls_psk_server_get_username
4154           (gnutls_session_t SESSION)
4155      SESSION: is a gnutls session
4156
4157      This should only be called in case of PSK authentication and in
4158      case of a server.
4159
4160      *Returns:* the username of the peer, or 'NULL' in case of an error.
4161
4162 gnutls_psk_set_client_credentials
4163 ---------------------------------
4164
4165  -- Function: int gnutls_psk_set_client_credentials
4166           (gnutls_psk_client_credentials_t RES, const char * USERNAME,
4167           const gnutls_datum_t * KEY, gnutls_psk_key_flags FLAGS)
4168      RES: is a 'gnutls_psk_client_credentials_t' structure.
4169
4170      USERNAME: is the user's zero-terminated userid
4171
4172      KEY: is the user's key
4173
4174      FLAGS: indicate the format of the key, either 'GNUTLS_PSK_KEY_RAW'
4175      or 'GNUTLS_PSK_KEY_HEX' .
4176
4177      This function sets the username and password, in a
4178      gnutls_psk_client_credentials_t structure.  Those will be used in
4179      PSK authentication.  'username' should be an ASCII string or UTF-8
4180      strings prepared using the "SASLprep" profile of "stringprep".  The
4181      key can be either in raw byte format or in Hex format (without the
4182      0x prefix).
4183
4184      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4185      otherwise an error code is returned.
4186
4187 gnutls_psk_set_client_credentials_function
4188 ------------------------------------------
4189
4190  -- Function: void gnutls_psk_set_client_credentials_function
4191           (gnutls_psk_client_credentials_t CRED,
4192           gnutls_psk_client_credentials_function * FUNC)
4193      CRED: is a 'gnutls_psk_server_credentials_t' structure.
4194
4195      FUNC: is the callback function
4196
4197      This function can be used to set a callback to retrieve the
4198      username and password for client PSK authentication.  The
4199      callback's function form is: int (*callback)(gnutls_session_t,
4200      char** username, gnutls_datum_t* key);
4201
4202      The 'username' and 'key' ->data must be allocated using
4203      'gnutls_malloc()' .  'username' should be ASCII strings or UTF-8
4204      strings prepared using the "SASLprep" profile of "stringprep".
4205
4206      The callback function will be called once per handshake.
4207
4208      The callback function should return 0 on success.  -1 indicates an
4209      error.
4210
4211 gnutls_psk_set_params_function
4212 ------------------------------
4213
4214  -- Function: void gnutls_psk_set_params_function
4215           (gnutls_psk_server_credentials_t RES, gnutls_params_function *
4216           FUNC)
4217      RES: is a gnutls_psk_server_credentials_t structure
4218
4219      FUNC: is the function to be called
4220
4221      This function will set a callback in order for the server to get
4222      the Diffie-Hellman or RSA parameters for PSK authentication.  The
4223      callback should return 'GNUTLS_E_SUCCESS' (0) on success.
4224
4225 gnutls_psk_set_server_credentials_file
4226 --------------------------------------
4227
4228  -- Function: int gnutls_psk_set_server_credentials_file
4229           (gnutls_psk_server_credentials_t RES, const char *
4230           PASSWORD_FILE)
4231      RES: is a 'gnutls_psk_server_credentials_t' structure.
4232
4233      PASSWORD_FILE: is the PSK password file (passwd.psk)
4234
4235      This function sets the password file, in a
4236      'gnutls_psk_server_credentials_t' structure.  This password file
4237      holds usernames and keys and will be used for PSK authentication.
4238
4239      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4240      otherwise an error code is returned.
4241
4242 gnutls_psk_set_server_credentials_function
4243 ------------------------------------------
4244
4245  -- Function: void gnutls_psk_set_server_credentials_function
4246           (gnutls_psk_server_credentials_t CRED,
4247           gnutls_psk_server_credentials_function * FUNC)
4248      CRED: is a 'gnutls_psk_server_credentials_t' structure.
4249
4250      FUNC: is the callback function
4251
4252      This function can be used to set a callback to retrieve the user's
4253      PSK credentials.  The callback's function form is: int
4254      (*callback)(gnutls_session_t, const char* username, gnutls_datum_t*
4255      key);
4256
4257      'username' contains the actual username.  The 'key' must be filled
4258      in using the 'gnutls_malloc()' .
4259
4260      In case the callback returned a negative number then gnutls will
4261      assume that the username does not exist.
4262
4263      The callback function will only be called once per handshake.  The
4264      callback function should return 0 on success, while -1 indicates an
4265      error.
4266
4267 gnutls_psk_set_server_credentials_hint
4268 --------------------------------------
4269
4270  -- Function: int gnutls_psk_set_server_credentials_hint
4271           (gnutls_psk_server_credentials_t RES, const char * HINT)
4272      RES: is a 'gnutls_psk_server_credentials_t' structure.
4273
4274      HINT: is the PSK identity hint string
4275
4276      This function sets the identity hint, in a
4277      'gnutls_psk_server_credentials_t' structure.  This hint is sent to
4278      the client to help it chose a good PSK credential (i.e., username
4279      and password).
4280
4281      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4282      otherwise an error code is returned.
4283
4284      *Since:* 2.4.0
4285
4286 gnutls_psk_set_server_dh_params
4287 -------------------------------
4288
4289  -- Function: void gnutls_psk_set_server_dh_params
4290           (gnutls_psk_server_credentials_t RES, gnutls_dh_params_t
4291           DH_PARAMS)
4292      RES: is a gnutls_psk_server_credentials_t structure
4293
4294      DH_PARAMS: is a structure that holds Diffie-Hellman parameters.
4295
4296      This function will set the Diffie-Hellman parameters for an
4297      anonymous server to use.  These parameters will be used in
4298      Diffie-Hellman exchange with PSK cipher suites.
4299
4300 gnutls_psk_set_server_params_function
4301 -------------------------------------
4302
4303  -- Function: void gnutls_psk_set_server_params_function
4304           (gnutls_psk_server_credentials_t RES, gnutls_params_function *
4305           FUNC)
4306      RES: is a 'gnutls_certificate_credentials_t' structure
4307
4308      FUNC: is the function to be called
4309
4310      This function will set a callback in order for the server to get
4311      the Diffie-Hellman parameters for PSK authentication.  The callback
4312      should return 'GNUTLS_E_SUCCESS' (0) on success.
4313
4314 gnutls_random_art
4315 -----------------
4316
4317  -- Function: int gnutls_random_art (gnutls_random_art_t TYPE, const
4318           char * KEY_TYPE, unsigned int KEY_SIZE, void * FPR, size_t
4319           FPR_SIZE, gnutls_datum_t * ART)
4320      TYPE: The type of the random art (for now only
4321      'GNUTLS_RANDOM_ART_OPENSSH' is supported)
4322
4323      KEY_TYPE: The type of the key (RSA, DSA etc.)
4324
4325      KEY_SIZE: The size of the key in bits
4326
4327      FPR: The fingerprint of the key
4328
4329      FPR_SIZE: The size of the fingerprint
4330
4331      ART: The returned random art
4332
4333      This function will convert a given fingerprint to an "artistic"
4334      image.  The returned image is allocated using 'gnutls_malloc()' .
4335
4336      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4337      otherwise an error code is returned.
4338
4339 gnutls_range_split
4340 ------------------
4341
4342  -- Function: int gnutls_range_split (gnutls_session_t SESSION, const
4343           gnutls_range_st * ORIG, gnutls_range_st * NEXT,
4344           gnutls_range_st * REMAINDER)
4345      SESSION: is a 'gnutls_session_t' structure
4346
4347      ORIG: is the original range provided by the user
4348
4349      NEXT: is the returned range that can be conveyed in a TLS record
4350
4351      REMAINDER: is the returned remaining range
4352
4353      This function should be used when it is required to hide the length
4354      of very long data that cannot be directly provided to
4355      'gnutls_record_send_range()' .  In that case this function should
4356      be called with the desired length hiding range in 'orig' .  The
4357      returned 'next' value should then be used in the next call to
4358      'gnutls_record_send_range()' with the partial data.  That process
4359      should be repeated until 'remainder' is (0,0).
4360
4361      *Returns:* 0 in case splitting succeeds, non zero in case of error.
4362      Note that 'orig' is not changed, while the values of 'next' and
4363      'remainder' are modified to store the resulting values.
4364
4365 gnutls_record_can_use_length_hiding
4366 -----------------------------------
4367
4368  -- Function: int gnutls_record_can_use_length_hiding (gnutls_session_t
4369           SESSION)
4370      SESSION: is a 'gnutls_session_t' structure.
4371
4372      If the session supports length-hiding padding, you can invoke
4373      'gnutls_range_send_message()' to send a message whose length is
4374      hidden in the given range.  If the session does not support length
4375      hiding padding, you can use the standard 'gnutls_record_send()'
4376      function, or 'gnutls_range_send_message()' making sure that the
4377      range is the same as the length of the message you are trying to
4378      send.
4379
4380      *Returns:* true (1) if the current session supports length-hiding
4381      padding, false (0) if the current session does not.
4382
4383 gnutls_record_check_corked
4384 --------------------------
4385
4386  -- Function: size_t gnutls_record_check_corked (gnutls_session_t
4387           SESSION)
4388      SESSION: is a 'gnutls_session_t' structure.
4389
4390      This function checks if there pending corked data in the gnutls
4391      buffers -see 'gnutls_record_cork()' .
4392
4393      *Returns:* Returns the size of the corked data or zero.
4394
4395      *Since:* 3.2.8
4396
4397 gnutls_record_check_pending
4398 ---------------------------
4399
4400  -- Function: size_t gnutls_record_check_pending (gnutls_session_t
4401           SESSION)
4402      SESSION: is a 'gnutls_session_t' structure.
4403
4404      This function checks if there are unread data in the gnutls
4405      buffers.  If the return value is non-zero the next call to
4406      'gnutls_record_recv()' is guaranteed not to block.
4407
4408      *Returns:* Returns the size of the data or zero.
4409
4410 gnutls_record_cork
4411 ------------------
4412
4413  -- Function: void gnutls_record_cork (gnutls_session_t SESSION)
4414      SESSION: is a 'gnutls_session_t' structure.
4415
4416      If called, 'gnutls_record_send()' will no longer send any records.
4417      Any sent records will be cached until 'gnutls_record_uncork()' is
4418      called.
4419
4420      This function is safe to use with DTLS after GnuTLS 3.3.0.
4421
4422      *Since:* 3.1.9
4423
4424 gnutls_record_disable_padding
4425 -----------------------------
4426
4427  -- Function: void gnutls_record_disable_padding (gnutls_session_t
4428           SESSION)
4429      SESSION: is a 'gnutls_session_t' structure.
4430
4431      Used to disabled padding in TLS 1.0 and above.  Normally you do not
4432      need to use this function, but there are buggy clients that
4433      complain if a server pads the encrypted data.  This of course will
4434      disable protection against statistical attacks on the data.
4435
4436      This functions is defunt since 3.1.7.  Random padding is disabled
4437      by default unless requested using 'gnutls_range_send_message()' .
4438
4439 gnutls_record_get_direction
4440 ---------------------------
4441
4442  -- Function: int gnutls_record_get_direction (gnutls_session_t SESSION)
4443      SESSION: is a 'gnutls_session_t' structure.
4444
4445      This function provides information about the internals of the
4446      record protocol and is only useful if a prior gnutls function call
4447      (e.g.  'gnutls_handshake()' ) was interrupted for some reason, that
4448      is, if a function returned 'GNUTLS_E_INTERRUPTED' or
4449      'GNUTLS_E_AGAIN' .  In such a case, you might want to call
4450      'select()' or 'poll()' before calling the interrupted gnutls
4451      function again.  To tell you whether a file descriptor should be
4452      selected for either reading or writing,
4453      'gnutls_record_get_direction()' returns 0 if the interrupted
4454      function was trying to read data, and 1 if it was trying to write
4455      data.
4456
4457      This function's output is unreliable if you are using the 'session'
4458      in different threads, for sending and receiving.
4459
4460      *Returns:* 0 if trying to read data, 1 if trying to write data.
4461
4462 gnutls_record_get_max_size
4463 --------------------------
4464
4465  -- Function: size_t gnutls_record_get_max_size (gnutls_session_t
4466           SESSION)
4467      SESSION: is a 'gnutls_session_t' structure.
4468
4469      Get the record size.  The maximum record size is negotiated by the
4470      client after the first handshake message.
4471
4472      *Returns:* The maximum record packet size in this connection.
4473
4474 gnutls_record_overhead_size
4475 ---------------------------
4476
4477  -- Function: size_t gnutls_record_overhead_size (gnutls_session_t
4478           SESSION)
4479      SESSION: is 'gnutls_session_t'
4480
4481      This function will return the set size in bytes of the overhead due
4482      to TLS (or DTLS) per record.
4483
4484      *Since:* 3.2.2
4485
4486 gnutls_record_recv
4487 ------------------
4488
4489  -- Function: ssize_t gnutls_record_recv (gnutls_session_t SESSION, void
4490           * DATA, size_t DATA_SIZE)
4491      SESSION: is a 'gnutls_session_t' structure.
4492
4493      DATA: the buffer that the data will be read into
4494
4495      DATA_SIZE: the number of requested bytes
4496
4497      This function has the similar semantics with 'recv()' .  The only
4498      difference is that it accepts a GnuTLS session, and uses different
4499      error codes.  In the special case that a server requests a
4500      renegotiation, the client may receive an error code of
4501      'GNUTLS_E_REHANDSHAKE' .  This message may be simply ignored,
4502      replied with an alert 'GNUTLS_A_NO_RENEGOTIATION' , or replied with
4503      a new handshake, depending on the client's will.  If 'EINTR' is
4504      returned by the internal push function (the default is 'recv()' )
4505      then 'GNUTLS_E_INTERRUPTED' will be returned.  If
4506      'GNUTLS_E_INTERRUPTED' or 'GNUTLS_E_AGAIN' is returned, you must
4507      call this function again to get the data.  See also
4508      'gnutls_record_get_direction()' .  A server may also receive
4509      'GNUTLS_E_REHANDSHAKE' when a client has initiated a handshake.  In
4510      that case the server can only initiate a handshake or terminate the
4511      connection.
4512
4513      *Returns:* The number of bytes received and zero on EOF (for stream
4514      connections).  A negative error code is returned in case of an
4515      error.  The number of bytes received might be less than the
4516      requested 'data_size' .
4517
4518 gnutls_record_recv_packet
4519 -------------------------
4520
4521  -- Function: ssize_t gnutls_record_recv_packet (gnutls_session_t
4522           SESSION, gnutls_packet_t * PACKET)
4523      SESSION: is a 'gnutls_session_t' structure.
4524
4525      PACKET: the structure that will hold the packet data
4526
4527      This is a lower-level function thatn 'gnutls_record_recv()' and
4528      allows to directly receive the whole decrypted packet.  That avoids
4529      a memory copy, and is mostly applicable to applications seeking
4530      high performance.
4531
4532      The received packet is accessed using 'gnutls_packet_get()' and
4533      must be deinitialized using 'gnutls_packet_deinit()' .  The
4534      returned packet will be 'NULL' if the return value is zero (EOF).
4535
4536      *Returns:* The number of bytes received and zero on EOF (for stream
4537      connections).  A negative error code is returned in case of an
4538      error.
4539
4540      *Since:* 3.3.5
4541
4542 gnutls_record_recv_seq
4543 ----------------------
4544
4545  -- Function: ssize_t gnutls_record_recv_seq (gnutls_session_t SESSION,
4546           void * DATA, size_t DATA_SIZE, unsigned char * SEQ)
4547      SESSION: is a 'gnutls_session_t' structure.
4548
4549      DATA: the buffer that the data will be read into
4550
4551      DATA_SIZE: the number of requested bytes
4552
4553      SEQ: is the packet's 64-bit sequence number.  Should have space for
4554      8 bytes.
4555
4556      This function is the same as 'gnutls_record_recv()' , except that
4557      it returns in addition to data, the sequence number of the data.
4558      This is useful in DTLS where record packets might be received
4559      out-of-order.  The returned 8-byte sequence number is an integer in
4560      big-endian format and should be treated as a unique message
4561      identification.
4562
4563      *Returns:* The number of bytes received and zero on EOF. A negative
4564      error code is returned in case of an error.  The number of bytes
4565      received might be less than 'data_size' .
4566
4567      *Since:* 3.0
4568
4569 gnutls_record_send
4570 ------------------
4571
4572  -- Function: ssize_t gnutls_record_send (gnutls_session_t SESSION,
4573           const void * DATA, size_t DATA_SIZE)
4574      SESSION: is a 'gnutls_session_t' structure.
4575
4576      DATA: contains the data to send
4577
4578      DATA_SIZE: is the length of the data
4579
4580      This function has the similar semantics with 'send()' .  The only
4581      difference is that it accepts a GnuTLS session, and uses different
4582      error codes.  Note that if the send buffer is full, 'send()' will
4583      block this function.  See the 'send()' documentation for more
4584      information.
4585
4586      You can replace the default push function which is 'send()' , by
4587      using 'gnutls_transport_set_push_function()' .
4588
4589      If the EINTR is returned by the internal push function then
4590      'GNUTLS_E_INTERRUPTED' will be returned.  If 'GNUTLS_E_INTERRUPTED'
4591      or 'GNUTLS_E_AGAIN' is returned, you must call this function again,
4592      with the exact same parameters; alternatively you could provide a
4593      'NULL' pointer for data, and 0 for size.  cf.
4594      'gnutls_record_get_direction()' .
4595
4596      Note that in DTLS this function will return the
4597      'GNUTLS_E_LARGE_PACKET' error code if the send data exceed the data
4598      MTU value - as returned by 'gnutls_dtls_get_data_mtu()' .  The
4599      errno value EMSGSIZE also maps to 'GNUTLS_E_LARGE_PACKET' .  Note
4600      that since 3.2.13 this function can be called under cork in DTLS
4601      mode, and will refuse to send data over the MTU size by returning
4602      'GNUTLS_E_LARGE_PACKET' .
4603
4604      *Returns:* The number of bytes sent, or a negative error code.  The
4605      number of bytes sent might be less than 'data_size' .  The maximum
4606      number of bytes this function can send in a single call depends on
4607      the negotiated maximum record size.
4608
4609 gnutls_record_send_range
4610 ------------------------
4611
4612  -- Function: ssize_t gnutls_record_send_range (gnutls_session_t
4613           SESSION, const void * DATA, size_t DATA_SIZE, const
4614           gnutls_range_st * RANGE)
4615      SESSION: is a 'gnutls_session_t' structure.
4616
4617      DATA: contains the data to send.
4618
4619      DATA_SIZE: is the length of the data.
4620
4621      RANGE: is the range of lengths in which the real data length must
4622      be hidden.
4623
4624      This function operates like 'gnutls_record_send()' but, while
4625      'gnutls_record_send()' adds minimal padding to each TLS record,
4626      this function uses the TLS extra-padding feature to conceal the
4627      real data size within the range of lengths provided.  Some TLS
4628      sessions do not support extra padding (e.g.  stream ciphers in
4629      standard TLS or SSL3 sessions).  To know whether the current
4630      session supports extra padding, and hence length hiding, use the
4631      'gnutls_record_can_use_length_hiding()' function.
4632
4633      *Note:* This function currently is only limited to blocking
4634      sockets.
4635
4636      *Returns:* The number of bytes sent (that is data_size in a
4637      successful invocation), or a negative error code.
4638
4639 gnutls_record_set_max_empty_records
4640 -----------------------------------
4641
4642  -- Function: void gnutls_record_set_max_empty_records (gnutls_session_t
4643           SESSION, const unsigned int I)
4644      SESSION: is a 'gnutls_session_t' structure.
4645
4646      I: is the desired value of maximum empty records that can be
4647      accepted in a row.
4648
4649      Used to set the maximum number of empty fragments that can be
4650      accepted in a row.  Accepting many empty fragments is useful for
4651      receiving length-hidden content, where empty fragments filled with
4652      pad are sent to hide the real length of a message.  However, a
4653      malicious peer could send empty fragments to mount a DoS attack, so
4654      as a safety measure, a maximum number of empty fragments is
4655      accepted by default.  If you know your application must accept a
4656      given number of empty fragments in a row, you can use this function
4657      to set the desired value.
4658
4659 gnutls_record_set_max_size
4660 --------------------------
4661
4662  -- Function: ssize_t gnutls_record_set_max_size (gnutls_session_t
4663           SESSION, size_t SIZE)
4664      SESSION: is a 'gnutls_session_t' structure.
4665
4666      SIZE: is the new size
4667
4668      This function sets the maximum record packet size in this
4669      connection.  This property can only be set to clients.  The server
4670      may choose not to accept the requested size.
4671
4672      Acceptable values are 512(=2^9), 1024(=2^10), 2048(=2^11) and
4673      4096(=2^12).  The requested record size does get in effect
4674      immediately only while sending data.  The receive part will take
4675      effect after a successful handshake.
4676
4677      This function uses a TLS extension called 'max record size'.  Not
4678      all TLS implementations use or even understand this extension.
4679
4680      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4681      otherwise a negative error code is returned.
4682
4683 gnutls_record_set_timeout
4684 -------------------------
4685
4686  -- Function: void gnutls_record_set_timeout (gnutls_session_t SESSION,
4687           unsigned int MS)
4688      SESSION: is a 'gnutls_session_t' structure.
4689
4690      MS: is a timeout value in milliseconds
4691
4692      This function sets the receive timeout for the record layer to the
4693      provided value.  Use an 'ms' value of zero to disable timeout (the
4694      default).
4695
4696      *Since:* 3.1.7
4697
4698 gnutls_record_uncork
4699 --------------------
4700
4701  -- Function: int gnutls_record_uncork (gnutls_session_t SESSION,
4702           unsigned int FLAGS)
4703      SESSION: is a 'gnutls_session_t' structure.
4704
4705      FLAGS: Could be zero or 'GNUTLS_RECORD_WAIT'
4706
4707      This resets the effect of 'gnutls_record_cork()' , and flushes any
4708      pending data.  If the 'GNUTLS_RECORD_WAIT' flag is specified then
4709      this function will block until the data is sent or a fatal error
4710      occurs (i.e., the function will retry on 'GNUTLS_E_AGAIN' and
4711      'GNUTLS_E_INTERRUPTED' ).
4712
4713      If the flag 'GNUTLS_RECORD_WAIT' is not specified and the function
4714      is interrupted then the 'GNUTLS_E_AGAIN' or 'GNUTLS_E_INTERRUPTED'
4715      errors will be returned.  To obtain the data left in the corked
4716      buffer use 'gnutls_record_check_corked()' .
4717
4718      *Returns:* On success the number of transmitted data is returned,
4719      or otherwise a negative error code.
4720
4721      *Since:* 3.1.9
4722
4723 gnutls_rehandshake
4724 ------------------
4725
4726  -- Function: int gnutls_rehandshake (gnutls_session_t SESSION)
4727      SESSION: is a 'gnutls_session_t' structure.
4728
4729      This function will renegotiate security parameters with the client.
4730      This should only be called in case of a server.
4731
4732      This message informs the peer that we want to renegotiate
4733      parameters (perform a handshake).
4734
4735      If this function succeeds (returns 0), you must call the
4736      'gnutls_handshake()' function in order to negotiate the new
4737      parameters.
4738
4739      Since TLS is full duplex some application data might have been sent
4740      during peer's processing of this message.  In that case one should
4741      call 'gnutls_record_recv()' until GNUTLS_E_REHANDSHAKE is returned
4742      to clear any pending data.  Care must be taken if rehandshake is
4743      mandatory to terminate if it does not start after some threshold.
4744
4745      If the client does not wish to renegotiate parameters he should
4746      reply with an alert message, thus the return code will be
4747      'GNUTLS_E_WARNING_ALERT_RECEIVED' and the alert will be
4748      'GNUTLS_A_NO_RENEGOTIATION' .  A client may also choose to ignore
4749      this message.
4750
4751      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
4752      error code.
4753
4754 gnutls_safe_renegotiation_status
4755 --------------------------------
4756
4757  -- Function: int gnutls_safe_renegotiation_status (gnutls_session_t
4758           SESSION)
4759      SESSION: is a 'gnutls_session_t' structure.
4760
4761      Can be used to check whether safe renegotiation is being used in
4762      the current session.
4763
4764      *Returns:* 0 when safe renegotiation is not used and non (0) when
4765      safe renegotiation is used.
4766
4767      *Since:* 2.10.0
4768
4769 gnutls_sec_param_get_name
4770 -------------------------
4771
4772  -- Function: const char * gnutls_sec_param_get_name (gnutls_sec_param_t
4773           PARAM)
4774      PARAM: is a security parameter
4775
4776      Convert a 'gnutls_sec_param_t' value to a string.
4777
4778      *Returns:* a pointer to a string that contains the name of the
4779      specified security level, or 'NULL' .
4780
4781      *Since:* 2.12.0
4782
4783 gnutls_sec_param_to_pk_bits
4784 ---------------------------
4785
4786  -- Function: unsigned int gnutls_sec_param_to_pk_bits
4787           (gnutls_pk_algorithm_t ALGO, gnutls_sec_param_t PARAM)
4788      ALGO: is a public key algorithm
4789
4790      PARAM: is a security parameter
4791
4792      When generating private and public key pairs a difficult question
4793      is which size of "bits" the modulus will be in RSA and the group
4794      size in DSA. The easy answer is 1024, which is also wrong.  This
4795      function will convert a human understandable security parameter to
4796      an appropriate size for the specific algorithm.
4797
4798      *Returns:* The number of bits, or (0).
4799
4800      *Since:* 2.12.0
4801
4802 gnutls_sec_param_to_symmetric_bits
4803 ----------------------------------
4804
4805  -- Function: unsigned int gnutls_sec_param_to_symmetric_bits
4806           (gnutls_sec_param_t PARAM)
4807      PARAM: is a security parameter
4808
4809      This function will return the number of bits that correspond to
4810      symmetric cipher strength for the given security parameter.
4811
4812      *Returns:* The number of bits, or (0).
4813
4814      *Since:* 3.3.0
4815
4816 gnutls_server_name_get
4817 ----------------------
4818
4819  -- Function: int gnutls_server_name_get (gnutls_session_t SESSION, void
4820           * DATA, size_t * DATA_LENGTH, unsigned int * TYPE, unsigned
4821           int INDX)
4822      SESSION: is a 'gnutls_session_t' structure.
4823
4824      DATA: will hold the data
4825
4826      DATA_LENGTH: will hold the data length.  Must hold the maximum size
4827      of data.
4828
4829      TYPE: will hold the server name indicator type
4830
4831      INDX: is the index of the server_name
4832
4833      This function will allow you to get the name indication (if any), a
4834      client has sent.  The name indication may be any of the enumeration
4835      gnutls_server_name_type_t.
4836
4837      If 'type' is GNUTLS_NAME_DNS, then this function is to be used by
4838      servers that support virtual hosting, and the data will be a null
4839      terminated UTF-8 string.
4840
4841      If 'data' has not enough size to hold the server name
4842      GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and 'data_length' will
4843      hold the required size.
4844
4845      'index' is used to retrieve more than one server names (if sent by
4846      the client).  The first server name has an index of 0, the second 1
4847      and so on.  If no name with the given index exists
4848      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
4849
4850      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4851      otherwise a negative error code is returned.
4852
4853 gnutls_server_name_set
4854 ----------------------
4855
4856  -- Function: int gnutls_server_name_set (gnutls_session_t SESSION,
4857           gnutls_server_name_type_t TYPE, const void * NAME, size_t
4858           NAME_LENGTH)
4859      SESSION: is a 'gnutls_session_t' structure.
4860
4861      TYPE: specifies the indicator type
4862
4863      NAME: is a string that contains the server name.
4864
4865      NAME_LENGTH: holds the length of name
4866
4867      This function is to be used by clients that want to inform (via a
4868      TLS extension mechanism) the server of the name they connected to.
4869      This should be used by clients that connect to servers that do
4870      virtual hosting.
4871
4872      The value of 'name' depends on the 'type' type.  In case of
4873      'GNUTLS_NAME_DNS' , an ASCII (0)-terminated domain name string,
4874      without the trailing dot, is expected.  IPv4 or IPv6 addresses are
4875      not permitted.
4876
4877      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4878      otherwise a negative error code is returned.
4879
4880 gnutls_session_channel_binding
4881 ------------------------------
4882
4883  -- Function: int gnutls_session_channel_binding (gnutls_session_t
4884           SESSION, gnutls_channel_binding_t CBTYPE, gnutls_datum_t * CB)
4885      SESSION: is a 'gnutls_session_t' structure.
4886
4887      CBTYPE: an 'gnutls_channel_binding_t' enumeration type
4888
4889      CB: output buffer array with data
4890
4891      Extract given channel binding data of the 'cbtype' (e.g.,
4892      'GNUTLS_CB_TLS_UNIQUE' ) type.
4893
4894      *Returns:* 'GNUTLS_E_SUCCESS' on success,
4895      'GNUTLS_E_UNIMPLEMENTED_FEATURE' if the 'cbtype' is unsupported,
4896      'GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE' if the data is not
4897      currently available, or an error code.
4898
4899      *Since:* 2.12.0
4900
4901 gnutls_session_enable_compatibility_mode
4902 ----------------------------------------
4903
4904  -- Function: void gnutls_session_enable_compatibility_mode
4905           (gnutls_session_t SESSION)
4906      SESSION: is a 'gnutls_session_t' structure.
4907
4908      This function can be used to disable certain (security) features in
4909      TLS in order to maintain maximum compatibility with buggy clients.
4910      Because several trade-offs with security are enabled, if required
4911      they will be reported through the audit subsystem.
4912
4913      Normally only servers that require maximum compatibility with
4914      everything out there, need to call this function.
4915
4916      Note that this function must be called after any call to
4917      gnutls_priority functions.
4918
4919 gnutls_session_force_valid
4920 --------------------------
4921
4922  -- Function: void gnutls_session_force_valid (gnutls_session_t SESSION)
4923      SESSION: is a 'gnutls_session_t' structure.
4924
4925      Clears the invalid flag in a session.  That means that sessions
4926      were corrupt or invalid data were received can be re-used.  Use
4927      only when debugging or experimenting with the TLS protocol.  Should
4928      not be used in typical applications.
4929
4930 gnutls_session_get_data
4931 -----------------------
4932
4933  -- Function: int gnutls_session_get_data (gnutls_session_t SESSION,
4934           void * SESSION_DATA, size_t * SESSION_DATA_SIZE)
4935      SESSION: is a 'gnutls_session_t' structure.
4936
4937      SESSION_DATA: is a pointer to space to hold the session.
4938
4939      SESSION_DATA_SIZE: is the session_data's size, or it will be set by
4940      the function.
4941
4942      Returns all session parameters needed to be stored to support
4943      resumption.  The client should call this, and store the returned
4944      session data.  A session may be resumed later by calling
4945      'gnutls_session_set_data()' .  This function must be called after a
4946      successful (full) handshake.  It should not be used in resumed
4947      sessions -see 'gnutls_session_is_resumed()' .
4948
4949      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4950      otherwise an error code is returned.
4951
4952 gnutls_session_get_data2
4953 ------------------------
4954
4955  -- Function: int gnutls_session_get_data2 (gnutls_session_t SESSION,
4956           gnutls_datum_t * DATA)
4957      SESSION: is a 'gnutls_session_t' structure.
4958
4959      DATA: is a pointer to a datum that will hold the session.
4960
4961      Returns all session parameters needed to be stored to support
4962      resumption.  The client should call this, and store the returned
4963      session data.  A session may be resumed later by calling
4964      'gnutls_session_set_data()' .  This function must be called after a
4965      successful (full) handshake.  It should not be used in resumed
4966      sessions -see 'gnutls_session_is_resumed()' .
4967
4968      The returned 'data' are allocated and must be released using
4969      'gnutls_free()' .
4970
4971      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
4972      otherwise an error code is returned.
4973
4974 gnutls_session_get_desc
4975 -----------------------
4976
4977  -- Function: char * gnutls_session_get_desc (gnutls_session_t SESSION)
4978      SESSION: is a gnutls session
4979
4980      This function returns a string describing the current session.  The
4981      string is null terminated and allocated using 'gnutls_malloc()' .
4982
4983      *Returns:* a description of the protocols and algorithms in the
4984      current session.
4985
4986      *Since:* 3.1.10
4987
4988 gnutls_session_get_id
4989 ---------------------
4990
4991  -- Function: int gnutls_session_get_id (gnutls_session_t SESSION, void
4992           * SESSION_ID, size_t * SESSION_ID_SIZE)
4993      SESSION: is a 'gnutls_session_t' structure.
4994
4995      SESSION_ID: is a pointer to space to hold the session id.
4996
4997      SESSION_ID_SIZE: initially should contain the maximum 'session_id'
4998      size and will be updated.
4999
5000      Returns the current session ID. This can be used if you want to
5001      check if the next session you tried to resume was actually resumed.
5002      That is because resumed sessions share the same session ID with the
5003      original session.
5004
5005      The session ID is selected by the server, that identify the current
5006      session.  In TLS 1.0 and SSL 3.0 session id is always less than 32
5007      bytes.
5008
5009      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5010      otherwise an error code is returned.
5011
5012 gnutls_session_get_id2
5013 ----------------------
5014
5015  -- Function: int gnutls_session_get_id2 (gnutls_session_t SESSION,
5016           gnutls_datum_t * SESSION_ID)
5017      SESSION: is a 'gnutls_session_t' structure.
5018
5019      SESSION_ID: will point to the session ID.
5020
5021      Returns the current session ID. The returned data should be treated
5022      as constant.
5023
5024      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5025      otherwise an error code is returned.
5026
5027      *Since:* 3.1.4
5028
5029 gnutls_session_get_ptr
5030 ----------------------
5031
5032  -- Function: void * gnutls_session_get_ptr (gnutls_session_t SESSION)
5033      SESSION: is a 'gnutls_session_t' structure.
5034
5035      Get user pointer for session.  Useful in callbacks.  This is the
5036      pointer set with 'gnutls_session_set_ptr()' .
5037
5038      *Returns:* the user given pointer from the session structure, or
5039      'NULL' if it was never set.
5040
5041 gnutls_session_get_random
5042 -------------------------
5043
5044  -- Function: void gnutls_session_get_random (gnutls_session_t SESSION,
5045           gnutls_datum_t * CLIENT, gnutls_datum_t * SERVER)
5046      SESSION: is a 'gnutls_session_t' structure.
5047
5048      CLIENT: the client part of the random
5049
5050      SERVER: the server part of the random
5051
5052      This function returns pointers to the client and server random
5053      fields used in the TLS handshake.  The pointers are not to be
5054      modified or deallocated.
5055
5056      If a client random value has not yet been established, the output
5057      will be garbage.
5058
5059      *Since:* 3.0
5060
5061 gnutls_session_is_resumed
5062 -------------------------
5063
5064  -- Function: int gnutls_session_is_resumed (gnutls_session_t SESSION)
5065      SESSION: is a 'gnutls_session_t' structure.
5066
5067      Check whether session is resumed or not.
5068
5069      *Returns:* non zero if this session is resumed, or a zero if this
5070      is a new session.
5071
5072 gnutls_session_resumption_requested
5073 -----------------------------------
5074
5075  -- Function: int gnutls_session_resumption_requested (gnutls_session_t
5076           SESSION)
5077      SESSION: is a 'gnutls_session_t' structure.
5078
5079      Check whether the client has asked for session resumption.  This
5080      function is valid only on server side.
5081
5082      *Returns:* non zero if session resumption was asked, or a zero if
5083      not.
5084
5085 gnutls_session_set_data
5086 -----------------------
5087
5088  -- Function: int gnutls_session_set_data (gnutls_session_t SESSION,
5089           const void * SESSION_DATA, size_t SESSION_DATA_SIZE)
5090      SESSION: is a 'gnutls_session_t' structure.
5091
5092      SESSION_DATA: is a pointer to space to hold the session.
5093
5094      SESSION_DATA_SIZE: is the session's size
5095
5096      Sets all session parameters, in order to resume a previously
5097      established session.  The session data given must be the one
5098      returned by 'gnutls_session_get_data()' .  This function should be
5099      called before 'gnutls_handshake()' .
5100
5101      Keep in mind that session resuming is advisory.  The server may
5102      choose not to resume the session, thus a full handshake will be
5103      performed.
5104
5105      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5106      otherwise an error code is returned.
5107
5108 gnutls_session_set_id
5109 ---------------------
5110
5111  -- Function: int gnutls_session_set_id (gnutls_session_t SESSION, const
5112           gnutls_datum_t * SID)
5113      SESSION: is a 'gnutls_session_t' structure.
5114
5115      SID: the session identifier
5116
5117      This function sets the session ID to be used in a client hello.
5118      This is a function intended for exceptional uses.  Do not use this
5119      function unless you are implementing a custom protocol.
5120
5121      To set session resumption parameters use
5122      'gnutls_session_set_data()' instead.
5123
5124      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5125      otherwise an error code is returned.
5126
5127 gnutls_session_set_premaster
5128 ----------------------------
5129
5130  -- Function: int gnutls_session_set_premaster (gnutls_session_t
5131           SESSION, unsigned int ENTITY, gnutls_protocol_t VERSION,
5132           gnutls_kx_algorithm_t KX, gnutls_cipher_algorithm_t CIPHER,
5133           gnutls_mac_algorithm_t MAC, gnutls_compression_method_t COMP,
5134           const gnutls_datum_t * MASTER, const gnutls_datum_t *
5135           SESSION_ID)
5136      SESSION: is a 'gnutls_session_t' structure.
5137
5138      ENTITY: GNUTLS_SERVER or GNUTLS_CLIENT
5139
5140      VERSION: the TLS protocol version
5141
5142      KX: the key exchange method
5143
5144      CIPHER: the cipher
5145
5146      MAC: the MAC algorithm
5147
5148      COMP: the compression method
5149
5150      MASTER: the master key to use
5151
5152      SESSION_ID: the session identifier
5153
5154      This function sets the premaster secret in a session.  This is a
5155      function intended for exceptional uses.  Do not use this function
5156      unless you are implementing a legacy protocol.  Use
5157      'gnutls_session_set_data()' instead.
5158
5159      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5160      otherwise an error code is returned.
5161
5162 gnutls_session_set_ptr
5163 ----------------------
5164
5165  -- Function: void gnutls_session_set_ptr (gnutls_session_t SESSION,
5166           void * PTR)
5167      SESSION: is a 'gnutls_session_t' structure.
5168
5169      PTR: is the user pointer
5170
5171      This function will set (associate) the user given pointer 'ptr' to
5172      the session structure.  This pointer can be accessed with
5173      'gnutls_session_get_ptr()' .
5174
5175 gnutls_session_ticket_enable_client
5176 -----------------------------------
5177
5178  -- Function: int gnutls_session_ticket_enable_client (gnutls_session_t
5179           SESSION)
5180      SESSION: is a 'gnutls_session_t' structure.
5181
5182      Request that the client should attempt session resumption using
5183      SessionTicket.
5184
5185      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5186      error code.
5187
5188      *Since:* 2.10.0
5189
5190 gnutls_session_ticket_enable_server
5191 -----------------------------------
5192
5193  -- Function: int gnutls_session_ticket_enable_server (gnutls_session_t
5194           SESSION, const gnutls_datum_t * KEY)
5195      SESSION: is a 'gnutls_session_t' structure.
5196
5197      KEY: key to encrypt session parameters.
5198
5199      Request that the server should attempt session resumption using
5200      SessionTicket.  'key' must be initialized with
5201      'gnutls_session_ticket_key_generate()' .
5202
5203      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5204      error code.
5205
5206      *Since:* 2.10.0
5207
5208 gnutls_session_ticket_key_generate
5209 ----------------------------------
5210
5211  -- Function: int gnutls_session_ticket_key_generate (gnutls_datum_t *
5212           KEY)
5213      KEY: is a pointer to a 'gnutls_datum_t' which will contain a newly
5214      created key.
5215
5216      Generate a random key to encrypt security parameters within
5217      SessionTicket.
5218
5219      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5220      error code.
5221
5222      *Since:* 2.10.0
5223
5224 gnutls_set_default_priority
5225 ---------------------------
5226
5227  -- Function: int gnutls_set_default_priority (gnutls_session_t SESSION)
5228      SESSION: is a 'gnutls_session_t' structure.
5229
5230      Sets the default priority on the ciphers, key exchange methods,
5231      macs and compression methods.  For more fine-tuning you could use
5232      'gnutls_priority_set_direct()' or 'gnutls_priority_set()' instead.
5233
5234      *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
5235
5236 gnutls_sign_algorithm_get
5237 -------------------------
5238
5239  -- Function: int gnutls_sign_algorithm_get (gnutls_session_t SESSION)
5240      SESSION: is a 'gnutls_session_t' structure.
5241
5242      Returns the signature algorithm that is (or will be) used in this
5243      session by the server to sign data.
5244
5245      *Returns:* The sign algorithm or 'GNUTLS_SIGN_UNKNOWN' .
5246
5247      *Since:* 3.1.1
5248
5249 gnutls_sign_algorithm_get_client
5250 --------------------------------
5251
5252  -- Function: int gnutls_sign_algorithm_get_client (gnutls_session_t
5253           SESSION)
5254      SESSION: is a 'gnutls_session_t' structure.
5255
5256      Returns the signature algorithm that is (or will be) used in this
5257      session by the client to sign data.
5258
5259      *Returns:* The sign algorithm or 'GNUTLS_SIGN_UNKNOWN' .
5260
5261      *Since:* 3.1.11
5262
5263 gnutls_sign_algorithm_get_requested
5264 -----------------------------------
5265
5266  -- Function: int gnutls_sign_algorithm_get_requested (gnutls_session_t
5267           SESSION, size_t INDX, gnutls_sign_algorithm_t * ALGO)
5268      SESSION: is a 'gnutls_session_t' structure.
5269
5270      INDX: is an index of the signature algorithm to return
5271
5272      ALGO: the returned certificate type will be stored there
5273
5274      Returns the signature algorithm specified by index that was
5275      requested by the peer.  If the specified index has no data
5276      available this function returns
5277      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .  If the negotiated TLS
5278      version does not support signature algorithms then
5279      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned even for
5280      the first index.  The first index is 0.
5281
5282      This function is useful in the certificate callback functions to
5283      assist in selecting the correct certificate.
5284
5285      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5286      otherwise an error code is returned.
5287
5288      *Since:* 2.10.0
5289
5290 gnutls_sign_get_hash_algorithm
5291 ------------------------------
5292
5293  -- Function: gnutls_digest_algorithm_t gnutls_sign_get_hash_algorithm
5294           (gnutls_sign_algorithm_t SIGN)
5295      SIGN: is a signature algorithm
5296
5297      This function returns the digest algorithm corresponding to the
5298      given signature algorithms.
5299
5300      *Since:* 3.1.1
5301
5302      *Returns:* return a 'gnutls_digest_algorithm_t' value, or
5303      'GNUTLS_DIG_UNKNOWN' on error.
5304
5305 gnutls_sign_get_id
5306 ------------------
5307
5308  -- Function: gnutls_sign_algorithm_t gnutls_sign_get_id (const char *
5309           NAME)
5310      NAME: is a sign algorithm name
5311
5312      The names are compared in a case insensitive way.
5313
5314      *Returns:* return a 'gnutls_sign_algorithm_t' value corresponding
5315      to the specified algorithm, or 'GNUTLS_SIGN_UNKNOWN' on error.
5316
5317 gnutls_sign_get_name
5318 --------------------
5319
5320  -- Function: const char * gnutls_sign_get_name (gnutls_sign_algorithm_t
5321           ALGORITHM)
5322      ALGORITHM: is a sign algorithm
5323
5324      Convert a 'gnutls_sign_algorithm_t' value to a string.
5325
5326      *Returns:* a string that contains the name of the specified sign
5327      algorithm, or 'NULL' .
5328
5329 gnutls_sign_get_pk_algorithm
5330 ----------------------------
5331
5332  -- Function: gnutls_pk_algorithm_t gnutls_sign_get_pk_algorithm
5333           (gnutls_sign_algorithm_t SIGN)
5334      SIGN: is a signature algorithm
5335
5336      This function returns the public key algorithm corresponding to the
5337      given signature algorithms.
5338
5339      *Since:* 3.1.1
5340
5341      *Returns:* return a 'gnutls_pk_algorithm_t' value, or
5342      'GNUTLS_PK_UNKNOWN' on error.
5343
5344 gnutls_sign_is_secure
5345 ---------------------
5346
5347  -- Function: int gnutls_sign_is_secure (gnutls_sign_algorithm_t
5348           ALGORITHM)
5349      ALGORITHM: is a sign algorithm
5350
5351      *Returns:* Non-zero if the provided signature algorithm is
5352      considered to be secure.
5353
5354 gnutls_sign_list
5355 ----------------
5356
5357  -- Function: const gnutls_sign_algorithm_t * gnutls_sign_list ( VOID)
5358
5359      Get a list of supported public key signature algorithms.
5360
5361      *Returns:* a (0)-terminated list of 'gnutls_sign_algorithm_t'
5362      integers indicating the available ciphers.
5363
5364 gnutls_srp_allocate_client_credentials
5365 --------------------------------------
5366
5367  -- Function: int gnutls_srp_allocate_client_credentials
5368           (gnutls_srp_client_credentials_t * SC)
5369      SC: is a pointer to a 'gnutls_srp_server_credentials_t' structure.
5370
5371      This structure is complex enough to manipulate directly thus this
5372      helper function is provided in order to allocate it.
5373
5374      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5375      error code.
5376
5377 gnutls_srp_allocate_server_credentials
5378 --------------------------------------
5379
5380  -- Function: int gnutls_srp_allocate_server_credentials
5381           (gnutls_srp_server_credentials_t * SC)
5382      SC: is a pointer to a 'gnutls_srp_server_credentials_t' structure.
5383
5384      This structure is complex enough to manipulate directly thus this
5385      helper function is provided in order to allocate it.
5386
5387      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5388      error code.
5389
5390 gnutls_srp_base64_decode
5391 ------------------------
5392
5393  -- Function: int gnutls_srp_base64_decode (const gnutls_datum_t *
5394           B64_DATA, char * RESULT, size_t * RESULT_SIZE)
5395      B64_DATA: contain the encoded data
5396
5397      RESULT: the place where decoded data will be copied
5398
5399      RESULT_SIZE: holds the size of the result
5400
5401      This function will decode the given encoded data, using the base64
5402      encoding found in libsrp.
5403
5404      Note that 'b64_data' should be null terminated.
5405
5406      Warning!  This base64 encoding is not the "standard" encoding, so
5407      do not use it for non-SRP purposes.
5408
5409      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
5410      not long enough, or 0 on success.
5411
5412 gnutls_srp_base64_decode_alloc
5413 ------------------------------
5414
5415  -- Function: int gnutls_srp_base64_decode_alloc (const gnutls_datum_t *
5416           B64_DATA, gnutls_datum_t * RESULT)
5417      B64_DATA: contains the encoded data
5418
5419      RESULT: the place where decoded data lie
5420
5421      This function will decode the given encoded data.  The decoded data
5422      will be allocated, and stored into result.  It will decode using
5423      the base64 algorithm as used in libsrp.
5424
5425      You should use 'gnutls_free()' to free the returned data.
5426
5427      Warning!  This base64 encoding is not the "standard" encoding, so
5428      do not use it for non-SRP purposes.
5429
5430      *Returns:* 0 on success, or an error code.
5431
5432 gnutls_srp_base64_encode
5433 ------------------------
5434
5435  -- Function: int gnutls_srp_base64_encode (const gnutls_datum_t * DATA,
5436           char * RESULT, size_t * RESULT_SIZE)
5437      DATA: contain the raw data
5438
5439      RESULT: the place where base64 data will be copied
5440
5441      RESULT_SIZE: holds the size of the result
5442
5443      This function will convert the given data to printable data, using
5444      the base64 encoding, as used in the libsrp.  This is the encoding
5445      used in SRP password files.  If the provided buffer is not long
5446      enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
5447
5448      Warning!  This base64 encoding is not the "standard" encoding, so
5449      do not use it for non-SRP purposes.
5450
5451      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
5452      not long enough, or 0 on success.
5453
5454 gnutls_srp_base64_encode_alloc
5455 ------------------------------
5456
5457  -- Function: int gnutls_srp_base64_encode_alloc (const gnutls_datum_t *
5458           DATA, gnutls_datum_t * RESULT)
5459      DATA: contains the raw data
5460
5461      RESULT: will hold the newly allocated encoded data
5462
5463      This function will convert the given data to printable data, using
5464      the base64 encoding.  This is the encoding used in SRP password
5465      files.  This function will allocate the required memory to hold the
5466      encoded data.
5467
5468      You should use 'gnutls_free()' to free the returned data.
5469
5470      Warning!  This base64 encoding is not the "standard" encoding, so
5471      do not use it for non-SRP purposes.
5472
5473      *Returns:* 0 on success, or an error code.
5474
5475 gnutls_srp_free_client_credentials
5476 ----------------------------------
5477
5478  -- Function: void gnutls_srp_free_client_credentials
5479           (gnutls_srp_client_credentials_t SC)
5480      SC: is a 'gnutls_srp_client_credentials_t' structure.
5481
5482      This structure is complex enough to manipulate directly thus this
5483      helper function is provided in order to free (deallocate) it.
5484
5485 gnutls_srp_free_server_credentials
5486 ----------------------------------
5487
5488  -- Function: void gnutls_srp_free_server_credentials
5489           (gnutls_srp_server_credentials_t SC)
5490      SC: is a 'gnutls_srp_server_credentials_t' structure.
5491
5492      This structure is complex enough to manipulate directly thus this
5493      helper function is provided in order to free (deallocate) it.
5494
5495 gnutls_srp_server_get_username
5496 ------------------------------
5497
5498  -- Function: const char * gnutls_srp_server_get_username
5499           (gnutls_session_t SESSION)
5500      SESSION: is a gnutls session
5501
5502      This function will return the username of the peer.  This should
5503      only be called in case of SRP authentication and in case of a
5504      server.  Returns NULL in case of an error.
5505
5506      *Returns:* SRP username of the peer, or NULL in case of error.
5507
5508 gnutls_srp_set_client_credentials
5509 ---------------------------------
5510
5511  -- Function: int gnutls_srp_set_client_credentials
5512           (gnutls_srp_client_credentials_t RES, const char * USERNAME,
5513           const char * PASSWORD)
5514      RES: is a 'gnutls_srp_client_credentials_t' structure.
5515
5516      USERNAME: is the user's userid
5517
5518      PASSWORD: is the user's password
5519
5520      This function sets the username and password, in a
5521      'gnutls_srp_client_credentials_t' structure.  Those will be used in
5522      SRP authentication.  'username' and 'password' should be ASCII
5523      strings or UTF-8 strings prepared using the "SASLprep" profile of
5524      "stringprep".
5525
5526      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5527      error code.
5528
5529 gnutls_srp_set_client_credentials_function
5530 ------------------------------------------
5531
5532  -- Function: void gnutls_srp_set_client_credentials_function
5533           (gnutls_srp_client_credentials_t CRED,
5534           gnutls_srp_client_credentials_function * FUNC)
5535      CRED: is a 'gnutls_srp_server_credentials_t' structure.
5536
5537      FUNC: is the callback function
5538
5539      This function can be used to set a callback to retrieve the
5540      username and password for client SRP authentication.  The
5541      callback's function form is:
5542
5543      int (*callback)(gnutls_session_t, char** username, char**password);
5544
5545      The 'username' and 'password' must be allocated using
5546      'gnutls_malloc()' .  'username' and 'password' should be ASCII
5547      strings or UTF-8 strings prepared using the "SASLprep" profile of
5548      "stringprep".
5549
5550      The callback function will be called once per handshake before the
5551      initial hello message is sent.
5552
5553      The callback should not return a negative error code the second
5554      time called, since the handshake procedure will be aborted.
5555
5556      The callback function should return 0 on success.  -1 indicates an
5557      error.
5558
5559 gnutls_srp_set_prime_bits
5560 -------------------------
5561
5562  -- Function: void gnutls_srp_set_prime_bits (gnutls_session_t SESSION,
5563           unsigned int BITS)
5564      SESSION: is a 'gnutls_session_t' structure.
5565
5566      BITS: is the number of bits
5567
5568      This function sets the minimum accepted number of bits, for use in
5569      an SRP key exchange.  If zero, the default 2048 bits will be used.
5570
5571      In the client side it sets the minimum accepted number of bits.  If
5572      a server sends a prime with less bits than that
5573      'GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER' will be returned by the
5574      handshake.
5575
5576      This function has no effect in server side.
5577
5578      *Since:* 2.6.0
5579
5580 gnutls_srp_set_server_credentials_file
5581 --------------------------------------
5582
5583  -- Function: int gnutls_srp_set_server_credentials_file
5584           (gnutls_srp_server_credentials_t RES, const char *
5585           PASSWORD_FILE, const char * PASSWORD_CONF_FILE)
5586      RES: is a 'gnutls_srp_server_credentials_t' structure.
5587
5588      PASSWORD_FILE: is the SRP password file (tpasswd)
5589
5590      PASSWORD_CONF_FILE: is the SRP password conf file (tpasswd.conf)
5591
5592      This function sets the password files, in a
5593      'gnutls_srp_server_credentials_t' structure.  Those password files
5594      hold usernames and verifiers and will be used for SRP
5595      authentication.
5596
5597      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5598      error code.
5599
5600 gnutls_srp_set_server_credentials_function
5601 ------------------------------------------
5602
5603  -- Function: void gnutls_srp_set_server_credentials_function
5604           (gnutls_srp_server_credentials_t CRED,
5605           gnutls_srp_server_credentials_function * FUNC)
5606      CRED: is a 'gnutls_srp_server_credentials_t' structure.
5607
5608      FUNC: is the callback function
5609
5610      This function can be used to set a callback to retrieve the user's
5611      SRP credentials.  The callback's function form is:
5612
5613      int (*callback)(gnutls_session_t, const char* username,
5614      gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t
5615      *generator, gnutls_datum_t *prime);
5616
5617      'username' contains the actual username.  The 'salt' , 'verifier' ,
5618      'generator' and 'prime' must be filled in using the
5619      'gnutls_malloc()' .  For convenience 'prime' and 'generator' may
5620      also be one of the static parameters defined in gnutls.h.
5621
5622      Initially, the data field is NULL in every 'gnutls_datum_t'
5623      structure that the callback has to fill in.  When the callback is
5624      done GnuTLS deallocates all of those buffers which are non-NULL,
5625      regardless of the return value.
5626
5627      In order to prevent attackers from guessing valid usernames, if a
5628      user does not exist, g and n values should be filled in using a
5629      random user's parameters.  In that case the callback must return
5630      the special value (1).  See 'gnutls_srp_set_server_fake_salt_seed'
5631      too.  If this is not required for your application, return a
5632      negative number from the callback to abort the handshake.
5633
5634      The callback function will only be called once per handshake.  The
5635      callback function should return 0 on success, while -1 indicates an
5636      error.
5637
5638 gnutls_srp_set_server_fake_salt_seed
5639 ------------------------------------
5640
5641  -- Function: void gnutls_srp_set_server_fake_salt_seed
5642           (gnutls_srp_server_credentials_t CRED, const gnutls_datum_t *
5643           SEED, unsigned int SALT_LENGTH)
5644      CRED: is a 'gnutls_srp_server_credentials_t' structure
5645
5646      SEED: is the seed data, only needs to be valid until the function
5647      returns; size of the seed must be greater than zero
5648
5649      SALT_LENGTH: is the length of the generated fake salts
5650
5651      This function sets the seed that is used to generate salts for
5652      invalid (non-existent) usernames.
5653
5654      In order to prevent attackers from guessing valid usernames, when a
5655      user does not exist gnutls generates a salt and a verifier and
5656      proceeds with the protocol as usual.  The authentication will
5657      ultimately fail, but the client cannot tell whether the username is
5658      valid (exists) or invalid.
5659
5660      If an attacker learns the seed, given a salt (which is part of the
5661      handshake) which was generated when the seed was in use, it can
5662      tell whether or not the authentication failed because of an unknown
5663      username.  This seed cannot be used to reveal application data or
5664      passwords.
5665
5666      'salt_length' should represent the salt length your application
5667      uses.  Generating fake salts longer than 20 bytes is not supported.
5668
5669      By default the seed is a random value, different each time a
5670      'gnutls_srp_server_credentials_t' is allocated and fake salts are
5671      16 bytes long.
5672
5673      *Since:* 3.3.0
5674
5675 gnutls_srp_verifier
5676 -------------------
5677
5678  -- Function: int gnutls_srp_verifier (const char * USERNAME, const char
5679           * PASSWORD, const gnutls_datum_t * SALT, const gnutls_datum_t
5680           * GENERATOR, const gnutls_datum_t * PRIME, gnutls_datum_t *
5681           RES)
5682      USERNAME: is the user's name
5683
5684      PASSWORD: is the user's password
5685
5686      SALT: should be some randomly generated bytes
5687
5688      GENERATOR: is the generator of the group
5689
5690      PRIME: is the group's prime
5691
5692      RES: where the verifier will be stored.
5693
5694      This function will create an SRP verifier, as specified in RFC2945.
5695      The 'prime' and 'generator' should be one of the static parameters
5696      defined in gnutls/gnutls.h or may be generated.
5697
5698      The verifier will be allocated with 'gnutls_malloc' () and will be
5699      stored in 'res' using binary format.
5700
5701      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
5702      error code.
5703
5704 gnutls_srtp_get_keys
5705 --------------------
5706
5707  -- Function: int gnutls_srtp_get_keys (gnutls_session_t SESSION, void *
5708           KEY_MATERIAL, unsigned int KEY_MATERIAL_SIZE, gnutls_datum_t *
5709           CLIENT_KEY, gnutls_datum_t * CLIENT_SALT, gnutls_datum_t *
5710           SERVER_KEY, gnutls_datum_t * SERVER_SALT)
5711      SESSION: is a 'gnutls_session_t' structure.
5712
5713      KEY_MATERIAL: Space to hold the generated key material
5714
5715      KEY_MATERIAL_SIZE: The maximum size of the key material
5716
5717      CLIENT_KEY: The master client write key, pointing inside the key
5718      material
5719
5720      CLIENT_SALT: The master client write salt, pointing inside the key
5721      material
5722
5723      SERVER_KEY: The master server write key, pointing inside the key
5724      material
5725
5726      SERVER_SALT: The master server write salt, pointing inside the key
5727      material
5728
5729      This is a helper function to generate the keying material for SRTP.
5730      It requires the space of the key material to be pre-allocated
5731      (should be at least 2x the maximum key size and salt size).  The
5732      'client_key' , 'client_salt' , 'server_key' and 'server_salt' are
5733      convenience datums that point inside the key material.  They may be
5734      'NULL' .
5735
5736      *Returns:* On success the size of the key material is returned,
5737      otherwise, 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
5738      not sufficient, or a negative error code.
5739
5740      Since 3.1.4
5741
5742 gnutls_srtp_get_mki
5743 -------------------
5744
5745  -- Function: int gnutls_srtp_get_mki (gnutls_session_t SESSION,
5746           gnutls_datum_t * MKI)
5747      SESSION: is a 'gnutls_session_t' structure.
5748
5749      MKI: will hold the MKI
5750
5751      This function exports the negotiated Master Key Identifier,
5752      received by the peer if any.  The returned value in 'mki' should be
5753      treated as constant and valid only during the session's lifetime.
5754
5755      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5756      otherwise a negative error code is returned.
5757
5758      Since 3.1.4
5759
5760 gnutls_srtp_get_profile_id
5761 --------------------------
5762
5763  -- Function: int gnutls_srtp_get_profile_id (const char * NAME,
5764           gnutls_srtp_profile_t * PROFILE)
5765      NAME: The name of the profile to look up
5766
5767      PROFILE: Will hold the profile id
5768
5769      This function allows you to look up a profile based on a string.
5770
5771      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5772      otherwise a negative error code is returned.
5773
5774      Since 3.1.4
5775
5776 gnutls_srtp_get_profile_name
5777 ----------------------------
5778
5779  -- Function: const char * gnutls_srtp_get_profile_name
5780           (gnutls_srtp_profile_t PROFILE)
5781      PROFILE: The profile to look up a string for
5782
5783      This function allows you to get the corresponding name for a SRTP
5784      protection profile.
5785
5786      *Returns:* On success, the name of a SRTP profile as a string,
5787      otherwise NULL.
5788
5789      Since 3.1.4
5790
5791 gnutls_srtp_get_selected_profile
5792 --------------------------------
5793
5794  -- Function: int gnutls_srtp_get_selected_profile (gnutls_session_t
5795           SESSION, gnutls_srtp_profile_t * PROFILE)
5796      SESSION: is a 'gnutls_session_t' structure.
5797
5798      PROFILE: will hold the profile
5799
5800      This function allows you to get the negotiated SRTP profile.
5801
5802      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5803      otherwise a negative error code is returned.
5804
5805      Since 3.1.4
5806
5807 gnutls_srtp_set_mki
5808 -------------------
5809
5810  -- Function: int gnutls_srtp_set_mki (gnutls_session_t SESSION, const
5811           gnutls_datum_t * MKI)
5812      SESSION: is a 'gnutls_session_t' structure.
5813
5814      MKI: holds the MKI
5815
5816      This function sets the Master Key Identifier, to be used by this
5817      session (if any).
5818
5819      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5820      otherwise a negative error code is returned.
5821
5822      Since 3.1.4
5823
5824 gnutls_srtp_set_profile
5825 -----------------------
5826
5827  -- Function: int gnutls_srtp_set_profile (gnutls_session_t SESSION,
5828           gnutls_srtp_profile_t PROFILE)
5829      SESSION: is a 'gnutls_session_t' structure.
5830
5831      PROFILE: is the profile id to add.
5832
5833      This function is to be used by both clients and servers, to declare
5834      what SRTP profiles they support, to negotiate with the peer.
5835
5836      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5837      otherwise a negative error code is returned.
5838
5839      Since 3.1.4
5840
5841 gnutls_srtp_set_profile_direct
5842 ------------------------------
5843
5844  -- Function: int gnutls_srtp_set_profile_direct (gnutls_session_t
5845           SESSION, const char * PROFILES, const char ** ERR_POS)
5846      SESSION: is a 'gnutls_session_t' structure.
5847
5848      PROFILES: is a string that contains the supported SRTP profiles,
5849      separated by colons.
5850
5851      ERR_POS: In case of an error this will have the position in the
5852      string the error occured, may be NULL.
5853
5854      This function is to be used by both clients and servers, to declare
5855      what SRTP profiles they support, to negotiate with the peer.
5856
5857      *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
5858      'GNUTLS_E_SUCCESS' on success, or an error code.
5859
5860      Since 3.1.4
5861
5862 gnutls_store_commitment
5863 -----------------------
5864
5865  -- Function: int gnutls_store_commitment (const char * DB_NAME,
5866           gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
5867           gnutls_digest_algorithm_t HASH_ALGO, const gnutls_datum_t *
5868           HASH, time_t EXPIRATION, unsigned int FLAGS)
5869      DB_NAME: A file specifying the stored keys (use NULL for the
5870      default)
5871
5872      TDB: A storage structure or NULL to use the default
5873
5874      HOST: The peer's name
5875
5876      SERVICE: non-NULL if this key is specific to a service (e.g.  http)
5877
5878      HASH_ALGO: The hash algorithm type
5879
5880      HASH: The raw hash
5881
5882      EXPIRATION: The expiration time (use 0 to disable expiration)
5883
5884      FLAGS: should be 0.
5885
5886      This function will store the provided hash commitment to the list
5887      of stored public keys.  The key with the given hash will be
5888      considered valid until the provided expiration time.
5889
5890      The 'store' variable if non-null specifies a custom backend for the
5891      storage of entries.  If it is NULL then the default file backend
5892      will be used.
5893
5894      Note that this function is not thread safe with the default
5895      backend.
5896
5897      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5898      otherwise a negative error value.
5899
5900      *Since:* 3.0
5901
5902 gnutls_store_pubkey
5903 -------------------
5904
5905  -- Function: int gnutls_store_pubkey (const char * DB_NAME,
5906           gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
5907           gnutls_certificate_type_t CERT_TYPE, const gnutls_datum_t *
5908           CERT, time_t EXPIRATION, unsigned int FLAGS)
5909      DB_NAME: A file specifying the stored keys (use NULL for the
5910      default)
5911
5912      TDB: A storage structure or NULL to use the default
5913
5914      HOST: The peer's name
5915
5916      SERVICE: non-NULL if this key is specific to a service (e.g.  http)
5917
5918      CERT_TYPE: The type of the certificate
5919
5920      CERT: The data of the certificate
5921
5922      EXPIRATION: The expiration time (use 0 to disable expiration)
5923
5924      FLAGS: should be 0.
5925
5926      This function will store the provided (raw or DER-encoded)
5927      certificate to the list of stored public keys.  The key will be
5928      considered valid until the provided expiration time.
5929
5930      The 'store' variable if non-null specifies a custom backend for the
5931      storage of entries.  If it is NULL then the default file backend
5932      will be used.
5933
5934      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5935      otherwise a negative error value.
5936
5937      *Since:* 3.0.13
5938
5939 gnutls_strerror
5940 ---------------
5941
5942  -- Function: const char * gnutls_strerror (int ERROR)
5943      ERROR: is a GnuTLS error code, a negative error code
5944
5945      This function is similar to strerror.  The difference is that it
5946      accepts an error number returned by a gnutls function; In case of
5947      an unknown error a descriptive string is sent instead of 'NULL' .
5948
5949      Error codes are always a negative error code.
5950
5951      *Returns:* A string explaining the GnuTLS error message.
5952
5953 gnutls_strerror_name
5954 --------------------
5955
5956  -- Function: const char * gnutls_strerror_name (int ERROR)
5957      ERROR: is an error returned by a gnutls function.
5958
5959      Return the GnuTLS error code define as a string.  For example,
5960      gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return
5961      the string "GNUTLS_E_DH_PRIME_UNACCEPTABLE".
5962
5963      *Returns:* A string corresponding to the symbol name of the error
5964      code.
5965
5966      *Since:* 2.6.0
5967
5968 gnutls_supplemental_get_name
5969 ----------------------------
5970
5971  -- Function: const char * gnutls_supplemental_get_name
5972           (gnutls_supplemental_data_format_type_t TYPE)
5973      TYPE: is a supplemental data format type
5974
5975      Convert a 'gnutls_supplemental_data_format_type_t' value to a
5976      string.
5977
5978      *Returns:* a string that contains the name of the specified
5979      supplemental data format type, or 'NULL' for unknown types.
5980
5981 gnutls_tdb_deinit
5982 -----------------
5983
5984  -- Function: void gnutls_tdb_deinit (gnutls_tdb_t TDB)
5985      TDB: The structure to be deinitialized
5986
5987      This function will deinitialize a public key trust storage
5988      structure.
5989
5990 gnutls_tdb_init
5991 ---------------
5992
5993  -- Function: int gnutls_tdb_init (gnutls_tdb_t * TDB)
5994      TDB: The structure to be initialized
5995
5996      This function will initialize a public key trust storage structure.
5997
5998      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5999      otherwise a negative error value.
6000
6001 gnutls_tdb_set_store_commitment_func
6002 ------------------------------------
6003
6004  -- Function: void gnutls_tdb_set_store_commitment_func (gnutls_tdb_t
6005           TDB, gnutls_tdb_store_commitment_func CSTORE)
6006      TDB: The trust storage
6007
6008      CSTORE: The commitment storage function
6009
6010      This function will associate a commitment (hash) storage function
6011      with the trust storage structure.  The function is of the following
6012      form.
6013
6014      int gnutls_tdb_store_commitment_func(const char* db_name, const
6015      char* host, const char* service, time_t expiration,
6016      gnutls_digest_algorithm_t, const gnutls_datum_t* hash);
6017
6018      The 'db_name' should be used to pass any private data to this
6019      function.
6020
6021 gnutls_tdb_set_store_func
6022 -------------------------
6023
6024  -- Function: void gnutls_tdb_set_store_func (gnutls_tdb_t TDB,
6025           gnutls_tdb_store_func STORE)
6026      TDB: The trust storage
6027
6028      STORE: The storage function
6029
6030      This function will associate a storage function with the trust
6031      storage structure.  The function is of the following form.
6032
6033      int gnutls_tdb_store_func(const char* db_name, const char* host,
6034      const char* service, time_t expiration, const gnutls_datum_t*
6035      pubkey);
6036
6037      The 'db_name' should be used to pass any private data to this
6038      function.
6039
6040 gnutls_tdb_set_verify_func
6041 --------------------------
6042
6043  -- Function: void gnutls_tdb_set_verify_func (gnutls_tdb_t TDB,
6044           gnutls_tdb_verify_func VERIFY)
6045      TDB: The trust storage
6046
6047      VERIFY: The verification function
6048
6049      This function will associate a retrieval function with the trust
6050      storage structure.  The function is of the following form.
6051
6052      int gnutls_tdb_verify_func(const char* db_name, const char* host,
6053      const char* service, const gnutls_datum_t* pubkey);
6054
6055      The verify function should return zero on a match,
6056      'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' if there is a mismatch and any
6057      other negative error code otherwise.
6058
6059      The 'db_name' should be used to pass any private data to this
6060      function.
6061
6062 gnutls_transport_get_int
6063 ------------------------
6064
6065  -- Function: int gnutls_transport_get_int (gnutls_session_t SESSION)
6066      SESSION: is a 'gnutls_session_t' structure.
6067
6068      Used to get the first argument of the transport function (like PUSH
6069      and PULL). This must have been set using
6070      'gnutls_transport_set_int()' .
6071
6072      *Returns:* The first argument of the transport function.
6073
6074      *Since:* 3.1.9
6075
6076 gnutls_transport_get_int2
6077 -------------------------
6078
6079  -- Function: void gnutls_transport_get_int2 (gnutls_session_t SESSION,
6080           int * RECV_INT, int * SEND_INT)
6081      SESSION: is a 'gnutls_session_t' structure.
6082
6083      RECV_INT: will hold the value for the pull function
6084
6085      SEND_INT: will hold the value for the push function
6086
6087      Used to get the arguments of the transport functions (like PUSH and
6088      PULL). These should have been set using
6089      'gnutls_transport_set_int2()' .
6090
6091      *Since:* 3.1.9
6092
6093 gnutls_transport_get_ptr
6094 ------------------------
6095
6096  -- Function: gnutls_transport_ptr_t gnutls_transport_get_ptr
6097           (gnutls_session_t SESSION)
6098      SESSION: is a 'gnutls_session_t' structure.
6099
6100      Used to get the first argument of the transport function (like PUSH
6101      and PULL). This must have been set using
6102      'gnutls_transport_set_ptr()' .
6103
6104      *Returns:* The first argument of the transport function.
6105
6106 gnutls_transport_get_ptr2
6107 -------------------------
6108
6109  -- Function: void gnutls_transport_get_ptr2 (gnutls_session_t SESSION,
6110           gnutls_transport_ptr_t * RECV_PTR, gnutls_transport_ptr_t *
6111           SEND_PTR)
6112      SESSION: is a 'gnutls_session_t' structure.
6113
6114      RECV_PTR: will hold the value for the pull function
6115
6116      SEND_PTR: will hold the value for the push function
6117
6118      Used to get the arguments of the transport functions (like PUSH and
6119      PULL). These should have been set using
6120      'gnutls_transport_set_ptr2()' .
6121
6122 gnutls_transport_set_errno
6123 --------------------------
6124
6125  -- Function: void gnutls_transport_set_errno (gnutls_session_t SESSION,
6126           int ERR)
6127      SESSION: is a 'gnutls_session_t' structure.
6128
6129      ERR: error value to store in session-specific errno variable.
6130
6131      Store 'err' in the session-specific errno variable.  Useful values
6132      for 'err' are EINTR, EAGAIN and EMSGSIZE, other values are treated
6133      will be treated as real errors in the push/pull function.
6134
6135      This function is useful in replacement push and pull functions set
6136      by 'gnutls_transport_set_push_function()' and
6137      'gnutls_transport_set_pull_function()' under Windows, where the
6138      replacements may not have access to the same 'errno' variable that
6139      is used by GnuTLS (e.g., the application is linked to msvcr71.dll
6140      and gnutls is linked to msvcrt.dll).
6141
6142 gnutls_transport_set_errno_function
6143 -----------------------------------
6144
6145  -- Function: void gnutls_transport_set_errno_function (gnutls_session_t
6146           SESSION, gnutls_errno_func ERRNO_FUNC)
6147      SESSION: is a 'gnutls_session_t' structure.
6148
6149      ERRNO_FUNC: a callback function similar to 'write()'
6150
6151      This is the function where you set a function to retrieve errno
6152      after a failed push or pull operation.
6153
6154      'errno_func' is of the form, int
6155      (*gnutls_errno_func)(gnutls_transport_ptr_t); and should return the
6156      errno.
6157
6158      *Since:* 2.12.0
6159
6160 gnutls_transport_set_int
6161 ------------------------
6162
6163  -- Function: void gnutls_transport_set_int (gnutls_session_t SESSION,
6164           int I)
6165      SESSION: is a 'gnutls_session_t' structure.
6166
6167      I: is the value.
6168
6169      Used to set the first argument of the transport function (for push
6170      and pull callbacks) for berkeley style sockets.
6171
6172      *Since:* 3.1.9
6173
6174 gnutls_transport_set_int2
6175 -------------------------
6176
6177  -- Function: void gnutls_transport_set_int2 (gnutls_session_t SESSION,
6178           int RECV_INT, int SEND_INT)
6179      SESSION: is a 'gnutls_session_t' structure.
6180
6181      RECV_INT: is the value for the pull function
6182
6183      SEND_INT: is the value for the push function
6184
6185      Used to set the first argument of the transport function (for push
6186      and pull callbacks), when using the berkeley style sockets.  With
6187      this function you can set two different pointers for receiving and
6188      sending.
6189
6190      *Since:* 3.1.9
6191
6192 gnutls_transport_set_ptr
6193 ------------------------
6194
6195  -- Function: void gnutls_transport_set_ptr (gnutls_session_t SESSION,
6196           gnutls_transport_ptr_t PTR)
6197      SESSION: is a 'gnutls_session_t' structure.
6198
6199      PTR: is the value.
6200
6201      Used to set the first argument of the transport function (for push
6202      and pull callbacks).  In berkeley style sockets this function will
6203      set the connection descriptor.
6204
6205 gnutls_transport_set_ptr2
6206 -------------------------
6207
6208  -- Function: void gnutls_transport_set_ptr2 (gnutls_session_t SESSION,
6209           gnutls_transport_ptr_t RECV_PTR, gnutls_transport_ptr_t
6210           SEND_PTR)
6211      SESSION: is a 'gnutls_session_t' structure.
6212
6213      RECV_PTR: is the value for the pull function
6214
6215      SEND_PTR: is the value for the push function
6216
6217      Used to set the first argument of the transport function (for push
6218      and pull callbacks).  In berkeley style sockets this function will
6219      set the connection descriptor.  With this function you can use two
6220      different pointers for receiving and sending.
6221
6222 gnutls_transport_set_pull_function
6223 ----------------------------------
6224
6225  -- Function: void gnutls_transport_set_pull_function (gnutls_session_t
6226           SESSION, gnutls_pull_func PULL_FUNC)
6227      SESSION: is a 'gnutls_session_t' structure.
6228
6229      PULL_FUNC: a callback function similar to 'read()'
6230
6231      This is the function where you set a function for gnutls to receive
6232      data.  Normally, if you use berkeley style sockets, do not need to
6233      use this function since the default recv(2) will probably be ok.
6234      The callback should return 0 on connection termination, a positive
6235      number indicating the number of bytes received, and -1 on error.
6236
6237      'gnutls_pull_func' is of the form, ssize_t
6238      (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
6239
6240 gnutls_transport_set_pull_timeout_function
6241 ------------------------------------------
6242
6243  -- Function: void gnutls_transport_set_pull_timeout_function
6244           (gnutls_session_t SESSION, gnutls_pull_timeout_func FUNC)
6245      SESSION: is a 'gnutls_session_t' structure.
6246
6247      FUNC: a callback function
6248
6249      This is the function where you set a function for gnutls to know
6250      whether data are ready to be received.  It should wait for data a
6251      given time frame in milliseconds.  The callback should return 0 on
6252      timeout, a positive number if data can be received, and -1 on
6253      error.  You'll need to override this function if 'select()' is not
6254      suitable for the provided transport calls.
6255
6256      As with 'select()' , if the timeout value is zero the callback
6257      should return zero if no data are immediately available.
6258
6259      'gnutls_pull_timeout_func' is of the form, int
6260      (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int
6261      ms);
6262
6263      *Since:* 3.0
6264
6265 gnutls_transport_set_push_function
6266 ----------------------------------
6267
6268  -- Function: void gnutls_transport_set_push_function (gnutls_session_t
6269           SESSION, gnutls_push_func PUSH_FUNC)
6270      SESSION: is a 'gnutls_session_t' structure.
6271
6272      PUSH_FUNC: a callback function similar to 'write()'
6273
6274      This is the function where you set a push function for gnutls to
6275      use in order to send data.  If you are going to use berkeley style
6276      sockets, you do not need to use this function since the default
6277      send(2) will probably be ok.  Otherwise you should specify this
6278      function for gnutls to be able to send data.  The callback should
6279      return a positive number indicating the bytes sent, and -1 on
6280      error.
6281
6282      'push_func' is of the form, ssize_t
6283      (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
6284
6285 gnutls_transport_set_vec_push_function
6286 --------------------------------------
6287
6288  -- Function: void gnutls_transport_set_vec_push_function
6289           (gnutls_session_t SESSION, gnutls_vec_push_func VEC_FUNC)
6290      SESSION: is a 'gnutls_session_t' structure.
6291
6292      VEC_FUNC: a callback function similar to 'writev()'
6293
6294      Using this function you can override the default writev(2) function
6295      for gnutls to send data.  Setting this callback instead of
6296      'gnutls_transport_set_push_function()' is recommended since it
6297      introduces less overhead in the TLS handshake process.
6298
6299      'vec_func' is of the form, ssize_t (*gnutls_vec_push_func)
6300      (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
6301
6302      *Since:* 2.12.0
6303
6304 gnutls_url_is_supported
6305 -----------------------
6306
6307  -- Function: int gnutls_url_is_supported (const char * URL)
6308      URL: A PKCS 11 url
6309
6310      Check whether url is supported.  Depending on the system libraries
6311      GnuTLS may support pkcs11 or tpmkey URLs.
6312
6313      *Returns:* return non-zero if the given URL is supported, and zero
6314      if it is not known.
6315
6316      *Since:* 3.1.0
6317
6318 gnutls_verify_stored_pubkey
6319 ---------------------------
6320
6321  -- Function: int gnutls_verify_stored_pubkey (const char * DB_NAME,
6322           gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
6323           gnutls_certificate_type_t CERT_TYPE, const gnutls_datum_t *
6324           CERT, unsigned int FLAGS)
6325      DB_NAME: A file specifying the stored keys (use NULL for the
6326      default)
6327
6328      TDB: A storage structure or NULL to use the default
6329
6330      HOST: The peer's name
6331
6332      SERVICE: non-NULL if this key is specific to a service (e.g.  http)
6333
6334      CERT_TYPE: The type of the certificate
6335
6336      CERT: The raw (der) data of the certificate
6337
6338      FLAGS: should be 0.
6339
6340      This function will try to verify the provided (raw or DER-encoded)
6341      certificate using a list of stored public keys.  The 'service'
6342      field if non-NULL should be a port number.
6343
6344      The 'retrieve' variable if non-null specifies a custom backend for
6345      the retrieval of entries.  If it is NULL then the default file
6346      backend will be used.  In POSIX-like systems the file backend uses
6347      the $HOME/.gnutls/known_hosts file.
6348
6349      Note that if the custom storage backend is provided the retrieval
6350      function should return 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' if the
6351      host/service pair is found but key doesn't match,
6352      'GNUTLS_E_NO_CERTIFICATE_FOUND' if no such host/service with the
6353      given key is found, and 0 if it was found.  The storage function
6354      should return 0 on success.
6355
6356      *Returns:* If no associated public key is found then
6357      'GNUTLS_E_NO_CERTIFICATE_FOUND' will be returned.  If a key is
6358      found but does not match 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' is
6359      returned.  On success, 'GNUTLS_E_SUCCESS' (0) is returned, or a
6360      negative error value on other errors.
6361
6362      *Since:* 3.0.13
6363
6364 \1f
6365 File: gnutls.info,  Node: Datagram TLS API,  Next: X509 certificate API,  Prev: Core TLS API,  Up: API reference
6366
6367 E.2 Datagram TLS API
6368 ====================
6369
6370 The prototypes for the following functions lie in 'gnutls/dtls.h'.
6371
6372 gnutls_dtls_cookie_send
6373 -----------------------
6374
6375  -- Function: int gnutls_dtls_cookie_send (gnutls_datum_t * KEY, void *
6376           CLIENT_DATA, size_t CLIENT_DATA_SIZE, gnutls_dtls_prestate_st
6377           * PRESTATE, gnutls_transport_ptr_t PTR, gnutls_push_func
6378           PUSH_FUNC)
6379      KEY: is a random key to be used at cookie generation
6380
6381      CLIENT_DATA: contains data identifying the client (i.e.  address)
6382
6383      CLIENT_DATA_SIZE: The size of client's data
6384
6385      PRESTATE: The previous cookie returned by
6386      'gnutls_dtls_cookie_verify()'
6387
6388      PTR: A transport pointer to be used by 'push_func'
6389
6390      PUSH_FUNC: A function that will be used to reply
6391
6392      This function can be used to prevent denial of service attacks to a
6393      DTLS server by requiring the client to reply using a cookie sent by
6394      this function.  That way it can be ensured that a client we
6395      allocated resources for (i.e.  'gnutls_session_t' ) is the one that
6396      the original incoming packet was originated from.
6397
6398      This function must be called at the first incoming packet, prior to
6399      allocating any resources and must be succeeded by
6400      'gnutls_dtls_cookie_verify()' .
6401
6402      *Returns:* the number of bytes sent, or a negative error code.
6403
6404      *Since:* 3.0
6405
6406 gnutls_dtls_cookie_verify
6407 -------------------------
6408
6409  -- Function: int gnutls_dtls_cookie_verify (gnutls_datum_t * KEY, void
6410           * CLIENT_DATA, size_t CLIENT_DATA_SIZE, void * _MSG, size_t
6411           MSG_SIZE, gnutls_dtls_prestate_st * PRESTATE)
6412      KEY: is a random key to be used at cookie generation
6413
6414      CLIENT_DATA: contains data identifying the client (i.e.  address)
6415
6416      CLIENT_DATA_SIZE: The size of client's data
6417
6418      _MSG: An incoming message that initiates a connection.
6419
6420      MSG_SIZE: The size of the message.
6421
6422      PRESTATE: The cookie of this client.
6423
6424      This function will verify the received message for a valid cookie.
6425      If a valid cookie is returned then it should be associated with the
6426      session using 'gnutls_dtls_prestate_set()' ;
6427
6428      This function must be called after 'gnutls_dtls_cookie_send()' .
6429
6430      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
6431      code.
6432
6433      *Since:* 3.0
6434
6435 gnutls_dtls_get_data_mtu
6436 ------------------------
6437
6438  -- Function: unsigned int gnutls_dtls_get_data_mtu (gnutls_session_t
6439           SESSION)
6440      SESSION: is a 'gnutls_session_t' structure.
6441
6442      This function will return the actual maximum transfer unit for
6443      application data.  I.e.  DTLS headers are subtracted from the
6444      actual MTU which is set using 'gnutls_dtls_set_mtu()' .
6445
6446      *Returns:* the maximum allowed transfer unit.
6447
6448      *Since:* 3.0
6449
6450 gnutls_dtls_get_mtu
6451 -------------------
6452
6453  -- Function: unsigned int gnutls_dtls_get_mtu (gnutls_session_t
6454           SESSION)
6455      SESSION: is a 'gnutls_session_t' structure.
6456
6457      This function will return the MTU size as set with
6458      'gnutls_dtls_set_mtu()' .  This is not the actual MTU of data you
6459      can transmit.  Use 'gnutls_dtls_get_data_mtu()' for that reason.
6460
6461      *Returns:* the set maximum transfer unit.
6462
6463      *Since:* 3.0
6464
6465 gnutls_dtls_get_timeout
6466 -----------------------
6467
6468  -- Function: unsigned int gnutls_dtls_get_timeout (gnutls_session_t
6469           SESSION)
6470      SESSION: is a 'gnutls_session_t' structure.
6471
6472      This function will return the milliseconds remaining for a
6473      retransmission of the previously sent handshake message.  This
6474      function is useful when DTLS is used in non-blocking mode, to
6475      estimate when to call 'gnutls_handshake()' if no packets have been
6476      received.
6477
6478      *Returns:* the remaining time in milliseconds.
6479
6480      *Since:* 3.0
6481
6482 gnutls_dtls_prestate_set
6483 ------------------------
6484
6485  -- Function: void gnutls_dtls_prestate_set (gnutls_session_t SESSION,
6486           gnutls_dtls_prestate_st * PRESTATE)
6487      SESSION: a new session
6488
6489      PRESTATE: contains the client's prestate
6490
6491      This function will associate the prestate acquired by the cookie
6492      authentication with the client, with the newly established session.
6493
6494      This functions must be called after a successful
6495      'gnutls_dtls_cookie_verify()' and should be succeeded by the actual
6496      DTLS handshake using 'gnutls_handshake()' .
6497
6498      *Since:* 3.0
6499
6500 gnutls_dtls_set_data_mtu
6501 ------------------------
6502
6503  -- Function: int gnutls_dtls_set_data_mtu (gnutls_session_t SESSION,
6504           unsigned int MTU)
6505      SESSION: is a 'gnutls_session_t' structure.
6506
6507      MTU: The maximum unencrypted transfer unit of the session
6508
6509      This function will set the maximum size of the *unencrypted*
6510      records which will be sent over a DTLS session.  It is equivalent
6511      to calculating the DTLS packet overhead with the current encryption
6512      parameters, and calling 'gnutls_dtls_set_mtu()' with that value.
6513      In particular, this means that you may need to call this function
6514      again after any negotiation or renegotiation, in order to ensure
6515      that the MTU is still sufficient to account for the new protocol
6516      overhead.
6517
6518      In most cases you only need to call 'gnutls_dtls_set_mtu()' with
6519      the maximum MTU of your transport layer.
6520
6521      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
6522      code.
6523
6524      *Since:* 3.1
6525
6526 gnutls_dtls_set_mtu
6527 -------------------
6528
6529  -- Function: void gnutls_dtls_set_mtu (gnutls_session_t SESSION,
6530           unsigned int MTU)
6531      SESSION: is a 'gnutls_session_t' structure.
6532
6533      MTU: The maximum transfer unit of the transport
6534
6535      This function will set the maximum transfer unit of the transport
6536      that DTLS packets are sent over.  Note that this should exclude the
6537      IP (or IPv6) and UDP headers.  So for DTLS over IPv6 on an Ethenet
6538      device with MTU 1500, the DTLS MTU set with this function would be
6539      1500 - 40 (IPV6 header) - 8 (UDP header) = 1452.
6540
6541      *Since:* 3.0
6542
6543 gnutls_dtls_set_timeouts
6544 ------------------------
6545
6546  -- Function: void gnutls_dtls_set_timeouts (gnutls_session_t SESSION,
6547           unsigned int RETRANS_TIMEOUT, unsigned int TOTAL_TIMEOUT)
6548      SESSION: is a 'gnutls_session_t' structure.
6549
6550      RETRANS_TIMEOUT: The time at which a retransmission will occur in
6551      milliseconds
6552
6553      TOTAL_TIMEOUT: The time at which the connection will be aborted, in
6554      milliseconds.
6555
6556      This function will set the timeouts required for the DTLS handshake
6557      protocol.  The retransmission timeout is the time after which a
6558      message from the peer is not received, the previous messages will
6559      be retransmitted.  The total timeout is the time after which the
6560      handshake will be aborted with 'GNUTLS_E_TIMEDOUT' .
6561
6562      The DTLS protocol recommends the values of 1 sec and 60 seconds
6563      respectively.
6564
6565      To disable retransmissions set a 'retrans_timeout' larger than the
6566      'total_timeout' .
6567
6568      *Since:* 3.0
6569
6570 gnutls_record_get_discarded
6571 ---------------------------
6572
6573  -- Function: unsigned int gnutls_record_get_discarded (gnutls_session_t
6574           SESSION)
6575      SESSION: is a 'gnutls_session_t' structure.
6576
6577      Returns the number of discarded packets in a DTLS connection.
6578
6579      *Returns:* The number of discarded packets.
6580
6581      *Since:* 3.0
6582
6583 \1f
6584 File: gnutls.info,  Node: X509 certificate API,  Next: OCSP API,  Prev: Datagram TLS API,  Up: API reference
6585
6586 E.3 X.509 certificate API
6587 =========================
6588
6589 The following functions are to be used for X.509 certificate handling.
6590 Their prototypes lie in 'gnutls/x509.h'.
6591
6592 gnutls_certificate_set_trust_list
6593 ---------------------------------
6594
6595  -- Function: void gnutls_certificate_set_trust_list
6596           (gnutls_certificate_credentials_t RES,
6597           gnutls_x509_trust_list_t TLIST, unsigned FLAGS)
6598      RES: is a 'gnutls_certificate_credentials_t' structure.
6599
6600      TLIST: is a 'gnutls_x509_trust_list_t' structure
6601
6602      FLAGS: must be zero
6603
6604      This function sets a trust list in the
6605      gnutls_certificate_credentials_t structure.
6606
6607      Note that the 'tlist' will become part of the credentials structure
6608      and must not be deallocated.  It will be automatically deallocated
6609      when the 'res' structure is deinitialized.
6610
6611      *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
6612      code.
6613
6614      *Since:* 3.2.2
6615
6616 gnutls_pkcs7_deinit
6617 -------------------
6618
6619  -- Function: void gnutls_pkcs7_deinit (gnutls_pkcs7_t PKCS7)
6620      PKCS7: The structure to be initialized
6621
6622      This function will deinitialize a PKCS7 structure.
6623
6624 gnutls_pkcs7_delete_crl
6625 -----------------------
6626
6627  -- Function: int gnutls_pkcs7_delete_crl (gnutls_pkcs7_t PKCS7, int
6628           INDX)
6629      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6630
6631      INDX: the index of the crl to delete
6632
6633      This function will delete a crl from a PKCS7 or RFC2630 crl set.
6634      Index starts from 0.  Returns 0 on success.
6635
6636      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6637      otherwise a negative error value.
6638
6639 gnutls_pkcs7_delete_crt
6640 -----------------------
6641
6642  -- Function: int gnutls_pkcs7_delete_crt (gnutls_pkcs7_t PKCS7, int
6643           INDX)
6644      PKCS7: should contain a gnutls_pkcs7_t structure
6645
6646      INDX: the index of the certificate to delete
6647
6648      This function will delete a certificate from a PKCS7 or RFC2630
6649      certificate set.  Index starts from 0.  Returns 0 on success.
6650
6651      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6652      otherwise a negative error value.
6653
6654 gnutls_pkcs7_export
6655 -------------------
6656
6657  -- Function: int gnutls_pkcs7_export (gnutls_pkcs7_t PKCS7,
6658           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
6659           OUTPUT_DATA_SIZE)
6660      PKCS7: Holds the pkcs7 structure
6661
6662      FORMAT: the format of output params.  One of PEM or DER.
6663
6664      OUTPUT_DATA: will contain a structure PEM or DER encoded
6665
6666      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
6667      replaced by the actual size of parameters)
6668
6669      This function will export the pkcs7 structure to DER or PEM format.
6670
6671      If the buffer provided is not long enough to hold the output, then
6672      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
6673      will be returned.
6674
6675      If the structure is PEM encoded, it will have a header of "BEGIN
6676      PKCS7".
6677
6678      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6679      otherwise a negative error value.
6680
6681 gnutls_pkcs7_export2
6682 --------------------
6683
6684  -- Function: int gnutls_pkcs7_export2 (gnutls_pkcs7_t PKCS7,
6685           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
6686      PKCS7: Holds the pkcs7 structure
6687
6688      FORMAT: the format of output params.  One of PEM or DER.
6689
6690      OUT: will contain a structure PEM or DER encoded
6691
6692      This function will export the pkcs7 structure to DER or PEM format.
6693
6694      The output buffer is allocated using 'gnutls_malloc()' .
6695
6696      If the structure is PEM encoded, it will have a header of "BEGIN
6697      PKCS7".
6698
6699      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6700      otherwise a negative error value.
6701
6702      *Since:* 3.1.3
6703
6704 gnutls_pkcs7_get_crl_count
6705 --------------------------
6706
6707  -- Function: int gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t PKCS7)
6708      PKCS7: should contain a gnutls_pkcs7_t structure
6709
6710      This function will return the number of certifcates in the PKCS7 or
6711      RFC2630 crl set.
6712
6713      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6714      otherwise a negative error value.
6715
6716 gnutls_pkcs7_get_crl_raw
6717 ------------------------
6718
6719  -- Function: int gnutls_pkcs7_get_crl_raw (gnutls_pkcs7_t PKCS7, int
6720           INDX, void * CRL, size_t * CRL_SIZE)
6721      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6722
6723      INDX: contains the index of the crl to extract
6724
6725      CRL: the contents of the crl will be copied there (may be null)
6726
6727      CRL_SIZE: should hold the size of the crl
6728
6729      This function will return a crl of the PKCS7 or RFC2630 crl set.
6730
6731      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6732      otherwise a negative error value.  If the provided buffer is not
6733      long enough, then 'crl_size' is updated and
6734      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned.  After the last crl has
6735      been read 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
6736
6737 gnutls_pkcs7_get_crt_count
6738 --------------------------
6739
6740  -- Function: int gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t PKCS7)
6741      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6742
6743      This function will return the number of certifcates in the PKCS7 or
6744      RFC2630 certificate set.
6745
6746      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6747      otherwise a negative error value.
6748
6749 gnutls_pkcs7_get_crt_raw
6750 ------------------------
6751
6752  -- Function: int gnutls_pkcs7_get_crt_raw (gnutls_pkcs7_t PKCS7, int
6753           INDX, void * CERTIFICATE, size_t * CERTIFICATE_SIZE)
6754      PKCS7: should contain a gnutls_pkcs7_t structure
6755
6756      INDX: contains the index of the certificate to extract
6757
6758      CERTIFICATE: the contents of the certificate will be copied there
6759      (may be null)
6760
6761      CERTIFICATE_SIZE: should hold the size of the certificate
6762
6763      This function will return a certificate of the PKCS7 or RFC2630
6764      certificate set.
6765
6766      After the last certificate has been read
6767      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
6768
6769      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6770      otherwise a negative error value.  If the provided buffer is not
6771      long enough, then 'certificate_size' is updated and
6772      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned.
6773
6774 gnutls_pkcs7_import
6775 -------------------
6776
6777  -- Function: int gnutls_pkcs7_import (gnutls_pkcs7_t PKCS7, const
6778           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
6779      PKCS7: The structure to store the parsed PKCS7.
6780
6781      DATA: The DER or PEM encoded PKCS7.
6782
6783      FORMAT: One of DER or PEM
6784
6785      This function will convert the given DER or PEM encoded PKCS7 to
6786      the native 'gnutls_pkcs7_t' format.  The output will be stored in
6787      'pkcs7' .
6788
6789      If the PKCS7 is PEM encoded it should have a header of "PKCS7".
6790
6791      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6792      otherwise a negative error value.
6793
6794 gnutls_pkcs7_init
6795 -----------------
6796
6797  -- Function: int gnutls_pkcs7_init (gnutls_pkcs7_t * PKCS7)
6798      PKCS7: The structure to be initialized
6799
6800      This function will initialize a PKCS7 structure.  PKCS7 structures
6801      usually contain lists of X.509 Certificates and X.509 Certificate
6802      revocation lists.
6803
6804      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6805      otherwise a negative error value.
6806
6807 gnutls_pkcs7_set_crl
6808 --------------------
6809
6810  -- Function: int gnutls_pkcs7_set_crl (gnutls_pkcs7_t PKCS7,
6811           gnutls_x509_crl_t CRL)
6812      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6813
6814      CRL: the DER encoded crl to be added
6815
6816      This function will add a parsed CRL to the PKCS7 or RFC2630 crl
6817      set.
6818
6819      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6820      otherwise a negative error value.
6821
6822 gnutls_pkcs7_set_crl_raw
6823 ------------------------
6824
6825  -- Function: int gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t PKCS7, const
6826           gnutls_datum_t * CRL)
6827      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6828
6829      CRL: the DER encoded crl to be added
6830
6831      This function will add a crl to the PKCS7 or RFC2630 crl set.
6832
6833      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6834      otherwise a negative error value.
6835
6836 gnutls_pkcs7_set_crt
6837 --------------------
6838
6839  -- Function: int gnutls_pkcs7_set_crt (gnutls_pkcs7_t PKCS7,
6840           gnutls_x509_crt_t CRT)
6841      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6842
6843      CRT: the certificate to be copied.
6844
6845      This function will add a parsed certificate to the PKCS7 or RFC2630
6846      certificate set.  This is a wrapper function over
6847      'gnutls_pkcs7_set_crt_raw()' .
6848
6849      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6850      otherwise a negative error value.
6851
6852 gnutls_pkcs7_set_crt_raw
6853 ------------------------
6854
6855  -- Function: int gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t PKCS7, const
6856           gnutls_datum_t * CRT)
6857      PKCS7: should contain a 'gnutls_pkcs7_t' structure
6858
6859      CRT: the DER encoded certificate to be added
6860
6861      This function will add a certificate to the PKCS7 or RFC2630
6862      certificate set.
6863
6864      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6865      otherwise a negative error value.
6866
6867 gnutls_subject_alt_names_deinit
6868 -------------------------------
6869
6870  -- Function: void gnutls_subject_alt_names_deinit
6871           (gnutls_subject_alt_names_t SANS)
6872      SANS: The alternative names structure
6873
6874      This function will deinitialize an alternative names structure.
6875
6876      *Since:* 3.3.0
6877
6878 gnutls_subject_alt_names_get
6879 ----------------------------
6880
6881  -- Function: int gnutls_subject_alt_names_get
6882           (gnutls_subject_alt_names_t SANS, unsigned int SEQ, unsigned
6883           int * SAN_TYPE, gnutls_datum_t * SAN, gnutls_datum_t *
6884           OTHERNAME_OID)
6885      SANS: The alternative names structure
6886
6887      SEQ: The index of the name to get
6888
6889      SAN_TYPE: Will hold the type of the name (of
6890      'gnutls_subject_alt_names_t' )
6891
6892      SAN: The alternative name data (should be treated as constant)
6893
6894      OTHERNAME_OID: The object identifier if 'san_type' is
6895      'GNUTLS_SAN_OTHERNAME' (should be treated as constant)
6896
6897      This function will return a specific alternative name as stored in
6898      the 'sans' structure.  The returned values should be treated as
6899      constant and valid for the lifetime of 'sans' .
6900
6901      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6902      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
6903      bounds, otherwise a negative error value.
6904
6905      *Since:* 3.3.0
6906
6907 gnutls_subject_alt_names_init
6908 -----------------------------
6909
6910  -- Function: int gnutls_subject_alt_names_init
6911           (gnutls_subject_alt_names_t * SANS)
6912      SANS: The alternative names structure
6913
6914      This function will initialize an alternative names structure.
6915
6916      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6917      otherwise a negative error value.
6918
6919      *Since:* 3.3.0
6920
6921 gnutls_subject_alt_names_set
6922 ----------------------------
6923
6924  -- Function: int gnutls_subject_alt_names_set
6925           (gnutls_subject_alt_names_t SANS, unsigned int SAN_TYPE, const
6926           gnutls_datum_t * SAN, const char * OTHERNAME_OID)
6927      SANS: The alternative names structure
6928
6929      SAN_TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
6930
6931      SAN: The alternative name data
6932
6933      OTHERNAME_OID: The object identifier if 'san_type' is
6934      'GNUTLS_SAN_OTHERNAME'
6935
6936      This function will store the specified alternative name in the
6937      'sans' structure.
6938
6939      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
6940      error value.
6941
6942      *Since:* 3.3.0
6943
6944 gnutls_x509_aia_deinit
6945 ----------------------
6946
6947  -- Function: void gnutls_x509_aia_deinit (gnutls_x509_aia_t AIA)
6948      AIA: The authority info access structure
6949
6950      This function will deinitialize a CRL distribution points
6951      structure.
6952
6953      *Since:* 3.3.0
6954
6955 gnutls_x509_aia_get
6956 -------------------
6957
6958  -- Function: int gnutls_x509_aia_get (gnutls_x509_aia_t AIA, unsigned
6959           int SEQ, gnutls_datum_t * OID, unsigned * SAN_TYPE,
6960           gnutls_datum_t * SAN)
6961      AIA: The authority info access structure
6962
6963      SEQ: specifies the sequence number of the access descriptor (0 for
6964      the first one, 1 for the second etc.)
6965
6966      OID: the type of available data; to be treated as constant.
6967
6968      SAN_TYPE: Will hold the type of the name of
6969      'gnutls_subject_alt_names_t' (may be null).
6970
6971      SAN: the access location name; to be treated as constant (may be
6972      null).
6973
6974      This function reads from the Authority Information Access
6975      structure.
6976
6977      The 'seq' input parameter is used to indicate which member of the
6978      sequence the caller is interested in.  The first member is 0, the
6979      second member 1 and so on.  When the 'seq' value is out of bounds,
6980      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
6981
6982      Typically 'oid' is 'GNUTLS_OID_AD_CAISSUERS' or
6983      'GNUTLS_OID_AD_OCSP' .
6984
6985      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6986      otherwise a negative error value.
6987
6988      *Since:* 3.3.0
6989
6990 gnutls_x509_aia_init
6991 --------------------
6992
6993  -- Function: int gnutls_x509_aia_init (gnutls_x509_aia_t * AIA)
6994      AIA: The authority info access structure
6995
6996      This function will initialize a CRL distribution points structure.
6997
6998      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6999      otherwise a negative error value.
7000
7001      *Since:* 3.3.0
7002
7003 gnutls_x509_aia_set
7004 -------------------
7005
7006  -- Function: int gnutls_x509_aia_set (gnutls_x509_aia_t AIA, const char
7007           * OID, unsigned SAN_TYPE, const gnutls_datum_t * SAN)
7008      AIA: The authority info access structure
7009
7010      OID: the type of data.
7011
7012      SAN_TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
7013
7014      SAN: The alternative name data
7015
7016      This function will store the specified alternative name in the
7017      'aia' structure.
7018
7019      Typically the value for 'oid' should be 'GNUTLS_OID_AD_OCSP' , or
7020      'GNUTLS_OID_AD_CAISSUERS' .
7021
7022      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
7023      error value.
7024
7025      *Since:* 3.3.0
7026
7027 gnutls_x509_aki_deinit
7028 ----------------------
7029
7030  -- Function: void gnutls_x509_aki_deinit (gnutls_x509_aki_t AKI)
7031      AKI: The authority key identifier structure
7032
7033      This function will deinitialize an authority key identifier
7034      structure.
7035
7036      *Since:* 3.3.0
7037
7038 gnutls_x509_aki_get_cert_issuer
7039 -------------------------------
7040
7041  -- Function: int gnutls_x509_aki_get_cert_issuer (gnutls_x509_aki_t
7042           AKI, unsigned int SEQ, unsigned int * SAN_TYPE, gnutls_datum_t
7043           * SAN, gnutls_datum_t * OTHERNAME_OID, gnutls_datum_t *
7044           SERIAL)
7045      AKI: The authority key ID structure
7046
7047      SEQ: The index of the name to get
7048
7049      SAN_TYPE: Will hold the type of the name (of
7050      'gnutls_subject_alt_names_t' )
7051
7052      SAN: The alternative name data
7053
7054      OTHERNAME_OID: The object identifier if 'san_type' is
7055      'GNUTLS_SAN_OTHERNAME'
7056
7057      SERIAL: The authorityCertSerialNumber number
7058
7059      This function will return a specific authorityCertIssuer name as
7060      stored in the 'aki' structure, as well as the
7061      authorityCertSerialNumber.  All the returned values should be
7062      treated as constant, and may be set to 'NULL' when are not
7063      required.
7064
7065      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7066      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
7067      bounds, otherwise a negative error value.
7068
7069      *Since:* 3.3.0
7070
7071 gnutls_x509_aki_get_id
7072 ----------------------
7073
7074  -- Function: int gnutls_x509_aki_get_id (gnutls_x509_aki_t AKI,
7075           gnutls_datum_t * ID)
7076      AKI: The authority key ID structure
7077
7078      ID: Will hold the identifier
7079
7080      This function will return the key identifier as stored in the 'aki'
7081      structure.  The identifier should be treated as constant.
7082
7083      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7084      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
7085      bounds, otherwise a negative error value.
7086
7087      *Since:* 3.3.0
7088
7089 gnutls_x509_aki_init
7090 --------------------
7091
7092  -- Function: int gnutls_x509_aki_init (gnutls_x509_aki_t * AKI)
7093      AKI: The authority key ID structure
7094
7095      This function will initialize an authority key ID structure.
7096
7097      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7098      otherwise a negative error value.
7099
7100      *Since:* 3.3.0
7101
7102 gnutls_x509_aki_set_cert_issuer
7103 -------------------------------
7104
7105  -- Function: int gnutls_x509_aki_set_cert_issuer (gnutls_x509_aki_t
7106           AKI, unsigned int SAN_TYPE, const gnutls_datum_t * SAN, const
7107           char * OTHERNAME_OID, const gnutls_datum_t * SERIAL)
7108      AKI: The authority key ID structure
7109
7110      SAN_TYPE: the type of the name (of 'gnutls_subject_alt_names_t' ),
7111      may be null
7112
7113      SAN: The alternative name data
7114
7115      OTHERNAME_OID: The object identifier if 'san_type' is
7116      'GNUTLS_SAN_OTHERNAME'
7117
7118      SERIAL: The authorityCertSerialNumber number (may be null)
7119
7120      This function will set the authorityCertIssuer name and the
7121      authorityCertSerialNumber to be stored in the 'aki' structure.
7122      When storing multiple names, the serial should be set on the first
7123      call, and subsequent calls should use a 'NULL' serial.
7124
7125      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7126      otherwise a negative error value.
7127
7128      *Since:* 3.3.0
7129
7130 gnutls_x509_aki_set_id
7131 ----------------------
7132
7133  -- Function: int gnutls_x509_aki_set_id (gnutls_x509_aki_t AKI, const
7134           gnutls_datum_t * ID)
7135      AKI: The authority key ID structure
7136
7137      ID: the key identifier
7138
7139      This function will set the keyIdentifier to be stored in the 'aki'
7140      structure.
7141
7142      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7143      otherwise a negative error value.
7144
7145      *Since:* 3.3.0
7146
7147 gnutls_x509_crl_check_issuer
7148 ----------------------------
7149
7150  -- Function: int gnutls_x509_crl_check_issuer (gnutls_x509_crl_t CRL,
7151           gnutls_x509_crt_t ISSUER)
7152      CRL: is the CRL to be checked
7153
7154      ISSUER: is the certificate of a possible issuer
7155
7156      This function will check if the given CRL was issued by the given
7157      issuer certificate.
7158
7159      *Returns:* true (1) if the given CRL was issued by the given
7160      issuer, and false (0) if not.
7161
7162 gnutls_x509_crl_deinit
7163 ----------------------
7164
7165  -- Function: void gnutls_x509_crl_deinit (gnutls_x509_crl_t CRL)
7166      CRL: The structure to be deinitialized
7167
7168      This function will deinitialize a CRL structure.
7169
7170 gnutls_x509_crl_dist_points_deinit
7171 ----------------------------------
7172
7173  -- Function: void gnutls_x509_crl_dist_points_deinit
7174           (gnutls_x509_crl_dist_points_t CDP)
7175      CDP: The CRL distribution points structure
7176
7177      This function will deinitialize a CRL distribution points
7178      structure.
7179
7180      *Since:* 3.3.0
7181
7182 gnutls_x509_crl_dist_points_get
7183 -------------------------------
7184
7185  -- Function: int gnutls_x509_crl_dist_points_get
7186           (gnutls_x509_crl_dist_points_t CDP, unsigned int SEQ, unsigned
7187           int * TYPE, gnutls_datum_t * SAN, unsigned int * REASONS)
7188      CDP: The CRL distribution points structure
7189
7190      SEQ: specifies the sequence number of the distribution point (0 for
7191      the first one, 1 for the second etc.)
7192
7193      TYPE: The name type of the corresponding name
7194      (gnutls_x509_subject_alt_name_t)
7195
7196      SAN: The distribution point names (to be treated as constant)
7197
7198      REASONS: Revocation reasons.  An ORed sequence of flags from
7199      'gnutls_x509_crl_reason_flags_t' .
7200
7201      This function retrieves the individual CRL distribution points
7202      (2.5.29.31), contained in provided structure.
7203
7204      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7205      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
7206      bounds, otherwise a negative error value.
7207
7208 gnutls_x509_crl_dist_points_init
7209 --------------------------------
7210
7211  -- Function: int gnutls_x509_crl_dist_points_init
7212           (gnutls_x509_crl_dist_points_t * CDP)
7213      CDP: The CRL distribution points structure
7214
7215      This function will initialize a CRL distribution points structure.
7216
7217      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7218      otherwise a negative error value.
7219
7220      *Since:* 3.3.0
7221
7222 gnutls_x509_crl_dist_points_set
7223 -------------------------------
7224
7225  -- Function: int gnutls_x509_crl_dist_points_set
7226           (gnutls_x509_crl_dist_points_t CDP,
7227           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
7228           SAN, unsigned int REASONS)
7229      CDP: The CRL distribution points structure
7230
7231      TYPE: The type of the name (of 'gnutls_subject_alt_names_t' )
7232
7233      SAN: The point name data
7234
7235      REASONS: Revocation reasons.  An ORed sequence of flags from
7236      'gnutls_x509_crl_reason_flags_t' .
7237
7238      This function will store the specified CRL distibution point value
7239      the 'cdp' structure.
7240
7241      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
7242      error value.
7243
7244      *Since:* 3.3.0
7245
7246 gnutls_x509_crl_export
7247 ----------------------
7248
7249  -- Function: int gnutls_x509_crl_export (gnutls_x509_crl_t CRL,
7250           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
7251           OUTPUT_DATA_SIZE)
7252      CRL: Holds the revocation list
7253
7254      FORMAT: the format of output params.  One of PEM or DER.
7255
7256      OUTPUT_DATA: will contain a private key PEM or DER encoded
7257
7258      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
7259      replaced by the actual size of parameters)
7260
7261      This function will export the revocation list to DER or PEM format.
7262
7263      If the buffer provided is not long enough to hold the output, then
7264      'GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned.
7265
7266      If the structure is PEM encoded, it will have a header of "BEGIN
7267      X509 CRL".
7268
7269      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7270      otherwise a negative error value.
7271
7272 gnutls_x509_crl_export2
7273 -----------------------
7274
7275  -- Function: int gnutls_x509_crl_export2 (gnutls_x509_crl_t CRL,
7276           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
7277      CRL: Holds the revocation list
7278
7279      FORMAT: the format of output params.  One of PEM or DER.
7280
7281      OUT: will contain a private key PEM or DER encoded
7282
7283      This function will export the revocation list to DER or PEM format.
7284
7285      The output buffer is allocated using 'gnutls_malloc()' .
7286
7287      If the structure is PEM encoded, it will have a header of "BEGIN
7288      X509 CRL".
7289
7290      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7291      otherwise a negative error value.
7292
7293      Since 3.1.3
7294
7295 gnutls_x509_crl_get_authority_key_gn_serial
7296 -------------------------------------------
7297
7298  -- Function: int gnutls_x509_crl_get_authority_key_gn_serial
7299           (gnutls_x509_crl_t CRL, unsigned int SEQ, void * ALT, size_t *
7300           ALT_SIZE, unsigned int * ALT_TYPE, void * SERIAL, size_t *
7301           SERIAL_SIZE, unsigned int * CRITICAL)
7302      CRL: should contain a 'gnutls_x509_crl_t' structure
7303
7304      SEQ: specifies the sequence number of the alt name (0 for the first
7305      one, 1 for the second etc.)
7306
7307      ALT: is the place where the alternative name will be copied to
7308
7309      ALT_SIZE: holds the size of alt.
7310
7311      ALT_TYPE: holds the type of the alternative name (one of
7312      gnutls_x509_subject_alt_name_t).
7313
7314      SERIAL: buffer to store the serial number (may be null)
7315
7316      SERIAL_SIZE: Holds the size of the serial field (may be null)
7317
7318      CRITICAL: will be non-zero if the extension is marked as critical
7319      (may be null)
7320
7321      This function will return the X.509 authority key identifier when
7322      stored as a general name (authorityCertIssuer) and serial number.
7323
7324      Because more than one general names might be stored 'seq' can be
7325      used as a counter to request them all until
7326      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
7327
7328      *Returns:* Returns 0 on success, or an error code.
7329
7330      *Since:* 3.0
7331
7332 gnutls_x509_crl_get_authority_key_id
7333 ------------------------------------
7334
7335  -- Function: int gnutls_x509_crl_get_authority_key_id
7336           (gnutls_x509_crl_t CRL, void * ID, size_t * ID_SIZE, unsigned
7337           int * CRITICAL)
7338      CRL: should contain a 'gnutls_x509_crl_t' structure
7339
7340      ID: The place where the identifier will be copied
7341
7342      ID_SIZE: Holds the size of the result field.
7343
7344      CRITICAL: will be non-zero if the extension is marked as critical
7345      (may be null)
7346
7347      This function will return the CRL authority's key identifier.  This
7348      is obtained by the X.509 Authority Key identifier extension field
7349      (2.5.29.35).  Note that this function only returns the
7350      keyIdentifier field of the extension and
7351      'GNUTLS_E_X509_UNSUPPORTED_EXTENSION' , if the extension contains
7352      the name and serial number of the certificate.  In that case
7353      'gnutls_x509_crl_get_authority_key_gn_serial()' may be used.
7354
7355      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7356      otherwise a negative error code in case of an error.
7357
7358      *Since:* 2.8.0
7359
7360 gnutls_x509_crl_get_crt_count
7361 -----------------------------
7362
7363  -- Function: int gnutls_x509_crl_get_crt_count (gnutls_x509_crl_t CRL)
7364      CRL: should contain a 'gnutls_x509_crl_t' structure
7365
7366      This function will return the number of revoked certificates in the
7367      given CRL.
7368
7369      *Returns:* number of certificates, a negative error code on
7370      failure.
7371
7372 gnutls_x509_crl_get_crt_serial
7373 ------------------------------
7374
7375  -- Function: int gnutls_x509_crl_get_crt_serial (gnutls_x509_crl_t CRL,
7376           int INDX, unsigned char * SERIAL, size_t * SERIAL_SIZE, time_t
7377           * T)
7378      CRL: should contain a 'gnutls_x509_crl_t' structure
7379
7380      INDX: the index of the certificate to extract (starting from 0)
7381
7382      SERIAL: where the serial number will be copied
7383
7384      SERIAL_SIZE: initially holds the size of serial
7385
7386      T: if non null, will hold the time this certificate was revoked
7387
7388      This function will retrieve the serial number of the specified, by
7389      the index, revoked certificate.
7390
7391      Note that this function will have performance issues in large
7392      sequences of revoked certificates.  In that case use
7393      'gnutls_x509_crl_iter_crt_serial()' .
7394
7395      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7396      otherwise a negative error value.
7397
7398 gnutls_x509_crl_get_dn_oid
7399 --------------------------
7400
7401  -- Function: int gnutls_x509_crl_get_dn_oid (gnutls_x509_crl_t CRL, int
7402           INDX, void * OID, size_t * SIZEOF_OID)
7403      CRL: should contain a gnutls_x509_crl_t structure
7404
7405      INDX: Specifies which DN OID to send.  Use (0) to get the first
7406      one.
7407
7408      OID: a pointer to a structure to hold the name (may be null)
7409
7410      SIZEOF_OID: initially holds the size of 'oid'
7411
7412      This function will extract the requested OID of the name of the CRL
7413      issuer, specified by the given index.
7414
7415      If oid is null then only the size will be filled.
7416
7417      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
7418      not long enough, and in that case the sizeof_oid will be updated
7419      with the required size.  On success 0 is returned.
7420
7421 gnutls_x509_crl_get_extension_data
7422 ----------------------------------
7423
7424  -- Function: int gnutls_x509_crl_get_extension_data (gnutls_x509_crl_t
7425           CRL, int INDX, void * DATA, size_t * SIZEOF_DATA)
7426      CRL: should contain a 'gnutls_x509_crl_t' structure
7427
7428      INDX: Specifies which extension OID to send.  Use (0) to get the
7429      first one.
7430
7431      DATA: a pointer to a structure to hold the data (may be null)
7432
7433      SIZEOF_DATA: initially holds the size of 'oid'
7434
7435      This function will return the requested extension data in the CRL.
7436      The extension data will be stored as a string in the provided
7437      buffer.
7438
7439      Use 'gnutls_x509_crl_get_extension_info()' to extract the OID and
7440      critical flag.  Use 'gnutls_x509_crl_get_extension_info()' instead,
7441      if you want to get data indexed by the extension OID rather than
7442      sequence.
7443
7444      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7445      otherwise a negative error code in case of an error.  If your have
7446      reached the last extension available
7447      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7448
7449      *Since:* 2.8.0
7450
7451 gnutls_x509_crl_get_extension_data2
7452 -----------------------------------
7453
7454  -- Function: int gnutls_x509_crl_get_extension_data2 (gnutls_x509_crl_t
7455           CRL, unsigned INDX, gnutls_datum_t * DATA)
7456      CRL: should contain a 'gnutls_x509_crl_t' structure
7457
7458      INDX: Specifies which extension OID to read.  Use (0) to get the
7459      first one.
7460
7461      DATA: will contain the extension DER-encoded data
7462
7463      This function will return the requested by the index extension data
7464      in the certificate revocation list.  The extension data will be
7465      allocated using 'gnutls_malloc()' .
7466
7467      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID.
7468
7469      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7470      otherwise a negative error code is returned.  If you have reached
7471      the last extension available
7472      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7473
7474 gnutls_x509_crl_get_extension_info
7475 ----------------------------------
7476
7477  -- Function: int gnutls_x509_crl_get_extension_info (gnutls_x509_crl_t
7478           CRL, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
7479           CRITICAL)
7480      CRL: should contain a 'gnutls_x509_crl_t' structure
7481
7482      INDX: Specifies which extension OID to send, use (0) to get the
7483      first one.
7484
7485      OID: a pointer to a structure to hold the OID
7486
7487      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
7488      holds actual size of 'oid' .
7489
7490      CRITICAL: output variable with critical flag, may be NULL.
7491
7492      This function will return the requested extension OID in the CRL,
7493      and the critical flag for it.  The extension OID will be stored as
7494      a string in the provided buffer.  Use
7495      'gnutls_x509_crl_get_extension_data()' to extract the data.
7496
7497      If the buffer provided is not long enough to hold the output, then
7498      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
7499      be returned.
7500
7501      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7502      otherwise a negative error code in case of an error.  If your have
7503      reached the last extension available
7504      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7505
7506      *Since:* 2.8.0
7507
7508 gnutls_x509_crl_get_extension_oid
7509 ---------------------------------
7510
7511  -- Function: int gnutls_x509_crl_get_extension_oid (gnutls_x509_crl_t
7512           CRL, int INDX, void * OID, size_t * SIZEOF_OID)
7513      CRL: should contain a 'gnutls_x509_crl_t' structure
7514
7515      INDX: Specifies which extension OID to send, use (0) to get the
7516      first one.
7517
7518      OID: a pointer to a structure to hold the OID (may be null)
7519
7520      SIZEOF_OID: initially holds the size of 'oid'
7521
7522      This function will return the requested extension OID in the CRL.
7523      The extension OID will be stored as a string in the provided
7524      buffer.
7525
7526      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7527      otherwise a negative error code in case of an error.  If your have
7528      reached the last extension available
7529      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
7530
7531      *Since:* 2.8.0
7532
7533 gnutls_x509_crl_get_issuer_dn
7534 -----------------------------
7535
7536  -- Function: int gnutls_x509_crl_get_issuer_dn (const gnutls_x509_crl_t
7537           CRL, char * BUF, size_t * SIZEOF_BUF)
7538      CRL: should contain a gnutls_x509_crl_t structure
7539
7540      BUF: a pointer to a structure to hold the peer's name (may be null)
7541
7542      SIZEOF_BUF: initially holds the size of 'buf'
7543
7544      This function will copy the name of the CRL issuer in the provided
7545      buffer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
7546      described in RFC4514.  The output string will be ASCII or UTF-8
7547      encoded, depending on the certificate data.
7548
7549      If buf is 'NULL' then only the size will be filled.
7550
7551      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
7552      not long enough, and in that case the sizeof_buf will be updated
7553      with the required size, and 0 on success.
7554
7555 gnutls_x509_crl_get_issuer_dn2
7556 ------------------------------
7557
7558  -- Function: int gnutls_x509_crl_get_issuer_dn2 (gnutls_x509_crl_t CRL,
7559           gnutls_datum_t * DN)
7560      CRL: should contain a 'gnutls_x509_crl_t' structure
7561
7562      DN: a pointer to a structure to hold the name
7563
7564      This function will allocate buffer and copy the name of the CRL
7565      issuer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
7566      described in RFC4514.  The output string will be ASCII or UTF-8
7567      encoded, depending on the certificate data.
7568
7569      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7570      otherwise a negative error value.
7571
7572      *Since:* 3.1.10
7573
7574 gnutls_x509_crl_get_issuer_dn_by_oid
7575 ------------------------------------
7576
7577  -- Function: int gnutls_x509_crl_get_issuer_dn_by_oid
7578           (gnutls_x509_crl_t CRL, const char * OID, int INDX, unsigned
7579           int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF)
7580      CRL: should contain a gnutls_x509_crl_t structure
7581
7582      OID: holds an Object Identified in null terminated string
7583
7584      INDX: In case multiple same OIDs exist in the RDN, this specifies
7585      which to send.  Use (0) to get the first one.
7586
7587      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
7588
7589      BUF: a pointer to a structure to hold the peer's name (may be null)
7590
7591      SIZEOF_BUF: initially holds the size of 'buf'
7592
7593      This function will extract the part of the name of the CRL issuer
7594      specified by the given OID. The output will be encoded as described
7595      in RFC4514.  The output string will be ASCII or UTF-8 encoded,
7596      depending on the certificate data.
7597
7598      Some helper macros with popular OIDs can be found in gnutls/x509.h
7599      If raw flag is (0), this function will only return known OIDs as
7600      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
7601      hex format with a '#' prefix.  You can check about known OIDs using
7602      'gnutls_x509_dn_oid_known()' .
7603
7604      If buf is null then only the size will be filled.
7605
7606      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
7607      not long enough, and in that case the sizeof_buf will be updated
7608      with the required size, and 0 on success.
7609
7610 gnutls_x509_crl_get_next_update
7611 -------------------------------
7612
7613  -- Function: time_t gnutls_x509_crl_get_next_update (gnutls_x509_crl_t
7614           CRL)
7615      CRL: should contain a 'gnutls_x509_crl_t' structure
7616
7617      This function will return the time the next CRL will be issued.
7618      This field is optional in a CRL so it might be normal to get an
7619      error instead.
7620
7621      *Returns:* when the next CRL will be issued, or (time_t)-1 on
7622      error.
7623
7624 gnutls_x509_crl_get_number
7625 --------------------------
7626
7627  -- Function: int gnutls_x509_crl_get_number (gnutls_x509_crl_t CRL,
7628           void * RET, size_t * RET_SIZE, unsigned int * CRITICAL)
7629      CRL: should contain a 'gnutls_x509_crl_t' structure
7630
7631      RET: The place where the number will be copied
7632
7633      RET_SIZE: Holds the size of the result field.
7634
7635      CRITICAL: will be non-zero if the extension is marked as critical
7636      (may be null)
7637
7638      This function will return the CRL number extension.  This is
7639      obtained by the CRL Number extension field (2.5.29.20).
7640
7641      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7642      otherwise a negative error code in case of an error.
7643
7644      *Since:* 2.8.0
7645
7646 gnutls_x509_crl_get_raw_issuer_dn
7647 ---------------------------------
7648
7649  -- Function: int gnutls_x509_crl_get_raw_issuer_dn (gnutls_x509_crl_t
7650           CRL, gnutls_datum_t * DN)
7651      CRL: should contain a gnutls_x509_crl_t structure
7652
7653      DN: will hold the starting point of the DN
7654
7655      This function will return a pointer to the DER encoded DN structure
7656      and the length.
7657
7658      *Returns:* a negative error code on error, and (0) on success.
7659
7660      *Since:* 2.12.0
7661
7662 gnutls_x509_crl_get_signature
7663 -----------------------------
7664
7665  -- Function: int gnutls_x509_crl_get_signature (gnutls_x509_crl_t CRL,
7666           char * SIG, size_t * SIZEOF_SIG)
7667      CRL: should contain a gnutls_x509_crl_t structure
7668
7669      SIG: a pointer where the signature part will be copied (may be
7670      null).
7671
7672      SIZEOF_SIG: initially holds the size of 'sig'
7673
7674      This function will extract the signature field of a CRL.
7675
7676      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7677      otherwise a negative error value.
7678
7679 gnutls_x509_crl_get_signature_algorithm
7680 ---------------------------------------
7681
7682  -- Function: int gnutls_x509_crl_get_signature_algorithm
7683           (gnutls_x509_crl_t CRL)
7684      CRL: should contain a 'gnutls_x509_crl_t' structure
7685
7686      This function will return a value of the 'gnutls_sign_algorithm_t'
7687      enumeration that is the signature algorithm.
7688
7689      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7690      otherwise a negative error value.
7691
7692 gnutls_x509_crl_get_this_update
7693 -------------------------------
7694
7695  -- Function: time_t gnutls_x509_crl_get_this_update (gnutls_x509_crl_t
7696           CRL)
7697      CRL: should contain a 'gnutls_x509_crl_t' structure
7698
7699      This function will return the time this CRL was issued.
7700
7701      *Returns:* when the CRL was issued, or (time_t)-1 on error.
7702
7703 gnutls_x509_crl_get_version
7704 ---------------------------
7705
7706  -- Function: int gnutls_x509_crl_get_version (gnutls_x509_crl_t CRL)
7707      CRL: should contain a 'gnutls_x509_crl_t' structure
7708
7709      This function will return the version of the specified CRL.
7710
7711      *Returns:* The version number, or a negative error code on error.
7712
7713 gnutls_x509_crl_import
7714 ----------------------
7715
7716  -- Function: int gnutls_x509_crl_import (gnutls_x509_crl_t CRL, const
7717           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
7718      CRL: The structure to store the parsed CRL.
7719
7720      DATA: The DER or PEM encoded CRL.
7721
7722      FORMAT: One of DER or PEM
7723
7724      This function will convert the given DER or PEM encoded CRL to the
7725      native 'gnutls_x509_crl_t' format.  The output will be stored in
7726      'crl'.
7727
7728      If the CRL is PEM encoded it should have a header of "X509 CRL".
7729
7730      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7731      otherwise a negative error value.
7732
7733 gnutls_x509_crl_init
7734 --------------------
7735
7736  -- Function: int gnutls_x509_crl_init (gnutls_x509_crl_t * CRL)
7737      CRL: The structure to be initialized
7738
7739      This function will initialize a CRL structure.  CRL stands for
7740      Certificate Revocation List.  A revocation list usually contains
7741      lists of certificate serial numbers that have been revoked by an
7742      Authority.  The revocation lists are always signed with the
7743      authority's private key.
7744
7745      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7746      otherwise a negative error value.
7747
7748 gnutls_x509_crl_iter_crt_serial
7749 -------------------------------
7750
7751  -- Function: int gnutls_x509_crl_iter_crt_serial (gnutls_x509_crl_t
7752           CRL, gnutls_x509_crl_iter_t * ITER, unsigned char * SERIAL,
7753           size_t * SERIAL_SIZE, time_t * T)
7754      CRL: should contain a 'gnutls_x509_crl_t' structure
7755
7756      ITER: A pointer to an iterator (initially the iterator should be
7757      'NULL' )
7758
7759      SERIAL: where the serial number will be copied
7760
7761      SERIAL_SIZE: initially holds the size of serial
7762
7763      T: if non null, will hold the time this certificate was revoked
7764
7765      This function performs the same as
7766      'gnutls_x509_crl_get_crt_serial()' , but reads sequentially and
7767      keeps state in the iterator between calls.  That allows it to
7768      provide better performance in sequences with many elements
7769      (50000+).
7770
7771      When past the last element is accessed
7772      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned and the
7773      iterator is reset.
7774
7775      After use, the iterator must be deinitialized using
7776      'gnutls_x509_crl_iter_deinit()' .
7777
7778      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7779      otherwise a negative error value.
7780
7781 gnutls_x509_crl_iter_deinit
7782 ---------------------------
7783
7784  -- Function: void gnutls_x509_crl_iter_deinit (gnutls_x509_crl_iter_t
7785           ITER)
7786      ITER: The iterator structure to be deinitialized
7787
7788      This function will deinitialize an iterator structure.
7789
7790 gnutls_x509_crl_list_import
7791 ---------------------------
7792
7793  -- Function: int gnutls_x509_crl_list_import (gnutls_x509_crl_t * CRLS,
7794           unsigned int * CRL_MAX, const gnutls_datum_t * DATA,
7795           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
7796      CRLS: The structures to store the parsed CRLs.  Must not be
7797      initialized.
7798
7799      CRL_MAX: Initially must hold the maximum number of crls.  It will
7800      be updated with the number of crls available.
7801
7802      DATA: The PEM encoded CRLs
7803
7804      FORMAT: One of DER or PEM.
7805
7806      FLAGS: must be (0) or an OR'd sequence of
7807      gnutls_certificate_import_flags.
7808
7809      This function will convert the given PEM encoded CRL list to the
7810      native gnutls_x509_crl_t format.  The output will be stored in
7811      'crls' .  They will be automatically initialized.
7812
7813      If the Certificate is PEM encoded it should have a header of "X509
7814      CRL".
7815
7816      *Returns:* the number of certificates read or a negative error
7817      value.
7818
7819      *Since:* 3.0
7820
7821 gnutls_x509_crl_list_import2
7822 ----------------------------
7823
7824  -- Function: int gnutls_x509_crl_list_import2 (gnutls_x509_crl_t **
7825           CRLS, unsigned int * SIZE, const gnutls_datum_t * DATA,
7826           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
7827      CRLS: The structures to store the parsed crl list.  Must not be
7828      initialized.
7829
7830      SIZE: It will contain the size of the list.
7831
7832      DATA: The PEM encoded CRL.
7833
7834      FORMAT: One of DER or PEM.
7835
7836      FLAGS: must be (0) or an OR'd sequence of
7837      gnutls_certificate_import_flags.
7838
7839      This function will convert the given PEM encoded CRL list to the
7840      native gnutls_x509_crl_t format.  The output will be stored in
7841      'crls' .  They will be automatically initialized.
7842
7843      If the Certificate is PEM encoded it should have a header of "X509
7844      CRL".
7845
7846      *Returns:* the number of certificates read or a negative error
7847      value.
7848
7849      *Since:* 3.0
7850
7851 gnutls_x509_crl_print
7852 ---------------------
7853
7854  -- Function: int gnutls_x509_crl_print (gnutls_x509_crl_t CRL,
7855           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
7856           OUT)
7857      CRL: The structure to be printed
7858
7859      FORMAT: Indicate the format to use
7860
7861      OUT: Newly allocated datum with null terminated string.
7862
7863      This function will pretty print a X.509 certificate revocation
7864      list, suitable for display to a human.
7865
7866      The output 'out' needs to be deallocated using 'gnutls_free()' .
7867
7868      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7869      otherwise a negative error value.
7870
7871 gnutls_x509_crl_set_authority_key_id
7872 ------------------------------------
7873
7874  -- Function: int gnutls_x509_crl_set_authority_key_id
7875           (gnutls_x509_crl_t CRL, const void * ID, size_t ID_SIZE)
7876      CRL: a CRL of type 'gnutls_x509_crl_t'
7877
7878      ID: The key ID
7879
7880      ID_SIZE: Holds the size of the serial field.
7881
7882      This function will set the CRL's authority key ID extension.  Only
7883      the keyIdentifier field can be set with this function.  This may be
7884      used by an authority that holds multiple private keys, to
7885      distinguish the used key.
7886
7887      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7888      otherwise a negative error value.
7889
7890      *Since:* 2.8.0
7891
7892 gnutls_x509_crl_set_crt
7893 -----------------------
7894
7895  -- Function: int gnutls_x509_crl_set_crt (gnutls_x509_crl_t CRL,
7896           gnutls_x509_crt_t CRT, time_t REVOCATION_TIME)
7897      CRL: should contain a gnutls_x509_crl_t structure
7898
7899      CRT: a certificate of type 'gnutls_x509_crt_t' with the revoked
7900      certificate
7901
7902      REVOCATION_TIME: The time this certificate was revoked
7903
7904      This function will set a revoked certificate's serial number to the
7905      CRL.
7906
7907      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7908      otherwise a negative error value.
7909
7910 gnutls_x509_crl_set_crt_serial
7911 ------------------------------
7912
7913  -- Function: int gnutls_x509_crl_set_crt_serial (gnutls_x509_crl_t CRL,
7914           const void * SERIAL, size_t SERIAL_SIZE, time_t
7915           REVOCATION_TIME)
7916      CRL: should contain a gnutls_x509_crl_t structure
7917
7918      SERIAL: The revoked certificate's serial number
7919
7920      SERIAL_SIZE: Holds the size of the serial field.
7921
7922      REVOCATION_TIME: The time this certificate was revoked
7923
7924      This function will set a revoked certificate's serial number to the
7925      CRL.
7926
7927      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7928      otherwise a negative error value.
7929
7930 gnutls_x509_crl_set_next_update
7931 -------------------------------
7932
7933  -- Function: int gnutls_x509_crl_set_next_update (gnutls_x509_crl_t
7934           CRL, time_t EXP_TIME)
7935      CRL: should contain a gnutls_x509_crl_t structure
7936
7937      EXP_TIME: The actual time
7938
7939      This function will set the time this CRL will be updated.
7940
7941      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7942      otherwise a negative error value.
7943
7944 gnutls_x509_crl_set_number
7945 --------------------------
7946
7947  -- Function: int gnutls_x509_crl_set_number (gnutls_x509_crl_t CRL,
7948           const void * NR, size_t NR_SIZE)
7949      CRL: a CRL of type 'gnutls_x509_crl_t'
7950
7951      NR: The CRL number
7952
7953      NR_SIZE: Holds the size of the nr field.
7954
7955      This function will set the CRL's number extension.  This is to be
7956      used as a unique and monotonic number assigned to the CRL by the
7957      authority.
7958
7959      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7960      otherwise a negative error value.
7961
7962      *Since:* 2.8.0
7963
7964 gnutls_x509_crl_set_this_update
7965 -------------------------------
7966
7967  -- Function: int gnutls_x509_crl_set_this_update (gnutls_x509_crl_t
7968           CRL, time_t ACT_TIME)
7969      CRL: should contain a gnutls_x509_crl_t structure
7970
7971      ACT_TIME: The actual time
7972
7973      This function will set the time this CRL was issued.
7974
7975      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7976      otherwise a negative error value.
7977
7978 gnutls_x509_crl_set_version
7979 ---------------------------
7980
7981  -- Function: int gnutls_x509_crl_set_version (gnutls_x509_crl_t CRL,
7982           unsigned int VERSION)
7983      CRL: should contain a gnutls_x509_crl_t structure
7984
7985      VERSION: holds the version number.  For CRLv1 crls must be 1.
7986
7987      This function will set the version of the CRL. This must be one for
7988      CRL version 1, and so on.  The CRLs generated by gnutls should have
7989      a version number of 2.
7990
7991      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7992      otherwise a negative error value.
7993
7994 gnutls_x509_crl_sign2
7995 ---------------------
7996
7997  -- Function: int gnutls_x509_crl_sign2 (gnutls_x509_crl_t CRL,
7998           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY,
7999           gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
8000      CRL: should contain a gnutls_x509_crl_t structure
8001
8002      ISSUER: is the certificate of the certificate issuer
8003
8004      ISSUER_KEY: holds the issuer's private key
8005
8006      DIG: The message digest to use.  GNUTLS_DIG_SHA1 is the safe choice
8007      unless you know what you're doing.
8008
8009      FLAGS: must be 0
8010
8011      This function will sign the CRL with the issuer's private key, and
8012      will copy the issuer's information into the CRL.
8013
8014      This must be the last step in a certificate CRL since all the
8015      previously set parameters are now signed.
8016
8017      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8018      otherwise a negative error value.
8019
8020 gnutls_x509_crl_verify
8021 ----------------------
8022
8023  -- Function: int gnutls_x509_crl_verify (gnutls_x509_crl_t CRL, const
8024           gnutls_x509_crt_t * TRUSTED_CAS, int TCAS_SIZE, unsigned int
8025           FLAGS, unsigned int * VERIFY)
8026      CRL: is the crl to be verified
8027
8028      TRUSTED_CAS: is a certificate list that is considered to be trusted
8029      one
8030
8031      TCAS_SIZE: holds the number of CA certificates in CA_list
8032
8033      FLAGS: Flags that may be used to change the verification algorithm.
8034      Use OR of the gnutls_certificate_verify_flags enumerations.
8035
8036      VERIFY: will hold the crl verification output.
8037
8038      This function will try to verify the given crl and return its
8039      verification status.  See 'gnutls_x509_crt_list_verify()' for a
8040      detailed description of return values.  Note that since GnuTLS
8041      3.1.4 this function includes the time checks.
8042
8043      Note that value in 'verify' is set only when the return value of
8044      this function is success (i.e, failure to trust a CRL a certificate
8045      does not imply a negative return value).
8046
8047      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8048      otherwise a negative error value.
8049
8050 gnutls_x509_crq_deinit
8051 ----------------------
8052
8053  -- Function: void gnutls_x509_crq_deinit (gnutls_x509_crq_t CRQ)
8054      CRQ: The structure to be initialized
8055
8056      This function will deinitialize a PKCS'10' certificate request
8057      structure.
8058
8059 gnutls_x509_crq_export
8060 ----------------------
8061
8062  -- Function: int gnutls_x509_crq_export (gnutls_x509_crq_t CRQ,
8063           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
8064           OUTPUT_DATA_SIZE)
8065      CRQ: should contain a 'gnutls_x509_crq_t' structure
8066
8067      FORMAT: the format of output params.  One of PEM or DER.
8068
8069      OUTPUT_DATA: will contain a certificate request PEM or DER encoded
8070
8071      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
8072      replaced by the actual size of parameters)
8073
8074      This function will export the certificate request to a PEM or DER
8075      encoded PKCS10 structure.
8076
8077      If the buffer provided is not long enough to hold the output, then
8078      'GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned and *
8079      'output_data_size' will be updated.
8080
8081      If the structure is PEM encoded, it will have a header of "BEGIN
8082      NEW CERTIFICATE REQUEST".
8083
8084      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8085      otherwise a negative error value.
8086
8087 gnutls_x509_crq_export2
8088 -----------------------
8089
8090  -- Function: int gnutls_x509_crq_export2 (gnutls_x509_crq_t CRQ,
8091           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
8092      CRQ: should contain a 'gnutls_x509_crq_t' structure
8093
8094      FORMAT: the format of output params.  One of PEM or DER.
8095
8096      OUT: will contain a certificate request PEM or DER encoded
8097
8098      This function will export the certificate request to a PEM or DER
8099      encoded PKCS10 structure.
8100
8101      The output buffer is allocated using 'gnutls_malloc()' .
8102
8103      If the structure is PEM encoded, it will have a header of "BEGIN
8104      NEW CERTIFICATE REQUEST".
8105
8106      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8107      otherwise a negative error value.
8108
8109      Since 3.1.3
8110
8111 gnutls_x509_crq_get_attribute_by_oid
8112 ------------------------------------
8113
8114  -- Function: int gnutls_x509_crq_get_attribute_by_oid
8115           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
8116           BUF, size_t * BUF_SIZE)
8117      CRQ: should contain a 'gnutls_x509_crq_t' structure
8118
8119      OID: holds an Object Identifier in null-terminated string
8120
8121      INDX: In case multiple same OIDs exist in the attribute list, this
8122      specifies which to get, use (0) to get the first one
8123
8124      BUF: a pointer to a structure to hold the attribute data (may be
8125      'NULL' )
8126
8127      BUF_SIZE: initially holds the size of 'buf'
8128
8129      This function will return the attribute in the certificate request
8130      specified by the given Object ID. The attribute will be DER
8131      encoded.
8132
8133      Attributes in a certificate request is an optional set of data
8134      appended to the request.  Their interpretation depends on the CA
8135      policy.
8136
8137      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8138      otherwise a negative error value.
8139
8140 gnutls_x509_crq_get_attribute_data
8141 ----------------------------------
8142
8143  -- Function: int gnutls_x509_crq_get_attribute_data (gnutls_x509_crq_t
8144           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
8145      CRQ: should contain a 'gnutls_x509_crq_t' structure
8146
8147      INDX: Specifies which attribute number to get.  Use (0) to get the
8148      first one.
8149
8150      DATA: a pointer to a structure to hold the data (may be null)
8151
8152      SIZEOF_DATA: initially holds the size of 'oid'
8153
8154      This function will return the requested attribute data in the
8155      certificate request.  The attribute data will be stored as a string
8156      in the provided buffer.
8157
8158      Use 'gnutls_x509_crq_get_attribute_info()' to extract the OID. Use
8159      'gnutls_x509_crq_get_attribute_by_oid()' instead, if you want to
8160      get data indexed by the attribute OID rather than sequence.
8161
8162      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8163      otherwise a negative error code in case of an error.  If your have
8164      reached the last extension available
8165      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8166
8167      *Since:* 2.8.0
8168
8169 gnutls_x509_crq_get_attribute_info
8170 ----------------------------------
8171
8172  -- Function: int gnutls_x509_crq_get_attribute_info (gnutls_x509_crq_t
8173           CRQ, int INDX, void * OID, size_t * SIZEOF_OID)
8174      CRQ: should contain a 'gnutls_x509_crq_t' structure
8175
8176      INDX: Specifies which attribute number to get.  Use (0) to get the
8177      first one.
8178
8179      OID: a pointer to a structure to hold the OID
8180
8181      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
8182      holds actual size of 'oid' .
8183
8184      This function will return the requested attribute OID in the
8185      certificate, and the critical flag for it.  The attribute OID will
8186      be stored as a string in the provided buffer.  Use
8187      'gnutls_x509_crq_get_attribute_data()' to extract the data.
8188
8189      If the buffer provided is not long enough to hold the output, then
8190      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
8191      be returned.
8192
8193      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8194      otherwise a negative error code in case of an error.  If your have
8195      reached the last extension available
8196      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8197
8198      *Since:* 2.8.0
8199
8200 gnutls_x509_crq_get_basic_constraints
8201 -------------------------------------
8202
8203  -- Function: int gnutls_x509_crq_get_basic_constraints
8204           (gnutls_x509_crq_t CRQ, unsigned int * CRITICAL, unsigned int
8205           * CA, int * PATHLEN)
8206      CRQ: should contain a 'gnutls_x509_crq_t' structure
8207
8208      CRITICAL: will be non-zero if the extension is marked as critical
8209
8210      CA: pointer to output integer indicating CA status, may be NULL,
8211      value is 1 if the certificate CA flag is set, 0 otherwise.
8212
8213      PATHLEN: pointer to output integer indicating path length (may be
8214      NULL), non-negative error codes indicate a present
8215      pathLenConstraint field and the actual value, -1 indicate that the
8216      field is absent.
8217
8218      This function will read the certificate's basic constraints, and
8219      return the certificates CA status.  It reads the basicConstraints
8220      X.509 extension (2.5.29.19).
8221
8222      *Returns:* If the certificate is a CA a positive value will be
8223      returned, or (0) if the certificate does not have CA flag set.  A
8224      negative error code may be returned in case of errors.  If the
8225      certificate does not contain the basicConstraints extension
8226      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8227
8228      *Since:* 2.8.0
8229
8230 gnutls_x509_crq_get_challenge_password
8231 --------------------------------------
8232
8233  -- Function: int gnutls_x509_crq_get_challenge_password
8234           (gnutls_x509_crq_t CRQ, char * PASS, size_t * PASS_SIZE)
8235      CRQ: should contain a 'gnutls_x509_crq_t' structure
8236
8237      PASS: will hold a (0)-terminated password string
8238
8239      PASS_SIZE: Initially holds the size of 'pass' .
8240
8241      This function will return the challenge password in the request.
8242      The challenge password is intended to be used for requesting a
8243      revocation of the certificate.
8244
8245      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8246      otherwise a negative error value.
8247
8248 gnutls_x509_crq_get_dn
8249 ----------------------
8250
8251  -- Function: int gnutls_x509_crq_get_dn (gnutls_x509_crq_t CRQ, char *
8252           BUF, size_t * BUF_SIZE)
8253      CRQ: should contain a 'gnutls_x509_crq_t' structure
8254
8255      BUF: a pointer to a structure to hold the name (may be 'NULL' )
8256
8257      BUF_SIZE: initially holds the size of 'buf'
8258
8259      This function will copy the name of the Certificate request subject
8260      to the provided buffer.  The name will be in the form
8261      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253.  The output
8262      string 'buf' will be ASCII or UTF-8 encoded, depending on the
8263      certificate data.
8264
8265      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
8266      not long enough, and in that case the * 'buf_size' will be updated
8267      with the required size.  On success 0 is returned.
8268
8269 gnutls_x509_crq_get_dn2
8270 -----------------------
8271
8272  -- Function: int gnutls_x509_crq_get_dn2 (gnutls_x509_crq_t CRQ,
8273           gnutls_datum_t * DN)
8274      CRQ: should contain a 'gnutls_x509_crq_t' structure
8275
8276      DN: a pointer to a structure to hold the name
8277
8278      This function will allocate buffer and copy the name of the
8279      Certificate request.  The name will be in the form
8280      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
8281      will be ASCII or UTF-8 encoded, depending on the certificate data.
8282
8283      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8284      otherwise a negative error value.  and a negative error code on
8285      error.
8286
8287      *Since:* 3.1.10
8288
8289 gnutls_x509_crq_get_dn_by_oid
8290 -----------------------------
8291
8292  -- Function: int gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t CRQ,
8293           const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF,
8294           size_t * BUF_SIZE)
8295      CRQ: should contain a gnutls_x509_crq_t structure
8296
8297      OID: holds an Object Identifier in a null terminated string
8298
8299      INDX: In case multiple same OIDs exist in the RDN, this specifies
8300      which to get.  Use (0) to get the first one.
8301
8302      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
8303
8304      BUF: a pointer to a structure to hold the name (may be 'NULL' )
8305
8306      BUF_SIZE: initially holds the size of 'buf'
8307
8308      This function will extract the part of the name of the Certificate
8309      request subject, specified by the given OID. The output will be
8310      encoded as described in RFC2253.  The output string will be ASCII
8311      or UTF-8 encoded, depending on the certificate data.
8312
8313      Some helper macros with popular OIDs can be found in gnutls/x509.h
8314      If raw flag is (0), this function will only return known OIDs as
8315      text.  Other OIDs will be DER encoded, as described in RFC2253 - in
8316      hex format with a '\#' prefix.  You can check about known OIDs
8317      using 'gnutls_x509_dn_oid_known()' .
8318
8319      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
8320      not long enough, and in that case the * 'buf_size' will be updated
8321      with the required size.  On success 0 is returned.
8322
8323 gnutls_x509_crq_get_dn_oid
8324 --------------------------
8325
8326  -- Function: int gnutls_x509_crq_get_dn_oid (gnutls_x509_crq_t CRQ, int
8327           INDX, void * OID, size_t * SIZEOF_OID)
8328      CRQ: should contain a gnutls_x509_crq_t structure
8329
8330      INDX: Specifies which DN OID to get.  Use (0) to get the first one.
8331
8332      OID: a pointer to a structure to hold the name (may be 'NULL' )
8333
8334      SIZEOF_OID: initially holds the size of 'oid'
8335
8336      This function will extract the requested OID of the name of the
8337      certificate request subject, specified by the given index.
8338
8339      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
8340      not long enough, and in that case the * 'sizeof_oid' will be
8341      updated with the required size.  On success 0 is returned.
8342
8343 gnutls_x509_crq_get_extension_by_oid
8344 ------------------------------------
8345
8346  -- Function: int gnutls_x509_crq_get_extension_by_oid
8347           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
8348           BUF, size_t * BUF_SIZE, unsigned int * CRITICAL)
8349      CRQ: should contain a 'gnutls_x509_crq_t' structure
8350
8351      OID: holds an Object Identifier in a null terminated string
8352
8353      INDX: In case multiple same OIDs exist in the extensions, this
8354      specifies which to get.  Use (0) to get the first one.
8355
8356      BUF: a pointer to a structure to hold the name (may be null)
8357
8358      BUF_SIZE: initially holds the size of 'buf'
8359
8360      CRITICAL: will be non-zero if the extension is marked as critical
8361
8362      This function will return the extension specified by the OID in the
8363      certificate.  The extensions will be returned as binary data DER
8364      encoded, in the provided buffer.
8365
8366      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8367      otherwise a negative error code in case of an error.  If the
8368      certificate does not contain the specified extension
8369      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8370
8371      *Since:* 2.8.0
8372
8373 gnutls_x509_crq_get_extension_by_oid2
8374 -------------------------------------
8375
8376  -- Function: int gnutls_x509_crq_get_extension_by_oid2
8377           (gnutls_x509_crq_t CRQ, const char * OID, int INDX,
8378           gnutls_datum_t * OUTPUT, unsigned int * CRITICAL)
8379      CRQ: should contain a 'gnutls_x509_crq_t' structure
8380
8381      OID: holds an Object Identifier in a null terminated string
8382
8383      INDX: In case multiple same OIDs exist in the extensions, this
8384      specifies which to get.  Use (0) to get the first one.
8385
8386      OUTPUT: will hold the allocated extension data
8387
8388      CRITICAL: will be non-zero if the extension is marked as critical
8389
8390      This function will return the extension specified by the OID in the
8391      certificate.  The extensions will be returned as binary data DER
8392      encoded, in the provided buffer.
8393
8394      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8395      otherwise a negative error code in case of an error.  If the
8396      certificate does not contain the specified extension
8397      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8398
8399      *Since:* 3.3.8
8400
8401 gnutls_x509_crq_get_extension_data
8402 ----------------------------------
8403
8404  -- Function: int gnutls_x509_crq_get_extension_data (gnutls_x509_crq_t
8405           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
8406      CRQ: should contain a 'gnutls_x509_crq_t' structure
8407
8408      INDX: Specifies which extension number to get.  Use (0) to get the
8409      first one.
8410
8411      DATA: a pointer to a structure to hold the data (may be null)
8412
8413      SIZEOF_DATA: initially holds the size of 'oid'
8414
8415      This function will return the requested extension data in the
8416      certificate.  The extension data will be stored as a string in the
8417      provided buffer.
8418
8419      Use 'gnutls_x509_crq_get_extension_info()' to extract the OID and
8420      critical flag.  Use 'gnutls_x509_crq_get_extension_by_oid()'
8421      instead, if you want to get data indexed by the extension OID
8422      rather than sequence.
8423
8424      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8425      otherwise a negative error code in case of an error.  If your have
8426      reached the last extension available
8427      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8428
8429      *Since:* 2.8.0
8430
8431 gnutls_x509_crq_get_extension_data2
8432 -----------------------------------
8433
8434  -- Function: int gnutls_x509_crq_get_extension_data2 (gnutls_x509_crq_t
8435           CRQ, unsigned INDX, gnutls_datum_t * DATA)
8436      CRQ: should contain a 'gnutls_x509_crq_t' structure
8437
8438      INDX: Specifies which extension OID to read.  Use (0) to get the
8439      first one.
8440
8441      DATA: will contain the extension DER-encoded data
8442
8443      This function will return the requested extension data in the
8444      certificate request.  The extension data will be allocated using
8445      'gnutls_malloc()' .
8446
8447      Use 'gnutls_x509_crq_get_extension_info()' to extract the OID.
8448
8449      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8450      otherwise a negative error code is returned.  If you have reached
8451      the last extension available
8452      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8453
8454      *Since:* 3.3.0
8455
8456 gnutls_x509_crq_get_extension_info
8457 ----------------------------------
8458
8459  -- Function: int gnutls_x509_crq_get_extension_info (gnutls_x509_crq_t
8460           CRQ, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
8461           CRITICAL)
8462      CRQ: should contain a 'gnutls_x509_crq_t' structure
8463
8464      INDX: Specifies which extension number to get.  Use (0) to get the
8465      first one.
8466
8467      OID: a pointer to a structure to hold the OID
8468
8469      SIZEOF_OID: initially holds the maximum size of 'oid' , on return
8470      holds actual size of 'oid' .
8471
8472      CRITICAL: output variable with critical flag, may be NULL.
8473
8474      This function will return the requested extension OID in the
8475      certificate, and the critical flag for it.  The extension OID will
8476      be stored as a string in the provided buffer.  Use
8477      'gnutls_x509_crq_get_extension_data()' to extract the data.
8478
8479      If the buffer provided is not long enough to hold the output, then
8480      * 'sizeof_oid' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will
8481      be returned.
8482
8483      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8484      otherwise a negative error code in case of an error.  If your have
8485      reached the last extension available
8486      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
8487
8488      *Since:* 2.8.0
8489
8490 gnutls_x509_crq_get_key_id
8491 --------------------------
8492
8493  -- Function: int gnutls_x509_crq_get_key_id (gnutls_x509_crq_t CRQ,
8494           unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
8495           OUTPUT_DATA_SIZE)
8496      CRQ: a certificate of type 'gnutls_x509_crq_t'
8497
8498      FLAGS: should be 0 for now
8499
8500      OUTPUT_DATA: will contain the key ID
8501
8502      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
8503      replaced by the actual size of parameters)
8504
8505      This function will return a unique ID that depends on the public
8506      key parameters.  This ID can be used in checking whether a
8507      certificate corresponds to the given private key.
8508
8509      If the buffer provided is not long enough to hold the output, then
8510      * 'output_data_size' is updated and GNUTLS_E_SHORT_MEMORY_BUFFER
8511      will be returned.  The output will normally be a SHA-1 hash output,
8512      which is 20 bytes.
8513
8514      *Returns:* In case of failure a negative error code will be
8515      returned, and 0 on success.
8516
8517      *Since:* 2.8.0
8518
8519 gnutls_x509_crq_get_key_purpose_oid
8520 -----------------------------------
8521
8522  -- Function: int gnutls_x509_crq_get_key_purpose_oid (gnutls_x509_crq_t
8523           CRQ, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int *
8524           CRITICAL)
8525      CRQ: should contain a 'gnutls_x509_crq_t' structure
8526
8527      INDX: This specifies which OID to return, use (0) to get the first
8528      one
8529
8530      OID: a pointer to a buffer to hold the OID (may be 'NULL' )
8531
8532      SIZEOF_OID: initially holds the size of 'oid'
8533
8534      CRITICAL: output variable with critical flag, may be 'NULL' .
8535
8536      This function will extract the key purpose OIDs of the Certificate
8537      specified by the given index.  These are stored in the Extended Key
8538      Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions for
8539      human readable names.
8540
8541      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
8542      not long enough, and in that case the * 'sizeof_oid' will be
8543      updated with the required size.  On success 0 is returned.
8544
8545      *Since:* 2.8.0
8546
8547 gnutls_x509_crq_get_key_rsa_raw
8548 -------------------------------
8549
8550  -- Function: int gnutls_x509_crq_get_key_rsa_raw (gnutls_x509_crq_t
8551           CRQ, gnutls_datum_t * M, gnutls_datum_t * E)
8552      CRQ: Holds the certificate
8553
8554      M: will hold the modulus
8555
8556      E: will hold the public exponent
8557
8558      This function will export the RSA public key's parameters found in
8559      the given structure.  The new parameters will be allocated using
8560      'gnutls_malloc()' and will be stored in the appropriate datum.
8561
8562      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8563      otherwise a negative error value.
8564
8565      *Since:* 2.8.0
8566
8567 gnutls_x509_crq_get_key_usage
8568 -----------------------------
8569
8570  -- Function: int gnutls_x509_crq_get_key_usage (gnutls_x509_crq_t CRQ,
8571           unsigned int * KEY_USAGE, unsigned int * CRITICAL)
8572      CRQ: should contain a 'gnutls_x509_crq_t' structure
8573
8574      KEY_USAGE: where the key usage bits will be stored
8575
8576      CRITICAL: will be non-zero if the extension is marked as critical
8577
8578      This function will return certificate's key usage, by reading the
8579      keyUsage X.509 extension (2.5.29.15).  The key usage value will
8580      ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE' ,
8581      'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
8582      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
8583      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
8584      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
8585
8586      *Returns:* the certificate key usage, or a negative error code in
8587      case of parsing error.  If the certificate does not contain the
8588      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
8589      returned.
8590
8591      *Since:* 2.8.0
8592
8593 gnutls_x509_crq_get_pk_algorithm
8594 --------------------------------
8595
8596  -- Function: int gnutls_x509_crq_get_pk_algorithm (gnutls_x509_crq_t
8597           CRQ, unsigned int * BITS)
8598      CRQ: should contain a 'gnutls_x509_crq_t' structure
8599
8600      BITS: if bits is non-'NULL' it will hold the size of the
8601      parameters' in bits
8602
8603      This function will return the public key algorithm of a PKCS'10'
8604      certificate request.
8605
8606      If bits is non-'NULL' , it should have enough size to hold the
8607      parameters size in bits.  For RSA the bits returned is the modulus.
8608      For DSA the bits returned are of the public exponent.
8609
8610      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
8611      success, or a negative error code on error.
8612
8613 gnutls_x509_crq_get_private_key_usage_period
8614 --------------------------------------------
8615
8616  -- Function: int gnutls_x509_crq_get_private_key_usage_period
8617           (gnutls_x509_crq_t CRQ, time_t * ACTIVATION, time_t *
8618           EXPIRATION, unsigned int * CRITICAL)
8619      CRQ: should contain a 'gnutls_x509_crq_t' structure
8620
8621      ACTIVATION: The activation time
8622
8623      EXPIRATION: The expiration time
8624
8625      CRITICAL: the extension status
8626
8627      This function will return the expiration and activation times of
8628      the private key of the certificate.
8629
8630      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8631      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
8632      present, otherwise a negative error value.
8633
8634 gnutls_x509_crq_get_subject_alt_name
8635 ------------------------------------
8636
8637  -- Function: int gnutls_x509_crq_get_subject_alt_name
8638           (gnutls_x509_crq_t CRQ, unsigned int SEQ, void * RET, size_t *
8639           RET_SIZE, unsigned int * RET_TYPE, unsigned int * CRITICAL)
8640      CRQ: should contain a 'gnutls_x509_crq_t' structure
8641
8642      SEQ: specifies the sequence number of the alt name, 0 for the first
8643      one, 1 for the second etc.
8644
8645      RET: is the place where the alternative name will be copied to
8646
8647      RET_SIZE: holds the size of ret.
8648
8649      RET_TYPE: holds the 'gnutls_x509_subject_alt_name_t' name type
8650
8651      CRITICAL: will be non-zero if the extension is marked as critical
8652      (may be null)
8653
8654      This function will return the alternative names, contained in the
8655      given certificate.  It is the same as
8656      'gnutls_x509_crq_get_subject_alt_name()' except for the fact that
8657      it will return the type of the alternative name in 'ret_type' even
8658      if the function fails for some reason (i.e.  the buffer provided is
8659      not enough).
8660
8661      *Returns:* the alternative subject name type on success, one of the
8662      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
8663      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ret_size' is not large enough to
8664      hold the value.  In that case 'ret_size' will be updated with the
8665      required size.  If the certificate request does not have an
8666      Alternative name with the specified sequence number then
8667      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
8668
8669      *Since:* 2.8.0
8670
8671 gnutls_x509_crq_get_subject_alt_othername_oid
8672 ---------------------------------------------
8673
8674  -- Function: int gnutls_x509_crq_get_subject_alt_othername_oid
8675           (gnutls_x509_crq_t CRQ, unsigned int SEQ, void * RET, size_t *
8676           RET_SIZE)
8677      CRQ: should contain a 'gnutls_x509_crq_t' structure
8678
8679      SEQ: specifies the sequence number of the alt name (0 for the first
8680      one, 1 for the second etc.)
8681
8682      RET: is the place where the otherName OID will be copied to
8683
8684      RET_SIZE: holds the size of ret.
8685
8686      This function will extract the type OID of an otherName Subject
8687      Alternative Name, contained in the given certificate, and return
8688      the type as an enumerated element.
8689
8690      This function is only useful if
8691      'gnutls_x509_crq_get_subject_alt_name()' returned
8692      'GNUTLS_SAN_OTHERNAME' .
8693
8694      *Returns:* the alternative subject name type on success, one of the
8695      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
8696      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
8697      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
8698      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
8699      'ret_size' is not large enough to hold the value.  In that case
8700      'ret_size' will be updated with the required size.  If the
8701      certificate does not have an Alternative name with the specified
8702      sequence number and with the otherName type then
8703      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
8704
8705      *Since:* 2.8.0
8706
8707 gnutls_x509_crq_get_version
8708 ---------------------------
8709
8710  -- Function: int gnutls_x509_crq_get_version (gnutls_x509_crq_t CRQ)
8711      CRQ: should contain a 'gnutls_x509_crq_t' structure
8712
8713      This function will return the version of the specified Certificate
8714      request.
8715
8716      *Returns:* version of certificate request, or a negative error code
8717      on error.
8718
8719 gnutls_x509_crq_import
8720 ----------------------
8721
8722  -- Function: int gnutls_x509_crq_import (gnutls_x509_crq_t CRQ, const
8723           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
8724      CRQ: The structure to store the parsed certificate request.
8725
8726      DATA: The DER or PEM encoded certificate.
8727
8728      FORMAT: One of DER or PEM
8729
8730      This function will convert the given DER or PEM encoded certificate
8731      request to a 'gnutls_x509_crq_t' structure.  The output will be
8732      stored in 'crq' .
8733
8734      If the Certificate is PEM encoded it should have a header of "NEW
8735      CERTIFICATE REQUEST".
8736
8737      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8738      otherwise a negative error value.
8739
8740 gnutls_x509_crq_init
8741 --------------------
8742
8743  -- Function: int gnutls_x509_crq_init (gnutls_x509_crq_t * CRQ)
8744      CRQ: The structure to be initialized
8745
8746      This function will initialize a PKCS'10' certificate request
8747      structure.
8748
8749      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8750      otherwise a negative error value.
8751
8752 gnutls_x509_crq_print
8753 ---------------------
8754
8755  -- Function: int gnutls_x509_crq_print (gnutls_x509_crq_t CRQ,
8756           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
8757           OUT)
8758      CRQ: The structure to be printed
8759
8760      FORMAT: Indicate the format to use
8761
8762      OUT: Newly allocated datum with null terminated string.
8763
8764      This function will pretty print a certificate request, suitable for
8765      display to a human.
8766
8767      The output 'out' needs to be deallocated using 'gnutls_free()' .
8768
8769      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8770      otherwise a negative error value.
8771
8772      *Since:* 2.8.0
8773
8774 gnutls_x509_crq_set_attribute_by_oid
8775 ------------------------------------
8776
8777  -- Function: int gnutls_x509_crq_set_attribute_by_oid
8778           (gnutls_x509_crq_t CRQ, const char * OID, void * BUF, size_t
8779           BUF_SIZE)
8780      CRQ: should contain a 'gnutls_x509_crq_t' structure
8781
8782      OID: holds an Object Identifier in a null-terminated string
8783
8784      BUF: a pointer to a structure that holds the attribute data
8785
8786      BUF_SIZE: holds the size of 'buf'
8787
8788      This function will set the attribute in the certificate request
8789      specified by the given Object ID. The provided attribute must be be
8790      DER encoded.
8791
8792      Attributes in a certificate request is an optional set of data
8793      appended to the request.  Their interpretation depends on the CA
8794      policy.
8795
8796      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8797      otherwise a negative error value.
8798
8799 gnutls_x509_crq_set_basic_constraints
8800 -------------------------------------
8801
8802  -- Function: int gnutls_x509_crq_set_basic_constraints
8803           (gnutls_x509_crq_t CRQ, unsigned int CA, int
8804           PATHLENCONSTRAINT)
8805      CRQ: a certificate request of type 'gnutls_x509_crq_t'
8806
8807      CA: true(1) or false(0) depending on the Certificate authority
8808      status.
8809
8810      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
8811      of path, and negative error codes indicate that the
8812      pathLenConstraints field should not be present.
8813
8814      This function will set the basicConstraints certificate extension.
8815
8816      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8817      otherwise a negative error value.
8818
8819      *Since:* 2.8.0
8820
8821 gnutls_x509_crq_set_challenge_password
8822 --------------------------------------
8823
8824  -- Function: int gnutls_x509_crq_set_challenge_password
8825           (gnutls_x509_crq_t CRQ, const char * PASS)
8826      CRQ: should contain a 'gnutls_x509_crq_t' structure
8827
8828      PASS: holds a (0)-terminated password
8829
8830      This function will set a challenge password to be used when
8831      revoking the request.
8832
8833      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8834      otherwise a negative error value.
8835
8836 gnutls_x509_crq_set_dn
8837 ----------------------
8838
8839  -- Function: int gnutls_x509_crq_set_dn (gnutls_x509_crq_t CRQ, const
8840           char * DN, const char ** ERR)
8841      CRQ: a certificate of type 'gnutls_x509_crq_t'
8842
8843      DN: a comma separated DN string (RFC4514)
8844
8845      ERR: indicates the error position (if any)
8846
8847      This function will set the DN on the provided certificate.  The
8848      input string should be plain ASCII or UTF-8 encoded.
8849
8850      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8851      otherwise a negative error value.
8852
8853 gnutls_x509_crq_set_dn_by_oid
8854 -----------------------------
8855
8856  -- Function: int gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t CRQ,
8857           const char * OID, unsigned int RAW_FLAG, const void * DATA,
8858           unsigned int SIZEOF_DATA)
8859      CRQ: should contain a 'gnutls_x509_crq_t' structure
8860
8861      OID: holds an Object Identifier in a (0)-terminated string
8862
8863      RAW_FLAG: must be 0, or 1 if the data are DER encoded
8864
8865      DATA: a pointer to the input data
8866
8867      SIZEOF_DATA: holds the size of 'data'
8868
8869      This function will set the part of the name of the Certificate
8870      request subject, specified by the given OID. The input string
8871      should be ASCII or UTF-8 encoded.
8872
8873      Some helper macros with popular OIDs can be found in gnutls/x509.h
8874      With this function you can only set the known OIDs.  You can test
8875      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
8876      are not known (by gnutls) you should properly DER encode your data,
8877      and call this function with raw_flag set.
8878
8879      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8880      otherwise a negative error value.
8881
8882 gnutls_x509_crq_set_key
8883 -----------------------
8884
8885  -- Function: int gnutls_x509_crq_set_key (gnutls_x509_crq_t CRQ,
8886           gnutls_x509_privkey_t KEY)
8887      CRQ: should contain a 'gnutls_x509_crq_t' structure
8888
8889      KEY: holds a private key
8890
8891      This function will set the public parameters from the given private
8892      key to the request.
8893
8894      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8895      otherwise a negative error value.
8896
8897 gnutls_x509_crq_set_key_purpose_oid
8898 -----------------------------------
8899
8900  -- Function: int gnutls_x509_crq_set_key_purpose_oid (gnutls_x509_crq_t
8901           CRQ, const void * OID, unsigned int CRITICAL)
8902      CRQ: a certificate of type 'gnutls_x509_crq_t'
8903
8904      OID: a pointer to a (0)-terminated string that holds the OID
8905
8906      CRITICAL: Whether this extension will be critical or not
8907
8908      This function will set the key purpose OIDs of the Certificate.
8909      These are stored in the Extended Key Usage extension (2.5.29.37)
8910      See the GNUTLS_KP_* definitions for human readable names.
8911
8912      Subsequent calls to this function will append OIDs to the OID list.
8913
8914      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8915      otherwise a negative error value.
8916
8917      *Since:* 2.8.0
8918
8919 gnutls_x509_crq_set_key_rsa_raw
8920 -------------------------------
8921
8922  -- Function: int gnutls_x509_crq_set_key_rsa_raw (gnutls_x509_crq_t
8923           CRQ, const gnutls_datum_t * M, const gnutls_datum_t * E)
8924      CRQ: should contain a 'gnutls_x509_crq_t' structure
8925
8926      M: holds the modulus
8927
8928      E: holds the public exponent
8929
8930      This function will set the public parameters from the given private
8931      key to the request.  Only RSA keys are currently supported.
8932
8933      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8934      otherwise a negative error value.
8935
8936      *Since:* 2.6.0
8937
8938 gnutls_x509_crq_set_key_usage
8939 -----------------------------
8940
8941  -- Function: int gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t CRQ,
8942           unsigned int USAGE)
8943      CRQ: a certificate request of type 'gnutls_x509_crq_t'
8944
8945      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
8946
8947      This function will set the keyUsage certificate extension.
8948
8949      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8950      otherwise a negative error value.
8951
8952      *Since:* 2.8.0
8953
8954 gnutls_x509_crq_set_private_key_usage_period
8955 --------------------------------------------
8956
8957  -- Function: int gnutls_x509_crq_set_private_key_usage_period
8958           (gnutls_x509_crq_t CRQ, time_t ACTIVATION, time_t EXPIRATION)
8959      CRQ: a certificate of type 'gnutls_x509_crq_t'
8960
8961      ACTIVATION: The activation time
8962
8963      EXPIRATION: The expiration time
8964
8965      This function will set the private key usage period extension
8966      (2.5.29.16).
8967
8968      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8969      otherwise a negative error value.
8970
8971 gnutls_x509_crq_set_subject_alt_name
8972 ------------------------------------
8973
8974  -- Function: int gnutls_x509_crq_set_subject_alt_name
8975           (gnutls_x509_crq_t CRQ, gnutls_x509_subject_alt_name_t NT,
8976           const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS)
8977      CRQ: a certificate request of type 'gnutls_x509_crq_t'
8978
8979      NT: is one of the 'gnutls_x509_subject_alt_name_t' enumerations
8980
8981      DATA: The data to be set
8982
8983      DATA_SIZE: The size of data to be set
8984
8985      FLAGS: 'GNUTLS_FSAN_SET' to clear previous data or
8986      'GNUTLS_FSAN_APPEND' to append.
8987
8988      This function will set the subject alternative name certificate
8989      extension.  It can set the following types:
8990
8991      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
8992      otherwise a negative error value.
8993
8994      *Since:* 2.8.0
8995
8996 gnutls_x509_crq_set_version
8997 ---------------------------
8998
8999  -- Function: int gnutls_x509_crq_set_version (gnutls_x509_crq_t CRQ,
9000           unsigned int VERSION)
9001      CRQ: should contain a 'gnutls_x509_crq_t' structure
9002
9003      VERSION: holds the version number, for v1 Requests must be 1
9004
9005      This function will set the version of the certificate request.  For
9006      version 1 requests this must be one.
9007
9008      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9009      otherwise a negative error value.
9010
9011 gnutls_x509_crq_sign2
9012 ---------------------
9013
9014  -- Function: int gnutls_x509_crq_sign2 (gnutls_x509_crq_t CRQ,
9015           gnutls_x509_privkey_t KEY, gnutls_digest_algorithm_t DIG,
9016           unsigned int FLAGS)
9017      CRQ: should contain a 'gnutls_x509_crq_t' structure
9018
9019      KEY: holds a private key
9020
9021      DIG: The message digest to use, i.e., 'GNUTLS_DIG_SHA1'
9022
9023      FLAGS: must be 0
9024
9025      This function will sign the certificate request with a private key.
9026      This must be the same key as the one used in
9027      'gnutls_x509_crt_set_key()' since a certificate request is self
9028      signed.
9029
9030      This must be the last step in a certificate request generation
9031      since all the previously set parameters are now signed.
9032
9033      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
9034      error code.  'GNUTLS_E_ASN1_VALUE_NOT_FOUND' is returned if you
9035      didn't set all information in the certificate request (e.g., the
9036      version using 'gnutls_x509_crq_set_version()' ).
9037
9038 gnutls_x509_crq_verify
9039 ----------------------
9040
9041  -- Function: int gnutls_x509_crq_verify (gnutls_x509_crq_t CRQ,
9042           unsigned int FLAGS)
9043      CRQ: is the crq to be verified
9044
9045      FLAGS: Flags that may be used to change the verification algorithm.
9046      Use OR of the gnutls_certificate_verify_flags enumerations.
9047
9048      This function will verify self signature in the certificate request
9049      and return its status.
9050
9051      *Returns:* In case of a verification failure
9052      'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
9053      code on success.
9054
9055      Since 2.12.0
9056
9057 gnutls_x509_crt_check_hostname
9058 ------------------------------
9059
9060  -- Function: int gnutls_x509_crt_check_hostname (gnutls_x509_crt_t
9061           CERT, const char * HOSTNAME)
9062      CERT: should contain an gnutls_x509_crt_t structure
9063
9064      HOSTNAME: A null terminated string that contains a DNS name
9065
9066      This function will check if the given certificate's subject matches
9067      the given hostname.  This is a basic implementation of the matching
9068      described in RFC6125, and takes into account wildcards, and the
9069      DNSName/IPAddress subject alternative name PKIX extension.
9070
9071      For details see also 'gnutls_x509_crt_check_hostname2()' .
9072
9073      *Returns:* non-zero for a successful match, and zero on failure.
9074
9075 gnutls_x509_crt_check_hostname2
9076 -------------------------------
9077
9078  -- Function: int gnutls_x509_crt_check_hostname2 (gnutls_x509_crt_t
9079           CERT, const char * HOSTNAME, unsigned int FLAGS)
9080      CERT: should contain an gnutls_x509_crt_t structure
9081
9082      HOSTNAME: A null terminated string that contains a DNS name
9083
9084      FLAGS: gnutls_certificate_verify_flags
9085
9086      This function will check if the given certificate's subject matches
9087      the given hostname.  This is a basic implementation of the matching
9088      described in RFC6125, and takes into account wildcards, and the
9089      DNSName/IPAddress subject alternative name PKIX extension.
9090
9091      IPv4 addresses are accepted by this function in the dotted-decimal
9092      format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the
9093      hexadecimal x:x:x:x:x:x:x:x format.  For them the IPAddress subject
9094      alternative name extension is consulted, as well as the DNSNames in
9095      case of a non-match.  The latter fallback exists due to
9096      misconfiguration of many servers which place an IPAddress inside
9097      the DNSName extension.
9098
9099      The comparison of dns names may have false-negatives as it is done
9100      byte by byte in non-ascii names.
9101
9102      When the flag 'GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS' is specified
9103      no wildcards are considered.  Otherwise they are only considered if
9104      the domain name consists of three components or more, and the
9105      wildcard starts at the leftmost position.
9106
9107      *Returns:* non-zero for a successful match, and zero on failure.
9108
9109 gnutls_x509_crt_check_issuer
9110 ----------------------------
9111
9112  -- Function: int gnutls_x509_crt_check_issuer (gnutls_x509_crt_t CERT,
9113           gnutls_x509_crt_t ISSUER)
9114      CERT: is the certificate to be checked
9115
9116      ISSUER: is the certificate of a possible issuer
9117
9118      This function will check if the given certificate was issued by the
9119      given issuer.  It checks the DN fields and the authority key
9120      identifier and subject key identifier fields match.
9121
9122      If the same certificate is provided at the 'cert' and 'issuer'
9123      fields, it will check whether the certificate is self-signed.
9124
9125      *Returns:* It will return true (1) if the given certificate is
9126      issued by the given issuer, and false (0) if not.
9127
9128 gnutls_x509_crt_check_revocation
9129 --------------------------------
9130
9131  -- Function: int gnutls_x509_crt_check_revocation (gnutls_x509_crt_t
9132           CERT, const gnutls_x509_crl_t * CRL_LIST, int CRL_LIST_LENGTH)
9133      CERT: should contain a 'gnutls_x509_crt_t' structure
9134
9135      CRL_LIST: should contain a list of gnutls_x509_crl_t structures
9136
9137      CRL_LIST_LENGTH: the length of the crl_list
9138
9139      This function will return check if the given certificate is
9140      revoked.  It is assumed that the CRLs have been verified before.
9141
9142      *Returns:* 0 if the certificate is NOT revoked, and 1 if it is.  A
9143      negative error code is returned on error.
9144
9145 gnutls_x509_crt_cpy_crl_dist_points
9146 -----------------------------------
9147
9148  -- Function: int gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t
9149           DST, gnutls_x509_crt_t SRC)
9150      DST: a certificate of type 'gnutls_x509_crt_t'
9151
9152      SRC: the certificate where the dist points will be copied from
9153
9154      This function will copy the CRL distribution points certificate
9155      extension, from the source to the destination certificate.  This
9156      may be useful to copy from a CA certificate to issued ones.
9157
9158      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9159      otherwise a negative error value.
9160
9161 gnutls_x509_crt_deinit
9162 ----------------------
9163
9164  -- Function: void gnutls_x509_crt_deinit (gnutls_x509_crt_t CERT)
9165      CERT: The structure to be deinitialized
9166
9167      This function will deinitialize a certificate structure.
9168
9169 gnutls_x509_crt_export
9170 ----------------------
9171
9172  -- Function: int gnutls_x509_crt_export (gnutls_x509_crt_t CERT,
9173           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
9174           OUTPUT_DATA_SIZE)
9175      CERT: Holds the certificate
9176
9177      FORMAT: the format of output params.  One of PEM or DER.
9178
9179      OUTPUT_DATA: will contain a certificate PEM or DER encoded
9180
9181      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
9182      replaced by the actual size of parameters)
9183
9184      This function will export the certificate to DER or PEM format.
9185
9186      If the buffer provided is not long enough to hold the output, then
9187      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
9188      be returned.
9189
9190      If the structure is PEM encoded, it will have a header of "BEGIN
9191      CERTIFICATE".
9192
9193      *Returns:* In case of failure a negative error code will be
9194      returned, and 0 on success.
9195
9196 gnutls_x509_crt_export2
9197 -----------------------
9198
9199  -- Function: int gnutls_x509_crt_export2 (gnutls_x509_crt_t CERT,
9200           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
9201      CERT: Holds the certificate
9202
9203      FORMAT: the format of output params.  One of PEM or DER.
9204
9205      OUT: will contain a certificate PEM or DER encoded
9206
9207      This function will export the certificate to DER or PEM format.
9208      The output buffer is allocated using 'gnutls_malloc()' .
9209
9210      If the structure is PEM encoded, it will have a header of "BEGIN
9211      CERTIFICATE".
9212
9213      *Returns:* In case of failure a negative error code will be
9214      returned, and 0 on success.
9215
9216      *Since:* 3.1.3
9217
9218 gnutls_x509_crt_get_activation_time
9219 -----------------------------------
9220
9221  -- Function: time_t gnutls_x509_crt_get_activation_time
9222           (gnutls_x509_crt_t CERT)
9223      CERT: should contain a 'gnutls_x509_crt_t' structure
9224
9225      This function will return the time this Certificate was or will be
9226      activated.
9227
9228      *Returns:* activation time, or (time_t)-1 on error.
9229
9230 gnutls_x509_crt_get_authority_info_access
9231 -----------------------------------------
9232
9233  -- Function: int gnutls_x509_crt_get_authority_info_access
9234           (gnutls_x509_crt_t CRT, unsigned int SEQ, int WHAT,
9235           gnutls_datum_t * DATA, unsigned int * CRITICAL)
9236      CRT: Holds the certificate
9237
9238      SEQ: specifies the sequence number of the access descriptor (0 for
9239      the first one, 1 for the second etc.)
9240
9241      WHAT: what data to get, a 'gnutls_info_access_what_t' type.
9242
9243      DATA: output data to be freed with 'gnutls_free()' .
9244
9245      CRITICAL: pointer to output integer that is set to non-zero if the
9246      extension is marked as critical (may be 'NULL' )
9247
9248      Note that a simpler API to access the authority info data is
9249      provided by 'gnutls_x509_aia_get()' and
9250      'gnutls_x509_ext_import_aia()' .
9251
9252      This function extracts the Authority Information Access (AIA)
9253      extension, see RFC 5280 section 4.2.2.1 for more information.  The
9254      AIA extension holds a sequence of AccessDescription (AD) data.
9255
9256      The 'seq' input parameter is used to indicate which member of the
9257      sequence the caller is interested in.  The first member is 0, the
9258      second member 1 and so on.  When the 'seq' value is out of bounds,
9259      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
9260
9261      The type of data returned in 'data' is specified via 'what' which
9262      should be 'gnutls_info_access_what_t' values.
9263
9264      If 'what' is 'GNUTLS_IA_ACCESSMETHOD_OID' then 'data' will hold the
9265      accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1").
9266
9267      If 'what' is 'GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE' , 'data'
9268      will hold the accessLocation GeneralName type (e.g.,
9269      "uniformResourceIdentifier").
9270
9271      If 'what' is 'GNUTLS_IA_URI' , 'data' will hold the accessLocation
9272      URI data.  Requesting this 'what' value leads to an error if the
9273      accessLocation is not of the "uniformResourceIdentifier" type.
9274
9275      If 'what' is 'GNUTLS_IA_OCSP_URI' , 'data' will hold the OCSP URI.
9276      Requesting this 'what' value leads to an error if the accessMethod
9277      is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
9278      the "uniformResourceIdentifier" type.  In that case
9279      'GNUTLS_E_UNKNOWN_ALGORITHM' will be returned, and 'seq' should be
9280      increased and this function called again.
9281
9282      If 'what' is 'GNUTLS_IA_CAISSUERS_URI' , 'data' will hold the
9283      caIssuers URI. Requesting this 'what' value leads to an error if
9284      the accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
9285      accessLocation is not of the "uniformResourceIdentifier" type.  In
9286      that case handle as in 'GNUTLS_IA_OCSP_URI' .
9287
9288      More 'what' values may be allocated in the future as needed.
9289
9290      If 'data' is NULL, the function does the same without storing the
9291      output data, that is, it will set 'critical' and do error checking
9292      as usual.
9293
9294      The value of the critical flag is returned in * 'critical' .
9295      Supply a NULL 'critical' if you want the function to make sure the
9296      extension is non-critical, as required by RFC 5280.
9297
9298      *Returns:* 'GNUTLS_E_SUCCESS' on success,
9299      'GNUTLS_E_INVALID_REQUEST' on invalid 'crt' ,
9300      'GNUTLS_E_CONSTRAINT_ERROR' if the extension is incorrectly marked
9301      as critical (use a non-NULL 'critical' to override),
9302      'GNUTLS_E_UNKNOWN_ALGORITHM' if the requested OID does not match
9303      (e.g., when using 'GNUTLS_IA_OCSP_URI' ), otherwise a negative
9304      error code.
9305
9306      *Since:* 3.0
9307
9308 gnutls_x509_crt_get_authority_key_gn_serial
9309 -------------------------------------------
9310
9311  -- Function: int gnutls_x509_crt_get_authority_key_gn_serial
9312           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * ALT, size_t
9313           * ALT_SIZE, unsigned int * ALT_TYPE, void * SERIAL, size_t *
9314           SERIAL_SIZE, unsigned int * CRITICAL)
9315      CERT: should contain a 'gnutls_x509_crt_t' structure
9316
9317      SEQ: specifies the sequence number of the alt name (0 for the first
9318      one, 1 for the second etc.)
9319
9320      ALT: is the place where the alternative name will be copied to
9321
9322      ALT_SIZE: holds the size of alt.
9323
9324      ALT_TYPE: holds the type of the alternative name (one of
9325      gnutls_x509_subject_alt_name_t).
9326
9327      SERIAL: buffer to store the serial number (may be null)
9328
9329      SERIAL_SIZE: Holds the size of the serial field (may be null)
9330
9331      CRITICAL: will be non-zero if the extension is marked as critical
9332      (may be null)
9333
9334      This function will return the X.509 authority key identifier when
9335      stored as a general name (authorityCertIssuer) and serial number.
9336
9337      Because more than one general names might be stored 'seq' can be
9338      used as a counter to request them all until
9339      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
9340
9341      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9342      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
9343      present, otherwise a negative error value.
9344
9345      *Since:* 3.0
9346
9347 gnutls_x509_crt_get_authority_key_id
9348 ------------------------------------
9349
9350  -- Function: int gnutls_x509_crt_get_authority_key_id
9351           (gnutls_x509_crt_t CERT, void * ID, size_t * ID_SIZE, unsigned
9352           int * CRITICAL)
9353      CERT: should contain a 'gnutls_x509_crt_t' structure
9354
9355      ID: The place where the identifier will be copied
9356
9357      ID_SIZE: Holds the size of the id field.
9358
9359      CRITICAL: will be non-zero if the extension is marked as critical
9360      (may be null)
9361
9362      This function will return the X.509v3 certificate authority's key
9363      identifier.  This is obtained by the X.509 Authority Key identifier
9364      extension field (2.5.29.35).  Note that this function only returns
9365      the keyIdentifier field of the extension and
9366      'GNUTLS_E_X509_UNSUPPORTED_EXTENSION' , if the extension contains
9367      the name and serial number of the certificate.  In that case
9368      'gnutls_x509_crt_get_authority_key_gn_serial()' may be used.
9369
9370      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9371      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
9372      present, otherwise a negative error value.
9373
9374 gnutls_x509_crt_get_basic_constraints
9375 -------------------------------------
9376
9377  -- Function: int gnutls_x509_crt_get_basic_constraints
9378           (gnutls_x509_crt_t CERT, unsigned int * CRITICAL, unsigned int
9379           * CA, int * PATHLEN)
9380      CERT: should contain a 'gnutls_x509_crt_t' structure
9381
9382      CRITICAL: will be non-zero if the extension is marked as critical
9383
9384      CA: pointer to output integer indicating CA status, may be NULL,
9385      value is 1 if the certificate CA flag is set, 0 otherwise.
9386
9387      PATHLEN: pointer to output integer indicating path length (may be
9388      NULL), non-negative error codes indicate a present
9389      pathLenConstraint field and the actual value, -1 indicate that the
9390      field is absent.
9391
9392      This function will read the certificate's basic constraints, and
9393      return the certificates CA status.  It reads the basicConstraints
9394      X.509 extension (2.5.29.19).
9395
9396      *Returns:* If the certificate is a CA a positive value will be
9397      returned, or (0) if the certificate does not have CA flag set.  A
9398      negative error code may be returned in case of errors.  If the
9399      certificate does not contain the basicConstraints extension
9400      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
9401
9402 gnutls_x509_crt_get_ca_status
9403 -----------------------------
9404
9405  -- Function: int gnutls_x509_crt_get_ca_status (gnutls_x509_crt_t CERT,
9406           unsigned int * CRITICAL)
9407      CERT: should contain a 'gnutls_x509_crt_t' structure
9408
9409      CRITICAL: will be non-zero if the extension is marked as critical
9410
9411      This function will return certificates CA status, by reading the
9412      basicConstraints X.509 extension (2.5.29.19).  If the certificate
9413      is a CA a positive value will be returned, or (0) if the
9414      certificate does not have CA flag set.
9415
9416      Use 'gnutls_x509_crt_get_basic_constraints()' if you want to read
9417      the pathLenConstraint field too.
9418
9419      *Returns:* If the certificate is a CA a positive value will be
9420      returned, or (0) if the certificate does not have CA flag set.  A
9421      negative error code may be returned in case of errors.  If the
9422      certificate does not contain the basicConstraints extension
9423      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
9424
9425 gnutls_x509_crt_get_crl_dist_points
9426 -----------------------------------
9427
9428  -- Function: int gnutls_x509_crt_get_crl_dist_points (gnutls_x509_crt_t
9429           CERT, unsigned int SEQ, void * SAN, size_t * SAN_SIZE,
9430           unsigned int * REASON_FLAGS, unsigned int * CRITICAL)
9431      CERT: should contain a 'gnutls_x509_crt_t' structure
9432
9433      SEQ: specifies the sequence number of the distribution point (0 for
9434      the first one, 1 for the second etc.)
9435
9436      SAN: is the place where the distribution point will be copied to
9437
9438      SAN_SIZE: holds the size of ret.
9439
9440      REASON_FLAGS: Revocation reasons.  An ORed sequence of flags from
9441      'gnutls_x509_crl_reason_flags_t' .
9442
9443      CRITICAL: will be non-zero if the extension is marked as critical
9444      (may be null)
9445
9446      This function retrieves the CRL distribution points (2.5.29.31),
9447      contained in the given certificate in the X509v3 Certificate
9448      Extensions.
9449
9450      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' and updates 'ret_size' if
9451      'ret_size' is not enough to hold the distribution point, or the
9452      type of the distribution point if everything was ok.  The type is
9453      one of the enumerated 'gnutls_x509_subject_alt_name_t' .  If the
9454      certificate does not have an Alternative name with the specified
9455      sequence number then 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is
9456      returned.
9457
9458 gnutls_x509_crt_get_dn
9459 ----------------------
9460
9461  -- Function: int gnutls_x509_crt_get_dn (gnutls_x509_crt_t CERT, char *
9462           BUF, size_t * BUF_SIZE)
9463      CERT: should contain a 'gnutls_x509_crt_t' structure
9464
9465      BUF: a pointer to a structure to hold the name (may be null)
9466
9467      BUF_SIZE: initially holds the size of 'buf'
9468
9469      This function will copy the name of the Certificate in the provided
9470      buffer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
9471      described in RFC4514.  The output string will be ASCII or UTF-8
9472      encoded, depending on the certificate data.
9473
9474      If 'buf' is null then only the size will be filled.
9475
9476      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
9477      not long enough, and in that case the 'buf_size' will be updated
9478      with the required size.  On success 0 is returned.
9479
9480 gnutls_x509_crt_get_dn2
9481 -----------------------
9482
9483  -- Function: int gnutls_x509_crt_get_dn2 (gnutls_x509_crt_t CERT,
9484           gnutls_datum_t * DN)
9485      CERT: should contain a 'gnutls_x509_crt_t' structure
9486
9487      DN: a pointer to a structure to hold the name
9488
9489      This function will allocate buffer and copy the name of the
9490      Certificate.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz"
9491      as described in RFC4514.  The output string will be ASCII or UTF-8
9492      encoded, depending on the certificate data.
9493
9494      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9495      otherwise a negative error value.  and a negative error code on
9496      error.
9497
9498      *Since:* 3.1.10
9499
9500 gnutls_x509_crt_get_dn_by_oid
9501 -----------------------------
9502
9503  -- Function: int gnutls_x509_crt_get_dn_by_oid (gnutls_x509_crt_t CERT,
9504           const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF,
9505           size_t * BUF_SIZE)
9506      CERT: should contain a 'gnutls_x509_crt_t' structure
9507
9508      OID: holds an Object Identified in null terminated string
9509
9510      INDX: In case multiple same OIDs exist in the RDN, this specifies
9511      which to send.  Use (0) to get the first one.
9512
9513      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
9514
9515      BUF: a pointer where the DN part will be copied (may be null).
9516
9517      BUF_SIZE: initially holds the size of 'buf'
9518
9519      This function will extract the part of the name of the Certificate
9520      subject specified by the given OID. The output, if the raw flag is
9521      not used, will be encoded as described in RFC4514.  Thus a string
9522      that is ASCII or UTF-8 encoded, depending on the certificate data.
9523
9524      Some helper macros with popular OIDs can be found in gnutls/x509.h
9525      If raw flag is (0), this function will only return known OIDs as
9526      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
9527      hex format with a '#' prefix.  You can check about known OIDs using
9528      'gnutls_x509_dn_oid_known()' .
9529
9530      If 'buf' is null then only the size will be filled.  If the
9531      'raw_flag' is not specified the output is always null terminated,
9532      although the 'buf_size' will not include the null character.
9533
9534      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
9535      not long enough, and in that case the 'buf_size' will be updated
9536      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
9537      there are no data in the current index.  On success 0 is returned.
9538
9539 gnutls_x509_crt_get_dn_oid
9540 --------------------------
9541
9542  -- Function: int gnutls_x509_crt_get_dn_oid (gnutls_x509_crt_t CERT,
9543           int INDX, void * OID, size_t * OID_SIZE)
9544      CERT: should contain a 'gnutls_x509_crt_t' structure
9545
9546      INDX: This specifies which OID to return.  Use (0) to get the first
9547      one.
9548
9549      OID: a pointer to a buffer to hold the OID (may be null)
9550
9551      OID_SIZE: initially holds the size of 'oid'
9552
9553      This function will extract the OIDs of the name of the Certificate
9554      subject specified by the given index.
9555
9556      If 'oid' is null then only the size will be filled.  The 'oid'
9557      returned will be null terminated, although 'oid_size' will not
9558      account for the trailing null.
9559
9560      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
9561      not long enough, and in that case the 'buf_size' will be updated
9562      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
9563      there are no data in the current index.  On success 0 is returned.
9564
9565 gnutls_x509_crt_get_expiration_time
9566 -----------------------------------
9567
9568  -- Function: time_t gnutls_x509_crt_get_expiration_time
9569           (gnutls_x509_crt_t CERT)
9570      CERT: should contain a 'gnutls_x509_crt_t' structure
9571
9572      This function will return the time this Certificate was or will be
9573      expired.
9574
9575      The no well defined expiration time can be checked against with the
9576      'GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION' macro.
9577
9578      *Returns:* expiration time, or (time_t)-1 on error.
9579
9580 gnutls_x509_crt_get_extension_by_oid
9581 ------------------------------------
9582
9583  -- Function: int gnutls_x509_crt_get_extension_by_oid
9584           (gnutls_x509_crt_t CERT, const char * OID, int INDX, void *
9585           BUF, size_t * BUF_SIZE, unsigned int * CRITICAL)
9586      CERT: should contain a 'gnutls_x509_crt_t' structure
9587
9588      OID: holds an Object Identified in null terminated string
9589
9590      INDX: In case multiple same OIDs exist in the extensions, this
9591      specifies which to send.  Use (0) to get the first one.
9592
9593      BUF: a pointer to a structure to hold the name (may be null)
9594
9595      BUF_SIZE: initially holds the size of 'buf'
9596
9597      CRITICAL: will be non-zero if the extension is marked as critical
9598
9599      This function will return the extension specified by the OID in the
9600      certificate.  The extensions will be returned as binary data DER
9601      encoded, in the provided buffer.
9602
9603      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9604      otherwise a negative error code is returned.  If the certificate
9605      does not contain the specified extension
9606      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
9607
9608 gnutls_x509_crt_get_extension_by_oid2
9609 -------------------------------------
9610
9611  -- Function: int gnutls_x509_crt_get_extension_by_oid2
9612           (gnutls_x509_crt_t CERT, const char * OID, int INDX,
9613           gnutls_datum_t * OUTPUT, unsigned int * CRITICAL)
9614      CERT: should contain a 'gnutls_x509_crt_t' structure
9615
9616      OID: holds an Object Identified in null terminated string
9617
9618      INDX: In case multiple same OIDs exist in the extensions, this
9619      specifies which to send.  Use (0) to get the first one.
9620
9621      OUTPUT: will hold the allocated extension data
9622
9623      CRITICAL: will be non-zero if the extension is marked as critical
9624
9625      This function will return the extension specified by the OID in the
9626      certificate.  The extensions will be returned as binary data DER
9627      encoded, in the provided buffer.
9628
9629      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9630      otherwise a negative error code is returned.  If the certificate
9631      does not contain the specified extension
9632      GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
9633
9634      *Since:* 3.3.8
9635
9636 gnutls_x509_crt_get_extension_data
9637 ----------------------------------
9638
9639  -- Function: int gnutls_x509_crt_get_extension_data (gnutls_x509_crt_t
9640           CERT, int INDX, void * DATA, size_t * SIZEOF_DATA)
9641      CERT: should contain a 'gnutls_x509_crt_t' structure
9642
9643      INDX: Specifies which extension OID to send.  Use (0) to get the
9644      first one.
9645
9646      DATA: a pointer to a structure to hold the data (may be null)
9647
9648      SIZEOF_DATA: initially holds the size of 'data'
9649
9650      This function will return the requested extension data in the
9651      certificate.  The extension data will be stored in the provided
9652      buffer.
9653
9654      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID and
9655      critical flag.  Use 'gnutls_x509_crt_get_extension_by_oid()'
9656      instead, if you want to get data indexed by the extension OID
9657      rather than sequence.
9658
9659      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9660      otherwise a negative error code is returned.  If you have reached
9661      the last extension available
9662      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
9663
9664 gnutls_x509_crt_get_extension_data2
9665 -----------------------------------
9666
9667  -- Function: int gnutls_x509_crt_get_extension_data2 (gnutls_x509_crt_t
9668           CERT, unsigned INDX, gnutls_datum_t * DATA)
9669      CERT: should contain a 'gnutls_x509_crt_t' structure
9670
9671      INDX: Specifies which extension OID to read.  Use (0) to get the
9672      first one.
9673
9674      DATA: will contain the extension DER-encoded data
9675
9676      This function will return the requested by the index extension data
9677      in the certificate.  The extension data will be allocated using
9678      'gnutls_malloc()' .
9679
9680      Use 'gnutls_x509_crt_get_extension_info()' to extract the OID.
9681
9682      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9683      otherwise a negative error code is returned.  If you have reached
9684      the last extension available
9685      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
9686
9687 gnutls_x509_crt_get_extension_info
9688 ----------------------------------
9689
9690  -- Function: int gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t
9691           CERT, int INDX, void * OID, size_t * OID_SIZE, unsigned int *
9692           CRITICAL)
9693      CERT: should contain a 'gnutls_x509_crt_t' structure
9694
9695      INDX: Specifies which extension OID to send.  Use (0) to get the
9696      first one.
9697
9698      OID: a pointer to a structure to hold the OID
9699
9700      OID_SIZE: initially holds the maximum size of 'oid' , on return
9701      holds actual size of 'oid' .
9702
9703      CRITICAL: output variable with critical flag, may be NULL.
9704
9705      This function will return the requested extension OID in the
9706      certificate, and the critical flag for it.  The extension OID will
9707      be stored as a string in the provided buffer.  Use
9708      'gnutls_x509_crt_get_extension()' to extract the data.
9709
9710      If the buffer provided is not long enough to hold the output, then
9711      'oid_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER' will be
9712      returned.  The 'oid' returned will be null terminated, although
9713      'oid_size' will not account for the trailing null.
9714
9715      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9716      otherwise a negative error code is returned.  If you have reached
9717      the last extension available
9718      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
9719
9720 gnutls_x509_crt_get_extension_oid
9721 ---------------------------------
9722
9723  -- Function: int gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t
9724           CERT, int INDX, void * OID, size_t * OID_SIZE)
9725      CERT: should contain a 'gnutls_x509_crt_t' structure
9726
9727      INDX: Specifies which extension OID to send.  Use (0) to get the
9728      first one.
9729
9730      OID: a pointer to a structure to hold the OID (may be null)
9731
9732      OID_SIZE: initially holds the size of 'oid'
9733
9734      This function will return the requested extension OID in the
9735      certificate.  The extension OID will be stored as a string in the
9736      provided buffer.
9737
9738      The 'oid' returned will be null terminated, although 'oid_size'
9739      will not account for the trailing null.
9740
9741      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9742      otherwise a negative error code is returned.  If you have reached
9743      the last extension available
9744      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
9745
9746 gnutls_x509_crt_get_fingerprint
9747 -------------------------------
9748
9749  -- Function: int gnutls_x509_crt_get_fingerprint (gnutls_x509_crt_t
9750           CERT, gnutls_digest_algorithm_t ALGO, void * BUF, size_t *
9751           BUF_SIZE)
9752      CERT: should contain a 'gnutls_x509_crt_t' structure
9753
9754      ALGO: is a digest algorithm
9755
9756      BUF: a pointer to a structure to hold the fingerprint (may be null)
9757
9758      BUF_SIZE: initially holds the size of 'buf'
9759
9760      This function will calculate and copy the certificate's fingerprint
9761      in the provided buffer.  The fingerprint is a hash of the
9762      DER-encoded data of the certificate.
9763
9764      If the buffer is null then only the size will be filled.
9765
9766      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
9767      not long enough, and in that case the *buf_size will be updated
9768      with the required size.  On success 0 is returned.
9769
9770 gnutls_x509_crt_get_issuer
9771 --------------------------
9772
9773  -- Function: int gnutls_x509_crt_get_issuer (gnutls_x509_crt_t CERT,
9774           gnutls_x509_dn_t * DN)
9775      CERT: should contain a 'gnutls_x509_crt_t' structure
9776
9777      DN: output variable with pointer to uint8_t DN
9778
9779      Return the Certificate's Issuer DN as a 'gnutls_x509_dn_t' data
9780      type, that can be decoded using 'gnutls_x509_dn_get_rdn_ava()' .
9781
9782      Note that 'dn' should be treated as constant.  Because it points
9783      into the 'cert' object, you should not use 'dn' after 'cert' is
9784      deallocated.
9785
9786      *Returns:* Returns 0 on success, or an error code.
9787
9788 gnutls_x509_crt_get_issuer_alt_name
9789 -----------------------------------
9790
9791  -- Function: int gnutls_x509_crt_get_issuer_alt_name (gnutls_x509_crt_t
9792           CERT, unsigned int SEQ, void * IAN, size_t * IAN_SIZE,
9793           unsigned int * CRITICAL)
9794      CERT: should contain a 'gnutls_x509_crt_t' structure
9795
9796      SEQ: specifies the sequence number of the alt name (0 for the first
9797      one, 1 for the second etc.)
9798
9799      IAN: is the place where the alternative name will be copied to
9800
9801      IAN_SIZE: holds the size of ian.
9802
9803      CRITICAL: will be non-zero if the extension is marked as critical
9804      (may be null)
9805
9806      This function retrieves the Issuer Alternative Name (2.5.29.18),
9807      contained in the given certificate in the X509v3 Certificate
9808      Extensions.
9809
9810      When the SAN type is otherName, it will extract the data in the
9811      otherName's value field, and 'GNUTLS_SAN_OTHERNAME' is returned.
9812      You may use 'gnutls_x509_crt_get_subject_alt_othername_oid()' to
9813      get the corresponding OID and the "virtual" SAN types (e.g.,
9814      'GNUTLS_SAN_OTHERNAME_XMPP' ).
9815
9816      If an otherName OID is known, the data will be decoded.  Otherwise
9817      the returned data will be DER encoded, and you will have to decode
9818      it yourself.  Currently, only the RFC 3920 id-on-xmppAddr Issuer
9819      AltName is recognized.
9820
9821      *Returns:* the alternative issuer name type on success, one of the
9822      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
9823      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ian_size' is not large enough to
9824      hold the value.  In that case 'ian_size' will be updated with the
9825      required size.  If the certificate does not have an Alternative
9826      name with the specified sequence number then
9827      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
9828
9829      *Since:* 2.10.0
9830
9831 gnutls_x509_crt_get_issuer_alt_name2
9832 ------------------------------------
9833
9834  -- Function: int gnutls_x509_crt_get_issuer_alt_name2
9835           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * IAN, size_t
9836           * IAN_SIZE, unsigned int * IAN_TYPE, unsigned int * CRITICAL)
9837      CERT: should contain a 'gnutls_x509_crt_t' structure
9838
9839      SEQ: specifies the sequence number of the alt name (0 for the first
9840      one, 1 for the second etc.)
9841
9842      IAN: is the place where the alternative name will be copied to
9843
9844      IAN_SIZE: holds the size of ret.
9845
9846      IAN_TYPE: holds the type of the alternative name (one of
9847      gnutls_x509_subject_alt_name_t).
9848
9849      CRITICAL: will be non-zero if the extension is marked as critical
9850      (may be null)
9851
9852      This function will return the alternative names, contained in the
9853      given certificate.  It is the same as
9854      'gnutls_x509_crt_get_issuer_alt_name()' except for the fact that it
9855      will return the type of the alternative name in 'ian_type' even if
9856      the function fails for some reason (i.e.  the buffer provided is
9857      not enough).
9858
9859      *Returns:* the alternative issuer name type on success, one of the
9860      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
9861      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'ian_size' is not large enough to
9862      hold the value.  In that case 'ian_size' will be updated with the
9863      required size.  If the certificate does not have an Alternative
9864      name with the specified sequence number then
9865      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
9866
9867      *Since:* 2.10.0
9868
9869 gnutls_x509_crt_get_issuer_alt_othername_oid
9870 --------------------------------------------
9871
9872  -- Function: int gnutls_x509_crt_get_issuer_alt_othername_oid
9873           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t
9874           * RET_SIZE)
9875      CERT: should contain a 'gnutls_x509_crt_t' structure
9876
9877      SEQ: specifies the sequence number of the alt name (0 for the first
9878      one, 1 for the second etc.)
9879
9880      RET: is the place where the otherName OID will be copied to
9881
9882      RET_SIZE: holds the size of ret.
9883
9884      This function will extract the type OID of an otherName Subject
9885      Alternative Name, contained in the given certificate, and return
9886      the type as an enumerated element.
9887
9888      If 'oid' is null then only the size will be filled.  The 'oid'
9889      returned will be null terminated, although 'oid_size' will not
9890      account for the trailing null.
9891
9892      This function is only useful if
9893      'gnutls_x509_crt_get_issuer_alt_name()' returned
9894      'GNUTLS_SAN_OTHERNAME' .
9895
9896      *Returns:* the alternative issuer name type on success, one of the
9897      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
9898      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
9899      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
9900      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
9901      'ret_size' is not large enough to hold the value.  In that case
9902      'ret_size' will be updated with the required size.  If the
9903      certificate does not have an Alternative name with the specified
9904      sequence number and with the otherName type then
9905      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
9906
9907      *Since:* 2.10.0
9908
9909 gnutls_x509_crt_get_issuer_dn
9910 -----------------------------
9911
9912  -- Function: int gnutls_x509_crt_get_issuer_dn (gnutls_x509_crt_t CERT,
9913           char * BUF, size_t * BUF_SIZE)
9914      CERT: should contain a 'gnutls_x509_crt_t' structure
9915
9916      BUF: a pointer to a structure to hold the name (may be null)
9917
9918      BUF_SIZE: initially holds the size of 'buf'
9919
9920      This function will copy the name of the Certificate issuer in the
9921      provided buffer.  The name will be in the form
9922      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
9923      will be ASCII or UTF-8 encoded, depending on the certificate data.
9924
9925      If 'buf' is null then only the size will be filled.
9926
9927      *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is
9928      not long enough, and in that case the 'buf_size' will be updated
9929      with the required size.  On success 0 is returned.
9930
9931 gnutls_x509_crt_get_issuer_dn2
9932 ------------------------------
9933
9934  -- Function: int gnutls_x509_crt_get_issuer_dn2 (gnutls_x509_crt_t
9935           CERT, gnutls_datum_t * DN)
9936      CERT: should contain a 'gnutls_x509_crt_t' structure
9937
9938      DN: a pointer to a structure to hold the name
9939
9940      This function will allocate buffer and copy the name of issuer of
9941      the Certificate.  The name will be in the form
9942      "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514.  The output string
9943      will be ASCII or UTF-8 encoded, depending on the certificate data.
9944
9945      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
9946      otherwise a negative error value.  and a negative error code on
9947      error.
9948
9949      *Since:* 3.1.10
9950
9951 gnutls_x509_crt_get_issuer_dn_by_oid
9952 ------------------------------------
9953
9954  -- Function: int gnutls_x509_crt_get_issuer_dn_by_oid
9955           (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned
9956           int RAW_FLAG, void * BUF, size_t * BUF_SIZE)
9957      CERT: should contain a 'gnutls_x509_crt_t' structure
9958
9959      OID: holds an Object Identified in null terminated string
9960
9961      INDX: In case multiple same OIDs exist in the RDN, this specifies
9962      which to send.  Use (0) to get the first one.
9963
9964      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
9965
9966      BUF: a pointer to a structure to hold the name (may be null)
9967
9968      BUF_SIZE: initially holds the size of 'buf'
9969
9970      This function will extract the part of the name of the Certificate
9971      issuer specified by the given OID. The output, if the raw flag is
9972      not used, will be encoded as described in RFC4514.  Thus a string
9973      that is ASCII or UTF-8 encoded, depending on the certificate data.
9974
9975      Some helper macros with popular OIDs can be found in gnutls/x509.h
9976      If raw flag is (0), this function will only return known OIDs as
9977      text.  Other OIDs will be DER encoded, as described in RFC4514 - in
9978      hex format with a '#' prefix.  You can check about known OIDs using
9979      'gnutls_x509_dn_oid_known()' .
9980
9981      If 'buf' is null then only the size will be filled.  If the
9982      'raw_flag' is not specified the output is always null terminated,
9983      although the 'buf_size' will not include the null character.
9984
9985      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
9986      not long enough, and in that case the 'buf_size' will be updated
9987      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
9988      there are no data in the current index.  On success 0 is returned.
9989
9990 gnutls_x509_crt_get_issuer_dn_oid
9991 ---------------------------------
9992
9993  -- Function: int gnutls_x509_crt_get_issuer_dn_oid (gnutls_x509_crt_t
9994           CERT, int INDX, void * OID, size_t * OID_SIZE)
9995      CERT: should contain a 'gnutls_x509_crt_t' structure
9996
9997      INDX: This specifies which OID to return.  Use (0) to get the first
9998      one.
9999
10000      OID: a pointer to a buffer to hold the OID (may be null)
10001
10002      OID_SIZE: initially holds the size of 'oid'
10003
10004      This function will extract the OIDs of the name of the Certificate
10005      issuer specified by the given index.
10006
10007      If 'oid' is null then only the size will be filled.  The 'oid'
10008      returned will be null terminated, although 'oid_size' will not
10009      account for the trailing null.
10010
10011      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
10012      not long enough, and in that case the 'buf_size' will be updated
10013      with the required size.  'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if
10014      there are no data in the current index.  On success 0 is returned.
10015
10016 gnutls_x509_crt_get_issuer_unique_id
10017 ------------------------------------
10018
10019  -- Function: int gnutls_x509_crt_get_issuer_unique_id
10020           (gnutls_x509_crt_t CRT, char * BUF, size_t * BUF_SIZE)
10021      CRT: Holds the certificate
10022
10023      BUF: user allocated memory buffer, will hold the unique id
10024
10025      BUF_SIZE: size of user allocated memory buffer (on input), will
10026      hold actual size of the unique ID on return.
10027
10028      This function will extract the issuerUniqueID value (if present)
10029      for the given certificate.
10030
10031      If the user allocated memory buffer is not large enough to hold the
10032      full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error
10033      will be returned, and buf_size will be set to the actual length.
10034
10035      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
10036      error code.
10037
10038      *Since:* 2.12.0
10039
10040 gnutls_x509_crt_get_key_id
10041 --------------------------
10042
10043  -- Function: int gnutls_x509_crt_get_key_id (gnutls_x509_crt_t CRT,
10044           unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
10045           OUTPUT_DATA_SIZE)
10046      CRT: Holds the certificate
10047
10048      FLAGS: should be 0 for now
10049
10050      OUTPUT_DATA: will contain the key ID
10051
10052      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
10053      replaced by the actual size of parameters)
10054
10055      This function will return a unique ID that depends on the public
10056      key parameters.  This ID can be used in checking whether a
10057      certificate corresponds to the given private key.
10058
10059      If the buffer provided is not long enough to hold the output, then
10060      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
10061      be returned.  The output will normally be a SHA-1 hash output,
10062      which is 20 bytes.
10063
10064      *Returns:* In case of failure a negative error code will be
10065      returned, and 0 on success.
10066
10067 gnutls_x509_crt_get_key_purpose_oid
10068 -----------------------------------
10069
10070  -- Function: int gnutls_x509_crt_get_key_purpose_oid (gnutls_x509_crt_t
10071           CERT, int INDX, void * OID, size_t * OID_SIZE, unsigned int *
10072           CRITICAL)
10073      CERT: should contain a 'gnutls_x509_crt_t' structure
10074
10075      INDX: This specifies which OID to return.  Use (0) to get the first
10076      one.
10077
10078      OID: a pointer to a buffer to hold the OID (may be null)
10079
10080      OID_SIZE: initially holds the size of 'oid'
10081
10082      CRITICAL: output flag to indicate criticality of extension
10083
10084      This function will extract the key purpose OIDs of the Certificate
10085      specified by the given index.  These are stored in the Extended Key
10086      Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
10087      human readable names.
10088
10089      If 'oid' is null then only the size will be filled.  The 'oid'
10090      returned will be null terminated, although 'oid_size' will not
10091      account for the trailing null.
10092
10093      *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is
10094      not long enough, and in that case the *oid_size will be updated
10095      with the required size.  On success 0 is returned.
10096
10097 gnutls_x509_crt_get_key_usage
10098 -----------------------------
10099
10100  -- Function: int gnutls_x509_crt_get_key_usage (gnutls_x509_crt_t CERT,
10101           unsigned int * KEY_USAGE, unsigned int * CRITICAL)
10102      CERT: should contain a 'gnutls_x509_crt_t' structure
10103
10104      KEY_USAGE: where the key usage bits will be stored
10105
10106      CRITICAL: will be non-zero if the extension is marked as critical
10107
10108      This function will return certificate's key usage, by reading the
10109      keyUsage X.509 extension (2.5.29.15).  The key usage value will
10110      ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE' ,
10111      'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
10112      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
10113      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
10114      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
10115
10116      *Returns:* the certificate key usage, or a negative error code in
10117      case of parsing error.  If the certificate does not contain the
10118      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
10119      returned.
10120
10121 gnutls_x509_crt_get_name_constraints
10122 ------------------------------------
10123
10124  -- Function: int gnutls_x509_crt_get_name_constraints
10125           (gnutls_x509_crt_t CRT, gnutls_x509_name_constraints_t NC,
10126           unsigned int FLAGS, unsigned int * CRITICAL)
10127      CRT: should contain a 'gnutls_x509_crt_t' structure
10128
10129      NC: The nameconstraints intermediate structure
10130
10131      FLAGS: zero or 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND'
10132
10133      CRITICAL: the extension status
10134
10135      This function will return an intermediate structure containing the
10136      name constraints of the provided CA certificate.  That structure
10137      can be used in combination with
10138      'gnutls_x509_name_constraints_check()' to verify whether a server's
10139      name is in accordance with the constraints.
10140
10141      When the 'flags' is set to 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND' ,
10142      then if the 'nc' structure is empty this function will behave
10143      identically as if the flag was not set.  Otherwise if there are
10144      elements in the 'nc' structure then only the excluded constraints
10145      will be appended to the constraints.
10146
10147      Note that 'nc' must be initialized prior to calling this function.
10148
10149      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10150      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
10151      present, otherwise a negative error value.
10152
10153      *Since:* 3.3.0
10154
10155 gnutls_x509_crt_get_pk_algorithm
10156 --------------------------------
10157
10158  -- Function: int gnutls_x509_crt_get_pk_algorithm (gnutls_x509_crt_t
10159           CERT, unsigned int * BITS)
10160      CERT: should contain a 'gnutls_x509_crt_t' structure
10161
10162      BITS: if bits is non null it will hold the size of the parameters'
10163      in bits
10164
10165      This function will return the public key algorithm of an X.509
10166      certificate.
10167
10168      If bits is non null, it should have enough size to hold the
10169      parameters size in bits.  For RSA the bits returned is the modulus.
10170      For DSA the bits returned are of the public exponent.
10171
10172      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
10173      success, or a negative error code on error.
10174
10175 gnutls_x509_crt_get_pk_dsa_raw
10176 ------------------------------
10177
10178  -- Function: int gnutls_x509_crt_get_pk_dsa_raw (gnutls_x509_crt_t CRT,
10179           gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G,
10180           gnutls_datum_t * Y)
10181      CRT: Holds the certificate
10182
10183      P: will hold the p
10184
10185      Q: will hold the q
10186
10187      G: will hold the g
10188
10189      Y: will hold the y
10190
10191      This function will export the DSA public key's parameters found in
10192      the given certificate.  The new parameters will be allocated using
10193      'gnutls_malloc()' and will be stored in the appropriate datum.
10194
10195      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
10196      error code.
10197
10198 gnutls_x509_crt_get_pk_rsa_raw
10199 ------------------------------
10200
10201  -- Function: int gnutls_x509_crt_get_pk_rsa_raw (gnutls_x509_crt_t CRT,
10202           gnutls_datum_t * M, gnutls_datum_t * E)
10203      CRT: Holds the certificate
10204
10205      M: will hold the modulus
10206
10207      E: will hold the public exponent
10208
10209      This function will export the RSA public key's parameters found in
10210      the given structure.  The new parameters will be allocated using
10211      'gnutls_malloc()' and will be stored in the appropriate datum.
10212
10213      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
10214      error code.
10215
10216 gnutls_x509_crt_get_policy
10217 --------------------------
10218
10219  -- Function: int gnutls_x509_crt_get_policy (gnutls_x509_crt_t CRT, int
10220           INDX, struct gnutls_x509_policy_st * POLICY, unsigned int *
10221           CRITICAL)
10222      CRT: should contain a 'gnutls_x509_crt_t' structure
10223
10224      INDX: This specifies which policy to return.  Use (0) to get the
10225      first one.
10226
10227      POLICY: A pointer to a policy structure.
10228
10229      CRITICAL: will be non-zero if the extension is marked as critical
10230
10231      This function will extract the certificate policy (extension
10232      2.5.29.32) specified by the given index.
10233
10234      The policy returned by this function must be deinitialized by using
10235      'gnutls_x509_policy_release()' .
10236
10237      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10238      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
10239      present, otherwise a negative error value.
10240
10241      *Since:* 3.1.5
10242
10243 gnutls_x509_crt_get_private_key_usage_period
10244 --------------------------------------------
10245
10246  -- Function: int gnutls_x509_crt_get_private_key_usage_period
10247           (gnutls_x509_crt_t CERT, time_t * ACTIVATION, time_t *
10248           EXPIRATION, unsigned int * CRITICAL)
10249      CERT: should contain a 'gnutls_x509_crt_t' structure
10250
10251      ACTIVATION: The activation time
10252
10253      EXPIRATION: The expiration time
10254
10255      CRITICAL: the extension status
10256
10257      This function will return the expiration and activation times of
10258      the private key of the certificate.  It relies on the PKIX
10259      extension 2.5.29.16 being present.
10260
10261      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10262      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
10263      present, otherwise a negative error value.
10264
10265 gnutls_x509_crt_get_proxy
10266 -------------------------
10267
10268  -- Function: int gnutls_x509_crt_get_proxy (gnutls_x509_crt_t CERT,
10269           unsigned int * CRITICAL, int * PATHLEN, char **
10270           POLICYLANGUAGE, char ** POLICY, size_t * SIZEOF_POLICY)
10271      CERT: should contain a 'gnutls_x509_crt_t' structure
10272
10273      CRITICAL: will be non-zero if the extension is marked as critical
10274
10275      PATHLEN: pointer to output integer indicating path length (may be
10276      NULL), non-negative error codes indicate a present
10277      pCPathLenConstraint field and the actual value, -1 indicate that
10278      the field is absent.
10279
10280      POLICYLANGUAGE: output variable with OID of policy language
10281
10282      POLICY: output variable with policy data
10283
10284      SIZEOF_POLICY: output variable size of policy data
10285
10286      This function will get information from a proxy certificate.  It
10287      reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
10288
10289      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10290      otherwise a negative error code is returned.
10291
10292 gnutls_x509_crt_get_raw_dn
10293 --------------------------
10294
10295  -- Function: int gnutls_x509_crt_get_raw_dn (gnutls_x509_crt_t CERT,
10296           gnutls_datum_t * DN)
10297      CERT: should contain a 'gnutls_x509_crt_t' structure
10298
10299      DN: will hold the starting point of the DN
10300
10301      This function will return a pointer to the DER encoded DN structure
10302      and the length.  This points to allocated data that must be free'd
10303      using 'gnutls_free()' .
10304
10305      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10306      otherwise a negative error value.  or a negative error code on
10307      error.
10308
10309 gnutls_x509_crt_get_raw_issuer_dn
10310 ---------------------------------
10311
10312  -- Function: int gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t
10313           CERT, gnutls_datum_t * DN)
10314      CERT: should contain a 'gnutls_x509_crt_t' structure
10315
10316      DN: will hold the starting point of the DN
10317
10318      This function will return a pointer to the DER encoded DN structure
10319      and the length.  This points to allocated data that must be free'd
10320      using 'gnutls_free()' .
10321
10322      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10323      otherwise a negative error value.or a negative error code on error.
10324
10325 gnutls_x509_crt_get_serial
10326 --------------------------
10327
10328  -- Function: int gnutls_x509_crt_get_serial (gnutls_x509_crt_t CERT,
10329           void * RESULT, size_t * RESULT_SIZE)
10330      CERT: should contain a 'gnutls_x509_crt_t' structure
10331
10332      RESULT: The place where the serial number will be copied
10333
10334      RESULT_SIZE: Holds the size of the result field.
10335
10336      This function will return the X.509 certificate's serial number.
10337      This is obtained by the X509 Certificate serialNumber field.
10338      Serial is not always a 32 or 64bit number.  Some CAs use large
10339      serial numbers, thus it may be wise to handle it as something
10340      uint8_t.
10341
10342      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10343      otherwise a negative error value.
10344
10345 gnutls_x509_crt_get_signature
10346 -----------------------------
10347
10348  -- Function: int gnutls_x509_crt_get_signature (gnutls_x509_crt_t CERT,
10349           char * SIG, size_t * SIG_SIZE)
10350      CERT: should contain a 'gnutls_x509_crt_t' structure
10351
10352      SIG: a pointer where the signature part will be copied (may be
10353      null).
10354
10355      SIG_SIZE: initially holds the size of 'sig'
10356
10357      This function will extract the signature field of a certificate.
10358
10359      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10360      otherwise a negative error value.  and a negative error code on
10361      error.
10362
10363 gnutls_x509_crt_get_signature_algorithm
10364 ---------------------------------------
10365
10366  -- Function: int gnutls_x509_crt_get_signature_algorithm
10367           (gnutls_x509_crt_t CERT)
10368      CERT: should contain a 'gnutls_x509_crt_t' structure
10369
10370      This function will return a value of the 'gnutls_sign_algorithm_t'
10371      enumeration that is the signature algorithm that has been used to
10372      sign this certificate.
10373
10374      *Returns:* a 'gnutls_sign_algorithm_t' value, or a negative error
10375      code on error.
10376
10377 gnutls_x509_crt_get_subject
10378 ---------------------------
10379
10380  -- Function: int gnutls_x509_crt_get_subject (gnutls_x509_crt_t CERT,
10381           gnutls_x509_dn_t * DN)
10382      CERT: should contain a 'gnutls_x509_crt_t' structure
10383
10384      DN: output variable with pointer to uint8_t DN.
10385
10386      Return the Certificate's Subject DN as a 'gnutls_x509_dn_t' data
10387      type, that can be decoded using 'gnutls_x509_dn_get_rdn_ava()' .
10388
10389      Note that 'dn' should be treated as constant.  Because it points
10390      into the 'cert' object, you should not use 'dn' after 'cert' is
10391      deallocated.
10392
10393      *Returns:* Returns 0 on success, or an error code.
10394
10395 gnutls_x509_crt_get_subject_alt_name
10396 ------------------------------------
10397
10398  -- Function: int gnutls_x509_crt_get_subject_alt_name
10399           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * SAN, size_t
10400           * SAN_SIZE, unsigned int * CRITICAL)
10401      CERT: should contain a 'gnutls_x509_crt_t' structure
10402
10403      SEQ: specifies the sequence number of the alt name (0 for the first
10404      one, 1 for the second etc.)
10405
10406      SAN: is the place where the alternative name will be copied to
10407
10408      SAN_SIZE: holds the size of san.
10409
10410      CRITICAL: will be non-zero if the extension is marked as critical
10411      (may be null)
10412
10413      This function retrieves the Alternative Name (2.5.29.17), contained
10414      in the given certificate in the X509v3 Certificate Extensions.
10415
10416      When the SAN type is otherName, it will extract the data in the
10417      otherName's value field, and 'GNUTLS_SAN_OTHERNAME' is returned.
10418      You may use 'gnutls_x509_crt_get_subject_alt_othername_oid()' to
10419      get the corresponding OID and the "virtual" SAN types (e.g.,
10420      'GNUTLS_SAN_OTHERNAME_XMPP' ).
10421
10422      If an otherName OID is known, the data will be decoded.  Otherwise
10423      the returned data will be DER encoded, and you will have to decode
10424      it yourself.  Currently, only the RFC 3920 id-on-xmppAddr SAN is
10425      recognized.
10426
10427      *Returns:* the alternative subject name type on success, one of the
10428      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
10429      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'san_size' is not large enough to
10430      hold the value.  In that case 'san_size' will be updated with the
10431      required size.  If the certificate does not have an Alternative
10432      name with the specified sequence number then
10433      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
10434
10435 gnutls_x509_crt_get_subject_alt_name2
10436 -------------------------------------
10437
10438  -- Function: int gnutls_x509_crt_get_subject_alt_name2
10439           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * SAN, size_t
10440           * SAN_SIZE, unsigned int * SAN_TYPE, unsigned int * CRITICAL)
10441      CERT: should contain a 'gnutls_x509_crt_t' structure
10442
10443      SEQ: specifies the sequence number of the alt name (0 for the first
10444      one, 1 for the second etc.)
10445
10446      SAN: is the place where the alternative name will be copied to
10447
10448      SAN_SIZE: holds the size of ret.
10449
10450      SAN_TYPE: holds the type of the alternative name (one of
10451      gnutls_x509_subject_alt_name_t).
10452
10453      CRITICAL: will be non-zero if the extension is marked as critical
10454      (may be null)
10455
10456      This function will return the alternative names, contained in the
10457      given certificate.  It is the same as
10458      'gnutls_x509_crt_get_subject_alt_name()' except for the fact that
10459      it will return the type of the alternative name in 'san_type' even
10460      if the function fails for some reason (i.e.  the buffer provided is
10461      not enough).
10462
10463      *Returns:* the alternative subject name type on success, one of the
10464      enumerated 'gnutls_x509_subject_alt_name_t' .  It will return
10465      'GNUTLS_E_SHORT_MEMORY_BUFFER' if 'san_size' is not large enough to
10466      hold the value.  In that case 'san_size' will be updated with the
10467      required size.  If the certificate does not have an Alternative
10468      name with the specified sequence number then
10469      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
10470
10471 gnutls_x509_crt_get_subject_alt_othername_oid
10472 ---------------------------------------------
10473
10474  -- Function: int gnutls_x509_crt_get_subject_alt_othername_oid
10475           (gnutls_x509_crt_t CERT, unsigned int SEQ, void * OID, size_t
10476           * OID_SIZE)
10477      CERT: should contain a 'gnutls_x509_crt_t' structure
10478
10479      SEQ: specifies the sequence number of the alt name (0 for the first
10480      one, 1 for the second etc.)
10481
10482      OID: is the place where the otherName OID will be copied to
10483
10484      OID_SIZE: holds the size of ret.
10485
10486      This function will extract the type OID of an otherName Subject
10487      Alternative Name, contained in the given certificate, and return
10488      the type as an enumerated element.
10489
10490      This function is only useful if
10491      'gnutls_x509_crt_get_subject_alt_name()' returned
10492      'GNUTLS_SAN_OTHERNAME' .
10493
10494      If 'oid' is null then only the size will be filled.  The 'oid'
10495      returned will be null terminated, although 'oid_size' will not
10496      account for the trailing null.
10497
10498      *Returns:* the alternative subject name type on success, one of the
10499      enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
10500      will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g.
10501      'GNUTLS_SAN_OTHERNAME_XMPP' , and 'GNUTLS_SAN_OTHERNAME' for
10502      unknown OIDs.  It will return 'GNUTLS_E_SHORT_MEMORY_BUFFER' if
10503      'ian_size' is not large enough to hold the value.  In that case
10504      'ian_size' will be updated with the required size.  If the
10505      certificate does not have an Alternative name with the specified
10506      sequence number and with the otherName type then
10507      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
10508
10509 gnutls_x509_crt_get_subject_key_id
10510 ----------------------------------
10511
10512  -- Function: int gnutls_x509_crt_get_subject_key_id (gnutls_x509_crt_t
10513           CERT, void * RET, size_t * RET_SIZE, unsigned int * CRITICAL)
10514      CERT: should contain a 'gnutls_x509_crt_t' structure
10515
10516      RET: The place where the identifier will be copied
10517
10518      RET_SIZE: Holds the size of the result field.
10519
10520      CRITICAL: will be non-zero if the extension is marked as critical
10521      (may be null)
10522
10523      This function will return the X.509v3 certificate's subject key
10524      identifier.  This is obtained by the X.509 Subject Key identifier
10525      extension field (2.5.29.14).
10526
10527      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10528      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
10529      present, otherwise a negative error value.
10530
10531 gnutls_x509_crt_get_subject_unique_id
10532 -------------------------------------
10533
10534  -- Function: int gnutls_x509_crt_get_subject_unique_id
10535           (gnutls_x509_crt_t CRT, char * BUF, size_t * BUF_SIZE)
10536      CRT: Holds the certificate
10537
10538      BUF: user allocated memory buffer, will hold the unique id
10539
10540      BUF_SIZE: size of user allocated memory buffer (on input), will
10541      hold actual size of the unique ID on return.
10542
10543      This function will extract the subjectUniqueID value (if present)
10544      for the given certificate.
10545
10546      If the user allocated memory buffer is not large enough to hold the
10547      full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error
10548      will be returned, and buf_size will be set to the actual length.
10549
10550      *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
10551      error code.
10552
10553 gnutls_x509_crt_get_version
10554 ---------------------------
10555
10556  -- Function: int gnutls_x509_crt_get_version (gnutls_x509_crt_t CERT)
10557      CERT: should contain a 'gnutls_x509_crt_t' structure
10558
10559      This function will return the version of the specified Certificate.
10560
10561      *Returns:* version of certificate, or a negative error code on
10562      error.
10563
10564 gnutls_x509_crt_import
10565 ----------------------
10566
10567  -- Function: int gnutls_x509_crt_import (gnutls_x509_crt_t CERT, const
10568           gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
10569      CERT: The structure to store the parsed certificate.
10570
10571      DATA: The DER or PEM encoded certificate.
10572
10573      FORMAT: One of DER or PEM
10574
10575      This function will convert the given DER or PEM encoded Certificate
10576      to the native gnutls_x509_crt_t format.  The output will be stored
10577      in 'cert' .
10578
10579      If the Certificate is PEM encoded it should have a header of "X509
10580      CERTIFICATE", or "CERTIFICATE".
10581
10582      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10583      otherwise a negative error value.
10584
10585 gnutls_x509_crt_init
10586 --------------------
10587
10588  -- Function: int gnutls_x509_crt_init (gnutls_x509_crt_t * CERT)
10589      CERT: The structure to be initialized
10590
10591      This function will initialize an X.509 certificate structure.
10592
10593      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10594      otherwise a negative error value.
10595
10596 gnutls_x509_crt_list_import
10597 ---------------------------
10598
10599  -- Function: int gnutls_x509_crt_list_import (gnutls_x509_crt_t *
10600           CERTS, unsigned int * CERT_MAX, const gnutls_datum_t * DATA,
10601           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
10602      CERTS: The structures to store the parsed certificate.  Must not be
10603      initialized.
10604
10605      CERT_MAX: Initially must hold the maximum number of certs.  It will
10606      be updated with the number of certs available.
10607
10608      DATA: The PEM encoded certificate.
10609
10610      FORMAT: One of DER or PEM.
10611
10612      FLAGS: must be (0) or an OR'd sequence of
10613      gnutls_certificate_import_flags.
10614
10615      This function will convert the given PEM encoded certificate list
10616      to the native gnutls_x509_crt_t format.  The output will be stored
10617      in 'certs' .  They will be automatically initialized.
10618
10619      The flag 'GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED' will cause
10620      import to fail if the certificates in the provided buffer are more
10621      than the available structures.  The
10622      'GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED' flag will cause the
10623      function to fail if the provided list is not sorted from subject to
10624      issuer.
10625
10626      If the Certificate is PEM encoded it should have a header of "X509
10627      CERTIFICATE", or "CERTIFICATE".
10628
10629      *Returns:* the number of certificates read or a negative error
10630      value.
10631
10632 gnutls_x509_crt_list_import2
10633 ----------------------------
10634
10635  -- Function: int gnutls_x509_crt_list_import2 (gnutls_x509_crt_t **
10636           CERTS, unsigned int * SIZE, const gnutls_datum_t * DATA,
10637           gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)
10638      CERTS: The structures to store the parsed certificate.  Must not be
10639      initialized.
10640
10641      SIZE: It will contain the size of the list.
10642
10643      DATA: The PEM encoded certificate.
10644
10645      FORMAT: One of DER or PEM.
10646
10647      FLAGS: must be (0) or an OR'd sequence of
10648      gnutls_certificate_import_flags.
10649
10650      This function will convert the given PEM encoded certificate list
10651      to the native gnutls_x509_crt_t format.  The output will be stored
10652      in 'certs' which will allocated and initialized.
10653
10654      If the Certificate is PEM encoded it should have a header of "X509
10655      CERTIFICATE", or "CERTIFICATE".
10656
10657      To deinitialize 'certs' , you need to deinitialize each crt
10658      structure independently, and use 'gnutls_free()' at
10659
10660      *Returns:* the number of certificates read or a negative error
10661      value.
10662
10663      *Since:* 3.0
10664
10665 gnutls_x509_crt_list_verify
10666 ---------------------------
10667
10668  -- Function: int gnutls_x509_crt_list_verify (const gnutls_x509_crt_t *
10669           CERT_LIST, int CERT_LIST_LENGTH, const gnutls_x509_crt_t *
10670           CA_LIST, int CA_LIST_LENGTH, const gnutls_x509_crl_t *
10671           CRL_LIST, int CRL_LIST_LENGTH, unsigned int FLAGS, unsigned
10672           int * VERIFY)
10673      CERT_LIST: is the certificate list to be verified
10674
10675      CERT_LIST_LENGTH: holds the number of certificate in cert_list
10676
10677      CA_LIST: is the CA list which will be used in verification
10678
10679      CA_LIST_LENGTH: holds the number of CA certificate in CA_list
10680
10681      CRL_LIST: holds a list of CRLs.
10682
10683      CRL_LIST_LENGTH: the length of CRL list.
10684
10685      FLAGS: Flags that may be used to change the verification algorithm.
10686      Use OR of the gnutls_certificate_verify_flags enumerations.
10687
10688      VERIFY: will hold the certificate verification output.
10689
10690      This function will try to verify the given certificate list and
10691      return its status.  If no flags are specified (0), this function
10692      will use the basicConstraints (2.5.29.19) PKIX extension.  This
10693      means that only a certificate authority is allowed to sign a
10694      certificate.
10695
10696      You must also check the peer's name in order to check if the
10697      verified certificate belongs to the actual peer.
10698
10699      The certificate verification output will be put in 'verify' and
10700      will be one or more of the gnutls_certificate_status_t enumerated
10701      elements bitwise or'd.  For a more detailed verification status use
10702      'gnutls_x509_crt_verify()' per list element.
10703
10704      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10705      otherwise a negative error value.
10706
10707 gnutls_x509_crt_print
10708 ---------------------
10709
10710  -- Function: int gnutls_x509_crt_print (gnutls_x509_crt_t CERT,
10711           gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t *
10712           OUT)
10713      CERT: The structure to be printed
10714
10715      FORMAT: Indicate the format to use
10716
10717      OUT: Newly allocated datum with null terminated string.
10718
10719      This function will pretty print a X.509 certificate, suitable for
10720      display to a human.
10721
10722      If the format is 'GNUTLS_CRT_PRINT_FULL' then all fields of the
10723      certificate will be output, on multiple lines.  The
10724      'GNUTLS_CRT_PRINT_ONELINE' format will generate one line with some
10725      selected fields, which is useful for logging purposes.
10726
10727      The output 'out' needs to be deallocated using 'gnutls_free()' .
10728
10729      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10730      otherwise a negative error value.
10731
10732 gnutls_x509_crt_set_activation_time
10733 -----------------------------------
10734
10735  -- Function: int gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t
10736           CERT, time_t ACT_TIME)
10737      CERT: a certificate of type 'gnutls_x509_crt_t'
10738
10739      ACT_TIME: The actual time
10740
10741      This function will set the time this Certificate was or will be
10742      activated.
10743
10744      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10745      otherwise a negative error value.
10746
10747 gnutls_x509_crt_set_authority_info_access
10748 -----------------------------------------
10749
10750  -- Function: int gnutls_x509_crt_set_authority_info_access
10751           (gnutls_x509_crt_t CRT, int WHAT, gnutls_datum_t * DATA)
10752      CRT: Holds the certificate
10753
10754      WHAT: what data to get, a 'gnutls_info_access_what_t' type.
10755
10756      DATA: output data to be freed with 'gnutls_free()' .
10757
10758      This function sets the Authority Information Access (AIA)
10759      extension, see RFC 5280 section 4.2.2.1 for more information.
10760
10761      The type of data stored in 'data' is specified via 'what' which
10762      should be 'gnutls_info_access_what_t' values.
10763
10764      If 'what' is 'GNUTLS_IA_OCSP_URI' , 'data' will hold the OCSP URI.
10765      If 'what' is 'GNUTLS_IA_CAISSUERS_URI' , 'data' will hold the
10766      caIssuers URI.
10767
10768      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10769      otherwise a negative error value.
10770
10771      *Since:* 3.0
10772
10773 gnutls_x509_crt_set_authority_key_id
10774 ------------------------------------
10775
10776  -- Function: int gnutls_x509_crt_set_authority_key_id
10777           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
10778      CERT: a certificate of type 'gnutls_x509_crt_t'
10779
10780      ID: The key ID
10781
10782      ID_SIZE: Holds the size of the key ID field.
10783
10784      This function will set the X.509 certificate's authority key ID
10785      extension.  Only the keyIdentifier field can be set with this
10786      function.
10787
10788      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10789      otherwise a negative error value.
10790
10791 gnutls_x509_crt_set_basic_constraints
10792 -------------------------------------
10793
10794  -- Function: int gnutls_x509_crt_set_basic_constraints
10795           (gnutls_x509_crt_t CRT, unsigned int CA, int
10796           PATHLENCONSTRAINT)
10797      CRT: a certificate of type 'gnutls_x509_crt_t'
10798
10799      CA: true(1) or false(0).  Depending on the Certificate authority
10800      status.
10801
10802      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
10803      of path, and negative error codes indicate that the
10804      pathLenConstraints field should not be present.
10805
10806      This function will set the basicConstraints certificate extension.
10807
10808      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10809      otherwise a negative error value.
10810
10811 gnutls_x509_crt_set_ca_status
10812 -----------------------------
10813
10814  -- Function: int gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t CRT,
10815           unsigned int CA)
10816      CRT: a certificate of type 'gnutls_x509_crt_t'
10817
10818      CA: true(1) or false(0).  Depending on the Certificate authority
10819      status.
10820
10821      This function will set the basicConstraints certificate extension.
10822      Use 'gnutls_x509_crt_set_basic_constraints()' if you want to
10823      control the pathLenConstraint field too.
10824
10825      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10826      otherwise a negative error value.
10827
10828 gnutls_x509_crt_set_crl_dist_points
10829 -----------------------------------
10830
10831  -- Function: int gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t
10832           CRT, gnutls_x509_subject_alt_name_t TYPE, const void *
10833           DATA_STRING, unsigned int REASON_FLAGS)
10834      CRT: a certificate of type 'gnutls_x509_crt_t'
10835
10836      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
10837
10838      DATA_STRING: The data to be set
10839
10840      REASON_FLAGS: revocation reasons
10841
10842      This function will set the CRL distribution points certificate
10843      extension.
10844
10845      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10846      otherwise a negative error value.
10847
10848 gnutls_x509_crt_set_crl_dist_points2
10849 ------------------------------------
10850
10851  -- Function: int gnutls_x509_crt_set_crl_dist_points2
10852           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
10853           const void * DATA, unsigned int DATA_SIZE, unsigned int
10854           REASON_FLAGS)
10855      CRT: a certificate of type 'gnutls_x509_crt_t'
10856
10857      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
10858
10859      DATA: The data to be set
10860
10861      DATA_SIZE: The data size
10862
10863      REASON_FLAGS: revocation reasons
10864
10865      This function will set the CRL distribution points certificate
10866      extension.
10867
10868      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10869      otherwise a negative error value.
10870
10871      *Since:* 2.6.0
10872
10873 gnutls_x509_crt_set_crq
10874 -----------------------
10875
10876  -- Function: int gnutls_x509_crt_set_crq (gnutls_x509_crt_t CRT,
10877           gnutls_x509_crq_t CRQ)
10878      CRT: a certificate of type 'gnutls_x509_crt_t'
10879
10880      CRQ: holds a certificate request
10881
10882      This function will set the name and public parameters as well as
10883      the extensions from the given certificate request to the
10884      certificate.  Only RSA keys are currently supported.
10885
10886      Note that this function will only set the 'crq' if it is self
10887      signed and the signature is correct.  See 'gnutls_x509_crq_sign2()'
10888      .
10889
10890      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10891      otherwise a negative error value.
10892
10893 gnutls_x509_crt_set_crq_extensions
10894 ----------------------------------
10895
10896  -- Function: int gnutls_x509_crt_set_crq_extensions (gnutls_x509_crt_t
10897           CRT, gnutls_x509_crq_t CRQ)
10898      CRT: a certificate of type 'gnutls_x509_crt_t'
10899
10900      CRQ: holds a certificate request
10901
10902      This function will set extensions from the given request to the
10903      certificate.
10904
10905      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10906      otherwise a negative error value.
10907
10908      *Since:* 2.8.0
10909
10910 gnutls_x509_crt_set_dn
10911 ----------------------
10912
10913  -- Function: int gnutls_x509_crt_set_dn (gnutls_x509_crt_t CRT, const
10914           char * DN, const char ** ERR)
10915      CRT: a certificate of type 'gnutls_x509_crt_t'
10916
10917      DN: a comma separated DN string (RFC4514)
10918
10919      ERR: indicates the error position (if any)
10920
10921      This function will set the DN on the provided certificate.  The
10922      input string should be plain ASCII or UTF-8 encoded.
10923
10924      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10925      otherwise a negative error value.
10926
10927 gnutls_x509_crt_set_dn_by_oid
10928 -----------------------------
10929
10930  -- Function: int gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t CRT,
10931           const char * OID, unsigned int RAW_FLAG, const void * NAME,
10932           unsigned int SIZEOF_NAME)
10933      CRT: a certificate of type 'gnutls_x509_crt_t'
10934
10935      OID: holds an Object Identifier in a null terminated string
10936
10937      RAW_FLAG: must be 0, or 1 if the data are DER encoded
10938
10939      NAME: a pointer to the name
10940
10941      SIZEOF_NAME: holds the size of 'name'
10942
10943      This function will set the part of the name of the Certificate
10944      subject, specified by the given OID. The input string should be
10945      ASCII or UTF-8 encoded.
10946
10947      Some helper macros with popular OIDs can be found in gnutls/x509.h
10948      With this function you can only set the known OIDs.  You can test
10949      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
10950      are not known (by gnutls) you should properly DER encode your data,
10951      and call this function with 'raw_flag' set.
10952
10953      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10954      otherwise a negative error value.
10955
10956 gnutls_x509_crt_set_expiration_time
10957 -----------------------------------
10958
10959  -- Function: int gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t
10960           CERT, time_t EXP_TIME)
10961      CERT: a certificate of type 'gnutls_x509_crt_t'
10962
10963      EXP_TIME: The actual time
10964
10965      This function will set the time this Certificate will expire.
10966      Setting an expiration time to (time_t)-1 or to
10967      'GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION' will set to the no
10968      well-defined expiration date value.
10969
10970      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10971      otherwise a negative error value.
10972
10973 gnutls_x509_crt_set_extension_by_oid
10974 ------------------------------------
10975
10976  -- Function: int gnutls_x509_crt_set_extension_by_oid
10977           (gnutls_x509_crt_t CRT, const char * OID, const void * BUF,
10978           size_t SIZEOF_BUF, unsigned int CRITICAL)
10979      CRT: a certificate of type 'gnutls_x509_crt_t'
10980
10981      OID: holds an Object Identified in null terminated string
10982
10983      BUF: a pointer to a DER encoded data
10984
10985      SIZEOF_BUF: holds the size of 'buf'
10986
10987      CRITICAL: should be non-zero if the extension is to be marked as
10988      critical
10989
10990      This function will set an the extension, by the specified OID, in
10991      the certificate.  The extension data should be binary data DER
10992      encoded.
10993
10994      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
10995      otherwise a negative error value.
10996
10997 gnutls_x509_crt_set_issuer_alt_name
10998 -----------------------------------
10999
11000  -- Function: int gnutls_x509_crt_set_issuer_alt_name (gnutls_x509_crt_t
11001           CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA,
11002           unsigned int DATA_SIZE, unsigned int FLAGS)
11003      CRT: a certificate of type 'gnutls_x509_crt_t'
11004
11005      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
11006
11007      DATA: The data to be set
11008
11009      DATA_SIZE: The size of data to be set
11010
11011      FLAGS: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND
11012      to append.
11013
11014      This function will set the issuer alternative name certificate
11015      extension.  It can set the same types as
11016      'gnutls_x509_crt_set_subject_alt_name()' .
11017
11018      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11019      otherwise a negative error value.
11020
11021      *Since:* 3.3.0
11022
11023 gnutls_x509_crt_set_issuer_dn
11024 -----------------------------
11025
11026  -- Function: int gnutls_x509_crt_set_issuer_dn (gnutls_x509_crt_t CRT,
11027           const char * DN, const char ** ERR)
11028      CRT: a certificate of type 'gnutls_x509_crt_t'
11029
11030      DN: a comma separated DN string (RFC4514)
11031
11032      ERR: indicates the error position (if any)
11033
11034      This function will set the DN on the provided certificate.  The
11035      input string should be plain ASCII or UTF-8 encoded.
11036
11037      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11038      otherwise a negative error value.
11039
11040 gnutls_x509_crt_set_issuer_dn_by_oid
11041 ------------------------------------
11042
11043  -- Function: int gnutls_x509_crt_set_issuer_dn_by_oid
11044           (gnutls_x509_crt_t CRT, const char * OID, unsigned int
11045           RAW_FLAG, const void * NAME, unsigned int SIZEOF_NAME)
11046      CRT: a certificate of type 'gnutls_x509_crt_t'
11047
11048      OID: holds an Object Identifier in a null terminated string
11049
11050      RAW_FLAG: must be 0, or 1 if the data are DER encoded
11051
11052      NAME: a pointer to the name
11053
11054      SIZEOF_NAME: holds the size of 'name'
11055
11056      This function will set the part of the name of the Certificate
11057      issuer, specified by the given OID. The input string should be
11058      ASCII or UTF-8 encoded.
11059
11060      Some helper macros with popular OIDs can be found in gnutls/x509.h
11061      With this function you can only set the known OIDs.  You can test
11062      for known OIDs using 'gnutls_x509_dn_oid_known()' .  For OIDs that
11063      are not known (by gnutls) you should properly DER encode your data,
11064      and call this function with 'raw_flag' set.
11065
11066      Normally you do not need to call this function, since the signing
11067      operation will copy the signer's name as the issuer of the
11068      certificate.
11069
11070      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11071      otherwise a negative error value.
11072
11073 gnutls_x509_crt_set_issuer_unique_id
11074 ------------------------------------
11075
11076  -- Function: int gnutls_x509_crt_set_issuer_unique_id
11077           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
11078      CERT: a certificate of type 'gnutls_x509_crt_t'
11079
11080      ID: The unique ID
11081
11082      ID_SIZE: Holds the size of the unique ID.
11083
11084      This function will set the X.509 certificate's issuer unique ID
11085      field.
11086
11087      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11088      otherwise a negative error value.
11089
11090 gnutls_x509_crt_set_key
11091 -----------------------
11092
11093  -- Function: int gnutls_x509_crt_set_key (gnutls_x509_crt_t CRT,
11094           gnutls_x509_privkey_t KEY)
11095      CRT: a certificate of type 'gnutls_x509_crt_t'
11096
11097      KEY: holds a private key
11098
11099      This function will set the public parameters from the given private
11100      key to the certificate.  Only RSA keys are currently supported.
11101
11102      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11103      otherwise a negative error value.
11104
11105 gnutls_x509_crt_set_key_purpose_oid
11106 -----------------------------------
11107
11108  -- Function: int gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t
11109           CERT, const void * OID, unsigned int CRITICAL)
11110      CERT: a certificate of type 'gnutls_x509_crt_t'
11111
11112      OID: a pointer to a null terminated string that holds the OID
11113
11114      CRITICAL: Whether this extension will be critical or not
11115
11116      This function will set the key purpose OIDs of the Certificate.
11117      These are stored in the Extended Key Usage extension (2.5.29.37)
11118      See the GNUTLS_KP_* definitions for human readable names.
11119
11120      Subsequent calls to this function will append OIDs to the OID list.
11121
11122      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11123      otherwise a negative error code is returned.
11124
11125 gnutls_x509_crt_set_key_usage
11126 -----------------------------
11127
11128  -- Function: int gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t CRT,
11129           unsigned int USAGE)
11130      CRT: a certificate of type 'gnutls_x509_crt_t'
11131
11132      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
11133
11134      This function will set the keyUsage certificate extension.
11135
11136      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11137      otherwise a negative error value.
11138
11139 gnutls_x509_crt_set_name_constraints
11140 ------------------------------------
11141
11142  -- Function: int gnutls_x509_crt_set_name_constraints
11143           (gnutls_x509_crt_t CRT, gnutls_x509_name_constraints_t NC,
11144           unsigned int CRITICAL)
11145      CRT: The certificate structure
11146
11147      NC: The nameconstraints structure
11148
11149      CRITICAL: whether this extension will be critical
11150
11151      This function will set the provided name constraints to the
11152      certificate extension list.  This extension is always marked as
11153      critical.
11154
11155      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11156      otherwise a negative error value.
11157
11158      *Since:* 3.3.0
11159
11160 gnutls_x509_crt_set_pin_function
11161 --------------------------------
11162
11163  -- Function: void gnutls_x509_crt_set_pin_function (gnutls_x509_crt_t
11164           CRT, gnutls_pin_callback_t FN, void * USERDATA)
11165      CRT: The certificate structure
11166
11167      FN: the callback
11168
11169      USERDATA: data associated with the callback
11170
11171      This function will set a callback function to be used when it is
11172      required to access a protected object.  This function overrides the
11173      global function set using 'gnutls_pkcs11_set_pin_function()' .
11174
11175      Note that this callback is currently used only during the import of
11176      a PKCS '11' certificate with 'gnutls_x509_crt_import_pkcs11_url()'
11177      .
11178
11179      *Since:* 3.1.0
11180
11181 gnutls_x509_crt_set_policy
11182 --------------------------
11183
11184  -- Function: int gnutls_x509_crt_set_policy (gnutls_x509_crt_t CRT,
11185           const struct gnutls_x509_policy_st * POLICY, unsigned int
11186           CRITICAL)
11187      CRT: should contain a 'gnutls_x509_crt_t' structure
11188
11189      POLICY: A pointer to a policy structure.
11190
11191      CRITICAL: use non-zero if the extension is marked as critical
11192
11193      This function will set the certificate policy extension
11194      (2.5.29.32).  Multiple calls to this function append a new policy.
11195
11196      Note the maximum text size for the qualifier
11197      'GNUTLS_X509_QUALIFIER_NOTICE' is 200 characters.  This function
11198      will fail with 'GNUTLS_E_INVALID_REQUEST' if this is exceeded.
11199
11200      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11201      otherwise a negative error value.
11202
11203      *Since:* 3.1.5
11204
11205 gnutls_x509_crt_set_private_key_usage_period
11206 --------------------------------------------
11207
11208  -- Function: int gnutls_x509_crt_set_private_key_usage_period
11209           (gnutls_x509_crt_t CRT, time_t ACTIVATION, time_t EXPIRATION)
11210      CRT: a certificate of type 'gnutls_x509_crt_t'
11211
11212      ACTIVATION: The activation time
11213
11214      EXPIRATION: The expiration time
11215
11216      This function will set the private key usage period extension
11217      (2.5.29.16).
11218
11219      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11220      otherwise a negative error value.
11221
11222 gnutls_x509_crt_set_proxy
11223 -------------------------
11224
11225  -- Function: int gnutls_x509_crt_set_proxy (gnutls_x509_crt_t CRT, int
11226           PATHLENCONSTRAINT, const char * POLICYLANGUAGE, const char *
11227           POLICY, size_t SIZEOF_POLICY)
11228      CRT: a certificate of type 'gnutls_x509_crt_t'
11229
11230      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
11231      of path, and negative error codes indicate that the
11232      pathLenConstraints field should not be present.
11233
11234      POLICYLANGUAGE: OID describing the language of 'policy' .
11235
11236      POLICY: uint8_t byte array with policy language, can be 'NULL'
11237
11238      SIZEOF_POLICY: size of 'policy' .
11239
11240      This function will set the proxyCertInfo extension.
11241
11242      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11243      otherwise a negative error value.
11244
11245 gnutls_x509_crt_set_proxy_dn
11246 ----------------------------
11247
11248  -- Function: int gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t CRT,
11249           gnutls_x509_crt_t EECRT, unsigned int RAW_FLAG, const void *
11250           NAME, unsigned int SIZEOF_NAME)
11251      CRT: a gnutls_x509_crt_t structure with the new proxy cert
11252
11253      EECRT: the end entity certificate that will be issuing the proxy
11254
11255      RAW_FLAG: must be 0, or 1 if the CN is DER encoded
11256
11257      NAME: a pointer to the CN name, may be NULL (but MUST then be added
11258      later)
11259
11260      SIZEOF_NAME: holds the size of 'name'
11261
11262      This function will set the subject in 'crt' to the end entity's
11263      'eecrt' subject name, and add a single Common Name component 'name'
11264      of size 'sizeof_name' .  This corresponds to the required proxy
11265      certificate naming style.  Note that if 'name' is 'NULL' , you MUST
11266      set it later by using 'gnutls_x509_crt_set_dn_by_oid()' or similar.
11267
11268      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11269      otherwise a negative error value.
11270
11271 gnutls_x509_crt_set_serial
11272 --------------------------
11273
11274  -- Function: int gnutls_x509_crt_set_serial (gnutls_x509_crt_t CERT,
11275           const void * SERIAL, size_t SERIAL_SIZE)
11276      CERT: a certificate of type 'gnutls_x509_crt_t'
11277
11278      SERIAL: The serial number
11279
11280      SERIAL_SIZE: Holds the size of the serial field.
11281
11282      This function will set the X.509 certificate's serial number.
11283      While the serial number is an integer, it is often handled as an
11284      opaque field by several CAs.  For this reason this function accepts
11285      any kind of data as a serial number.  To be consistent with the
11286      X.509/PKIX specifications the provided 'serial' should be a
11287      big-endian positive number (i.e.  it's leftmost bit should be
11288      zero).
11289
11290      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11291      otherwise a negative error value.
11292
11293 gnutls_x509_crt_set_subject_alt_name
11294 ------------------------------------
11295
11296  -- Function: int gnutls_x509_crt_set_subject_alt_name
11297           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
11298           const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS)
11299      CRT: a certificate of type 'gnutls_x509_crt_t'
11300
11301      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
11302
11303      DATA: The data to be set
11304
11305      DATA_SIZE: The size of data to be set
11306
11307      FLAGS: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND
11308      to append.
11309
11310      This function will set the subject alternative name certificate
11311      extension.  It can set the following types:
11312
11313      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11314      otherwise a negative error value.
11315
11316      *Since:* 2.6.0
11317
11318 gnutls_x509_crt_set_subject_alternative_name
11319 --------------------------------------------
11320
11321  -- Function: int gnutls_x509_crt_set_subject_alternative_name
11322           (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
11323           const char * DATA_STRING)
11324      CRT: a certificate of type 'gnutls_x509_crt_t'
11325
11326      TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
11327
11328      DATA_STRING: The data to be set, a (0) terminated string
11329
11330      This function will set the subject alternative name certificate
11331      extension.  This function assumes that data can be expressed as a
11332      null terminated string.
11333
11334      The name of the function is unfortunate since it is incosistent
11335      with 'gnutls_x509_crt_get_subject_alt_name()' .
11336
11337      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11338      otherwise a negative error value.
11339
11340 gnutls_x509_crt_set_subject_key_id
11341 ----------------------------------
11342
11343  -- Function: int gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t
11344           CERT, const void * ID, size_t ID_SIZE)
11345      CERT: a certificate of type 'gnutls_x509_crt_t'
11346
11347      ID: The key ID
11348
11349      ID_SIZE: Holds the size of the subject key ID field.
11350
11351      This function will set the X.509 certificate's subject key ID
11352      extension.
11353
11354      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11355      otherwise a negative error value.
11356
11357 gnutls_x509_crt_set_subject_unique_id
11358 -------------------------------------
11359
11360  -- Function: int gnutls_x509_crt_set_subject_unique_id
11361           (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE)
11362      CERT: a certificate of type 'gnutls_x509_crt_t'
11363
11364      ID: The unique ID
11365
11366      ID_SIZE: Holds the size of the unique ID.
11367
11368      This function will set the X.509 certificate's subject unique ID
11369      field.
11370
11371      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11372      otherwise a negative error value.
11373
11374 gnutls_x509_crt_set_version
11375 ---------------------------
11376
11377  -- Function: int gnutls_x509_crt_set_version (gnutls_x509_crt_t CRT,
11378           unsigned int VERSION)
11379      CRT: a certificate of type 'gnutls_x509_crt_t'
11380
11381      VERSION: holds the version number.  For X.509v1 certificates must
11382      be 1.
11383
11384      This function will set the version of the certificate.  This must
11385      be one for X.509 version 1, and so on.  Plain certificates without
11386      extensions must have version set to one.
11387
11388      To create well-formed certificates, you must specify version 3 if
11389      you use any certificate extensions.  Extensions are created by
11390      functions such as 'gnutls_x509_crt_set_subject_alt_name()' or
11391      'gnutls_x509_crt_set_key_usage()' .
11392
11393      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11394      otherwise a negative error value.
11395
11396 gnutls_x509_crt_sign
11397 --------------------
11398
11399  -- Function: int gnutls_x509_crt_sign (gnutls_x509_crt_t CRT,
11400           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY)
11401      CRT: a certificate of type 'gnutls_x509_crt_t'
11402
11403      ISSUER: is the certificate of the certificate issuer
11404
11405      ISSUER_KEY: holds the issuer's private key
11406
11407      This function is the same a 'gnutls_x509_crt_sign2()' with no
11408      flags, and SHA1 as the hash algorithm.
11409
11410      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11411      otherwise a negative error value.
11412
11413 gnutls_x509_crt_sign2
11414 ---------------------
11415
11416  -- Function: int gnutls_x509_crt_sign2 (gnutls_x509_crt_t CRT,
11417           gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY,
11418           gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
11419      CRT: a certificate of type 'gnutls_x509_crt_t'
11420
11421      ISSUER: is the certificate of the certificate issuer
11422
11423      ISSUER_KEY: holds the issuer's private key
11424
11425      DIG: The message digest to use, 'GNUTLS_DIG_SHA1' is a safe choice
11426
11427      FLAGS: must be 0
11428
11429      This function will sign the certificate with the issuer's private
11430      key, and will copy the issuer's information into the certificate.
11431
11432      This must be the last step in a certificate generation since all
11433      the previously set parameters are now signed.
11434
11435      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11436      otherwise a negative error value.
11437
11438 gnutls_x509_crt_verify
11439 ----------------------
11440
11441  -- Function: int gnutls_x509_crt_verify (gnutls_x509_crt_t CERT, const
11442           gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, unsigned int
11443           FLAGS, unsigned int * VERIFY)
11444      CERT: is the certificate to be verified
11445
11446      CA_LIST: is one certificate that is considered to be trusted one
11447
11448      CA_LIST_LENGTH: holds the number of CA certificate in CA_list
11449
11450      FLAGS: Flags that may be used to change the verification algorithm.
11451      Use OR of the gnutls_certificate_verify_flags enumerations.
11452
11453      VERIFY: will hold the certificate verification output.
11454
11455      This function will try to verify the given certificate and return
11456      its status.  Note that a verification error does not imply a
11457      negative return status.  In that case the 'verify' status is set.
11458
11459      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11460      otherwise a negative error value.
11461
11462 gnutls_x509_dn_deinit
11463 ---------------------
11464
11465  -- Function: void gnutls_x509_dn_deinit (gnutls_x509_dn_t DN)
11466      DN: a DN uint8_t object pointer.
11467
11468      This function deallocates the DN object as returned by
11469      'gnutls_x509_dn_import()' .
11470
11471      *Since:* 2.4.0
11472
11473 gnutls_x509_dn_export
11474 ---------------------
11475
11476  -- Function: int gnutls_x509_dn_export (gnutls_x509_dn_t DN,
11477           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
11478           OUTPUT_DATA_SIZE)
11479      DN: Holds the uint8_t DN object
11480
11481      FORMAT: the format of output params.  One of PEM or DER.
11482
11483      OUTPUT_DATA: will contain a DN PEM or DER encoded
11484
11485      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
11486      replaced by the actual size of parameters)
11487
11488      This function will export the DN to DER or PEM format.
11489
11490      If the buffer provided is not long enough to hold the output, then
11491      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
11492      will be returned.
11493
11494      If the structure is PEM encoded, it will have a header of "BEGIN
11495      NAME".
11496
11497      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11498      otherwise a negative error value.
11499
11500 gnutls_x509_dn_export2
11501 ----------------------
11502
11503  -- Function: int gnutls_x509_dn_export2 (gnutls_x509_dn_t DN,
11504           gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
11505      DN: Holds the uint8_t DN object
11506
11507      FORMAT: the format of output params.  One of PEM or DER.
11508
11509      OUT: will contain a DN PEM or DER encoded
11510
11511      This function will export the DN to DER or PEM format.
11512
11513      The output buffer is allocated using 'gnutls_malloc()' .
11514
11515      If the structure is PEM encoded, it will have a header of "BEGIN
11516      NAME".
11517
11518      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11519      otherwise a negative error value.
11520
11521      *Since:* 3.1.3
11522
11523 gnutls_x509_dn_get_rdn_ava
11524 --------------------------
11525
11526  -- Function: int gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t DN, int
11527           IRDN, int IAVA, gnutls_x509_ava_st * AVA)
11528      DN: a pointer to DN
11529
11530      IRDN: index of RDN
11531
11532      IAVA: index of AVA.
11533
11534      AVA: Pointer to structure which will hold output information.
11535
11536      Get pointers to data within the DN. The format of the 'ava'
11537      structure is shown below.
11538
11539      struct gnutls_x509_ava_st { gnutls_datum_t oid; gnutls_datum_t
11540      value; unsigned long value_tag; };
11541
11542      The X.509 distinguished name is a sequence of sequences of strings
11543      and this is what the 'irdn' and 'iava' indexes model.
11544
11545      Note that 'ava' will contain pointers into the 'dn' structure which
11546      in turns points to the original certificate.  Thus you should not
11547      modify any data or deallocate any of those.
11548
11549      This is a low-level function that requires the caller to do the
11550      value conversions when necessary (e.g.  from UCS-2).
11551
11552      *Returns:* Returns 0 on success, or an error code.
11553
11554 gnutls_x509_dn_import
11555 ---------------------
11556
11557  -- Function: int gnutls_x509_dn_import (gnutls_x509_dn_t DN, const
11558           gnutls_datum_t * DATA)
11559      DN: the structure that will hold the imported DN
11560
11561      DATA: should contain a DER encoded RDN sequence
11562
11563      This function parses an RDN sequence and stores the result to a
11564      'gnutls_x509_dn_t' structure.  The structure must have been
11565      initialized with 'gnutls_x509_dn_init()' .  You may use
11566      'gnutls_x509_dn_get_rdn_ava()' to decode the DN.
11567
11568      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11569      otherwise a negative error value.
11570
11571      *Since:* 2.4.0
11572
11573 gnutls_x509_dn_init
11574 -------------------
11575
11576  -- Function: int gnutls_x509_dn_init (gnutls_x509_dn_t * DN)
11577      DN: the object to be initialized
11578
11579      This function initializes a 'gnutls_x509_dn_t' structure.
11580
11581      The object returned must be deallocated using
11582      'gnutls_x509_dn_deinit()' .
11583
11584      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11585      otherwise a negative error value.
11586
11587      *Since:* 2.4.0
11588
11589 gnutls_x509_dn_oid_known
11590 ------------------------
11591
11592  -- Function: int gnutls_x509_dn_oid_known (const char * OID)
11593      OID: holds an Object Identifier in a null terminated string
11594
11595      This function will inform about known DN OIDs.  This is useful
11596      since functions like 'gnutls_x509_crt_set_dn_by_oid()' use the
11597      information on known OIDs to properly encode their input.  Object
11598      Identifiers that are not known are not encoded by these functions,
11599      and their input is stored directly into the ASN.1 structure.  In
11600      that case of unknown OIDs, you have the responsibility of DER
11601      encoding your data.
11602
11603      *Returns:* 1 on known OIDs and 0 otherwise.
11604
11605 gnutls_x509_dn_oid_name
11606 -----------------------
11607
11608  -- Function: const char * gnutls_x509_dn_oid_name (const char * OID,
11609           unsigned int FLAGS)
11610      OID: holds an Object Identifier in a null terminated string
11611
11612      FLAGS: 0 or GNUTLS_X509_DN_OID_*
11613
11614      This function will return the name of a known DN OID. If
11615      'GNUTLS_X509_DN_OID_RETURN_OID' is specified this function will
11616      return the given OID if no descriptive name has been found.
11617
11618      *Returns:* A null terminated string or NULL otherwise.
11619
11620      *Since:* 3.0
11621
11622 gnutls_x509_ext_deinit
11623 ----------------------
11624
11625  -- Function: void gnutls_x509_ext_deinit (gnutls_x509_ext_st * EXT)
11626      EXT: The extensions structure
11627
11628      This function will deinitialize an extensions structure.
11629
11630      *Since:* 3.3.8
11631
11632 gnutls_x509_ext_export_aia
11633 --------------------------
11634
11635  -- Function: int gnutls_x509_ext_export_aia (gnutls_x509_aia_t AIA,
11636           gnutls_datum_t * EXT)
11637      AIA: The authority info access structure
11638
11639      EXT: The DER-encoded extension data; must be freed using
11640      'gnutls_free()' .
11641
11642      This function will DER encode the Authority Information Access
11643      (AIA) extension; see RFC 5280 section 4.2.2.1 for more information
11644      on the extension.
11645
11646      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11647      otherwise a negative error value.
11648
11649      *Since:* 3.3.0
11650
11651 gnutls_x509_ext_export_authority_key_id
11652 ---------------------------------------
11653
11654  -- Function: int gnutls_x509_ext_export_authority_key_id
11655           (gnutls_x509_aki_t AKI, gnutls_datum_t * EXT)
11656      AKI: An initialized authority key identifier structure
11657
11658      EXT: The DER-encoded extension data; must be freed using
11659      'gnutls_free()' .
11660
11661      This function will convert the provided key identifier to a
11662      DER-encoded PKIX AuthorityKeyIdentifier extension.  The output data
11663      in 'ext' will be allocated using 'gnutls_malloc()' .
11664
11665      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11666      otherwise a negative error value.
11667
11668      *Since:* 3.3.0
11669
11670 gnutls_x509_ext_export_basic_constraints
11671 ----------------------------------------
11672
11673  -- Function: int gnutls_x509_ext_export_basic_constraints (unsigned int
11674           CA, int PATHLEN, gnutls_datum_t * EXT)
11675      CA: non-zero for a CA
11676
11677      PATHLEN: The path length constraint (set to -1 for no constraint)
11678
11679      EXT: The DER-encoded extension data; must be freed using
11680      'gnutls_free()' .
11681
11682      This function will convert the parameters provided to a basic
11683      constraints DER encoded extension (2.5.29.19).  The 'ext' data will
11684      be allocated using 'gnutls_malloc()' .
11685
11686      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11687      otherwise a negative error value.
11688
11689      *Since:* 3.3.0
11690
11691 gnutls_x509_ext_export_crl_dist_points
11692 --------------------------------------
11693
11694  -- Function: int gnutls_x509_ext_export_crl_dist_points
11695           (gnutls_x509_crl_dist_points_t CDP, gnutls_datum_t * EXT)
11696      CDP: A pointer to an initialized CRL distribution points structure.
11697
11698      EXT: The DER-encoded extension data; must be freed using
11699      'gnutls_free()' .
11700
11701      This function will convert the provided policies, to a certificate
11702      policy DER encoded extension (2.5.29.31).
11703
11704      The 'ext' data will be allocated using 'gnutls_malloc()' .
11705
11706      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11707      otherwise a negative error value.
11708
11709      *Since:* 3.3.0
11710
11711 gnutls_x509_ext_export_key_purposes
11712 -----------------------------------
11713
11714  -- Function: int gnutls_x509_ext_export_key_purposes
11715           (gnutls_x509_key_purposes_t P, gnutls_datum_t * EXT)
11716      P: The key purposes structure
11717
11718      EXT: The DER-encoded extension data; must be freed using
11719      'gnutls_free()' .
11720
11721      This function will convert the key purposes structure to a
11722      DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension.  The
11723      output data in 'ext' will be allocated usin 'gnutls_malloc()' .
11724
11725      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11726      otherwise a negative error value.
11727
11728      *Since:* 3.3.0
11729
11730 gnutls_x509_ext_export_key_usage
11731 --------------------------------
11732
11733  -- Function: int gnutls_x509_ext_export_key_usage (unsigned int USAGE,
11734           gnutls_datum_t * EXT)
11735      USAGE: an ORed sequence of the GNUTLS_KEY_* elements.
11736
11737      EXT: The DER-encoded extension data; must be freed using
11738      'gnutls_free()' .
11739
11740      This function will convert the keyUsage bit string to a DER encoded
11741      PKIX extension.  The 'ext' data will be allocated using
11742      'gnutls_malloc()' .
11743
11744      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11745      otherwise a negative error value.
11746
11747      *Since:* 3.3.0
11748
11749 gnutls_x509_ext_export_name_constraints
11750 ---------------------------------------
11751
11752  -- Function: int gnutls_x509_ext_export_name_constraints
11753           (gnutls_x509_name_constraints_t NC, gnutls_datum_t * EXT)
11754      NC: The nameconstraints structure
11755
11756      EXT: The DER-encoded extension data; must be freed using
11757      'gnutls_free()' .
11758
11759      This function will convert the provided name constraints structure
11760      to a DER-encoded PKIX NameConstraints (2.5.29.30) extension.  The
11761      output data in 'ext' will be allocated usin 'gnutls_malloc()' .
11762
11763      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11764      otherwise a negative error value.
11765
11766      *Since:* 3.3.0
11767
11768 gnutls_x509_ext_export_policies
11769 -------------------------------
11770
11771  -- Function: int gnutls_x509_ext_export_policies
11772           (gnutls_x509_policies_t POLICIES, gnutls_datum_t * EXT)
11773      POLICIES: A pointer to an initialized policies structure.
11774
11775      EXT: The DER-encoded extension data; must be freed using
11776      'gnutls_free()' .
11777
11778      This function will convert the provided policies, to a certificate
11779      policy DER encoded extension (2.5.29.32).
11780
11781      The 'ext' data will be allocated using 'gnutls_malloc()' .
11782
11783      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11784      otherwise a negative error value.
11785
11786      *Since:* 3.3.0
11787
11788 gnutls_x509_ext_export_private_key_usage_period
11789 -----------------------------------------------
11790
11791  -- Function: int gnutls_x509_ext_export_private_key_usage_period
11792           (time_t ACTIVATION, time_t EXPIRATION, gnutls_datum_t * EXT)
11793      ACTIVATION: The activation time
11794
11795      EXPIRATION: The expiration time
11796
11797      EXT: The DER-encoded extension data; must be freed using
11798      'gnutls_free()' .
11799
11800      This function will convert the periods provided to a private key
11801      usage DER encoded extension (2.5.29.16).  The 'ext' data will be
11802      allocated using 'gnutls_malloc()' .
11803
11804      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11805      otherwise a negative error value.
11806
11807      *Since:* 3.3.0
11808
11809 gnutls_x509_ext_export_proxy
11810 ----------------------------
11811
11812  -- Function: int gnutls_x509_ext_export_proxy (int PATHLENCONSTRAINT,
11813           const char * POLICYLANGUAGE, const char * POLICY, size_t
11814           SIZEOF_POLICY, gnutls_datum_t * EXT)
11815      PATHLENCONSTRAINT: non-negative error codes indicate maximum length
11816      of path, and negative error codes indicate that the
11817      pathLenConstraints field should not be present.
11818
11819      POLICYLANGUAGE: OID describing the language of 'policy' .
11820
11821      POLICY: uint8_t byte array with policy language, can be 'NULL'
11822
11823      SIZEOF_POLICY: size of 'policy' .
11824
11825      EXT: The DER-encoded extension data; must be freed using
11826      'gnutls_free()' .
11827
11828      This function will convert the parameters provided to a
11829      proxyCertInfo extension.
11830
11831      The 'ext' data will be allocated using 'gnutls_malloc()' .
11832
11833      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11834      otherwise a negative error value.
11835
11836      *Since:* 3.3.0
11837
11838 gnutls_x509_ext_export_subject_alt_names
11839 ----------------------------------------
11840
11841  -- Function: int gnutls_x509_ext_export_subject_alt_names
11842           (gnutls_subject_alt_names_t SANS, gnutls_datum_t * EXT)
11843      SANS: The alternative names structure
11844
11845      EXT: The DER-encoded extension data; must be freed using
11846      'gnutls_free()' .
11847
11848      This function will convert the provided alternative names structure
11849      to a DER-encoded SubjectAltName PKIX extension.  The output data in
11850      'ext' will be allocated using 'gnutls_malloc()' .
11851
11852      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11853      otherwise a negative error value.
11854
11855      *Since:* 3.3.0
11856
11857 gnutls_x509_ext_export_subject_key_id
11858 -------------------------------------
11859
11860  -- Function: int gnutls_x509_ext_export_subject_key_id (const
11861           gnutls_datum_t * ID, gnutls_datum_t * EXT)
11862      ID: The key identifier
11863
11864      EXT: The DER-encoded extension data; must be freed using
11865      'gnutls_free()' .
11866
11867      This function will convert the provided key identifier to a
11868      DER-encoded PKIX SubjectKeyIdentifier extension.  The output data
11869      in 'ext' will be allocated using 'gnutls_malloc()' .
11870
11871      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11872      otherwise a negative error value.
11873
11874      *Since:* 3.3.0
11875
11876 gnutls_x509_ext_import_aia
11877 --------------------------
11878
11879  -- Function: int gnutls_x509_ext_import_aia (const gnutls_datum_t *
11880           EXT, gnutls_x509_aia_t AIA, unsigned int FLAGS)
11881      EXT: The DER-encoded extension data
11882
11883      AIA: The authority info access structure
11884
11885      FLAGS: should be zero
11886
11887      This function extracts the Authority Information Access (AIA)
11888      extension from the provided DER-encoded data; see RFC 5280 section
11889      4.2.2.1 for more information on the extension.  The AIA extension
11890      holds a sequence of AccessDescription (AD) data.
11891
11892      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11893      otherwise a negative error value.
11894
11895      *Since:* 3.3.0
11896
11897 gnutls_x509_ext_import_authority_key_id
11898 ---------------------------------------
11899
11900  -- Function: int gnutls_x509_ext_import_authority_key_id (const
11901           gnutls_datum_t * EXT, gnutls_x509_aki_t AKI, unsigned int
11902           FLAGS)
11903      EXT: a DER encoded extension
11904
11905      AKI: An initialized authority key identifier structure
11906
11907      FLAGS: should be zero
11908
11909      This function will return the subject key ID stored in the provided
11910      AuthorityKeyIdentifier extension.
11911
11912      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11913      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
11914      present, otherwise a negative error value.
11915
11916      *Since:* 3.3.0
11917
11918 gnutls_x509_ext_import_basic_constraints
11919 ----------------------------------------
11920
11921  -- Function: int gnutls_x509_ext_import_basic_constraints (const
11922           gnutls_datum_t * EXT, unsigned int * CA, int * PATHLEN)
11923      EXT: the DER encoded extension data
11924
11925      CA: will be non zero if the CA status is true
11926
11927      PATHLEN: the path length constraint; will be set to -1 for no limit
11928
11929      This function will return the CA status and path length constraint
11930      as written in the PKIX extension 2.5.29.19.
11931
11932      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11933      otherwise a negative error value.
11934
11935      *Since:* 3.3.0
11936
11937 gnutls_x509_ext_import_crl_dist_points
11938 --------------------------------------
11939
11940  -- Function: int gnutls_x509_ext_import_crl_dist_points (const
11941           gnutls_datum_t * EXT, gnutls_x509_crl_dist_points_t CDP,
11942           unsigned int FLAGS)
11943      EXT: the DER encoded extension data
11944
11945      CDP: A pointer to an initialized CRL distribution points structure.
11946
11947      FLAGS: should be zero
11948
11949      This function will extract the CRL distribution points extension
11950      (2.5.29.31) and store it into the provided structure.
11951
11952      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11953      otherwise a negative error value.
11954
11955      *Since:* 3.3.0
11956
11957 gnutls_x509_ext_import_key_purposes
11958 -----------------------------------
11959
11960  -- Function: int gnutls_x509_ext_import_key_purposes (const
11961           gnutls_datum_t * EXT, gnutls_x509_key_purposes_t P, unsigned
11962           int FLAGS)
11963      EXT: The DER-encoded extension data
11964
11965      P: The key purposes structure
11966
11967      FLAGS: should be zero
11968
11969      This function will extract the key purposes in the provided
11970      DER-encoded ExtKeyUsageSyntax PKIX extension, to a
11971      'gnutls_x509_key_purposes_t' structure.  The structure must be
11972      initialized.
11973
11974      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
11975      otherwise a negative error value.
11976
11977      *Since:* 3.3.0
11978
11979 gnutls_x509_ext_import_key_usage
11980 --------------------------------
11981
11982  -- Function: int gnutls_x509_ext_import_key_usage (const gnutls_datum_t
11983           * EXT, unsigned int * KEY_USAGE)
11984      EXT: the DER encoded extension data
11985
11986      KEY_USAGE: where the key usage bits will be stored
11987
11988      This function will return certificate's key usage, by reading the
11989      DER data of the keyUsage X.509 extension (2.5.29.15).  The key
11990      usage value will ORed values of the: 'GNUTLS_KEY_DIGITAL_SIGNATURE'
11991      , 'GNUTLS_KEY_NON_REPUDIATION' , 'GNUTLS_KEY_KEY_ENCIPHERMENT' ,
11992      'GNUTLS_KEY_DATA_ENCIPHERMENT' , 'GNUTLS_KEY_KEY_AGREEMENT' ,
11993      'GNUTLS_KEY_KEY_CERT_SIGN' , 'GNUTLS_KEY_CRL_SIGN' ,
11994      'GNUTLS_KEY_ENCIPHER_ONLY' , 'GNUTLS_KEY_DECIPHER_ONLY' .
11995
11996      *Returns:* the certificate key usage, or a negative error code in
11997      case of parsing error.  If the certificate does not contain the
11998      keyUsage extension 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be
11999      returned.
12000
12001      *Since:* 3.3.0
12002
12003 gnutls_x509_ext_import_name_constraints
12004 ---------------------------------------
12005
12006  -- Function: int gnutls_x509_ext_import_name_constraints (const
12007           gnutls_datum_t * EXT, gnutls_x509_name_constraints_t NC,
12008           unsigned int FLAGS)
12009      EXT: a DER encoded extension
12010
12011      NC: The nameconstraints intermediate structure
12012
12013      FLAGS: zero or 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND'
12014
12015      This function will return an intermediate structure containing the
12016      name constraints of the provided NameConstraints extension.  That
12017      structure can be used in combination with
12018      'gnutls_x509_name_constraints_check()' to verify whether a server's
12019      name is in accordance with the constraints.
12020
12021      When the 'flags' is set to 'GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND' ,
12022      then if the 'nc' structure is empty this function will behave
12023      identically as if the flag was not set.  Otherwise if there are
12024      elements in the 'nc' structure then only the excluded constraints
12025      will be appended to the constraints.
12026
12027      Note that 'nc' must be initialized prior to calling this function.
12028
12029      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12030      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
12031      present, otherwise a negative error value.
12032
12033      *Since:* 3.3.0
12034
12035 gnutls_x509_ext_import_policies
12036 -------------------------------
12037
12038  -- Function: int gnutls_x509_ext_import_policies (const gnutls_datum_t
12039           * EXT, gnutls_x509_policies_t POLICIES, unsigned int FLAGS)
12040      EXT: the DER encoded extension data
12041
12042      POLICIES: A pointer to an initialized policies structures.
12043
12044      FLAGS: should be zero
12045
12046      This function will extract the certificate policy extension
12047      (2.5.29.32) and store it the provided structure.
12048
12049      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12050      otherwise a negative error value.
12051
12052      *Since:* 3.3.0
12053
12054 gnutls_x509_ext_import_private_key_usage_period
12055 -----------------------------------------------
12056
12057  -- Function: int gnutls_x509_ext_import_private_key_usage_period (const
12058           gnutls_datum_t * EXT, time_t * ACTIVATION, time_t *
12059           EXPIRATION)
12060      EXT: the DER encoded extension data
12061
12062      ACTIVATION: Will hold the activation time
12063
12064      EXPIRATION: Will hold the expiration time
12065
12066      This function will return the expiration and activation times of
12067      the private key as written in the PKIX extension 2.5.29.16.
12068
12069      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12070      otherwise a negative error value.
12071
12072      *Since:* 3.3.0
12073
12074 gnutls_x509_ext_import_proxy
12075 ----------------------------
12076
12077  -- Function: int gnutls_x509_ext_import_proxy (const gnutls_datum_t *
12078           EXT, int * PATHLEN, char ** POLICYLANGUAGE, char ** POLICY,
12079           size_t * SIZEOF_POLICY)
12080      EXT: the DER encoded extension data
12081
12082      PATHLEN: pointer to output integer indicating path length (may be
12083      NULL), non-negative error codes indicate a present
12084      pCPathLenConstraint field and the actual value, -1 indicate that
12085      the field is absent.
12086
12087      POLICYLANGUAGE: output variable with OID of policy language
12088
12089      POLICY: output variable with policy data
12090
12091      SIZEOF_POLICY: output variable size of policy data
12092
12093      This function will return the information from a proxy certificate
12094      extension.  It reads the ProxyCertInfo X.509 extension
12095      (1.3.6.1.5.5.7.1.14).  The 'policyLanguage' and 'policy' values
12096      must be deinitialized using 'gnutls_free()' after use.
12097
12098      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12099      otherwise a negative error value.
12100
12101      *Since:* 3.3.0
12102
12103 gnutls_x509_ext_import_subject_alt_names
12104 ----------------------------------------
12105
12106  -- Function: int gnutls_x509_ext_import_subject_alt_names (const
12107           gnutls_datum_t * EXT, gnutls_subject_alt_names_t SANS,
12108           unsigned int FLAGS)
12109      EXT: The DER-encoded extension data
12110
12111      SANS: The alternative names structure
12112
12113      FLAGS: should be zero
12114
12115      This function will export the alternative names in the provided
12116      DER-encoded SubjectAltName PKIX extension, to a
12117      'gnutls_subject_alt_names_t' structure.  The structure must have
12118      been initialized.
12119
12120      This function will succeed even if there no subject alternative
12121      names in the structure.
12122
12123      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12124      otherwise a negative error value.
12125
12126      *Since:* 3.3.0
12127
12128 gnutls_x509_ext_import_subject_key_id
12129 -------------------------------------
12130
12131  -- Function: int gnutls_x509_ext_import_subject_key_id (const
12132           gnutls_datum_t * EXT, gnutls_datum_t * ID)
12133      EXT: a DER encoded extension
12134
12135      ID: will contain the subject key ID
12136
12137      This function will return the subject key ID stored in the provided
12138      SubjectKeyIdentifier extension.  The ID will be allocated using
12139      'gnutls_malloc()' .
12140
12141      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12142      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
12143      present, otherwise a negative error value.
12144
12145      *Since:* 3.3.0
12146
12147 gnutls_x509_ext_print
12148 ---------------------
12149
12150  -- Function: int gnutls_x509_ext_print (gnutls_x509_ext_st * EXTS,
12151           unsigned int EXTS_SIZE, gnutls_certificate_print_formats_t
12152           FORMAT, gnutls_datum_t * OUT)
12153      EXTS: The structures to be printed
12154
12155      EXTS_SIZE: the number of available structures
12156
12157      FORMAT: Indicate the format to use
12158
12159      OUT: Newly allocated datum with null terminated string.
12160
12161      This function will pretty print X.509 certificate extensions,
12162      suitable for display to a human.
12163
12164      The output 'out' needs to be deallocated using 'gnutls_free()' .
12165
12166      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12167      otherwise a negative error value.
12168
12169 gnutls_x509_key_purpose_deinit
12170 ------------------------------
12171
12172  -- Function: void gnutls_x509_key_purpose_deinit
12173           (gnutls_x509_key_purposes_t P)
12174      P: The key purposes structure
12175
12176      This function will deinitialize an alternative names structure.
12177
12178      *Since:* 3.3.0
12179
12180 gnutls_x509_key_purpose_get
12181 ---------------------------
12182
12183  -- Function: int gnutls_x509_key_purpose_get
12184           (gnutls_x509_key_purposes_t P, unsigned IDX, gnutls_datum_t *
12185           OID)
12186      P: The key purposes structure
12187
12188      IDX: The index of the key purpose to retrieve
12189
12190      OID: Will hold the object identifier of the key purpose (to be
12191      treated as constant)
12192
12193      This function will retrieve the specified by the index key purpose
12194      in the purposes structure.  The object identifier will be a null
12195      terminated string.
12196
12197      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12198      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
12199      bounds, otherwise a negative error value.
12200
12201      *Since:* 3.3.0
12202
12203 gnutls_x509_key_purpose_init
12204 ----------------------------
12205
12206  -- Function: int gnutls_x509_key_purpose_init
12207           (gnutls_x509_key_purposes_t * P)
12208      P: The key purposes structure
12209
12210      This function will initialize an alternative names structure.
12211
12212      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12213      otherwise a negative error value.
12214
12215      *Since:* 3.3.0
12216
12217 gnutls_x509_key_purpose_set
12218 ---------------------------
12219
12220  -- Function: int gnutls_x509_key_purpose_set
12221           (gnutls_x509_key_purposes_t P, const char * OID)
12222      P: The key purposes structure
12223
12224      OID: The object identifier of the key purpose
12225
12226      This function will store the specified key purpose in the purposes
12227      structure.
12228
12229      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
12230      error value.
12231
12232      *Since:* 3.3.0
12233
12234 gnutls_x509_name_constraints_add_excluded
12235 -----------------------------------------
12236
12237  -- Function: int gnutls_x509_name_constraints_add_excluded
12238           (gnutls_x509_name_constraints_t NC,
12239           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
12240           NAME)
12241      NC: The nameconstraints structure
12242
12243      TYPE: The type of the constraints
12244
12245      NAME: The data of the constraints
12246
12247      This function will add a name constraint to the list of excluded
12248      constraints.  The constraints 'type' can be any of the following
12249      types: 'GNUTLS_SAN_DNSNAME' , 'GNUTLS_SAN_RFC822NAME' ,
12250      'GNUTLS_SAN_DN' , 'GNUTLS_SAN_URI' , 'GNUTLS_SAN_IPADDRESS' .  For
12251      the latter, an IP address in network byte order is expected,
12252      followed by its network mask (which is 4 bytes in IPv4 or 16-bytes
12253      in IPv6).
12254
12255      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12256      otherwise a negative error value.
12257
12258      *Since:* 3.3.0
12259
12260 gnutls_x509_name_constraints_add_permitted
12261 ------------------------------------------
12262
12263  -- Function: int gnutls_x509_name_constraints_add_permitted
12264           (gnutls_x509_name_constraints_t NC,
12265           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
12266           NAME)
12267      NC: The nameconstraints structure
12268
12269      TYPE: The type of the constraints
12270
12271      NAME: The data of the constraints
12272
12273      This function will add a name constraint to the list of permitted
12274      constraints.  The constraints 'type' can be any of the following
12275      types: 'GNUTLS_SAN_DNSNAME' , 'GNUTLS_SAN_RFC822NAME' ,
12276      'GNUTLS_SAN_DN' , 'GNUTLS_SAN_URI' , 'GNUTLS_SAN_IPADDRESS' .  For
12277      the latter, an IP address in network byte order is expected,
12278      followed by its network mask.
12279
12280      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12281      otherwise a negative error value.
12282
12283      *Since:* 3.3.0
12284
12285 gnutls_x509_name_constraints_check
12286 ----------------------------------
12287
12288  -- Function: unsigned gnutls_x509_name_constraints_check
12289           (gnutls_x509_name_constraints_t NC,
12290           gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t *
12291           NAME)
12292      NC: the extracted name constraints structure
12293
12294      TYPE: the type of the constraint to check (of type
12295      gnutls_x509_subject_alt_name_t)
12296
12297      NAME: the name to be checked
12298
12299      This function will check the provided name against the constraints
12300      in 'nc' using the RFC5280 rules.  Currently this function is
12301      limited to DNS names and emails (of type 'GNUTLS_SAN_DNSNAME' and
12302      'GNUTLS_SAN_RFC822NAME' ).
12303
12304      *Returns:* zero if the provided name is not acceptable, and
12305      non-zero otherwise.
12306
12307      *Since:* 3.3.0
12308
12309 gnutls_x509_name_constraints_check_crt
12310 --------------------------------------
12311
12312  -- Function: unsigned gnutls_x509_name_constraints_check_crt
12313           (gnutls_x509_name_constraints_t NC,
12314           gnutls_x509_subject_alt_name_t TYPE, gnutls_x509_crt_t CERT)
12315      NC: the extracted name constraints structure
12316
12317      TYPE: the type of the constraint to check (of type
12318      gnutls_x509_subject_alt_name_t)
12319
12320      CERT: the certificate to be checked
12321
12322      This function will check the provided certificate names against the
12323      constraints in 'nc' using the RFC5280 rules.  It will traverse all
12324      the certificate's names and alternative names.
12325
12326      Currently this function is limited to DNS names and emails (of type
12327      'GNUTLS_SAN_DNSNAME' and 'GNUTLS_SAN_RFC822NAME' ).
12328
12329      *Returns:* zero if the provided name is not acceptable, and
12330      non-zero otherwise.
12331
12332      *Since:* 3.3.0
12333
12334 gnutls_x509_name_constraints_deinit
12335 -----------------------------------
12336
12337  -- Function: void gnutls_x509_name_constraints_deinit
12338           (gnutls_x509_name_constraints_t NC)
12339      NC: The nameconstraints structure
12340
12341      This function will deinitialize a name constraints structure.
12342
12343      *Since:* 3.3.0
12344
12345 gnutls_x509_name_constraints_get_excluded
12346 -----------------------------------------
12347
12348  -- Function: int gnutls_x509_name_constraints_get_excluded
12349           (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned *
12350           TYPE, gnutls_datum_t * NAME)
12351      NC: the extracted name constraints structure
12352
12353      IDX: the index of the constraint
12354
12355      TYPE: the type of the constraint (of type
12356      gnutls_x509_subject_alt_name_t)
12357
12358      NAME: the name in the constraint (of the specific type)
12359
12360      This function will return an intermediate structure containing the
12361      name constraints of the provided CA certificate.  That structure
12362      can be used in combination with
12363      'gnutls_x509_name_constraints_check()' to verify whether a server's
12364      name is in accordance with the constraints.
12365
12366      The name should be treated as constant and valid for the lifetime
12367      of 'nc' .
12368
12369      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12370      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
12371      present, otherwise a negative error value.
12372
12373      *Since:* 3.3.0
12374
12375 gnutls_x509_name_constraints_get_permitted
12376 ------------------------------------------
12377
12378  -- Function: int gnutls_x509_name_constraints_get_permitted
12379           (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned *
12380           TYPE, gnutls_datum_t * NAME)
12381      NC: the extracted name constraints structure
12382
12383      IDX: the index of the constraint
12384
12385      TYPE: the type of the constraint (of type
12386      gnutls_x509_subject_alt_name_t)
12387
12388      NAME: the name in the constraint (of the specific type)
12389
12390      This function will return an intermediate structure containing the
12391      name constraints of the provided CA certificate.  That structure
12392      can be used in combination with
12393      'gnutls_x509_name_constraints_check()' to verify whether a server's
12394      name is in accordance with the constraints.
12395
12396      The name should be treated as constant and valid for the lifetime
12397      of 'nc' .
12398
12399      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12400      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the extension is not
12401      present, otherwise a negative error value.
12402
12403      *Since:* 3.3.0
12404
12405 gnutls_x509_name_constraints_init
12406 ---------------------------------
12407
12408  -- Function: int gnutls_x509_name_constraints_init
12409           (gnutls_x509_name_constraints_t * NC)
12410      NC: The nameconstraints structure
12411
12412      This function will initialize a name constraints structure.
12413
12414      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12415      otherwise a negative error value.
12416
12417      *Since:* 3.3.0
12418
12419 gnutls_x509_othername_to_virtual
12420 --------------------------------
12421
12422  -- Function: int gnutls_x509_othername_to_virtual (const char * OID,
12423           const gnutls_datum_t * OTHERNAME, unsigned int * VIRT_TYPE,
12424           gnutls_datum_t * VIRT)
12425      OID: The othername object identifier
12426
12427      OTHERNAME: - undescribed -
12428
12429      VIRT_TYPE: GNUTLS_SAN_OTHERNAME_XXX
12430
12431      VIRT: allocated printable data
12432
12433      This function will parse and convert the othername data to a
12434      virtual type supported by gnutls.
12435
12436      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12437      otherwise a negative error value.
12438
12439      *Since:* 3.3.8
12440
12441 gnutls_x509_policies_deinit
12442 ---------------------------
12443
12444  -- Function: void gnutls_x509_policies_deinit (gnutls_x509_policies_t
12445           POLICIES)
12446      POLICIES: The authority key identifier structure
12447
12448      This function will deinitialize an authority key identifier
12449      structure.
12450
12451      *Since:* 3.3.0
12452
12453 gnutls_x509_policies_get
12454 ------------------------
12455
12456  -- Function: int gnutls_x509_policies_get (gnutls_x509_policies_t
12457           POLICIES, unsigned int SEQ, struct gnutls_x509_policy_st *
12458           POLICY)
12459      POLICIES: The policies structure
12460
12461      SEQ: The index of the name to get
12462
12463      POLICY: Will hold the policy
12464
12465      This function will return a specific policy as stored in the
12466      'policies' structure.  The returned values should be treated as
12467      constant and valid for the lifetime of 'policies' .
12468
12469      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12470      'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' if the index is out of
12471      bounds, otherwise a negative error value.
12472
12473      *Since:* 3.3.0
12474
12475 gnutls_x509_policies_init
12476 -------------------------
12477
12478  -- Function: int gnutls_x509_policies_init (gnutls_x509_policies_t *
12479           POLICIES)
12480      POLICIES: The authority key ID structure
12481
12482      This function will initialize an authority key ID structure.
12483
12484      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12485      otherwise a negative error value.
12486
12487      *Since:* 3.3.0
12488
12489 gnutls_x509_policies_set
12490 ------------------------
12491
12492  -- Function: int gnutls_x509_policies_set (gnutls_x509_policies_t
12493           POLICIES, const struct gnutls_x509_policy_st * POLICY)
12494      POLICIES: An initialized policies structure
12495
12496      POLICY: Contains the policy to set
12497
12498      This function will store the specified policy in the provided
12499      'policies' structure.
12500
12501      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0), otherwise a negative
12502      error value.
12503
12504      *Since:* 3.3.0
12505
12506 gnutls_x509_policy_release
12507 --------------------------
12508
12509  -- Function: void gnutls_x509_policy_release (struct
12510           gnutls_x509_policy_st * POLICY)
12511      POLICY: a certificate policy
12512
12513      This function will deinitialize all memory associated with the
12514      provided 'policy' .  The policy is allocated using
12515      'gnutls_x509_crt_get_policy()' .
12516
12517      *Since:* 3.1.5
12518
12519 gnutls_x509_privkey_cpy
12520 -----------------------
12521
12522  -- Function: int gnutls_x509_privkey_cpy (gnutls_x509_privkey_t DST,
12523           gnutls_x509_privkey_t SRC)
12524      DST: The destination key, which should be initialized.
12525
12526      SRC: The source key
12527
12528      This function will copy a private key from source to destination
12529      key.  Destination has to be initialized.
12530
12531      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12532      otherwise a negative error value.
12533
12534 gnutls_x509_privkey_deinit
12535 --------------------------
12536
12537  -- Function: void gnutls_x509_privkey_deinit (gnutls_x509_privkey_t
12538           KEY)
12539      KEY: The structure to be deinitialized
12540
12541      This function will deinitialize a private key structure.
12542
12543 gnutls_x509_privkey_export
12544 --------------------------
12545
12546  -- Function: int gnutls_x509_privkey_export (gnutls_x509_privkey_t KEY,
12547           gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t *
12548           OUTPUT_DATA_SIZE)
12549      KEY: Holds the key
12550
12551      FORMAT: the format of output params.  One of PEM or DER.
12552
12553      OUTPUT_DATA: will contain a private key PEM or DER encoded
12554
12555      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
12556      replaced by the actual size of parameters)
12557
12558      This function will export the private key to a PKCS1 structure for
12559      RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
12560      the same format with the parameters used by openssl.
12561
12562      If the buffer provided is not long enough to hold the output, then
12563      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
12564      will be returned.
12565
12566      If the structure is PEM encoded, it will have a header of "BEGIN
12567      RSA PRIVATE KEY".
12568
12569      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12570      otherwise a negative error value.
12571
12572 gnutls_x509_privkey_export2
12573 ---------------------------
12574
12575  -- Function: int gnutls_x509_privkey_export2 (gnutls_x509_privkey_t
12576           KEY, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
12577      KEY: Holds the key
12578
12579      FORMAT: the format of output params.  One of PEM or DER.
12580
12581      OUT: will contain a private key PEM or DER encoded
12582
12583      This function will export the private key to a PKCS1 structure for
12584      RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
12585      the same format with the parameters used by openssl.
12586
12587      The output buffer is allocated using 'gnutls_malloc()' .
12588
12589      If the structure is PEM encoded, it will have a header of "BEGIN
12590      RSA PRIVATE KEY".
12591
12592      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12593      otherwise a negative error value.
12594
12595      Since 3.1.3
12596
12597 gnutls_x509_privkey_export2_pkcs8
12598 ---------------------------------
12599
12600  -- Function: int gnutls_x509_privkey_export2_pkcs8
12601           (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT,
12602           const char * PASSWORD, unsigned int FLAGS, gnutls_datum_t *
12603           OUT)
12604      KEY: Holds the key
12605
12606      FORMAT: the format of output params.  One of PEM or DER.
12607
12608      PASSWORD: the password that will be used to encrypt the key.
12609
12610      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
12611
12612      OUT: will contain a private key PEM or DER encoded
12613
12614      This function will export the private key to a PKCS8 structure.
12615      Both RSA and DSA keys can be exported.  For DSA keys we use PKCS
12616      '11' definitions.  If the flags do not specify the encryption
12617      cipher, then the default 3DES (PBES2) will be used.
12618
12619      The 'password' can be either ASCII or UTF-8 in the default PBES2
12620      encryption schemas, or ASCII for the PKCS12 schemas.
12621
12622      The output buffer is allocated using 'gnutls_malloc()' .
12623
12624      If the structure is PEM encoded, it will have a header of "BEGIN
12625      ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if encryption is not
12626      used.
12627
12628      *Returns:* In case of failure a negative error code will be
12629      returned, and 0 on success.
12630
12631      Since 3.1.3
12632
12633 gnutls_x509_privkey_export_dsa_raw
12634 ----------------------------------
12635
12636  -- Function: int gnutls_x509_privkey_export_dsa_raw
12637           (gnutls_x509_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t
12638           * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t *
12639           X)
12640      KEY: a structure that holds the DSA parameters
12641
12642      P: will hold the p
12643
12644      Q: will hold the q
12645
12646      G: will hold the g
12647
12648      Y: will hold the y
12649
12650      X: will hold the x
12651
12652      This function will export the DSA private key's parameters found in
12653      the given structure.  The new parameters will be allocated using
12654      'gnutls_malloc()' and will be stored in the appropriate datum.
12655
12656      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12657      otherwise a negative error value.
12658
12659 gnutls_x509_privkey_export_ecc_raw
12660 ----------------------------------
12661
12662  -- Function: int gnutls_x509_privkey_export_ecc_raw
12663           (gnutls_x509_privkey_t KEY, gnutls_ecc_curve_t * CURVE,
12664           gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K)
12665      KEY: a structure that holds the rsa parameters
12666
12667      CURVE: will hold the curve
12668
12669      X: will hold the x coordinate
12670
12671      Y: will hold the y coordinate
12672
12673      K: will hold the private key
12674
12675      This function will export the ECC private key's parameters found in
12676      the given structure.  The new parameters will be allocated using
12677      'gnutls_malloc()' and will be stored in the appropriate datum.
12678
12679      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12680      otherwise a negative error value.
12681
12682      *Since:* 3.0
12683
12684 gnutls_x509_privkey_export_pkcs8
12685 --------------------------------
12686
12687  -- Function: int gnutls_x509_privkey_export_pkcs8
12688           (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT,
12689           const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA,
12690           size_t * OUTPUT_DATA_SIZE)
12691      KEY: Holds the key
12692
12693      FORMAT: the format of output params.  One of PEM or DER.
12694
12695      PASSWORD: the password that will be used to encrypt the key.
12696
12697      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
12698
12699      OUTPUT_DATA: will contain a private key PEM or DER encoded
12700
12701      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
12702      replaced by the actual size of parameters)
12703
12704      This function will export the private key to a PKCS8 structure.
12705      Both RSA and DSA keys can be exported.  For DSA keys we use PKCS
12706      '11' definitions.  If the flags do not specify the encryption
12707      cipher, then the default 3DES (PBES2) will be used.
12708
12709      The 'password' can be either ASCII or UTF-8 in the default PBES2
12710      encryption schemas, or ASCII for the PKCS12 schemas.
12711
12712      If the buffer provided is not long enough to hold the output, then
12713      *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
12714      be returned.
12715
12716      If the structure is PEM encoded, it will have a header of "BEGIN
12717      ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if encryption is not
12718      used.
12719
12720      *Returns:* In case of failure a negative error code will be
12721      returned, and 0 on success.
12722
12723 gnutls_x509_privkey_export_rsa_raw
12724 ----------------------------------
12725
12726  -- Function: int gnutls_x509_privkey_export_rsa_raw
12727           (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t
12728           * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t *
12729           Q, gnutls_datum_t * U)
12730      KEY: a structure that holds the rsa parameters
12731
12732      M: will hold the modulus
12733
12734      E: will hold the public exponent
12735
12736      D: will hold the private exponent
12737
12738      P: will hold the first prime (p)
12739
12740      Q: will hold the second prime (q)
12741
12742      U: will hold the coefficient
12743
12744      This function will export the RSA private key's parameters found in
12745      the given structure.  The new parameters will be allocated using
12746      'gnutls_malloc()' and will be stored in the appropriate datum.
12747
12748      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12749      otherwise a negative error value.
12750
12751 gnutls_x509_privkey_export_rsa_raw2
12752 -----------------------------------
12753
12754  -- Function: int gnutls_x509_privkey_export_rsa_raw2
12755           (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t
12756           * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t *
12757           Q, gnutls_datum_t * U, gnutls_datum_t * E1, gnutls_datum_t *
12758           E2)
12759      KEY: a structure that holds the rsa parameters
12760
12761      M: will hold the modulus
12762
12763      E: will hold the public exponent
12764
12765      D: will hold the private exponent
12766
12767      P: will hold the first prime (p)
12768
12769      Q: will hold the second prime (q)
12770
12771      U: will hold the coefficient
12772
12773      E1: will hold e1 = d mod (p-1)
12774
12775      E2: will hold e2 = d mod (q-1)
12776
12777      This function will export the RSA private key's parameters found in
12778      the given structure.  The new parameters will be allocated using
12779      'gnutls_malloc()' and will be stored in the appropriate datum.
12780
12781      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12782      otherwise a negative error value.
12783
12784      *Since:* 2.12.0
12785
12786 gnutls_x509_privkey_fix
12787 -----------------------
12788
12789  -- Function: int gnutls_x509_privkey_fix (gnutls_x509_privkey_t KEY)
12790      KEY: Holds the key
12791
12792      This function will recalculate the secondary parameters in a key.
12793      In RSA keys, this can be the coefficient and exponent1,2.
12794
12795      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12796      otherwise a negative error value.
12797
12798 gnutls_x509_privkey_generate
12799 ----------------------------
12800
12801  -- Function: int gnutls_x509_privkey_generate (gnutls_x509_privkey_t
12802           KEY, gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned
12803           int FLAGS)
12804      KEY: should contain a 'gnutls_x509_privkey_t' structure
12805
12806      ALGO: is one of the algorithms in 'gnutls_pk_algorithm_t' .
12807
12808      BITS: the size of the modulus
12809
12810      FLAGS: unused for now.  Must be 0.
12811
12812      This function will generate a random private key.  Note that this
12813      function must be called on an empty private key.
12814
12815      Note that when generating an elliptic curve key, the curve can be
12816      substituted in the place of the bits parameter using the
12817      'GNUTLS_CURVE_TO_BITS()' macro.
12818
12819      For DSA keys, if the subgroup size needs to be specified check the
12820      'GNUTLS_SUBGROUP_TO_BITS()' macro.
12821
12822      Do not set the number of bits directly, use
12823      'gnutls_sec_param_to_pk_bits()' .
12824
12825      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12826      otherwise a negative error value.
12827
12828 gnutls_x509_privkey_get_key_id
12829 ------------------------------
12830
12831  -- Function: int gnutls_x509_privkey_get_key_id (gnutls_x509_privkey_t
12832           KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
12833           OUTPUT_DATA_SIZE)
12834      KEY: Holds the key
12835
12836      FLAGS: should be 0 for now
12837
12838      OUTPUT_DATA: will contain the key ID
12839
12840      OUTPUT_DATA_SIZE: holds the size of output_data (and will be
12841      replaced by the actual size of parameters)
12842
12843      This function will return a unique ID that depends on the public
12844      key parameters.  This ID can be used in checking whether a
12845      certificate corresponds to the given key.
12846
12847      If the buffer provided is not long enough to hold the output, then
12848      * 'output_data_size' is updated and 'GNUTLS_E_SHORT_MEMORY_BUFFER'
12849      will be returned.  The output will normally be a SHA-1 hash output,
12850      which is 20 bytes.
12851
12852      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12853      otherwise a negative error value.
12854
12855 gnutls_x509_privkey_get_pk_algorithm
12856 ------------------------------------
12857
12858  -- Function: int gnutls_x509_privkey_get_pk_algorithm
12859           (gnutls_x509_privkey_t KEY)
12860      KEY: should contain a 'gnutls_x509_privkey_t' structure
12861
12862      This function will return the public key algorithm of a private
12863      key.
12864
12865      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
12866      success, or a negative error code on error.
12867
12868 gnutls_x509_privkey_get_pk_algorithm2
12869 -------------------------------------
12870
12871  -- Function: int gnutls_x509_privkey_get_pk_algorithm2
12872           (gnutls_x509_privkey_t KEY, unsigned int * BITS)
12873      KEY: should contain a 'gnutls_x509_privkey_t' structure
12874
12875      BITS: The number of bits in the public key algorithm
12876
12877      This function will return the public key algorithm of a private
12878      key.
12879
12880      *Returns:* a member of the 'gnutls_pk_algorithm_t' enumeration on
12881      success, or a negative error code on error.
12882
12883 gnutls_x509_privkey_import
12884 --------------------------
12885
12886  -- Function: int gnutls_x509_privkey_import (gnutls_x509_privkey_t KEY,
12887           const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)
12888      KEY: The structure to store the parsed key
12889
12890      DATA: The DER or PEM encoded certificate.
12891
12892      FORMAT: One of DER or PEM
12893
12894      This function will convert the given DER or PEM encoded key to the
12895      native 'gnutls_x509_privkey_t' format.  The output will be stored
12896      in 'key' .
12897
12898      If the key is PEM encoded it should have a header that contains
12899      "PRIVATE KEY". Note that this function falls back to PKCS '8'
12900      decoding without password, if the default format fails to import.
12901
12902      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12903      otherwise a negative error value.
12904
12905 gnutls_x509_privkey_import2
12906 ---------------------------
12907
12908  -- Function: int gnutls_x509_privkey_import2 (gnutls_x509_privkey_t
12909           KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t
12910           FORMAT, const char * PASSWORD, unsigned int FLAGS)
12911      KEY: The structure to store the parsed key
12912
12913      DATA: The DER or PEM encoded key.
12914
12915      FORMAT: One of DER or PEM
12916
12917      PASSWORD: A password (optional)
12918
12919      FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
12920
12921      This function will import the given DER or PEM encoded key, to the
12922      native 'gnutls_x509_privkey_t' format, irrespective of the input
12923      format.  The input format is auto-detected.
12924
12925      The supported formats are basic unencrypted key, PKCS8, PKCS12, and
12926      the openssl format.
12927
12928      If the provided key is encrypted but no password was given, then
12929      'GNUTLS_E_DECRYPTION_FAILED' is returned.
12930
12931      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12932      otherwise a negative error value.
12933
12934 gnutls_x509_privkey_import_dsa_raw
12935 ----------------------------------
12936
12937  -- Function: int gnutls_x509_privkey_import_dsa_raw
12938           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * P, const
12939           gnutls_datum_t * Q, const gnutls_datum_t * G, const
12940           gnutls_datum_t * Y, const gnutls_datum_t * X)
12941      KEY: The structure to store the parsed key
12942
12943      P: holds the p
12944
12945      Q: holds the q
12946
12947      G: holds the g
12948
12949      Y: holds the y
12950
12951      X: holds the x
12952
12953      This function will convert the given DSA raw parameters to the
12954      native 'gnutls_x509_privkey_t' format.  The output will be stored
12955      in 'key' .
12956
12957      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12958      otherwise a negative error value.
12959
12960 gnutls_x509_privkey_import_ecc_raw
12961 ----------------------------------
12962
12963  -- Function: int gnutls_x509_privkey_import_ecc_raw
12964           (gnutls_x509_privkey_t KEY, gnutls_ecc_curve_t CURVE, const
12965           gnutls_datum_t * X, const gnutls_datum_t * Y, const
12966           gnutls_datum_t * K)
12967      KEY: The structure to store the parsed key
12968
12969      CURVE: holds the curve
12970
12971      X: holds the x
12972
12973      Y: holds the y
12974
12975      K: holds the k
12976
12977      This function will convert the given elliptic curve parameters to
12978      the native 'gnutls_x509_privkey_t' format.  The output will be
12979      stored in 'key' .
12980
12981      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
12982      otherwise a negative error value.
12983
12984      *Since:* 3.0
12985
12986 gnutls_x509_privkey_import_openssl
12987 ----------------------------------
12988
12989  -- Function: int gnutls_x509_privkey_import_openssl
12990           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, const
12991           char * PASSWORD)
12992      KEY: The structure to store the parsed key
12993
12994      DATA: The DER or PEM encoded key.
12995
12996      PASSWORD: the password to decrypt the key (if it is encrypted).
12997
12998      This function will convert the given PEM encrypted to the native
12999      gnutls_x509_privkey_t format.  The output will be stored in 'key' .
13000
13001      The 'password' should be in ASCII. If the password is not provided
13002      or wrong then 'GNUTLS_E_DECRYPTION_FAILED' will be returned.
13003
13004      If the Certificate is PEM encoded it should have a header of
13005      "PRIVATE KEY" and the "DEK-Info" header.
13006
13007      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13008      otherwise a negative error value.
13009
13010 gnutls_x509_privkey_import_pkcs8
13011 --------------------------------
13012
13013  -- Function: int gnutls_x509_privkey_import_pkcs8
13014           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA,
13015           gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned
13016           int FLAGS)
13017      KEY: The structure to store the parsed key
13018
13019      DATA: The DER or PEM encoded key.
13020
13021      FORMAT: One of DER or PEM
13022
13023      PASSWORD: the password to decrypt the key (if it is encrypted).
13024
13025      FLAGS: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
13026
13027      This function will convert the given DER or PEM encoded PKCS8 2.0
13028      encrypted key to the native gnutls_x509_privkey_t format.  The
13029      output will be stored in 'key' .  Both RSA and DSA keys can be
13030      imported, and flags can only be used to indicate an unencrypted
13031      key.
13032
13033      The 'password' can be either ASCII or UTF-8 in the default PBES2
13034      encryption schemas, or ASCII for the PKCS12 schemas.
13035
13036      If the Certificate is PEM encoded it should have a header of
13037      "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to specify
13038      the flags if the key is DER encoded, since in that case the
13039      encryption status cannot be auto-detected.
13040
13041      If the 'GNUTLS_PKCS_PLAIN' flag is specified and the supplied data
13042      are encrypted then 'GNUTLS_E_DECRYPTION_FAILED' is returned.
13043
13044      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13045      otherwise a negative error value.
13046
13047 gnutls_x509_privkey_import_rsa_raw
13048 ----------------------------------
13049
13050  -- Function: int gnutls_x509_privkey_import_rsa_raw
13051           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * M, const
13052           gnutls_datum_t * E, const gnutls_datum_t * D, const
13053           gnutls_datum_t * P, const gnutls_datum_t * Q, const
13054           gnutls_datum_t * U)
13055      KEY: The structure to store the parsed key
13056
13057      M: holds the modulus
13058
13059      E: holds the public exponent
13060
13061      D: holds the private exponent
13062
13063      P: holds the first prime (p)
13064
13065      Q: holds the second prime (q)
13066
13067      U: holds the coefficient
13068
13069      This function will convert the given RSA raw parameters to the
13070      native 'gnutls_x509_privkey_t' format.  The output will be stored
13071      in 'key' .
13072
13073      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13074      otherwise a negative error value.
13075
13076 gnutls_x509_privkey_import_rsa_raw2
13077 -----------------------------------
13078
13079  -- Function: int gnutls_x509_privkey_import_rsa_raw2
13080           (gnutls_x509_privkey_t KEY, const gnutls_datum_t * M, const
13081           gnutls_datum_t * E, const gnutls_datum_t * D, const
13082           gnutls_datum_t * P, const gnutls_datum_t * Q, const
13083           gnutls_datum_t * U, const gnutls_datum_t * E1, const
13084           gnutls_datum_t * E2)
13085      KEY: The structure to store the parsed key
13086
13087      M: holds the modulus
13088
13089      E: holds the public exponent
13090
13091      D: holds the private exponent
13092
13093      P: holds the first prime (p)
13094
13095      Q: holds the second prime (q)
13096
13097      U: holds the coefficient (optional)
13098
13099      E1: holds e1 = d mod (p-1) (optional)
13100
13101      E2: holds e2 = d mod (q-1) (optional)
13102
13103      This function will convert the given RSA raw parameters to the
13104      native 'gnutls_x509_privkey_t' format.  The output will be stored
13105      in 'key' .
13106
13107      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13108      otherwise a negative error value.
13109
13110 gnutls_x509_privkey_init
13111 ------------------------
13112
13113  -- Function: int gnutls_x509_privkey_init (gnutls_x509_privkey_t * KEY)
13114      KEY: The structure to be initialized
13115
13116      This function will initialize an private key structure.
13117
13118      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13119      otherwise a negative error value.
13120
13121 gnutls_x509_privkey_sec_param
13122 -----------------------------
13123
13124  -- Function: gnutls_sec_param_t gnutls_x509_privkey_sec_param
13125           (gnutls_x509_privkey_t KEY)
13126      KEY: a key structure
13127
13128      This function will return the security parameter appropriate with
13129      this private key.
13130
13131      *Returns:* On success, a valid security parameter is returned
13132      otherwise 'GNUTLS_SEC_PARAM_UNKNOWN' is returned.
13133
13134      *Since:* 2.12.0
13135
13136 gnutls_x509_privkey_verify_params
13137 ---------------------------------
13138
13139  -- Function: int gnutls_x509_privkey_verify_params
13140           (gnutls_x509_privkey_t KEY)
13141      KEY: should contain a 'gnutls_x509_privkey_t' structure
13142
13143      This function will verify the private key parameters.
13144
13145      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13146      otherwise a negative error value.
13147
13148 gnutls_x509_rdn_get
13149 -------------------
13150
13151  -- Function: int gnutls_x509_rdn_get (const gnutls_datum_t * IDN, char
13152           * BUF, size_t * BUF_SIZE)
13153      IDN: should contain a DER encoded RDN sequence
13154
13155      BUF: a pointer to a structure to hold the peer's name
13156
13157      BUF_SIZE: holds the size of 'buf'
13158
13159      This function will return the name of the given RDN sequence.  The
13160      name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
13161      RFC4514.
13162
13163      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
13164      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
13165      updated if the provided buffer is not long enough, otherwise a
13166      negative error value.
13167
13168 gnutls_x509_rdn_get_by_oid
13169 --------------------------
13170
13171  -- Function: int gnutls_x509_rdn_get_by_oid (const gnutls_datum_t *
13172           IDN, const char * OID, int INDX, unsigned int RAW_FLAG, void *
13173           BUF, size_t * BUF_SIZE)
13174      IDN: should contain a DER encoded RDN sequence
13175
13176      OID: an Object Identifier
13177
13178      INDX: In case multiple same OIDs exist in the RDN indicates which
13179      to send.  Use 0 for the first one.
13180
13181      RAW_FLAG: If non-zero then the raw DER data are returned.
13182
13183      BUF: a pointer to a structure to hold the peer's name
13184
13185      BUF_SIZE: holds the size of 'buf'
13186
13187      This function will return the name of the given Object identifier,
13188      of the RDN sequence.  The name will be encoded using the rules from
13189      RFC4514.
13190
13191      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
13192      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
13193      updated if the provided buffer is not long enough, otherwise a
13194      negative error value.
13195
13196 gnutls_x509_rdn_get_oid
13197 -----------------------
13198
13199  -- Function: int gnutls_x509_rdn_get_oid (const gnutls_datum_t * IDN,
13200           int INDX, void * BUF, size_t * BUF_SIZE)
13201      IDN: should contain a DER encoded RDN sequence
13202
13203      INDX: Indicates which OID to return.  Use 0 for the first one.
13204
13205      BUF: a pointer to a structure to hold the peer's name OID
13206
13207      BUF_SIZE: holds the size of 'buf'
13208
13209      This function will return the specified Object identifier, of the
13210      RDN sequence.
13211
13212      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or
13213      'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and * 'buf_size' is
13214      updated if the provided buffer is not long enough, otherwise a
13215      negative error value.
13216
13217      *Since:* 2.4.0
13218
13219 gnutls_x509_trust_list_add_cas
13220 ------------------------------
13221
13222  -- Function: int gnutls_x509_trust_list_add_cas
13223           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
13224           CLIST, unsigned CLIST_SIZE, unsigned int FLAGS)
13225      LIST: The structure of the list
13226
13227      CLIST: A list of CAs
13228
13229      CLIST_SIZE: The length of the CA list
13230
13231      FLAGS: should be 0 or an or'ed sequence of 'GNUTLS_TL' options.
13232
13233      This function will add the given certificate authorities to the
13234      trusted list.  The list of CAs must not be deinitialized during
13235      this structure's lifetime.
13236
13237      If the flag 'GNUTLS_TL_NO_DUPLICATES' is specified, then the
13238      provided 'clist' entries that are duplicates will not be added to
13239      the list and will be deinitialized.
13240
13241      *Returns:* The number of added elements is returned.
13242
13243      *Since:* 3.0.0
13244
13245 gnutls_x509_trust_list_add_crls
13246 -------------------------------
13247
13248  -- Function: int gnutls_x509_trust_list_add_crls
13249           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crl_t *
13250           CRL_LIST, int CRL_SIZE, unsigned int FLAGS, unsigned int
13251           VERIFICATION_FLAGS)
13252      LIST: The structure of the list
13253
13254      CRL_LIST: A list of CRLs
13255
13256      CRL_SIZE: The length of the CRL list
13257
13258      FLAGS: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified
13259      before being added.
13260
13261      VERIFICATION_FLAGS: gnutls_certificate_verify_flags if flags
13262      specifies GNUTLS_TL_VERIFY_CRL
13263
13264      This function will add the given certificate revocation lists to
13265      the trusted list.  The list of CRLs must not be deinitialized
13266      during this structure's lifetime.
13267
13268      This function must be called after
13269      'gnutls_x509_trust_list_add_cas()' to allow verifying the CRLs for
13270      validity.  If the flag 'GNUTLS_TL_NO_DUPLICATES' is given, then any
13271      provided CRLs that are a duplicate, will be deinitialized and not
13272      added to the list (that assumes that
13273      'gnutls_x509_trust_list_deinit()' will be called with all=1).
13274
13275      *Returns:* The number of added elements is returned.
13276
13277      *Since:* 3.0
13278
13279 gnutls_x509_trust_list_add_named_crt
13280 ------------------------------------
13281
13282  -- Function: int gnutls_x509_trust_list_add_named_crt
13283           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
13284           void * NAME, size_t NAME_SIZE, unsigned int FLAGS)
13285      LIST: The structure of the list
13286
13287      CERT: A certificate
13288
13289      NAME: An identifier for the certificate
13290
13291      NAME_SIZE: The size of the identifier
13292
13293      FLAGS: should be 0.
13294
13295      This function will add the given certificate to the trusted list
13296      and associate it with a name.  The certificate will not be be used
13297      for verification with 'gnutls_x509_trust_list_verify_crt()' but
13298      only with 'gnutls_x509_trust_list_verify_named_crt()' .
13299
13300      In principle this function can be used to set individual "server"
13301      certificates that are trusted by the user for that specific server
13302      but for no other purposes.
13303
13304      The certificate must not be deinitialized during the lifetime of
13305      the trusted list.
13306
13307      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13308      otherwise a negative error value.
13309
13310      *Since:* 3.0.0
13311
13312 gnutls_x509_trust_list_add_system_trust
13313 ---------------------------------------
13314
13315  -- Function: int gnutls_x509_trust_list_add_system_trust
13316           (gnutls_x509_trust_list_t LIST, unsigned int TL_FLAGS,
13317           unsigned int TL_VFLAGS)
13318      LIST: The structure of the list
13319
13320      TL_FLAGS: GNUTLS_TL_*
13321
13322      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
13323      GNUTLS_TL_VERIFY_CRL
13324
13325      This function adds the system's default trusted certificate
13326      authorities to the trusted list.  Note that on unsupported systems
13327      this function returns 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .
13328
13329      This function implies the flag 'GNUTLS_TL_NO_DUPLICATES' .
13330
13331      *Returns:* The number of added elements or a negative error code on
13332      error.
13333
13334      *Since:* 3.1
13335
13336 gnutls_x509_trust_list_add_trust_dir
13337 ------------------------------------
13338
13339  -- Function: int gnutls_x509_trust_list_add_trust_dir
13340           (gnutls_x509_trust_list_t LIST, const char * CA_DIR, const
13341           char * CRL_DIR, gnutls_x509_crt_fmt_t TYPE, unsigned int
13342           TL_FLAGS, unsigned int TL_VFLAGS)
13343      LIST: The structure of the list
13344
13345      CA_DIR: A directory containing the CAs (optional)
13346
13347      CRL_DIR: A directory containing a list of CRLs (optional)
13348
13349      TYPE: The format of the certificates
13350
13351      TL_FLAGS: GNUTLS_TL_*
13352
13353      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
13354      GNUTLS_TL_VERIFY_CRL
13355
13356      This function will add the given certificate authorities to the
13357      trusted list.  Only directories are accepted by this function.
13358
13359      *Returns:* The number of added elements is returned.
13360
13361      *Since:* 3.3.6
13362
13363 gnutls_x509_trust_list_add_trust_file
13364 -------------------------------------
13365
13366  -- Function: int gnutls_x509_trust_list_add_trust_file
13367           (gnutls_x509_trust_list_t LIST, const char * CA_FILE, const
13368           char * CRL_FILE, gnutls_x509_crt_fmt_t TYPE, unsigned int
13369           TL_FLAGS, unsigned int TL_VFLAGS)
13370      LIST: The structure of the list
13371
13372      CA_FILE: A file containing a list of CAs (optional)
13373
13374      CRL_FILE: A file containing a list of CRLs (optional)
13375
13376      TYPE: The format of the certificates
13377
13378      TL_FLAGS: GNUTLS_TL_*
13379
13380      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
13381      GNUTLS_TL_VERIFY_CRL
13382
13383      This function will add the given certificate authorities to the
13384      trusted list.  PKCS '11' URLs are also accepted, instead of files,
13385      by this function.  A PKCS '11' URL implies a trust database (a
13386      specially marked module in p11-kit); the URL "pkcs11:" implies all
13387      trust databases in the system.  Only a single URL specifying trust
13388      databases can be set; they cannot be stacked with multiple calls.
13389
13390      *Returns:* The number of added elements is returned.
13391
13392      *Since:* 3.1
13393
13394 gnutls_x509_trust_list_add_trust_mem
13395 ------------------------------------
13396
13397  -- Function: int gnutls_x509_trust_list_add_trust_mem
13398           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
13399           const gnutls_datum_t * CRLS, gnutls_x509_crt_fmt_t TYPE,
13400           unsigned int TL_FLAGS, unsigned int TL_VFLAGS)
13401      LIST: The structure of the list
13402
13403      CAS: A buffer containing a list of CAs (optional)
13404
13405      CRLS: A buffer containing a list of CRLs (optional)
13406
13407      TYPE: The format of the certificates
13408
13409      TL_FLAGS: GNUTLS_TL_*
13410
13411      TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
13412      GNUTLS_TL_VERIFY_CRL
13413
13414      This function will add the given certificate authorities to the
13415      trusted list.
13416
13417      *Returns:* The number of added elements is returned.
13418
13419      *Since:* 3.1
13420
13421 gnutls_x509_trust_list_deinit
13422 -----------------------------
13423
13424  -- Function: void gnutls_x509_trust_list_deinit
13425           (gnutls_x509_trust_list_t LIST, unsigned int ALL)
13426      LIST: The structure to be deinitialized
13427
13428      ALL: if non-zero it will deinitialize all the certificates and CRLs
13429      contained in the structure.
13430
13431      This function will deinitialize a trust list.  Note that the 'all'
13432      flag should be typically non-zero unless you have specified your
13433      certificates using 'gnutls_x509_trust_list_add_cas()' and you want
13434      to prevent them from being deinitialized by this function.
13435
13436      *Since:* 3.0.0
13437
13438 gnutls_x509_trust_list_get_issuer
13439 ---------------------------------
13440
13441  -- Function: int gnutls_x509_trust_list_get_issuer
13442           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT,
13443           gnutls_x509_crt_t * ISSUER, unsigned int FLAGS)
13444      LIST: The structure of the list
13445
13446      CERT: is the certificate to find issuer for
13447
13448      ISSUER: Will hold the issuer if any.  Should be treated as
13449      constant.
13450
13451      FLAGS: Use zero or 'GNUTLS_TL_GET_COPY'
13452
13453      This function will find the issuer of the given certificate.  If
13454      the flag 'GNUTLS_TL_GET_COPY' is specified a copy of the issuer
13455      will be returned which must be freed using
13456      'gnutls_x509_crt_deinit()' .  Note that the flag
13457      'GNUTLS_TL_GET_COPY' is required for this function to work with
13458      PKCS '11' trust lists in a thread-safe way.
13459
13460      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13461      otherwise a negative error value.
13462
13463      *Since:* 3.0
13464
13465 gnutls_x509_trust_list_init
13466 ---------------------------
13467
13468  -- Function: int gnutls_x509_trust_list_init (gnutls_x509_trust_list_t
13469           * LIST, unsigned int SIZE)
13470      LIST: The structure to be initialized
13471
13472      SIZE: The size of the internal hash table.  Use (0) for default
13473      size.
13474
13475      This function will initialize an X.509 trust list structure.
13476
13477      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13478      otherwise a negative error value.
13479
13480      *Since:* 3.0.0
13481
13482 gnutls_x509_trust_list_remove_cas
13483 ---------------------------------
13484
13485  -- Function: int gnutls_x509_trust_list_remove_cas
13486           (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
13487           CLIST, int CLIST_SIZE)
13488      LIST: The structure of the list
13489
13490      CLIST: A list of CAs
13491
13492      CLIST_SIZE: The length of the CA list
13493
13494      This function will remove the given certificate authorities from
13495      the trusted list.
13496
13497      Note that this function can accept certificates and authorities not
13498      yet known.  In that case they will be kept in a separate black list
13499      that will be used during certificate verification.  Unlike
13500      'gnutls_x509_trust_list_add_cas()' there is no deinitialization
13501      restriction for certificate list provided in this function.
13502
13503      *Returns:* The number of removed elements is returned.
13504
13505      *Since:* 3.1.10
13506
13507 gnutls_x509_trust_list_remove_trust_file
13508 ----------------------------------------
13509
13510  -- Function: int gnutls_x509_trust_list_remove_trust_file
13511           (gnutls_x509_trust_list_t LIST, const char * CA_FILE,
13512           gnutls_x509_crt_fmt_t TYPE)
13513      LIST: The structure of the list
13514
13515      CA_FILE: A file containing a list of CAs
13516
13517      TYPE: The format of the certificates
13518
13519      This function will remove the given certificate authorities from
13520      the trusted list, and add them into a black list when needed.  PKCS
13521      11 URLs are also accepted, instead of files, by this function.
13522
13523      See also 'gnutls_x509_trust_list_remove_cas()' .
13524
13525      *Returns:* The number of added elements is returned.
13526
13527      *Since:* 3.1.10
13528
13529 gnutls_x509_trust_list_remove_trust_mem
13530 ---------------------------------------
13531
13532  -- Function: int gnutls_x509_trust_list_remove_trust_mem
13533           (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
13534           gnutls_x509_crt_fmt_t TYPE)
13535      LIST: The structure of the list
13536
13537      CAS: A buffer containing a list of CAs (optional)
13538
13539      TYPE: The format of the certificates
13540
13541      This function will remove the provided certificate authorities from
13542      the trusted list, and add them into a black list when needed.
13543
13544      See also 'gnutls_x509_trust_list_remove_cas()' .
13545
13546      *Returns:* The number of removed elements is returned.
13547
13548      *Since:* 3.1.10
13549
13550 gnutls_x509_trust_list_verify_crt
13551 ---------------------------------
13552
13553  -- Function: int gnutls_x509_trust_list_verify_crt
13554           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
13555           unsigned int CERT_LIST_SIZE, unsigned int FLAGS, unsigned int
13556           * VOUTPUT, gnutls_verify_output_function FUNC)
13557      LIST: The structure of the list
13558
13559      CERT_LIST: is the certificate list to be verified
13560
13561      CERT_LIST_SIZE: is the certificate list size
13562
13563      FLAGS: Flags that may be used to change the verification algorithm.
13564      Use OR of the gnutls_certificate_verify_flags enumerations.
13565
13566      VOUTPUT: will hold the certificate verification output.
13567
13568      FUNC: If non-null will be called on each chain element verification
13569      with the output.
13570
13571      This function will try to verify the given certificate and return
13572      its status.  The 'verify' parameter will hold an OR'ed sequence of
13573      'gnutls_certificate_status_t' flags.
13574
13575      Additionally a certificate verification profile can be specified
13576      from the ones in 'gnutls_certificate_verification_profiles_t' by
13577      ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
13578      verification flags.
13579
13580      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13581      otherwise a negative error value.
13582
13583      *Since:* 3.0
13584
13585 gnutls_x509_trust_list_verify_crt2
13586 ----------------------------------
13587
13588  -- Function: int gnutls_x509_trust_list_verify_crt2
13589           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
13590           unsigned int CERT_LIST_SIZE, gnutls_typed_vdata_st * DATA,
13591           unsigned int ELEMENTS, unsigned int FLAGS, unsigned int *
13592           VOUTPUT, gnutls_verify_output_function FUNC)
13593      LIST: The structure of the list
13594
13595      CERT_LIST: is the certificate list to be verified
13596
13597      CERT_LIST_SIZE: is the certificate list size
13598
13599      DATA: an array of typed data
13600
13601      ELEMENTS: the number of data elements
13602
13603      FLAGS: Flags that may be used to change the verification algorithm.
13604      Use OR of the gnutls_certificate_verify_flags enumerations.
13605
13606      VOUTPUT: will hold the certificate verification output.
13607
13608      FUNC: If non-null will be called on each chain element verification
13609      with the output.
13610
13611      This function will try to verify the given certificate and return
13612      its status.  The 'verify' parameter will hold an OR'ed sequence of
13613      'gnutls_certificate_status_t' flags.
13614
13615      Additionally a certificate verification profile can be specified
13616      from the ones in 'gnutls_certificate_verification_profiles_t' by
13617      ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
13618      verification flags.
13619
13620      The acceptable 'data' types are 'GNUTLS_DT_DNS_HOSTNAME' and
13621      'GNUTLS_DT_KEY_PURPOSE_OID' .  The former accepts as data a
13622      null-terminated hostname, and the latter a null-terminated object
13623      identifier (e.g., 'GNUTLS_KP_TLS_WWW_SERVER' ).  If a DNS hostname
13624      is provided then this function will compare the hostname in the
13625      certificate against the given.  If names do not match the
13626      'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.  If a key
13627      purpose OID is provided and the end-certificate contains the
13628      extended key usage PKIX extension, it will be required to be have
13629      the provided key purpose or be marked for any purpose, otherwise
13630      verification will fail with
13631      'GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE' status.
13632
13633      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13634      otherwise a negative error value.  Note that verification failure
13635      will not result to an error code, only 'voutput' will be updated.
13636
13637      *Since:* 3.3.8
13638
13639 gnutls_x509_trust_list_verify_named_crt
13640 ---------------------------------------
13641
13642  -- Function: int gnutls_x509_trust_list_verify_named_crt
13643           (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
13644           void * NAME, size_t NAME_SIZE, unsigned int FLAGS, unsigned
13645           int * VOUTPUT, gnutls_verify_output_function FUNC)
13646      LIST: The structure of the list
13647
13648      CERT: is the certificate to be verified
13649
13650      NAME: is the certificate's name
13651
13652      NAME_SIZE: is the certificate's name size
13653
13654      FLAGS: Flags that may be used to change the verification algorithm.
13655      Use OR of the gnutls_certificate_verify_flags enumerations.
13656
13657      VOUTPUT: will hold the certificate verification output.
13658
13659      FUNC: If non-null will be called on each chain element verification
13660      with the output.
13661
13662      This function will try to find a certificate that is associated
13663      with the provided name -see
13664      'gnutls_x509_trust_list_add_named_crt()' .  If a match is found the
13665      certificate is considered valid.  In addition to that this function
13666      will also check CRLs.  The 'voutput' parameter will hold an OR'ed
13667      sequence of 'gnutls_certificate_status_t' flags.
13668
13669      Additionally a certificate verification profile can be specified
13670      from the ones in 'gnutls_certificate_verification_profiles_t' by
13671      ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
13672      verification flags.
13673
13674      *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
13675      otherwise a negative error value.
13676
13677      *Since:* 3.0.0
13678