.\"	$OpenBSD: SMIME_read_PKCS7.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
.\"
.Dd $Mdocdate: November 6 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
.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.