PKCS12 etc.: Add hints on using -legacy and -provider-path options

Fixes #14790

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14891)

5 files changed, 16 insertions, 2 deletions

diff --git a/apps/lib/app_provider.c b/apps/lib/app_provider.c
index fd7d55c09b..c3100b2fa8 100644
--- a/apps/lib/app_provider.c
+++ b/apps/lib/app_provider.c
@@ -33,7 +33,8 @@ int app_provider_load(OSSL_LIB_CTX *libctx, const char *provider_name)
 
     prov = OSSL_PROVIDER_load(libctx, provider_name);
     if (prov == NULL) {
-        opt_printf_stderr("%s: unable to load provider %s\n",
+        opt_printf_stderr("%s: unable to load provider %s\n"
+                          "Hint: use -provider-path option or OPENSSL_MODULES environment variable.\n",
                           opt_getprog(), provider_name);
         ERR_print_errors(bio_err);
         return 0;
diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in
index b367be2b7f..7a75d9ca32 100644
--- a/doc/man1/openssl-pkcs12.pod.in
+++ b/doc/man1/openssl-pkcs12.pod.in
@@ -85,8 +85,13 @@ The PKCS#12 export encryption and MAC options such as B<-certpbe> and B<-iter>
 and many further options such as B<-chain> are relevant only with B<-export>.
 Conversely, the options regarding encryption of private keys when outputting
 PKCS#12 input are relevant only when the B<-export> option is not given.
+
 The default encryption algorithm is AES-256-CBC with PBKDF2 for key derivation.
 
+When encountering problems loading legacy PKCS#12 files that involve,
+for example, RC2-40-CBC,
+try using the B<-legacy> option and, if needed, the B<-provider-path> option.
+
 =over 4
 
 =item B<-help>
@@ -132,6 +137,11 @@ and so the input is just verified.
 =item B<-legacy>
 
 Use legacy mode of operation and automatically load the legacy provider.
+If OpenSSL is not installed system-wide,
+it is necessary to also use, for example, C<-provider-path ./providers>
+or to set the environment variable B<OPENSSL_MODULES>
+to point to the directory where the providers can be found.
+
 In the legacy mode, the default algorithm for certificate encryption
 is RC2_CBC or 3DES_CBC depending on whether the RC2 cipher is enabled
 in the build. The default algorithm for private key encryption is 3DES_CBC.
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 7b84921893..78b98ab7a6 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -652,10 +652,12 @@ the PKCS#11 URI as defined in RFC 7512 should be possible to use directly:
 =item B<-provider> I<name>
 
 Load and initialize the provider identified by I<name>.
+See L<provider(7)> for a more detailed description.
 
 =item B<-provider-path> I<path>
 
 Specifies the search path that is to be used for looking for providers.
+Equivalently, the B<OPENSSL_MODULES> environment variable may be set.
 
 =item B<-propquery> I<propq>
 
diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod
index f29f5e2835..f691191b6f 100644
--- a/doc/man7/openssl-env.pod
+++ b/doc/man7/openssl-env.pod
@@ -49,6 +49,7 @@ See L<OPENSSL_malloc(3)>.
 =item B<OPENSSL_MODULES>
 
 Specifies the directory from which cryptographic providers are loaded.
+Equivalently, the generic B<-provider-path> command-line option may be used.
 
 =item B<OPENSSL_WIN32_UTF8>
 
diff --git a/doc/perlvars.pm b/doc/perlvars.pm
index 0be68e275d..91dd5d8284 100644
--- a/doc/perlvars.pm
+++ b/doc/perlvars.pm
@@ -102,7 +102,7 @@ $OpenSSL::safe::opt_provider_item = ""
 . "\n"
 . "=item B<-propquery> I<propq>\n"
 . "\n"
-. "See L<openssl(1)/Provider Options>.";
+. "See L<openssl(1)/Provider Options>, L<provider(7)>, and L<property(7)>.";
 
 # Configuration option
 $OpenSSL::safe::opt_config_synopsis = ""