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 #19108)

doc/man3/CMS_add0_cert.pod

@@ -19,25 +19,33 @@ CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_ge
 
 =head1 DESCRIPTION
 
-CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
-must be of type signed data or enveloped data.
+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 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 B<cms>.
+CMS_get1_certs() returns all certificates in I<cms>.
 
-CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls()
-returns any CRLs in B<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>.
 
 =head1 NOTES
 
-The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
+The CMS_ContentInfo structure I<cms> must be of type signed data or enveloped
 data or an error will be returned.
 
-For signed data certificates and CRLs are added to the B<certificates> and
-B<crls> fields of SignedData structure. For enveloped data they are added to
+For signed data certificates and CRLs are added to the I<certificates> and
+I<crls> fields of SignedData structure. For enveloped data they are added to
 B<OriginatorInfo>.
 
-As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
-must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
+As the I<0> implies CMS_add0_cert() adds I<cert> internally to I<cms> and it
+must not be freed up after the call as opposed to CMS_add1_cert() where I<cert>
 must be freed up.
 
 The same certificate or CRL must not be added to the same cms structure more
@@ -50,7 +58,7 @@ CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
 
 CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
 or NULL if there are none or an error occurs. The only error which will occur
-in practice is if the B<cms> type is invalid.
+in practice is if the I<cms> type is invalid.
 
 =head1 SEE ALSO
 

doc/man3/CMS_verify.pod

@@ -15,58 +15,66 @@ CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
 
 =head1 DESCRIPTION
 
-CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
-structure to verify. B<certs> is a set of certificates in which to search for
-the signing certificate(s). B<store> is a trusted certificate store used for
-chain verification. B<indata> is the detached content if the content is not
-present in B<cms>. The content is written to B<out> if it is not NULL.
-
-B<flags> is an optional set of flags, which can be used to modify the verify
-operation.
-
-CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it may only
+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.
+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<indata> refers to the signed data if the content is detached from I<cms>.
+Otherwise I<indata> 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_get0_signers() retrieves the signing certificate(s) from I<cms>, it may only
 be called after a successful CMS_verify() operation.
 
 =head1 VERIFY PROCESS
 
 Normally the verify process proceeds as follows.
 
-Initially some sanity checks are performed on B<cms>. The type of B<cms> must
+Initially some sanity checks are performed on I<cms>. The type of I<cms> 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>.
+the content is detached I<indata> cannot be NULL.
 
 An attempt is made to locate all the signing certificate(s), first looking in
-the B<certs> parameter (if it is not NULL) and then looking in any
-certificates contained in the B<cms> structure itself. If any signing
-certificate cannot be located the operation fails.
+the I<certs> parameter (if it is not NULL) and then looking in any
+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 B<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 B<store> any internal
-CRLs are used in addition to attempting to look them up in B<store>. If any
-chain verify fails an error code is returned.
+Each signing certificate is chain verified using the I<smimesign> purpose and
+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 B<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 B<flags>
+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 B<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 B<store> then any
+If B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any
 CRLs in the message itself are ignored.
 
 If the B<CMS_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
 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.
@@ -81,20 +89,20 @@ 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 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 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
 setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
 and any modified content 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
@@ -104,24 +112,24 @@ 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_get0_signers() returns all signers or NULL if an error occurred.
 
 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
 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)>
 

doc/man3/PKCS7_sign.pod

@@ -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.
 

doc/man3/PKCS7_sign_add_signer.pod

@@ -2,30 +2,31 @@
 
 =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
 
  #include <openssl/pkcs7.h>
 
  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,22 +38,22 @@ 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
 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