fixup! PKCS7 and SMIME: improve documentation w.r.t. untrusted and si…

…gner certificates

apps/cms.c

@@ -176,9 +176,9 @@ const OPTIONS cms_options[] = {
     {"md", OPT_MD, 's', "Digest algorithm to use"},
     {"signer", OPT_SIGNER, 's', "Signer certificate input file"},
     {"certfile", OPT_CERTFILE, '<',
-     "Other certificates to include when signing or to use when verifying;"},
+     "Extra signer and intermediate CA certificates to include when signing"},
     {OPT_MORE_STR, 0, 0,
-     "may be used for chain building and as signer cerificates"},
+     "or to use as preferred signer certificates when verifying"},
     {"cades", OPT_CADES, '-',
      "Include signingCertificate attribute (CAdES-BES)"},
     {"nodetach", OPT_NODETACH, '-', "Use opaque signing"},
@@ -846,7 +846,7 @@ int cms_main(int argc, char **argv)
     }
 
     if (certfile != NULL) {
-        if (!load_certs(certfile, 0, &other, NULL, "other certificates")) {
+        if (!load_certs(certfile, 0, &other, NULL, "extra certificates")) {
             ERR_print_errors(bio_err);
             goto end;
         }

apps/smime.c

@@ -107,9 +107,9 @@ const OPTIONS smime_options[] = {
 
     OPT_SECTION("Certificate chain"),
     {"certfile", OPT_CERTFILE, '<',
-     "Other certificates to include when signing or to use when verifying;"},
+     "Extra signer and intermediate CA certificates to include when signing"},
     {OPT_MORE_STR, 0, 0,
-     "may be used for chain building and as signer cerificates"},
+     "or to use as preferred signer certificates when verifying"},
     {"CApath", OPT_CAPATH, '/', "Trusted certificates directory"},
     {"CAfile", OPT_CAFILE, '<', "Trusted certificates file"},
     {"CAstore", OPT_CASTORE, ':', "Trusted certificates store URI"},
@@ -494,7 +494,7 @@ int smime_main(int argc, char **argv)
     }
 
     if (certfile != NULL) {
-        if (!load_certs(certfile, 0, &other, NULL, "other certificates")) {
+        if (!load_certs(certfile, 0, &other, NULL, "extra certificates")) {
             ERR_print_errors(bio_err);
             goto end;
         }

doc/man1/openssl-cms.pod.in

@@ -447,15 +447,21 @@ default digest algorithm for the signing key will be used (usually SHA1).
 
 =item B<-signer> I<file>
 
-A signing certificate.  When signing or resigning a message, this option can be
+A signer certificate.  When signing or resigning a message, this option can be
 used multiple times if more than one signer is required.
 
 =item B<-certfile> I<file>
 
-Provide additional certificates.
-When signing, these will be included
-in the message to help chain building and to provide extra signer certificates.
-When verifying, these will be searched first for signer certificates.
+Provide extra certificates.
+When signing, these will be included in the message and can serve
+both as candidate untrusted CA certificates for chain building in verification
+and as fallback signer certificates.
+When verifying, the provided certificates take precedence over the
+signer certificates in the message as a source of candidate signers.
+With B<-nointern> these will be the only signer certificates considered.
+
+Note that a message can have multiple signers.
+When verifying a multi-signed message, all the signatures must be valid, and so all the signer certificates need to be available.
 
 The input can be in PEM, DER, or PKCS#12 format.
 
@@ -475,9 +481,9 @@ the MIME type multipart/signed is used.
 
 =item B<-nocerts>
 
-When signing a message, the signer's certificate it normally
-included, but this option disables its inclusion. This will reduce the size of
-the signed message but the verifier must have a copy of the signers certificate
+When signing a message, the signer certificates are normally included,
+but this option disables their inclusion. This will reduce the size of the
+signed message but the verifier must then have a copy of the signer certificates
 available locally (passed using the B<-certfile> option for example).
 
 =item B<-noattr>
@@ -545,10 +551,10 @@ Do not verify the signers certificate of a signed message.
 =item B<-nointern>
 
 When verifying a message, normally certificates (if any) included in
-the message are searched for the signing certificate. With this option,
+the message are searched for the signer certificates. With this option,
 only the certificates given with the B<-certfile> option are used.
-However, the certificates included in
-the message are still used for chain building as certificates of untrusted CAs.
+However, the certificates included in the message are still used
+as candidate intermediate CA certificates during chain construction.
 
 =item B<-cades>
 

doc/man1/openssl-smime.pod.in

@@ -178,30 +178,30 @@ If not specified triple DES is used. Only used with B<-encrypt>.
 =item B<-nointern>
 
 When verifying a message, normally certificates (if any) included in
-the message are searched for the signing certificate. With this option,
+the message are searched for the signer certificates. With this option,
 only the certificates given with the B<-certfile> option are used.
-However, unless the B<-nochain> option is given, the certificates included in
-the message are still used for chain building as certificates of untrusted CAs.
+However, the certificates included in the message are still used
+as candidate intermediate CA certificates during chain construction.
 
 =item B<-noverify>
 
 Do not verify the signers certificate of a signed message.
 
 =item B<-nochain>
 
-During chain verification of signer certificates, do not use the certificates
-in the signed message as untrusted CA certificates for chain building.
+When verifying the signer certificates of a signed message, do not use the
+certificates in the message as candidate CA certificates for chain building.
 
 =item B<-nosigs>
 
 Don't try to verify the signatures on the message.
 
 =item B<-nocerts>
 
-When signing a message, the signer's certificate and chain certificates are
+When signing a message, the signer certificates and chain certificates are
 normally included, but this option disables their inclusion.
-This will reduce the size of
-the signed message but the verifier must have a copy of those certificates
+This will reduce the size of the
+signed message but the verifier must then have a copy of those certificates
 available locally (passed using the B<-certfile> option for example).
 
 =item B<-noattr>
@@ -235,16 +235,22 @@ option is present B<CRLF> is used instead.
 
 =item B<-certfile> I<file>
 
-Provide additional certificates.
+Provide extra certificates.
 When signing, these will be included (unless the B<-nocerts> option is given)
-in the message to help chain building and to provide extra signer certificates.
-When verifying, these will be searched first for signer certificates.
+in the message and can serve both as candidate untrusted CA certificates
+for chain building in verification and as fallback signer certificates.
+When verifying, the provided certificates take precedence over the
+signer certificates in the message as a source of candidate signers.
+With B<-nointern> these will be the only signer certificates considered.
+
+Note that a message can have multiple signers.
+When verifying a multi-signed message, all the signatures must be valid, and so all the signer certificates need to be available.
 
 The input can be in PEM, DER, or PKCS#12 format.
 
 =item B<-signer> I<file>
 
-A signing certificate when signing or resigning a message, this option can be
+A signer certificate when signing or resigning a message, this option can be
 used multiple times if more than one signer is required. If a message is being
 verified then the signers certificates will be written to this file if the
 verification was successful.

doc/man3/CMS_add0_cert.pod

@@ -22,10 +22,13 @@ CMS_add0_crl, CMS_add1_crl, CMS_get1_crls
 
 CMS_add0_cert() and CMS_add1_cert() add certificate I<cert> to I<cms>
 unless it is already present.
-This can be used with L<CMS_sign_ex(3)> and L<CMS_sign(3)>
-to include a chain certificate or an extra signer certificate
-and may be used with L<CMS_verify(3)> to set a
-fallback signer certificate or to help chain building in certificate validation.
+Signer certificates and intermediate CA certificates are usually added
+to a CMS structure by L<CMS_sign_ex(3)> and L<CMS_sign(3)>, yet further
+such certificates may be added in advance by directly calling these functions.
+The verifier of the message can use the included certificates
+as candidate signer certificates and for chain building.
+These functions may also be used before calling L<CMS_verify(3)> to add
+fallback signer certificates or intermediate CA certificates for chain building.
 As the 0 implies, CMS_add0_cert() adds I<cert> internally to I<cms>
 and on success it must not be freed up by the caller.
 In contrast, the caller of CMS_add1_cert() must free I<cert>.

doc/man3/CMS_verify.pod

@@ -25,7 +25,7 @@ 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 can provide a list of certificates,
-which is searched first for the signer's certificate.
+which is searched first for signer 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

doc/man3/PKCS7_sign_add_signer.pod

@@ -34,8 +34,8 @@ 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
-but can also be called directly to add a further such certificate.
-It may be used before calling L<PKCS7_verify(3)>
+but can also be called directly to add another such certificate.
+It may be used also before calling L<PKCS7_verify(3)>
 to provide any missing certificate(s) needed for chain building
 or to provide a fallback signer certificate.
 
@@ -66,8 +66,8 @@ 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
-B<PKCS7> structure, the signer's certificate must still be supplied in the
+If B<PKCS7_NOCERTS> is set, the signer certificates will not be included in the
+B<PKCS7> structure. The signer certificates 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.
@@ -84,14 +84,12 @@ these algorithms is disabled then it will not be included.
 
 Certificates and CRLs are added to the I<cert> or
 I<crl> fields of PKCS7_SIGNED structure.
-A certificate or CRL may be added to the same PKCS7 structure
-more than once, although this does not make sense.
 
 =head1 RETURN VALUES
 
 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, or NULL if an error occurs.
+structure just added (which can be used to set additional attributes
+before it is finalized), or NULL if an error occurs.
 
 PKCS7_add_certificate() and PKCS7_add_crl() return 1 on success, 0 on error.
 

doc/man3/PKCS7_verify.pod

@@ -18,7 +18,7 @@ PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
 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 can provide a list of certificates,
-which is searched first for the signer's certificate.
+which is searched first for signer 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
@@ -28,7 +28,7 @@ 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.
 
-PKCS7_get0_signers() retrieves the signer's certificates from I<p7>, it does
+PKCS7_get0_signers() retrieves the signer 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().
 
@@ -45,10 +45,10 @@ 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
+An attempt is made to locate all the signer certificates, first looking in
 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.
+If any signer certificates cannot be located the operation fails.
 
 Each signer certificate is chain verified using by default the C<smime_sign>
 purpose and using the trusted certificate store I<store> if supplied.
@@ -71,8 +71,8 @@ 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 certificates.
-This means that all the signer's certificates must be in the I<certs> parameter.
+searched when locating the signer certificates.
+This means that all the signer certificates must be in the I<certs> parameter.
 
 If B<PKCS7_NOCRL> is set and CRL checking is enabled in I<store> then any
 CRLs in the message itself are ignored.
@@ -81,7 +81,7 @@ 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_NOVERIFY> is set the signer certificates are not chain verified.
 
 If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are
 not used as untrusted CA certificates for chain building.
@@ -92,7 +92,7 @@ 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 I<certs> parameter. In this case if the signer's certificate is not one
+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.
 
@@ -117,7 +117,7 @@ The error can be obtained from L<ERR_get_error(3)>.
 
 =head1 BUGS
 
-The trusted certificate store is not searched for the signer's certificates.
+The trusted certificate store is not searched for the signer certificates.
 This is primarily due to the inadequacies of the current B<X509_STORE>
 functionality.