SMIME_read_PKCS7.pod revision 337982 
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().
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)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)>
65L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
66L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
67L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
68
69=head1 HISTORY
70
71SMIME_read_PKCS7() was added to OpenSSL 0.9.5
72
73=cut
74