1=pod 2 3=head1 NAME 4 5CMS_verify, CMS_SignedData_verify, 6CMS_get0_signers - verify a CMS SignedData structure 7 8=head1 SYNOPSIS 9 10 #include <openssl/cms.h> 11 12 int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, 13 BIO *detached_data, BIO *out, unsigned int flags); 14 BIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data, 15 STACK_OF(X509) *scerts, X509_STORE *store, 16 STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls, 17 unsigned int flags, 18 OSSL_LIB_CTX *libctx, const char *propq); 19 20 STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); 21 22=head1 DESCRIPTION 23 24CMS_verify() verifies a B<CMS SignedData> structure 25contained in a structure of type B<CMS_ContentInfo>. 26I<cms> points to the B<CMS_ContentInfo> structure to verify. 27I<certs> is a set of certificates in which to search for signing certificate(s). 28I<store> is a trusted certificate store used for chain verification. 29I<detached_data> refers to the content if the content is not present in I<cms>. 30The content is written to the BIO I<out> if it is not NULL. 31I<flags> is an optional set of flags, which can be used to modify the verify 32operation. 33 34CMS_SignedData_verify() is like CMS_verify() except that 35it operates on B<CMS SignedData> input in the I<sd> argument, 36it has some additional parameters described next, 37and on success it returns the verfied content as a memory BIO. 38The optional I<extra> parameter may be used to provide untrusted CA 39certificates that may be helpful for chain building in certificate valiation. 40This list of certificates must not contain duplicates. 41The optional I<crls> parameter may be used to provide extra CRLs. 42Also the list of CRLs must not contain duplicates. 43The optional parameters library context I<libctx> and property query I<propq> 44are used when retrieving algorithms from providers. 45 46CMS_get0_signers() retrieves the signing certificate(s) from I<cms>; it may only 47be called after a successful CMS_verify() or CMS_SignedData_verify() operation. 48 49=head1 VERIFY PROCESS 50 51Normally the verify process proceeds as follows. 52 53Initially some sanity checks are performed on I<cms>. The type of I<cms> must 54be SignedData. There must be at least one signature on the data and if 55the content is detached I<detached_data> cannot be NULL. 56 57An attempt is made to locate all the signing certificate(s), first looking in 58the I<certs> parameter (if it is not NULL) and then looking in any 59certificates contained in the I<cms> structure itself. If any signing 60certificate cannot be located the operation fails. 61 62Each signing certificate is chain verified using the I<smimesign> purpose and 63the supplied trusted certificate store. Any internal certificates in the message 64are used as untrusted CAs. If CRL checking is enabled in I<store> any internal 65CRLs are used in addition to attempting to look them up in I<store>. If any 66chain verify fails an error code is returned. 67 68Finally the signed content is read (and written to I<out> if it is not NULL) 69and the signature's checked. 70 71If all signature's verify correctly then the function is successful. 72 73Any of the following flags (ored together) can be passed in the I<flags> 74parameter to change the default verify behaviour. 75 76If B<CMS_NOINTERN> is set the certificates in the message itself are not 77searched when locating the signing certificate(s). This means that all the 78signing certificates must be in the I<certs> parameter. 79 80If B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any 81CRLs in the message itself and provided via the I<crls> parameter are ignored. 82 83If the B<CMS_TEXT> flag is set MIME headers for type C<text/plain> are deleted 84from the content. If the content is not of type C<text/plain> then an error is 85returned. 86 87If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not 88verified, unless CMS_CADES flag is also set. 89 90If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not 91verified, unless CMS_CADES flag is also set. 92 93If B<CMS_CADES> is set, each signer certificate is checked against the 94ESS signingCertificate or ESS signingCertificateV2 extension 95that is required in the signed attributes of the signature. 96 97If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. 98 99=head1 NOTES 100 101One application of B<CMS_NOINTERN> is to only accept messages signed by 102a small number of certificates. The acceptable certificates would be passed 103in the I<certs> parameter. In this case if the signer is not one of the 104certificates supplied in I<certs> then the verify will fail because the 105signer cannot be found. 106 107In some cases the standard techniques for looking up and validating 108certificates are not appropriate: for example an application may wish to 109lookup certificates in a database or perform customised verification. This 110can be achieved by setting and verifying the signers certificates manually 111using the signed data utility functions. 112 113Care should be taken when modifying the default verify behaviour, for example 114setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification 115and any modified content will be considered valid. This combination is however 116useful if one merely wishes to write the content to I<out> and its validity 117is not considered important. 118 119Chain verification should arguably be performed using the signing time rather 120than the current time. However, since the signing time is supplied by the 121signer it cannot be trusted without additional evidence (such as a trusted 122timestamp). 123 124=head1 RETURN VALUES 125 126CMS_verify() returns 1 for a successful verification and zero if an error 127occurred. 128 129CMS_SignedData_verify() returns a memory BIO containing the verfied content, 130or NULL on error. 131 132CMS_get0_signers() returns all signers or NULL if an error occurred. 133 134The error can be obtained from L<ERR_get_error(3)>. 135 136=head1 BUGS 137 138The trusted certificate store is not searched for the signing certificate, 139this is primarily due to the inadequacies of the current B<X509_STORE> 140functionality. 141 142The lack of single pass processing means that the signed content must all 143be held in memory if it is not detached. 144 145=head1 SEE ALSO 146 147L<OSSL_ESS_check_signing_certs(3)>, 148L<ERR_get_error(3)>, L<CMS_sign(3)> 149 150=head1 HISTORY 151 152CMS_SignedData_verify() was added in OpenSSL 3.1. 153 154=head1 COPYRIGHT 155 156Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved. 157 158Licensed under the Apache License 2.0 (the "License"). You may not use 159this file except in compliance with the License. You can obtain a copy 160in the file LICENSE in the source distribution or at 161L<https://www.openssl.org/source/license.html>. 162 163=cut 164
