document d2i_X509_PUBKEY(3) and i2d_X509_PUBKEY(3);

while here, apply the usual conventions for naming d2i and i2d arguments

1 files changed, 57 insertions, 23 deletions

diff --git a/src/lib/libcrypto/man/X509_PUBKEY_new.3 b/src/lib/libcrypto/man/X509_PUBKEY_new.3
index 69afcb5adb..648b028d5d 100644
--- a/src/lib/libcrypto/man/X509_PUBKEY_new.3
+++ b/src/lib/libcrypto/man/X509_PUBKEY_new.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: X509_PUBKEY_new.3,v 1.16 2020/06/19 14:04:25 schwarze Exp $
+.\" $OpenBSD: X509_PUBKEY_new.3,v 1.17 2021/10/26 10:01:23 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2020, 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
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 19 2020 $
+.Dd $Mdocdate: October 26 2021 $
 .Dt X509_PUBKEY_NEW 3
 .Os
 .Sh NAME
@@ -74,6 +74,8 @@
 .Nm X509_PUBKEY_set ,
 .Nm X509_PUBKEY_get0 ,
 .Nm X509_PUBKEY_get ,
+.Nm d2i_X509_PUBKEY ,
+.Nm i2d_X509_PUBKEY ,
 .Nm d2i_PUBKEY ,
 .Nm i2d_PUBKEY ,
 .Nm d2i_PUBKEY_bio ,
@@ -104,36 +106,47 @@
 .Fo X509_PUBKEY_get
 .Fa "X509_PUBKEY *key"
 .Fc
+.Ft X509_PUBKEY *
+.Fo d2i_X509_PUBKEY
+.Fa "X509_PUBKEY **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_X509_PUBKEY
+.Fa "X509_PUBKEY *val_in"
+.Fa "unsigned char **der_out"
+.Fc
 .Ft EVP_PKEY *
 .Fo d2i_PUBKEY
-.Fa "EVP_PKEY **a"
-.Fa "const unsigned char **pp"
+.Fa "EVP_PKEY **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_PUBKEY
-.Fa "EVP_PKEY *a"
-.Fa "unsigned char **pp"
+.Fa "EVP_PKEY *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft EVP_PKEY *
 .Fo d2i_PUBKEY_bio
 .Fa "BIO *bp"
-.Fa "EVP_PKEY **a"
+.Fa "EVP_PKEY **val_out"
 .Fc
 .Ft EVP_PKEY *
 .Fo d2i_PUBKEY_fp
 .Fa "FILE *fp"
-.Fa "EVP_PKEY **a"
+.Fa "EVP_PKEY **val_out"
 .Fc
 .Ft int
 .Fo i2d_PUBKEY_fp
 .Fa "FILE *fp"
-.Fa "EVP_PKEY *pkey"
+.Fa "EVP_PKEY *val_in"
 .Fc
 .Ft int
 .Fo i2d_PUBKEY_bio
 .Fa "BIO *bp"
-.Fa "EVP_PKEY *pkey"
+.Fa "EVP_PKEY *val_in"
 .Fc
 .Ft int
 .Fo X509_PUBKEY_set0_param
@@ -202,14 +215,18 @@ count on the returned key is incremented so it must be freed using
 .Xr EVP_PKEY_free 3
 after use.
 .Pp
-.Fn d2i_PUBKEY
+.Fn d2i_X509_PUBKEY ,
+.Fn i2d_X509_PUBKEY ,
+.Fn d2i_PUBKEY ,
 and
 .Fn i2d_PUBKEY
-decode and encode an
-.Vt EVP_PKEY
-structure using
+decode and encode an ASN.1
 .Vt SubjectPublicKeyInfo
-format.
+structure using either the
+.Vt X509_PUBKEY
+or the
+.Vt EVP_PKEY
+object type, respectively.
 For details about the semantics, examples, caveats, and bugs, see
 .Xr ASN1_item_d2i 3 .
 .Fn d2i_PUBKEY_bio ,
@@ -217,7 +234,11 @@ For details about the semantics, examples, caveats, and bugs, see
 .Fn i2d_PUBKEY_bio
 and
 .Fn i2d_PUBKEY_fp
-are similar except they decode or encode using a
+are similar to
+.Fn d2i_PUBKEY
+and
+.Fn i2d_PUBKEY
+except they decode or encode using a
 .Vt BIO
 or
 .Vt FILE
@@ -267,20 +288,29 @@ and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 Otherwise it returns a pointer to the newly allocated structure.
 .Pp
-.Fn X509_PUBKEY_get0 ,
-.Fn X509_PUBKEY_get ,
+.Fn X509_PUBKEY_get0
+returns an internal pointer or
+.Dv NULL
+if an error occurs.
+.Pp
+.Fn X509_PUBKEY_get
+returns a pointer to an object that had its reference count incremented or
+.Dv NULL
+if an error occurs.
+.Pp
+.Fn d2i_X509_PUBKEY ,
 .Fn d2i_PUBKEY ,
 .Fn d2i_PUBKEY_bio ,
 and
 .Fn d2i_PUBKEY_fp
-return a pointer to an
-.Vt EVP_PKEY
-structure or
+return a pointer to a valid object or
 .Dv NULL
 if an error occurs.
 .Pp
+.Fn i2d_X509_PUBKEY
+and
 .Fn i2d_PUBKEY
-returns the number of bytes successfully encoded or a negative value
+return the number of bytes successfully encoded or a negative value
 if an error occurs.
 .Pp
 .Fn X509_PUBKEY_set ,
@@ -336,6 +366,10 @@ Certificate Revocation List (CRL) Profile
 and
 .Fn X509_PUBKEY_free
 appeared in SSLeay 0.4 or earlier.
+.Fn d2i_X509_PUBKEY
+and
+.Fn i2d_X509_PUBKEY
+first appeared in SSLeay 0.5.1.
 .Fn X509_PUBKEY_set
 and
 .Fn X509_PUBKEY_get