generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Reformat, fix typos and clarify CMS API docs.

Browse Source
This commit is contained in:
Dr. Stephen Henson 2008-04-10 23:28:25 +00:00
parent 73b3c2d861
commit 38d3a73808
20 changed files with 128 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/crypto/BIO_new_CMS.pod
View File

@ -13,28 +13,30 @@ BIO_new_CMS - CMS streaming filter BIO
=head1 DESCRIPTION =head1 DESCRIPTION
BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output
of the filter is written to B<out>. Any data written to the returned BIO of the filter is written to B<out>. Any data written to the chain is
is automatically translated to a BER format CMS structure. automatically translated to a BER format CMS structure of the appropriate type.
=head1 NOTES =head1 NOTES
The BIO returned by this functions behaves like a standard filter BIO. It The chain returned by this function behaves like a standard filter BIO. It
supports non blocking I/O. Content is processes and streamed on the fly and not supports non blocking I/O. Content is processed and streamed on the fly and not
all held in memory at once: so it is possible to encode very large structures. all held in memory at once: so it is possible to encode very large structures.
After all content has been written through the BIO BIO_flush() must be called After all content has been written through the chain BIO_flush() must be called
to finalise the structure. to finalise the structure.
The B<CMS_STREAM> flag must be included in the corresponding B<flags> The B<CMS_STREAM> flag must be included in the corresponding B<flags>
parameter of the B<cms> creation function. parameter of the B<cms> creation function.
After use BIOs should be removed from the filter using BIO_pop() until If an application wishes to write additional data to B<out> BIOs should be
the output BIO B<out> is reached. removed from the chain using BIO_pop() and freed with BIO_free() until B<out>
is reached. If no additional data needs to be written BIO_free_all() can be
called to free up the whole chain.
Any content written through the filter is uses "as-is" and no canonical Any content written through the filter is used verbatim: no canonical
translation is performed. translation is performed.
It is possible to chain multiple BIOs to for example create a triple wrapped It is possible to chain multiple BIOs to, for example, create a triple wrapped
signed, enveloped signed structure. In this case it is the applications signed, enveloped, signed structure. In this case it is the applications
responsibility to set the inner content type of any outer CMS_ContentInfo responsibility to set the inner content type of any outer CMS_ContentInfo
structures. structures.

21
doc/crypto/CMS_add0_cert.pod
View File

@ -18,16 +18,23 @@
=head1 DESCRIPTION =head1 DESCRIPTION
CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms> which CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
must be of type signed data or enveloped data. must be of type signed data or enveloped data.
CMS_get1_certs() returns all certificates in B<cms>. CMS_get1_certs() returns all certificates in B<cms>.
CMS_add0_crl() adds CRL B<crl> to B<cms> which must be of type signed data or CMS_add0_crl() adds CRL B<crl> to B<cms>. CMS_get1_crls() returns any CRLs in
enveloped data. CMS_get1_crls() returns any CRLs in B<cms>. B<cms>.
=head1 NOTES =head1 NOTES
The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
data or an error will be returned.
For signed data certificates and CRLs are added to the B<certificates> and
B<crls> fields of SignedData structure. For enveloped data they are added to
B<OriginatorInfo>.
As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
must not be freed up after the call as opposed to CMS_add1_cert() where B<cert> must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
must be freed up. must be freed up.
@ -35,10 +42,6 @@ must be freed up.
The same certificate or CRL must not be added to the same cms structure more The same certificate or CRL must not be added to the same cms structure more
than once. than once.
For signed data CMS types certificates and CRLs are added to the
B<certificates> and B<crls> fields of the SignedData structure. For enveloped
data they are added to B<OriginatorInfo>.
=head1 RETURN VALUES =head1 RETURN VALUES
CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() return 1 for success and CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() return 1 for success and
@ -50,7 +53,9 @@ in practice is if the B<cms> type is invalid.
=head1 SEE ALSO =head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)> L<ERR_get_error(3)|ERR_get_error(3)>,
L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY =head1 HISTORY

7
doc/crypto/CMS_add1_recipient_cert.pod
View File

