projects / thirdparty / openssl.git / blame
| Commit | Line | Data |
|---|---|---|
| dda4e259 SL |
1 | =pod |
| 2 | ||
| 3 | =head1 NAME | |
| 4 | ||
| 5 | SMIME_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, BIO **bcont, const ASN1_ITEM *it, | |
| 13 | ASN1_VALUE **x); | |
| 14 | ASN1_VALUE *SMIME_read_ASN1(BIO *in, BIO **bcont, const ASN1_ITEM *it); | |
| 15 | ||
| 16 | =head1 DESCRIPTION | |
| 17 | ||
| 18 | SMIME_read_ASN1_ex() parses a message in S/MIME format. | |
| 19 | ||
| 20 | I<in> is a BIO to read the message from. I<x> can be used to optionally supply | |
| 21 | a previously created I<it> ASN1_VALUE object (such as CMS_ContentInfo or PKCS7), | |
| 22 | it can be set to NULL. Valid values that can be used by ASN.1 structure I<it> | |
| 23 | are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo). | |
| 24 | ||
| 25 | If cleartext signing is used then the content is saved in a memory bio which is | |
| 26 | written to I<*bcont>, otherwise I<*bcont> is set to NULL. | |
| 27 | ||
| 28 | The parsed ASN1_VALUE structure is returned or NULL if an error occurred. | |
| 29 | ||
| 30 | SMIME_read_ASN1() is similar to SMIME_read_ASN1_ex() but sets the value of I<x> | |
| 31 | to NULL. | |
| 32 | ||
| 33 | =head1 NOTES | |
| 34 | ||
| 35 | The higher level functions L<SMIME_read_CMS_ex(3)> and | |
| 36 | L<SMIME_read_PKCS7_ex(3)> should be used instead of SMIME_read_ASN1_ex(). | |
| 37 | ||
| 38 | To support future functionality if I<bcont> is not NULL I<*bcont> should be | |
| 39 | initialized to NULL. | |
| 40 | ||
| 41 | =head1 BUGS | |
| 42 | ||
| 43 | The MIME parser used by SMIME_read_ASN1_ex() is somewhat primitive. While it will | |
| 44 | handle most S/MIME messages more complex compound formats may not work. | |
| 45 | ||
| 46 | The use of a memory BIO to hold the signed content limits the size of message | |
| 47 | which can be processed due to memory restraints: a streaming single pass option | |
| 48 | should be available. | |
| 49 | ||
| 50 | =head1 RETURN VALUES | |
| 51 | ||
| 52 | SMIME_read_ASN1_ex() and SMIME_read_ASN1() return a valid B<ASN1_VALUE> | |
| 53 | structure or B<NULL> if an error occurred. The error can be obtained from | |
| 54 | ERR_get_error(3). | |
| 55 | ||
| 56 | =head1 SEE ALSO | |
| 57 | ||
| 58 | L<ERR_get_error(3)>, | |
| 59 | L<SMIME_read_CMS_ex(3)>, | |
| 60 | L<SMIME_read_PKCS7_ex(3)>, | |
| 61 | L<SMIME_write_ASN1(3)>, | |
| d8652be0 | 62 | L<SMIME_write_ASN1_ex(3)> |
| dda4e259 SL |
63 | |
| 64 | =head1 HISTORY | |
| 65 | ||
| 66 | The function SMIME_read_ASN1_ex() was added in OpenSSL 3.0. | |
| 67 | ||
| 68 | =head1 COPYRIGHT | |
| 69 | ||
| 70 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
| 71 | ||
| 72 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
| 73 | this file except in compliance with the License. You can obtain a copy | |
| 74 | in the file LICENSE in the source distribution or at | |
| 75 | L<https://www.openssl.org/source/license.html>. | |
| 76 | ||
| 77 | =cut |