1=pod
2
3=head1 NAME
4
5SMIME_read_ASN1_ex, SMIME_read_ASN1
6- parse S/MIME message
7
8=head1 SYNOPSIS
9
10 #include <openssl/asn1.h>
11
12 ASN1_VALUE *SMIME_read_ASN1_ex(BIO *in, int flags, BIO **bcont,
13                                const ASN1_ITEM *it, ASN1_VALUE **x,
14                                OSSL_LIB_CTX *libctx, const char *propq);
15 ASN1_VALUE *SMIME_read_ASN1(BIO *in, BIO **bcont, const ASN1_ITEM *it);
16
17=head1 DESCRIPTION
18
19SMIME_read_ASN1_ex() parses a message in S/MIME format.
20
21I<in> is a BIO to read the message from.
22If the I<flags> argument contains B<CMS_BINARY> then the input is assumed to be
23in binary format and is not translated to canonical form.
24If in addition B<SMIME_ASCIICRLF> is set then the binary input is assumed
25to be followed by B<CR> and B<LF> characters, else only by an B<LF> character.
26I<x> can be used to optionally supply
27a previously created I<it> ASN1_VALUE object (such as CMS_ContentInfo or PKCS7),
28it can be set to NULL. Valid values that can be used by ASN.1 structure I<it>
29are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo). Any algorithm
30fetches that occur during the operation will use the B<OSSL_LIB_CTX> supplied in
31the I<libctx> parameter, and use the property query string I<propq> See
32L<crypto(7)/ALGORITHM FETCHING> for further details about algorithm fetching.
33
34If cleartext signing is used then the content is saved in a memory bio which is
35written to I<*bcont>, otherwise I<*bcont> is set to NULL.
36
37The parsed ASN1_VALUE structure is returned or NULL if an error occurred.
38
39SMIME_read_ASN1() is similar to SMIME_read_ASN1_ex() but sets the value of I<x>
40to NULL and the value of I<flags> to 0.
41
42=head1 NOTES
43
44The higher level functions L<SMIME_read_CMS_ex(3)> and
45L<SMIME_read_PKCS7_ex(3)> should be used instead of SMIME_read_ASN1_ex().
46
47To support future functionality if I<bcont> is not NULL I<*bcont> should be
48initialized to NULL.
49
50=head1 BUGS
51
52The MIME parser used by SMIME_read_ASN1_ex() is somewhat primitive. While it will
53handle most S/MIME messages more complex compound formats may not work.
54
55The use of a memory BIO to hold the signed content limits the size of message
56which can be processed due to memory restraints: a streaming single pass option
57should be available.
58
59=head1 RETURN VALUES
60
61SMIME_read_ASN1_ex() and SMIME_read_ASN1() return a valid B<ASN1_VALUE>
62structure or B<NULL> if an error occurred. The error can be obtained from
63ERR_get_error(3).
64
65=head1 SEE ALSO
66
67L<ERR_get_error(3)>,
68L<SMIME_read_CMS_ex(3)>,
69L<SMIME_read_PKCS7_ex(3)>,
70L<SMIME_write_ASN1(3)>,
71L<SMIME_write_ASN1_ex(3)>
72
73=head1 HISTORY
74
75The function SMIME_read_ASN1_ex() was added in OpenSSL 3.0.
76
77=head1 COPYRIGHT
78
79Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
80
81Licensed under the Apache License 2.0 (the "License").  You may not use
82this file except in compliance with the License.  You can obtain a copy
83in the file LICENSE in the source distribution or at
84L<https://www.openssl.org/source/license.html>.
85
86=cut
87