Add inline documentation for API contracts (#3267)

### Issues:

Addresses P409219367

### Description of changes:

Adds clarifying comments to document existing API contracts that were
reviewed and determined to be working as designed:

- SSL session deserialization: document that session bytes are assumed
non-malleable
- BIO pair: document that concurrent free requires caller
synchronization
- BIO callbacks: document that callbacks must not free the BIO
- X509 thread safety: add general thread-safety note to the public
header

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license and the ISC license.

Author: nebeid

crypto/bio/pair.c

@@ -42,6 +42,10 @@ static int bio_new(BIO *bio) {
   return 1;
 }
 
+// bio_destroy_pair unlinks the two halves of a BIO pair. Concurrent calls to
+// BIO_free on both halves from separate threads are the caller's responsibility
+// to synchronize. As in OpenSSL, the BIO pair API does not provide internal
+// locking.
 static void bio_destroy_pair(BIO *bio) {
   struct bio_bio_st *b = bio->ptr;
   BIO *peer_bio;

include/openssl/bio.h

@@ -286,12 +286,15 @@ OPENSSL_EXPORT uint64_t BIO_number_read(const BIO *bio);
 // |bio|.
 OPENSSL_EXPORT uint64_t BIO_number_written(const BIO *bio);
 
-// BIO_set_callback_ex sets the |callback_ex| for |bio|.
+// BIO_set_callback_ex sets the |callback_ex| for |bio|. The callback is
+// invoked without incrementing the BIO's reference count, so a callback must
+// not call BIO_free on the BIO it is invoked on.
 OPENSSL_EXPORT void BIO_set_callback_ex(BIO *bio, BIO_callback_fn_ex callback_ex);
 
-// BIO_set_callback sets the legacy |callback| for |bio|. When both |callback| and
-// |callback_ex| are set, |callback_ex| will be used. Added for compatibility with
-// existing applications.
+// BIO_set_callback sets the legacy |callback| for |bio|. The same reference
+// count note as |BIO_set_callback_ex| applies. When both |callback| and
+// |callback_ex| are set, |callback_ex| will be used. Added for compatibility
+// with existing applications.
 OPENSSL_EXPORT OPENSSL_DEPRECATED void BIO_set_callback(BIO *bio, BIO_callback_fn callback);
 
 // BIO_set_callback_arg sets the callback |arg| for |bio|.

include/openssl/ssl.h

@@ -2037,7 +2037,9 @@ OPENSSL_EXPORT int SSL_SESSION_to_bytes_for_ticket(const SSL_SESSION *in,
                                                    size_t *out_len);
 
 // SSL_SESSION_from_bytes parses |in_len| bytes from |in| as an SSL_SESSION. It
-// returns a newly-allocated |SSL_SESSION| on success or NULL on error.
+// returns a newly-allocated |SSL_SESSION| on success or NULL on error. The
+// caller is responsible for protecting the integrity of the serialized session
+// data; no minimum-length validation is performed on individual fields.
 OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_from_bytes(const uint8_t *in,
                                                    size_t in_len,
                                                    const SSL_CTX *ctx);

include/openssl/x509.h

@@ -48,6 +48,11 @@ extern "C" {
 //
 // In the future, a replacement library will be available. Meanwhile, minimize
 // dependencies on this header where possible.
+//
+// Thread safety: Unlike other objects in this library, |X509| objects are not
+// yet safe for concurrent use by non-mutating functions (see
+// https://crbug.com/boringssl/407). Callers must not concurrently read and
+// mutate the same |X509| object without external synchronization.
 
 
 // Certificates.

ssl/ssl_asn1.cc

@@ -497,6 +497,10 @@ UniquePtr<SSL_SESSION> SSL_SESSION_parse(CBS *cbs,
     return nullptr;
   }
 
+  // Note: The secret field is validated only with an upper-bound check. A
+  // minimum-length check is intentionally omitted because the serialized
+  // session bytes are assumed to be non-malleable: the calling application is
+  // responsible for protecting the integrity of session data.
   CBS session_id, secret;
   if (!CBS_get_asn1(&session, &session_id, CBS_ASN1_OCTETSTRING) ||
       CBS_len(&session_id) > SSL3_MAX_SSL_SESSION_ID_LENGTH ||