Browse Source

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 <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10159)
master
Rich Salz 3 years ago
committed by Tomas Mraz
parent
commit
9fcb9702fb
34 changed files with 571 additions and 292 deletions
  1. +29
    -0
      .gitignore
  2. +4
    -4
      .travis.yml
  3. +2
    -1
      build.info
  4. +84
    -0
      doc/man1/build.info
  5. +8
    -6
      doc/man1/openssl-ca.pod.in
  6. +16
    -19
      doc/man1/openssl-cms.pod.in
  7. +7
    -7
      doc/man1/openssl-crl.pod.in
  8. +8
    -6
      doc/man1/openssl-dgst.pod.in
  9. +8
    -6
      doc/man1/openssl-dhparam.pod.in
  10. +8
    -6
      doc/man1/openssl-dsaparam.pod.in
  11. +8
    -6
      doc/man1/openssl-ecparam.pod.in
  12. +7
    -5
      doc/man1/openssl-enc.pod.in
  13. +8
    -6
      doc/man1/openssl-gendsa.pod.in
  14. +8
    -6
      doc/man1/openssl-genrsa.pod.in
  15. +8
    -8
      doc/man1/openssl-ocsp.pod.in
  16. +7
    -5
      doc/man1/openssl-passwd.pod.in
  17. +11
    -14
      doc/man1/openssl-pkcs12.pod.in
  18. +8
    -6
      doc/man1/openssl-pkcs8.pod.in
  19. +8
    -6
      doc/man1/openssl-pkeyutl.pod.in
  20. +8
    -6
      doc/man1/openssl-rand.pod.in
  21. +8
    -6
      doc/man1/openssl-req.pod.in
  22. +8
    -6
      doc/man1/openssl-rsautl.pod.in
  23. +20
    -44
      doc/man1/openssl-s_client.pod.in
  24. +15
    -41
      doc/man1/openssl-s_server.pod.in
  25. +8
    -8
      doc/man1/openssl-s_time.pod.in
  26. +11
    -14
      doc/man1/openssl-smime.pod.in
  27. +8
    -6
      doc/man1/openssl-speed.pod.in
  28. +7
    -5
      doc/man1/openssl-srp.pod.in
  29. +8
    -6
      doc/man1/openssl-ts.pod.in
  30. +8
    -8
      doc/man1/openssl-verify.pod.in
  31. +8
    -6
      doc/man1/openssl-x509.pod.in
  32. +35
    -1
      doc/man1/openssl.pod
  33. +129
    -0
      doc/perlvars.pm
  34. +43
    -18
      util/dofile.pl

+ 29
- 0
.gitignore View File

@ -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


+ 4
- 4
.travis.yml View File

@ -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;


+ 2
- 1
build.info View File

@ -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


+ 84
- 0
doc/man1/build.info View File

@ -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

doc/man1/openssl-ca.pod → doc/man1/openssl-ca.pod.in View File


doc/man1/openssl-cms.pod → doc/man1/openssl-cms.pod.in View File


doc/man1/openssl-crl.pod → doc/man1/openssl-crl.pod.in View File


doc/man1/openssl-dgst.pod → doc/man1/openssl-dgst.pod.in View File


doc/man1/openssl-dhparam.pod → doc/man1/openssl-dhparam.pod.in View File


doc/man1/openssl-dsaparam.pod → doc/man1/openssl-dsaparam.pod.in View File


doc/man1/openssl-ecparam.pod → doc/man1/openssl-ecparam.pod.in View File


doc/man1/openssl-enc.pod → doc/man1/openssl-enc.pod.in View File


doc/man1/openssl-gendsa.pod → doc/man1/openssl-gendsa.pod.in View File


doc/man1/openssl-genrsa.pod → doc/man1/openssl-genrsa.pod.in View File


doc/man1/openssl-ocsp.pod → doc/man1/openssl-ocsp.pod.in View File


doc/man1/openssl-passwd.pod → doc/man1/openssl-passwd.pod.in View File


doc/man1/openssl-pkcs12.pod → doc/man1/openssl-pkcs12.pod.in View File


doc/man1/openssl-pkcs8.pod → doc/man1/openssl-pkcs8.pod.in View File


doc/man1/openssl-pkeyutl.pod → doc/man1/openssl-pkeyutl.pod.in View File


doc/man1/openssl-rand.pod → doc/man1/openssl-rand.pod.in View File


doc/man1/openssl-req.pod → doc/man1/openssl-req.pod.in View File


doc/man1/openssl-rsautl.pod → doc/man1/openssl-rsautl.pod.in View File


doc/man1/openssl-s_client.pod → doc/man1/openssl-s_client.pod.in View File


doc/man1/openssl-s_server.pod → doc/man1/openssl-s_server.pod.in View File


