From 9fcb9702fba8aa135945f96aefddf050a6f4f11d Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sat, 12 Oct 2019 17:45:56 -0400 Subject: [PATCH] Infrastructure for templated doc in POD files Use new doc-build capabilities Add -i flag to dofile. Add doc/man1 to SUBDIRS for the new templated doc files Rewrite commit a397aca (merged from PR 10118) to use the doc-template stuff. Put template references in common place Template options and text come at the end of command-specific options: opt_x, opt_trust, opt_r (in that order). Refactor xchain options. Do doc-nits after building generated sources. Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/10159) --- .gitignore | 29 ++++ .travis.yml | 8 +- build.info | 3 +- doc/man1/build.info | 84 ++++++++++++ .../{openssl-ca.pod => openssl-ca.pod.in} | 14 +- .../{openssl-cms.pod => openssl-cms.pod.in} | 35 +++-- .../{openssl-crl.pod => openssl-crl.pod.in} | 14 +- .../{openssl-dgst.pod => openssl-dgst.pod.in} | 14 +- ...ssl-dhparam.pod => openssl-dhparam.pod.in} | 14 +- ...l-dsaparam.pod => openssl-dsaparam.pod.in} | 14 +- ...ssl-ecparam.pod => openssl-ecparam.pod.in} | 14 +- .../{openssl-enc.pod => openssl-enc.pod.in} | 12 +- ...enssl-gendsa.pod => openssl-gendsa.pod.in} | 14 +- ...enssl-genrsa.pod => openssl-genrsa.pod.in} | 14 +- .../{openssl-ocsp.pod => openssl-ocsp.pod.in} | 16 +-- ...enssl-passwd.pod => openssl-passwd.pod.in} | 12 +- ...enssl-pkcs12.pod => openssl-pkcs12.pod.in} | 25 ++-- ...openssl-pkcs8.pod => openssl-pkcs8.pod.in} | 14 +- ...ssl-pkeyutl.pod => openssl-pkeyutl.pod.in} | 14 +- .../{openssl-rand.pod => openssl-rand.pod.in} | 14 +- .../{openssl-req.pod => openssl-req.pod.in} | 14 +- ...enssl-rsautl.pod => openssl-rsautl.pod.in} | 14 +- ...l-s_client.pod => openssl-s_client.pod.in} | 64 +++------ ...l-s_server.pod => openssl-s_server.pod.in} | 56 ++------ ...enssl-s_time.pod => openssl-s_time.pod.in} | 16 +-- ...openssl-smime.pod => openssl-smime.pod.in} | 25 ++-- ...openssl-speed.pod => openssl-speed.pod.in} | 14 +- .../{openssl-srp.pod => openssl-srp.pod.in} | 12 +- .../{openssl-ts.pod => openssl-ts.pod.in} | 14 +- ...enssl-verify.pod => openssl-verify.pod.in} | 16 +-- .../{openssl-x509.pod => openssl-x509.pod.in} | 14 +- doc/man1/openssl.pod | 36 ++++- doc/perlvars.pm | 129 ++++++++++++++++++ util/dofile.pl | 61 ++++++--- 34 files changed, 571 insertions(+), 292 deletions(-) create mode 100644 doc/man1/build.info rename doc/man1/{openssl-ca.pod => openssl-ca.pod.in} (99%) rename doc/man1/{openssl-cms.pod => openssl-cms.pod.in} (98%) rename doc/man1/{openssl-crl.pod => openssl-crl.pod.in} (91%) rename doc/man1/{openssl-dgst.pod => openssl-dgst.pod.in} (97%) rename doc/man1/{openssl-dhparam.pod => openssl-dhparam.pod.in} (96%) rename doc/man1/{openssl-dsaparam.pod => openssl-dsaparam.pod.in} (94%) rename doc/man1/{openssl-ecparam.pod => openssl-ecparam.pod.in} (96%) rename doc/man1/{openssl-enc.pod => openssl-enc.pod.in} (98%) rename doc/man1/{openssl-gendsa.pod => openssl-gendsa.pod.in} (93%) rename doc/man1/{openssl-genrsa.pod => openssl-genrsa.pod.in} (95%) rename doc/man1/{openssl-ocsp.pod => openssl-ocsp.pod.in} (98%) rename doc/man1/{openssl-passwd.pod => openssl-passwd.pod.in} (94%) rename doc/man1/{openssl-pkcs12.pod => openssl-pkcs12.pod.in} (96%) rename doc/man1/{openssl-pkcs8.pod => openssl-pkcs8.pod.in} (98%) rename doc/man1/{openssl-pkeyutl.pod => openssl-pkeyutl.pod.in} (98%) rename doc/man1/{openssl-rand.pod => openssl-rand.pod.in} (86%) rename doc/man1/{openssl-req.pod => openssl-req.pod.in} (99%) rename doc/man1/{openssl-rsautl.pod => openssl-rsautl.pod.in} (97%) rename doc/man1/{openssl-s_client.pod => openssl-s_client.pod.in} (95%) rename doc/man1/{openssl-s_server.pod => openssl-s_server.pod.in} (95%) rename doc/man1/{openssl-s_time.pod => openssl-s_time.pod.in} (96%) rename doc/man1/{openssl-smime.pod => openssl-smime.pod.in} (97%) rename doc/man1/{openssl-speed.pod => openssl-speed.pod.in} (94%) rename doc/man1/{openssl-srp.pod => openssl-srp.pod.in} (92%) rename doc/man1/{openssl-ts.pod => openssl-ts.pod.in} (99%) rename doc/man1/{openssl-verify.pod => openssl-verify.pod.in} (99%) rename doc/man1/{openssl-x509.pod => openssl-x509.pod.in} (99%) create mode 100644 doc/perlvars.pm diff --git a/.gitignore b/.gitignore index f035ab1975..fa57dfcb38 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,35 @@ /include/openssl/opensslconf.h /include/openssl/opensslv.h +# Auto generated doc files +doc/man1/openssl-ca.pod +doc/man1/openssl-cms.pod +doc/man1/openssl-crl.pod +doc/man1/openssl-dgst.pod +doc/man1/openssl-dhparam.pod +doc/man1/openssl-dsaparam.pod +doc/man1/openssl-ecparam.pod +doc/man1/openssl-enc.pod +doc/man1/openssl-gendsa.pod +doc/man1/openssl-genrsa.pod +doc/man1/openssl-ocsp.pod +doc/man1/openssl-passwd.pod +doc/man1/openssl-pkcs12.pod +doc/man1/openssl-pkcs8.pod +doc/man1/openssl-pkeyutl.pod +doc/man1/openssl-rand.pod +doc/man1/openssl-req.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-srp.pod +doc/man1/openssl-ts.pod +doc/man1/openssl-verify.pod +doc/man1/openssl-x509.pod + # error code files /crypto/err/openssl.txt.old /engines/e_afalg.txt.old diff --git a/.travis.yml b/.travis.yml index 9f616c7e00..4b104642ff 100644 --- a/.travis.yml +++ b/.travis.yml @@ -177,14 +177,14 @@ script: echo -e '\052\052 FAILED -- UPDATED FILES NOT COMMITED'; travis_terminate 1; fi - - if test -n "$CHECKDOCS" && ! $make doc-nits; then - echo -e '\052\052 FAILED -- MAKE DOC-NITS'; - travis_terminate 1; - fi - if test -n "$GENERATE" && ! $make build_all_generated; then echo -e '\052\052 FAILED -- MAKE BUILD_ALL_GENERATED'; travis_terminate 1; fi + - if test -n "$CHECKDOCS" && ! $make doc-nits; then + echo -e '\052\052 FAILED -- MAKE DOC-NITS'; + travis_terminate 1; + fi - if ! $make2; then echo -e '\052\052 FAILED -- MAKE'; travis_terminate 1; diff --git a/build.info b/build.info index 6b70b11006..a050ae9530 100644 --- a/build.info +++ b/build.info @@ -1,6 +1,6 @@ # Note that some of these directories are filtered in Configure. Look for # %skipdir there for further explanations. -SUBDIRS=crypto ssl apps test util tools fuzz engines providers +SUBDIRS=crypto ssl apps test util tools fuzz engines providers doc/man1 LIBS=libcrypto libssl INCLUDE[libcrypto]=. include @@ -12,6 +12,7 @@ DEPEND[libssl]=libcrypto DEPEND[]=include/openssl/opensslconf.h include/openssl/opensslv.h \ include/crypto/bn_conf.h include/crypto/dso_conf.h \ doc/man7/openssl_user_macros.pod + GENERATE[include/openssl/opensslconf.h]=include/openssl/opensslconf.h.in GENERATE[include/openssl/opensslv.h]=include/openssl/opensslv.h.in GENERATE[include/crypto/bn_conf.h]=include/crypto/bn_conf.h.in diff --git a/doc/man1/build.info b/doc/man1/build.info new file mode 100644 index 0000000000..aed1f948d5 --- /dev/null +++ b/doc/man1/build.info @@ -0,0 +1,84 @@ + +DEPEND[]= \ + openssl-ca.pod \ + openssl-cms.pod \ + openssl-crl.pod \ + openssl-dgst.pod \ + openssl-dhparam.pod \ + openssl-dsaparam.pod \ + openssl-ecparam.pod \ + openssl-enc.pod \ + openssl-gendsa.pod \ + openssl-genrsa.pod \ + openssl-ocsp.pod \ + openssl-passwd.pod \ + openssl-pkcs12.pod \ + openssl-pkcs8.pod \ + openssl-pkeyutl.pod \ + openssl-rand.pod \ + openssl-req.pod \ + openssl-rsautl.pod \ + openssl-s_client.pod \ + openssl-s_server.pod \ + openssl-s_time.pod \ + openssl-smime.pod \ + openssl-speed.pod \ + openssl-srp.pod \ + openssl-ts.pod \ + openssl-verify.pod \ + openssl-x509.pod + +DEPEND[openssl-ca.pod]=../perlvars.pm +GENERATE[openssl-ca.pod]=openssl-ca.pod.in +DEPEND[openssl-cms.pod]=../perlvars.pm +GENERATE[openssl-cms.pod]=openssl-cms.pod.in +DEPEND[openssl-crl.pod]=../perlvars.pm +GENERATE[openssl-crl.pod]=openssl-crl.pod.in +DEPEND[openssl-dgst.pod]=../perlvars.pm +GENERATE[openssl-dgst.pod]=openssl-dgst.pod.in +DEPEND[openssl-dhparam.pod]=../perlvars.pm +GENERATE[openssl-dhparam.pod]=openssl-dhparam.pod.in +DEPEND[openssl-dsaparam.pod]=../perlvars.pm +GENERATE[openssl-dsaparam.pod]=openssl-dsaparam.pod.in +DEPEND[openssl-ecparam.pod]=../perlvars.pm +GENERATE[openssl-ecparam.pod]=openssl-ecparam.pod.in +DEPEND[openssl-enc.pod]=../perlvars.pm +GENERATE[openssl-enc.pod]=openssl-enc.pod.in +DEPEND[openssl-gendsa.pod]=../perlvars.pm +GENERATE[openssl-gendsa.pod]=openssl-gendsa.pod.in +DEPEND[openssl-genrsa.pod]=../perlvars.pm +GENERATE[openssl-genrsa.pod]=openssl-genrsa.pod.in +DEPEND[openssl-ocsp.pod]=../perlvars.pm +GENERATE[openssl-ocsp.pod]=openssl-ocsp.pod.in +DEPEND[openssl-passwd.pod]=../perlvars.pm +GENERATE[openssl-passwd.pod]=openssl-passwd.pod.in +DEPEND[openssl-pkcs8.pod]=../perlvars.pm +GENERATE[openssl-pkcs8.pod]=openssl-pkcs8.pod.in +DEPEND[openssl-pkcs12.pod]=../perlvars.pm +GENERATE[openssl-pkcs12.pod]=openssl-pkcs12.pod.in +DEPEND[openssl-pkeyutl.pod]=../perlvars.pm +GENERATE[openssl-pkeyutl.pod]=openssl-pkeyutl.pod.in +DEPEND[openssl-rand.pod]=../perlvars.pm +GENERATE[openssl-rand.pod]=openssl-rand.pod.in +DEPEND[openssl-req.pod]=../perlvars.pm +GENERATE[openssl-req.pod]=openssl-req.pod.in +DEPEND[openssl-rsautl.pod]=../perlvars.pm +GENERATE[openssl-rsautl.pod]=openssl-rsautl.pod.in +DEPEND[openssl-s_client.pod]=../perlvars.pm +GENERATE[openssl-s_client.pod]=openssl-s_client.pod.in +DEPEND[openssl-s_server.pod]=../perlvars.pm +GENERATE[openssl-s_server.pod]=openssl-s_server.pod.in +DEPEND[openssl-s_time.pod]=../perlvars.pm +GENERATE[openssl-s_time.pod]=openssl-s_time.pod.in +DEPEND[openssl-smime.pod]=../perlvars.pm +GENERATE[openssl-smime.pod]=openssl-smime.pod.in +DEPEND[openssl-speed.pod]=../perlvars.pm +GENERATE[openssl-speed.pod]=openssl-speed.pod.in +DEPEND[openssl-srp.pod]=../perlvars.pm +GENERATE[openssl-srp.pod]=openssl-srp.pod.in +DEPEND[openssl-ts.pod]=../perlvars.pm +GENERATE[openssl-ts.pod]=openssl-ts.pod.in +DEPEND[openssl-verify.pod]=../perlvars.pm +GENERATE[openssl-verify.pod]=openssl-verify.pod.in +DEPEND[openssl-x509.pod]=../perlvars.pm +GENERATE[openssl-x509.pod]=openssl-x509.pod.in diff --git a/doc/man1/openssl-ca.pod b/doc/man1/openssl-ca.pod.in similarity index 99% rename from doc/man1/openssl-ca.pod rename to doc/man1/openssl-ca.pod.in index e3d6c7b17c..81d1186d23 100644 --- a/doc/man1/openssl-ca.pod +++ b/doc/man1/openssl-ca.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-ca - sample minimal CA application @@ -54,10 +59,9 @@ B B [B<-create_serial>] [B<-rand_serial>] [B<-multivalue-rdn>] -[B<-rand> I] -[B<-writerand> I] [B<-sm2-id> I] [B<-sm2-hex-id> I] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine sm2-id sm2-hex-id @@ -294,10 +298,6 @@ C If B<-multi-rdn> is not used then the UID value is C<123456+CN=John Doe>. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-sm2-id> I Specify the ID string to use when verifying an SM2 certificate. The ID string is @@ -308,6 +308,8 @@ required by the SM2 signature algorithm for signing and verification. Specify a binary ID string to use when signing or verifying using an SM2 certificate. The argument for this option is string of hexadecimal digits. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 CRL OPTIONS diff --git a/doc/man1/openssl-cms.pod b/doc/man1/openssl-cms.pod.in similarity index 98% rename from doc/man1/openssl-cms.pod rename to doc/man1/openssl-cms.pod.in index ff601cc548..3d8bcd792e 100644 --- a/doc/man1/openssl-cms.pod +++ b/doc/man1/openssl-cms.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-cms - CMS utility @@ -38,10 +43,6 @@ B B [B<-text>] [B<-noout>] [B<-print>] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-attime> I] [B<-check_ss_sig>] [B<-crl_check>] @@ -97,11 +98,11 @@ B B [B<-inkey> I] [B<-keyopt> I:I] [B<-passin> I] -[B<-rand> I] -[B<-writerand> I] [B<-to> I] [B<-from> I] [B<-subject> I] +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} [I ...] =for openssl ifdef des-wrap engine @@ -286,10 +287,6 @@ structure is being checked. For the B<-cmsout> operation print out all fields of the CMS structure. This is mainly useful for testing purposes. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-md> I Digest algorithm to use when signing or resigning. If not present then the @@ -462,15 +459,6 @@ or to modify default parameters for ECDH. The private key password source. For more information about the format of B see L. -=item B<-rand> I, B<-writerand> I - -See L for more information. - -=item I ... - -One or more certificates of message recipients: used when encrypting -a message. - =item B<-to>, B<-from>, B<-subject> The relevant mail headers. These are included outside the signed @@ -489,6 +477,15 @@ B<-verify_ip>, B<-verify_name>, B<-x509_strict> Set various certificate chain validation options. See the L manual page for details. +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + +=item I ... + +One or more certificates of message recipients: used when encrypting +a message. + =back =head1 NOTES diff --git a/doc/man1/openssl-crl.pod b/doc/man1/openssl-crl.pod.in similarity index 91% rename from doc/man1/openssl-crl.pod rename to doc/man1/openssl-crl.pod.in index 911af026bb..7441de446c 100644 --- a/doc/man1/openssl-crl.pod +++ b/doc/man1/openssl-crl.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-crl - CRL utility @@ -20,10 +25,7 @@ B B [B<-issuer>] [B<-lastupdate>] [B<-nextupdate>] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] +{- $OpenSSL::safe::opt_trust_synopsis -} =for openssl ifdef hash_old @@ -94,9 +96,7 @@ Output the lastUpdate field. Output the nextUpdate field. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. +{- $OpenSSL::safe::opt_trust_item -} =back diff --git a/doc/man1/openssl-dgst.pod b/doc/man1/openssl-dgst.pod.in similarity index 97% rename from doc/man1/openssl-dgst.pod rename to doc/man1/openssl-dgst.pod.in index 7ea47480bc..75187ffe2c 100644 --- a/doc/man1/openssl-dgst.pod +++ b/doc/man1/openssl-dgst.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-dgst - perform digest operations @@ -25,10 +30,9 @@ B B|I [B<-sigopt> I:I] [B<-hmac> I] [B<-fips-fingerprint>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] [B<-engine_impl>] +{- $OpenSSL::safe::opt_r_synopsis -} [I ...] =head1 DESCRIPTION @@ -164,10 +168,6 @@ for example exactly 32 chars for gost-mac. The L command should be preferred to using this command line option. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-fips-fingerprint> Compute HMAC using a specific key for certain OpenSSL-FIPS operations. @@ -184,6 +184,8 @@ specified. When used with the B<-engine> option, it specifies to also use engine I for digest operations. +{- $OpenSSL::safe::opt_r_item -} + =item I ... File or files to digest. If no files are specified then standard input is diff --git a/doc/man1/openssl-dhparam.pod b/doc/man1/openssl-dhparam.pod.in similarity index 96% rename from doc/man1/openssl-dhparam.pod rename to doc/man1/openssl-dhparam.pod.in index cbd52b00fb..9ae5006b1e 100644 --- a/doc/man1/openssl-dhparam.pod +++ b/doc/man1/openssl-dhparam.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-dhparam - DH parameter manipulation and generation @@ -20,9 +25,8 @@ B [B<-2>] [B<-3>] [B<-5>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] +{- $OpenSSL::safe::opt_r_synopsis -} [I] =for openssl ifdef dsaparam engine @@ -80,10 +84,6 @@ input file is ignored and parameters are generated instead. If not present but I is present, parameters are generated with the default generator 2. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item I This option specifies that a parameter set should be generated of size @@ -113,6 +113,8 @@ 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_r_item -} + =back =head1 WARNINGS diff --git a/doc/man1/openssl-dsaparam.pod b/doc/man1/openssl-dsaparam.pod.in similarity index 94% rename from doc/man1/openssl-dsaparam.pod rename to doc/man1/openssl-dsaparam.pod.in index 0c85ca0d1d..d23f48fd5b 100644 --- a/doc/man1/openssl-dsaparam.pod +++ b/doc/man1/openssl-dsaparam.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-dsaparam - DSA parameter manipulation and generation @@ -15,11 +20,10 @@ B [B<-noout>] [B<-text>] [B<-C>] -[B<-rand> I] -[B<-writerand> I] [B<-genkey>] [B<-engine> I] [B<-verbose>] +{- $OpenSSL::safe::opt_r_synopsis -} [I] =head1 DESCRIPTION @@ -75,10 +79,6 @@ be loaded by calling the get_dsaXXX() function. This option will generate a DSA either using the specified or generated parameters. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause this command @@ -90,6 +90,8 @@ for all available algorithms. Print extra details about the operations being performed. +{- $OpenSSL::safe::opt_r_item -} + =item I This option specifies that a parameter set should be generated of size diff --git a/doc/man1/openssl-ecparam.pod b/doc/man1/openssl-ecparam.pod.in similarity index 96% rename from doc/man1/openssl-ecparam.pod rename to doc/man1/openssl-ecparam.pod.in index c761980953..1e262a4a81 100644 --- a/doc/man1/openssl-ecparam.pod +++ b/doc/man1/openssl-ecparam.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-ecparam - EC parameter manipulation and generation @@ -22,10 +27,9 @@ B [B<-conv_form> I] [B<-param_enc> I] [B<-no_seed>] -[B<-rand> I] -[B<-writerand> I] [B<-genkey>] [B<-engine> I] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine @@ -122,10 +126,6 @@ is included in the ECParameters structure (see RFC 3279). This option will generate an EC private key using the specified parameters. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause B @@ -133,6 +133,8 @@ 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_r_item -} + =back =head1 EXAMPLES diff --git a/doc/man1/openssl-enc.pod b/doc/man1/openssl-enc.pod.in similarity index 98% rename from doc/man1/openssl-enc.pod rename to doc/man1/openssl-enc.pod.in index ced97e743e..842eb2a183 100644 --- a/doc/man1/openssl-enc.pod +++ b/doc/man1/openssl-enc.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-enc - symmetric cipher routines @@ -36,9 +41,8 @@ B B|I [B<-nopad>] [B<-debug>] [B<-none>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef z engine @@ -190,9 +194,7 @@ or zlib-dynamic option. Use NULL cipher (no encryption or decryption of input). -=item B<-rand> I, B<-writerand> I - -See L for more information. +{- $OpenSSL::safe::opt_r_item -} =back diff --git a/doc/man1/openssl-gendsa.pod b/doc/man1/openssl-gendsa.pod.in similarity index 93% rename from doc/man1/openssl-gendsa.pod rename to doc/man1/openssl-gendsa.pod.in index 451a3c4835..d92f0dd7a8 100644 --- a/doc/man1/openssl-gendsa.pod +++ b/doc/man1/openssl-gendsa.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-gendsa - generate a DSA private key from a set of parameters @@ -21,10 +26,9 @@ B B [B<-des>] [B<-des3>] [B<-idea>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] [B<-verbose>] +{- $OpenSSL::safe::opt_r_synopsis -} [I] =for openssl ifdef engine @@ -53,10 +57,6 @@ 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<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause this command @@ -74,6 +74,8 @@ 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-genrsa.pod b/doc/man1/openssl-genrsa.pod.in similarity index 95% rename from doc/man1/openssl-genrsa.pod rename to doc/man1/openssl-genrsa.pod.in index d04c8eeb19..6239cd8bee 100644 --- a/doc/man1/openssl-genrsa.pod +++ b/doc/man1/openssl-genrsa.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-genrsa - generate an RSA private key @@ -23,11 +28,10 @@ B B [B<-des3>] [B<-idea>] [B<-f4>|B<-3>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] [B<-primes> I] [B<-verbose>] +{- $OpenSSL::safe::opt_r_synopsis -} [B] =for openssl ifdef engine @@ -65,10 +69,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<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause this command @@ -87,6 +87,8 @@ RSA key, which is defined in RFC 8017. Print extra details about the operations being performed. +{- $OpenSSL::safe::opt_r_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-ocsp.pod b/doc/man1/openssl-ocsp.pod.in similarity index 98% rename from doc/man1/openssl-ocsp.pod rename to doc/man1/openssl-ocsp.pod.in index 6fc077506f..a3358e724a 100644 --- a/doc/man1/openssl-ocsp.pod +++ b/doc/man1/openssl-ocsp.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-ocsp - Online Certificate Status Protocol utility @@ -30,10 +35,6 @@ B B [B<-multi> I] [B<-header>] [B<-path>] -[B<-CApath> I] -[B<-CAfile> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-attime> I] [B<-check_ss_sig>] [B<-crl_check>] @@ -89,6 +90,7 @@ B B [B<-nrequest> I] [B<-rcid> I] [B<-I>] +{- $OpenSSL::safe::opt_trust_synopsis -} =for openssl ifdef multi @@ -207,10 +209,6 @@ each child is willing to wait for the client's OCSP response. This option is available on POSIX systems (that support the fork() and other required unix system-calls). -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, @@ -310,6 +308,8 @@ OCSP request. Any digest supported by the OpenSSL B command can be used. The default is SHA-1. This option may be used multiple times to specify the digest used by subsequent certificate identifiers. +{- $OpenSSL::safe::opt_trust_item -} + =back =head2 OCSP Server Options diff --git a/doc/man1/openssl-passwd.pod b/doc/man1/openssl-passwd.pod.in similarity index 94% rename from doc/man1/openssl-passwd.pod rename to doc/man1/openssl-passwd.pod.in index e7502ae332..2fa8e97f13 100644 --- a/doc/man1/openssl-passwd.pod +++ b/doc/man1/openssl-passwd.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-passwd - compute password hashes @@ -20,8 +25,7 @@ B [B<-noverify>] [B<-quiet>] [B<-table>] -[B<-rand> I] -[B<-writerand> I] +{- $OpenSSL::safe::opt_r_synopsis -} {I} =for openssl ifdef crypt @@ -93,9 +97,7 @@ Don't output warnings when passwords given at the command line are truncated. In the output list, prepend the cleartext password and a TAB character to each password hash. -=item B<-rand> I, B<-writerand> I - -See L for more information. +{- $OpenSSL::safe::opt_r_item -} =back diff --git a/doc/man1/openssl-pkcs12.pod b/doc/man1/openssl-pkcs12.pod.in similarity index 96% rename from doc/man1/openssl-pkcs12.pod rename to doc/man1/openssl-pkcs12.pod.in index 5742549891..09b75111db 100644 --- a/doc/man1/openssl-pkcs12.pod +++ b/doc/man1/openssl-pkcs12.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-pkcs12 - PKCS#12 file utility @@ -36,13 +41,9 @@ B B [B<-password> I] [B<-passin> I] [B<-passout> I] -[B<-rand> I] -[B<-writerand> I] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-CSP> I] +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine @@ -263,18 +264,14 @@ to be needed to use MAC iterations counts but they are now used by default. Don't attempt to provide the MAC integrity. -=item B<-rand> I, B<-writerand> I - -See L for more information. - -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-CSP> I Write I as a Microsoft CSP name. +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + =back =head1 NOTES diff --git a/doc/man1/openssl-pkcs8.pod b/doc/man1/openssl-pkcs8.pod.in similarity index 98% rename from doc/man1/openssl-pkcs8.pod rename to doc/man1/openssl-pkcs8.pod.in index f923c986a0..c9d8b9c5a8 100644 --- a/doc/man1/openssl-pkcs8.pod +++ b/doc/man1/openssl-pkcs8.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-pkcs8 - PKCS#8 format private key conversion tool @@ -17,8 +22,6 @@ B B [B<-passout> I] [B<-iter> I] [B<-noiter>] -[B<-rand> I] -[B<-writerand> I] [B<-nocrypt>] [B<-traditional>] [B<-v2> I] @@ -29,6 +32,7 @@ B B [B<-scrypt_N> I] [B<-scrypt_r> I] [B<-scrypt_p> I

] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine scrypt scrypt_N scrypt_r scrypt_p @@ -113,10 +117,6 @@ This option does not encrypt private keys at all and should only be used when absolutely necessary. Certain software such as some versions of Java code signing software used unencrypted private keys. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-v2> I This option sets the PKCS#5 v2.0 algorithm. @@ -158,6 +158,8 @@ B<-scrypt_p> and B<-v2> options. Sets the scrypt I, I or I