@ -14,12 +14,11 @@
=head1 DESCRIPTION =head1 DESCRIPTION
CMS_add1_recipient_cert() adds a recipient certificate B<recip> CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
CMS_ContentInfo enveloped data structure B<cms> as a KeyTransRecipientInfo data structure B<cms> as a KeyTransRecipientInfo structure.
structure.
CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
wrapping algorithm B<nid>, identifier B<id> or length B<idlen> and optional wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
data structure B<cms> as a KEKRecipientInfo structure. data structure B<cms> as a KEKRecipientInfo structure.

4
doc/crypto/CMS_compress.pod
View File

@ -14,7 +14,7 @@ CMS_compress - create a CMS CompressedData structure
CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid> CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
is the compression algorithm to use or B<NID_undef> to use the default is the compression algorithm to use or B<NID_undef> to use the default
algorithms (zlib compression). B<in> is the content to be compressed. algorithm (zlib compression). B<in> is the content to be compressed.
B<flags> is an optional set of flags. B<flags> is an optional set of flags.
=head1 NOTES =head1 NOTES
@ -22,7 +22,7 @@ B<flags> is an optional set of flags.
The only currently supported compression algorithm is zlib using the NID The only currently supported compression algorithm is zlib using the NID
NID_zlib_compression. NID_zlib_compression.
If zlib support is not compiled into OpenSSL this CMS_compress() will return If zlib support is not compiled into OpenSSL then CMS_compress() will return
an error. an error.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are

9
doc/crypto/CMS_decrypt.pod
View File

@ -12,9 +12,9 @@ CMS_decrypt - decrypt content from a CMS envelopedData structure
=head1 DESCRIPTION =head1 DESCRIPTION
CMS_decrypt() extracts and decrypts the content from a CMS envelopedData CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
structure. B<pkey> is the private key of the recipient, B<cert> is the structure. B<pkey> is the private key of the recipient, B<cert> is the
recipients certificate, B<data> is a BIO to write the content to and recipient's certificate, B<data> is a BIO to write the content to and
B<flags> is an optional set of flags. B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the encrypted content The B<dcont> parameter is used in the rare case where the encrypted content
@ -34,8 +34,9 @@ example looking them up in a database) and setting them in the CMS structure
in advance using the CMS utility functions such as CMS_set1_pkey(). In this in advance using the CMS utility functions such as CMS_set1_pkey(). In this
case both B<cert> and B<pkey> should be set to NULL. case both B<cert> and B<pkey> should be set to NULL.
To process KEKRecipientInfo types CMS_set1_key() should be used and B<cert> To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
and B<pkey> set to NULL. and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and
B<cert> and B<pkey> set to NULL.
The following flags can be passed in the B<flags> parameter. The following flags can be passed in the B<flags> parameter.

12
doc/crypto/CMS_encrypt.pod
View File

@ -12,23 +12,19 @@ CMS_encrypt - create a CMS envelopedData structure
=head1 DESCRIPTION =head1 DESCRIPTION
CMS_encrypt() creates and returns a CMS envelopedData structure. B<certs> CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
is a list of recipient certificates. B<in> is the content to be encrypted. is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
=head1 NOTES =head1 NOTES
Only certificates carrying RSA keys are supported in CMS and envelopedData so Only certificates carrying RSA keys are supported so the recipient certificates
the recipient certificates supplied to this function must all contain RSA supplied to this function must all contain RSA public keys, though they do not
public keys, though they do not have to be signed using the RSA algorithm. have to be signed using the RSA algorithm.
EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
because most clients will support it. because most clients will support it.
Some old "export grade" clients may only support weak encryption using 40 or 64
bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc()
respectively.
The algorithm passed in the B<cipher> parameter must support ASN1 encoding of The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
its parameters. its parameters.

2
doc/crypto/CMS_get0_RecipientInfos.pod
View File

@ -24,7 +24,7 @@ CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_sig
=head1 DESCRIPTION =head1 DESCRIPTION
The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
structures associated with a CMS envelopedData structure. structures associated with a CMS EnvelopedData structure.
CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>. CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,

4
doc/crypto/CMS_get0_SignerInfos.pod
View File

@ -10,9 +10,7 @@ CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CM
STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
ASN1_OCTET_STRING **keyid,
X509_NAME **issuer, ASN1_INTEGER **sno);
int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);

5
doc/crypto/CMS_get1_ReceiptRequest.pod
View File

@ -62,7 +62,8 @@ L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>
=head1 HISTORY =head1 HISTORY
CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(),
added to OpenSSL 0.9.8 CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to
OpenSSL 0.9.8
=cut =cut

