1=pod 2 3=head1 NAME 4 5 CMS_verify - verify a CMS SignedData structure 6 7=head1 SYNOPSIS 8 9 #include <openssl/cms.h> 10 11 int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); 12 13 STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); 14 15=head1 DESCRIPTION 16 17CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo 18structure to verify. B<certs> is a set of certificates in which to search for 19the signing certificate(s). B<store> is a trusted certificate store used for 20chain verification. B<indata> is the detached content if the content is not 21present in B<cms>. The content is written to B<out> if it is not NULL. 22 23B<flags> is an optional set of flags, which can be used to modify the verify 24operation. 25 26CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must 27be called after a successful CMS_verify() operation. 28 29=head1 VERIFY PROCESS 30 31Normally the verify process proceeds as follows. 32 33Initially some sanity checks are performed on B<cms>. The type of B<cms> must 34be SignedData. There must be at least one signature on the data and if 35the content is detached B<indata> cannot be B<NULL>. 36 37An attempt is made to locate all the signing certificate(s), first looking in 38the B<certs> parameter (if it is not NULL) and then looking in any 39certificates contained in the B<cms> structure itself. If any signing 40certificate cannot be located the operation fails. 41 42Each signing certificate is chain verified using the B<smimesign> purpose and 43the supplied trusted certificate store. Any internal certificates in the message 44are used as untrusted CAs. If CRL checking is enabled in B<store> any internal 45CRLs are used in addition to attempting to look them up in B<store>. If any 46chain verify fails an error code is returned. 47 48Finally the signed content is read (and written to B<out> is it is not NULL) 49and the signature's checked. 50 51If all signature's verify correctly then the function is successful. 52 53Any of the following flags (ored together) can be passed in the B<flags> 54parameter to change the default verify behaviour. 55 56If B<CMS_NOINTERN> is set the certificates in the message itself are not 57searched when locating the signing certificate(s). This means that all the 58signing certificates must be in the B<certs> parameter. 59 60If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any 61CRLs in the message itself are ignored. 62 63If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted 64from the content. If the content is not of type B<text/plain> then an error is 65returned. 66 67If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not 68verified. 69 70If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not 71verified. 72 73If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. 74 75=head1 NOTES 76 77One application of B<CMS_NOINTERN> is to only accept messages signed by 78a small number of certificates. The acceptable certificates would be passed 79in the B<certs> parameter. In this case if the signer is not one of the 80certificates supplied in B<certs> then the verify will fail because the 81signer cannot be found. 82 83In some cases the standard techniques for looking up and validating 84certificates are not appropriate: for example an application may wish to 85lookup certificates in a database or perform customised verification. This 86can be achieved by setting and verifying the signers certificates manually 87using the signed data utility functions. 88 89Care should be taken when modifying the default verify behaviour, for example 90setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification 91and any modified content will be considered valid. This combination is however 92useful if one merely wishes to write the content to B<out> and its validity 93is not considered important. 94 95Chain verification should arguably be performed using the signing time rather 96than the current time. However since the signing time is supplied by the 97signer it cannot be trusted without additional evidence (such as a trusted 98timestamp). 99 100=head1 RETURN VALUES 101 102CMS_verify() returns 1 for a successful verification and zero if an error 103occurred. 104 105CMS_get0_signers() returns all signers or NULL if an error occurred. 106 107The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> 108 109=head1 BUGS 110 111The trusted certificate store is not searched for the signing certificate, 112this is primarily due to the inadequacies of the current B<X509_STORE> 113functionality. 114 115The lack of single pass processing means that the signed content must all 116be held in memory if it is not detached. 117 118=head1 SEE ALSO 119 120L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> 121 122=head1 HISTORY 123 124CMS_verify() was added to OpenSSL 0.9.8 125 126=cut 127