Write new manual pages PKCS12_new(3) and PKCS12_SAFEBAG_new(3) from

scratch.  All these functions are listed in <openssl/pkcs12.h> and
in OpenSSL doc/man3/X509_dup.pod.  As usual, OpenSSL documentation
specifies the wrong header file.

Note that PKCS#12 documentation is still scanty at best.
For example, out of 19 public functions handling PKCS12 objects,
five are now documented, and this commit documents the first two
out of 24 public functions handling PKCS12_SAFEBAG objects.

4 files changed, 195 insertions, 6 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 39f9da37796..d76403010df 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.88 2016/12/22 14:06:51 schwarze Exp $
+# $OpenBSD: Makefile,v 1.89 2016/12/22 16:05:22 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -141,8 +141,10 @@ MAN=	\
 	PEM_read_bio_PrivateKey.3 \
 	PEM_write_bio_PKCS7_stream.3 \
 	PKCS12_create.3 \
+	PKCS12_new.3 \
 	PKCS12_newpass.3 \
 	PKCS12_parse.3 \
+	PKCS12_SAFEBAG_new.3 \
 	PKCS5_PBKDF2_HMAC.3 \
 	PKCS7_decrypt.3 \
 	PKCS7_encrypt.3 \
diff --git a/lib/libcrypto/man/PKCS12_SAFEBAG_new.3 b/lib/libcrypto/man/PKCS12_SAFEBAG_new.3
new file mode 100644
index 00000000000..8cb68351944
--- /dev/null
+++ b/lib/libcrypto/man/PKCS12_SAFEBAG_new.3
@@ -0,0 +1,92 @@
+.\"	$OpenBSD: PKCS12_SAFEBAG_new.3,v 1.1 2016/12/22 16:05:22 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 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: December 22 2016 $
+.Dt PKCS12_SAFEBAG_NEW 3
+.Os
+.Sh NAME
+.Nm PKCS12_SAFEBAG_new ,
+.Nm PKCS12_SAFEBAG_free ,
+.Nm PKCS12_BAGS_new ,
+.Nm PKCS12_BAGS_free
+.Nd PKCS#12 container for one piece of information
+.Sh SYNOPSIS
+.In openssl/pkcs12.h
+.Ft PKCS12_SAFEBAG *
+.Fn PKCS12_SAFEBAG_new void
+.Ft void
+.Fn PKCS12_SAFEBAG_free "PKCS12_SAFEBAG *safebag"
+.Ft PKCS12_BAGS *
+.Fn PKCS12_BAGS_new void
+.Ft void
+.Fn PKCS12_BAGS_free "PKCS12_BAGS *bag"
+.Sh DESCRIPTION
+.Fn PKCS12_SAFEBAG_new
+allocates and initializes an empty
+.Vt PKCS12_SAFEBAG
+object, representing an ASN.1 SafeBag structure
+defined in RFC 7292 section 4.2.
+It can hold a pointer to a
+.Vt PKCS12_BAGS
+object together with a type identifier and optional attributes.
+.Fn PKCS12_SAFEBAG_free
+frees
+.Fa safebag .
+.Pp
+.Fn PKCS12_BAGS_new
+allocates and initializes an empty
+.Vt PKCS12_BAGS
+object, representing the bagValue field of an ASN.1 SafeBag structure.
+It is used in
+.Vt PKCS12_SAFEBAG
+and can hold a DER-encoded X.509 certificate,
+a base64-encoded SDSI certificate,
+a DER-encoded X.509 CRL,
+or other user-defined information.
+.Pp
+If an instance of
+.Vt PKCS12_SAFEBAG
+contains
+.Vt PKCS8_PRIV_KEY_INFO ,
+.Vt X509_SIG ,
+or nested
+.Vt PKCS12_SAFEBAG
+objects, the respective pointers are stored directly in the
+.Vt PKCS12_SAFEBAG
+object rather than in the contained
+.Vt PKCS12_BAGS
+object as required by RFC 7292.
+.Sh RETURN VALUES
+.Fn PKCS12_SAFEBAG_new
+and
+.Fn PKCS12_BAGS_new
+return the new
+.Vt PKCS12_SAFEBAG
+or
+.Vt PKCS12_BAGS
+object, respectively, or
+.Dv NULL
+if an error occurs.
+.Sh SEE ALSO
+.Xr PKCS12_new 3 ,
+.Xr PKCS8_PRIV_KEY_INFO_new 3 ,
+.Xr X509_ATTRIBUTE_new 3 ,
+.Xr X509_CRL_new 3 ,
+.Xr X509_new 3 ,
+.Xr X509_SIG_new 3
+.Sh STANDARDS
+RFC 7292: PKCS #12: Personal Information Exchange Syntax,
+section 4.2: The SafeBag Type
diff --git a/lib/libcrypto/man/PKCS12_new.3 b/lib/libcrypto/man/PKCS12_new.3
new file mode 100644
index 00000000000..426074c9b1b
--- /dev/null
+++ b/lib/libcrypto/man/PKCS12_new.3
@@ -0,0 +1,87 @@
+.\"	$OpenBSD: PKCS12_new.3,v 1.1 2016/12/22 16:05:22 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 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: December 22 2016 $
+.Dt PKCS12_NEW 3
+.Os
+.Sh NAME
+.Nm PKCS12_new ,
+.Nm PKCS12_free ,
+.Nm PKCS12_MAC_DATA_new ,
+.Nm PKCS12_MAC_DATA_free
+.Nd PKCS#12 personal information exchange (PFX)
+.Sh SYNOPSIS
+.In openssl/pkcs12.h
+.Ft PKCS12 *
+.Fn PKCS12_new void
+.Ft void
+.Fn PKCS12_free "PKCS12 *pfx"
+.Ft PKCS12_MAC_DATA *
+.Fn PKCS12_MAC_DATA_new void
+.Ft void
+.Fn PKCS12_MAC_DATA_free "PKCS12_MAC_DATA *mac_data"
+.Sh DESCRIPTION
+.Fn PKCS12_new
+allocates and initializes an empty
+.Vt PKCS12
+object, representing an ASN.1 PFX (personal information exchange)
+structure defined in RFC 7292 section 4.
+It can hold a pointer to a
+.Vt PKCS7
+object described in
+.Xr PKCS7_new 3
+and optionally an instance of
+.Vt PKCS12_MAC_DATA
+described below.
+.Fn PKCS12_free
+frees
+.Fa pfx .
+.Pp
+.Fn PKCS12_MAC_DATA_new
+allocates and initializes an empty
+.Vt PKCS12_MAC_DATA
+object, representing an ASN.1 MacData structure
+defined in RFC 7292 section 4.
+It is used inside
+.Vt PKCS12
+and can hold a pointer to an
+.Vt X509_SIG
+object described in
+.Xr X509_SIG_new 3
+together with a salt value and an iteration count.
+.Fn PKCS12_MAC_DATA_free
+frees
+.Fa mac_data .
+.Sh RETURN VALUES
+.Fn PKCS12_new
+and
+.Fn PKCS12_MAC_DATA_new
+return the new
+.Vt PKCS12
+or
+.Vt PKCS12_MAC_DATA
+object, respectively, or
+.Dv NULL
+if an error occurs.
+.Sh SEE ALSO
+.Xr d2i_PKCS12 3 ,
+.Xr PKCS12_create 3 ,
+.Xr PKCS12_newpass 3 ,
+.Xr PKCS12_SAFEBAG_new 3 ,
+.Xr PKCS7_new 3 ,
+.Xr X509_SIG_new 3
+.Sh STANDARDS
+RFC 7292: PKCS #12: Personal Information Exchange Syntax
diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3
index 1410bd5c78a..49aa238da7f 100644
--- a/lib/libcrypto/man/X509_ATTRIBUTE_new.3
+++ b/lib/libcrypto/man/X509_ATTRIBUTE_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: X509_ATTRIBUTE_new.3,v 1.1 2016/12/17 14:51:09 schwarze Exp $
+.\"	$OpenBSD: X509_ATTRIBUTE_new.3,v 1.2 2016/12/22 16:05:22 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: December 17 2016 $
+.Dd $Mdocdate: December 22 2016 $
 .Dt X509_ATTRIBUTE_NEW 3
 .Os
 .Sh NAME