10
doc/crypto/CMS_sign.pod
View File

@ -54,8 +54,10 @@ will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted. omitted.
If present the SMIMECapabilities attribute indicates support for the following If present the SMIMECapabilities attribute indicates support for the following
algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
these algorithms is disabled then it will not be included. bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
not loaded.
OpenSSL will by default identify signing certificates using issuer name OpenSSL will by default identify signing certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
@ -92,13 +94,13 @@ The function CMS_sign() is a basic CMS signing function whose output will be
suitable for many purposes. For finer control of the output format the suitable for many purposes. For finer control of the output format the
B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
B<CMS_PARTIAL> flag set. Then one or more signers can be added using the B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
function B<CMS_sign_add1_signer()>, non default digests set and custom function CMS_sign_add1_signer(), non default digests can be used and custom
attributes added. B<CMS_final()> must then be called to finalize the attributes added. B<CMS_final()> must then be called to finalize the
structure if streaming is not enabled. structure if streaming is not enabled.
=head1 BUGS =head1 BUGS
Some advanced attributes such as counter signatures are not supported. Some attributes such as counter signatures are not supported.
=head1 RETURN VALUES =head1 RETURN VALUES

8
doc/crypto/CMS_sign_add1_signer.pod
View File

@ -16,12 +16,12 @@ int CMS_SignerInfo_sign(CMS_SignerInfo *si);
=head1 DESCRIPTION =head1 DESCRIPTION
CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private
key B<pkey> using message digest B<md> to CMS_ContentInfo signed data key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
structure B<cms>. structure B<cms>.
The CMS_ContentInfo structure should be obtained from an initial call to The CMS_ContentInfo structure should be obtained from an initial call to
CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
valid CMS_ContentInfo signed data structure. valid CMS_ContentInfo SignedData structure.
If the B<md> parameter is B<NULL> then the default digest for the public If the B<md> parameter is B<NULL> then the default digest for the public
key algorithm will be used. key algorithm will be used.
@ -36,7 +36,7 @@ are both set.
=head1 NOTES =head1 NOTES
The main purpose of this CMS_sign_add1_signer() is to provide finer control The main purpose of CMS_sign_add1_signer() is to provide finer control
over a CMS signed data structure where the simpler CMS_sign() function defaults over a CMS signed data structure where the simpler CMS_sign() function defaults
are not appropriate. For example if multiple signers or non default digest are not appropriate. For example if multiple signers or non default digest
algorithms are needed. New attributes can also be added using the returned algorithms are needed. New attributes can also be added using the returned
@ -63,7 +63,7 @@ the B<signcert> parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a the signers certificate can be obtained by other means: for example a
previously signed message. previously signed message.
The signedData structure includes several CMS signedAttributes including the The SignedData structure includes several CMS signedAttributes including the
signing time, the CMS content type and the supported list of ciphers in an signing time, the CMS content type and the supported list of ciphers in an
SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are

4
doc/crypto/CMS_uncompress.pod
View File

@ -21,8 +21,8 @@ is detached. It will normally be set to NULL.
=head1 NOTES =head1 NOTES
The only currently supported compression algorithm is zlib if the structure The only currently supported compression algorithm is zlib: if the structure
indicates the use of any other algorithm and error is returned. indicates the use of any other algorithm an error is returned.
If zlib support is not compiled into OpenSSL then CMS_uncompress() will always If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
return an error. return an error.

35
doc/crypto/CMS_verify.pod
View File

