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>
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
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