parameters. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 NOTES diff --git a/doc/man1/openssl-pkeyutl.pod b/doc/man1/openssl-pkeyutl.pod.in similarity index 98% rename from doc/man1/openssl-pkeyutl.pod rename to doc/man1/openssl-pkeyutl.pod.in index 13519399fa..61cf3cb9ef 100644 --- a/doc/man1/openssl-pkeyutl.pod +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-pkeyutl - public key algorithm utility @@ -33,10 +38,9 @@ B B [B<-pkeyopt_passin> I[:I]] [B<-hexdump>] [B<-asn1parse>] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] [B<-engine_impl>] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine engine_impl @@ -179,10 +183,6 @@ 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<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause this command @@ -195,6 +195,8 @@ for all available algorithms. When used with the B<-engine> option, it specifies to also use engine I for crypto operations. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 NOTES diff --git a/doc/man1/openssl-rand.pod b/doc/man1/openssl-rand.pod.in similarity index 86% rename from doc/man1/openssl-rand.pod rename to doc/man1/openssl-rand.pod.in index c32b10242e..fe7a2467bc 100644 --- a/doc/man1/openssl-rand.pod +++ b/doc/man1/openssl-rand.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-rand - generate pseudo-random bytes @@ -9,10 +14,9 @@ openssl-rand - generate pseudo-random bytes B [B<-help>] [B<-out> I] -[B<-rand> I] -[B<-writerand> I] [B<-base64>] [B<-hex>] +{- $OpenSSL::safe::opt_r_synopsis -} I =for openssl ifdef engine @@ -34,10 +38,6 @@ Print out a usage message. Write to I instead of standard output. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-base64> Perform base64 encoding on the output. @@ -46,6 +46,8 @@ Perform base64 encoding on the output. Show the output as a hex string. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 SEE ALSO diff --git a/doc/man1/openssl-req.pod b/doc/man1/openssl-req.pod.in similarity index 99% rename from doc/man1/openssl-req.pod rename to doc/man1/openssl-req.pod.in index f976b7948e..8ca4acc111 100644 --- a/doc/man1/openssl-req.pod +++ b/doc/man1/openssl-req.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-req - PKCS#10 certificate request and certificate generating utility @@ -20,8 +25,6 @@ B B [B<-verify>] [B<-modulus>] [B<-new>] -[B<-rand> I] -[B<-writerand> I] [B<-newkey> I] [B<-nodes>] [B<-key> I] @@ -50,6 +53,7 @@ B B [B<-engine> I] [B<-sm2-id> I] [B<-sm2-hex-id> I] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine keygen_engine sm2-id sm2-hex-id @@ -132,10 +136,6 @@ in the configuration file and any requested extensions. If the B<-key> option is not used it will generate a new RSA private key using information specified in the configuration file. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-newkey> I This option creates a new certificate request and a new private @@ -334,6 +334,8 @@ string is required by the SM2 signature algorithm for signing and verification. Specify a binary ID string to use when verifying an SM2 certificate request. The argument for this option is string of hexadecimal digits. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 CONFIGURATION FILE FORMAT diff --git a/doc/man1/openssl-rsautl.pod b/doc/man1/openssl-rsautl.pod.in similarity index 97% rename from doc/man1/openssl-rsautl.pod rename to doc/man1/openssl-rsautl.pod.in index cc85cc4b21..374b87a406 100644 --- a/doc/man1/openssl-rsautl.pod +++ b/doc/man1/openssl-rsautl.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-rsautl - RSA utility @@ -18,13 +23,12 @@ B B [B<-verify>] [B<-encrypt>] [B<-decrypt>] -[B<-rand> I] -[B<-writerand> I] [B<-pkcs>] [B<-ssl>] [B<-raw>] [B<-hexdump>] [B<-asn1parse>] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine @@ -85,10 +89,6 @@ Encrypt the input data using an RSA public key. Decrypt the input data using an RSA private key. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-pkcs>, B<-oaep>, B<-ssl>, B<-raw> The padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, @@ -105,6 +105,8 @@ Hex dump the output data. Parse the ASN.1 output data, this is useful when combined with the B<-verify> option. +{- $OpenSSL::safe::opt_r_item -} + =back =head1 NOTES diff --git a/doc/man1/openssl-s_client.pod b/doc/man1/openssl-s_client.pod.in similarity index 95% rename from doc/man1/openssl-s_client.pod rename to doc/man1/openssl-s_client.pod.in index 2dc64f578f..9752407a82 100644 --- a/doc/man1/openssl-s_client.pod +++ b/doc/man1/openssl-s_client.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-s_client - SSL/TLS client program @@ -27,19 +32,9 @@ B B [B<-keyform> B|B] [B<-cert_chain> I] [B<-build_chain>] -[B<-xkey>] -[B<-xcert>] -[B<-xchain>] -[B<-xchain_build>] -[B<-xcertform> B|B] -[B<-xkeyform> B|B] [B<-pass> I] -[B<-CApath> I] -[B<-CAfile> I] [B<-chainCApath> I] [B<-chainCAfile> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-requestCAfile> I] [B<-dane_tlsa_domain> I] [B<-dane_tlsa_rrdata> I] @@ -126,8 +121,6 @@ B B [B<-no_ticket>] [B<-sess_out> I] [B<-sess_in> I] -[B<-rand> I] -[B<-writerand> I] [B<-serverinfo> I] [B<-status>] [B<-alpn> I] @@ -138,6 +131,9 @@ B B [B<-keylogfile> I] [B<-early_data> I] [B<-enable_pha>] +{- $OpenSSL::safe::opt_x_synopsis -} +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} [I:I] =for openssl ifdef engine ssl_client_engine ct noct ctlogfile @@ -176,7 +172,7 @@ select the host and port using the optional target positional argument instead. If neither this nor the target positional argument are specified then an attempt is made to connect to the local host on port 4433. -=item B<-bind> I] +=item B<-bind> I This specifies the host address and or port to bind as the source for the connection. For Unix-domain sockets the port is ignored and the host is @@ -218,14 +214,14 @@ Use IPv6 only. =item B<-servername> I Set the TLS SNI (Server Name Indication) extension in the ClientHello message to -the given value. -If B<-servername> is not provided, the TLS SNI extension will be populated with -the name given to B<-connect> if it follows a DNS name format. If B<-connect> is +the given value. +If B<-servername> is not provided, the TLS SNI extension will be populated with +the name given to B<-connect> if it follows a DNS name format. If B<-connect> is not provided either, the SNI is set to "localhost". This is the default since OpenSSL 1.1.1. -Even though SNI should normally be a DNS name and not an IP address, if -B<-servername> is provided then that name will be sent, regardless of whether +Even though SNI should normally be a DNS name and not an IP address, if +B<-servername> is provided then that name will be sent, regardless of whether it is a DNS name or not. This option cannot be used in conjunction with B<-noservername>. @@ -271,24 +267,6 @@ B<-cert> option. Specify whether the application should build the certificate chain to be provided to the server. -=item B<-xkey> I, B<-xcert> I, B<-xchain> - -Specify an extra certificate, private key and certificate chain. These behave -in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When -specified, the callback returning the first valid chain will be in use by the -client. - -=item B<-xchain_build> - -Specify whether the application should build the certificate chain to be -provided to the server for the extra certificates provided via B<-xkey> I, -B<-xcert> I, B<-xchain> options. - -=item B<-xcertform> B|B, B<-xkeyform> B|B - -Extra certificate and private key format respectively. -See L for details. - =item B<-pass> I the private key password source. For more information about the format of I @@ -314,10 +292,6 @@ I

