1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948PKCS7_verify - verify a PKCS#7 signedData structure 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); 10*2175Sjp161948 11*2175Sjp161948int PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); 12*2175Sjp161948 13*2175Sjp161948=head1 DESCRIPTION 14*2175Sjp161948 15*2175Sjp161948PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 16*2175Sjp161948structure to verify. B<certs> is a set of certificates in which to search for 17*2175Sjp161948the signer's certificate. B<store> is a trusted certficate store (used for 18*2175Sjp161948chain verification). B<indata> is the signed data if the content is not 19*2175Sjp161948present in B<p7> (that is it is detached). The content is written to B<out> 20*2175Sjp161948if it is not NULL. 21*2175Sjp161948 22*2175Sjp161948B<flags> is an optional set of flags, which can be used to modify the verify 23*2175Sjp161948operation. 24*2175Sjp161948 25*2175Sjp161948PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does 26*2175Sjp161948B<not> check their validity or whether any signatures are valid. The B<certs> 27*2175Sjp161948and B<flags> parameters have the same meanings as in PKCS7_verify(). 28*2175Sjp161948 29*2175Sjp161948=head1 VERIFY PROCESS 30*2175Sjp161948 31*2175Sjp161948Normally the verify process proceeds as follows. 32*2175Sjp161948 33*2175Sjp161948Initially some sanity checks are performed on B<p7>. The type of B<p7> must 34*2175Sjp161948be signedData. There must be at least one signature on the data and if 35*2175Sjp161948the content is detached B<indata> cannot be B<NULL>. 36*2175Sjp161948 37*2175Sjp161948An attempt is made to locate all the signer's certificates, first looking in 38*2175Sjp161948the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates 39*2175Sjp161948contained in the B<p7> structure itself. If any signer's certificates cannot be 40*2175Sjp161948located the operation fails. 41*2175Sjp161948 42*2175Sjp161948Each signer's certificate is chain verified using the B<smimesign> purpose and 43*2175Sjp161948the supplied trusted certificate store. Any internal certificates in the message 44*2175Sjp161948are used as untrusted CAs. If any chain verify fails an error code is returned. 45*2175Sjp161948 46*2175Sjp161948Finally the signed content is read (and written to B<out> is it is not NULL) and 47*2175Sjp161948the signature's checked. 48*2175Sjp161948 49*2175Sjp161948If all signature's verify correctly then the function is successful. 50*2175Sjp161948 51*2175Sjp161948Any of the following flags (ored together) can be passed in the B<flags> parameter 52*2175Sjp161948to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is 53*2175Sjp161948meaningful to PKCS7_get0_signers(). 54*2175Sjp161948 55*2175Sjp161948If B<PKCS7_NOINTERN> is set the certificates in the message itself are not 56*2175Sjp161948searched when locating the signer's certificate. This means that all the signers 57*2175Sjp161948certificates must be in the B<certs> parameter. 58*2175Sjp161948 59*2175Sjp161948If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted 60*2175Sjp161948from the content. If the content is not of type B<text/plain> then an error is 61*2175Sjp161948returned. 62*2175Sjp161948 63*2175Sjp161948If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. 64*2175Sjp161948 65*2175Sjp161948If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are 66*2175Sjp161948not used as untrusted CAs. This means that the whole verify chain (apart from 67*2175Sjp161948the signer's certificate) must be contained in the trusted store. 68*2175Sjp161948 69*2175Sjp161948If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. 70*2175Sjp161948 71*2175Sjp161948=head1 NOTES 72*2175Sjp161948 73*2175Sjp161948One application of B<PKCS7_NOINTERN> is to only accept messages signed by 74*2175Sjp161948a small number of certificates. The acceptable certificates would be passed 75*2175Sjp161948in the B<certs> parameter. In this case if the signer is not one of the 76*2175Sjp161948certificates supplied in B<certs> then the verify will fail because the 77*2175Sjp161948signer cannot be found. 78*2175Sjp161948 79*2175Sjp161948Care should be taken when modifying the default verify behaviour, for example 80*2175Sjp161948setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification 81*2175Sjp161948and any signed message will be considered valid. This combination is however 82*2175Sjp161948useful if one merely wishes to write the content to B<out> and its validity 83*2175Sjp161948is not considered important. 84*2175Sjp161948 85*2175Sjp161948Chain verification should arguably be performed using the signing time rather 86*2175Sjp161948than the current time. However since the signing time is supplied by the 87*2175Sjp161948signer it cannot be trusted without additional evidence (such as a trusted 88*2175Sjp161948timestamp). 89*2175Sjp161948 90*2175Sjp161948=head1 RETURN VALUES 91*2175Sjp161948 92*2175Sjp161948PKCS7_verify() returns 1 for a successful verification and zero or a negative 93*2175Sjp161948value if an error occurs. 94*2175Sjp161948 95*2175Sjp161948PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. 96*2175Sjp161948 97*2175Sjp161948The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> 98*2175Sjp161948 99*2175Sjp161948=head1 BUGS 100*2175Sjp161948 101*2175Sjp161948The trusted certificate store is not searched for the signers certificate, 102*2175Sjp161948this is primarily due to the inadequacies of the current B<X509_STORE> 103*2175Sjp161948functionality. 104*2175Sjp161948 105*2175Sjp161948The lack of single pass processing and need to hold all data in memory as 106*2175Sjp161948mentioned in PKCS7_sign() also applies to PKCS7_verify(). 107*2175Sjp161948 108*2175Sjp161948=head1 SEE ALSO 109*2175Sjp161948 110*2175Sjp161948L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> 111*2175Sjp161948 112*2175Sjp161948=head1 HISTORY 113*2175Sjp161948 114*2175Sjp161948PKCS7_verify() was added to OpenSSL 0.9.5 115*2175Sjp161948 116*2175Sjp161948=cut 117