Refactor -engine documentation
Common wording courtesy Richard Levitte.
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10128)
diff --git a/.gitignore b/.gitignore
index 659be22..91d2c03 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,28 +31,41 @@
doc/man1/openssl-crl.pod
doc/man1/openssl-dgst.pod
doc/man1/openssl-dhparam.pod
+doc/man1/openssl-dsa.pod
doc/man1/openssl-dsaparam.pod
+doc/man1/openssl-ec.pod
doc/man1/openssl-ecparam.pod
doc/man1/openssl-enc.pod
+doc/man1/openssl-engine.pod
doc/man1/openssl-gendsa.pod
+doc/man1/openssl-genpkey.pod
doc/man1/openssl-genrsa.pod
+doc/man1/openssl-info.pod
+doc/man1/openssl-list.pod
doc/man1/openssl-ocsp.pod
doc/man1/openssl-passwd.pod
doc/man1/openssl-pkcs12.pod
+doc/man1/openssl-pkcs7.pod
doc/man1/openssl-pkcs8.pod
+doc/man1/openssl-pkey.pod
+doc/man1/openssl-pkeyparam.pod
doc/man1/openssl-pkeyutl.pod
doc/man1/openssl-rand.pod
doc/man1/openssl-req.pod
+doc/man1/openssl-rsa.pod
doc/man1/openssl-rsautl.pod
doc/man1/openssl-s_client.pod
doc/man1/openssl-s_server.pod
doc/man1/openssl-s_time.pod
doc/man1/openssl-smime.pod
doc/man1/openssl-speed.pod
+doc/man1/openssl-spkac.pod
doc/man1/openssl-srp.pod
+doc/man1/openssl-storeutl.pod
doc/man1/openssl-ts.pod
doc/man1/openssl-verify.pod
doc/man1/openssl-x509.pod
+doc/man1/openssl.pod
# error code files
/crypto/err/openssl.txt.old
diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in
index ca8ebb8..44e581e 100644
--- a/doc/man1/openssl-ca.pod.in
+++ b/doc/man1/openssl-ca.pod.in
@@ -48,7 +48,6 @@
[B<-msie_hack>]
[B<-extensions> I<section>]
[B<-extfile> I<section>]
-[B<-engine> I<id>]
[B<-subj> I<arg>]
[B<-utf8>]
[B<-sigopt> I<nm>:I<v>]
@@ -58,6 +57,7 @@
[B<-sm2-id> I<string>]
[B<-sm2-hex-id> I<hex-string>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[I<certreq>...]
=for openssl ifdef engine sm2-id sm2-hex-id
@@ -253,13 +253,6 @@
(using the default section unless the B<-extensions> option is also
used).
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<ca>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-subj> I<arg>
Supersedes subject name given in the request.
@@ -310,6 +303,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 CRL OPTIONS
diff --git a/doc/man1/openssl-dgst.pod.in b/doc/man1/openssl-dgst.pod.in
index 4472b2f..4563ad1 100644
--- a/doc/man1/openssl-dgst.pod.in
+++ b/doc/man1/openssl-dgst.pod.in
@@ -27,7 +27,7 @@
[B<-hmac> I<key>]
[B<-fips-fingerprint>]
[B<-engine> I<id>]
-[B<-engine_impl>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
[I<file> ...]
@@ -168,13 +168,6 @@
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
-=item B<-engine> I<id>
-
-Use engine I<id> for operations (including private key storage).
-This engine is not used as source for digest algorithms, unless it is
-also specified in the configuration file or B<-engine_impl> is also
-specified.
-
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
@@ -182,6 +175,10 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+The engine is not used for digests unless the B<-engine_impl> option is
+used or it is configured to do so, see L<config(5)/Engine Configuration Module>.
+
=item I<file> ...
File or files to digest. If no files are specified then standard input is
diff --git a/doc/man1/openssl-dhparam.pod.in b/doc/man1/openssl-dhparam.pod.in
index d55931f..e125330 100644
--- a/doc/man1/openssl-dhparam.pod.in
+++ b/doc/man1/openssl-dhparam.pod.in
@@ -21,7 +21,7 @@
[B<-2>]
[B<-3>]
[B<-5>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
[I<numbits>]
@@ -102,12 +102,7 @@
This option converts the parameters into C code. The parameters can then
be loaded by calling the get_dhNNNN() function.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<dhparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
{- $OpenSSL::safe::opt_r_item -}
diff --git a/doc/man1/openssl-dsa.pod b/doc/man1/openssl-dsa.pod.in
similarity index 92%
rename from doc/man1/openssl-dsa.pod
rename to doc/man1/openssl-dsa.pod.in
index 8c7b037..548d368 100644
--- a/doc/man1/openssl-dsa.pod
+++ b/doc/man1/openssl-dsa.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-dsa - DSA key processing
@@ -31,7 +36,7 @@
[B<-modulus>]
[B<-pubin>]
[B<-pubout>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef pvk-string pvk-weak pvk-none engine
@@ -113,12 +118,7 @@
key will be output instead. This option is automatically set if the input is
a public key.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause L<openssl-dsa(1)>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-dsaparam.pod.in b/doc/man1/openssl-dsaparam.pod.in
index cfe7c31..bab7436 100644
--- a/doc/man1/openssl-dsaparam.pod.in
+++ b/doc/man1/openssl-dsaparam.pod.in
@@ -17,9 +17,9 @@
[B<-text>]
[B<-C>]
[B<-genkey>]
-[B<-engine> I<id>]
[B<-verbose>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[I<numbits>]
=head1 DESCRIPTION
@@ -75,12 +75,6 @@
This option will generate a DSA either using the specified or generated
parameters.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
=item B<-verbose>
@@ -88,6 +82,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=item I<numbits>
This option specifies that a parameter set should be generated of size
diff --git a/doc/man1/openssl-ec.pod b/doc/man1/openssl-ec.pod.in
similarity index 94%
rename from doc/man1/openssl-ec.pod
rename to doc/man1/openssl-ec.pod.in
index 2646c12..d20b49a 100644
--- a/doc/man1/openssl-ec.pod
+++ b/doc/man1/openssl-ec.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-ec - EC key processing
@@ -26,7 +31,7 @@
[B<-param_enc> I<arg>]
[B<-no_public>]
[B<-check>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -131,12 +136,7 @@
This option checks the consistency of an EC private or public key.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-ecparam.pod.in b/doc/man1/openssl-ecparam.pod.in
index 823ca51..ae2240c 100644
--- a/doc/man1/openssl-ecparam.pod.in
+++ b/doc/man1/openssl-ecparam.pod.in
@@ -24,7 +24,7 @@
[B<-param_enc> I<arg>]
[B<-no_seed>]
[B<-genkey>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
=for openssl ifdef engine
@@ -122,12 +122,7 @@
This option will generate an EC private key using the specified parameters.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<ecparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
{- $OpenSSL::safe::opt_r_item -}
diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in
index 0f1508e..cff127d 100644
--- a/doc/man1/openssl-enc.pod.in
+++ b/doc/man1/openssl-enc.pod.in
@@ -37,7 +37,7 @@
[B<-nopad>]
[B<-debug>]
[B<-none>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
=for openssl ifdef z engine
@@ -192,6 +192,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 NOTES
@@ -204,8 +206,8 @@
Engines which provide entirely new encryption algorithms (such as the ccgost
engine which provides gost89 algorithm) should be configured in the
-configuration file. Engines specified on the command line using -engine
-options can only be used for hardware-assisted implementations of
+configuration file. Engines specified on the command line using B<-engine>
+option can only be used for hardware-assisted implementations of
ciphers which are supported by the OpenSSL core or another engine specified
in the configuration file.
diff --git a/doc/man1/openssl-gendsa.pod.in b/doc/man1/openssl-gendsa.pod.in
index c15fdc9..46b9c70 100644
--- a/doc/man1/openssl-gendsa.pod.in
+++ b/doc/man1/openssl-gendsa.pod.in
@@ -22,9 +22,9 @@
[B<-des>]
[B<-des3>]
[B<-idea>]
-[B<-engine> I<id>]
[B<-verbose>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[I<paramfile>]
=for openssl ifdef engine
@@ -53,25 +53,20 @@
cipher before outputting it. A pass phrase is prompted for.
If none of these options is specified no encryption is used.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-verbose>
Print extra details about the operations being performed.
+{- $OpenSSL::safe::opt_r_item -}
+
+{- $OpenSSL::safe::opt_engine_item -}
+
=item I<paramfile>
The DSA parameter file to use. The parameters in this file determine
the size of the private key. DSA parameters can be generated and
examined using the L<openssl-dsaparam(1)> command.
-{- $OpenSSL::safe::opt_r_item -}
-
=back
=head1 NOTES
diff --git a/doc/man1/openssl-genpkey.pod b/doc/man1/openssl-genpkey.pod.in
similarity index 96%
rename from doc/man1/openssl-genpkey.pod
rename to doc/man1/openssl-genpkey.pod.in
index 69c642c..c031f23 100644
--- a/doc/man1/openssl-genpkey.pod
+++ b/doc/man1/openssl-genpkey.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-genpkey - generate a private key
@@ -12,12 +17,12 @@
[B<-outform> B<DER>|B<PEM>]
[B<-pass> I<arg>]
[B<-I<cipher>>]
-[B<-engine> I<id>]
[B<-paramfile> I<file>]
[B<-algorithm> I<alg>]
[B<-pkeyopt> I<opt>:I<value>]
[B<-genparam>]
[B<-text>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -53,14 +58,6 @@
This option encrypts the private key with the supplied cipher. Any algorithm
name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms. If used this option should precede all other
-options.
-
=item B<-algorithm> I<alg>
Public key algorithm to use such as RSA, DSA or DH. If used this option must
@@ -105,6 +102,8 @@
Print an (unencrypted) text representation of private and public keys and
parameters along with the PEM or DER structure.
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 KEY GENERATION OPTIONS
diff --git a/doc/man1/openssl-genrsa.pod.in b/doc/man1/openssl-genrsa.pod.in
index 16b887b..8a815ee 100644
--- a/doc/man1/openssl-genrsa.pod.in
+++ b/doc/man1/openssl-genrsa.pod.in
@@ -24,10 +24,10 @@
[B<-des3>]
[B<-idea>]
[B<-f4>|B<-3>]
-[B<-engine> I<id>]
[B<-primes> I<num>]
[B<-verbose>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[B<numbits>]
=for openssl ifdef engine
@@ -65,13 +65,6 @@
The public exponent to use, either 65537 or 3. The default is 65537.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-primes> I<num>
Specify the number of primes to use while generating the RSA key. The I<num>
@@ -85,6 +78,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=item B<numbits>
The size of the private key to generate in bits. This must be the last option
diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in
index 86c9de4..bc2f496 100644
--- a/doc/man1/openssl-pkcs12.pod.in
+++ b/doc/man1/openssl-pkcs12.pod.in
@@ -41,6 +41,7 @@
[B<-CSP> I<name>]
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -271,6 +272,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 NOTES
diff --git a/doc/man1/openssl-pkcs7.pod b/doc/man1/openssl-pkcs7.pod.in
similarity index 86%
rename from doc/man1/openssl-pkcs7.pod
rename to doc/man1/openssl-pkcs7.pod.in
index adfe54e..f62b69b 100644
--- a/doc/man1/openssl-pkcs7.pod
+++ b/doc/man1/openssl-pkcs7.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-pkcs7 - PKCS#7 utility
@@ -15,7 +20,7 @@
[B<-print_certs>]
[B<-text>]
[B<-noout>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -67,12 +72,7 @@
Don't output the encoded version of the PKCS#7 structure (or certificates
is B<-print_certs> is set).
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in
index b53f0ee..34b469d 100644
--- a/doc/man1/openssl-pkcs8.pod.in
+++ b/doc/man1/openssl-pkcs8.pod.in
@@ -23,12 +23,12 @@
[B<-v2> I<alg>]
[B<-v2prf> I<alg>]
[B<-v1> I<alg>]
-[B<-engine> I<id>]
[B<-scrypt>]
[B<-scrypt_N> I<N>]
[B<-scrypt_r> I<r>]
[B<-scrypt_p> I<p>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine scrypt scrypt_N scrypt_r scrypt_p
@@ -135,13 +135,6 @@
older implementations may not support PKCS#5 v2.0 and may require this option.
If not specified PKCS#5 v2.0 form is used.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-scrypt>
Uses the B<scrypt> algorithm for private key encryption using default
@@ -155,6 +148,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 NOTES
diff --git a/doc/man1/openssl-pkey.pod b/doc/man1/openssl-pkey.pod.in
similarity index 92%
rename from doc/man1/openssl-pkey.pod
rename to doc/man1/openssl-pkey.pod.in
index b1aa4af..e2905b6 100644
--- a/doc/man1/openssl-pkey.pod
+++ b/doc/man1/openssl-pkey.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-pkey - public or private key processing tool
@@ -21,9 +26,9 @@
[B<-noout>]
[B<-pubin>]
[B<-pubout>]
-[B<-engine> I<id>]
[B<-check>]
[B<-pubcheck>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -99,13 +104,6 @@
key will be output instead. This option is automatically set if
the input is a public key.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-check>
This option checks the consistency of a key pair for both public and private
@@ -116,6 +114,8 @@
This option checks the correctness of either a public key or the public component
of a key pair.
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 EXAMPLES
diff --git a/doc/man1/openssl-pkeyparam.pod b/doc/man1/openssl-pkeyparam.pod.in
similarity index 85%
rename from doc/man1/openssl-pkeyparam.pod
rename to doc/man1/openssl-pkeyparam.pod.in
index 36ff7f5..4488119 100644
--- a/doc/man1/openssl-pkeyparam.pod
+++ b/doc/man1/openssl-pkeyparam.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-pkeyparam - public key algorithm parameter processing tool
@@ -12,8 +17,8 @@
[B<-out> I<filename>]
[B<-text>]
[B<-noout>]
-[B<-engine> I<id>]
[B<-check>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -48,17 +53,12 @@
Do not output the encoded version of the parameters.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-check>
This option checks the correctness of parameters.
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 EXAMPLES
diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in
index 27f1d26..c239a04 100644
--- a/doc/man1/openssl-pkeyutl.pod.in
+++ b/doc/man1/openssl-pkeyutl.pod.in
@@ -34,7 +34,7 @@
[B<-pkeyopt_passin> I<opt>[:I<passarg>]]
[B<-hexdump>]
[B<-asn1parse>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
[B<-engine_impl>]
{- $OpenSSL::safe::opt_r_synopsis -}
@@ -179,12 +179,7 @@
Parse the ASN.1 output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=item B<-engine_impl>
diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in
index 17ffe9a..cd49679 100644
--- a/doc/man1/openssl-req.pod.in
+++ b/doc/man1/openssl-req.pod.in
@@ -45,11 +45,11 @@
[B<-sigopt> I<nm>:I<v>]
[B<-batch>]
[B<-verbose>]
-[B<-engine> I<id>]
[B<-sm2-id> I<string>]
[B<-sm2-hex-id> I<hex-string>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine keygen_engine sm2-id sm2-hex-id
@@ -301,13 +301,6 @@
Print extra details about the operations being performed.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-keygen_engine> I<id>
Specifies an engine (by its unique I<id> string) which would be used
@@ -327,6 +320,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 CONFIGURATION FILE FORMAT
diff --git a/doc/man1/openssl-rsa.pod b/doc/man1/openssl-rsa.pod.in
similarity index 93%
rename from doc/man1/openssl-rsa.pod
rename to doc/man1/openssl-rsa.pod.in
index 9e1be94..b391487 100644
--- a/doc/man1/openssl-rsa.pod
+++ b/doc/man1/openssl-rsa.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-rsa - RSA key processing tool
@@ -34,7 +39,7 @@
[B<-pubout>]
[B<-RSAPublicKey_in>]
[B<-RSAPublicKey_out>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef pvk-strong pvk-weak pvk-none engine
@@ -126,12 +131,7 @@
Like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index f010e60..8bd6c9e 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -112,7 +112,6 @@
[B<-starttls> I<protocol>]
[B<-xmpphost> I<hostname>]
[B<-name> I<hostname>]
-[B<-engine> I<id>]
[B<-tlsextdebug>]
[B<-no_ticket>]
[B<-sess_out> I<filename>]
@@ -131,6 +130,7 @@
{- $OpenSSL::safe::opt_x_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[I<host>:I<port>]
=for openssl ifdef engine ssl_client_engine ct noct ctlogfile
@@ -628,13 +628,6 @@
Load SSL session from I<filename>. The client will attempt to resume a
connection from this session.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-serverinfo> I<types>
A list of comma-separated TLS Extension Types (numbers between 0 and
@@ -707,6 +700,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 CONNECTED COMMANDS
diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in
index ed2d049..743ad61 100644
--- a/doc/man1/openssl-s_server.pod.in
+++ b/doc/man1/openssl-s_server.pod.in
@@ -166,7 +166,6 @@
[B<-nextprotoneg> I<val>]
[B<-use_srtp> I<val>]
[B<-alpn> I<val>]
-[B<-engine> I<val>]
[B<-keylogfile> I<outfile>]
[B<-max_early_data> I<int>]
[B<-early_data>]
@@ -177,6 +176,7 @@
{- $OpenSSL::safe::opt_x_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef unix 4 6 unlink no_dhe nextprotoneg use_srtp engine
@@ -676,13 +676,6 @@
"spdy/3".
The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used.
-=item B<-engine> I<val>
-
-Specifying an engine (by its unique id string in I<val>) will cause
-this command to attempt to obtain a functional reference to the
-specified engine, thus initialising it if needed. The engine will then be
-set as the default for all available algorithms.
-
=item B<-keylogfile> I<outfile>
Appends TLS secrets to the specified keylog file such that external programs
@@ -722,6 +715,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 CONNECTED COMMANDS
diff --git a/doc/man1/openssl-speed.pod.in b/doc/man1/openssl-speed.pod.in
index 164bf3d..6e1bb64 100644
--- a/doc/man1/openssl-speed.pod.in
+++ b/doc/man1/openssl-speed.pod.in
@@ -9,7 +9,6 @@
B<openssl speed>
[B<-help>]
-[B<-engine> I<id>]
[B<-elapsed>]
[B<-evp> I<algo>]
[B<-hmac> I<algo>]
@@ -19,6 +18,7 @@
[B<-seconds> I<num>]
[B<-bytes> I<num>]
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[I<algorithm> ...]
=for openssl ifdef cmac multi async_jobs engine
@@ -38,13 +38,6 @@
Print out a usage message.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-elapsed>
When calculating operations- or bytes-per-second, use wall-clock time
@@ -86,6 +79,8 @@
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=item I<algorithm> ...
If any I<algorithm> is given, then those algorithms are tested, otherwise a
diff --git a/doc/man1/openssl-spkac.pod b/doc/man1/openssl-spkac.pod.in
similarity index 92%
rename from doc/man1/openssl-spkac.pod
rename to doc/man1/openssl-spkac.pod.in
index a36d536..bfb17d1 100644
--- a/doc/man1/openssl-spkac.pod
+++ b/doc/man1/openssl-spkac.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-spkac - SPKAC printing and generating utility
@@ -19,7 +24,7 @@
[B<-spksect> I<section>]
[B<-noout>]
[B<-verify>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine
@@ -92,12 +97,7 @@
Verifies the digital signature on the supplied SPKAC.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-storeutl.pod b/doc/man1/openssl-storeutl.pod.in
similarity index 89%
rename from doc/man1/openssl-storeutl.pod
rename to doc/man1/openssl-storeutl.pod.in
index 0ceb1ce..3bfca08 100644
--- a/doc/man1/openssl-storeutl.pod
+++ b/doc/man1/openssl-storeutl.pod.in
@@ -1,5 +1,10 @@
=pod
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
=head1 NAME
openssl-storeutl - STORE utility
@@ -12,7 +17,6 @@
[B<-noout>]
[B<-passin> I<arg>]
[B<-text> I<arg>]
-[B<-engine> I<id>]
[B<-r>]
[B<-certs>]
[B<-keys>]
@@ -23,6 +27,7 @@
[B<-alias> I<arg>]
[B<-fingerprint> I<arg>]
[B<-I<digest>>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
I<uri> ...
=head1 DESCRIPTION
@@ -57,13 +62,6 @@
Prints out the objects in text form, similarly to the B<-text> output from
L<openssl-x509(1)>, L<openssl-pkey(1)>, etc.
-=item B<-engine> I<id>
-
-specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed.
-The engine will then be set as the default for all available algorithms.
-
=item B<-r>
Fetch objects recursively when possible.
@@ -110,6 +108,8 @@
The digest that was used to compute the fingerprint given with B<-fingerprint>.
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head1 SEE ALSO
diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in
index f6202fa..0eb4f80 100644
--- a/doc/man1/openssl-ts.pod.in
+++ b/doc/man1/openssl-ts.pod.in
@@ -37,7 +37,7 @@
[B<-out> I<response.tsr>]
[B<-token_out>]
[B<-text>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
B<openssl> B<ts>
B<-verify>
@@ -303,12 +303,7 @@
If this option is specified the output is human-readable text format
instead of DER. (Optional)
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms. Default is built-in. (Optional)
+{- $OpenSSL::safe::opt_engine_item -}
=back
diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in
index 100cff4..ab8257a 100644
--- a/doc/man1/openssl-verify.pod.in
+++ b/doc/man1/openssl-verify.pod.in
@@ -16,7 +16,6 @@
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
-[B<-engine> I<id>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
@@ -49,6 +48,7 @@
[B<-sm2-hex-id> I<hex-string>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
[B<-->]
[I<certificate> ...]
@@ -101,15 +101,6 @@
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
-=item B<-engine> I<id>
-
-Specifying an engine I<id> will cause this command to attempt to load the
-specified engine.
-The engine will then be set as the default for all its supported algorithms.
-If you want to load certificates or CRLs that require engine support via any of
-the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
-must be specified before those options.
-
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC5280).
@@ -303,6 +294,11 @@
{- $OpenSSL::safe::opt_trust_item -}
+{- $OpenSSL::safe::opt_engine_item -}
+To load certificates or CRLs that require engine support, specify the
+B<-engine> option before any of the
+B<-trusted>, B<-untrusted> or B<-CRLfile> options.
+
=item B<-->
Indicates the last option. All arguments following this are assumed to be
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index 5dfb9bb..a69d219 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -63,10 +63,10 @@
[B<-extfile> I<filename>]
[B<-extensions> I<section>]
[B<-sigopt> I<nm>:I<v>]
-[B<-engine> I<id>]
[B<-preserve_dates>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
=for openssl ifdef engine subject_hash_old issuer_hash_old
@@ -117,13 +117,6 @@
If not specified then SHA1 is used with B<-fingerprint> or
the default digest for the signing algorithm is used, typically SHA256.
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
=item B<-preserve_dates>
When signing a certificate, preserve the "notBefore" and "notAfter" dates
@@ -132,6 +125,8 @@
{- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_item -}
+
=back
=head2 Display Options
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 2e58b1b..5ef5374 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -933,6 +933,19 @@
=back
+=head2 Engine Options
+
+=over 4
+
+=item B<-engine> I<id>
+
+Use the engine identified by I<id> and use all the methods it
+implements (algorithms, key storage, etc.), unless specified otherwise in
+the command-specific documentation or it is configured to do so, as described
+in L<config(5)/Engine Configuration Module>.
+
+=back
+
=head1 ENVIRONMENT
The OpenSSL library can be take some configuration parameters from the
diff --git a/doc/perlvars.pm b/doc/perlvars.pm
index 5425c87..4e9dc31 100644
--- a/doc/perlvars.pm
+++ b/doc/perlvars.pm
@@ -85,6 +85,14 @@
. "\n"
. "See L<openssl(1)/Random State Options> for details.";
+# Engine option
+$OpenSSL::safe::opt_engine_synopsis = ""
+. "[B<-engine> I<id>]";
+$OpenSSL::safe::opt_engine_item = ""
+. "=item B<-engine> I<id>\n"
+. "\n"
+. "See L<openssl(1)/Engine Options>.";
+
# Trusted certs options
$OpenSSL::safe::opt_trust_synopsis = ""
. "[B<-CAfile> I<file>]\n"
