Make deprecation of ASN1_STRING_data(3) more prominent

The function has been deprecated for a long time: OpenSSL did so when
adding ASN1_STRING_get0_data in 1.1.0. beck removed it from OpenSSL 4.
The reason is that it returns a modifiable "string" and you should not
be modifying an ASN1_STRING this way. You should be using one of the
clumsy, inconvenient accessors.

schwarze merged the deprecation when adding documentation for
ASN1_STRING_get0_data() in 2018. Make this a bit more obvious: move
function to the end of the documented functions in this page, and mark
it deprecated in the SYNOPSIS, too.

I'm aware that deprecation does not work. I was hopeful to be able to
remove the function in the last cycle, but that did not happen and it
might not happen in this cycle either. It will happen at some point,
though.

Prompted by a question by brad

1 files changed, 22 insertions, 19 deletions

diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3
index 922ae89ac6..96eb50e193 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.31 2025/06/08 22:37:23 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.32 2026/08/23 05:10:18 tb Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
@@ -66,13 +66,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 8 2025 $
+.Dd $Mdocdate: August 23 2026 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
 .Nm ASN1_STRING_cmp ,
 .Nm ASN1_OCTET_STRING_cmp ,
-.Nm ASN1_STRING_data ,
 .Nm ASN1_STRING_dup ,
 .Nm ASN1_OCTET_STRING_dup ,
 .Nm ASN1_STRING_get0_data ,
@@ -83,7 +82,8 @@
 .Nm ASN1_OCTET_STRING_set ,
 .Nm ASN1_STRING_copy ,
 .Nm ASN1_STRING_to_UTF8 ,
-.Nm ASN1_STRING_type
+.Nm ASN1_STRING_type ,
+.Nm ASN1_STRING_data
 .Nd ASN1_STRING utility functions
 .Sh SYNOPSIS
 .Lb libcrypto
@@ -98,10 +98,6 @@
 .Fa "const ASN1_OCTET_STRING *a"
 .Fa "const ASN1_OCTET_STRING *b"
 .Fc
-.Ft unsigned char *
-.Fo ASN1_STRING_data
-.Fa "ASN1_STRING *x"
-.Fc
 .Ft ASN1_STRING *
 .Fo ASN1_STRING_dup
 .Fa "const ASN1_STRING *a"
@@ -155,6 +151,13 @@
 .Fo ASN1_STRING_type
 .Fa "const ASN1_STRING *x"
 .Fc
+.Pp
+Deprecated:
+.Pp
+.Ft unsigned char *
+.Fo ASN1_STRING_data
+.Fa "ASN1_STRING *x"
+.Fc
 .Sh DESCRIPTION
 These functions manipulate
 .Vt ASN1_STRING
@@ -171,15 +174,6 @@ does exactly the same as
 .Fn ASN1_STRING_cmp
 without providing any type safety.
 .Pp
-.Fn ASN1_STRING_data
-is similar to
-.Fn ASN1_STRING_get0_data
-except that the returned value is not constant.
-This function is deprecated.
-Applications should use
-.Fn ASN1_STRING_get0_data
-instead.
-.Pp
 .Fn ASN1_STRING_dup
 allocates a new
 .Vt ASN1_STRING
@@ -283,6 +277,15 @@ is set in the return value,
 .Fa x
 is an ASN.1 INTEGER or ENUMERATED object with a negative value.
 .Pp
+.Fn ASN1_STRING_data
+is similar to
+.Fn ASN1_STRING_get0_data
+except that the returned value is not constant.
+This function is deprecated.
+Applications should use
+.Fn ASN1_STRING_get0_data
+instead.
+.Pp
 Almost all ASN.1 types are represented as
 .Vt ASN1_STRING
 structures.
@@ -341,9 +344,9 @@ In contrast to
 .Xr strcmp 3 ,
 the sign of the return value does not indicate lexicographical ordering.
 .Pp
-.Fn ASN1_STRING_data
-and
 .Fn ASN1_STRING_get0_data
+and
+.Fn ASN1_STRING_data
 return an internal pointer to the data of
 .Fa x .
 .Pp