1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimCMS_verify, CMS_get0_signers - verify a CMS SignedData structure 6e71b7053SJung-uk Kim 7e71b7053SJung-uk Kim=head1 SYNOPSIS 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim #include <openssl/cms.h> 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, 12e71b7053SJung-uk Kim BIO *indata, BIO *out, unsigned int flags); 13e71b7053SJung-uk Kim 14e71b7053SJung-uk Kim STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim=head1 DESCRIPTION 17e71b7053SJung-uk Kim 18cfc39718SJung-uk KimCMS_verify() is very similar to L<PKCS7_verify(3)>. It verifies a 19cfc39718SJung-uk KimB<CMS SignedData> structure contained in a structure of type B<CMS_ContentInfo>. 20cfc39718SJung-uk KimI<cms> points to the B<CMS_ContentInfo> structure to verify. 21cfc39718SJung-uk KimThe optional I<certs> parameter refers to a set of certificates 22cfc39718SJung-uk Kimin which to search for signing certificates. 23cfc39718SJung-uk KimI<cms> may contain extra untrusted CA certificates that may be used for 24cfc39718SJung-uk Kimchain building as well as CRLs that may be used for certificate validation. 25cfc39718SJung-uk KimI<store> may be NULL or point to 26cfc39718SJung-uk Kimthe trusted certificate store to use for chain verification. 27cfc39718SJung-uk KimI<indata> refers to the signed data if the content is detached from I<cms>. 28cfc39718SJung-uk KimOtherwise I<indata> should be NULL and the signed data must be in I<cms>. 29cfc39718SJung-uk KimThe content is written to the BIO I<out> unless it is NULL. 30cfc39718SJung-uk KimI<flags> is an optional set of flags, which can be used to modify the operation. 31e71b7053SJung-uk Kim 32cfc39718SJung-uk KimCMS_get0_signers() retrieves the signing certificate(s) from I<cms>, it may only 33e71b7053SJung-uk Kimbe called after a successful CMS_verify() operation. 34e71b7053SJung-uk Kim 35e71b7053SJung-uk Kim=head1 VERIFY PROCESS 36e71b7053SJung-uk Kim 37e71b7053SJung-uk KimNormally the verify process proceeds as follows. 38e71b7053SJung-uk Kim 39cfc39718SJung-uk KimInitially some sanity checks are performed on I<cms>. The type of I<cms> must 40e71b7053SJung-uk Kimbe SignedData. There must be at least one signature on the data and if 41cfc39718SJung-uk Kimthe content is detached I<indata> cannot be NULL. 42e71b7053SJung-uk Kim 43e71b7053SJung-uk KimAn attempt is made to locate all the signing certificate(s), first looking in 44cfc39718SJung-uk Kimthe I<certs> parameter (if it is not NULL) and then looking in any 45cfc39718SJung-uk Kimcertificates contained in the I<cms> structure unless B<CMS_NOINTERN> is set. 46cfc39718SJung-uk KimIf any signing certificate cannot be located the operation fails. 47e71b7053SJung-uk Kim 48cfc39718SJung-uk KimEach signing certificate is chain verified using the I<smimesign> purpose and 49cfc39718SJung-uk Kimusing the trusted certificate store I<store> if supplied. 50cfc39718SJung-uk KimAny internal certificates in the message, which may have been added using 51cfc39718SJung-uk KimL<CMS_add1_cert(3)>, are used as untrusted CAs. 52cfc39718SJung-uk KimIf CRL checking is enabled in I<store> and B<CMS_NOCRL> is not set, 53cfc39718SJung-uk Kimany internal CRLs, which may have been added using L<CMS_add1_crl(3)>, 54cfc39718SJung-uk Kimare used in addition to attempting to look them up in I<store>. 55cfc39718SJung-uk KimIf I<store> is not NULL and any chain verify fails an error code is returned. 56e71b7053SJung-uk Kim 57cfc39718SJung-uk KimFinally the signed content is read (and written to I<out> unless it is NULL) 58cfc39718SJung-uk Kimand the signature is checked. 59e71b7053SJung-uk Kim 60cfc39718SJung-uk KimIf all signatures verify correctly then the function is successful. 61e71b7053SJung-uk Kim 62cfc39718SJung-uk KimAny of the following flags (ored together) can be passed in the I<flags> 63e71b7053SJung-uk Kimparameter to change the default verify behaviour. 64e71b7053SJung-uk Kim 65e71b7053SJung-uk KimIf B<CMS_NOINTERN> is set the certificates in the message itself are not 66cfc39718SJung-uk Kimsearched when locating the signing certificate(s). 67cfc39718SJung-uk KimThis means that all the signing certificates must be in the I<certs> parameter. 68e71b7053SJung-uk Kim 69cfc39718SJung-uk KimIf B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any 70e71b7053SJung-uk KimCRLs in the message itself are ignored. 71e71b7053SJung-uk Kim 72e71b7053SJung-uk KimIf the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted 73e71b7053SJung-uk Kimfrom the content. If the content is not of type B<text/plain> then an error is 74e71b7053SJung-uk Kimreturned. 75e71b7053SJung-uk Kim 76e71b7053SJung-uk KimIf B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not 77*b077aed3SPierre Proncherychain verified, unless B<CMS_CADES> flag is also set. 78e71b7053SJung-uk Kim 79e71b7053SJung-uk KimIf B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not 80*b077aed3SPierre Proncheryverified, unless CMS_CADES flag is also set. 81*b077aed3SPierre Pronchery 82*b077aed3SPierre ProncheryIf B<CMS_CADES> is set, each signer certificate is checked against the 83*b077aed3SPierre ProncheryESS signingCertificate or ESS signingCertificateV2 extension 84*b077aed3SPierre Proncherythat is required in the signed attributes of the signature. 85e71b7053SJung-uk Kim 86e71b7053SJung-uk KimIf B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. 87e71b7053SJung-uk Kim 88e71b7053SJung-uk Kim=head1 NOTES 89e71b7053SJung-uk Kim 90e71b7053SJung-uk KimOne application of B<CMS_NOINTERN> is to only accept messages signed by 91e71b7053SJung-uk Kima small number of certificates. The acceptable certificates would be passed 92cfc39718SJung-uk Kimin the I<certs> parameter. In this case if the signer certificate is not one 93cfc39718SJung-uk Kimof the certificates supplied in I<certs> then the verify will fail because the 94e71b7053SJung-uk Kimsigner cannot be found. 95e71b7053SJung-uk Kim 96e71b7053SJung-uk KimIn some cases the standard techniques for looking up and validating 97e71b7053SJung-uk Kimcertificates are not appropriate: for example an application may wish to 98e71b7053SJung-uk Kimlookup certificates in a database or perform customised verification. This 99cfc39718SJung-uk Kimcan be achieved by setting and verifying the signer certificates manually 100e71b7053SJung-uk Kimusing the signed data utility functions. 101e71b7053SJung-uk Kim 102e71b7053SJung-uk KimCare should be taken when modifying the default verify behaviour, for example 103e71b7053SJung-uk Kimsetting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification 104e71b7053SJung-uk Kimand any modified content will be considered valid. This combination is however 105cfc39718SJung-uk Kimuseful if one merely wishes to write the content to I<out> and its validity 106e71b7053SJung-uk Kimis not considered important. 107e71b7053SJung-uk Kim 108e71b7053SJung-uk KimChain verification should arguably be performed using the signing time rather 10958f35182SJung-uk Kimthan the current time. However, since the signing time is supplied by the 110e71b7053SJung-uk Kimsigner it cannot be trusted without additional evidence (such as a trusted 111e71b7053SJung-uk Kimtimestamp). 112e71b7053SJung-uk Kim 113e71b7053SJung-uk Kim=head1 RETURN VALUES 114e71b7053SJung-uk Kim 115cfc39718SJung-uk KimCMS_verify() returns 1 for a successful verification and 0 if an error occurred. 116e71b7053SJung-uk Kim 117e71b7053SJung-uk KimCMS_get0_signers() returns all signers or NULL if an error occurred. 118e71b7053SJung-uk Kim 119e71b7053SJung-uk KimThe error can be obtained from L<ERR_get_error(3)> 120e71b7053SJung-uk Kim 121e71b7053SJung-uk Kim=head1 BUGS 122e71b7053SJung-uk Kim 123cfc39718SJung-uk KimThe trusted certificate store is not searched for the signing certificate. 124cfc39718SJung-uk KimThis is primarily due to the inadequacies of the current B<X509_STORE> 125e71b7053SJung-uk Kimfunctionality. 126e71b7053SJung-uk Kim 127e71b7053SJung-uk KimThe lack of single pass processing means that the signed content must all 128e71b7053SJung-uk Kimbe held in memory if it is not detached. 129e71b7053SJung-uk Kim 130e71b7053SJung-uk Kim=head1 SEE ALSO 131e71b7053SJung-uk Kim 132cfc39718SJung-uk KimL<PKCS7_verify(3)>, L<CMS_add1_cert(3)>, L<CMS_add1_crl(3)>, 133cfc39718SJung-uk KimL<OSSL_ESS_check_signing_certs(3)>, 134e71b7053SJung-uk KimL<ERR_get_error(3)>, L<CMS_sign(3)> 135e71b7053SJung-uk Kim 136e71b7053SJung-uk Kim=head1 COPYRIGHT 137e71b7053SJung-uk Kim 138cfc39718SJung-uk KimCopyright 2008-2022 The OpenSSL Project Authors. All Rights Reserved. 139e71b7053SJung-uk Kim 140*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 141e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 142e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 143e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 144e71b7053SJung-uk Kim 145e71b7053SJung-uk Kim=cut 146