Document -trusted_first option in man pages and help.

Add -trusted_first description to help messages and man pages
of tools that deal with certificate verification.

apps/cms.c

@@ -716,6 +716,7 @@ int MAIN(int argc, char **argv)
 		BIO_printf (bio_err, "-text          include or delete text MIME headers\n");
 		BIO_printf (bio_err, "-CApath dir    trusted certificates directory\n");
 		BIO_printf (bio_err, "-CAfile file   trusted certificates file\n");
+		BIO_printf (bio_err, "-trusted_first use locally trusted certificates first when building trust chain\n");
 		BIO_printf (bio_err, "-crl_check     check revocation status of signer's certificate using CRLs\n");
 		BIO_printf (bio_err, "-crl_check_all check revocation status of signer's certificate chain using CRLs\n");
 #ifndef OPENSSL_NO_ENGINE

apps/ocsp.c

@@ -626,6 +626,7 @@ int MAIN(int argc, char **argv)
 		BIO_printf (bio_err, "-path              path to use in OCSP request\n");
 		BIO_printf (bio_err, "-CApath dir        trusted certificates directory\n");
 		BIO_printf (bio_err, "-CAfile file       trusted certificates file\n");
+		BIO_printf (bio_err, "-trusted_first     use locally trusted CA's first when building trust chain\n");
 		BIO_printf (bio_err, "-VAfile file       validator certificates file\n");
 		BIO_printf (bio_err, "-validity_period n maximum validity discrepancy in seconds\n");
 		BIO_printf (bio_err, "-status_age n      maximum status age in seconds\n");

apps/s_client.c

@@ -334,6 +334,7 @@ static void sc_usage(void)
 	BIO_printf(bio_err," -pass arg     - private key file pass phrase source\n");
 	BIO_printf(bio_err," -CApath arg   - PEM format directory of CA's\n");
 	BIO_printf(bio_err," -CAfile arg   - PEM format file of CA's\n");
+	BIO_printf(bio_err," -trusted_first - Use local CA's first when building trust chain\n");
 	BIO_printf(bio_err," -reconnect    - Drop and re-make the connection with the same Session-ID\n");
 	BIO_printf(bio_err," -pause        - sleep(1) after each read(2) and write(2) system call\n");
 	BIO_printf(bio_err," -showcerts    - show all certificates in the chain\n");

apps/s_server.c

@@ -526,6 +526,7 @@ static void sv_usage(void)
 	BIO_printf(bio_err," -state        - Print the SSL states\n");
 	BIO_printf(bio_err," -CApath arg   - PEM format directory of CA's\n");
 	BIO_printf(bio_err," -CAfile arg   - PEM format file of CA's\n");
+	BIO_printf(bio_err," -trusted_first - Use locally trusted CA's first when building trust chain\n");
 	BIO_printf(bio_err," -nocert       - Don't use any certificates (Anon-DH)\n");
 	BIO_printf(bio_err," -cipher arg   - play with 'openssl ciphers' to see what goes here\n");
 	BIO_printf(bio_err," -serverpref   - Use server's cipher preferences\n");

apps/smime.c

@@ -479,6 +479,7 @@ int MAIN(int argc, char **argv)
 		BIO_printf (bio_err, "-text          include or delete text MIME headers\n");
 		BIO_printf (bio_err, "-CApath dir    trusted certificates directory\n");
 		BIO_printf (bio_err, "-CAfile file   trusted certificates file\n");
+		BIO_printf (bio_err, "-trusted_first use locally trusted CA's first when building trust chain\n");
 		BIO_printf (bio_err, "-crl_check     check revocation status of signer's certificate using CRLs\n");
 		BIO_printf (bio_err, "-crl_check_all check revocation status of signer's certificate chain using CRLs\n");
 #ifndef OPENSSL_NO_ENGINE

apps/verify.c

