glib2 1.2.5-x86-mingw32 → 1.2.6-x86-mingw32

data/vendor/local/share/info/gnutls.info-3

@@ -1,9 +1,9 @@
 This is gnutls.info, produced by makeinfo version 4.13 from gnutls.texi.
 
-This manual is last updated 17 November 2012 for version 3.1.5 of
-GnuTLS.
+This manual is last updated 21 March 2013 for version 3.1.10 of GnuTLS.
 
-Copyright (C) 2001-2012 Free Software Foundation, Inc.
+Copyright (C) 2001-2013 Free Software Foundation, Inc.\\ Copyright (C)
+2001-2013 Nikos Mavrogiannopoulos
 
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License,
@@ -28,9 +28,17 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
 
-File: gnutls.info,  Node: Datagram TLS API,  Next: X509 certificate API,  Prev: Core TLS API,  Up: API reference
+File: gnutls.info,  Node: High level TLS API,  Next: Datagram TLS API,  Prev: Core TLS API,  Up: API reference
 
-E.2 Datagram TLS API
+E.2 High level TLS API
+======================
+
+The prototypes for the following functions lie in `gnutls/xssl.h'.
+
+
+File: gnutls.info,  Node: Datagram TLS API,  Next: X509 certificate API,  Prev: High level TLS API,  Up: API reference
+
+E.3 Datagram TLS API
 ====================
 
 The prototypes for the following functions lie in `gnutls/dtls.h'.
@@ -236,7 +244,7 @@ gnutls_record_get_discarded
 
 File: gnutls.info,  Node: X509 certificate API,  Next: OCSP API,  Prev: Datagram TLS API,  Up: API reference
 
-E.3 X.509 certificate API
+E.4 X.509 certificate API
 =========================
 
 The following functions are to be used for X.509 certificate handling.
@@ -328,6 +336,8 @@ gnutls_pkcs7_export2
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
+     *Since:* 3.1.3
+
 gnutls_pkcs7_get_crl_count
 --------------------------
 
@@ -502,11 +512,10 @@ gnutls_x509_crl_check_issuer
      ISSUER: is the certificate of a possible issuer
 
      This function will check if the given CRL was issued by the given
-     issuer certificate.  It will return true (1) if the given CRL was
-     issued by the given issuer, and false (0) if not.
+     issuer certificate.
 
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
+     *Returns:* true (1) if the given CRL was issued by the given
+     issuer, and false (0) if not.
 
 gnutls_x509_crl_deinit
 ----------------------
@@ -800,6 +809,26 @@ gnutls_x509_crl_get_issuer_dn
      is not long enough, and in that case the sizeof_buf will be updated
      with the required size, and 0 on success.
 
+gnutls_x509_crl_get_issuer_dn2
+------------------------------
+
+ -- Function: int gnutls_x509_crl_get_issuer_dn2 (gnutls_x509_crl_t
+          CRL, gnutls_datum_t * DN)
+     CRL: - undescribed -
+
+     DN: a pointer to a structure to hold the name
+
+     This function will allocate buffer and copy the name of the CRL
+     issuer.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as
+     described in RFC4514. The output string will be ASCII or UTF-8
+     encoded, depending on the certificate data.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value. and a negative error code on
+     error.
+
+     *Since:* 3.1.10
+
 gnutls_x509_crl_get_issuer_dn_by_oid
 ------------------------------------
 
@@ -1209,13 +1238,14 @@ gnutls_x509_crl_verify
 ----------------------
 
  -- Function: int gnutls_x509_crl_verify (gnutls_x509_crl_t CRL, const
-          gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, unsigned int
+          gnutls_x509_crt_t * TRUSTED_CAS, int TCAS_SIZE, unsigned int
           FLAGS, unsigned int * VERIFY)
      CRL: is the crl to be verified
 
-     CA_LIST: is a certificate list that is considered to be trusted one
+     TRUSTED_CAS: is a certificate list that is considered to be
+     trusted one
 
-     CA_LIST_LENGTH: holds the number of CA certificates in CA_list
+     TCAS_SIZE: holds the number of CA certificates in CA_list
 
      FLAGS: Flags that may be used to change the verification
      algorithm. Use OR of the gnutls_certificate_verify_flags
@@ -1224,9 +1254,13 @@ gnutls_x509_crl_verify
      VERIFY: will hold the crl verification output.
 
      This function will try to verify the given crl and return its
