提交 e33ffaca 编写于 作者: D Dr. Stephen Henson

Initial CMS API documentation.

上级 853eae51
=pod
=head1 NAME
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms> which
must be of type signed data or enveloped data.
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
enveloped data. CMS_get1_crls() returns any CRLs in B<cms>.
=head1 NOTES
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 be freed up.
The same certificate or CRL must not be added to the same cms structure more
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
CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() return 1 for success and
0 for failure.
CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
or NULL if there are none or an error occurs. The only error which will occur
in practice is if the B<cms> type is invalid.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
first added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType);
=head1 DESCRIPTION
CMS_add1_recipient_cert() adds a recipient certificate B<recip>
CMS_ContentInfo enveloped data structure B<cms> as a KeyTransRecipientInfo
structure.
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
values B<date>, B<otherTypeId> abd B<otherType> to CMS_ContentInfo enveloped
data structure B<cms> as a KEKRecipientInfo structure.
The CMS_ContentInfo structure should be obtained from an initial call to
CMS_encrypt() with the flag B<CMS_PARTIAL> set.
=head1 NOTES
The main purpose of this function is to provide finer control over a CMS
enveloped data structure where the simpler CMS_encrypt() function defaults are
not appropriate. For example if one or more KEKRecipientInfo structures
need to be added. New attributes can also be added using the returned
CMS_RecipientInfo structure and the CMS attribute utility functions.
OpenSSL will by default identify recipient certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if all recipient certificates do not
have a subject key identifier extension.
Currently only AES based key wrapping algorithms are supported for B<nid>,
specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
consistent with B<keylen>.
=head1 RETURN VALUES
CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
pointer to the CMS_RecipientInfo structure just added or NULL if an error
occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>,
L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL
0.9.8
=cut
=pod
=head1 NAME
CMS_decrypt - decrypt content from a CMS envelopedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *data, BIO *dcont, unsigned int flags);
=head1 DESCRIPTION
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
recipients certificate, B<data> is a BIO to write the content to and
B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the encrypted content
is detached. It will normally be set to NULL.
=head1 NOTES
OpenSSL_add_all_algorithms() (or equivalent) should be called before using this
function or errors about unknown algorithms will occur.
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the CMS
structure. If B<cert> is set to NULL all possible recipients are tried.
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and settin them in the CMS strutucre
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.
To process KEKRecipientInfo types CMS_set1_key() should be used and B<cert>
and B<pkey> set to NULL.
The following flags can be passed in the B<flags> parameter.
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
returned.
=head1 RETURN VALUES
CMS_decrypt() returns either 1 for success or 0 for failure.
The error can be obtained from ERR_get_error(3)
=head1 BUGS
The lack of single pass processing and need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decrypt().
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY
CMS_decrypt() was added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
CMS_encrypt - create a CMS envelopedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
=head1 DESCRIPTION
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.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
=head1 NOTES
Only certificates carrying RSA keys are supported in CMS and envelopedData so
the recipient certificates supplied to this function must all contain RSA
public keys, though they do not have to be signed using the RSA algorithm.
EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
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
its parameters.
Many browsers implement a "sign and encrypt" option which is simply an S/MIME
envelopedData containing an S/MIME signed message. This can be readily produced
by storing the S/MIME signed message in a memory BIO and passing it to
CMS_encrypt().
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
prepended to the data.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
B<CMS_TEXT> is ignored.
OpenSSL will by default identify recipient certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if all recipient certificates do not
have a subject key identifier extension.
If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
returned suitable for streaming I/O: no data is read from the BIO B<in>.
If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
returned to which additional recipients and attributes can be added before
finalization.
The data being encrypted is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
=head1 NOTES
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), d2i_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
The receipients specified in B<certs> use a CMS KeyTransRecipientInfo info
structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL>
and CMS_add0_recipient_key().
The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
=head1 RETURN VALUES
CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
=head1 HISTORY
CMS_decrypt() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag was first supported in OpenSSL 0.9.9.
=cut
=pod
=head1 NAME
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
=head1 SYNOPSIS
#include <openssl/cms.h>
STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si,
ASN1_OCTET_STRING **keyid,
X509_NAME **issuer, ASN1_INTEGER **sno);
int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
=head1 DESCRIPTION
The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
associated with a CMS signedData structure.
CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
associated with a specific CMS_SignerInfo structure B<si>. Either the
keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
in B<issuer> and B<sno>.
CMS_SignerInfo_cert_cmp() compares the cerificate B<cert> against the signer
identifier B<si>. It returns zero if the comparison is successful and non zero
if not.
CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
B<signer>.
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
signers certificates using any appropriate technique when the simpler method
of CMS_verify() is not appropriate.
In typical usage and application will retrieve all CMS_SignerInfo structures
using CMS_get0_SignerInfo() and retrieve the identifier information using
CMS. It will then obtain the signer certificate by some unspecified means
(or return and error if it cannot be found) and set it using
CMS_SignerInfo_set1_signer_cert().
Once all signer certificates have been set CMS_verify() can be used.
Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if
there are no signers this is not a problem in practice because the only
error which can occur is if the B<cms> structure is not of type signedData
due to application error.
=head1 RETURN VALUES
CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
are no signers or an error occurs.
CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
zero otherwise.
CMS_SignerInfo_set1_signer_cert() does not return a value.
Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
=head1 HISTORY
These functions were first was added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types
=head1 SYNOPSIS
#include <openssl/cms.h>
const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
and ASN1_OBJECT pointer. An application can then decide how to process the
CMS_ContentInfo strutucture based on this value.
CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
structure. It should be called with CMS functions with the B<CMS_PARTIAL>
flag and B<before> the strutucre is finalised, otherwise the results are
undefined.
ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
content type.
=head1 NOTES
As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal
pointers which should B<not> be freed up. CMS_set1_eContentType() copies the
supplied OID and it B<should> be freed up after use.
The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
using OBJ_obj2nid(). For the currently supported content types the following
values are returned:
NID_pkcs7_data
NID_pkcs7_signed
NID_pkcs7_digest
NID_id_smime_ct_compressedData:
NID_pkcs7_encrypted
NID_pkcs7_enveloped
=head1 RETURN VALUES
CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The
error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
first added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
CMS_sign - create a CMS signedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
=head1 DESCRIPTION
CMS_sign() creates and returns a CMS signedData structure. B<signcert> is
the certificate to sign with, B<pkey> is the corresponsding private key.
B<certs> is an optional additional set of certificates to include in the CMS
structure (for example any intermediate CAs in the chain). Any or all of
these parameters can be B<NULL>, see B<NOTES> below.
The data to be signed is read from BIO B<data>.
B<flags> is an optional set of flags.
=head1 NOTES
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
Many S/MIME clients expect the signed content to include valid MIME headers. If
the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
to the data.
If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
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
previously signed message.
The data being signed is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is used for
CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
messages for example.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it.
The signedData structure includes several CMS signedAttributes including the
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
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted.
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
these algorithms is disabled then it will not be included.
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
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
structure is just initialized ready to perform the signing operation. The
signing is however B<not> performed and the data to be signed is not read from
the B<data> parameter. Signing is deferred until after the data has been
written. In this way data can be signed in a single pass.
If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
output to which additional signers and capabilities can be added before
finalization.
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), d2i_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
If a signer is specified it will use the default digest for the signing
algorithm. This is B<SHA1> for both RSA and DSA keys.
If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
output.
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
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
function B<CMS_sign_add1_signer()>, non default digests set and custom
attributes added. B<CMS_final()> must then be called to finalize the
structure if streaming is not enabled.
=head1 BUGS
Some advanced attributes such as counter signatures are not supported.
=head1 RETURN VALUES
CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
=head1 HISTORY
CMS_sign() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
it is supportd for embedded data in OpenSSL 0.9.9 and later.
=cut
=pod
=head1 NAME
CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
int CMS_SignerInfo_sign(CMS_SignerInfo *si);
=head1 DESCRIPTION
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
structure B<cms>.
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
valid CMS_ContentInfo signed data structure.
If the B<md> parameter is B<NULL> then the default digest for the public
key algorithm will be used.
Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
structure is not complete and must be finalized either by streaming (if
applicable) or a call to CMS_final().
The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
are both set.
=head1 NOTES
The main purpose of this function is to provide finer control 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
algorithms are needed. New attributes can also be added using the returned
CMS_SignerInfo struture and the CMS attribute utility functions.
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
digest value from the CMS_ContentInfo struture: to add a signer to an existing
structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
B<CMS_SIGNER_INO> structure will not be finalized so additional attributes
can be added. In this case an explicit call to CMS_SignerInfo_Sign() is
needed to finalize it.
If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
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
previously signed message.
The signedData structure includes several CMS signedAttributes including the
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
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted.
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
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
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
these algorithms is disabled then it will not be included.
CMS_sign_add_signers() returns an internal pointer to the CMS_SIGNER_INFO
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo
structure just added or NULL if an error occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
PEM_sign_add_signer() was added to OpenSSL 0.9.9
=cut
=pod
=head1 NAME
CMS_verify - verify a CMS signedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
=head1 DESCRIPTION
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
the signer's certificate. B<store> is a trusted certficate store (used for
chain verification). B<indata> is the signed data if the content is not
present in B<cms> (that is it is detached). The content is written to B<out>
if it is not NULL.
B<flags> is an optional set of flags, which can be used to modify the verify
operation.
CMS_get0_signers() retrieves the signer's certificate(s) from B<cms>, it must
be called after a succeful CMS_verify() operation.
=head1 VERIFY PROCESS
Normally the verify process proceeds as follows.
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
the content is detached B<indata> cannot be B<NULL>.
An attempt is made to locate all the signer's certificates, first looking in
the B<certs> parameter (if it is not B<NULL>) and then looking in any
certificates contained in the B<cms> structure itself. If any signer's
certificates cannot be located the operation fails.
Each signer's certificate is chain verified using the B<smimesign> purpose and
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
CRLs are used in addition to attempting to look the up in B<store>. If any
chain verify fails an error code is returned.
Finally the signed content is read (and written to B<out> is it is not NULL)
and the signature's checked.
If all signature's verify correctly then the function is successful.
Any of the following flags (ored together) can be passed in the B<flags>
parameter to change the default verify behaviour.
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
certificates must be in the B<certs> parameter.
If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
CRLs in the message itself are ignored.
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
returned.
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signer's certificates are not
verified.
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
verified.
If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
=head1 NOTES
One application of B<CMS_NOINTERN> is to only accept messages signed by
a small number of certificates. The acceptable certificates would be passed
in the B<certs> parameter. In this case if the signer is not one of the
certificates supplied in B<certs> then the verify will fail because the
signer cannot be found.
In some cases the standard techniques for looking up and validating
certificates are not appropriate: for example an application may wish to
lookup certificates in a database or perform customised verification. This
can be achieved by setting and verifying the signers certificates manually
using the signed data utility functions.
Care should be taken when modifying the default verify behaviour, for example
setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
and any modified content will be considered valid. This combination is however
useful if one merely wishes to write the content to B<out> and its validity
is not considered important.
Chain verification should arguably be performed using the signing time rather
than the current time. However since the signing time is supplied by the
signer it cannot be trusted without additional evidence (such as a trusted
timestamp).
=head1 RETURN VALUES
CMS_verify() returns 1 for a successful verification and zero if an error
occured.
CMS_get0_signers() returns all signers or B<NULL> if an error occurred.
The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 BUGS
The trusted certificate store is not searched for the signers certificate,
this is primarily due to the inadequacies of the current B<X509_STORE>
functionality.
The lack of single pass processing and need to hold all data in memory as
mentioned in CMS_sign() also applies to CMS_verify().
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>
=head1 HISTORY
CMS_verify() was added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format.
=head1 SYNOPSIS
#include <openssl/cms.h>
#include <openssl/pem.h>
int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
=head1 DESCRIPTION
PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format.
It is otherwise identical to the function SMIME_write_CMS().
=head1 NOTES
This function is effectively a version of the PEM_write_bio_CMS() supporting
streaming.
=head1 RETURN VALUES
PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
L<CMS_decrypt(3)|CMS_decrypt(3)>,
L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>,
L<d2i_CMS_bio_stream(3)|d2i_CMS_bio_stream(3)>
=head1 HISTORY
PEM_write_bio_CMS_stream() was added to OpenSSL 0.9.9
=cut
=pod
=head1 NAME
SMIME_read_CMS - parse S/MIME message.
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
=head1 DESCRIPTION
SMIME_read_CMS() 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 CMS_ContentInfo structure is returned or B<NULL> if an
error occurred.
=head1 NOTES
If B<*bcont> is not B<NULL> then the message is clear text
signed. B<*bcont> can then be passed to CMS_verify() with
the B<CMS_DETACHED> flag set.
Otherwise the type of the returned structure can be determined
using CMS_get0_type().
To support future functionality if B<bcont> is not B<NULL>
B<*bcont> should be initialized to B<NULL>. For example:
BIO *cont = NULL;
CMS_ContentInfo *cms;
cms = SMIME_read_CMS(in, &cont);
=head1 BUGS
The MIME parser used by SMIME_read_CMS() is somewhat primitive.
While it will handle most S/MIME messages more complex compound
formats may not work.
The parser assumes that the CMS_ContentInfo 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_CMS() returns a valid B<CMS_ContentInfo> 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)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)>
L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
L<CMS_decrypt(3)|CMS_decrypt(3)>
=head1 HISTORY
SMIME_read_CMS() was added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
SMIME_write_CMS - convert CMS structure to S/MIME format.
=head1 SYNOPSIS
#include <openssl/cms.h>
int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
=head1 DESCRIPTION
SMIME_write_CMS() adds the appropriate MIME headers to a CMS
structure to produce an S/MIME message.
B<out> is the BIO to write the data to. B<cms> is the appropriate
B<CMS_ContentInfo> structure. If streaming is enabled then the content must be
supplied in the B<data> argument. B<flags> is an optional set of flags.
=head1 NOTES
The following flags can be passed in the B<flags> parameter.
If B<CMS_DETACHED> is set then cleartext signing will be used,
this option only makes sense for signedData where B<CMS_DETACHED>
is also set when CMS_sign() is called.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain>
are added to the content, this only makes sense if B<CMS_DETACHED>
is also set.
If the B<CMS_STREAM> flag is set streaming is performed. This flag should
only be set if B<CMS_STREAM> was also set in the previous call to a
CMS_ContentInfo creation function.
If cleartext signing is being used and B<CMS_STREAM> not set then
the data must be read twice: once to compute the signature in CMS_sign()
and once to output the S/MIME message.
If streaming is performed the content is output in BER format using indefinite
length constructuted encoding except in the case of signed data with detached
content where the content is absent and DER format is used.
=head1 BUGS
SMIME_write_CMS() always base64 encodes CMS structures, there
should be an option to disable this.
=head1 RETURN VALUES
SMIME_write_CMS() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
L<CMS_decrypt(3)|CMS_decrypt(3)>
=head1 HISTORY
SMIME_write_CMS() was added to OpenSSL 0.9.8
=cut
=pod
=head1 NAME
d2i_CMS_bio_stream - output CMS_ContentInfo structure in BER format.
=head1 SYNOPSIS
#include <openssl/cms.h>
int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
=head1 DESCRIPTION
i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format.
It is otherwise identical to the function SMIME_write_CMS().
=head1 NOTES
This function is effectively a version of the i2d_CMS_bio() supporting
streaming.
=head1 BUGS
The prefix "i2d" is arguably wrong because the function outputs BER format.
=head1 RETURN VALUES
i2d_CMS_bio_stream() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
L<CMS_decrypt(3)|CMS_decrypt(3)>,
L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>,
L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)>
=head1 HISTORY
d2i_CMS_bio_stream() was added to OpenSSL 0.9.9
=cut
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册