@@ -245,7 +245,7 @@ int MAIN(int argc, char **argv)
 
 end:
 	if (ret == 1) {
-		BIO_printf(bio_err,"usage: verify [-verbose] [-CApath path] [-CAfile file] [-purpose purpose] [-crl_check]");
+		BIO_printf(bio_err,"usage: verify [-verbose] [-CApath path] [-CAfile file] [-trusted_first] [-purpose purpose] [-crl_check]");
 #ifndef OPENSSL_NO_ENGINE
 		BIO_printf(bio_err," [-engine e]");
 #endif

doc/apps/cms.pod

@@ -35,6 +35,7 @@ B<openssl> B<cms>
 [B<-print>]
 [B<-CAfile file>]
 [B<-CApath dir>]
+[B<-trusted_first>]
 [B<-md digest>]
 [B<-[cipher]>]
 [B<-nointern>]
@@ -429,9 +430,9 @@ portion of a message so they may be included manually. If signing
 then many S/MIME mail clients check the signers certificate's email
 address matches that specified in the From: address.
 
-=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig>
+=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig, -trusted_first>
 
-Set various certificate chain valiadition option. See the
+Set various certificate chain valiadition options. See the
 L<B<verify>|verify(1)> manual page for details.
 
 =back

doc/apps/ocsp.pod

@@ -29,6 +29,7 @@ B<openssl> B<ocsp>
 [B<-path>]
 [B<-CApath dir>]
 [B<-CAfile file>]
+[B<-trusted_first>]
 [B<-VAfile file>]
 [B<-validity_period n>]
 [B<-status_age n>]
@@ -138,6 +139,11 @@ or "/" by default.
 file or pathname containing trusted CA certificates. These are used to verify
 the signature on the OCSP response.
 
+=item B<-trusted_first>
+
+Set certificate verification option.
+See L<B<verify>|verify(1)> manual page for details.
+
 =item B<-verify_other file>
 
 file containing additional certificates to search when attempting to locate

doc/apps/s_client.pod

@@ -18,6 +18,7 @@ B<openssl> B<s_client>
 [B<-pass arg>]
 [B<-CApath directory>]
 [B<-CAfile filename>]
+[B<-trusted_first>]
 [B<-reconnect>]
 [B<-pause>]
 [B<-showcerts>]
@@ -116,9 +117,9 @@ also used when building the client certificate chain.
 A file containing trusted certificates to use during server authentication
 and to use when attempting to build the client certificate chain.
 
-=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig>
+=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig, -trusted_first>
 
-Set various certificate chain valiadition option. See the
+Set various certificate chain valiadition options. See the
 L<B<verify>|verify(1)> manual page for details.
 
 =item B<-reconnect>

doc/apps/s_server.pod

@@ -34,6 +34,7 @@ B<openssl> B<s_server>
 [B<-state>]
 [B<-CApath directory>]
 [B<-CAfile filename>]
+[B<-trusted_first>]
 [B<-nocert>]
 [B<-cipher cipherlist>]
 [B<-quiet>]
@@ -183,6 +184,11 @@ and to use when attempting to build the server certificate chain. The list
 is also used in the list of acceptable client CAs passed to the client when
 a certificate is requested.
 
+=item B<-trusted_first>
+
+Set certificate verification option.
+See the L<B<verify>|verify(1)> manual page for details.
+
 =item B<-state>
 
 prints out the SSL session states.

doc/apps/smime.pod

@@ -15,6 +15,7 @@ B<openssl> B<smime>
 [B<-pk7out>]
 [B<-[cipher]>]
 [B<-in file>]
+[B<-trusted_first>]
 [B<-certfile file>]
 [B<-signer file>]
 [B<-recip  file>]
@@ -259,7 +260,7 @@ portion of a message so they may be included manually. If signing
 then many S/MIME mail clients check the signers certificate's email
 address matches that specified in the From: address.
 
-=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig>
+=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig, -trusted_first>
 
 Set various options of certificate chain verification. See
 L<B<verify>|verify(1)> manual page for details.

doc/apps/verify.pod

@@ -9,6 +9,7 @@ verify - Utility to verify certificates.
 B<openssl> B<verify>
 [B<-CApath directory>]
 [B<-CAfile file>]
+[B<-trusted_first>]
 [B<-purpose purpose>]
 [B<-policy arg>]
 [B<-ignore_critical>]
@@ -57,6 +58,12 @@ in PEM format concatenated together.
 A file of untrusted certificates. The file should contain multiple certificates
 in PEM format concatenated together.
 
+=item B<-trusted_first>
+
+Use certificates in CA file or CA directory before certificates in untrusted
+file when building the trust chain to verify certificates.
+This is mainly useful in environments with Bridge CA or Cross-Certified CAs.
+
 =item B<-purpose purpose>
 
 The intended use for the certificate. If this option is not specified,