[thirdparty/openssl.git] / doc / man3 / SMIME_read_PKCS7.pod

=pod

=head1 NAME

SMIME_read_PKCS7_ex, SMIME_read_PKCS7 - parse S/MIME message

=head1 SYNOPSIS

 #include <openssl/pkcs7.h>

 PKCS7 *SMIME_read_PKCS7_ex(BIO *bio, BIO **bcont, PKCS7 **p7);
 PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);

=head1 DESCRIPTION

SMIME_read_PKCS7() parses a message in S/MIME format.

B<in> is a BIO to read the message from.

If cleartext signing is used then the content is saved in
a memory bio which is written to B<*bcont>, otherwise
B<*bcont> is set to B<NULL>.

The parsed PKCS#7 structure is returned or B<NULL> if an
error occurred.

SMIME_read_PKCS7_ex() is similar to SMIME_read_PKCS7() but can optionally supply
a previously created I<p7> PKCS#7 object. If I<p7> is NULL then it is identical
to SMIME_read_PKCS7().
To create a I<p7> object use L<PKCS7_new_ex(3)>.

=head1 NOTES

If B<*bcont> is not B<NULL> then the message is clear text
signed. B<*bcont> can then be passed to PKCS7_verify() with
the B<PKCS7_DETACHED> flag set.

Otherwise the type of the returned structure can be determined
using PKCS7_type_is_enveloped(), etc.

To support future functionality if B<bcont> is not B<NULL>
B<*bcont> should be initialized to B<NULL>. For example:

 BIO *cont = NULL;
 PKCS7 *p7;

 p7 = SMIME_read_PKCS7(in, &cont);

=head1 BUGS

The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
While it will handle most S/MIME messages more complex compound
formats may not work.

The parser assumes that the PKCS7 structure is always base64
encoded and will not handle the case where it is in binary format
or uses quoted printable format.

The use of a memory BIO to hold the signed content limits the size
of message which can be processed due to memory restraints: a
streaming single pass option should be available.

=head1 RETURN VALUES

SMIME_read_PKCS7_ex() and SMIME_read_PKCS7() return a valid B<PKCS7> structure
or B<NULL> if an error occurred. The error can be obtained from ERR_get_error(3).

=head1 SEE ALSO

L<ERR_get_error(3)>,
L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>,
L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
L<PKCS7_decrypt(3)>

=head1 HISTORY

The function SMIME_read_PKCS7_ex() was added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
4e1b50e2 DSH	1	=pod
	2
	3	=head1 NAME
	4
90a1f2d7	5	SMIME_read_PKCS7_ex, SMIME_read_PKCS7 - parse S/MIME message
4e1b50e2 DSH	6
	7	=head1 SYNOPSIS
	8
c264592d UM	9	#include <openssl/pkcs7.h>
c264592d UM	10
90a1f2d7	11	PKCS7 SMIME_read_PKCS7_ex(BIO bio, BIO bcont, PKCS7 p7);
c264592d	12	PKCS7 SMIME_read_PKCS7(BIO in, BIO **bcont);
4e1b50e2 DSH	13
	14	=head1 DESCRIPTION
	15
	16	SMIME_read_PKCS7() parses a message in S/MIME format.
	17
	18	B<in> is a BIO to read the message from.
	19
	20	If cleartext signing is used then the content is saved in
	21	a memory bio which is written to B<*bcont>, otherwise
	22	B<*bcont> is set to B<NULL>.
	23
	24	The parsed PKCS#7 structure is returned or B<NULL> if an
	25	error occurred.
	26
90a1f2d7 SL	27	SMIME_read_PKCS7_ex() is similar to SMIME_read_PKCS7() but can optionally supply
	28	a previously created I<p7> PKCS#7 object. If I<p7> is NULL then it is identical
	29	to SMIME_read_PKCS7().
d8652be0	30	To create a I<p7> object use L<PKCS7_new_ex(3)>.
90a1f2d7	31
4e1b50e2 DSH	32	=head1 NOTES
	33
	34	If B<*bcont> is not B<NULL> then the message is clear text
	35	signed. B<*bcont> can then be passed to PKCS7_verify() with
	36	the B<PKCS7_DETACHED> flag set.
	37
	38	Otherwise the type of the returned structure can be determined
9e183d22	39	using PKCS7_type_is_enveloped(), etc.
4e1b50e2 DSH	40
	41	To support future functionality if B<bcont> is not B<NULL>
	42	B<*bcont> should be initialized to B<NULL>. For example:
	43
	44	BIO *cont = NULL;
	45	PKCS7 *p7;
	46
	47	p7 = SMIME_read_PKCS7(in, &cont);
	48
	49	=head1 BUGS
	50
	51	The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
	52	While it will handle most S/MIME messages more complex compound
	53	formats may not work.
	54
	55	The parser assumes that the PKCS7 structure is always base64
	56	encoded and will not handle the case where it is in binary format
	57	or uses quoted printable format.
	58
	59	The use of a memory BIO to hold the signed content limits the size
	60	of message which can be processed due to memory restraints: a
	61	streaming single pass option should be available.
	62
	63	=head1 RETURN VALUES
	64
90a1f2d7 SL	65	SMIME_read_PKCS7_ex() and SMIME_read_PKCS7() return a valid B<PKCS7> structure
90a1f2d7 SL	66	or B<NULL> if an error occurred. The error can be obtained from ERR_get_error(3).
4e1b50e2 DSH	67
	68	=head1 SEE ALSO
	69
9e183d22	70	L<ERR_get_error(3)>,
9b86974e RS	71	L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>,
	72	L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
	73	L<PKCS7_decrypt(3)>
4e1b50e2	74
90a1f2d7 SL	75	=head1 HISTORY
	76
	77	The function SMIME_read_PKCS7_ex() was added in OpenSSL 3.0.
	78
e2f92610 RS	79	=head1 COPYRIGHT
e2f92610 RS	80
90a1f2d7	81	Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	82
4746f25a	83	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	84	this file except in compliance with the License. You can obtain a copy
	85	in the file LICENSE in the source distribution or at
	86	L<https://www.openssl.org/source/license.html>.
	87
	88	=cut