From 86b940df4e56667bb259c7d37d9a09cc6c1e1925 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 9 Jul 2021 12:07:27 +0000 Subject: new manual page for X509_keyid_set1(3), X509_keyid_get0(3), X509_alias_set1(3), X509_alias_get0(3) --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS12_create.3 | 7 +- src/lib/libcrypto/man/PKCS12_parse.3 | 7 +- src/lib/libcrypto/man/X509_CINF_new.3 | 5 +- src/lib/libcrypto/man/X509_keyid_set1.3 | 171 ++++++++++++++++++++++++++++++++ 5 files changed, 184 insertions(+), 9 deletions(-) create mode 100644 src/lib/libcrypto/man/X509_keyid_set1.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index ff7fc4fd95..bf76a1ce74 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.174 2021/07/08 12:30:27 schwarze Exp $ +# $OpenBSD: Makefile,v 1.175 2021/07/09 12:07:27 schwarze Exp $ .include @@ -316,6 +316,7 @@ MAN= \ X509_get0_notBefore.3 \ X509_get0_signature.3 \ X509_get1_email.3 \ + X509_keyid_set1.3 \ X509_new.3 \ X509_sign.3 \ X509_signature_dump.3 \ diff --git a/src/lib/libcrypto/man/PKCS12_create.3 b/src/lib/libcrypto/man/PKCS12_create.3 index 1b0af646ae..1f44ef9b67 100644 --- a/src/lib/libcrypto/man/PKCS12_create.3 +++ b/src/lib/libcrypto/man/PKCS12_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS12_create.3,v 1.9 2019/06/10 09:49:48 schwarze Exp $ +.\" $OpenBSD: PKCS12_create.3,v 1.10 2021/07/09 12:07:27 schwarze Exp $ .\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 .\" @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: July 9 2021 $ .Dt PKCS12_CREATE 3 .Os .Sh NAME @@ -168,7 +168,8 @@ if an error occurred. .Xr PKCS12_new 3 , .Xr PKCS12_newpass 3 , .Xr PKCS12_parse 3 , -.Xr PKCS12_SAFEBAG_new 3 +.Xr PKCS12_SAFEBAG_new 3 , +.Xr X509_keyid_set1 3 .Sh HISTORY .Fn PKCS12_create first appeared in OpenSSL 0.9.3 and has been available since diff --git a/src/lib/libcrypto/man/PKCS12_parse.3 b/src/lib/libcrypto/man/PKCS12_parse.3 index 3037c537d2..4e92d303c7 100644 --- a/src/lib/libcrypto/man/PKCS12_parse.3 +++ b/src/lib/libcrypto/man/PKCS12_parse.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS12_parse.3,v 1.6 2019/06/06 01:06:58 schwarze Exp $ +.\" $OpenBSD: PKCS12_parse.3,v 1.7 2021/07/09 12:07:27 schwarze Exp $ .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: July 9 2021 $ .Dt PKCS12_PARSE 3 .Os .Sh NAME @@ -121,7 +121,8 @@ The error can be obtained from .Sh SEE ALSO .Xr d2i_PKCS12 3 , .Xr PKCS12_create 3 , -.Xr PKCS12_new 3 +.Xr PKCS12_new 3 , +.Xr X509_keyid_set1 3 .Sh HISTORY .Fn PKCS12_parse first appeared in OpenSSL 0.9.3 and has been available since diff --git a/src/lib/libcrypto/man/X509_CINF_new.3 b/src/lib/libcrypto/man/X509_CINF_new.3 index 52d5acef6e..94fae2a49d 100644 --- a/src/lib/libcrypto/man/X509_CINF_new.3 +++ b/src/lib/libcrypto/man/X509_CINF_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_CINF_new.3,v 1.7 2021/07/08 12:30:27 schwarze Exp $ +.\" $OpenBSD: X509_CINF_new.3,v 1.8 2021/07/09 12:07:27 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 8 2021 $ +.Dd $Mdocdate: July 9 2021 $ .Dt X509_CINF_NEW 3 .Os .Sh NAME @@ -95,6 +95,7 @@ if an error occurs. .Sh SEE ALSO .Xr d2i_X509_CINF 3 , .Xr X509_add1_trust_object 3 , +.Xr X509_keyid_set1 3 , .Xr X509_new 3 .Sh STANDARDS RFC 5280: Internet X.509 Public Key Infrastructure Certificate and diff --git a/src/lib/libcrypto/man/X509_keyid_set1.3 b/src/lib/libcrypto/man/X509_keyid_set1.3 new file mode 100644 index 0000000000..a7733013bc --- /dev/null +++ b/src/lib/libcrypto/man/X509_keyid_set1.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: X509_keyid_set1.3,v 1.1 2021/07/09 12:07:27 schwarze Exp $ +.\" +.\" Copyright (c) 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 +.\" 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. +.\" +.Dd $Mdocdate: July 9 2021 $ +.Dt X509_KEYID_SET1 3 +.Os +.Sh NAME +.Nm X509_keyid_set1 , +.Nm X509_keyid_get0 , +.Nm X509_alias_set1 , +.Nm X509_alias_get0 +.Nd auxiliary certificate data for PKCS#12 +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_keyid_set1 +.Fa "X509 *x" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft unsigned char * +.Fo X509_keyid_get0 +.Fa "X509 *x" +.Fa "int *plen" +.Fc +.Ft int +.Fo X509_alias_set1 +.Fa "X509 *x" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft unsigned char * +.Fo X509_alias_get0 +.Fa "X509 *x" +.Fa "int *plen" +.Fc +.Sh DESCRIPTION +These functions store non-standard auxiliary data in +.Fa x +and retrieve it. +.Pp +The +.Fa len +bytes of +.Fa data +stored using +.Fn X509_keyid_set1 +will be written to the +.Sy friendlyName +attribute of the PKCS#12 structure if +.Xr PKCS12_create 3 +is later called on +.Fa x , +and the +.Fa data +stored using +.Fn X509_alias_set1 +will be written to the +.Sy localKeyID +attribute. +If +.Fa data +points to a NUL-terminated string, \-1 can be passed as the +.Fa len +argument to let +.Fa len +be calculated internally using +.Xr strlen 3 . +If a +.Dv NULL +pointer is passed as the +.Fa data +argument, the respective auxiliary data stored in +.Fa x , +if any, is removed from +.Fa x +and freed. +.Pp +Conversely, +.Xr PKCS12_parse 3 +retrieves these attributes from a PKCS#12 structure such that they can +subsequently be accessed with +.Fn X509_keyid_get0 +and +.Fn X509_alias_get0 . +Unless +.Dv NULL +is passed for the +.Fa plen +argument, these functions store the size of the returned buffer in bytes in +.Pf * Fa plen . +After the call, the returned buffer is not necessarily NUL-terminated, +but it may contain internal NUL bytes. +.Pp +API design is very incomplete; given the complexity of PKCS#12, +that's probably an asset rather than a defect. +The PKCS#12 standard defines many attributes that cannot be stored in +.Vt X509 +objects. +.Pp +To associate certificates with alternative names and key identifiers, +X.509 certificate extensions are more commonly used than PKCS#12 +attributes, for example using +.Xr X509_EXTENSION_create_by_NID 3 +with +.Dv NID_subject_alt_name +or +.Dv NID_subject_key_identifier . +.Sh RETURN VALUES +.Fn X509_keyid_set1 +and +.Fn X509_alias_set1 +return 1 if +.Fa data +is +.Dv NULL +or if the input +.Fa data +was successfully copied into +.Fa x , +or 0 if +.Fa data +is not +.Dv NULL +but could not be copied because +.Fa x +is +.Dv NULL +or memory allocation failed. +.Pp +.Fn X509_keyid_get0 +and +.Fn X509_alias_get0 +return an internal pointer to an array of bytes or +.Dv NULL +if +.Fa x +does not contain auxiliary data of the requested kind. +.Sh SEE ALSO +.Xr ASN1_STRING_set 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_alias_set1 +and +.Fn X509_alias_get0 +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509_keyid_set1 +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn X509_keyid_get0 +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . -- cgit v1.2.3-55-g6feb