new manual page for X509_keyid_set1(3), X509_keyid_get0(3),

X509_alias_set1(3), X509_alias_get0(3)

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index ff7fc4f..bf76a1c 100644 (file)
--- a/lib/libcrypto/man/Makefile
+++ b/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 <bsd.own.mk>
 
@@ -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/lib/libcrypto/man/PKCS12_create.3 b/lib/libcrypto/man/PKCS12_create.3
index 1b0af64..1f44ef9 100644 (file)
--- a/lib/libcrypto/man/PKCS12_create.3
+++ b/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/lib/libcrypto/man/PKCS12_parse.3 b/lib/libcrypto/man/PKCS12_parse.3
index 3037c53..4e92d30 100644 (file)
--- a/lib/libcrypto/man/PKCS12_parse.3
+++ b/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 <steve@openssl.org>.
@@ -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/lib/libcrypto/man/X509_CINF_new.3 b/lib/libcrypto/man/X509_CINF_new.3
index 52d5ace..94fae2a 100644 (file)
--- a/lib/libcrypto/man/X509_CINF_new.3
+++ b/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 <schwarze@openbsd.org>
 .\"
@@ -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/lib/libcrypto/man/X509_keyid_set1.3 b/lib/libcrypto/man/X509_keyid_set1.3
new file mode 100644 (file)
index 0000000..a773301
--- /dev/null
+++ b/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 <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
+.\" 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 .