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.

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 @@
	1	.Dd $Mdocdate: November 3 2016 $
	2	.Dt PKCS7_ENCRYPT 3
	3	.Os
	4	.Sh NAME
	5	.Nm PKCS7_encrypt
	6	.Nd create a PKCS#7 envelopedData structure
	7	.Sh SYNOPSIS
	8	.In openssl/pkcs7.h
	9	.Ft PKCS7 *
	10	.Fo PKCS7_encrypt
	11	.Fa "STACK_OF(X509) *certs"
	12	.Fa "BIO *in"
	13	.Fa "const EVP_CIPHER *cipher"
	14	.Fa "int flags"
	15	.Fc
	16	.Sh DESCRIPTION
	17	.Fn PKCS7_encrypt
	18	creates and returns a PKCS#7 envelopedData structure.
	19	.Fa certs
	20	is a list of recipient certificates.
	21	.Fa in
	22	is the content to be encrypted.
	23	.Fa cipher
	24	is the symmetric cipher to use.
	25	.Fa flags
	26	is an optional set of flags.
	27	.Pp
	28	Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
	29	certificates supplied to this function must all contain RSA public keys,
	30	though they do not have to be signed using the RSA algorithm.
	31	.Pp
	32	The algorithm passed in the
	33	.Fa cipher
	34	parameter must support ASN1 encoding of its parameters.
	35	.Pp
	36	Many browsers implement a "sign and encrypt" option which is simply an
	37	S/MIME envelopedData containing an S/MIME signed message.
	38	This can be readily produced by storing the S/MIME signed message in a
	39	memory
	40	.Vt BIO
	41	and passing it to
	42	.Fn PKCS7_encrypt .
	43	.Pp
	44	The following flags can be passed in the
	45	.Fa flags
	46	parameter.
	47	.Pp
	48	If the
	49	.Dv PKCS7_TEXT
	50	flag is set, MIME headers for type
	51	.Sy text/plain
	52	are prepended to the data.
	53	.Pp
	54	Normally the supplied content is translated into MIME canonical format
	55	(as required by the S/MIME specifications).
	56	If
	57	.Dv PKCS7_BINARY
	58	is set, no translation occurs.
	59	This option should be used if the supplied data is in binary format;
	60	otherwise, the translation will corrupt it.
	61	If
	62	.Dv PKCS7_BINARY
	63	is set, then
	64	.Dv PKCS7_TEXT
	65	is ignored.
	66	.Pp
	67	If the
	68	.Dv PKCS7_STREAM
	69	flag is set, a partial
	70	.Vt PKCS7
	71	structure is output suitable for streaming I/O: no data is read from
	72	.Fa in .
	73	.Pp
	74	If the flag
	75	.Dv PKCS7_STREAM
	76	is set, the returned
	77	.Vt PKCS7
	78	structure is
	79	.Sy not
	80	complete and outputting its contents via a function that does not
	81	properly finalize the
	82	.Vt PKCS7
	83	structure will give unpredictable results.
	84	.Pp
	85	Several functions including
	86	.Xr SMIME_write_PKCS7 3 ,
	87	.Xr i2d_PKCS7_bio_stream 3 ,
	88	and
	89	.Xr PEM_write_bio_PKCS7_stream 3
	90	finalize the structure.
	91	Alternatively finalization can be performed by obtaining the streaming
	92	ASN1
	93	.Vt BIO
	94	directly using
	95	.Xr BIO_new_PKCS7 3 .
	96	.Sh RETURN VALUES
	97	.Fn PKCS7_encrypt
	98	returns either a
	99	.Vt PKCS7
	100	structure or
	101	.Dv NULL
	102	if an error occurred.
	103	The error can be obtained from
	104	.Xr ERR_get_error 3 .
	105	.Sh SEE ALSO
	106	.Xr ERR_get_error 3 ,
	107	.Xr PKCS7_decrypt 3
	108	.Sh HISTORY
	109	.Xr PKCS7_decrypt 3
	110	was added to OpenSSL 0.9.5.
	111	The
	112	.Dv PKCS7_STREAM
	113	flag was first supported in OpenSSL 1.0.0.