In x509.h rev. 1.32 2018/02/20 17:09:20, jsing@ provided

X509_NAME_get0_der(3).  Document it without using anything
from the existing OpenSSL X509_NAME_get0_der(3) manual page
because that page fails to mention the similarity to i2d_X509_NAME(3)
and also fails to explain how both differ, likely causing users
to pick the wrong one for their purposes.

1 files changed, 28 insertions, 5 deletions

diff --git a/lib/libcrypto/man/d2i_X509_NAME.3 b/lib/libcrypto/man/d2i_X509_NAME.3
index 3dd337c4305..c1e7efddf13 100644
--- a/lib/libcrypto/man/d2i_X509_NAME.3
+++ b/lib/libcrypto/man/d2i_X509_NAME.3
@@ -1,7 +1,9 @@
-.\"	$OpenBSD: d2i_X509_NAME.3,v 1.10 2017/01/07 08:46:13 jmc Exp $
-.\"	OpenSSL d900a015 Oct 8 14:40:42 2015 +0200
+.\" $OpenBSD: d2i_X509_NAME.3,v 1.11 2018/02/22 21:53:23 schwarze Exp $
+.\" checked up to:
+.\" OpenSSL crypto/d2i_X509_NAME 4692340e Jun 7 15:49:08 2016 -0400 and
+.\" OpenSSL man3/X509_NAME_get0_der 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" Copyright (c) 2016, 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2016, 2017, 2018 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
@@ -15,12 +17,13 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 7 2017 $
+.Dd $Mdocdate: February 22 2018 $
 .Dt D2I_X509_NAME 3
 .Os
 .Sh NAME
 .Nm d2i_X509_NAME ,
 .Nm i2d_X509_NAME ,
+.Nm X509_NAME_get0_der ,
 .Nm X509_NAME_dup ,
 .Nm X509_NAME_hash ,
 .Nm d2i_X509_NAME_ENTRY ,
@@ -28,7 +31,7 @@
 .Nm X509_NAME_ENTRY_dup
 .\" In the following line, "X.501" and "Name" are not typos.
 .\" The "Name" type is defined in X.501, not in X.509.
-.\" The type in called "Name" with capital "N", not "name".
+.\" The type is called "Name" with capital "N", not "name".
 .Nd decode and encode X.501 Name objects
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -43,6 +46,12 @@
 .Fa "X509_NAME *val_in"
 .Fa "unsigned char **der_out"
 .Fc
+.Ft int
+.Fo X509_NAME_get0_der
+.Fa "X509_NAME *val_in"
+.Fa "const unsigned char **der_out"
+.Fa "size_t *out_len"
+.Fc
 .Ft X509_NAME *
 .Fo X509_NAME_dup
 .Fa "X509_NAME *val_in"
@@ -80,6 +89,17 @@ decode and encode an ASN.1
 .Vt Name
 structure defined in RFC 5280 section 4.1.2.4.
 .Pp
+.Fn X509_NAME_get0_der
+is a variant of
+.Fn i2d_X509_NAME
+that does not copy the encoded output but instead returns a pointer
+to the internally cached DER-encoded version of the name.
+Also, it does not return the length of the output in bytes,
+but instead stores it in
+.Fa out_len .
+If the cached encoded form happens to be out of date, both functions
+update it before copying it or returning a pointer to it.
+.Pp
 .Fn X509_NAME_dup
 copies
 .Fa val_in
@@ -121,6 +141,9 @@ object or
 .Dv NULL
 if an error occurs.
 .Pp
+.Fn X509_NAME_get0_der
+returns 1 on success or 0 if an error occurs.
+.Pp
 .Fn X509_NAME_hash
 returns the hash value or 0 if an error occurs.
 .Pp