← Back to branch summary

~brian-sidebotham/openssl-cmake/1.0.1e

« back to all changes in this revision

Viewing changes to doc/crypto/SMIME_read_CMS.pod

  • Committer: Brian Sidebotham
  • Date: 2013-10-19 21:50:27 UTC
  • Revision ID: brian.sidebotham@gmail.com-20131019215027-yzoyh4svqj87uepu
Import OpenSSL 1.0.1e

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/crypto/SMIME_read_CMS.pod
 
1
=pod
 
2
 
 
3
=head1 NAME
 
4
 
 
5
 SMIME_read_CMS - parse S/MIME message.
 
6
 
 
7
=head1 SYNOPSIS
 
8
 
 
9
 #include <openssl/cms.h>
 
10
 
 
11
 CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
 
12
 
 
13
=head1 DESCRIPTION
 
14
 
 
15
SMIME_read_CMS() parses a message in S/MIME format.
 
16
 
 
17
B<in> is a BIO to read the message from.
 
18
 
 
19
If cleartext signing is used then the content is saved in a memory bio which is
 
20
written to B<*bcont>, otherwise B<*bcont> is set to NULL.
 
21
 
 
22
The parsed CMS_ContentInfo structure is returned or NULL if an
 
23
error occurred.
 
24
 
 
25
=head1 NOTES
 
26
 
 
27
If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can
 
28
then be passed to CMS_verify() with the B<CMS_DETACHED> flag set.
 
29
 
 
30
Otherwise the type of the returned structure can be determined
 
31
using CMS_get0_type().
 
32
 
 
33
To support future functionality if B<bcont> is not NULL B<*bcont> should be
 
34
initialized to NULL. For example:
 
35
 
 
36
 BIO *cont = NULL;
 
37
 CMS_ContentInfo *cms;
 
38
 
 
39
 cms = SMIME_read_CMS(in, &cont);
 
40
 
 
41
=head1 BUGS
 
42
 
 
43
The MIME parser used by SMIME_read_CMS() is somewhat primitive.  While it will
 
44
handle most S/MIME messages more complex compound formats may not work.
 
45
 
 
46
The parser assumes that the CMS_ContentInfo structure is always base64 encoded
 
47
and will not handle the case where it is in binary format or uses quoted
 
48
printable format.
 
49
 
 
50
The use of a memory BIO to hold the signed content limits the size of message
 
51
which can be processed due to memory restraints: a streaming single pass option
 
52
should be available.
 
53
 
 
54
=head1 RETURN VALUES
 
55
 
 
56
SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL>
 
57
if an error occurred. The error can be obtained from ERR_get_error(3).
 
58
 
 
59
=head1 SEE ALSO
 
60
 
 
61
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)>
 
62
L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>,
 
63
L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
 
64
L<CMS_decrypt(3)|CMS_decrypt(3)>
 
65
 
 
66
=head1 HISTORY
 
67
 
 
68
SMIME_read_CMS() was added to OpenSSL 0.9.8
 
69
 
 
70
=cut