x509: better documented gnutls_trust_list_flags_t

3 files changed, 34 insertions, 7 deletions

diff --git a/lib/includes/gnutls/x509.h b/lib/includes/gnutls/x509.h
index b71847fbce..a4389156f2 100644
--- a/lib/includes/gnutls/x509.h
+++ b/lib/includes/gnutls/x509.h
@@ -1429,12 +1429,37 @@ int gnutls_x509_trust_list_get_issuer_by_subject_key_id(gnutls_x509_trust_list_t
 				      const gnutls_datum_t *spki,
 				      gnutls_x509_crt_t *issuer,
 				      unsigned int flags);
-
+/**
+ * gnutls_trust_list_flags_t:
+ * @GNUTLS_TL_VERIFY_CRL: If any CRLs are provided they will be verified for validity
+ *   prior to be added. The CA certificates that will be used for verification are the
+ *   ones already added in the trusted list.
+ * @GNUTLS_TL_USE_IN_TLS: Internal flag used by GnuTLS. If provided the trust list
+ *   structure will cache a copy of CA DNs to be used in the certificate request
+ *   TLS message.
+ * @GNUTLS_TL_NO_DUPLICATES: If this flag is specified, a function adding certificates
+ *   will check and eliminate any duplicates.
+ * @GNUTLS_TL_NO_DUPLICATE_KEY: If this flag is specified, a certificate sharing the
+ *   same key as a previously added on will not be added.
+ * @GNUTLS_TL_GET_COPY: The semantics of this flag are documented to the functions which
+ *   are applicable. In general, on returned value, the function will provide a copy
+ *   if this flag is provided, rather than a pointer to internal data.
+ *
+ * Enumeration of different certificate trust list flags.
+ */
+typedef enum gnutls_trust_list_flags_t {
+	GNUTLS_TL_VERIFY_CRL = 1,
 #define GNUTLS_TL_VERIFY_CRL 1
+	GNUTLS_TL_USE_IN_TLS = (1<<1),
 #define GNUTLS_TL_USE_IN_TLS (1<<1)
+	GNUTLS_TL_NO_DUPLICATES = (1<<2),
 #define GNUTLS_TL_NO_DUPLICATES (1<<2)
+	GNUTLS_TL_NO_DUPLICATE_KEY = (1<<3),
 #define GNUTLS_TL_NO_DUPLICATE_KEY (1<<3)
+	GNUTLS_TL_GET_COPY = (1<<4)
 #define GNUTLS_TL_GET_COPY (1<<4)
+} gnutls_trust_list_flags_t;
+
 int
 gnutls_x509_trust_list_add_cas(gnutls_x509_trust_list_t list,
 			       const gnutls_x509_crt_t * clist,
diff --git a/lib/x509/verify-high.c b/lib/x509/verify-high.c
index 96880e7e90..1749d49b10 100644
--- a/lib/x509/verify-high.c
+++ b/lib/x509/verify-high.c
@@ -254,7 +254,7 @@ trust_list_add_compat(gnutls_x509_trust_list_t list,
  * @list: The list
  * @clist: A list of CAs
  * @clist_size: The length of the CA list
- * @flags: should be 0 or an or'ed sequence of %GNUTLS_TL options.
+ * @flags: flags from %gnutls_trust_list_flags_t
  *
  * This function will add the given certificate authorities
  * to the trusted list. The list of CAs must not be deinitialized
@@ -680,7 +680,7 @@ gnutls_x509_trust_list_add_named_crt(gnutls_x509_trust_list_t list,
  * @list: The list
  * @crl_list: A list of CRLs
  * @crl_size: The length of the CRL list
- * @flags: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
+ * @flags: flags from %gnutls_trust_list_flags_t
  * @verification_flags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
  *
  * This function will add the given certificate revocation lists
@@ -693,6 +693,8 @@ gnutls_x509_trust_list_add_named_crt(gnutls_x509_trust_list_t list,
  * and not added to the list (that assumes that gnutls_x509_trust_list_deinit()
  * will be called with all=1).
  *
+ * If GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
+ *
  * Returns: The number of added elements is returned.
  *
  * Since: 3.0
@@ -929,7 +931,7 @@ int trust_list_get_issuer_by_dn(gnutls_x509_trust_list_t list,
  * @list: The list
  * @cert: is the certificate to find issuer for
  * @issuer: Will hold the issuer if any. Should be treated as constant.
- * @flags: Use zero or %GNUTLS_TL_GET_COPY
+ * @flags: flags from %gnutls_trust_list_flags_t (%GNUTLS_TL_GET_COPY is applicable)
  *
  * This function will find the issuer of the given certificate.
  * If the flag %GNUTLS_TL_GET_COPY is specified a copy of the issuer
diff --git a/lib/x509/verify-high2.c b/lib/x509/verify-high2.c
index 971284b30a..fb9f9ce101 100644
--- a/lib/x509/verify-high2.c
+++ b/lib/x509/verify-high2.c
@@ -52,7 +52,7 @@
  * @cas: A buffer containing a list of CAs (optional)
  * @crls: A buffer containing a list of CRLs (optional)
  * @type: The format of the certificates
- * @tl_flags: GNUTLS_TL_*
+ * @tl_flags: flags from %gnutls_trust_list_flags_t
  * @tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
  *
  * This function will add the given certificate authorities
@@ -286,7 +286,7 @@ int remove_pkcs11_object_url(gnutls_x509_trust_list_t list, const char *url)
  * @ca_file: A file containing a list of CAs (optional)
  * @crl_file: A file containing a list of CRLs (optional)
  * @type: The format of the certificates
- * @tl_flags: GNUTLS_TL_*
+ * @tl_flags: flags from %gnutls_trust_list_flags_t
  * @tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
  *
  * This function will add the given certificate authorities
@@ -420,7 +420,7 @@ int load_dir_certs(const char *dirname,
  * @ca_dir: A directory containing the CAs (optional)
  * @crl_dir: A directory containing a list of CRLs (optional)
  * @type: The format of the certificates
- * @tl_flags: GNUTLS_TL_*
+ * @tl_flags: flags from %gnutls_trust_list_flags_t
  * @tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
  *
  * This function will add the given certificate authorities