, B<-no-CApath> - -See L for more information. - =item B<-chainCApath> I The directory to use for building the chain provided to the server. This @@ -667,10 +641,6 @@ 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<-rand> I, B<-writerand> I - -See L for more information. - =item B<-serverinfo> I A list of comma-separated TLS Extension Types (numbers between 0 and @@ -735,6 +705,12 @@ be provided as a single positional argument after all options. If neither this nor B<-connect> are provided, falls back to attempting to connect to I on port I<4433>. +{- $OpenSSL::safe::opt_x_item -} + +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + =back =head1 CONNECTED COMMANDS diff --git a/doc/man1/openssl-s_server.pod b/doc/man1/openssl-s_server.pod.in similarity index 95% rename from doc/man1/openssl-s_server.pod rename to doc/man1/openssl-s_server.pod.in index be70cfcff5..638516695f 100644 --- a/doc/man1/openssl-s_server.pod +++ b/doc/man1/openssl-s_server.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-s_server - SSL/TLS server program @@ -36,10 +41,6 @@ B B [B<-msg>] [B<-msgfile> I] [B<-state>] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-nocert>] [B<-quiet>] [B<-no_resume_ephemeral>] @@ -52,8 +53,6 @@ B B [B<-tlsextdebug>] [B<-HTTP>] [B<-id_prefix> I] -[B<-rand> I] -[B<-writerand> I] [B<-keymatexport> I] [B<-keymatexportlen> I<+int>] [B<-CRL> I] @@ -146,13 +145,6 @@ B B [B<-no_alt_chains>] [B<-no_check_time>] [B<-allow_proxy_certs>] -[B<-xkey>] -[B<-xcert>] -[B<-xchain>] -[B<-xchain_build>] -[B<-CRLform> B|B] -[B<-xcertform> B|B] -[B<-xkeyform> B|B] [B<-nbio>] [B<-psk_identity> I] [B<-psk_hint> I] @@ -184,6 +176,9 @@ B B [B<-anti_replay>] [B<-no_anti_replay>] [B<-http_server_binmode>] +{- $OpenSSL::safe::opt_x_synopsis -} +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef unix 4 6 unlink no_dhe nextprotoneg use_srtp engine @@ -300,7 +295,7 @@ See L for details. The private key to use. If not specified then the certificate file will be used. -=item B<-keyform> B|B] +=item B<-keyform> B|B The key format; the default is B. See L for details. @@ -339,25 +334,6 @@ The passphrase for the additional private key. For more information about the format of I, see L. -=item B<-xkey> I, B<-xcert> I, B<-xchain> - -Specify an extra certificate, private key and certificate chain. These behave -in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When -specified, the callback returning the first valid chain will be in use by -the server. - -=item B<-xchain_build> - -Specify whether the application should build the certificate chain to be -provided to the client for the extra certificates provided via B<-xkey> I, -B<-xcert> I, B<-xchain> options. - -=item B<-xcertform> B|B, B<-xkeyform> B|B - -The format for the extra certificate and private key, respectively; -the default format is B. -see L. - =item B<-nbio_test> Tests non blocking I/O. @@ -382,10 +358,6 @@ File to send output of B<-msg> or B<-trace> to, default standard output. Prints the SSL session states. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-chainCApath> I The directory to use for building the chain provided to the client. This @@ -441,10 +413,6 @@ for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple servers, when each of which might be generating a unique range of session IDs (eg. with a certain prefix). -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-verify_return_error> Verification errors normally just print a message but allow the @@ -745,6 +713,12 @@ data that was sent will be rejected. When acting as web-server (using option B<-WWW> or B<-HTTP>) open files requested by the client in binary mode. +{- $OpenSSL::safe::opt_x_item -} + +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + =back =head1 CONNECTED COMMANDS diff --git a/doc/man1/openssl-s_time.pod b/doc/man1/openssl-s_time.pod.in similarity index 96% rename from doc/man1/openssl-s_time.pod rename to doc/man1/openssl-s_time.pod.in index f5126dae54..737424da87 100644 --- a/doc/man1/openssl-s_time.pod +++ b/doc/man1/openssl-s_time.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-s_time - SSL/TLS performance timing program @@ -12,10 +17,6 @@ B B [B<-www> I] [B<-cert> I] [B<-key> I] -[B<-CApath> I] -[B<-cafile> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-reuse>] [B<-new>] [B<-verify> I] @@ -29,6 +30,7 @@ B B [B<-bugs>] [B<-cipher> I] [B<-ciphersuites> I] +{- $OpenSSL::safe::opt_trust_synopsis -} =for openssl ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 @@ -91,10 +93,6 @@ The directory to use for server certificate verification. This directory must be in "hash format", see L for more information. These are also used when building the client certificate chain. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-new> Performs the timing test using a new session ID for each connection. @@ -145,6 +143,8 @@ and optionally transfer payload data from a server. Server and client performance and the link speed determine how many connections it can establish. +{- $OpenSSL::safe::opt_trust_item -} + =back =head1 NOTES diff --git a/doc/man1/openssl-smime.pod b/doc/man1/openssl-smime.pod.in similarity index 97% rename from doc/man1/openssl-smime.pod rename to doc/man1/openssl-smime.pod.in index 935a89b678..4e07af3860 100644 --- a/doc/man1/openssl-smime.pod +++ b/doc/man1/openssl-smime.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-smime - S/MIME utility @@ -18,10 +23,6 @@ B B [B<-crlfeol>] [B<-I>] [B<-in> I] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-attime> I] [B<-check_ss_sig>] [B<-crl_check>] @@ -66,9 +67,9 @@ B B [B<-indef>] [B<-noindef>] [B<-stream>] -[B<-rand> I] -[B<-writerand> I] [B<-md> I] +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} I ... =for openssl ifdef engine @@ -179,10 +180,6 @@ message if encrypting or signing. If decrypting or verifying it strips off text headers: if the decrypted or verified message is not of MIME type text/plain then an error occurs. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-md> I Digest algorithm to use when signing or resigning. If not present then the @@ -283,10 +280,6 @@ specified, the argument is given to the engine as a key identifier. The private key password source. For more information about the format of I see L. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-to>, B<-from>, B<-subject> The relevant mail headers. These are included outside the signed @@ -305,6 +298,10 @@ B<-verify_ip>, B<-verify_name>, B<-x509_strict> Set various options of certificate chain verification. See L manual page for details. +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + =item I ... One or more certificates of message recipients, used when encrypting diff --git a/doc/man1/openssl-speed.pod b/doc/man1/openssl-speed.pod.in similarity index 94% rename from doc/man1/openssl-speed.pod rename to doc/man1/openssl-speed.pod.in index e818bf6666..657a4156c6 100644 --- a/doc/man1/openssl-speed.pod +++ b/doc/man1/openssl-speed.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-speed - test library performance @@ -14,11 +19,10 @@ B [B<-hmac> I] [B<-cmac> I] [B<-decrypt>] -[B<-rand> I] -[B<-writerand> I] [B<-primes> I] [B<-seconds> I] [B<-bytes> I] +{- $OpenSSL::safe::opt_r_synopsis -} [I ...] =for openssl ifdef cmac multi async_jobs engine @@ -71,10 +75,6 @@ C. Time the decryption instead of encryption. Affects only the EVP testing. -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-primes> I Generate a I-prime RSA key and use it to run the benchmarks. This option @@ -88,6 +88,8 @@ Run benchmarks for I seconds. Run benchmarks on I-byte buffers. Affects ciphers, digests and the CSPRNG. +{- $OpenSSL::safe::opt_r_item -} + =item I ... If any I is given, then those algorithms are tested, otherwise a diff --git a/doc/man1/openssl-srp.pod b/doc/man1/openssl-srp.pod.in similarity index 92% rename from doc/man1/openssl-srp.pod rename to doc/man1/openssl-srp.pod.in index 65443c25cf..24990c9148 100644 --- a/doc/man1/openssl-srp.pod +++ b/doc/man1/openssl-srp.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-srp - maintain SRP password file @@ -20,8 +25,7 @@ B [B<-userinfo> I] [B<-passin> I] [B<-passout> I] -[B<-rand> I] -[B<-writerand> I] +{- $OpenSSL::safe::opt_r_synopsis -} [I ...] =for openssl ifdef engine @@ -71,9 +75,7 @@ The password source for the input and output file. For more information about the format of B see L. -=item B<-rand> I, B<-writerand> I - -See L for more information. +{- $OpenSSL::safe::opt_r_synopsis -} =back diff --git a/doc/man1/openssl-ts.pod b/doc/man1/openssl-ts.pod.in similarity index 99% rename from doc/man1/openssl-ts.pod rename to doc/man1/openssl-ts.pod.in index fc46421745..d9354b2ab7 100644 --- a/doc/man1/openssl-ts.pod +++ b/doc/man1/openssl-ts.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-ts - Time Stamping Authority tool (client/server) @@ -8,8 +13,6 @@ openssl-ts - Time Stamping Authority tool (client/server) B B B<-query> -[B<-rand> I] -[B<-writerand> I] [B<-config> I] [B<-data> I] [B<-digest> I] @@ -20,6 +23,7 @@ B<-query> [B<-in> I] [B<-out> I] [B<-text>] +{- $OpenSSL::safe::opt_r_synopsis -} B B B<-reply> @@ -134,10 +138,6 @@ request with the following options: =over 4 -=item B<-rand> I, B<-writerand> I - -See L for more information. - =item B<-config> I The configuration file to use. @@ -200,6 +200,8 @@ is stdout. (Optional) If this option is specified the output is human-readable text format instead of DER. (Optional) +{- $OpenSSL::safe::opt_r_item -} + =back =head2 Timestamp Response generation diff --git a/doc/man1/openssl-verify.pod b/doc/man1/openssl-verify.pod.in similarity index 99% rename from doc/man1/openssl-verify.pod rename to doc/man1/openssl-verify.pod.in index abaa0755f2..72ef98cc85 100644 --- a/doc/man1/openssl-verify.pod +++ b/doc/man1/openssl-verify.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-verify - Utility to verify certificates @@ -8,10 +13,6 @@ openssl-verify - Utility to verify certificates B B [B<-help>] -[B<-CAfile> I] -[B<-CApath> I] -[B<-no-CAfile>] -[B<-no-CApath>] [B<-allow_proxy_certs>] [B<-attime> I] [B<-check_ss_sig>] @@ -51,6 +52,7 @@ B B [B<-show_chain>] [B<-sm2-id> I] [B<-sm2-hex-id> I] +{- $OpenSSL::safe::opt_trust_synopsis -} [B<-->] [I ...] @@ -68,10 +70,6 @@ This command verifies certificate chains. Print out a usage message. -=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath> - -See L for more information. - =item B<-allow_proxy_certs> Allow the verification of proxy certificates. @@ -318,6 +316,8 @@ Indicates the last option. All arguments following this are assumed to be certificate files. This is useful if the first certificate filename begins with a B<-->. +{- $OpenSSL::safe::opt_trust_item -} + =item I ... One or more certificates to verify. If no certificates are given, diff --git a/doc/man1/openssl-x509.pod b/doc/man1/openssl-x509.pod.in similarity index 99% rename from doc/man1/openssl-x509.pod rename to doc/man1/openssl-x509.pod.in index d843ff3975..c99a5b23f0 100644 --- a/doc/man1/openssl-x509.pod +++ b/doc/man1/openssl-x509.pod.in @@ -1,5 +1,10 @@ =pod +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + =head1 NAME openssl-x509 - Certificate display and signing utility @@ -63,10 +68,9 @@ B B [B<-extfile> I] [B<-extensions> I
] [B<-sigopt> I:I] -[B<-rand> I] -[B<-writerand> I] [B<-engine> I] [B<-preserve_dates>] +{- $OpenSSL::safe::opt_r_synopsis -} =for openssl ifdef engine subject_hash_old issuer_hash_old @@ -117,10 +121,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<-rand> I, B<-writerand> I - -See L for more information. - =item B<-engine> I Specifying an engine (by its unique I string) will cause this command @@ -134,6 +134,8 @@ When signing a certificate, preserve the "notBefore" and "notAfter" dates instead of adjusting them to current time and duration. Cannot be used with the B<-days> option. +{- $OpenSSL::safe::opt_r_synopsis -} + =back =head2 Display Options diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index 2de4fceeb3..3198f90e22 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -613,7 +613,7 @@ The format of the input or output streams. Format of a private key input source. -=item B<-CRLform> I +=item B<-CRLform> I Format of a CRL input source. @@ -732,6 +732,40 @@ This file can be used in a subsequent command invocation. =back +=head2 Extended Verification Options + +Sometimes there may be more than one certificate chain leading to an +end-entity certificate. +This usually happens when a root or intermediate CA signs a certificate +for another a CA in other organization. +Another reason is when a CA might have intermediates that use two different +signature formats, such as a SHA-1 and a SHA-256 digest. + +The following options can be used to provide data that will allow the +OpenSSL command to generate an alternative chain. + +=over 4 + +=item B<-xchain_build> + +Specify whether the application should build the certificate chain to be +provided to the server for the extra certificates via the B<-xkey>, +B<-xcert>, and B<-xchain> options. + +=item B<-xkey> I, B<-xcert> I, B<-xchain> + +Specify an extra certificate, private key and certificate chain. These behave +in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When +specified, the callback returning the first valid chain will be in use by the +client. + +=item B<-xcertform> B|B, B<-xkeyform> B|B + +The input format for the extra certifcate and key, respectively. +See L for details. + +=back + =head1 ENVIRONMENT =over 4 diff --git a/doc/perlvars.pm b/doc/perlvars.pm new file mode 100644 index 0000000000..ca62ca5ce9 --- /dev/null +++ b/doc/perlvars.pm @@ -0,0 +1,129 @@ +#! /usr/bin/env perl +# Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +# +# Licensed under the Apache License 2.0 (the "License"). You may not use +# this file except in compliance with the License. You can obtain a copy +# in the file LICENSE in the source distribution or at + +# Set some Perl variables for use by util/dofile.pl when processing +# POD files (mainly man1). + +# Verify options +$OpenSSL::safe::opt_v_synopsis = "" +. "[B<-attime> I]\n" +. "[B<-check_ss_sig>]\n" +. "[B<-crl_check>]\n" +. "[B<-crl_check_all>]\n" +. "[B<-explicit_policy>]\n" +. "[B<-extended_crl>]\n" +. "[B<-ignore_critical>]\n" +. "[B<-inhibit_any>]\n" +. "[B<-inhibit_map>]\n" +. "[B<-partial_chain>]\n" +. "[B<-policy> I]\n" +. "[B<-policy_check>]\n" +. "[B<-policy_print>]\n" +. "[B<-purpose> I]\n" +. "[B<-suiteB_128>]\n" +. "[B<-suiteB_128_only>]\n" +. "[B<-suiteB_192>]\n" +. "[B<-trusted_first>]\n" +. "[B<-no_alt_chains>]\n" +. "[B<-use_deltas>]\n" +. "[B<-auth_level> I]\n" +. "[B<-verify_depth> I]\n" +. "[B<-verify_email> I]\n" +. "[B<-verify_hostname> I]\n" +. "[B<-verify_ip> I]\n" +. "[B<-verify_name> I]\n" +. "[B<-x509_strict>]\n" +. "[B<-certfile> I]"; +$OpenSSL::safe::opt_v_item = "" +. "=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,\n" +. "B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,\n" +. "B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,\n" +. "B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,\n" +. "B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,\n" +. "B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,\n" +. "B<-verify_ip>, B<-verify_name>, B<-x509_strict>\n" +. "\n" +. "Set various options of certificate chain verification.\n" +. "See L for details."; + + +# Extended validation options. +$OpenSSL::safe::opt_x_synopsis = "" +. "[B<-xkey>] I\n" +. "[B<-xcert> I]\n" +. "[B<-xchain>] I\n" +. "[B<-xchain_build>] I\n" +. "[B<-xcertform> B|B]>\n" +. "[B<-xkeyform> B|B]>"; +$OpenSSL::safe::opt_x_item = "" +. "=item B I, B<-xcert> I, B<-xchain> I,\n" +. "B<-xchain_build> I, B<-xcertform> B|B,\n" +. "B<-xkeyform> B|B>\n" +. "\n" +. "Set extended certificate verification options.\n" +. "See L for details."; + + +# Random State Options +$OpenSSL::safe::opt_r_synopsis = "" +. "[B<-rand> I]\n" +. "[B<-writerand> I]"; +$OpenSSL::safe::opt_r_item = "" +. "=item B<-rand> I, B<-writerand> I\n" +. "\n" +. "See L for details."; + +# Trusted certs options +$OpenSSL::safe::opt_trust_synopsis = "" +. "[B<-CAfile> I]\n" +. "[B<-no-CAfile>]\n" +. "[B<-CApath> I]\n" +. "[B<-no-CApath>]"; +$OpenSSL::safe::opt_trust_item = "" +. "=item B<-CAfile> I, B<-no-CAfile>, B<-CApath> I, B<-no-CApath>\n" +. "\n" +. "See L for details."; + +# SSL connection options. +# TODO(3.0) Not currently used. The refactoring needs to be done, and +# the options will probably be re-ordered. +$OpenSSL::safe::opt_s_synopsis = "" +. "[B<-bugs>]\n" +. "[B<-no_comp>]\n" +. "[B<-no_ticket>]\n" +. "[B<-serverpref>]\n" +. "[B<-legacy_renegotiation>]\n" +. "[B<-no_renegotiation>]\n" +. "[B<-legacy_server_connect>]\n" +. "[B<-no_resumption_on_reneg>]\n" +. "[B<-no_legacy_server_connect>]\n" +. "[B<-allow_no_dhe_kex>]\n" +. "[B<-prioritize_chacha>]\n" +. "[B<-strict>]\n" +. "[B<-sigalgs> I]\n" +. "[B<-client_sigalgs> I]\n" +. "[B<-groups> I]\n" +. "[B<-curves> I]\n" +. "[B<-named_curve> I]\n" +. "[B<-cipher> I]\n" +. "[B<-ciphersuites> I<1.3ciphers>]\n" +. "[B<-min_protocol> I]\n" +. "[B<-max_protocol> I]\n" +. "[B<-record_padding> I]\n" +. "[B<-debug_broken_protocol>]\n" +. "[B<-no_middlebox>]"; +$OpenSSL::safe::opt_s_item = "" +. "=item B<-bugs>, B<-no_comp>, B<-no_ticket>, B<-serverpref>," +. "B<-legacy_renegotiation>, B<-no_renegotiation>, B<-legacy_server_connect>,\n" +. "B<-no_resumption_on_reneg>, B<-no_legacy_server_connect>,\n" +. "B<-allow_no_dhe_kex>, B<-prioritize_chacha>, B<-strict>, B<-sigalgs>\n" +. "I, B<-client_sigalgs> I, B<-groups> I, B<-curves>\n" +. "I, B<-named_curve> I, B<-cipher> I, B<-ciphersuites>\n" +. "I<1.3ciphers>, B<-min_protocol> I, B<-max_protocol> I,\n" +. "B<-record_padding> I, B<-debug_broken_protocol>, B<-no_middlebox>\n" +. "\n" +. "See L for details."; diff --git a/util/dofile.pl b/util/dofile.pl index 9fa8684549..a82b987eba 100644 --- a/util/dofile.pl +++ b/util/dofile.pl @@ -20,30 +20,28 @@ use OpenSSL::fallback "$FindBin::Bin/../external/perl/MODULES.txt"; use Getopt::Std; use OpenSSL::Template; -# We actually expect to get the following hash tables from configdata: -# -# %config -# %target -# %withargs -# %unified_info -# -# We just do a minimal test to see that we got what we expected. -# $config{target} must exist as an absolute minimum. +# We expect to get a lot of information from configdata, so check that +# it was part of our commandline. die "You must run this script with -Mconfigdata\n" if !exists($config{target}); # Check options ###################################################### -my %opts = (); - # -o ORIGINATOR # declares ORIGINATOR as the originating script. -getopt('o', \%opts); +# -i .ext Like Perl's edit-in-place -i flag +my %opts = (); +getopt('oi', \%opts); -my @autowarntext = ("WARNING: do not edit!", - "Generated" - . (defined($opts{o}) ? " by ".$opts{o} : "") - . (scalar(@ARGV) > 0 ? " from ".join(", ",@ARGV) : "")); +my @autowarntext = ( + "WARNING: do not edit!", + "Generated" + . (defined($opts{o}) ? " by $opts{o}" : "") + . (scalar(@ARGV) > 0 ? " from " .join(", ", @ARGV) : "") +); + +die "Must have input files" + if defined($opts{i}) and scalar(@ARGV) == 0; # Template setup ##################################################### @@ -52,6 +50,15 @@ my @template_settings = ? map { { TYPE => 'FILE', SOURCE => $_, FILENAME => $_ } } @ARGV : ( { TYPE => 'FILEHANDLE', SOURCE => \*STDIN, FILENAME => '' } ); +# Error callback; print message, set status, return "stop processing" +my $failed = 0; +sub errorcallback { + my %args = @_; + print STDERR $args{error}; + $failed++; + return undef; +} + # Engage! ############################################################ my $prepend = <<"_____"; @@ -65,17 +72,35 @@ _____ foreach (@template_settings) { my $template = OpenSSL::Template->new(%$_); - $template->fill_in(%$_, - OUTPUT => \*STDOUT, + die "Couldn't create template: $Text::Template::ERROR" + if !defined($template); + + my $result = $template->fill_in(%$_, HASH => { config => \%config, target => \%target, disabled => \%disabled, withargs => \%withargs, unified_info => \%unified_info, autowarntext => \@autowarntext }, + BROKEN => \&errorcallback, PREPEND => $prepend, # To ensure that global variables and functions # defined in one template stick around for the # next, making them combinable PACKAGE => 'OpenSSL::safe'); + exit 1 if $failed; + + if (defined($opts{i})) { + my $in = $_->{FILENAME}; + my $out = $in; + $out =~ s/$opts{i}$//; + die "Cannot replace file in-place $in" + if $in eq $out; + open OFH, ">$out" + or die "Can't open $out, $!"; + print OFH $result; + close OFH; + } else { + print $result; + } } -- 2.34.1