Document some miscellaneous x509.h functions

These three aren't part of some larger category of functions.

Bug: 426
Change-Id: I94c977b20c6e6beb51df9d89f86851c960b4dfc6
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/65809
Commit-Queue: David Benjamin <davidben@google.com>
Reviewed-by: Bob Beck <bbe@google.com>

include/openssl/ex_data.h

diff --git a/include/openssl/ex_data.h b/include/openssl/ex_data.h
index dab5383..2680055 100644
--- a/include/openssl/ex_data.h
+++ b/include/openssl/ex_data.h
@@ -129,11 +129,11 @@
 
 
 // Type-specific functions.
-//
-// Each type that supports ex_data provides three functions:
 
 #if 0  // Sample
 
+// Each type that supports ex_data provides three functions:
+
 // TYPE_get_ex_new_index allocates a new index for |TYPE|. An optional
 // |free_func| argument may be provided which is called when the owning object
 // is destroyed. See |CRYPTO_EX_free| for details. The |argl| and |argp|
@@ -153,6 +153,18 @@
 // previous call to |TYPE_get_ex_new_index|.
 OPENSSL_EXPORT void *TYPE_get_ex_data(const TYPE *t, int index);
 
+// Some types additionally preallocate index zero, with all callbacks set to
+// NULL. Applications that do not need the general ex_data machinery may use
+// this instead.
+
+// TYPE_set_app_data sets |t|'s application data pointer to |arg|. It returns
+// one on success and zero on error.
+OPENSSL_EXPORT int TYPE_set_app_data(TYPE *t, void *arg);
+
+// TYPE_get_app_data returns the application data pointer for |t|, or NULL if no
+// such pointer exists.
+OPENSSL_EXPORT void *TYPE_get_app_data(const TYPE *t);
+
 #endif  // Sample
 
 

include/openssl/x509.h

diff --git a/include/openssl/x509.h b/include/openssl/x509.h
index 008c0cb..38e367a 100644
--- a/include/openssl/x509.h
+++ b/include/openssl/x509.h
@@ -466,6 +466,22 @@
 // |OPENSSL_malloc|. If |sk| is NULL, no action is taken.
 OPENSSL_EXPORT void X509_email_free(STACK_OF(OPENSSL_STRING) *sk);
 
+// X509_cmp compares |a| and |b| and returns zero if they are equal, a negative
+// number if |b| sorts after |a| and a negative number if |a| sorts after |b|.
+// The sort order implemented by this function is arbitrary and does not
+// reflect properties of the certificate such as expiry. Applications should not
+// rely on the order itself.
+//
+// TODO(https://crbug.com/boringssl/355): This function works by comparing a
+// cached hash of the encoded certificate. If |a| or |b| could not be
+// serialized, the current behavior is to compare all unencodable certificates
+// as equal. This function should only be used with |X509| objects that were
+// parsed from bytes and never mutated.
+//
+// TODO(https://crbug.com/boringssl/407): This function is const, but it is not
+// always thread-safe, notably if |a| and |b| were mutated.
+OPENSSL_EXPORT int X509_cmp(const X509 *a, const X509 *b);
+
 
 // Issuing certificates.
 //
@@ -730,6 +746,18 @@
 // mutated.
 OPENSSL_EXPORT int i2d_X509_CRL(X509_CRL *crl, uint8_t **outp);
 
+// X509_CRL_match compares |a| and |b| and returns zero if they are equal, a
+// negative number if |b| sorts after |a| and a negative number if |a| sorts
+// after |b|. The sort order implemented by this function is arbitrary and does
+// not reflect properties of the CRL such as expiry. Applications should not
+// rely on the order itself.
+//
+// TODO(https://crbug.com/boringssl/355): This function works by comparing a
+// cached hash of the encoded CRL. This cached hash is computed when the CRL is
+// parsed, but not when mutating or issuing CRLs. This function should only be
+// used with |X509_CRL| objects that were parsed from bytes and never mutated.
+OPENSSL_EXPORT int X509_CRL_match(const X509_CRL *a, const X509_CRL *b);
+
 #define X509_CRL_VERSION_1 0
 #define X509_CRL_VERSION_2 1
 
@@ -3680,6 +3708,10 @@
                                               void *data);
 OPENSSL_EXPORT void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *ctx, int idx);
 
+#define X509_STORE_CTX_set_app_data(ctx, data) \
+  X509_STORE_CTX_set_ex_data(ctx, 0, data)
+#define X509_STORE_CTX_get_app_data(ctx) X509_STORE_CTX_get_ex_data(ctx, 0)
+
 
 // Hashing and signing ASN.1 structures.
 
@@ -4439,9 +4471,6 @@
 OPENSSL_EXPORT const char *X509_get_default_cert_file_env(void);
 OPENSSL_EXPORT const char *X509_get_default_private_dir(void);
 
-
-OPENSSL_EXPORT int X509_cmp(const X509 *a, const X509 *b);
-
 // X509_NAME_hash returns a hash of |name|, or zero on error. This is the new
 // hash used by |X509_LOOKUP_hash_dir|.
 //
@@ -4468,9 +4497,6 @@
 // value.
 OPENSSL_EXPORT uint32_t X509_NAME_hash_old(X509_NAME *name);
 
-OPENSSL_EXPORT int X509_CRL_match(const X509_CRL *a, const X509_CRL *b);
-
-
 /*
 SSL_CTX -> X509_STORE
                 -> X509_LOOKUP
@@ -4488,10 +4514,6 @@
 certificate chain.
 */
 
-#define X509_STORE_CTX_set_app_data(ctx, data) \
-  X509_STORE_CTX_set_ex_data(ctx, 0, data)
-#define X509_STORE_CTX_get_app_data(ctx) X509_STORE_CTX_get_ex_data(ctx, 0)
-
 #define X509_L_FILE_LOAD 1
 #define X509_L_ADD_DIR 2