mirror of https://github.com/openssl/openssl.git
Fix many inconsistencies in doc of CMS_verify() and PKC7_verify() etc.
Also change B< to I< in {CMS,PKCS7}_verify.pod, PKCS7_sign{,_add_signer}.pod
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/18915)
This commit is contained in:
Dr. David von Oheimb
Dr. David von Oheimb
parent
948c656c66
commit
cae1d08f2c
|
|
@ -22,14 +22,17 @@ CMS_add0_crl, CMS_add1_crl, CMS_get1_crls
|
|||
|
||||
CMS_add0_cert() and CMS_add1_cert() add certificate I<cert> to I<cms>.
|
||||
I<cms> must be of type signed data or (authenticated) enveloped data.
|
||||
For signed data, such a certificate can be used to fill in the signer
|
||||
certificate and may also be helpful for chain building in certificate validation.
|
||||
For signed data, such a certificate can be used when signing or verifying
|
||||
to fill in the signer certificate or to provide an extra CA certificate
|
||||
that may be needed for chain building in certificate validation.
|
||||
|
||||
CMS_get1_certs() returns all certificates in I<cms>.
|
||||
|
||||
CMS_add0_crl() and CMS_add1_crl() add CRL I<crl> to I<cms>.
|
||||
I<cms> must be of type signed data or (authenticated) enveloped data.
|
||||
For signed data, such a CRL may be used in certificate validation.
|
||||
It may be given both for inclusion when signing a CMS message
|
||||
and when verifying a signed CMS message.
|
||||
|
||||
CMS_get1_crls() returns all CRLs in I<cms>.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,15 +21,19 @@ CMS_get0_signers - verify a CMS SignedData structure
|
|||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
CMS_verify() verifies a B<CMS SignedData> structure
|
||||
contained in a structure of type B<CMS_ContentInfo>.
|
||||
CMS_verify() is very similar to L<PKCS7_verify(3)>. It verifies a
|
||||
B<CMS SignedData> structure contained in a structure of type B<CMS_ContentInfo>.
|
||||
I<cms> points to the B<CMS_ContentInfo> structure to verify.
|
||||
I<certs> is a set of certificates in which to search for signing certificate(s).
|
||||
I<store> is a trusted certificate store used for chain verification.
|
||||
I<detached_data> refers to the content if the content is not present in I<cms>.
|
||||
The content is written to the BIO I<out> if it is not NULL.
|
||||
I<flags> is an optional set of flags, which can be used to modify the verify
|
||||
operation.
|
||||
The optional I<certs> parameter refers to a set of certificates
|
||||
in which to search for signing certificates.
|
||||
I<cms> may contain extra untrusted CA certificates that may be used for
|
||||
chain building as well as CRLs that may be used for certificate validation.
|
||||
I<store> may be NULL or point to
|
||||
the trusted certificate store to use for chain verification.
|
||||
I<detached_data> refers to the signed data if the content is detached from I<cms>.
|
||||
Otherwise I<detached_data> should be NULL and the signed data must be in I<cms>.
|
||||
The content is written to the BIO I<out> unless it is NULL.
|
||||
I<flags> is an optional set of flags, which can be used to modify the operation.
|
||||
|
||||
CMS_SignedData_verify() is like CMS_verify() except that
|
||||
it operates on B<CMS SignedData> input in the I<sd> argument,
|
||||
|
|
@ -56,26 +60,29 @@ the content is detached I<detached_data> cannot be NULL.
|
|||
|
||||
An attempt is made to locate all the signing certificate(s), first looking in
|
||||
the I<certs> parameter (if it is not NULL) and then looking in any
|
||||
certificates contained in the I<cms> structure itself. If any signing
|
||||
certificate cannot be located the operation fails.
|
||||
certificates contained in the I<cms> structure unless B<CMS_NOINTERN> is set.
|
||||
If any signing certificate cannot be located the operation fails.
|
||||
|
||||
Each signing certificate is chain verified using the I<smimesign> purpose and
|
||||
the supplied trusted certificate store. Any internal certificates in the message
|
||||
are used as untrusted CAs. If CRL checking is enabled in I<store> any internal
|
||||
CRLs are used in addition to attempting to look them up in I<store>. If any
|
||||
chain verify fails an error code is returned.
|
||||
using the trusted certificate store I<store> if supplied.
|
||||
Any internal certificates in the message, which may have been added using
|
||||
L<CMS_add1_cert(3)>, are used as untrusted CAs.
|
||||
If CRL checking is enabled in I<store> and B<CMS_NOCRL> is not set,
|
||||
any internal CRLs, which may have been added using L<CMS_add1_crl(3)>,
|
||||
are used in addition to attempting to look them up in I<store>.
|
||||
If I<store> is not NULL and any chain verify fails an error code is returned.
|
||||
|
||||
Finally the signed content is read (and written to I<out> if it is not NULL)
|
||||
and the signature's checked.
|
||||
Finally the signed content is read (and written to I<out> unless it is NULL)
|
||||
and the signature is checked.
|
||||
|
||||
If all signature's verify correctly then the function is successful.
|
||||
If all signatures verify correctly then the function is successful.
|
||||
|
||||
Any of the following flags (ored together) can be passed in the I<flags>
|
||||
parameter to change the default verify behaviour.
|
||||
|
||||
If B<CMS_NOINTERN> is set the certificates in the message itself are not
|
||||
searched when locating the signing certificate(s). This means that all the
|
||||
signing certificates must be in the I<certs> parameter.
|
||||
searched when locating the signing certificate(s).
|
||||
This means that all the signing certificates must be in the I<certs> parameter.
|
||||
|
||||
If B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any
|
||||
CRLs in the message itself and provided via the I<crls> parameter are ignored.
|
||||
|
|
@ -85,7 +92,7 @@ from the content. If the content is not of type C<text/plain> then an error is
|
|||
returned.
|
||||
|
||||
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
|
||||
verified, unless CMS_CADES flag is also set.
|
||||
chain verified, unless B<CMS_CADES> flag is also set.
|
||||
|
||||
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
|
||||
verified, unless CMS_CADES flag is also set.
|
||||
|
|
@ -100,14 +107,14 @@ If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
|
|||
|
||||
One application of B<CMS_NOINTERN> is to only accept messages signed by
|
||||
a small number of certificates. The acceptable certificates would be passed
|
||||
in the I<certs> parameter. In this case if the signer is not one of the
|
||||
certificates supplied in I<certs> then the verify will fail because the
|
||||
in the I<certs> parameter. In this case if the signer certificate is not one
|
||||
of the certificates supplied in I<certs> then the verify will fail because the
|
||||
signer cannot be found.
|
||||
|
||||
In some cases the standard techniques for looking up and validating
|
||||
certificates are not appropriate: for example an application may wish to
|
||||
lookup certificates in a database or perform customised verification. This
|
||||
can be achieved by setting and verifying the signers certificates manually
|
||||
can be achieved by setting and verifying the signer certificates manually
|
||||
using the signed data utility functions.
|
||||
|
||||
Care should be taken when modifying the default verify behaviour, for example
|
||||
|
|
@ -123,8 +130,7 @@ timestamp).
|
|||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
CMS_verify() returns 1 for a successful verification and zero if an error
|
||||
occurred.
|
||||
CMS_verify() returns 1 for a successful verification and 0 if an error occurred.
|
||||
|
||||
CMS_SignedData_verify() returns a memory BIO containing the verfied content,
|
||||
or NULL on error.
|
||||
|
|
@ -135,8 +141,8 @@ The error can be obtained from L<ERR_get_error(3)>.
|
|||
|
||||
=head1 BUGS
|
||||
|
||||
The trusted certificate store is not searched for the signing certificate,
|
||||
this is primarily due to the inadequacies of the current B<X509_STORE>
|
||||
The trusted certificate store is not searched for the signing certificate.
|
||||
This is primarily due to the inadequacies of the current B<X509_STORE>
|
||||
functionality.
|
||||
|
||||
The lack of single pass processing means that the signed content must all
|
||||
|
|
@ -144,6 +150,7 @@ be held in memory if it is not detached.
|
|||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<PKCS7_verify(3)>, L<CMS_add1_cert(3)>, L<CMS_add1_crl(3)>,
|
||||
L<OSSL_ESS_check_signing_certs(3)>,
|
||||
L<ERR_get_error(3)>, L<CMS_sign(3)>
|
||||
|
||||
|
|
|
|||
|
|
@ -18,28 +18,28 @@ PKCS7_sign_ex, PKCS7_sign
|
|||
=head1 DESCRIPTION
|
||||
|
||||
PKCS7_sign_ex() creates and returns a PKCS#7 signedData structure.
|
||||
I<igncert> is the certificate to sign with, Ipkey> is the corresponding
|
||||
private key. I<certs> is an optional additional set of certificates to include
|
||||
in the PKCS#7 structure (for example any intermediate CAs in the chain). The
|
||||
library context I<libctx> and property query I<propq> are used when
|
||||
I<signcert> is the certificate to sign with, I<pkey> is the corresponding
|
||||
private key. I<certs> is an optional set of extra certificates to include
|
||||
in the PKCS#7 structure (for example any intermediate CAs in the chain).
|
||||
The library context I<libctx> and property query I<propq> are used when
|
||||
retrieving algorithms from providers.
|
||||
|
||||
The data to be signed is read from BIO B<data>.
|
||||
The data to be signed is read from BIO I<data>.
|
||||
|
||||
B<flags> is an optional set of flags.
|
||||
I<flags> is an optional set of flags.
|
||||
|
||||
Any of the following flags (ored together) can be passed in the B<flags>
|
||||
Any of the following flags (ored together) can be passed in the I<flags>
|
||||
parameter.
|
||||
|
||||
Many S/MIME clients expect the signed content to include valid MIME headers. If
|
||||
the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
|
||||
the B<PKCS7_TEXT> flag is set MIME headers for type C<text/plain> are prepended
|
||||
to the data.
|
||||
|
||||
If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
|
||||
PKCS7 structure, the signer's certificate must still be supplied in the
|
||||
B<signcert> parameter though. This can reduce the size of the signature if the
|
||||
signers certificate can be obtained by other means: for example a previously
|
||||
signed message.
|
||||
If B<PKCS7_NOCERTS> is set the signer's certificate and the extra I<certs>
|
||||
will not be included in the PKCS7 structure.
|
||||
The signer's certificate must still be supplied in the I<signcert> parameter
|
||||
though. This can reduce the size of the signatures if the signer's certificates
|
||||
can be obtained by other means: for example a previously signed message.
|
||||
|
||||
The data being signed is included in the PKCS7 structure, unless
|
||||
B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7
|
||||
|
|
@ -63,7 +63,7 @@ these algorithms is disabled then it will not be included.
|
|||
|
||||
If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
|
||||
just initialized ready to perform the signing operation. The signing is however
|
||||
B<not> performed and the data to be signed is not read from the B<data>
|
||||
B<not> performed and the data to be signed is not read from the I<data>
|
||||
parameter. Signing is deferred until after the data has been written. In this
|
||||
way data can be signed in a single pass.
|
||||
|
||||
|
|
@ -82,20 +82,21 @@ BIO_new_PKCS7().
|
|||
If a signer is specified it will use the default digest for the signing
|
||||
algorithm. This is B<SHA1> for both RSA and DSA keys.
|
||||
|
||||
The B<certs>, B<signcert> and B<pkey> parameters can all be
|
||||
B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
|
||||
The I<certs>, I<signcert> and I<pkey> parameters can all be
|
||||
NULL if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
|
||||
using the function PKCS7_sign_add_signer(). PKCS7_final() must also be
|
||||
called to finalize the structure if streaming is not enabled. Alternative
|
||||
signing digests can also be specified using this method.
|
||||
|
||||
If B<signcert> and B<pkey> are NULL then a certificates only
|
||||
If I<signcert> and I<pkey> are NULL then a certificates only
|
||||
PKCS#7 structure is output.
|
||||
|
||||
In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
|
||||
B<NOT> be NULL.
|
||||
In versions of OpenSSL before 1.0.0 the I<signcert> and I<pkey> parameters must
|
||||
not be NULL.
|
||||
|
||||
PKCS7_sign() is similar to PKCS7_sign_ex() but uses default values of
|
||||
PKCS7_sign() is like PKCS7_sign_ex() except that it uses default values of
|
||||
NULL for the library context I<libctx> and the property query I<propq>.
|
||||
This is retained for API backward compatibiliy.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
|
|
@ -114,8 +115,8 @@ L<ERR_get_error(3)>, L<PKCS7_verify(3)>
|
|||
|
||||
The function PKCS7_sign_ex() was added in OpenSSL 3.0.
|
||||
|
||||
The B<PKCS7_PARTIAL> flag, and the ability for B<certs>, B<signcert>,
|
||||
and B<pkey> parameters to be B<NULL> were added in OpenSSL 1.0.0.
|
||||
The B<PKCS7_PARTIAL> flag, and the ability for I<certs>, I<signcert>,
|
||||
and I<pkey> parameters to be NULL were added in OpenSSL 1.0.0.
|
||||
|
||||
The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,8 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
PKCS7_sign_add_signer - add a signer PKCS7 signed data structure
|
||||
PKCS7_sign_add_signer,
|
||||
PKCS7_add_certificate, PKCS7_add_crl - add information to PKCS7 structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
|
@ -10,22 +11,22 @@ PKCS7_sign_add_signer - add a signer PKCS7 signed data structure
|
|||
|
||||
PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert,
|
||||
EVP_PKEY *pkey, const EVP_MD *md, int flags);
|
||||
|
||||
int PKCS7_add_certificate(PKCS7 *p7, X509 *cert);
|
||||
int PKCS7_add_crl(PKCS7 *p7, X509_CRL *crl);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private
|
||||
key B<pkey> using message digest B<md> to a PKCS7 signed data structure
|
||||
B<p7>.
|
||||
PKCS7_sign_add_signer() adds a signer with certificate I<signcert> and private
|
||||
key I<pkey> using message digest I<md> to a PKCS7 signed data structure I<p7>.
|
||||
|
||||
The PKCS7 structure should be obtained from an initial call to PKCS7_sign()
|
||||
with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7
|
||||
The B<PKCS7> structure should be obtained from an initial call to PKCS7_sign()
|
||||
with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS#7
|
||||
signed data structure.
|
||||
|
||||
If the B<md> parameter is B<NULL> then the default digest for the public
|
||||
If the I<md> parameter is NULL then the default digest for the public
|
||||
key algorithm will be used.
|
||||
|
||||
Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure
|
||||
Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned B<PKCS7> structure
|
||||
is not complete and must be finalized either by streaming (if applicable) or
|
||||
a call to PKCS7_final().
|
||||
|
||||
|
|
@ -37,13 +38,13 @@ signed data structure where the simpler PKCS7_sign() function defaults are
|
|||
not appropriate. For example if multiple signers or non default digest
|
||||
algorithms are needed.
|
||||
|
||||
Any of the following flags (ored together) can be passed in the B<flags>
|
||||
Any of the following flags (ored together) can be passed in the I<flags>
|
||||
parameter.
|
||||
|
||||
If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content
|
||||
digest value from the PKCS7 structure: to add a signer to an existing structure.
|
||||
digest value from the B<PKCS7> structure: to add a signer to an existing structure.
|
||||
An error occurs if a matching digest value cannot be found to copy. The
|
||||
returned PKCS7 structure will be valid and finalized when this flag is set.
|
||||
returned B<PKCS7> structure will be valid and finalized when this flag is set.
|
||||
|
||||
If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the
|
||||
B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes
|
||||
|
|
@ -51,8 +52,8 @@ can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is
|
|||
needed to finalize it.
|
||||
|
||||
If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
|
||||
PKCS7 structure, the signer's certificate must still be supplied in the
|
||||
B<signcert> parameter though. This can reduce the size of the signature if the
|
||||
B<PKCS7> structure, the signer's certificate must still be supplied in the
|
||||
I<signcert> parameter though. This can reduce the size of the signature if the
|
||||
signers certificate can be obtained by other means: for example a previously
|
||||
signed message.
|
||||
|
||||
|
|
@ -66,20 +67,32 @@ If present the SMIMECapabilities attribute indicates support for the following
|
|||
algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
|
||||
these algorithms is disabled then it will not be included.
|
||||
|
||||
|
||||
PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
|
||||
structure just added, this can be used to set additional attributes
|
||||
PKCS7_sign_add_signers() returns an internal pointer to the B<PKCS7_SIGNER_INFO>
|
||||
structure just added, which can be used to set additional attributes
|
||||
before it is finalized.
|
||||
|
||||
PKCS7_add_certificate() adds to the B<PKCS7> structure I<p7> the certificate
|
||||
I<cert>, which may be an end-entity (signer) certificate
|
||||
or a CA certificate useful for chain building.
|
||||
This is done internally by L<PKCS7_sign_ex(3)> and similar signing functions.
|
||||
It may have to be used before calling L<PKCS7_verify(3)>
|
||||
in order to provide any missing certificate(s) needed for verification.
|
||||
|
||||
PKCS7_add_crl() adds the CRL I<crl> to the B<PKCS7> structure I<p7>.
|
||||
This may be called to provide certificate status information
|
||||
to be included when signing or to use when verifying the B<PKCS7> structure.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
|
||||
PKCS7_sign_add_signers() returns an internal pointer to the B<PKCS7_SIGNER_INFO>
|
||||
structure just added or NULL if an error occurs.
|
||||
|
||||
PKCS7_add_certificate() and PKCS7_add_crl() return 1 on success, 0 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
|
||||
L<PKCS7_final(3)>,
|
||||
L<ERR_get_error(3)>, L<PKCS7_sign_ex(3)>,
|
||||
L<PKCS7_final(3)>, L<PKCS7_verify(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
|
|||
|
|
@ -15,64 +15,76 @@ PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
|
|||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7
|
||||
structure to verify. B<certs> is a set of certificates in which to search for
|
||||
the signer's certificate. B<store> is a trusted certificate store (used for
|
||||
chain verification). B<indata> is the signed data if the content is not
|
||||
present in B<p7> (that is it is detached). The content is written to B<out>
|
||||
if it is not NULL.
|
||||
PKCS7_verify() is very similar to L<CMS_verify(3)>.
|
||||
It verifies a PKCS#7 signedData structure given in I<p7>.
|
||||
The optional I<certs> parameter refers to a set of certificates
|
||||
in which to search for signer's certificates.
|
||||
I<p7> may contain extra untrusted CA certificates that may be used for
|
||||
chain building as well as CRLs that may be used for certificate validation.
|
||||
I<store> may be NULL or point to
|
||||
the trusted certificate store to use for chain verification.
|
||||
I<indata> refers to the signed data if the content is detached from I<p7>.
|
||||
Otherwise I<indata> should be NULL, and then the signed data must be in I<p7>.
|
||||
The content is written to the BIO I<out> unless it is NULL.
|
||||
I<flags> is an optional set of flags, which can be used to modify the operation.
|
||||
|
||||
B<flags> is an optional set of flags, which can be used to modify the verify
|
||||
operation.
|
||||
|
||||
PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does
|
||||
B<not> check their validity or whether any signatures are valid. The B<certs>
|
||||
and B<flags> parameters have the same meanings as in PKCS7_verify().
|
||||
PKCS7_get0_signers() retrieves the signer's certificates from I<p7>, it does
|
||||
B<not> check their validity or whether any signatures are valid. The I<certs>
|
||||
and I<flags> parameters have the same meanings as in PKCS7_verify().
|
||||
|
||||
=head1 VERIFY PROCESS
|
||||
|
||||
Normally the verify process proceeds as follows.
|
||||
|
||||
Initially some sanity checks are performed on B<p7>. The type of B<p7> must
|
||||
be signedData. There must be at least one signature on the data and if
|
||||
the content is detached B<indata> cannot be B<NULL>. If the content is
|
||||
not detached and B<indata> is not B<NULL>, then the structure has both
|
||||
Initially some sanity checks are performed on I<p7>. The type of I<p7> must
|
||||
be SignedData. There must be at least one signature on the data and if
|
||||
the content is detached I<indata> cannot be NULL. If the content is
|
||||
not detached and I<indata> is not NULL then the structure has both
|
||||
embedded and external content. To treat this as an error, use the flag
|
||||
B<PKCS7_NO_DUAL_CONTENT>.
|
||||
The default behavior allows this, for compatibility with older
|
||||
versions of OpenSSL.
|
||||
|
||||
An attempt is made to locate all the signer's certificates, first looking in
|
||||
the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates
|
||||
contained in the B<p7> structure itself. If any signer's certificates cannot be
|
||||
located the operation fails.
|
||||
the I<certs> parameter (if it is not NULL). Then they are looked up in any
|
||||
certificates contained in the I<p7> structure unless B<PKCS7_NOINTERN> is set.
|
||||
If any signer's certificates cannot be located the operation fails.
|
||||
|
||||
Each signer's certificate is chain verified using the B<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.
|
||||
using the trusted certificate store I<store> if supplied.
|
||||
Any internal certificates in the message, which may have been added using
|
||||
L<PKCS7_add_certificate(3)>, are used as untrusted CAs unless B<PKCS7_NOCHAIN>
|
||||
is set.
|
||||
If CRL checking is enabled in I<store> and B<PKCS7_NOCRL> is not set,
|
||||
any internal CRLs, which may have been added using L<PKCS7_add_crl(3)>,
|
||||
are used in addition to attempting to look them up in I<store>.
|
||||
If I<store> is not NULL and any chain verify fails an error code is returned.
|
||||
|
||||
Finally the signed content is read (and written to B<out> is it is not NULL) and
|
||||
the signature's checked.
|
||||
Finally the signed content is read (and written to I<out> unless it is NULL)
|
||||
and the signature is checked.
|
||||
|
||||
If all signature's verify correctly then the function is successful.
|
||||
If all signatures verify correctly then the function is successful.
|
||||
|
||||
Any of the following flags (ored together) can be passed in the B<flags> parameter
|
||||
to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is
|
||||
meaningful to PKCS7_get0_signers().
|
||||
Any of the following flags (ored together) can be passed in the I<flags>
|
||||
parameter to change the default verify behaviour.
|
||||
Only the flag B<PKCS7_NOINTERN> is meaningful to PKCS7_get0_signers().
|
||||
|
||||
If B<PKCS7_NOINTERN> is set the certificates in the message itself are not
|
||||
searched when locating the signer's certificate. This means that all the signers
|
||||
certificates must be in the B<certs> parameter.
|
||||
searched when locating the signer's certificates.
|
||||
This means that all the signer's certificates must be in the I<certs> parameter.
|
||||
|
||||
If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
|
||||
from the content. If the content is not of type B<text/plain> then an error is
|
||||
If B<PKCS7_NOCRL> is set and CRL checking is enabled in I<store> then any
|
||||
CRLs in the message itself are ignored.
|
||||
|
||||
If the B<PKCS7_TEXT> flag is set MIME headers for type C<text/plain> are deleted
|
||||
from the content. If the content is not of type C<text/plain> then an error is
|
||||
returned.
|
||||
|
||||
If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified.
|
||||
|
||||
If B<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.
|
||||
the signer's certificates) must be contained in the trusted store.
|
||||
|
||||
If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
|
||||
|
||||
|
|
@ -80,14 +92,14 @@ If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
|
|||
|
||||
One application of B<PKCS7_NOINTERN> is to only accept messages signed by
|
||||
a small number of certificates. The acceptable certificates would be passed
|
||||
in the B<certs> parameter. In this case if the signer is not one of the
|
||||
certificates supplied in B<certs> then the verify will fail because the
|
||||
in the I<certs> parameter. In this case if the signer's certificate is not one
|
||||
of the certificates supplied in I<certs> then the verify will fail because the
|
||||
signer cannot be found.
|
||||
|
||||
Care should be taken when modifying the default verify behaviour, for example
|
||||
setting C<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 B<out> and its validity
|
||||
useful if one merely wishes to write the content to I<out> and its validity
|
||||
is not considered important.
|
||||
|
||||
Chain verification should arguably be performed using the signing time rather
|
||||
|
|
@ -97,24 +109,24 @@ timestamp).
|
|||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
PKCS7_verify() returns one for a successful verification and zero
|
||||
if an error occurs.
|
||||
PKCS7_verify() returns 1 for a successful verification and 0 if an error occurs.
|
||||
|
||||
PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.
|
||||
PKCS7_get0_signers() returns all signers or NULL if an error occurred.
|
||||
|
||||
The error can be obtained from L<ERR_get_error(3)>
|
||||
The error can be obtained from L<ERR_get_error(3)>.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The trusted certificate store is not searched for the signers certificate,
|
||||
this is primarily due to the inadequacies of the current B<X509_STORE>
|
||||
The trusted certificate store is not searched for the signer's certificates.
|
||||
This is primarily due to the inadequacies of the current B<X509_STORE>
|
||||
functionality.
|
||||
|
||||
The lack of single pass processing and need to hold all data in memory as
|
||||
mentioned in PKCS7_sign() also applies to PKCS7_verify().
|
||||
The lack of single pass processing means that the signed content must all
|
||||
be held in memory if it is not detached.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<CMS_verify(3)>, L<PKCS7_add_certificate(3)>, L<PKCS7_add_crl(3)>,
|
||||
L<ERR_get_error(3)>, L<PKCS7_sign(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
|
|
|||
|
|
@ -887,8 +887,6 @@ PKCS7_add1_attrib_digest(3)
|
|||
PKCS7_add_attrib_content_type(3)
|
||||
PKCS7_add_attrib_smimecap(3)
|
||||
PKCS7_add_attribute(3)
|
||||
PKCS7_add_certificate(3)
|
||||
PKCS7_add_crl(3)
|
||||
PKCS7_add_recipient(3)
|
||||
PKCS7_add_recipient_info(3)
|
||||
PKCS7_add_signature(3)
|
||||
|
|
|
|||
Loading…
Reference in New Issue