1 files changed, 193 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/PKCS7_verify.3 b/src/lib/libcrypto/man/PKCS7_verify.3
new file mode 100644
index 0000000000..3cc6cbac66
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_verify.3
@@ -0,0 +1,193 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt PKCS7_VERIFY 3
+.Os
+.Sh NAME
+.Nm PKCS7_verify ,
+.Nm PKCS7_get0_signers
+.Nd verify a PKCS#7 signedData structure
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft int
+.Fo PKCS7_verify
+.Fa "PKCS7 *p7"
+.Fa "STACK_OF(X509) *certs"
+.Fa "X509_STORE *store"
+.Fa "BIO *indata"
+.Fa "BIO *out"
+.Fa "int flags"
+.Fc
+.Ft STACK_OF(X509) *
+.Fo PKCS7_get0_signers
+.Fa "PKCS7 *p7"
+.Fa "STACK_OF(X509) *certs"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_verify
+verifies a PKCS#7 signedData structure.
+.Fa p7
+is the
+.Vt PKCS7
+structure to verify.
+.Fa certs
+is a set of certificates in which to search for the signer's
+certificate.
+.Fa store
+is a trusted certificate store (used for chain verification).
+.Fa indata
+is the signed data if the content is not present in
+.Fa p7 ,
+that is if it is detached.
+The content is written to
+.Fa out
+if it is not
+.Dv NULL .
+.Pp
+.Fa flags
+is an optional set of flags, which can be used to modify the verify
+operation.
+.Pp
+.Fn PKCS7_get0_signers
+retrieves the signer's certificates from
+.Fa p7 .
+It does
+.Sy not
+check their validity or whether any signatures are valid.
+The
+.Fa certs
+and
+.Fa flags
+parameters have the same meanings as in
+.Fn PKCS7_verify .
+.Pp
+Normally the verify process proceeds as follows.
+.Pp
+Initially some sanity checks are performed on
+.Fa p7 .
+The type of
+.Fa p7
+must be signedData.
+There must be at least one signature on the data and if the content
+is detached,
+.Fa indata
+cannot be
+.Dv NULL .
+.Pp
+An attempt is made to locate all the signer's certificates, first
+looking in the
+.Fa certs
+parameter (if it is not
+.Dv NULL )
+and then looking in any certificates contained in the
+.Fa p7
+structure itself.
+If any signer's certificates cannot be located the operation fails.
+.Pp
+Each signer's certificate is chain verified using the
+.Sy smimesign
+purpose and the supplied trusted certificate store.
+Any internal certificates in the message are used as untrusted CAs.
+If any chain verify fails an error code is returned.
+.Pp
+Finally, the signed content is read (and written to
+.Fa out
+is it is not
+.Dv NULL )
+and the signature's checked.
+.Pp
+If all signature's verify correctly then the function is successful.
+.Pp
+Any of the following flags (OR'ed together) can be passed in the
+.Fa flags
+parameter to change the default verify behaviour.
+Only the flag
+.Dv PKCS7_NOINTERN
+is meaningful to
+.Fn PKCS7_get0_signers .
+.Pp
+If
+.Dv PKCS7_NOINTERN
+is set, the certificates in the message itself are not searched when
+locating the signer's certificate.
+This means that all the signer's certificates must be in the
+.Fa certs
+parameter.
+.Pp
+If the
+.Dv PKCS7_TEXT
+flag is set, MIME headers for type
+.Sy text/plain
+are deleted from the content.
+If the content is not of type
+.Sy text/plain ,
+then an error is returned.
+.Pp
+If
+.Dv PKCS7_NOVERIFY
+is set, the signer's certificates are not chain verified.
+.Pp
+If
+.Dv PKCS7_NOCHAIN
+is set, then the certificates contained in the message are not used as
+untrusted CAs.
+This means that the whole verify chain (apart from the signer's
+certificate) must be contained in the trusted store.
+.Pp
+If
+.Dv PKCS7_NOSIGS
+is set, then the signatures on the data are not checked.
+.Pp
+One application of
+.Dv PKCS7_NOINTERN
+is to only accept messages signed by a small number of certificates.
+The acceptable certificates would be passed in the
+.Fa certs
+parameter.
+In this case, if the signer is not one of the certificates supplied in
+.Fa certs ,
+then the verify will fail because the signer cannot be found.
+.Pp
+Care should be taken when modifying the default verify behaviour, for
+example setting
+.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS
+will totally disable all verification and any signed message will be
+considered valid.
+This combination is however useful if one merely wishes to write the
+content to
+.Fa out
+and its validity is not considered important.
+.Pp
+Chain verification should arguably be performed using the signing time
+rather than the current time.
+However since the signing time is supplied by the signer, it cannot be
+trusted without additional evidence (such as a trusted timestamp).
+.Sh RETURN VALUES
+.Fn PKCS7_verify
+returns 1 for a successful verification and 0 or a negative value if
+an error occurs.
+.Pp
+.Fn PKCS7_get0_signers
+returns all signers or
+.Dv NULL
+if an error occurred.
+.Pp
+The error can be obtained from
+.Xr ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr ERR_get_error 3 ,
+.Xr PKCS7_sign 3
+.Sh HISTORY
+.Fn PKCS7_verify
+was added to OpenSSL 0.9.5 .
+.Sh BUGS
+The trusted certificate store is not searched for the signer's
+certificate.
+This is primarily due to the inadequacies of the current
+.Vt X509_STORE
+functionality.
+.Pp
+The lack of single pass processing and the need to hold all data
+in memory as mentioned in
+.Xr PKCS7_sign 3
+also applies to
+.Fn PKCS7_verify .