In x509.h rev. 1.41 2018/02/22 17:22:02, jsing@ provided

X509_chain_up_ref(3).  Merge the documentation from OpenSSL,
tweaked by me.

diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index dbf82bc..2648a60 100644 (file)
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,8 +1,9 @@
-.\"    $OpenBSD: X509_new.3,v 1.10 2016/12/25 22:15:10 schwarze Exp $
-.\"    OpenSSL 3a59ad98 Dec 11 00:36:06 2015 +0000
+.\" $OpenBSD: X509_new.3,v 1.11 2018/02/26 15:38:39 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>.
-.\" Copyright (c) 2002, 2006, 2015 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2002, 2006, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,13 +49,14 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 25 2016 $
+.Dd $Mdocdate: February 26 2018 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
 .Nm X509_new ,
 .Nm X509_free ,
-.Nm X509_up_ref
+.Nm X509_up_ref ,
+.Nm X509_chain_up_ref
 .Nd X.509 certificate object
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -68,6 +70,10 @@
 .Fo X509_up_ref
 .Fa "X509 *a"
 .Fc
+.Ft STACK_OF(X509) *
+.Fo X509_chain_up_ref
+.Fa "STACK_OF(X509) *chain"
+.Fc
 .Sh DESCRIPTION
 .Fn X509_new
 allocates and initializes an empty
@@ -93,12 +99,24 @@ pointer, no action occurs.
 .Pp
 .Fn X509_up_ref
 increments the reference count of
-.Fa a .
+.Fa a
+by 1.
 This function is useful if a certificate structure is being used
 by several different operations each of which will free it up after
 use: this avoids the need to duplicate the entire certificate
 structure.
 .Pp
+.Fn X509_chain_up_ref
+performs a shallow copy of the given
+.Fa chain
+using
+.Fn sk_X509_dup
+and increments the reference count of each contained certificate
+by 1.
+Its purpose is similar to
+.Fn X509_up_ref :
+The returned chain persists after the original is freed.
+.Pp
 The object
 .Vt X509_INFO ,
 which can hold a certificate, the corresponding private key,
@@ -114,6 +132,13 @@ Otherwise it returns a pointer to the newly allocated structure.
 .Pp
 .Fn X509_up_ref
 returns 1 for success or 0 for failure.
+.Pp
+.Fn X509_chain_up_ref
+returns the copy of the
+.Fa chain
+or
+.Dv NULL
+if an error occurs.
 .Sh SEE ALSO
 .Xr AUTHORITY_KEYID_new 3 ,
 .Xr BASIC_CONSTRAINTS_new 3 ,