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