diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2008-04-08 22:27:10 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2008-04-08 22:27:10 +0000 |
commit | e33ffaca12c67a115142d9327405babd21718e97 (patch) | |
tree | 46bc035248002c47f9fa5d88642673b51a73a643 /doc/crypto/CMS_verify.pod | |
parent | 853eae51e0ef43d8079bbe1a56155db6f49f5624 (diff) |
Initial CMS API documentation.
Diffstat (limited to 'doc/crypto/CMS_verify.pod')
-rw-r--r-- | doc/crypto/CMS_verify.pod | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/doc/crypto/CMS_verify.pod b/doc/crypto/CMS_verify.pod new file mode 100644 index 0000000000..74c09e25fd --- /dev/null +++ b/doc/crypto/CMS_verify.pod @@ -0,0 +1,127 @@ +=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 |