1=pod
2
3=head1 NAME
4
5SMIME_read_PKCS7 - parse S/MIME message
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
12
13=head1 DESCRIPTION
14
15SMIME_read_PKCS7() parses a message in S/MIME format.
16
17B<in> is a BIO to read the message from.
18
19If cleartext signing is used then the content is saved in
20a memory bio which is written to B<*bcont>, otherwise
21B<*bcont> is set to B<NULL>.
22
23The parsed PKCS#7 structure is returned or B<NULL> if an
24error occurred.
25
26=head1 NOTES
27
28If B<*bcont> is not B<NULL> then the message is clear text
29signed. B<*bcont> can then be passed to PKCS7_verify() with
30the B<PKCS7_DETACHED> flag set.
31
32Otherwise the type of the returned structure can be determined
33using PKCS7_type_is_enveloped(), etc.
34
35To support future functionality if B<bcont> is not B<NULL>
36B<*bcont> should be initialized to B<NULL>. For example:
37
38 BIO *cont = NULL;
39 PKCS7 *p7;
40
41 p7 = SMIME_read_PKCS7(in, &cont);
42
43=head1 BUGS
44
45The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
46While it will handle most S/MIME messages more complex compound
47formats may not work.
48
49The parser assumes that the PKCS7 structure is always base64
50encoded and will not handle the case where it is in binary format
51or uses quoted printable format.
52
53The use of a memory BIO to hold the signed content limits the size
54of message which can be processed due to memory restraints: a
55streaming single pass option should be available.
56
57=head1 RETURN VALUES
58
59SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL>
60if an error occurred. The error can be obtained from ERR_get_error(3).
61
62=head1 SEE ALSO
63
64L<ERR_get_error(3)>,
65L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>,
66L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
67L<PKCS7_decrypt(3)>
68
69=head1 COPYRIGHT
70
71Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
72
73Licensed under the OpenSSL license (the "License").  You may not use
74this file except in compliance with the License.  You can obtain a copy
75in the file LICENSE in the source distribution or at
76L<https://www.openssl.org/source/license.html>.
77
78=cut
79