mirror of
https://github.com/openssl/openssl.git
synced 2024-11-21 01:15:20 +08:00
Reformat, fix typos and clarify CMS API docs.
This commit is contained in:
Dr. Stephen Henson
parent
73b3c2d861
commit
38d3a73808
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_new_CMS - CMS streaming filter BIO
|
||||
BIO_new_CMS - CMS streaming filter BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -13,28 +13,30 @@ BIO_new_CMS - CMS streaming filter BIO
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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
|
||||
is automatically translated to a BER format CMS structure.
|
||||
of the filter is written to B<out>. Any data written to the chain is
|
||||
automatically translated to a BER format CMS structure of the appropriate type.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The BIO returned by this functions behaves like a standard filter BIO. It
|
||||
supports non blocking I/O. Content is processes and streamed on the fly and not
|
||||
The chain returned by this function behaves like a standard filter BIO. It
|
||||
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.
|
||||
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.
|
||||
|
||||
The B<CMS_STREAM> flag must be included in the corresponding B<flags>
|
||||
parameter of the B<cms> creation function.
|
||||
|
||||
After use BIOs should be removed from the filter using BIO_pop() until
|
||||
the output BIO B<out> is reached.
|
||||
If an application wishes to write additional data to B<out> BIOs should be
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
responsibility to set the inner content type of any outer CMS_ContentInfo
|
||||
structures.
|
||||
|
||||
|
||||
@ -18,16 +18,23 @@
|
||||
|
||||
=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.
|
||||
|
||||
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>.
|
||||
CMS_add0_crl() adds CRL B<crl> to B<cms>. CMS_get1_crls() returns any CRLs in
|
||||
B<cms>.
|
||||
|
||||
=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
|
||||
must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
|
||||
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
|
||||
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
|
||||
@ -50,7 +53,9 @@ in practice is if the B<cms> type is invalid.
|
||||
|
||||
=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
|
||||
|
||||
|
||||
@ -14,12 +14,11 @@
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
CMS_add1_recipient_cert() adds a recipient certificate B<recip>
|
||||
CMS_ContentInfo enveloped data structure B<cms> as a KeyTransRecipientInfo
|
||||
structure.
|
||||
CMS_add1_recipient_cert() adds recipient B<recip> to 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
|
||||
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
|
||||
data structure B<cms> as a KEKRecipientInfo structure.
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ CMS_compress - create a CMS CompressedData structure
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
=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
|
||||
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.
|
||||
|
||||
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_decrypt - decrypt content from a CMS envelopedData structure
|
||||
CMS_decrypt - decrypt content from a CMS envelopedData structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -12,9 +12,9 @@ CMS_decrypt - decrypt content from a CMS envelopedData structure
|
||||
|
||||
=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
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
|
||||
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.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_encrypt - create a CMS envelopedData structure
|
||||
CMS_encrypt - create a CMS envelopedData structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -12,23 +12,19 @@ CMS_encrypt - create a CMS envelopedData structure
|
||||
|
||||
=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.
|
||||
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.
|
||||
Only certificates carrying RSA keys are supported 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.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_final - finalise a CMS_ContentInfo structure
|
||||
CMS_final - finalise a CMS_ContentInfo structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
|
||||
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -24,7 +24,7 @@ CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_sig
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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>.
|
||||
It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
|
||||
@ -76,7 +76,7 @@ In typical usage and application will retrieve all CMS_RecipientInfo structures
|
||||
using CMS_get0_RecipientInfos() and check the type of each using
|
||||
CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
|
||||
can be ignored or its key identifier data retrieved using an appropriate
|
||||
function. Then if the corresponding secret or private key can be obtained by
|
||||
function. Then if the corresponding secret or private key can be obtained by
|
||||
any appropriate means it can then associated with the structure and
|
||||
CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
|
||||
with a NULL key to decrypt the enveloped content.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
|
||||
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -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);
|
||||
|
||||
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si,
|
||||
ASN1_OCTET_STRING **keyid,
|
||||
X509_NAME **issuer, ASN1_INTEGER **sno);
|
||||
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);
|
||||
|
||||
|
||||
@ -8,10 +8,10 @@
|
||||
|
||||
#include <openssl/cms.h>
|
||||
|
||||
CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
|
||||
int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
|
||||
int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
|
||||
void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto);
|
||||
CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
|
||||
int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
|
||||
int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
|
||||
void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
@ -62,7 +62,8 @@ L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were
|
||||
added to OpenSSL 0.9.8
|
||||
CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(),
|
||||
CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to
|
||||
OpenSSL 0.9.8
|
||||
|
||||
=cut
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_sign - create a CMS SignedData structure
|
||||
CMS_sign - create a CMS SignedData structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -54,8 +54,10 @@ 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.
|
||||
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
|
||||
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
|
||||
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
|
||||
@ -92,18 +94,18 @@ 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
|
||||
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
|
||||
structure if streaming is not enabled.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Some advanced attributes such as counter signatures are not supported.
|
||||
Some 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).
|
||||
occurred. The error can be obtained from ERR_get_error(3).
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
|
||||
CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -10,18 +10,18 @@ CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo sig
|
||||
|
||||
CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
|
||||
|
||||
int CMS_SignerInfo_sign(CMS_SignerInfo *si);
|
||||
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
|
||||
key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
|
||||
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.
|
||||
valid CMS_ContentInfo SignedData structure.
|
||||
|
||||
If the B<md> parameter is B<NULL> then the default digest for the public
|
||||
key algorithm will be used.
|
||||
@ -36,7 +36,7 @@ are both set.
|
||||
|
||||
=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
|
||||
are not appropriate. For example if multiple signers or non default digest
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_sign_receipt - create a CMS signed receipt
|
||||
CMS_sign_receipt - create a CMS signed receipt
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_uncompress - uncompress a CMS CompressedData structure
|
||||
CMS_uncompress - uncompress a CMS CompressedData structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -21,8 +21,8 @@ is detached. It will normally be set to NULL.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The only currently supported compression algorithm is zlib if the structure
|
||||
indicates the use of any other algorithm and error is returned.
|
||||
The only currently supported compression algorithm is zlib: if the structure
|
||||
indicates the use of any other algorithm an error is returned.
|
||||
|
||||
If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
|
||||
return an error.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_verify - verify a CMS SignedData structure
|
||||
CMS_verify - verify a CMS SignedData structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -16,15 +16,14 @@ CMS_verify - verify a CMS SignedData structure
|
||||
|
||||
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 certificate 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.
|
||||
the signing certificate(s). B<store> is a trusted certificate store used for
|
||||
chain verification. B<indata> is the detached content if the content is not
|
||||
present in B<cms>. 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
|
||||
CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
|
||||
be called after a successful CMS_verify() operation.
|
||||
|
||||
=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
|
||||
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.
|
||||
An attempt is made to locate all the signing certificate(s), first looking in
|
||||
the B<certs> parameter (if it is not NULL) and then looking in any
|
||||
certificates contained in the B<cms> structure itself. If any signing
|
||||
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
|
||||
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.
|
||||
|
||||
Finally the signed content is read (and written to B<out> is it is not NULL)
|
||||
@ -54,9 +53,9 @@ 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_NOINTERN> is set the certificates in the message itself are not
|
||||
searched when locating the signing certificate(s). This means that all the
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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)>
|
||||
|
||||
=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>
|
||||
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().
|
||||
The lack of single pass processing means that the signed content must all
|
||||
be held in memory if it is not detached.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CMS_verify - verify a CMS signed receipt
|
||||
CMS_verify_receipt - verify a CMS signed receipt
|
||||
|
||||
=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
|
||||
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
|
||||
signer's certificate. B<store> is a trusted certificate store (used for chain
|
||||
receipt request. B<certs> is a set of certificates in which to search for the
|
||||
signing certificate. B<store> is a trusted certificate store (used for chain
|
||||
verification).
|
||||
|
||||
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
|
||||
|
||||
CMS_verify() was added to OpenSSL 0.9.8
|
||||
CMS_verify_receipt() was added to OpenSSL 0.9.8
|
||||
|
||||
=cut
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format.
|
||||
PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SMIME_read_CMS - parse S/MIME message.
|
||||
SMIME_read_CMS - parse S/MIME message.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -16,24 +16,22 @@ 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>.
|
||||
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 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.
|
||||
|
||||
=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.
|
||||
If B<*bcont> is not 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:
|
||||
To support future functionality if B<bcont> is not NULL B<*bcont> should be
|
||||
initialized to NULL. For example:
|
||||
|
||||
BIO *cont = NULL;
|
||||
CMS_ContentInfo *cms;
|
||||
@ -42,17 +40,16 @@ B<*bcont> should be initialized to B<NULL>. For example:
|
||||
|
||||
=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 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 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.
|
||||
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
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SMIME_write_CMS - convert CMS structure to S/MIME format.
|
||||
SMIME_write_CMS - convert CMS structure to S/MIME format.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
@ -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.
|
||||
|
||||
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 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_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 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 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 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
|
||||
|
||||
SMIME_write_CMS() always base64 encodes CMS structures, there
|
||||
should be an option to disable this.
|
||||
SMIME_write_CMS() always base64 encodes CMS structures, there should be an
|
||||
option to disable this.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format.
|
||||
i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user