document X509_dup(3)

1 files changed, 40 insertions, 8 deletions

diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index c7a62c22157..5920384ffa9 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: X509_new.3,v 1.20 2019/08/22 15:15:35 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.21 2019/08/23 09:41:49 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016, 2018, 2019 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2002, 2006, 2015, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -49,11 +66,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 22 2019 $
+.Dd $Mdocdate: August 23 2019 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
 .Nm X509_new ,
+.Nm X509_dup ,
 .Nm X509_free ,
 .Nm X509_up_ref ,
 .Nm X509_chain_up_ref
@@ -62,6 +80,10 @@
 .In openssl/x509.h
 .Ft X509 *
 .Fn X509_new void
+.Ft X509 *
+.Fo X509_dup
+.Fa "X509 *a"
+.Fc
 .Ft void
 .Fo X509_free
 .Fa "X509 *a"
@@ -85,6 +107,13 @@ structure defined in RFC 5280 section 4.1.
 It can hold a public key together with information about the person,
 organization, device, or function the associated private key belongs to.
 .Pp
+.Fn X509_dup
+creates a deep copy of
+.Fa a
+using
+.Xr ASN1_item_dup 3 ,
+setting the reference count of the copy to 1.
+.Pp
 .Fn X509_free
 decrements the reference count of the
 .Vt X509
@@ -117,13 +146,13 @@ Its purpose is similar to
 .Fn X509_up_ref :
 The returned chain persists after the original is freed.
 .Sh RETURN VALUES
-If the allocation fails,
 .Fn X509_new
-returns
+and
+.Fn X509_dup
+return a pointer to the newly allocated object or
 .Dv NULL
-and sets an error code that can be obtained by
+if an error occurs; an error code can be obtained by
 .Xr ERR_get_error 3 .
-Otherwise it returns a pointer to the newly allocated structure.
 .Pp
 .Fn X509_up_ref
 returns 1 for success or 0 for failure.
@@ -174,7 +203,10 @@ Certificate Revocation List (CRL) Profile
 .Fn X509_new
 and
 .Fn X509_free
-appeared in SSLeay 0.4 or earlier and have been available since
+appeared in SSLeay 0.4 or earlier.
+.Fn X509_dup
+first appeared in SSLeay 0.4.4.
+These functions have been available since
 .Ox 2.4 .
 .Pp
 .Fn X509_up_ref