From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/CMS_verify.pod | 131 +++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/CMS_verify.pod (limited to 'openssl-1.1.0h/doc/crypto/CMS_verify.pod') diff --git a/openssl-1.1.0h/doc/crypto/CMS_verify.pod b/openssl-1.1.0h/doc/crypto/CMS_verify.pod new file mode 100644 index 0000000..c2ff57b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_verify.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +CMS_verify, CMS_get0_signers - verify a CMS SignedData structure + +=head1 SYNOPSIS + + #include + + 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 is the CMS_ContentInfo +structure to verify. B is a set of certificates in which to search for +the signing certificate(s). B is a trusted certificate store used for +chain verification. B is the detached content if the content is not +present in B. The content is written to B if it is not NULL. + +B is an optional set of flags, which can be used to modify the verify +operation. + +CMS_get0_signers() retrieves the signing certificate(s) from B, it must +be called after a successful CMS_verify() operation. + +=head1 VERIFY PROCESS + +Normally the verify process proceeds as follows. + +Initially some sanity checks are performed on B. The type of B must +be SignedData. There must be at least one signature on the data and if +the content is detached B cannot be B. + +An attempt is made to locate all the signing certificate(s), first looking in +the B parameter (if it is not NULL) and then looking in any +certificates contained in the B structure itself. If any signing +certificate cannot be located the operation fails. + +Each signing certificate is chain verified using the B 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 any internal +CRLs are used in addition to attempting to look them up in B. If any +chain verify fails an error code is returned. + +Finally the signed content is read (and written to B 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 +parameter to change the default verify behaviour. + +If B 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 parameter. + +If B is set and CRL checking is enabled in B then any +CRLs in the message itself are ignored. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B then an error is +returned. + +If B is set the signing certificates are not +verified. + +If B is set the signed attributes signature is not +verified. + +If B is set then the content digest is not checked. + +=head1 NOTES + +One application of B is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B parameter. In this case if the signer is not one of the +certificates supplied in B 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 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 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 +occurred. + +CMS_get0_signers() returns all signers or NULL if an error occurred. + +The error can be obtained from L + +=head1 BUGS + +The trusted certificate store is not searched for the signing certificate, +this is primarily due to the inadequacies of the current B +functionality. + +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 + +L, L + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3