From a2de7e2db0d8ae02ae642a832c543499deda6540 Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 26 Oct 2021 10:01:23 +0000 Subject: [PATCH] document d2i_X509_PUBKEY(3) and i2d_X509_PUBKEY(3); while here, apply the usual conventions for naming d2i and i2d arguments --- lib/libcrypto/man/X509_PUBKEY_new.3 | 80 ++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 23 deletions(-) diff --git a/lib/libcrypto/man/X509_PUBKEY_new.3 b/lib/libcrypto/man/X509_PUBKEY_new.3 index 69afcb5adbd..648b028d5d2 100644 --- a/lib/libcrypto/man/X509_PUBKEY_new.3 +++ b/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 +.\" Copyright (c) 2020, 2021 Ingo Schwarze .\" .\" 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 -- 2.20.1