1.\" $OpenBSD: PKCS7_verify.3,v 1.9 2019/06/10 14:58:48 schwarze Exp $ 2.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2006, 2013, 2014, 2015 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: June 10 2019 $ 52.Dt PKCS7_VERIFY 3 53.Os 54.Sh NAME 55.Nm PKCS7_verify , 56.Nm PKCS7_get0_signers 57.Nd verify a PKCS#7 signedData structure 58.Sh SYNOPSIS 59.In openssl/pkcs7.h 60.Ft int 61.Fo PKCS7_verify 62.Fa "PKCS7 *p7" 63.Fa "STACK_OF(X509) *certs" 64.Fa "X509_STORE *store" 65.Fa "BIO *indata" 66.Fa "BIO *out" 67.Fa "int flags" 68.Fc 69.Ft STACK_OF(X509) * 70.Fo PKCS7_get0_signers 71.Fa "PKCS7 *p7" 72.Fa "STACK_OF(X509) *certs" 73.Fa "int flags" 74.Fc 75.Sh DESCRIPTION 76.Fn PKCS7_verify 77verifies a PKCS#7 signedData structure. 78.Fa p7 79is the 80.Vt PKCS7 81structure to verify. 82.Fa certs 83is a set of certificates in which to search for the signer's 84certificate. 85.Fa store 86is a trusted certificate store (used for chain verification). 87.Fa indata 88is the signed data if the content is not present in 89.Fa p7 , 90that is if it is detached. 91The content is written to 92.Fa out 93if it is not 94.Dv NULL . 95.Pp 96.Fa flags 97is an optional set of flags, which can be used to modify the verify 98operation. 99.Pp 100.Fn PKCS7_get0_signers 101retrieves the signer's certificates from 102.Fa p7 . 103It does 104.Sy not 105check their validity or whether any signatures are valid. 106The 107.Fa certs 108and 109.Fa flags 110parameters have the same meanings as in 111.Fn PKCS7_verify . 112.Pp 113Normally the verify process proceeds as follows. 114.Pp 115Initially some sanity checks are performed on 116.Fa p7 . 117The type of 118.Fa p7 119must be signedData. 120There must be at least one signature on the data and if the content 121is detached, 122.Fa indata 123cannot be 124.Dv NULL . 125.Pp 126An attempt is made to locate all the signer's certificates, first 127looking in the 128.Fa certs 129parameter (if it is not 130.Dv NULL ) 131and then looking in any certificates contained in the 132.Fa p7 133structure itself. 134If any signer's certificates cannot be located the operation fails. 135.Pp 136Each signer's certificate is chain verified using the 137.Sy smimesign 138purpose and the supplied trusted certificate store. 139Any internal certificates in the message are used as untrusted CAs. 140If any chain verify fails an error code is returned. 141.Pp 142Finally, the signed content is read (and written to 143.Fa out 144if it is not 145.Dv NULL ) 146and the signature's checked. 147.Pp 148If all signature's verify correctly then the function is successful. 149.Pp 150Any of the following flags (OR'ed together) can be passed in the 151.Fa flags 152parameter to change the default verify behaviour. 153Only the flag 154.Dv PKCS7_NOINTERN 155is meaningful to 156.Fn PKCS7_get0_signers . 157.Pp 158If 159.Dv PKCS7_NOINTERN 160is set, the certificates in the message itself are not searched when 161locating the signer's certificate. 162This means that all the signer's certificates must be in the 163.Fa certs 164parameter. 165.Pp 166If the 167.Dv PKCS7_TEXT 168flag is set, MIME headers for type 169.Sy text/plain 170are deleted from the content. 171If the content is not of type 172.Sy text/plain , 173then an error is returned. 174.Pp 175If 176.Dv PKCS7_NOVERIFY 177is set, the signer's certificates are not chain verified. 178.Pp 179If 180.Dv PKCS7_NOCHAIN 181is set, then the certificates contained in the message are not used as 182untrusted CAs. 183This means that the whole verify chain (apart from the signer's 184certificate) must be contained in the trusted store. 185.Pp 186If 187.Dv PKCS7_NOSIGS 188is set, then the signatures on the data are not checked. 189.Pp 190One application of 191.Dv PKCS7_NOINTERN 192is to only accept messages signed by a small number of certificates. 193The acceptable certificates would be passed in the 194.Fa certs 195parameter. 196In this case, if the signer is not one of the certificates supplied in 197.Fa certs , 198then the verify will fail because the signer cannot be found. 199.Pp 200Care should be taken when modifying the default verify behaviour, for 201example setting 202.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS 203will totally disable all verification and any signed message will be 204considered valid. 205This combination is however useful if one merely wishes to write the 206content to 207.Fa out 208and its validity is not considered important. 209.Pp 210Chain verification should arguably be performed using the signing time 211rather than the current time. 212However since the signing time is supplied by the signer, it cannot be 213trusted without additional evidence (such as a trusted timestamp). 214.Sh RETURN VALUES 215.Fn PKCS7_verify 216returns 1 for a successful verification and 0 or a negative value if 217an error occurs. 218.Pp 219.Fn PKCS7_get0_signers 220returns all signers or 221.Dv NULL 222if an error occurred. 223.Pp 224The error can be obtained from 225.Xr ERR_get_error 3 . 226.Sh SEE ALSO 227.Xr PKCS7_decrypt 3 , 228.Xr PKCS7_new 3 , 229.Xr PKCS7_sign 3 , 230.Xr X509_STORE_new 3 231.Sh HISTORY 232.Fn PKCS7_verify 233and 234.Fn PKCS7_get0_signers 235first appeared in OpenSSL 0.9.5 and have been available since 236.Ox 2.7 . 237.Sh BUGS 238The trusted certificate store is not searched for the signer's 239certificate. 240This is primarily due to the inadequacies of the current 241.Vt X509_STORE 242functionality. 243.Pp 244The lack of single pass processing and the need to hold all data 245in memory as mentioned in 246.Xr PKCS7_sign 3 247also applies to 248.Fn PKCS7_verify . 249