Write PKCS7_new(3) manual page from scratch. All the functions are

public: listed in <openssl/pkcs7.h> and OpenSSL doc/man3/X509_dup.pod.
Note that the OpenSSL documentation specifies the wrong header file.

2 files changed, 247 insertions, 1 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 300051f921..2c70b7ec37 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.75 2016/12/12 22:48:02 schwarze Exp $
+# $OpenBSD: Makefile,v 1.76 2016/12/13 14:31:55 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -145,6 +145,7 @@ MAN=	\
         PKCS5_PBKDF2_HMAC.3 \
         PKCS7_decrypt.3 \
         PKCS7_encrypt.3 \
+        PKCS7_new.3 \
         PKCS7_sign.3 \
         PKCS7_sign_add_signer.3 \
         PKCS7_verify.3 \
diff --git a/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3
new file mode 100644
index 0000000000..9feecbb88b
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_new.3
@@ -0,0 +1,245 @@
+.\"     $OpenBSD: PKCS7_new.3,v 1.1 2016/12/13 14:31:55 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 13 2016 $
+.Dt PKCS7_NEW 3
+.Os
+.Sh NAME
+.Nm PKCS7_new ,
+.Nm PKCS7_free ,
+.Nm PKCS7_SIGNED_new ,
+.Nm PKCS7_SIGNED_free ,
+.Nm PKCS7_ENVELOPE_new ,
+.Nm PKCS7_ENVELOPE_free ,
+.Nm PKCS7_SIGN_ENVELOPE_new ,
+.Nm PKCS7_SIGN_ENVELOPE_free ,
+.Nm PKCS7_DIGEST_new ,
+.Nm PKCS7_DIGEST_free ,
+.Nm PKCS7_ENCRYPT_new ,
+.Nm PKCS7_ENCRYPT_free ,
+.Nm PKCS7_ENC_CONTENT_new ,
+.Nm PKCS7_ENC_CONTENT_free ,
+.Nm PKCS7_SIGNER_INFO_new ,
+.Nm PKCS7_SIGNER_INFO_free ,
+.Nm PKCS7_RECIP_INFO_new ,
+.Nm PKCS7_RECIP_INFO_free ,
+.Nm PKCS7_ISSUER_AND_SERIAL_new ,
+.Nm PKCS7_ISSUER_AND_SERIAL_free
+.Nd PKCS#7 data structures
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft PKCS7 *
+.Fn PKCS7_new void
+.Ft void
+.Fn PKCS7_free "PKCS7 *p7"
+.Ft PKCS7_SIGNED *
+.Fn PKCS7_SIGNED_new void
+.Ft void
+.Fn PKCS7_SIGNED_free "PKCS7_SIGNED *signed"
+.Ft PKCS7_ENVELOPE *
+.Fn PKCS7_ENVELOPE_new void
+.Ft void
+.Fn PKCS7_ENVELOPE_free "PKCS7_ENVELOPE *envelope"
+.Ft PKCS7_SIGN_ENVELOPE *
+.Fn PKCS7_SIGN_ENVELOPE_new void
+.Ft void
+.Fn PKCS7_SIGN_ENVELOPE_free "PKCS7_SIGN_ENVELOPE *signed_envelope"
+.Ft PKCS7_DIGEST *
+.Fn PKCS7_DIGEST_new void
+.Ft void
+.Fn PKCS7_DIGEST_free "PKCS7_DIGEST *digested"
+.Ft PKCS7_ENCRYPT *
+.Fn PKCS7_ENCRYPT_new void
+.Ft void
+.Fn PKCS7_ENCRYPT_free "PKCS7_ENCRYPT *encrypted"
+.Ft PKCS7_ENC_CONTENT *
+.Fn PKCS7_ENC_CONTENT_new void
+.Ft void
+.Fn PKCS7_ENC_CONTENT_free "PKCS7_ENC_CONTENT *content"
+.Ft PKCS7_SIGNER_INFO *
+.Fn PKCS7_SIGNER_INFO_new void
+.Ft void
+.Fn PKCS7_SIGNER_INFO_free "PKCS7_SIGNER_INFO *signer"
+.Ft PKCS7_RECIP_INFO *
+.Fn PKCS7_RECIP_INFO_new void
+.Ft void
+.Fn PKCS7_RECIP_INFO_free "PKCS7_RECIP_INFO *recip"
+.Ft PKCS7_ISSUER_AND_SERIAL *
+.Fn PKCS7_ISSUER_AND_SERIAL_new void
+.Ft void
+.Fn PKCS7_ISSUER_AND_SERIAL_free "PKCS7_ISSUER_AND_SERIAL *cert"
+.Sh DESCRIPTION
+PKCS#7 is an ASN.1-based format for transmitting data that has
+cryptography applied to it, in particular signed and encrypted data.
+.Pp
+.Fn PKCS7_new
+allocates and initializes an empty
+.Vt PKCS7
+object, representing an ASN.1 ContentInfo structure
+defined in RFC 2315 section 7.
+It is the top-level data structure able to hold any kind of content
+that can be transmitted using PKCS#7.
+It can be used recursively in
+.Vt PKCS7_SIGNED
+and
+.Vt PKCS7_DIGEST
+objects.
+.Fn PKCS7_free
+frees
+.Fa p7 .
+.Pp
+.Fn PKCS7_SIGNED_new
+allocates and initializes an empty
+.Vt PKCS7_SIGNED
+object, representing an ASN.1 SignedData structure
+defined in RFC 2315 section 9.
+It can be used inside
+.Vt PKCS7
+objects and holds any kind of content together with signatures by
+zero or more signers and information about the signing algorithm
+and certificates used.
+.Fn PKCS7_SIGNED_free
+frees
+.Fa signed .
+.Pp
+.Fn PKCS7_ENVELOPE_new
+allocates and initializes an empty
+.Vt PKCS7_ENVELOPE
+object, representing an ASN.1 EnvelopedData structure
+defined in RFC 2315 section 10.
+It can be used inside
+.Vt PKCS7
+objects and holds any kind of encrypted content together with
+content-encryption keys for one or more recipients.
+.Fn PKCS7_ENVELOPE_free
+frees
+.Fa envelope .
+.Pp
+.Fn PKCS7_SIGN_ENVELOPE_new
+allocates and initializes an empty
+.Vt PKCS7_SIGN_ENVELOPE
+object, representing an ASN.1 SignedAndEnvelopedData structure
+defined in RFC 2315 section 11.
+It can be used inside
+.Vt PKCS7
+objects and holds any kind of encrypted content together with
+signatures by one or more signers, information about the signing
+algorithm and certificates used, and content-encryption keys for
+one or more recipients.
+.Fn PKCS7_SIGN_ENVELOPE_free
+frees
+.Fa signed_envelope .
+.Pp
+.Fn PKCS7_DIGEST_new
+allocates and initializes an empty
+.Vt PKCS7_DIGEST
+object, representing an ASN.1 DigestedData structure
+defined in RFC 2315 section 12.
+It can be used inside
+.Vt PKCS7
+objects and holds any kind of content together with a message digest
+for checking its integrity and information about the algorithm used.
+.Fn PKCS7_DIGEST_free
+frees
+.Fa digested .
+.Pp
+.Fn PKCS7_ENCRYPT_new
+allocates and initializes an empty
+.Vt PKCS7_ENCRYPT
+object, representing an ASN.1 EncryptedData structure
+defined in RFC 2315 section 13.
+It can be used inside
+.Vt PKCS7
+objects and holds any kind of encrypted content.
+Keys are not included and need to be communicated separately.
+.Fn PKCS7_ENCRYPT_free
+frees
+.Fa encrypted .
+.Pp
+.Fn PKCS7_ENC_CONTENT_new
+allocates and initializes an empty
+.Vt PKCS7_ENC_CONTENT
+object, representing an ASN.1 EncryptedContentInfo structure
+defined in RFC 2315 section 10.1.
+It can be used inside
+.Vt PKCS7_ENVELOPE ,
+.Vt PKCS7_SIGN_ENVELOPE ,
+and
+.Vt PKCS7_ENCRYPT
+objects and holds encrypted content together with information about
+the encryption algorithm used.
+.Fn PKCS7_ENC_CONTENT_free
+frees
+.Fa content .
+.Pp
+.Fn PKCS7_SIGNER_INFO_new
+allocates and initializes an empty
+.Vt PKCS7_SIGNER_INFO
+object, representing an ASN.1 SignerInfo structure
+defined in RFC 2315 section 9.2.
+It can be used inside
+.Vt PKCS7_SIGNED
+and
+.Vt PKCS7_SIGN_ENVELOPE
+objects and holds a signature together with information about the
+signer and the algorithms used.
+.Fn PKCS7_SIGNER_INFO_free
+frees
+.Fa signer .
+.Pp
+.Fn PKCS7_RECIP_INFO_new
+allocates and initializes an empty
+.Vt PKCS7_RECIP_INFO
+object, representing an ASN.1 RecipientInfo structure
+defined in RFC 2315 section 10.2.
+It can be used inside
+.Vt PKCS7_ENVELOPE
+and
+.Vt PKCS7_SIGN_ENVELOPE
+objects and holds a content-encryption key together with information
+about the intended recipient and the key encryption algorithm used.
+.Fn PKCS7_RECIP_INFO_free
+frees
+.Fa recip .
+.Pp
+.Fn PKCS7_ISSUER_AND_SERIAL_new
+allocates and initializes an empty
+.Vt PKCS7_ISSUER_AND_SERIAL
+object, representing an ASN.1 IssuerAndSerialNumber structure
+defined in RFC 2315 section 6.7.
+It can be used inside
+.Vt PKCS7_SIGNER_INFO
+and
+.Vt PKCS7_RECIP_INFO
+objects and identifies a certificate by holding the distinguished
+name of the certificate issuer and an issuer-specific certificate
+serial number.
+.Fn PKCS7_ISSUER_AND_SERIAL_free
+frees
+.Fa cert .
+.Sh SEE ALSO
+.Xr i2d_PKCS7_bio_stream 3 ,
+.Xr PEM_read_PKCS7 3 ,
+.Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PKCS7_decrypt 3 ,
+.Xr PKCS7_encrypt 3 ,
+.Xr PKCS7_sign 3 ,
+.Xr PKCS7_sign_add_signer 3 ,
+.Xr PKCS7_verify 3 ,
+.Xr SMIME_read_PKCS7 3 ,
+.Xr SMIME_write_PKCS7 3
+.Sh STANDARDS
+RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5