-     status.  See `gnutls_x509_crt_list_verify()'  for a detailed
-     description of return values. Note that since GnuTLS 3.1.4 this
-     function includes the time checks.
+     verification status.  See `gnutls_x509_crt_list_verify()'  for a
+     detailed description of return values. Note that since GnuTLS
+     3.1.4 this function includes the time checks.
+
+     Note that value in  `verify' is set only when the return value of
+     this function is success (i.e, failure to trust a CRL a
+     certificate does not imply a negative return value).
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
@@ -1297,23 +1331,27 @@ gnutls_x509_crq_get_attribute_by_oid
 
  -- Function: int gnutls_x509_crq_get_attribute_by_oid
           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
-          BUF, size_t * SIZEOF_BUF)
+          BUF, size_t * BUF_SIZE)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     OID: holds an Object Identified in (0)-terminated string
+     OID: holds an Object Identifier in null-terminated string
 
      INDX: In case multiple same OIDs exist in the attribute list, this
-     specifies which to send, use (0) to get the first one
+     specifies which to get, use (0) to get the first one
 
      BUF: a pointer to a structure to hold the attribute data (may be
      `NULL' )
 
-     SIZEOF_BUF: initially holds the size of  `buf'
+     BUF_SIZE: initially holds the size of  `buf'
 
      This function will return the attribute in the certificate request
      specified by the given Object ID.  The attribute will be DER
      encoded.
 
+     Attributes in a certificate request is an optional set of data
+     appended to the request. Their interpretation depends on the CA
+     policy.
+
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
@@ -1324,7 +1362,7 @@ gnutls_x509_crq_get_attribute_data
           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     INDX: Specifies which attribute OID to send. Use (0) to get the
+     INDX: Specifies which attribute number to get. Use (0) to get the
      first one.
 
      DATA: a pointer to a structure to hold the data (may be null)
@@ -1353,7 +1391,7 @@ gnutls_x509_crq_get_attribute_info
           CRQ, int INDX, void * OID, size_t * SIZEOF_OID)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     INDX: Specifies which attribute OID to send. Use (0) to get the
+     INDX: Specifies which attribute number to get. Use (0) to get the
      first one.
 
      OID: a pointer to a structure to hold the OID
@@ -1411,12 +1449,12 @@ gnutls_x509_crq_get_challenge_password
 --------------------------------------
 
  -- Function: int gnutls_x509_crq_get_challenge_password
-          (gnutls_x509_crq_t CRQ, char * PASS, size_t * SIZEOF_PASS)
+          (gnutls_x509_crq_t CRQ, char * PASS, size_t * PASS_SIZE)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
      PASS: will hold a (0)-terminated password string
 
-     SIZEOF_PASS: Initially holds the size of  `pass' .
+     PASS_SIZE: Initially holds the size of  `pass' .
 
      This function will return the challenge password in the request.
      The challenge password is intended to be used for requesting a
@@ -1429,12 +1467,12 @@ gnutls_x509_crq_get_dn
 ----------------------
 
  -- Function: int gnutls_x509_crq_get_dn (gnutls_x509_crq_t CRQ, char *
-          BUF, size_t * SIZEOF_BUF)
+          BUF, size_t * BUF_SIZE)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
      BUF: a pointer to a structure to hold the name (may be `NULL' )
 
-     SIZEOF_BUF: initially holds the size of  `buf'
+     BUF_SIZE: initially holds the size of  `buf'
 
      This function will copy the name of the Certificate request subject
      to the provided buffer.  The name will be in the form
@@ -1443,27 +1481,47 @@ gnutls_x509_crq_get_dn
      data.
 
      *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER'  if the provided buffer
-     is not long enough, and in that case the * `sizeof_buf' will be
+     is not long enough, and in that case the * `buf_size' will be
      updated with the required size.  On success 0 is returned.
 
+gnutls_x509_crq_get_dn2
+-----------------------
+
+ -- Function: int gnutls_x509_crq_get_dn2 (gnutls_x509_crq_t CRQ,
+          gnutls_datum_t * DN)
+     CRQ: should contain a `gnutls_x509_crq_t'  structure
+
+     DN: a pointer to a structure to hold the name
+
+     This function will allocate buffer and copy the name of the
+     Certificate request. The name will be in the form
+     "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
+     will be ASCII or UTF-8 encoded, depending on the certificate data.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value. and a negative error code on
+     error.
+
+     *Since:* 3.1.10
+
 gnutls_x509_crq_get_dn_by_oid
 -----------------------------
 
  -- Function: int gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t CRQ,
           const char * OID, int INDX, unsigned int RAW_FLAG, void *
-          BUF, size_t * SIZEOF_BUF)
+          BUF, size_t * BUF_SIZE)
      CRQ: should contain a gnutls_x509_crq_t structure
 
-     OID: holds an Object Identified in null terminated string
+     OID: holds an Object Identifier in a null terminated string
 
      INDX: In case multiple same OIDs exist in the RDN, this specifies
