1 files changed, 101 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/SMIME_read_PKCS7.3 b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
new file mode 100644
index 0000000000..2e7fcb514c
--- /dev/null
+++ b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
@@ -0,0 +1,101 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt SMIME_READ_PKCS7 3
+.Os
+.Sh NAME
+.Nm SMIME_read_PKCS7
+.Nd parse S/MIME message
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft PKCS7 *
+.Fo SMIME_read_PKCS7
+.Fa "BIO *in"
+.Fa "BIO **bcont"
+.Fc
+.Sh DESCRIPTION
+.Fn SMIME_read_PKCS7
+parses a message in S/MIME format.
+.Pp
+.Fa in
+is a
+.Vt BIO
+to read the message from.
+.Pp
+If cleartext signing is used, then the content is saved in a memory
+.Vt BIO
+which is written to
+.Pf * Fa bcont ,
+otherwise
+.Pf * Fa bcont
+is set to
+.Dv NULL .
+.Pp
+The parsed PKCS#7 structure is returned, or
+.Dv NULL
+if an error occurred.
+.Pp
+If
+.Pf * Fa bcont
+is not
+.Dv NULL ,
+then the message is clear text signed.
+.Pf * Fa bcont
+can then be passed to
+.Xr PKCS7_verify 3
+with the
+.Dv PKCS7_DETACHED
+flag set.
+.Pp
+Otherwise the type of the returned structure can be determined using
+.Xr PKCS7_type 3 .
+.Pp
+To support future functionality, if
+.Fa bcont
+is not
+.Dv NULL ,
+.Pf * Fa bcont
+should be initialized to
+.Dv NULL .
+For example:
+.Bd -literal -offset indent
+BIO *cont = NULL;
+PKCS7 *p7;
+p7 = SMIME_read_PKCS7(in, &cont);
+.Ed
+.Sh RETURN VALUES
+.Fn SMIME_read_PKCS7
+returns a valid
+.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 ,
+.Xr PKCS7_encrypt 3 ,
+.Xr PKCS7_sign 3 ,
+.Xr PKCS7_type 3 ,
+.Xr PKCS7_verify 3 ,
+.Xr SMIME_read_PKCS7 3
+.Sh HISTORY
+.Fn SMIME_read_PKCS7
+was added to OpenSSL 0.9.5.
+.Sh BUGS
+The MIME parser used by
+.Fn SMIME_read_PKCS7
+is somewhat primitive.
+While it will handle most S/MIME messages, more complex compound
+formats may not work.
+.Pp
+The parser assumes that the
+.Vt PKCS7
+structure is always base64 encoded, and it will not handle the case
+where it is in binary format or uses quoted printable format.
+.Pp
+The use of a memory
+.Vt BIO
+to hold the signed content limits the size of the message which can
+be processed due to memory restraints: a streaming single pass
+option should be available.

diff --git a/src/lib/libcrypto/man/SMIME_read_PKCS7.3 b/src/lib/libcrypto/man/SMIME_read_PKCS7.3 new file mode 100644 index 0000000000..2e7fcb514c --- /dev/null +++ b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
@@ -0,0 +1,101 @@
	1	.Dd $Mdocdate: November 3 2016 $
	2	.Dt SMIME_READ_PKCS7 3
	3	.Os
	4	.Sh NAME
	5	.Nm SMIME_read_PKCS7
	6	.Nd parse S/MIME message
	7	.Sh SYNOPSIS
	8	.In openssl/pkcs7.h
	9	.Ft PKCS7 *
	10	.Fo SMIME_read_PKCS7
	11	.Fa "BIO *in"
	12	.Fa "BIO **bcont"
	13	.Fc
	14	.Sh DESCRIPTION
	15	.Fn SMIME_read_PKCS7
	16	parses a message in S/MIME format.
	17	.Pp
	18	.Fa in
	19	is a
	20	.Vt BIO
	21	to read the message from.
	22	.Pp
	23	If cleartext signing is used, then the content is saved in a memory
	24	.Vt BIO
	25	which is written to
	26	.Pf * Fa bcont ,
	27	otherwise
	28	.Pf * Fa bcont
	29	is set to
	30	.Dv NULL .
	31	.Pp
	32	The parsed PKCS#7 structure is returned, or
	33	.Dv NULL
	34	if an error occurred.
	35	.Pp
	36	If
	37	.Pf * Fa bcont
	38	is not
	39	.Dv NULL ,
	40	then the message is clear text signed.
	41	.Pf * Fa bcont
	42	can then be passed to
	43	.Xr PKCS7_verify 3
	44	with the
	45	.Dv PKCS7_DETACHED
	46	flag set.
	47	.Pp
	48	Otherwise the type of the returned structure can be determined using
	49	.Xr PKCS7_type 3 .
	50	.Pp
	51	To support future functionality, if
	52	.Fa bcont
	53	is not
	54	.Dv NULL ,
	55	.Pf * Fa bcont
	56	should be initialized to
	57	.Dv NULL .
	58	For example:
	59	.Bd -literal -offset indent
	60	BIO *cont = NULL;
	61	PKCS7 *p7;
	62
	63	p7 = SMIME_read_PKCS7(in, &cont);
	64	.Ed
	65	.Sh RETURN VALUES
	66	.Fn SMIME_read_PKCS7
	67	returns a valid
	68	.Vt PKCS7
	69	structure or
	70	.Dv NULL
	71	if an error occurred.
	72	The error can be obtained from
	73	.Xr ERR_get_error 3 .
	74	.Sh SEE ALSO
	75	.Xr ERR_get_error 3 ,
	76	.Xr PKCS7_decrypt 3 ,
	77	.Xr PKCS7_encrypt 3 ,
	78	.Xr PKCS7_sign 3 ,
	79	.Xr PKCS7_type 3 ,
	80	.Xr PKCS7_verify 3 ,
	81	.Xr SMIME_read_PKCS7 3
	82	.Sh HISTORY
	83	.Fn SMIME_read_PKCS7
	84	was added to OpenSSL 0.9.5.
	85	.Sh BUGS
	86	The MIME parser used by
	87	.Fn SMIME_read_PKCS7
	88	is somewhat primitive.
	89	While it will handle most S/MIME messages, more complex compound
	90	formats may not work.
	91	.Pp
	92	The parser assumes that the
	93	.Vt PKCS7
	94	structure is always base64 encoded, and it will not handle the case
	95	where it is in binary format or uses quoted printable format.
	96	.Pp
	97	The use of a memory
	98	.Vt BIO
	99	to hold the signed content limits the size of the message which can
	100	be processed due to memory restraints: a streaming single pass
	101	option should be available.