From 018aaeb47874272e157d35c05c68e826301d57f5 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sat, 12 Oct 2019 17:45:56 -0400 Subject: [PATCH] Refactor -engine documentation Common wording courtesy Richard Levitte. Reviewed-by: Dmitry Belyavskiy Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10128) --- .gitignore | 13 +++++++++++++ doc/man1/openssl-ca.pod.in | 11 +++-------- doc/man1/openssl-dgst.pod.in | 13 +++++-------- doc/man1/openssl-dhparam.pod.in | 9 ++------- .../{openssl-dsa.pod => openssl-dsa.pod.in} | 14 +++++++------- doc/man1/openssl-dsaparam.pod.in | 10 +++------- doc/man1/{openssl-ec.pod => openssl-ec.pod.in} | 14 +++++++------- doc/man1/openssl-ecparam.pod.in | 9 ++------- doc/man1/openssl-enc.pod.in | 8 +++++--- doc/man1/openssl-gendsa.pod.in | 15 +++++---------- ...enssl-genpkey.pod => openssl-genpkey.pod.in} | 17 ++++++++--------- doc/man1/openssl-genrsa.pod.in | 11 +++-------- doc/man1/openssl-pkcs12.pod.in | 3 +++ .../{openssl-pkcs7.pod => openssl-pkcs7.pod.in} | 14 +++++++------- doc/man1/openssl-pkcs8.pod.in | 11 +++-------- .../{openssl-pkey.pod => openssl-pkey.pod.in} | 16 ++++++++-------- ...l-pkeyparam.pod => openssl-pkeyparam.pod.in} | 16 ++++++++-------- doc/man1/openssl-pkeyutl.pod.in | 9 ++------- doc/man1/openssl-req.pod.in | 11 +++-------- .../{openssl-rsa.pod => openssl-rsa.pod.in} | 14 +++++++------- doc/man1/openssl-s_client.pod.in | 11 +++-------- doc/man1/openssl-s_server.pod.in | 11 +++-------- doc/man1/openssl-speed.pod.in | 11 +++-------- .../{openssl-spkac.pod => openssl-spkac.pod.in} | 14 +++++++------- ...ssl-storeutl.pod => openssl-storeutl.pod.in} | 16 ++++++++-------- doc/man1/openssl-ts.pod.in | 9 ++------- doc/man1/openssl-verify.pod.in | 16 ++++++---------- doc/man1/openssl-x509.pod.in | 11 +++-------- doc/man1/openssl.pod | 13 +++++++++++++ doc/perlvars.pm | 8 ++++++++ 30 files changed, 160 insertions(+), 198 deletions(-) rename doc/man1/{openssl-dsa.pod => openssl-dsa.pod.in} (93%) rename doc/man1/{openssl-ec.pod => openssl-ec.pod.in} (94%) rename doc/man1/{openssl-genpkey.pod => openssl-genpkey.pod.in} (96%) rename doc/man1/{openssl-pkcs7.pod => openssl-pkcs7.pod.in} (87%) rename doc/man1/{openssl-pkey.pod => openssl-pkey.pod.in} (92%) rename doc/man1/{openssl-pkeyparam.pod => openssl-pkeyparam.pod.in} (85%) rename doc/man1/{openssl-rsa.pod => openssl-rsa.pod.in} (93%) rename doc/man1/{openssl-spkac.pod => openssl-spkac.pod.in} (92%) rename doc/man1/{openssl-storeutl.pod => openssl-storeutl.pod.in} (90%) diff --git a/.gitignore b/.gitignore index 659be22843c..91d2c03b40d 100644 --- a/.gitignore +++ b/.gitignore @@ -31,28 +31,41 @@ doc/man1/openssl-cms.pod 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 ca8ebb8c70f..44e581e0d97 100644 --- a/doc/man1/openssl-ca.pod.in +++ b/doc/man1/openssl-ca.pod.in @@ -48,7 +48,6 @@ B B [B<-msie_hack>] [B<-extensions> I
] [B<-extfile> I
] -[B<-engine> I] [B<-subj> I] [B<-utf8>] [B<-sigopt> I:I] @@ -58,6 +57,7 @@ B B [B<-sm2-id> I] [B<-sm2-hex-id> I] {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [I...] =for openssl ifdef engine sm2-id sm2-hex-id @@ -253,13 +253,6 @@ An additional configuration file to read certificate extensions from (using the default section unless the B<-extensions> option is also used). -=item B<-engine> I - -Specifying an engine (by its unique I string) will cause B -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 Supersedes subject name given in the request. @@ -310,6 +303,8 @@ certificate. The argument for this option is string of hexadecimal digits. {- $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 4472b2ffe05..4563ad1d5e6 100644 --- a/doc/man1/openssl-dgst.pod.in +++ b/doc/man1/openssl-dgst.pod.in @@ -27,7 +27,7 @@ B B|I [B<-hmac> I] [B<-fips-fingerprint>] [B<-engine> I] -[B<-engine_impl>] +{- $OpenSSL::safe::opt_engine_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} [I ...] @@ -168,13 +168,6 @@ option. Compute HMAC using a specific key for certain OpenSSL-FIPS operations. -=item B<-engine> I - -Use engine I 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 @@ engine I for digest operations. {- $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. + =item I ... 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 d55931fae80..e125330b360 100644 --- a/doc/man1/openssl-dhparam.pod.in +++ b/doc/man1/openssl-dhparam.pod.in @@ -21,7 +21,7 @@ B [B<-2>] [B<-3>] [B<-5>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} [I] @@ -102,12 +102,7 @@ This option prints out the DH parameters in human readable form. This option converts the parameters into C code. The parameters can then be loaded by calling the get_dhNNNN() function. -=item B<-engine> I - -Specifying an engine (by its unique I string) will cause B -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 93% rename from doc/man1/openssl-dsa.pod rename to doc/man1/openssl-dsa.pod.in index 8c7b03781e1..548d36874f7 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 B [B<-modulus>] [B<-pubin>] [B<-pubout>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef pvk-string pvk-weak pvk-none engine @@ -113,12 +118,7 @@ By default, a private key is output. With this option a public key will be output instead. This option is automatically set if the input is a public key. -=item B<-engine> I - -Specifying an engine (by its unique I string) will cause L -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 cfe7c31e598..bab743672f1 100644 --- a/doc/man1/openssl-dsaparam.pod.in +++ b/doc/man1/openssl-dsaparam.pod.in @@ -17,9 +17,9 @@ B [B<-text>] [B<-C>] [B<-genkey>] -[B<-engine> I] [B<-verbose>] {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [I] =head1 DESCRIPTION @@ -75,12 +75,6 @@ be loaded by calling the get_dsaXXX() function. This option will generate a DSA either using the specified or generated parameters. -=item B<-engine> I - -Specifying an engine (by its unique I 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 @@ Print extra details about the operations being performed. {- $OpenSSL::safe::opt_r_item -} +{- $OpenSSL::safe::opt_engine_item -} + =item I 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 2646c126b5e..d20b49afcf6 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 B [B<-param_enc> I] [B<-no_public>] [B<-check>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -131,12 +136,7 @@ This option omits the public key components from the private key output. This option checks the consistency of an EC private or public key. -=item B<-engine> I - -Specifying an engine (by its unique I 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 823ca51273a..ae2240ca59a 100644 --- a/doc/man1/openssl-ecparam.pod.in +++ b/doc/man1/openssl-ecparam.pod.in @@ -24,7 +24,7 @@ B [B<-param_enc> I] [B<-no_seed>] [B<-genkey>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine @@ -122,12 +122,7 @@ is included in the ECParameters structure (see RFC 3279). This option will generate an EC private key using the specified parameters. -=item B<-engine> I - -Specifying an engine (by its unique I string) will cause B -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 0f1508e97ab..cff127d2119 100644 --- a/doc/man1/openssl-enc.pod.in +++ b/doc/man1/openssl-enc.pod.in @@ -37,7 +37,7 @@ B B|I [B<-nopad>] [B<-debug>] [B<-none>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef z engine @@ -192,6 +192,8 @@ Use NULL cipher (no encryption or decryption of input). {- $OpenSSL::safe::opt_r_item -} +{- $OpenSSL::safe::opt_engine_item -} + =back =head1 NOTES @@ -204,8 +206,8 @@ Use the L command to get a list of supported ciphers. 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 c15fdc9d037..46b9c70bba5 100644 --- a/doc/man1/openssl-gendsa.pod.in +++ b/doc/man1/openssl-gendsa.pod.in @@ -22,9 +22,9 @@ B B [B<-des>] [B<-des3>] [B<-idea>] -[B<-engine> I] [B<-verbose>] {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [I] =for openssl ifdef engine @@ -53,25 +53,20 @@ These options encrypt the private key with specified 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 - -Specifying an engine (by its unique I 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 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 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 69c642cdf7a..c031f238af2 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 B [B<-outform> B|B] [B<-pass> I] [B<-I>] -[B<-engine> I] [B<-paramfile> I] [B<-algorithm> I] [B<-pkeyopt> I:I] [B<-genparam>] [B<-text>] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -53,14 +58,6 @@ see L. This option encrypts the private key with the supplied cipher. Any algorithm name accepted by EVP_get_cipherbyname() is acceptable such as B. -=item B<-engine> I - -Specifying an engine (by its unique I 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 Public key algorithm to use such as RSA, DSA or DH. If used this option must @@ -105,6 +102,8 @@ are mutually exclusive. 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 16b887be994..8a815ee9606 100644 --- a/doc/man1/openssl-genrsa.pod.in +++ b/doc/man1/openssl-genrsa.pod.in @@ -24,10 +24,10 @@ B B [B<-des3>] [B<-idea>] [B<-f4>|B<-3>] -[B<-engine> I] [B<-primes> I] [B<-verbose>] {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [B] =for openssl ifdef engine @@ -65,13 +65,6 @@ for if it is not supplied via the B<-passout> argument. The public exponent to use, either 65537 or 3. The default is 65537. -=item B<-engine> I - -Specifying an engine (by its unique I 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 Specify the number of primes to use while generating the RSA key. The I @@ -85,6 +78,8 @@ Print extra details about the operations being performed. {- $OpenSSL::safe::opt_r_item -} +{- $OpenSSL::safe::opt_engine_item -} + =item B 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 86c9de46704..bc2f4963d58 100644 --- a/doc/man1/openssl-pkcs12.pod.in +++ b/doc/man1/openssl-pkcs12.pod.in @@ -41,6 +41,7 @@ B B [B<-CSP> I] {- $OpenSSL::safe::opt_trust_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -271,6 +272,8 @@ Write I as a Microsoft CSP name. {- $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 87% rename from doc/man1/openssl-pkcs7.pod rename to doc/man1/openssl-pkcs7.pod.in index adfe54ec0ea..f62b69b52b0 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 B [B<-print_certs>] [B<-text>] [B<-noout>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -67,12 +72,7 @@ issuer names. Don't output the encoded version of the PKCS#7 structure (or certificates is B<-print_certs> is set). -=item B<-engine> I - -Specifying an engine (by its unique I 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 b53f0ee8ce5..34b469ddbc6 100644 --- a/doc/man1/openssl-pkcs8.pod.in +++ b/doc/man1/openssl-pkcs8.pod.in @@ -23,12 +23,12 @@ B B [B<-v2> I] [B<-v2prf> I] [B<-v1> I] -[B<-engine> I] [B<-scrypt>] [B<-scrypt_N> I] [B<-scrypt_r> I] [B<-scrypt_p> I

] {- $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 @@ This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some 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 - -Specifying an engine (by its unique I 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 algorithm for private key encryption using default @@ -155,6 +148,8 @@ Sets the scrypt I, I or I

parameters. {- $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 b1aa4af454b..e2905b69340 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 B [B<-noout>] [B<-pubin>] [B<-pubout>] -[B<-engine> I] [B<-check>] [B<-pubcheck>] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -99,13 +104,6 @@ By default a private key is output: with this option a public key will be output instead. This option is automatically set if the input is a public key. -=item B<-engine> I - -Specifying an engine (by its unique I 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 @@ components. 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 36ff7f5245b..44881191213 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 B [B<-out> I] [B<-text>] [B<-noout>] -[B<-engine> I] [B<-check>] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -48,17 +53,12 @@ Prints out the parameters in plain text in addition to the encoded version. Do not output the encoded version of the parameters. -=item B<-engine> I - -Specifying an engine (by its unique I 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 27f1d26ac82..c239a0469a4 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -34,7 +34,7 @@ B B [B<-pkeyopt_passin> I[:I]] [B<-hexdump>] [B<-asn1parse>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} [B<-engine_impl>] {- $OpenSSL::safe::opt_r_synopsis -} @@ -179,12 +179,7 @@ hex dump the output data. 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 - -Specifying an engine (by its unique I 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 17ffe9ade68..cd49679d048 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -45,11 +45,11 @@ B B [B<-sigopt> I:I] [B<-batch>] [B<-verbose>] -[B<-engine> I] [B<-sm2-id> I] [B<-sm2-hex-id> I] {- $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 @@ Non-interactive mode. Print extra details about the operations being performed. -=item B<-engine> I - -Specifying an engine (by its unique I 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 Specifies an engine (by its unique I string) which would be used @@ -327,6 +320,8 @@ argument for this option is string of hexadecimal digits. {- $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 9e1be94a269..b391487719f 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 B [B<-pubout>] [B<-RSAPublicKey_in>] [B<-RSAPublicKey_out>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef pvk-strong pvk-weak pvk-none engine @@ -126,12 +131,7 @@ the input is a public key. Like B<-pubin> and B<-pubout> except B format is used instead. -=item B<-engine> I - -Specifying an engine (by its unique I 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 f010e606795..8bd6c9eec18 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -112,7 +112,6 @@ B B [B<-starttls> I] [B<-xmpphost> I] [B<-name> I] -[B<-engine> I] [B<-tlsextdebug>] [B<-no_ticket>] [B<-sess_out> I] @@ -131,6 +130,7 @@ B B {- $OpenSSL::safe::opt_x_synopsis -} {- $OpenSSL::safe::opt_trust_synopsis -} {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [I:I] =for openssl ifdef engine ssl_client_engine ct noct ctlogfile @@ -628,13 +628,6 @@ Output SSL session to I. Load SSL session from I. The client will attempt to resume a connection from this session. -=item B<-engine> I - -Specifying an engine (by its unique I 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 A list of comma-separated TLS Extension Types (numbers between 0 and @@ -707,6 +700,8 @@ I on port I<4433>. {- $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 ed2d0490811..743ad616d5f 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -166,7 +166,6 @@ B B [B<-nextprotoneg> I] [B<-use_srtp> I] [B<-alpn> I] -[B<-engine> I] [B<-keylogfile> I] [B<-max_early_data> I] [B<-early_data>] @@ -177,6 +176,7 @@ B B {- $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 @@ Protocol names are printable ASCII strings, for example "http/1.1" or "spdy/3". The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used. -=item B<-engine> I - -Specifying an engine (by its unique id string in I) 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 Appends TLS secrets to the specified keylog file such that external programs @@ -722,6 +715,8 @@ by the client in binary mode. {- $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 164bf3d9d72..6e1bb642e15 100644 --- a/doc/man1/openssl-speed.pod.in +++ b/doc/man1/openssl-speed.pod.in @@ -9,7 +9,6 @@ openssl-speed - test library performance B [B<-help>] -[B<-engine> I] [B<-elapsed>] [B<-evp> I] [B<-hmac> I] @@ -19,6 +18,7 @@ B [B<-seconds> I] [B<-bytes> I] {- $OpenSSL::safe::opt_r_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [I ...] =for openssl ifdef cmac multi async_jobs engine @@ -38,13 +38,6 @@ the B algorithm name. Print out a usage message. -=item B<-engine> I - -Specifying an engine (by its unique I 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 @@ Run benchmarks on I-byte buffers. Affects ciphers, digests and the CSPRNG. {- $OpenSSL::safe::opt_r_item -} +{- $OpenSSL::safe::opt_engine_item -} + =item I ... If any I 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 a36d5364d9b..bfb17d12083 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 B [B<-spksect> I

] [B<-noout>] [B<-verify>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} =for openssl ifdef engine @@ -92,12 +97,7 @@ being created). Verifies the digital signature on the supplied SPKAC. -=item B<-engine> I - -Specifying an engine (by its unique I 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 90% rename from doc/man1/openssl-storeutl.pod rename to doc/man1/openssl-storeutl.pod.in index 0ceb1cea97c..3bfca0873e8 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 B [B<-noout>] [B<-passin> I] [B<-text> I] -[B<-engine> I] [B<-r>] [B<-certs>] [B<-keys>] @@ -23,6 +27,7 @@ B B [B<-alias> I] [B<-fingerprint> I] [B<-I>] +{- $OpenSSL::safe::opt_engine_synopsis -} I ... =head1 DESCRIPTION @@ -57,13 +62,6 @@ see L. Prints out the objects in text form, similarly to the B<-text> output from L, L, etc. -=item B<-engine> I - -specifying an engine (by its unique I 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 @@ Search for an object having the given fingerprint. 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 f6202fa92f4..0eb4f8031aa 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -37,7 +37,7 @@ B<-reply> [B<-out> I] [B<-token_out>] [B<-text>] -[B<-engine> I] +{- $OpenSSL::safe::opt_engine_synopsis -} B B B<-verify> @@ -303,12 +303,7 @@ response (TimeStampResp). (Optional) If this option is specified the output is human-readable text format instead of DER. (Optional) -=item B<-engine> I - -Specifying an engine (by its unique I 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 100cff4a6bf..ab8257a5e46 100644 --- a/doc/man1/openssl-verify.pod.in +++ b/doc/man1/openssl-verify.pod.in @@ -16,7 +16,6 @@ B B [B<-crl_download>] [B<-crl_check>] [B<-crl_check_all>] -[B<-engine> I] [B<-explicit_policy>] [B<-extended_crl>] [B<-ignore_critical>] @@ -49,6 +48,7 @@ B B [B<-sm2-hex-id> I] {- $OpenSSL::safe::opt_name_synopsis -} {- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -} [B<-->] [I ...] @@ -101,15 +101,6 @@ If a valid CRL cannot be found an error occurs. Checks the validity of B certificates in the chain by attempting to look up valid CRLs. -=item B<-engine> I - -Specifying an engine I 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 @@ certificate. The argument for this option is string of hexadecimal digits. {- $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 5dfb9bb0e6f..a69d219f744 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/doc/man1/openssl-x509.pod.in @@ -63,10 +63,10 @@ B B [B<-extfile> I] [B<-extensions> I
] [B<-sigopt> I:I] -[B<-engine> I] [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 @@ Any digest supported by the L command can be used. 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 - -Specifying an engine (by its unique I 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 @@ Cannot be used with the B<-days> option. {- $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 2e58b1bb3e9..5ef537434cc 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -933,6 +933,19 @@ name. =back +=head2 Engine Options + +=over 4 + +=item B<-engine> I + +Use the engine identified by I 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. + +=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 5425c87e03c..4e9dc31ac25 100644 --- a/doc/perlvars.pm +++ b/doc/perlvars.pm @@ -85,6 +85,14 @@ $OpenSSL::safe::opt_r_item = "" . "\n" . "See L for details."; +# Engine option +$OpenSSL::safe::opt_engine_synopsis = "" +. "[B<-engine> I]"; +$OpenSSL::safe::opt_engine_item = "" +. "=item B<-engine> I\n" +. "\n" +. "See L."; + # Trusted certs options $OpenSSL::safe::opt_trust_synopsis = "" . "[B<-CAfile> I]\n" -- 2.47.2