From 9b779c0e9513364c0e4a0f40beb17632fb84d568 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 19 Jun 2020 14:31:29 +0000 Subject: document X509_get0_pubkey_bitstr(3), correct the description of X509_get_X509_PUBKEY(3), document error handling of the read accessors, and mention the relevant STANDARDS --- src/lib/libcrypto/man/X509_get_pubkey.3 | 86 +++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 5 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/X509_get_pubkey.3 b/src/lib/libcrypto/man/X509_get_pubkey.3 index 62367d8b0d..ad9c1ab0f5 100644 --- a/src/lib/libcrypto/man/X509_get_pubkey.3 +++ b/src/lib/libcrypto/man/X509_get_pubkey.3 @@ -1,7 +1,25 @@ -.\" $OpenBSD: X509_get_pubkey.3,v 1.7 2019/06/14 13:59:32 schwarze Exp $ +.\" $OpenBSD: X509_get_pubkey.3,v 1.8 2020/06/19 14:31:29 schwarze Exp $ .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" X509_REQ_get0_pubkey and X509_REQ_get_X509_PUBKEY not yet in LibreSSL .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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 +.\" 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 . .\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 14 2019 $ +.Dd $Mdocdate: June 19 2020 $ .Dt X509_GET_PUBKEY 3 .Os .Sh NAME @@ -56,6 +74,7 @@ .Nm X509_get0_pubkey , .Nm X509_set_pubkey , .Nm X509_get_X509_PUBKEY , +.Nm X509_get0_pubkey_bitstr , .Nm X509_REQ_get_pubkey , .Nm X509_REQ_set_pubkey .Nd get or set certificate or certificate request public key @@ -78,6 +97,10 @@ .Fo X509_get_X509_PUBKEY .Fa "X509 *x" .Fc +.Ft ASN1_BIT_STRING * +.Fo X509_get0_pubkey_bitstr +.Fa "const X509 *x" +.Fc .Ft EVP_PKEY * .Fo X509_REQ_get_pubkey .Fa "X509_REQ *req" @@ -103,13 +126,18 @@ so it must not be freed up after use. .Pp .Fn X509_get_X509_PUBKEY returns an internal pointer to the -.Vt X509_PUBKEY -structure which encodes the certificate of +.Vt SubjectPublicKeyInfo +structure contained in .Fa x . The returned value must not be freed up after use. .Fn X509_get_X509_PUBKEY is implemented as a macro. .Pp +.Fn X509_get0_pubkey_bitstr +returns an internal pointer to just the public key contained in this +.Vt SubjectPublicKeyInfo +structure, without the information about the algorithm used. +.Pp .Fn X509_set_pubkey attempts to set the public key for certificate .Fa x @@ -134,6 +162,7 @@ incremented to improve performance. .Fn X509_get_pubkey , .Fn X509_get0_pubkey , .Fn X509_get_X509_PUBKEY , +.Fn X509_get0_pubkey_bitstr , and .Fn X509_REQ_get_pubkey return a public key or @@ -153,6 +182,42 @@ and .Fn X509_REQ_set_pubkey , the reason can be determined with .Xr ERR_get_error 3 . +.Sh ERRORS +.Fn X509_get_pubkey , +.Fn X509_get0_pubkey , +and +.Fn X509_REQ_get_pubkey +provide diagnostics as documented for +.Xr X509_PUBKEY_get 3 . +If +.Fa x +or +.Fa req +is +.Dv NULL +or contains no certificate information, +they fail without pushing an error onto the stack. +.Pp +.Fn X509_get_X509_PUBKEY +provides no diagnostics and crashes by accessing a +.Dv NULL +pointer if +.Fa x +is +.Dv NULL +or contains no certificate information, +.Pp +.Fn X509_get0_pubkey_bitstr +provides no diagnostics +and fails without pushing an error onto the stack if +.Fa x +is +.Dv NULL , +but it crashes by accessing a +.Dv NULL +pointer if +.Fa x +contains no certificate information. .Sh SEE ALSO .Xr d2i_X509 3 , .Xr X509_CRL_get0_by_serial 3 , @@ -166,6 +231,13 @@ the reason can be determined with .Xr X509_sign 3 , .Xr X509_verify_cert 3 , .Xr X509V3_get_d2i 3 +.Sh STANDARDS +RFC 5280, Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile, +section 4.1 Basic Certificate Fields +.Pp +RFC 2986: PKCS #10: Certification Request Syntax Specification, +section 4.1 CertificationRequestInfo .Sh HISTORY .Fn X509_get_pubkey , .Fn X509_set_pubkey , @@ -178,6 +250,10 @@ first appeared in SSLeay 0.8.0. These functions have been available since .Ox 2.4 . .Pp +.Fn X509_get0_pubkey_bitstr +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.4 . +.Pp .Fn X509_get0_pubkey first appeared in OpenSSL 1.1.0 and has been available since .Ox 6.3 . -- cgit v1.2.3-55-g6feb