From dea77bc59e31878e77451213221e449609879012 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Mon, 25 Oct 2021 10:26:21 +0000
Subject: [PATCH] document ASN1_STRING_set0(3)

---
 lib/libcrypto/man/ASN1_STRING_length.3 | 35 +++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/lib/libcrypto/man/ASN1_STRING_length.3 b/lib/libcrypto/man/ASN1_STRING_length.3
index 76679e27e96..27bb6632a5e 100644
--- a/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.21 2021/10/20 13:14:00 schwarze Exp $
-.\" full merge up to: OpenSSL 4a56d2a3 Feb 25 16:49:27 2018 +0300
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.22 2021/10/25 10:26:21 schwarze Exp $
+.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2018, 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 20 2021 $
+.Dd $Mdocdate: October 25 2021 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
@@ -78,6 +78,7 @@
 .Nm ASN1_STRING_get0_data ,
 .Nm ASN1_STRING_length ,
 .Nm ASN1_STRING_length_set ,
+.Nm ASN1_STRING_set0 ,
 .Nm ASN1_STRING_set ,
 .Nm ASN1_OCTET_STRING_set ,
 .Nm ASN1_STRING_to_UTF8 ,
@@ -120,6 +121,12 @@
 .Fa "ASN1_STRING *x"
 .Fa "int len"
 .Fc
+.Ft void
+.Fo ASN1_STRING_set0
+.Fa "ASN1_STRING *str"
+.Fa "void *data"
+.Fa "int len"
+.Fc
 .Ft int
 .Fo ASN1_STRING_set
 .Fa "ASN1_STRING *str"
@@ -188,6 +195,15 @@ It may put
 .Fa x
 into an inconsistent internal state.
 .Pp
+.Fn ASN1_STRING_set0
+frees any data stored in
+.Fa str ,
+sets the length attribute to
+.Fa len
+bytes, and sets the data attribute to
+.Fa data ,
+transferring ownership, without doing any validation.
+.Pp
 .Fn ASN1_STRING_set
 and
 .Fn ASN1_OCTET_STRING_set
@@ -198,7 +214,8 @@ to
 and copy that number of bytes from
 .Fa data
 into
-.Fa str .
+.Fa str ,
+overwriting any previous data.
 If
 .Fa len
 is -1, then
@@ -272,7 +289,9 @@ UTF-8 characters.
 .Pp
 Similar care should be taken to ensure the data is in the correct format
 when calling
-.Fn ASN1_STRING_set .
+.Fn ASN1_STRING_set
+or
+.Fn ASN1_STRING_set0 .
 .Sh RETURN VALUES
 .Fn ASN1_STRING_cmp
 and
@@ -354,6 +373,10 @@ first appeared in OpenSSL 0.9.5 and has been available since
 first appeared in OpenSSL 0.9.6 and has been available since
 .Ox 2.9 .
 .Pp
+.Fn ASN1_STRING_set0
+first appeared in OpenSSL 0.9.8h and has been available since
+.Ox 4.5 .
+.Pp
 .Fn ASN1_STRING_get0_data
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .
-- 
2.20.1