@@ -36,11 +36,15 @@ used to represent any kind of property of any kind of directory entry.
 In OpenSSL, very few objects use it directly, most notably the
 .Vt X509_REQ_INFO
 object used for PKCS#10 certification requests described in
-.Xr X509_REQ_new 3
-and the
+.Xr X509_REQ_new 3 ,
+the
 .Vt PKCS8_PRIV_KEY_INFO
 object used for PKCS#8 private key information described in
-.Xr PKCS8_PRIV_KEY_INFO_new 3 .
+.Xr PKCS8_PRIV_KEY_INFO_new 3 ,
+and the
+.Vt PKCS12_SAFEBAG
+container object described in
+.Xr PKCS12_SAFEBAG_new 3 .
 .Pp
 .Fn X509_ATTRIBUTE_new
 allocates and initializes an empty
@@ -57,6 +61,7 @@ object or
 .Dv NULL
 if an error occurs.
 .Sh SEE ALSO
+.Xr PKCS12_SAFEBAG_new 3 ,
 .Xr PKCS8_PRIV_KEY_INFO_new 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_REQ_new 3
@@ -72,6 +77,9 @@ section 4.1: CertificationRequestInfo
 .It For the specific use in the context of private key information:
 RFC 5208: Public-Key Cryptography Standards (PKCS) #8:
 Private-Key Information Syntax Specification
+.It For the specific definition in the context of PFX:
+RFC 7292: PKCS #12: Personal Information Exchange Syntax,
+section 4.2: The SafeBag Type
 .El
 .Sh BUGS
 A data type designed to hold arbitrary data is an oxymoron.