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