@ -16,15 +16,14 @@ CMS_verify - verify a CMS SignedData structure
CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
structure to verify. B<certs> is a set of certificates in which to search for structure to verify. B<certs> is a set of certificates in which to search for
the signer's certificate. B<store> is a trusted certificate store (used for the signing certificate(s). B<store> is a trusted certificate store used for
chain verification). B<indata> is the signed data if the content is not chain verification. B<indata> is the detached content if the content is not
present in B<cms> (that is it is detached). The content is written to B<out> present in B<cms>. The content is written to B<out> if it is not NULL.
if it is not NULL.
B<flags> is an optional set of flags, which can be used to modify the verify B<flags> is an optional set of flags, which can be used to modify the verify
operation. operation.
CMS_get0_signers() retrieves the signer's certificate(s) from B<cms>, it must CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
be called after a successful CMS_verify() operation. be called after a successful CMS_verify() operation.
=head1 VERIFY PROCESS =head1 VERIFY PROCESS
@ -35,15 +34,15 @@ Initially some sanity checks are performed on B<cms>. The type of B<cms> must
be SignedData. There must be at least one signature on the data and if be SignedData. There must be at least one signature on the data and if
the content is detached B<indata> cannot be B<NULL>. the content is detached B<indata> cannot be B<NULL>.
An attempt is made to locate all the signer's certificates, first looking in An attempt is made to locate all the signing certificate(s), first looking in
the B<certs> parameter (if it is not B<NULL>) and then looking in any the B<certs> parameter (if it is not NULL) and then looking in any
certificates contained in the B<cms> structure itself. If any signer's certificates contained in the B<cms> structure itself. If any signing
certificates cannot be located the operation fails. certificate cannot be located the operation fails.
Each signer's certificate is chain verified using the B<smimesign> purpose and Each signing certificate is chain verified using the B<smimesign> purpose and
the supplied trusted certificate store. Any internal certificates in the message the supplied trusted certificate store. Any internal certificates in the message
are used as untrusted CAs. If CRL checking is enabled in B<store> any internal are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
CRLs are used in addition to attempting to look the up in B<store>. If any CRLs are used in addition to attempting to look them up in B<store>. If any
chain verify fails an error code is returned. chain verify fails an error code is returned.
Finally the signed content is read (and written to B<out> is it is not NULL) Finally the signed content is read (and written to B<out> is it is not NULL)
@ -55,8 +54,8 @@ Any of the following flags (ored together) can be passed in the B<flags>
parameter to change the default verify behaviour. parameter to change the default verify behaviour.
If B<CMS_NOINTERN> is set the certificates in the message itself are not If B<CMS_NOINTERN> is set the certificates in the message itself are not
searched when locating the signer's certificate. This means that all the signers searched when locating the signing certificate(s). This means that all the
certificates must be in the B<certs> parameter. signing certificates must be in the B<certs> parameter.
If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
CRLs in the message itself are ignored. CRLs in the message itself are ignored.
@ -65,7 +64,7 @@ If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is from the content. If the content is not of type B<text/plain> then an error is
returned. returned.
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signer's certificates are not If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
verified. verified.
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
@ -103,18 +102,18 @@ timestamp).
CMS_verify() returns 1 for a successful verification and zero if an error CMS_verify() returns 1 for a successful verification and zero if an error
occurred. occurred.
CMS_get0_signers() returns all signers or B<NULL> if an error occurred. CMS_get0_signers() returns all signers or NULL if an error occurred.
The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 BUGS =head1 BUGS
The trusted certificate store is not searched for the signers certificate, The trusted certificate store is not searched for the signing certificate,
this is primarily due to the inadequacies of the current B<X509_STORE> this is primarily due to the inadequacies of the current B<X509_STORE>
functionality. functionality.
The lack of single pass processing and need to hold all data in memory as The lack of single pass processing means that the signed content must all
mentioned in CMS_sign() also applies to CMS_verify(). be held in memory if it is not detached.
=head1 SEE ALSO =head1 SEE ALSO

8
doc/crypto/CMS_verify_receipt.pod
View File

@ -2,7 +2,7 @@
=head1 NAME =head1 NAME
CMS_verify - verify a CMS signed receipt CMS_verify_receipt - verify a CMS signed receipt
=head1 SYNOPSIS =head1 SYNOPSIS
@ -14,8 +14,8 @@ CMS_verify - verify a CMS signed receipt
CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed
receipt to verify. B<ocms> is the original SignedData structure containing the receipt to verify. B<ocms> is the original SignedData structure containing the
receipt request B<certs> is a set of certificates in which to search for the receipt request. B<certs> is a set of certificates in which to search for the
signer's certificate. B<store> is a trusted certificate store (used for chain signing certificate. B<store> is a trusted certificate store (used for chain
verification). verification).
B<flags> is an optional set of flags, which can be used to modify the verify B<flags> is an optional set of flags, which can be used to modify the verify
@ -42,6 +42,6 @@ L<CMS_verify(3)|CMS_verify(3)>,
=head1 HISTORY =head1 HISTORY
CMS_verify() was added to OpenSSL 0.9.8 CMS_verify_receipt() was added to OpenSSL 0.9.8
=cut =cut

