Document some more ASN1_ITEM-associated functions.

In doing so, fix ASN1_item_pack to not use the ASN1_OCTET_STRING
typedef. The function makes an untyped ASN1_STRING.

With all these caveats, one might think that ASN1_BOOLEAN ASN1_ITEMs are
pretty useless. This is about right. They're really only usable embedded
as a field in another struct.

Bug: 426
Change-Id: Id7830b91b2d011038ce79ec848e17ad6241423e1
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/49926
Reviewed-by: Adam Langley <agl@google.com>

crypto/asn1/asn_pack.c

diff --git a/crypto/asn1/asn_pack.c b/crypto/asn1/asn_pack.c
index 3c7116e..fd7ab4b 100644
--- a/crypto/asn1/asn_pack.c
+++ b/crypto/asn1/asn_pack.c
@@ -101,5 +101,6 @@
     p = oct->data;
     if (!(ret = ASN1_item_d2i(NULL, &p, oct->length, it)))
         OPENSSL_PUT_ERROR(ASN1, ASN1_R_DECODE_ERROR);
+    /* TODO(davidben): Check for trailing data. */
     return ret;
 }

include/openssl/asn1.h

diff --git a/include/openssl/asn1.h b/include/openssl/asn1.h
index a211019..0f12a5b 100644
--- a/include/openssl/asn1.h
+++ b/include/openssl/asn1.h
@@ -283,6 +283,66 @@
 OPENSSL_EXPORT int ASN1_item_i2d(ASN1_VALUE *val, unsigned char **outp,
                                  const ASN1_ITEM *it);
 
+// ASN1_item_dup returns a newly-allocated copy of |x|, or NULL on error. |x|
+// must be an object of |it|'s C type.
+//
+// This function may not be used with |ASN1_ITEM|s whose C type is
+// |ASN1_BOOLEAN|.
+//
+// WARNING: Casting the result of this function to the wrong type, or passing a
+// pointer of the wrong type into this function, are potentially exploitable
+// memory errors. Prefer using type-specific functions such as
+// |ASN1_STRING_dup|.
+OPENSSL_EXPORT void *ASN1_item_dup(const ASN1_ITEM *it, void *x);
+
+// The following functions behave like |ASN1_item_d2i| but read from |in|
+// instead. |out| is the same parameter as in |ASN1_item_d2i|, but written with
+// |void*| instead. The return values similarly match.
+//
+// These functions may not be used with |ASN1_ITEM|s whose C type is
+// |ASN1_BOOLEAN|.
+//
+// WARNING: These functions do not bound how much data is read from |in|.
+// Parsing an untrusted input could consume unbounded memory.
+OPENSSL_EXPORT void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *out);
+OPENSSL_EXPORT void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *out);
+
+// The following functions behave like |ASN1_item_i2d| but write to |out|
+// instead. |in| is the same parameter as in |ASN1_item_i2d|, but written with
+// |void*| instead.
+//
+// These functions may not be used with |ASN1_ITEM|s whose C type is
+// |ASN1_BOOLEAN|.
+OPENSSL_EXPORT int ASN1_item_i2d_fp(const ASN1_ITEM *it, FILE *out, void *in);
+OPENSSL_EXPORT int ASN1_item_i2d_bio(const ASN1_ITEM *it, BIO *out, void *in);
+
+// ASN1_item_unpack parses |oct|'s contents as |it|'s ASN.1 type. It returns a
+// newly-allocated instance of |it|'s C type on success, or NULL on error.
+//
+// This function may not be used with |ASN1_ITEM|s whose C type is
+// |ASN1_BOOLEAN|.
+//
+// WARNING: Casting the result of this function to the wrong type is a
+// potentially exploitable memory error. Callers must ensure the value is used
+// consistently with |it|.
+OPENSSL_EXPORT void *ASN1_item_unpack(const ASN1_STRING *oct,
+                                      const ASN1_ITEM *it);
+
+// ASN1_item_pack marshals |obj| as |it|'s ASN.1 type. If |out| is NULL, it
+// returns a newly-allocated |ASN1_STRING| with the result, or NULL on error.
+// If |out| is non-NULL, but |*out| is NULL, it does the same but additionally
+// sets |*out| to the result. If both |out| and |*out| are non-NULL, it writes
+// the result to |*out| and returns |*out| on success or NULL on error.
+//
+// This function may not be used with |ASN1_ITEM|s whose C type is
+// |ASN1_BOOLEAN|.
+//
+// WARNING: Passing a pointer of the wrong type into this function is a
+// potentially exploitable memory error. Callers must ensure |val| is consistent
+// with |it|.
+OPENSSL_EXPORT ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it,
+                                           ASN1_STRING **out);
+
 
 // Booleans.
 //
@@ -1474,22 +1534,6 @@
 OPENSSL_EXPORT int ASN1_put_eoc(unsigned char **pp);
 OPENSSL_EXPORT int ASN1_object_size(int constructed, int length, int tag);
 
-OPENSSL_EXPORT void *ASN1_item_dup(const ASN1_ITEM *it, void *x);
-
-OPENSSL_EXPORT void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
-OPENSSL_EXPORT int ASN1_item_i2d_fp(const ASN1_ITEM *it, FILE *out, void *x);
-
-OPENSSL_EXPORT void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);
-OPENSSL_EXPORT int ASN1_item_i2d_bio(const ASN1_ITEM *it, BIO *out, void *x);
-
-// Used to load and write netscape format cert
-
-OPENSSL_EXPORT void *ASN1_item_unpack(const ASN1_STRING *oct,
-                                      const ASN1_ITEM *it);
-
-OPENSSL_EXPORT ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it,
-                                           ASN1_OCTET_STRING **oct);
-
 // ASN1 template functions
 
 OPENSSL_EXPORT ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);