Commit 4b581a4666 for openssl.org

commit 4b581a4666c3e470a01a7323801b2ba8ccfa478c
Author: Bob Beck <beck@openssl.org>
Date:   Thu Aug 6 11:05:43 2026 -0600

    Add a migration entry for ASN1_STRINGs

    Re-document that ASN1_STRINGs are not NUL byte terminated, and
    have been documented as such for over 20 years.

    ASN1_STRING data has never been guaranteed to be NUL byte terminated.
    ASN1_STRING_set() added one anyway; its replacements do not, so code
    relying on UB, and treating it as a C string is more likely to break.

    Reviewed-by: Neil Horman <nhorman@openssl.org>
    Reviewed-by: Mounir Idrassi <mounir.idrassi@idrix.fr>
    Reviewed-by: Norbert Pocs <norbertp@openssl.org>
    Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
    Merge-date: Fri Sep  4 17:35:40 2026
    Merged-from: https://github.com/openssl/openssl/pull/32233

diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod
index fbf0ce6629..6bd27323ee 100644
--- a/doc/man7/ossl-guide-migration.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -60,6 +60,34 @@ by registering a handler for B<TLSEXT_TYPE_padding> with
 L<SSL_CTX_add_custom_ext(3)>. Registering a handler for this extension type
 was previously refused.

+=head3 B<ASN1_STRING> values have never been NUL byte terminated
+
+The bytes returned by L<ASN1_STRING_get0_data(3)> have never been guaranteed to
+be NUL byte terminated, and the documentation has said so since 2002. Values
+constructed as pointers into parsed DER never have been. Applications treating
+them as C strings have always relied on behaviour that was never promised.
+
+Such code usually escaped consequences because ASN1_STRING_set() allocated one
+byte more than the requested length and wrote a NUL byte into it. That byte was
+never counted in the length reported by ASN1_STRING_length().
+
+ASN1_STRING_set() is now deprecated. Its replacements,
+L<ASN1_STRING_set1_data(3)> and L<ASN1_STRING_set1_string(3)>, allocate exactly
+the requested number of bytes and append nothing. This includes
+ASN1_STRING_set1_string(): it takes a NUL byte terminated C string, but does not
+store the terminator.
+
+Applications must use the data only together with its length, obtained from
+L<ASN1_STRING_get_length(3)>, and never derive the length from the data.
+Applications should be cautious of passing a NULL data pointer when an
+B<ASN1_STRING> has a length of 0 to functions where this behaviour may be
+undefined.
+
+Applications which wish to use the content of an B<ASN1_STRING> as a C string
+should make a copy of the data, NUL byte terminate it, and when appropriate,
+sanitize it for embedded NUL bytes. They should never have been using the
+B<ASN1_STRING> data directly.
+
 =head1 OPENSSL 4.0

 =head2 Main Changes from OpenSSL 3.6