doc/man1/openssl-s_time.pod → doc/man1/openssl-s_time.pod.in View File


doc/man1/openssl-smime.pod → doc/man1/openssl-smime.pod.in View File


doc/man1/openssl-speed.pod → doc/man1/openssl-speed.pod.in View File


doc/man1/openssl-srp.pod → doc/man1/openssl-srp.pod.in View File


doc/man1/openssl-ts.pod → doc/man1/openssl-ts.pod.in View File


doc/man1/openssl-verify.pod → doc/man1/openssl-verify.pod.in View File


doc/man1/openssl-x509.pod → doc/man1/openssl-x509.pod.in View File


+ 35
- 1
doc/man1/openssl.pod View File

@ -613,7 +613,7 @@ The format of the input or output streams.
Format of a private key input source.
=item B<-CRLform> I<fornat>
=item B<-CRLform> I<format>
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<infile>, B<-xcert> I<infile>, 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<DER>|B<PEM>, B<-xkeyform> B<DER>|B<PEM>
The input format for the extra certifcate and key, respectively.
See L<openssl(1)/Format Options> for details.
=back
=head1 ENVIRONMENT
=over 4


+ 129
- 0
doc/perlvars.pm View File

@ -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<timestamp>]\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<arg>]\n"
. "[B<-policy_check>]\n"
. "[B<-policy_print>]\n"
. "[B<-purpose> I<purpose>]\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<num>]\n"
. "[B<-verify_depth> I<num>]\n"
. "[B<-verify_email> I<email>]\n"
. "[B<-verify_hostname> I<hostname>]\n"
. "[B<-verify_ip> I<ip>]\n"
. "[B<-verify_name> I<name>]\n"
. "[B<-x509_strict>]\n"
. "[B<-certfile> I<file>]";
$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<openssl(1)/Verification Options> for details.";
# Extended validation options.
$OpenSSL::safe::opt_x_synopsis = ""
. "[B<-xkey>] I<infile>\n"
. "[B<-xcert> I<file>]\n"
. "[B<-xchain>] I<file>\n"
. "[B<-xchain_build>] I<file>\n"
. "[B<-xcertform> B<DER>|B<PEM>]>\n"
. "[B<-xkeyform> B<DER>|B<PEM>]>";
$OpenSSL::safe::opt_x_item = ""
. "=item B<xkey> I<infile>, B<-xcert> I<file>, B<-xchain> I<file>,\n"
. "B<-xchain_build> I<file>, B<-xcertform> B<DER>|B<PEM>,\n"
. "B<-xkeyform> B<DER>|B<PEM>>\n"
. "\n"
. "Set extended certificate verification options.\n"
. "See L<openssl(1)/Extended Verification Options> for details.";
# Random State Options
$OpenSSL::safe::opt_r_synopsis = ""
. "[B<-rand> I<files>]\n"
. "[B<-writerand> I<file>]";
$OpenSSL::safe::opt_r_item = ""
. "=item B<-rand> I<files>, B<-writerand> I<file>\n"
. "\n"
. "See L<openssl(1)/Random State Options> for details.";
# Trusted certs options
$OpenSSL::safe::opt_trust_synopsis = ""
. "[B<-CAfile> I<file>]\n"
. "[B<-no-CAfile>]\n"
. "[B<-CApath> I<dir>]\n"
. "[B<-no-CApath>]";
$OpenSSL::safe::opt_trust_item = ""
. "=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>\n"
. "\n"
. "See L<openssl(1)/Trusted Certificate Options> 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<algs>]\n"
. "[B<-client_sigalgs> I<algs>]\n"
. "[B<-groups> I<groups>]\n"
. "[B<-curves> I<curves>]\n"
. "[B<-named_curve> I<curves>]\n"
. "[B<-cipher> I<ciphers>]\n"
. "[B<-ciphersuites> I<1.3ciphers>]\n"
. "[B<-min_protocol> I<minprot>]\n"
. "[B<-max_protocol> I<maxprot>]\n"
. "[B<-record_padding> I<padding>]\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<algs>, B<-client_sigalgs> I<algs>, B<-groups> I<groups>, B<-curves>\n"
. "I<curves>, B<-named_curve> I<curves>, B<-cipher> I<ciphers>, B<-ciphersuites>\n"
. "I<1.3ciphers>, B<-min_protocol> I<minprot>, B<-max_protocol> I<maxprot>,\n"
. "B<-record_padding> I<padding>, B<-debug_broken_protocol>, B<-no_middlebox>\n"
. "\n"
. "See L<SSL_CONF_cmd(3)/SUPPORTED COMMAND LINE COMMANDS> for details.";

+ 43
- 18
util/dofile.pl View File

@ -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 => '<stdin>' } );
# 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;
}
}

Loading…
Cancel
Save