convert PEM and PKCS manuals from pod to mdoc

1 files changed, 113 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/PKCS7_encrypt.3 b/src/lib/libcrypto/man/PKCS7_encrypt.3
new file mode 100644
index 0000000000..860a9181b8
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_encrypt.3
@@ -0,0 +1,113 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt PKCS7_ENCRYPT 3
+.Os
+.Sh NAME
+.Nm PKCS7_encrypt
+.Nd create a PKCS#7 envelopedData structure
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft PKCS7 *
+.Fo PKCS7_encrypt
+.Fa "STACK_OF(X509) *certs"
+.Fa "BIO *in"
+.Fa "const EVP_CIPHER *cipher"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_encrypt
+creates and returns a PKCS#7 envelopedData structure.
+.Fa certs
+is a list of recipient certificates.
+.Fa in
+is the content to be encrypted.
+.Fa cipher
+is the symmetric cipher to use.
+.Fa flags
+is an optional set of flags.
+.Pp
+Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
+certificates supplied to this function must all contain RSA public keys,
+though they do not have to be signed using the RSA algorithm.
+.Pp
+The algorithm passed in the
+.Fa cipher
+parameter must support ASN1 encoding of its parameters.
+.Pp
+Many browsers implement a "sign and encrypt" option which is simply an
+S/MIME envelopedData containing an S/MIME signed message.
+This can be readily produced by storing the S/MIME signed message in a
+memory
+.Vt BIO
+and passing it to
+.Fn PKCS7_encrypt .
+.Pp
+The following flags can be passed in the
+.Fa flags
+parameter.
+.Pp
+If the
+.Dv PKCS7_TEXT
+flag is set, MIME headers for type
+.Sy text/plain
+are prepended to the data.
+.Pp
+Normally the supplied content is translated into MIME canonical format
+(as required by the S/MIME specifications).
+If
+.Dv PKCS7_BINARY
+is set, no translation occurs.
+This option should be used if the supplied data is in binary format;
+otherwise, the translation will corrupt it.
+If
+.Dv PKCS7_BINARY
+is set, then
+.Dv PKCS7_TEXT
+is ignored.
+.Pp
+If the
+.Dv PKCS7_STREAM
+flag is set, a partial
+.Vt PKCS7
+structure is output suitable for streaming I/O: no data is read from
+.Fa in .
+.Pp
+If the flag
+.Dv PKCS7_STREAM
+is set, the returned
+.Vt PKCS7
+structure is
+.Sy not
+complete and outputting its contents via a function that does not
+properly finalize the
+.Vt PKCS7
+structure will give unpredictable results.
+.Pp
+Several functions including
+.Xr SMIME_write_PKCS7 3 ,
+.Xr i2d_PKCS7_bio_stream 3 ,
+and
+.Xr PEM_write_bio_PKCS7_stream 3
+finalize the structure.
+Alternatively finalization can be performed by obtaining the streaming
+ASN1
+.Vt BIO
+directly using
+.Xr BIO_new_PKCS7 3 .
+.Sh RETURN VALUES
+.Fn PKCS7_encrypt
+returns either a
+.Vt PKCS7
+structure or
+.Dv NULL
+if an error occurred.
+The error can be obtained from
+.Xr ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr ERR_get_error 3 ,
+.Xr PKCS7_decrypt 3
+.Sh HISTORY
+.Xr PKCS7_decrypt 3
+was added to OpenSSL 0.9.5.
+The
+.Dv PKCS7_STREAM
+flag was first supported in OpenSSL 1.0.0.