1.\" $OpenBSD: PKCS7_verify.3,v 1.11 2022/03/31 17:27:17 naddy 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: March 31 2022 $ 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 . 103The signers must be freed with 104.Fn sk_X509_free . 105It does 106.Sy not 107check their validity or whether any signatures are valid. 108The 109.Fa certs 110and 111.Fa flags 112parameters have the same meanings as in 113.Fn PKCS7_verify . 114.Pp 115Normally the verify process proceeds as follows. 116.Pp 117Initially some sanity checks are performed on 118.Fa p7 . 119The type of 120.Fa p7 121must be signedData. 122There must be at least one signature on the data and if the content 123is detached, 124.Fa indata 125cannot be 126.Dv NULL . 127.Pp 128An attempt is made to locate all the signer's certificates, first 129looking in the 130.Fa certs 131parameter (if it is not 132.Dv NULL ) 133and then looking in any certificates contained in the 134.Fa p7 135structure itself. 136If any signer's certificates cannot be located, the operation fails. 137.Pp 138Each signer's certificate is chain verified using the 139.Sy smimesign 140purpose and the supplied trusted certificate store. 141Any internal certificates in the message are used as untrusted CAs. 142If any chain verify fails, an error code is returned. 143.Pp 144Finally, the signed content is read (and written to 145.Fa out 146if it is not 147.Dv NULL ) 148and the signature's checked. 149.Pp 150If all signature's verify correctly then the function is successful. 151.Pp 152Any of the following flags (OR'ed together) can be passed in the 153.Fa flags 154parameter to change the default verify behaviour. 155Only the flag 156.Dv PKCS7_NOINTERN 157is meaningful to 158.Fn PKCS7_get0_signers . 159.Pp 160If 161.Dv PKCS7_NOINTERN 162is set, the certificates in the message itself are not searched when 163locating the signer's certificate. 164This means that all the signer's certificates must be in the 165.Fa certs 166parameter. 167.Pp 168If the 169.Dv PKCS7_TEXT 170flag is set, MIME headers for type 171.Sy text/plain 172are deleted from the content. 173If the content is not of type 174.Sy text/plain , 175then an error is returned. 176.Pp 177If 178.Dv PKCS7_NOVERIFY 179is set, the signer's certificates are not chain verified. 180.Pp 181If 182.Dv PKCS7_NOCHAIN 183is set, then the certificates contained in the message are not used as 184untrusted CAs. 185This means that the whole verify chain (apart from the signer's 186certificate) must be contained in the trusted store. 187.Pp 188If 189.Dv PKCS7_NOSIGS 190is set, then the signatures on the data are not checked. 191.Pp 192One application of 193.Dv PKCS7_NOINTERN 194is to only accept messages signed by a small number of certificates. 195The acceptable certificates would be passed in the 196.Fa certs 197parameter. 198In this case, if the signer is not one of the certificates supplied in 199.Fa certs , 200then the verify will fail because the signer cannot be found. 201.Pp 202Care should be taken when modifying the default verify behaviour, for 203example setting 204.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS 205will totally disable all verification and any signed message will be 206considered valid. 207This combination is however useful if one merely wishes to write the 208content to 209.Fa out 210and its validity is not considered important. 211.Pp 212Chain verification should arguably be performed using the signing time 213rather than the current time. 214However since the signing time is supplied by the signer, it cannot be 215trusted without additional evidence (such as a trusted timestamp). 216.Sh RETURN VALUES 217.Fn PKCS7_verify 218returns 1 for a successful verification and 0 or a negative value if 219an error occurs. 220.Pp 221.Fn PKCS7_get0_signers 222returns all signers or 223.Dv NULL 224if an error occurred. 225The signers must be freed with 226.Fn sk_X509_free . 227.Pp 228The error can be obtained from 229.Xr ERR_get_error 3 . 230.Sh SEE ALSO 231.Xr PKCS7_decrypt 3 , 232.Xr PKCS7_new 3 , 233.Xr PKCS7_sign 3 , 234.Xr X509_STORE_new 3 235.Sh HISTORY 236.Fn PKCS7_verify 237and 238.Fn PKCS7_get0_signers 239first appeared in OpenSSL 0.9.5 and have been available since 240.Ox 2.7 . 241.Sh BUGS 242The trusted certificate store is not searched for the signer's 243certificate. 244This is primarily due to the inadequacies of the current 245.Vt X509_STORE 246functionality. 247.Pp 248The lack of single pass processing and the need to hold all data 249in memory as mentioned in 250.Xr PKCS7_sign 3 251also applies to 252.Fn PKCS7_verify . 253