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