-     which to send. Use (0) to get the first one.
+     which to get. Use (0) to get the first one.
 
      RAW_FLAG: If non-zero returns the raw DER data of the DN part.
 
      BUF: a pointer to a structure to hold the name (may be `NULL' )
 
-     SIZEOF_BUF: initially holds the size of  `buf'
+     BUF_SIZE: initially holds the size of  `buf'
 
      This function will extract the part of the name of the Certificate
      request subject, specified by the given OID. The output will be
@@ -1477,7 +1535,7 @@ gnutls_x509_crq_get_dn_by_oid
      using `gnutls_x509_dn_oid_known()' .
 
      *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER'  if the provided buffer
-     is not long enough, and in that case the * `sizeof_buf' will be
+     is not long enough, and in that case the * `buf_size' will be
      updated with the required size.  On success 0 is returned.
 
 gnutls_x509_crq_get_dn_oid
@@ -1487,7 +1545,7 @@ gnutls_x509_crq_get_dn_oid
           int INDX, void * OID, size_t * SIZEOF_OID)
      CRQ: should contain a gnutls_x509_crq_t structure
 
-     INDX: Specifies which DN OID to send. Use (0) to get the first one.
+     INDX: Specifies which DN OID to get. Use (0) to get the first one.
 
      OID: a pointer to a structure to hold the name (may be `NULL' )
 
@@ -1505,17 +1563,17 @@ gnutls_x509_crq_get_extension_by_oid
 
  -- Function: int gnutls_x509_crq_get_extension_by_oid
           (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void *
-          BUF, size_t * SIZEOF_BUF, unsigned int * CRITICAL)
+          BUF, size_t * BUF_SIZE, unsigned int * CRITICAL)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     OID: holds an Object Identified in null terminated string
+     OID: holds an Object Identifier in a null terminated string
 
      INDX: In case multiple same OIDs exist in the extensions, this
-     specifies which to send. Use (0) to get the first one.
+     specifies which to get. Use (0) to get the first one.
 
      BUF: a pointer to a structure to hold the name (may be null)
 
-     SIZEOF_BUF: initially holds the size of  `buf'
+     BUF_SIZE: initially holds the size of  `buf'
 
      CRITICAL: will be non-zero if the extension is marked as critical
 
@@ -1537,7 +1595,7 @@ gnutls_x509_crq_get_extension_data
           CRQ, int INDX, void * DATA, size_t * SIZEOF_DATA)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     INDX: Specifies which extension OID to send. Use (0) to get the
+     INDX: Specifies which extension number to get. Use (0) to get the
      first one.
 
      DATA: a pointer to a structure to hold the data (may be null)
@@ -1568,7 +1626,7 @@ gnutls_x509_crq_get_extension_info
           * CRITICAL)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     INDX: Specifies which extension OID to send. Use (0) to get the
+     INDX: Specifies which extension number to get. Use (0) to get the
      first one.
 
      OID: a pointer to a structure to hold the OID
@@ -1883,18 +1941,22 @@ gnutls_x509_crq_set_attribute_by_oid
 
  -- Function: int gnutls_x509_crq_set_attribute_by_oid
           (gnutls_x509_crq_t CRQ, const char * OID, void * BUF, size_t
-          SIZEOF_BUF)
+          BUF_SIZE)
      CRQ: should contain a `gnutls_x509_crq_t'  structure
 
-     OID: holds an Object Identified in (0)-terminated string
+     OID: holds an Object Identifier in a null-terminated string
 
      BUF: a pointer to a structure that holds the attribute data
 
-     SIZEOF_BUF: holds the size of  `buf'
+     BUF_SIZE: holds the size of  `buf'
 
      This function will set the attribute in the certificate request
-     specified by the given Object ID.  The attribute must be be DER
-     encoded.
+     specified by the given Object ID. The provided attribute must be
+     be DER encoded.
+
+     Attributes in a certificate request is an optional set of data
+     appended to the request. Their interpretation depends on the CA
+     policy.
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
@@ -1936,6 +1998,23 @@ gnutls_x509_crq_set_challenge_password
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
+gnutls_x509_crq_set_dn
+----------------------
+
+ -- Function: int gnutls_x509_crq_set_dn (gnutls_x509_crq_t CRQ, const
+          char * DN, const char** ERR)
+     CRQ: a certificate of type `gnutls_x509_crq_t'
+
+     DN: a comma separated DN string (RFC4514)
+
+     ERR: indicates the error position (if any)
+
+     This function will set the DN on the provided certificate.  The
+     input string should be plain ASCII or UTF-8 encoded.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value.
+
 gnutls_x509_crq_set_dn_by_oid
 -----------------------------
 
@@ -2172,8 +2251,7 @@ gnutls_x509_crt_check_issuer
      identifier and subject key identifier fields match.
 
      *Returns:* It will return true (1) if the given certificate is
-     issued by the given issuer, and false (0) if not.  A negative
-     error code is returned in case of an error.
+     issued by the given issuer, and false (0) if not.
 
 gnutls_x509_crt_check_revocation
 --------------------------------
@@ -2263,7 +2341,7 @@ gnutls_x509_crt_export2
      *Returns:* In case of failure a negative error code will be
      returned, and 0 on success.
 
-     *Since:* 3.1
+     *Since:* 3.1.3
 
 gnutls_x509_crt_get_activation_time
 -----------------------------------
@@ -2528,6 +2606,26 @@ gnutls_x509_crt_get_dn
      is not long enough, and in that case the  `buf_size' will be
      updated with the required size.  On success 0 is returned.
 
+gnutls_x509_crt_get_dn2
+-----------------------
+
+ -- Function: int gnutls_x509_crt_get_dn2 (gnutls_x509_crt_t CERT,
+          gnutls_datum_t * DN)
+     CERT: should contain a `gnutls_x509_crt_t'  structure
+
+     DN: a pointer to a structure to hold the name
+
+     This function will allocate buffer and copy the name of the
+     Certificate.  The name will be in the form "C=xxxx,O=yyyy,CN=zzzz"
+     as described in RFC4514. The output string will be ASCII or UTF-8
+     encoded, depending on the certificate data.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value. and a negative error code on
+     error.
+
+     *Since:* 3.1.10
+
 gnutls_x509_crt_get_dn_by_oid
 -----------------------------
 
@@ -2906,6 +3004,26 @@ gnutls_x509_crt_get_issuer_dn
      not long enough, and in that case the  `buf_size' will be updated
      with the required size.  On success 0 is returned.
 
+gnutls_x509_crt_get_issuer_dn2
+------------------------------
+
+ -- Function: int gnutls_x509_crt_get_issuer_dn2 (gnutls_x509_crt_t
+          CERT, gnutls_datum_t * DN)
+     CERT: should contain a `gnutls_x509_crt_t'  structure
+
+     DN: a pointer to a structure to hold the name
+
+     This function will allocate buffer and copy the name of issuer of
+     the Certificate.  The name will be in the form
+     "C=xxxx,O=yyyy,CN=zzzz" as described in RFC4514. The output string
+     will be ASCII or UTF-8 encoded, depending on the certificate data.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value. and a negative error code on
+     error.
+
+     *Since:* 3.1.10
+
 gnutls_x509_crt_get_issuer_dn_by_oid
 ------------------------------------
 
@@ -3219,10 +3337,10 @@ gnutls_x509_crt_get_raw_dn
 --------------------------
 
  -- Function: int gnutls_x509_crt_get_raw_dn (gnutls_x509_crt_t CERT,
-          gnutls_datum_t * START)
+          gnutls_datum_t * DN)
      CERT: should contain a `gnutls_x509_crt_t'  structure
 
-     START: will hold the starting point of the DN
+     DN: will hold the starting point of the DN
 
      This function will return a pointer to the DER encoded DN
      structure and the length. This points to allocated data that must
@@ -3236,10 +3354,10 @@ gnutls_x509_crt_get_raw_issuer_dn
 ---------------------------------
 
  -- Function: int gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t
-          CERT, gnutls_datum_t * START)
+          CERT, gnutls_datum_t * DN)
      CERT: should contain a `gnutls_x509_crt_t'  structure
 
-     START: will hold the starting point of the DN
+     DN: will hold the starting point of the DN
 
      This function will return a pointer to the DER encoded DN structure
      and the length. This points to allocated data that must be free'd
@@ -3702,7 +3820,7 @@ gnutls_x509_crt_set_authority_key_id
 
      ID: The key ID
 
-     ID_SIZE: Holds the size of the serial field.
+     ID_SIZE: Holds the size of the key ID field.
 
      This function will set the X.509 certificate's authority key ID
      extension.  Only the keyIdentifier field can be set with this
@@ -3826,6 +3944,23 @@ gnutls_x509_crt_set_crq_extensions
 
      *Since:* 2.8.0
 
+gnutls_x509_crt_set_dn
+----------------------
+
+ -- Function: int gnutls_x509_crt_set_dn (gnutls_x509_crt_t CRT, const
+          char * DN, const char** ERR)
+     CRT: a certificate of type `gnutls_x509_crt_t'
+
+     DN: a comma separated DN string (RFC4514)
+
+     ERR: indicates the error position (if any)
+
+     This function will set the DN on the provided certificate.  The
+     input string should be plain ASCII or UTF-8 encoded.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value.
+
 gnutls_x509_crt_set_dn_by_oid
 -----------------------------
 
