1.Dd $Mdocdate: November 11 2015 $ 2.Dt CMS_VERIFY 3 3.Os 4.Sh NAME 5.Nm CMS_verify , 6.Nm CMS_get0_signers 7.Nd verify a CMS SignedData structure 8.Sh SYNOPSIS 9.In openssl/cms.h 10.Ft int 11.Fo CMS_verify 12.Fa "CMS_ContentInfo *cms" 13.Fa "STACK_OF(X509) *certs" 14.Fa "X509_STORE *store" 15.Fa "BIO *indata" 16.Fa "BIO *out" 17.Fa "unsigned int flags" 18.Fc 19.Ft STACK_OF(X509) * 20.Fo CMS_get0_signers 21.Fa "CMS_ContentInfo *cms" 22.Fc 23.Sh DESCRIPTION 24.Fn CMS_verify 25verifies a CMS SignedData structure. 26.Fa cms 27is the 28.Vt CMS_ContentInfo 29structure to verify. 30.Fa certs 31is a set of certificates in which to search for the signing 32certificate(s). 33.Fa store 34is a trusted certificate store used for chain verification. 35.Fa indata 36is the detached content if the content is not present in 37.Fa cms . 38The content is written to 39.Fa out 40if it is not 41.Dv NULL . 42.Pp 43.Fa flags 44is an optional set of flags, which can be used to modify the verify 45operation. 46.Pp 47.Fn CMS_get0_signers 48retrieves the signing certificate(s) from 49.Fa cms , 50it must be called after a successful 51.Fn CMS_verify 52operation. 53.Sh VERIFY PROCESS 54Normally the verify process proceeds as follows. 55.Pp 56Initially some sanity checks are performed on 57.Fa cms . 58The type of 59.Fa cms 60must be SignedData. 61There must be at least one signature on the data and if the content is 62detached 63.Fa indata 64cannot be 65.Dv NULL . 66.Pp 67An attempt is made to locate all the signing certificate(s), first 68looking in the 69.Fa certs 70parameter (if it is not 71.Dv NULL ) 72and then looking in any certificates contained in the 73.Fa cms 74structure itself. 75If no signing certificate can be located, the operation fails. 76.Pp 77Each signing certificate is chain verified using the 78.Sy smimesign 79purpose and the supplied trusted certificate store. 80Any internal certificates in the message are used as untrusted CAs. 81If CRL checking is enabled in 82.Fa store , 83any internal CRLs are used in addition to attempting to look them up in 84.Fa store . 85If any chain verify fails, an error code is returned. 86.Pp 87Finally the signed content is read (and written to 88.Fa out 89is it is not 90.Dv NULL ) 91and the signature is checked. 92.Pp 93If all signatures verify correctly, then the function is successful. 94.Pp 95Any of the following flags (OR'ed together) can be passed in the 96.Fa flags 97parameter to change the default verify behaviour. 98.Pp 99If 100.Dv CMS_NOINTERN 101is set, the certificates in the message itself are not searched when 102locating the signing certificate(s). 103This means that all the signing certificates must be in the 104.Fa certs 105parameter. 106.Pp 107If 108.Dv CMS_NOCRL 109is set, and CRL checking is enabled in 110.Fa store , 111then any CRLs in the message itself are ignored. 112.Pp 113If the 114.Dv CMS_TEXT 115flag is set, MIME headers for type 116.Sy text/plain 117are deleted from the content. 118If the content is not of type 119.Sy text/plain , 120then an error is returned. 121.Pp 122If 123.Dv CMS_NO_SIGNER_CERT_VERIFY 124is set, the signing certificates are not verified. 125.Pp 126If 127.Dv CMS_NO_ATTR_VERIFY 128is set, the signed attributes signature is not verified. 129.Pp 130If 131.Dv CMS_NO_CONTENT_VERIFY 132is set, then the content digest is not checked. 133.Sh NOTES 134One application of 135.Dv CMS_NOINTERN 136is to only accept messages signed by a small number of certificates. 137The acceptable certificates would be passed in the 138.Fa certs 139parameter. 140In this case, if the signer is not one of the certificates supplied in 141.Fa certs , 142then the verify will fail because the signer cannot be found. 143.Pp 144In some cases the standard techniques for looking up and validating 145certificates are not appropriate: for example an application may wish to 146lookup certificates in a database or perform customised verification. 147This can be achieved by setting and verifying the signers certificates 148manually using the signed data utility functions. 149.Pp 150Care should be taken when modifying the default verify behaviour, for 151example setting 152.Dv CMS_NO_CONTENT_VERIFY 153will totally disable all content verification and any modified content 154will be considered valid. 155This combination is however useful if one merely wishes to write the 156content to 157.Fa out 158and its validity is not considered important. 159.Pp 160Chain verification should arguably be performed using the signing time 161rather than the current time. 162However since the signing time is supplied by the signer it cannot be 163trusted without additional evidence (such as a trusted timestamp). 164.Sh RETURN VALUES 165.Fn CMS_verify 166returns 1 for a successful verification and zero if an error occurred. 167.Pp 168.Fn CMS_get0_signers 169returns all signers or 170.Dv NULL 171if an error occurred. 172.Pp 173The error can be obtained from 174.Xr ERR_get_error 3 . 175.Sh SEE ALSO 176.Xr CMS_sign 3 , 177.Xr ERR_get_error 3 178.Sh HISTORY 179.Fn CMS_verify 180was added to OpenSSL 0.9.8. 181.Sh BUGS 182The trusted certificate store is not searched for the signing 183certificate, this is primarily due to the inadequacies of the current 184.Vt X509_STORE 185functionality. 186.Pp 187The lack of single pass processing means that the signed content must 188all be held in memory if it is not detached. 189