Document the d2i object reuse changes in PORTING.md.
Change-Id: I1875c5246c7da19af13683ca36c737c188a97d18
Reviewed-on: https://boringssl-review.googlesource.com/6984
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/PORTING.md b/PORTING.md
index b3e50d7..f953e74 100644
--- a/PORTING.md
+++ b/PORTING.md
@@ -130,6 +130,23 @@
uppercase. Some code may require changes to avoid being sensitive to this
difference.
+### Legacy ASN.1 functions
+
+OpenSSL's ASN.1 stack uses `d2i` functions for parsing. They have the form:
+
+ RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len);
+
+In addition to returning the result, OpenSSL places it in `*out` if `out` is
+not `NULL`. On input, if `*out` is not `NULL`, OpenSSL will usually (but not
+always) reuse that object rather than allocating a new one. In BoringSSL, these
+functions are compatibility wrappers over a newer ASN.1 stack. Even if `*out`
+is not `NULL`, these wrappers will always allocate a new object and free the
+previous one.
+
+Ensure that callers do not rely on this object reuse behavior. It is
+recommended to avoid the `out` parameter completely and always pass in `NULL`.
+Note that less error-prone APIs are available for BoringSSL-specific code (see
+below).
## Optional BoringSSL-specific simplifications
@@ -162,3 +179,9 @@
these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the
corresponding Windows APIs internally and is always thread-safe where the API
guarantees it.
+
+### ASN.1
+
+BoringSSL is in the process of deprecating OpenSSL's `d2i` and `i2d` in favor of
+new functions using the much less error-prone `CBS` and `CBB` types.
+BoringSSL-only code should use those functions where available.