@@ -3893,6 +4028,23 @@ gnutls_x509_crt_set_extension_by_oid
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
+gnutls_x509_crt_set_issuer_dn
+-----------------------------
+
+ -- Function: int gnutls_x509_crt_set_issuer_dn (gnutls_x509_crt_t CRT,
+          const char * DN, const char** ERR)
+     CRT: a certificate of type `gnutls_x509_crt_t'
+
+     DN: a comma separated DN string (RFC4514)
+
+     ERR: indicates the error position (if any)
+
+     This function will set the DN on the provided certificate.  The
+     input string should be plain ASCII or UTF-8 encoded.
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value.
+
 gnutls_x509_crt_set_issuer_dn_by_oid
 ------------------------------------
 
@@ -4100,31 +4252,11 @@ gnutls_x509_crt_set_serial
      SERIAL_SIZE: Holds the size of the serial field.
 
      This function will set the X.509 certificate's serial number.
-     Serial is not always a 32 or 64bit number.  Some CAs use large
-     serial numbers, thus it may be wise to handle it as something
-     uint8_t.
-
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
-
-gnutls_x509_crt_set_subject_alternative_name
---------------------------------------------
-
- -- Function: int gnutls_x509_crt_set_subject_alternative_name
-          (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
-          const char * DATA_STRING)
-     CRT: a certificate of type `gnutls_x509_crt_t'
-
-     TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
-
-     DATA_STRING: The data to be set, a (0) terminated string
-
-     This function will set the subject alternative name certificate
-     extension. This function assumes that data can be expressed as a
-     null terminated string.
-
-     The name of the function is unfortunate since it is incosistent
-     with `gnutls_x509_crt_get_subject_alt_name()' .
+     While the serial number is an integer, it is often handled as an
+     opaque field by several CAs. For this reason this function accepts
+     any kind of data as a serial number. To be consistent with the
+     X.509/PKIX specifications the provided  `serial' should be a
+     big-endian positive number (i.e. it's leftmost bit should be zero).
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
@@ -4154,6 +4286,28 @@ gnutls_x509_crt_set_subject_alt_name
 
      *Since:* 2.6.0
 
+gnutls_x509_crt_set_subject_alternative_name
+--------------------------------------------
+
+ -- Function: int gnutls_x509_crt_set_subject_alternative_name
+          (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE,
+          const char * DATA_STRING)
+     CRT: a certificate of type `gnutls_x509_crt_t'
+
+     TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations
+
+     DATA_STRING: The data to be set, a (0) terminated string
+
+     This function will set the subject alternative name certificate
+     extension. This function assumes that data can be expressed as a
+     null terminated string.
+
+     The name of the function is unfortunate since it is incosistent
+     with `gnutls_x509_crt_get_subject_alt_name()' .
+
+     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
+     otherwise a negative error value.
+
 gnutls_x509_crt_set_subject_key_id
 ----------------------------------
 
@@ -4163,7 +4317,7 @@ gnutls_x509_crt_set_subject_key_id
 
      ID: The key ID
 
-     ID_SIZE: Holds the size of the serial field.
+     ID_SIZE: Holds the size of the subject key ID field.
 
      This function will set the X.509 certificate's subject key ID
      extension.
@@ -4254,7 +4408,8 @@ gnutls_x509_crt_verify
      VERIFY: will hold the certificate verification output.
 
      This function will try to verify the given certificate and return
-     its status.
+     its status. Note that a verification error does not imply a
+     negative return status. In that case the  `verify' status is set.
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
@@ -4318,12 +4473,14 @@ gnutls_x509_dn_export2
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
+     *Since:* 3.1.3
+
 gnutls_x509_dn_get_rdn_ava
 --------------------------
 
  -- Function: int gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t DN, int
           IRDN, int IAVA, gnutls_x509_ava_st * AVA)
-     DN: input variable with uint8_t DN pointer
+     DN: a pointer to DN
 
      IRDN: index of RDN
 
@@ -4337,11 +4494,15 @@ gnutls_x509_dn_get_rdn_ava
      struct gnutls_x509_ava_st { gnutls_datum_t oid; gnutls_datum_t
      value; unsigned long value_tag; };
 
-     Note that  `ava' will contain pointers into the  `dn' structure,
-     so you should not modify any data or deallocate it.  Note also
-     that the DN in turn points into the original certificate
-     structure, and thus you may not deallocate the certificate and
-     continue to access  `dn' .
+     The X.509 distinguished name is a sequence of sequences of strings
+     and this is what the  `irdn' and  `iava' indexes model.
+
+     Note that  `ava' will contain pointers into the  `dn' structure
+     which in turns points to the original certificate. Thus you should
+     not modify any data or deallocate any of those.
+
+     This is a low-level function that requires the caller to do the
+     value conversions when necessary (e.g. from UCS-2).
 
      *Returns:* Returns 0 on success, or an error code.
 
@@ -4826,8 +4987,8 @@ gnutls_x509_privkey_import2
      native `gnutls_x509_privkey_t'  format, irrespective of the input
      format. The input format is auto-detected.
 
-     The supported formats are typical X.509, PKCS `8'  and the openssl
-     format.
+     The supported formats are basic unencrypted key, PKCS `8' , PKCS
+     `12' , and the openssl format.
 
      If the provided key is encrypted but no password was given, then
      `GNUTLS_E_DECRYPTION_FAILED'  is returned.
@@ -5053,19 +5214,19 @@ gnutls_x509_rdn_get
 -------------------
 
  -- Function: int gnutls_x509_rdn_get (const gnutls_datum_t * IDN, char
-          * BUF, size_t * SIZEOF_BUF)
+          * BUF, size_t * BUF_SIZE)
      IDN: should contain a DER encoded RDN sequence
 
      BUF: a pointer to a structure to hold the peer's name
 
-     SIZEOF_BUF: holds the size of  `buf'
+     BUF_SIZE: holds the size of  `buf'
 
      This function will return the name of the given RDN sequence.  The
      name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in
      RFC4514.
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned, or
-     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `sizeof_buf' is
+     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `buf_size' is
      updated if the provided buffer is not long enough, otherwise a
      negative error value.
 
@@ -5074,7 +5235,7 @@ gnutls_x509_rdn_get_by_oid
 
  -- Function: int gnutls_x509_rdn_get_by_oid (const gnutls_datum_t *
           IDN, const char * OID, int INDX, unsigned int RAW_FLAG, void
-          * BUF, size_t * SIZEOF_BUF)
+          * BUF, size_t * BUF_SIZE)
      IDN: should contain a DER encoded RDN sequence
 
      OID: an Object Identifier
@@ -5086,14 +5247,14 @@ gnutls_x509_rdn_get_by_oid
 
      BUF: a pointer to a structure to hold the peer's name
 
-     SIZEOF_BUF: holds the size of  `buf'
+     BUF_SIZE: holds the size of  `buf'
 
      This function will return the name of the given Object identifier,
      of the RDN sequence.  The name will be encoded using the rules
      from RFC4514.
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned, or
-     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `sizeof_buf' is
+     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `buf_size' is
      updated if the provided buffer is not long enough, otherwise a
      negative error value.
 
@@ -5101,20 +5262,20 @@ gnutls_x509_rdn_get_oid
 -----------------------
 
  -- Function: int gnutls_x509_rdn_get_oid (const gnutls_datum_t * IDN,
-          int INDX, void * BUF, size_t * SIZEOF_BUF)
+          int INDX, void * BUF, size_t * BUF_SIZE)
      IDN: should contain a DER encoded RDN sequence
 
      INDX: Indicates which OID to return. Use 0 for the first one.
 
      BUF: a pointer to a structure to hold the peer's name OID
 
-     SIZEOF_BUF: holds the size of  `buf'
+     BUF_SIZE: holds the size of  `buf'
 
      This function will return the specified Object identifier, of the
      RDN sequence.
 
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned, or
-     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `sizeof_buf' is
+     `GNUTLS_E_SHORT_MEMORY_BUFFER'  is returned and * `buf_size' is
      updated if the provided buffer is not long enough, otherwise a
      negative error value.
 
@@ -5336,6 +5497,64 @@ gnutls_x509_trust_list_init
 
      *Since:* 3.0
 
+gnutls_x509_trust_list_remove_cas
+---------------------------------
+
+ -- Function: int gnutls_x509_trust_list_remove_cas
+          (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
+          CLIST, int CLIST_SIZE)
+     LIST: The structure of the list
+
+     CLIST: A list of CAs
+
+     CLIST_SIZE: The length of the CA list
+
+     This function will remove the given certificate authorities from
+     the trusted list.
+
+     *Returns:* The number of removed elements is returned.
+
+     *Since:* 3.1.10
+
+gnutls_x509_trust_list_remove_trust_file
+----------------------------------------
+
+ -- Function: int gnutls_x509_trust_list_remove_trust_file
+          (gnutls_x509_trust_list_t LIST, const char* CA_FILE,
+          gnutls_x509_crt_fmt_t TYPE)
+     LIST: The structure of the list
+
+     CA_FILE: A file containing a list of CAs
+
+     TYPE: The format of the certificates
+
+     This function will add the given certificate authorities to the
+     trusted list. pkcs11 URLs are also accepted, instead of files, by
+     this function.
+
+     *Returns:* The number of added elements is returned.
+
+     *Since:* 3.1.10
+
+gnutls_x509_trust_list_remove_trust_mem
+---------------------------------------
+
+ -- Function: int gnutls_x509_trust_list_remove_trust_mem
+          (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
+          gnutls_x509_crt_fmt_t TYPE)
+     LIST: The structure of the list
+
+     CAS: A buffer containing a list of CAs (optional)
+
+     TYPE: The format of the certificates
+
+     This function will add the given certificate authorities to the
+     trusted list.
+
+     *Returns:* The number of added elements is returned.
+
+     *Since:* 3.1.10
+
 gnutls_x509_trust_list_verify_crt
 ---------------------------------
 
@@ -5409,7 +5628,7 @@ gnutls_x509_trust_list_verify_named_crt
 
 File: gnutls.info,  Node: OCSP API,  Next: OpenPGP API,  Prev: X509 certificate API,  Up: API reference
 
-E.4 OCSP API
+E.5 OCSP API
 ============
 
 The following functions are for OCSP certificate status checking.
@@ -5719,6 +5938,8 @@ gnutls_ocsp_resp_check_crt
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error code is returned.
 
+     *Since:* 3.1.3
+
 gnutls_ocsp_resp_deinit
 -----------------------
 
@@ -6107,7 +6328,7 @@ gnutls_ocsp_resp_verify_direct
 
 File: gnutls.info,  Node: OpenPGP API,  Next: PKCS 12 API,  Prev: OCSP API,  Up: API reference
 
-E.5 OpenPGP API
+E.6 OpenPGP API
 ===============
 
 The following functions are to be used for OpenPGP certificate
@@ -6296,7 +6517,7 @@ gnutls_openpgp_crt_check_hostname
      given hostname. This is a basic implementation of the matching
      described in RFC2818 (HTTPS), which takes into account wildcards.
 
-     *Returns:* `GNUTLS_E_SUCCESS'  on success, or an error code.
+     *Returns:* non-zero for a successful match, and zero on failure.
 
 gnutls_openpgp_crt_deinit
 -------------------------
@@ -6343,6 +6564,8 @@ gnutls_openpgp_crt_export2
 
      *Returns:* `GNUTLS_E_SUCCESS'  on success, or an error code.
 
+     *Since:* 3.1.3
+
 gnutls_openpgp_crt_get_auth_subkey
 ----------------------------------
 
@@ -7030,7 +7253,7 @@ gnutls_openpgp_privkey_export2
 
      *Returns:* `GNUTLS_E_SUCCESS'  on success, or an error code.
 
-     *Since:* 3.1
+     *Since:* 3.1.3
 
 gnutls_openpgp_privkey_export_dsa_raw
 -------------------------------------
@@ -7447,10 +7670,12 @@ gnutls_openpgp_set_recv_key_function
      This callback is only useful in server side, and will be used if
      the peer sent a key fingerprint instead of a full key.
 
+     The retrieved key must be allocated using `gnutls_malloc()' .
+
 
 File: gnutls.info,  Node: PKCS 12 API,  Next: PKCS 11 API,  Prev: OpenPGP API,  Up: API reference
 
-E.6 PKCS 12 API
+E.7 PKCS 12 API
 ===============
 
 The following functions are to be used for PKCS 12 handling.  Their
@@ -7735,7 +7960,7 @@ gnutls_pkcs12_export2
      *Returns:* In case of failure a negative error code will be
      returned, and 0 on success.
 
-     *Since:* 3.1
+     *Since:* 3.1.3
 
 gnutls_pkcs12_generate_mac
 --------------------------
@@ -7836,17 +8061,19 @@ gnutls_pkcs12_simple_parse
 
      KEY: a structure to store the parsed private key.
 
-     CHAIN: the corresponding to key certificate chain
+     CHAIN: the corresponding to key certificate chain (may be `NULL' )
 
-     CHAIN_LEN: will be updated with the number of additional
+     CHAIN_LEN: will be updated with the number of additional (may be
+     `NULL' )
 
      EXTRA_CERTS: optional pointer to receive an array of additional
-     certificates found in the PKCS`12'  blob.
+     certificates found in the PKCS`12'  blob (may be `NULL' ).
 
      EXTRA_CERTS_LEN: will be updated with the number of additional
-     certs.
+     certs (may be `NULL' ).
 
-     CRL: an optional structure to store the parsed CRL.
+     CRL: an optional structure to store the parsed CRL (may be `NULL'
+     ).
 
      FLAGS: should be zero or one of GNUTLS_PKCS12_SP_*
 
@@ -7854,21 +8081,21 @@ gnutls_pkcs12_simple_parse
      the private key, the corresponding certificate chain, and any
      additional certificates and a CRL.
 
-     The  `extra_certs_ret' and  `extra_certs_ret_len' parameters are
+     The  `extra_certs_ret' and  `extra_certs_len' parameters are
      optional and both may be set to `NULL' . If either is non-`NULL' ,
-     then both must be.
+     then both must be set.
 
      Encrypted PKCS`12'  bags and PKCS`8'  private keys are supported.
      However, only password based security, and the same password for
      all operations, are supported.
 
-     PKCS`12'  file may contain many keys and/or certificates, and there
-     is no way to identify which key/certificate pair you want.  You
-     should make sure the PKCS`12'  file only contain one
+     A PKCS`12'  file may contain many keys and/or certificates, and
+     there is no way to identify which key/certificate pair you want.
+     You should make sure the PKCS`12'  file only contain one
      key/certificate pair and/or one CRL.
 
-     It is believed that the limitations of this function is acceptable
-     for most usage, and that any more flexibility would introduce
+     It is believed that the limitations of this function are acceptable
+     for common usage, and that any more flexibility would introduce
      complexity that would make it harder to use this functionality at
      all.
 
@@ -7903,7 +8130,7 @@ gnutls_pkcs12_verify_mac
 
 File: gnutls.info,  Node: PKCS 11 API,  Next: TPM API,  Prev: PKCS 12 API,  Up: API reference
 
-E.7 Hardware token via PKCS 11 API
+E.8 Hardware token via PKCS 11 API
 ==================================
 
 The following functions are to be used for PKCS 11 handling.  Their
@@ -8124,7 +8351,7 @@ gnutls_pkcs11_obj_export2
      *Returns:* In case of failure a negative error code will be
      returned, and `GNUTLS_E_SUCCESS'  (0) on success.
 
-     *Since:* 3.1
+     *Since:* 3.1.3
 
 gnutls_pkcs11_obj_export_url
 ----------------------------
@@ -8371,7 +8598,7 @@ gnutls_pkcs11_privkey_generate2
      *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
      otherwise a negative error value.
 
-     *Since:* 3.1
+     *Since:* 3.1.5
 
 gnutls_pkcs11_privkey_get_info
 ------------------------------
@@ -8463,6 +8690,20 @@ gnutls_pkcs11_privkey_set_pin_function
 
      *Since:* 3.1.0
 
+gnutls_pkcs11_privkey_status
+----------------------------
+
+ -- Function: int gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t
+          KEY)
+     KEY: Holds the key
+
+     Checks the status of the private key token.
+
+     *Returns:* this function will return non-zero if the token holding
+     the private key is still available (inserted), and zero otherwise.
+
+     *Since:* 3.1.9
+
 gnutls_pkcs11_reinit
 --------------------
 
@@ -8699,118 +8940,3 @@ gnutls_x509_crt_list_import_pkcs11
 
      *Since:* 2.12.0
 
-
-File: gnutls.info,  Node: TPM API,  Next: Abstract key API,  Prev: PKCS 11 API,  Up: API reference
-
-E.8 TPM API
-===========
-
-The following functions are to be used for TPM handling.  Their
-prototypes lie in `gnutls/tpm.h'.
-
-gnutls_tpm_get_registered
--------------------------
-
- -- Function: int gnutls_tpm_get_registered (gnutls_tpm_key_list_t *
-          LIST)
-     LIST: a list to store the keys
-
-     This function will get a list of stored keys in the TPM. The uuid
-     of those keys
-
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
-
-     *Since:* 3.1.0
-
-gnutls_tpm_key_list_deinit
---------------------------
-
- -- Function: void gnutls_tpm_key_list_deinit (gnutls_tpm_key_list_t
-          LIST)
-     LIST: a list of the keys
-
-     This function will deinitialize the list of stored keys in the TPM.
-
-     *Since:* 3.1.0
-
-gnutls_tpm_key_list_get_url
----------------------------
-
- -- Function: int gnutls_tpm_key_list_get_url (gnutls_tpm_key_list_t
-          LIST, unsigned int IDX, char** URL, unsigned int FLAGS)
-     LIST: a list of the keys
-
-     IDX: The index of the key (starting from zero)
-
-     URL: The URL to be returned
-
-     FLAGS: should be zero
-
-     This function will return for each given index a URL of the
-     corresponding key.  If the provided index is out of bounds then
-     `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.
-
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
-
-     *Since:* 3.1.0
-
-gnutls_tpm_privkey_delete
--------------------------
-
- -- Function: int gnutls_tpm_privkey_delete (const char* URL, const
-          char* SRK_PASSWORD)
-     URL: the URL describing the key
-
-     SRK_PASSWORD: a password for the SRK key
-
-     This function will unregister the private key from the TPM chip.
-
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
-
-     *Since:* 3.1.0
-
-gnutls_tpm_privkey_generate
----------------------------
-
- -- Function: int gnutls_tpm_privkey_generate (gnutls_pk_algorithm_t
-          PK, unsigned int BITS, const char* SRK_PASSWORD, const char*
-          KEY_PASSWORD, gnutls_tpmkey_fmt_t FORMAT,
-          gnutls_x509_crt_fmt_t PUB_FORMAT, gnutls_datum_t* PRIVKEY,
-          gnutls_datum_t* PUBKEY, unsigned int FLAGS)
-     PK: the public key algorithm
-
-     BITS: the security bits
-
-     SRK_PASSWORD: a password to protect the exported key (optional)
-
-     KEY_PASSWORD: the password for the TPM (optional)
-
-     FORMAT: the format of the private key
-
-     PUB_FORMAT: the format of the public key
-
-     PRIVKEY: the generated key
-
-     PUBKEY: the corresponding public key (may be null)
-
-     FLAGS: should be a list of GNUTLS_TPM_* flags
-
-     This function will generate a private key in the TPM chip. The
-     private key will be generated within the chip and will be exported
-     in a wrapped with TPM's master key form. Furthermore the wrapped
-     key can be protected with the provided  `password' .
-
-     Note that bits in TPM is quantized value. If the input value is
-     not one of the allowed values, then it will be quantized to one of
-     512, 1024, 2048, 4096, 8192 and 16384.
-
-     Allowed flags are:
-
-     *Returns:* On success, `GNUTLS_E_SUCCESS'  (0) is returned,
-     otherwise a negative error value.
-
-     *Since:* 3.1.0
-