33
doc/crypto/SMIME_read_CMS.pod
View File

@ -16,24 +16,22 @@ SMIME_read_CMS() parses a message in S/MIME format.
B<in> is a BIO to read the message from. B<in> is a BIO to read the message from.
If cleartext signing is used then the content is saved in If cleartext signing is used then the content is saved in a memory bio which is
a memory bio which is written to B<*bcont>, otherwise written to B<*bcont>, otherwise B<*bcont> is set to NULL.
B<*bcont> is set to B<NULL>.
The parsed CMS_ContentInfo structure is returned or B<NULL> if an The parsed CMS_ContentInfo structure is returned or NULL if an
error occurred. error occurred.
=head1 NOTES =head1 NOTES
If B<*bcont> is not B<NULL> then the message is clear text If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can
signed. B<*bcont> can then be passed to CMS_verify() with then be passed to CMS_verify() with the B<CMS_DETACHED> flag set.
the B<CMS_DETACHED> flag set.
Otherwise the type of the returned structure can be determined Otherwise the type of the returned structure can be determined
using CMS_get0_type(). using CMS_get0_type().
To support future functionality if B<bcont> is not B<NULL> To support future functionality if B<bcont> is not NULL B<*bcont> should be
B<*bcont> should be initialized to B<NULL>. For example: initialized to NULL. For example:
BIO *cont = NULL; BIO *cont = NULL;
CMS_ContentInfo *cms; CMS_ContentInfo *cms;
@ -42,17 +40,16 @@ B<*bcont> should be initialized to B<NULL>. For example:
=head1 BUGS =head1 BUGS
The MIME parser used by SMIME_read_CMS() is somewhat primitive. The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will
While it will handle most S/MIME messages more complex compound handle most S/MIME messages more complex compound formats may not work.
formats may not work.
The parser assumes that the CMS_ContentInfo structure is always base64 The parser assumes that the CMS_ContentInfo structure is always base64 encoded
encoded and will not handle the case where it is in binary format and will not handle the case where it is in binary format or uses quoted
or uses quoted printable format. printable format.
The use of a memory BIO to hold the signed content limits the size The use of a memory BIO to hold the signed content limits the size of message
of message which can be processed due to memory restraints: a which can be processed due to memory restraints: a streaming single pass option
streaming single pass option should be available. should be available.
=head1 RETURN VALUES =head1 RETURN VALUES

27
doc/crypto/SMIME_write_CMS.pod
View File

@ -23,21 +23,20 @@ supplied in the B<data> argument. B<flags> is an optional set of flags.
The following flags can be passed in the B<flags> parameter. The following flags can be passed in the B<flags> parameter.
If B<CMS_DETACHED> is set then cleartext signing will be used, If B<CMS_DETACHED> is set then cleartext signing will be used, this option only
this option only makes sense for signedData where B<CMS_DETACHED> makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is
is also set when CMS_sign() is called. called.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to
are added to the content, this only makes sense if B<CMS_DETACHED> the content, this only makes sense if B<CMS_DETACHED> is also set.
is also set.
If the B<CMS_STREAM> flag is set streaming is performed. This flag should If the B<CMS_STREAM> flag is set streaming is performed. This flag should only
only be set if B<CMS_STREAM> was also set in the previous call to a be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo
CMS_ContentInfo creation function. creation function.
If cleartext signing is being used and B<CMS_STREAM> not set then If cleartext signing is being used and B<CMS_STREAM> not set then the data must
the data must be read twice: once to compute the signature in CMS_sign() be read twice: once to compute the signature in CMS_sign() and once to output
and once to output the S/MIME message. the S/MIME message.
If streaming is performed the content is output in BER format using indefinite If streaming is performed the content is output in BER format using indefinite
length constructed encoding except in the case of signed data with detached length constructed encoding except in the case of signed data with detached
@ -45,8 +44,8 @@ content where the content is absent and DER format is used.
=head1 BUGS =head1 BUGS
SMIME_write_CMS() always base64 encodes CMS structures, there SMIME_write_CMS() always base64 encodes CMS structures, there should be an
should be an option to disable this. option to disable this.
=head1 RETURN VALUES =head1 RETURN VALUES