gpg and other doc

git-svn-id: svn://tug.org/texlive/trunk@41225 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 73 insertions, 88 deletions

diff --git a/Master/install-tl b/Master/install-tl
index 2bc05ef77a6..ac113456307 100755
--- a/Master/install-tl
+++ b/Master/install-tl
@@ -2433,9 +2433,9 @@ a new menu (for debugging purposes).
 
 For Windows only: configure for the current user, not for all users.
 
-=item B<--persistent-downloads>
+=item B<-persistent-downloads>
 
-=item B<--no-persistent-downloads>
+=item B<-no-persistent-downloads>
 
 For network installs, activating this option makes the installer try to
 set up a persistent connection using the C<Net::LWP> Perl module.  This
@@ -2445,13 +2445,15 @@ package, which typically yields a significant speed-up.
 
 This option is turned on by default, and the installation program will
 fall back to using C<wget> if this is not possible.  To disable usage of
-LWP and persistent connections, use C<--no-persistent-downloads>.
+LWP and persistent connections, use C<-no-persistent-downloads>.
 
-=item B<--no-verify-downloads>
+=item B<-no-verify-downloads>
 
 By default, if a GnuPG C<gpg> binary is found in PATH, downloads are
-verified against a cryptographic signature. This option disables
-such verification.
+verified against a cryptographic signature. This option disables such
+verification.  The full description is in the Crytographic Verification
+section of the C<tlmgr> documentation, e.g.,
+L<http://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>
 
 =item B<-portable>
 
diff --git a/Master/texmf-dist/scripts/texlive/NEWS b/Master/texmf-dist/scripts/texlive/NEWS
index b1dd268fa46..50221625f32 100644
--- a/Master/texmf-dist/scripts/texlive/NEWS
+++ b/Master/texmf-dist/scripts/texlive/NEWS
@@ -3,11 +3,17 @@ Karl Berry, 2010.)
 
 <p><b>tlmgr nnnnn (TeX Live 2016):</b>
 <li>support for system-level configuration files in 
-<tt>TEXMFSYSCONFIG/tlmgr/config</tt>, where a set of allowed actions can
-be defined, in addition to the usual tlmgr config file directives.
-<li>unify installer and tlmgr package installation routine.
-<li>verify package checksums during installation.
-<li>optional gpg verification.
+<tt>TEXMFSYSCONFIG/tlmgr/config</tt>, where a restricted set of allowed
+actions can be defined, in addition to the usual tlmgr config file
+directives.
+<li>the font and other gui controls can be specified as options to the
+<tt>gui</tt> action.
+<li>verify package checksums during installation; sha-512 used instead
+of md5 for checksums; new config file setting <tt>no-checksums</tt>.
+<li>gpg verification supported, with new action <tt>key</tt> and new
+options and config settings <tt>--require-verification</tt> and
+<tt>verify-downloads</tt>.
+<li>unify installer and tlmgr package installation implementations.
 
 <p><b>tlmgr revision 39198 (released 5jan16):</b>
 <li>message and doc changes.
diff --git a/Master/texmf-dist/scripts/texlive/tlmgr.pl b/Master/texmf-dist/scripts/texlive/tlmgr.pl
index 686cde7322a..9d5a6bd43fb 100755
--- a/Master/texmf-dist/scripts/texlive/tlmgr.pl
+++ b/Master/texmf-dist/scripts/texlive/tlmgr.pl
@@ -5636,6 +5636,7 @@ sub texconfig_conf_mimic {
   }
 }
 
+
 
 # Action key
 #
@@ -6500,7 +6501,7 @@ __END__
 
 =head1 NAME
 
-tlmgr - the TeX Live Manager
+tlmgr - the native TeX Live Manager
 
 =head1 SYNOPSIS
 
@@ -6585,7 +6586,6 @@ L</option> action).
 For backward compatibility and convenience, C<--location> and C<--repo>
 are accepted as aliases for this option.
 
-
 =item B<--gui> [I<action>]
 
 C<tlmgr> has a graphical interface as well as the command line
@@ -6669,7 +6669,6 @@ Instructs C<tlmgr> to only accept signed and verified remotes. In any
 other case C<tlmgr> will quit operation.
 See L<CRYPTOGRAPHIC VERIFICATION> below for details.
 
-
 =item B<--usermode>
 
 Activates user mode for this run of C<tlmgr>; see L<USER MODE> below.
@@ -6686,7 +6685,6 @@ Enables or disables cryptographic verification of downloaded database files.
 A working GnuPG (C<gpg>) binary needs to be present in the path, otherwise
 this option has no effect. See L<CRYPTOGRAPHIC VERIFICATION> below for details.
 
-
 =back
 
 The standard options for TeX Live programs are also accepted:
@@ -6698,7 +6696,6 @@ The C<--version> option shows version information about the TeX Live
 release and about the C<tlmgr> script itself.  If C<-v> is also given,
 revision number for the loaded TeX Live Perl modules are shown, too.
 
-
 =head1 ACTIONS
 
 =head2 help
@@ -6762,7 +6759,6 @@ performed are written to the terminal.
 
 =back
 
-
 =head2 candidates I<pkg>
 
 =over 4
@@ -6772,7 +6768,6 @@ performed are written to the terminal.
 Shows the available candidate repositories for package I<pkg>.
 See L</MULTIPLE REPOSITORIES> below.
 
-
 =back
 
 =head2 check [I<option>]... [files|depends|executes|runfiles|all]
@@ -6818,7 +6813,6 @@ checking the TL development repository.
 
 =back
 
-
 =head2 conf [texmf|tlmgr|updmap [--conffile I<file>] [--delete] [I<key> [I<value>]]]
 
 With only C<conf>, show general configuration information for TeX Live,
@@ -6863,7 +6857,6 @@ Warning: The general facility is here, but tinkering with settings in
 this way is very strongly discouraged.  Again, no error checking on
 either keys or values is done, so any sort of breakage is possible.
 
-
 =head2 dump-tlpdb [--local|--remote]
 
 Dump complete local or remote TLPDB to standard output, as-is.  The
@@ -6896,7 +6889,6 @@ I<location> is the file or url to the repository.
 
 Line endings may be either LF or CRLF depending on the current platform.
 
-
 =head2 generate [I<option>]... I<what>
 
 =over 4
@@ -7006,16 +6998,14 @@ succession before invoking these programs.
 
 The respective locations are as follows:
 
-  tex/generic/config/language.dat (and language-local.dat);
-  tex/generic/config/language.def (and language-local.def);
-  tex/generic/config/language.dat.lua (and language-local.dat.lua);
-
+  tex/generic/config/language.dat (and language-local.dat)
+  tex/generic/config/language.def (and language-local.def)
+  tex/generic/config/language.dat.lua (and language-local.dat.lua)
 
 =head2 gui
 
 Start the graphical user interface. See B<GUI> below.
 
-
 =head2 info [I<option>...] [collections|schemes|I<pkg>...]
 
 With no argument, lists all packages available at the package
@@ -7059,14 +7049,12 @@ locally installed packages, collections, or schemes are listed.
 
 =back
 
-
 =head2 init-usertree
 
 Sets up a texmf tree for so-called user mode management, either the
 default user tree (C<TEXMFHOME>), or one specified on the command line
 with C<--usertree>.  See L<USER MODE> below.
 
-
 =head2 install [I<option>]... I<pkg>...
 
 Install each I<pkg> given on the command line, if it is not already
@@ -7245,7 +7233,6 @@ C<postaction> action).  Finally, if C<multiuser> is set, then adaptions
 to the registry and the menus are done for all users on the system
 instead of only the current user.  All three options are on by default.
 
-
 =head2 paper
 
 =over 4
@@ -7280,7 +7267,6 @@ C<texconfig> script, which supports other configuration settings for
 some programs, notably C<dvips>.  C<tlmgr> does not support those extra
 settings.
 
-
 =head2 path [--w32mode=user|admin] [add|remove]
 
 On Unix, merely adds or removes symlinks for binaries, man pages, and
@@ -7308,7 +7294,6 @@ is given, it must be B<user> and the user path will be adjusted. If a
 user without admin rights uses the option C<--w32mode admin> a warning
 is issued that the caller does not have enough privileges.
 
-
 =head2 pinning 
 
 The C<pinning> action manages the pinning file, see L</Pinning> below.
@@ -7373,7 +7358,6 @@ written to the terminal.
 
 =back
 
-
 =cut
 
 # keep the following on *ONE* line otherwise Losedows perldoc does
@@ -7399,14 +7383,12 @@ set to 1 (the default), only new associations are added; if it is set to
 2, all associations are set to the TeX Live programs.  (See also
 C<option fileassocs>.)
 
-
 =head2 print-platform
 
 Print the TeX Live identifier for the detected platform
 (hardware/operating system) combination to standard output, and exit.
 C<--print-arch> is a synonym.
 
-
 =head2 remove [I<option>]... I<pkg>...
 
 Remove each I<pkg> specified.  Removing a collection removes all package
@@ -7442,7 +7424,6 @@ written to the terminal.
 
 =back
 
-
 =head2 repository
 
 =over 4
@@ -7479,7 +7460,6 @@ otherwise, all operations will fail!
 
 =back
 
-
 =head2 restore [--backupdir I<dir>] [--all | I<pkg> [I<rev>]]
 
 Restore a package from a previously-made backup.
@@ -7523,7 +7503,6 @@ Don't ask questions.
 
 =back
 
-
 =head2 search [I<option>...] I<what>
 
 =head3 search [I<option>...] --file I<what>
@@ -7560,7 +7539,6 @@ C<tables> (unless they also contain the word C<table> on its own).
 
 =back
 
-
 =head2 uninstall
 
 Uninstalls the entire TeX Live installation.  Options:
@@ -7573,7 +7551,6 @@ Do not ask for confirmation, remove immediately.
 
 =back
 
-
 =head2 update [I<option>]... [I<pkg>]...
 
 Updates the packages given as arguments to the latest version available
@@ -7802,7 +7779,7 @@ command-line option.
 =item C<persistent-downloads>, value 0 or 1 (default 1), same as
 command-line option.
 
-=item C<require-verification>, value 0 or 1 (default 1), same as
+=item C<require-verification>, value 0 or 1 (default 0), same as
 command-line option.
 
 =item C<verify-downloads>, value 0 or 1 (default 1), same as
@@ -7820,50 +7797,54 @@ allowed to be executed when C<tlmgr> is invoked in system mode (that is,
 without C<--usermode>).
 
 This allows distributors to include the C<tlmgr> in their packaging, but
-allow only a restricted set of actions that do not interfere with the
-distro package managers.  For native TeX Live installations, it doesn't
+allow only a restricted set of actions that do not interfere with their
+distro package manager.  For native TeX Live installations, it doesn't
 make sense to set this.
 
 =back
 
 The C<no-checksums> key needs more explanation.  By default, package
 checksums computed and stored on the server (in the TLPDB) are compared
-to checksums computed locally after downloading.  C<no-checksums>
-disables this.
-
-The checksum algorithm is SHA-512.  Your system must have (looked for in
-this order) the Perl C<Digest::SHA> module, the C<openssl> program
-(L<http://openssl.org>), or the C<sha512sum> program (from GNU
-Coreutils, L<http://www.gnu.org/software/coreutils>).  If none of these
-are available, a warning is issued and C<tlmgr> proceeds without
-checking checksums.  (Incidentally, other SHA implementations, such as
-the pure Perl and pure Lua modules, are much too slow to be usable in
-our context.)  C<no-checksums> also avoids the warning.
-
+to checksums computed locally after downloading.  That is, for each
+C<texlive.tlpdb> loaded from a repository, the corresponding checksum
+file C<texlive.tlpdb.sha512> is also downloaded, and C<tlmgr> confirms
+whether the checksum of the downloaded TLPDB file agrees with the
+download data.  C<no-checksums> disables this process.
+
+The checksum algorithm is SHA-512.  Your system must have one of (looked
+for in this order) the Perl C<Digest::SHA> module, the C<openssl>
+program (L<http://openssl.org>), the C<sha512sum> program (from GNU
+Coreutils, L<http://www.gnu.org/software/coreutils>), or finally the
+C<shasum> program (just to support old Macs).  If none of these are
+available, a warning is issued and C<tlmgr> proceeds without checking
+checksums.  (Incidentally, other SHA implementations, such as the pure
+Perl and pure Lua modules, are much too slow to be usable in our
+context.)  C<no-checksums> avoids the warning.
 
 =head1 CRYPTOGRAPHIC VERIFICATION
 
-If a working GnuPG binary (C<gpg>) is found (see below for search
-method), by default verification of downloaded files is performed. This
-can be suppressed by specifying C<--no-verify-downloads> on the command
-line, or adding an entry C<verify-downloads = 0> to a C<tlmgr> config
-file (described in L<CONFIGURATION FILE FOR TLMGR>). On the other hand,
-it is possible to I<require> verification by specifying
-C<--require-verification> on the command line, or by adding an entry
-C<require-verification = 1> to a C<tlmgr> config file.
-
-Verification is performed as follows: For each C<texlive.tlpdb> loaded
-for a repository, the respective checksum C<texlive.tlpdb.sha512> is
-always downloaded, too, and C<tlmgr> confirms whether the checksum of
-the downloaded TLPDB file agrees with the download data.  This is done
-in any case.
-
-Unless cryptographic verification is disabled, then a signature of the
-checksum file is downloaded and the signature verified. The signature is
-created by the TeX Live Distribution GPG key 0x06BAB6BC, which in turn
-is signed by Karl Berry's key 0x9DEB46C0 and Norbert Preining's key
-0x6CACA448.  All of these keys are obtainable from the standard key
-servers.
+C<tlmgr> and C<install-tl> perform cryptographic verification if
+possible.  If verification is performed and successful, the programs
+report C<(verified)> after loading the TLPDB; otherwise, they report
+C<(not verified)>.  Either way, by default the installation and/or
+updates proceed normally.
+
+The attempted verification can be suppressed by specifying
+C<--no-verify-downloads> on the command line, or the entry
+C<verify-downloads = 0> in a C<tlmgr> config file (described in
+L<CONFIGURATION FILE FOR TLMGR>).  On the other hand, it is possible to
+I<require> verification by specifying C<--require-verification> on the
+command line, or C<require-verification = 1> in a C<tlmgr> config file;
+in this case, if verification is not possible, the program quits.
+
+Cryptographic verification requires checksum checking (described just
+above) to succeed, and a working GnuPG (C<gpg>) program (see below for
+search method).  Then, unless cryptographic verification has been
+disabled, a signature file (C<texlive.tlpdb.*.asc>) of the checksum file
+is downloaded and the signature verified. The signature is created by
+the TeX Live Distribution GPG key 0x06BAB6BC, which in turn is signed by
+Karl Berry's key 0x9DEB46C0 and Norbert Preining's key 0x6CACA448.  All
+of these keys are obtainable from the standard key servers.
 
 Additional trusted keys can be added using the C<key> action.
 
@@ -7876,8 +7857,7 @@ checked; finally C<gpg2> is checked.
 Further adaptation of the C<gpg> invocation can be made using the two
 environment variables C<TL_GNUPGHOME>, which is passed to C<gpg> as the
 value for C<--homedir>, and C<TL_GNUPGARGS>, which replaces the default
-arguments C<--no-secmem-warning --no-permission-warning>.
-
+options C<--no-secmem-warning --no-permission-warning>.
 
 =head1 USER MODE
 
@@ -7964,7 +7944,6 @@ In user mode, these actions operate only on the user tree's
 configuration files and/or C<texlive.tlpdb>.
 creates configuration files in user tree
 
-
 =head1 MULTIPLE REPOSITORIES
 
 The main TeX Live repository contains a vast array of packages.
@@ -8058,7 +8037,6 @@ from a given repository:
 
 A summary of the C<tlmgr pinning> actions is given above.
 
-
 =head1 GUI FOR TLMGR
 
 The graphical user interface for C<tlmgr> needs Perl/Tk to be installed.
@@ -8081,7 +8059,6 @@ repository.  To load a different repository, see the C<tlmgr> menu item.
 Finally, the status area at the bottom of the window gives additional
 information about what is going on.
 
-
 =head2 Main display
 
 =head3 Display configuration area
@@ -8204,7 +8181,6 @@ action needs the option C<backupdir> set (see C<Options -> General>).
 
 =back
 
-
 =head2 Menu bar
 
 The following entries can be found in the menu bar:
@@ -8255,7 +8231,6 @@ L<http://tug.org/texlive/doc.html>) and the usual ``About'' box.
 
 =back
 
-
 =head1 MACHINE-READABLE OUTPUT
 
 With the C<--machine-readable> option, C<tlmgr> writes to stdout in the
@@ -8269,7 +8244,6 @@ L<update|/update [I<option>]... [I<pkg>]...>,
 L<install|/install [I<option>]... I<pkg>...>, and
 L</option> actions.  
 
-
 =head2 Machine-readable C<update> and C<install> output
 
 The output format is as follows:
@@ -8403,7 +8377,6 @@ If a value is not saved in the database the string C<(not set)> is shown.
 If you are developing a program that uses this output, and find that
 changes would be helpful, do not hesitate to write the mailing list.
 
-
 =head1 AUTHORS AND COPYRIGHT
 
 This script and its documentation were written for the TeX Live
@@ -8412,7 +8385,7 @@ GNU General Public License Version 2 or later.
 
 =cut
 
-# to remake HTML version: pod2html --cachedir=/tmp tlmgr.pl >/foo/tlmgr.html.
+# to remake HTML version: pod2html --cachedir=/tmp tlmgr.pl >/tmp/tlmgr.html
 
 ### Local Variables:
 ### perl-indent-level: 2
diff --git a/Master/tlpkg/TeXLive/TLCrypto.pm b/Master/tlpkg/TeXLive/TLCrypto.pm
index 29e7a2c5a41..3f23eab3001 100644
--- a/Master/tlpkg/TeXLive/TLCrypto.pm
+++ b/Master/tlpkg/TeXLive/TLCrypto.pm
@@ -61,9 +61,13 @@ BEGIN {
 
 =item C<< setup_checksum_method() >>
 
-Tries to find a checksum method: First check for usability of C<<Digest::SHA>>,
-then for either the C<openssl> or the C<sha512sum> programs.
-Returns the checksum method or undef if none found.
+Tries to find a checksum method: check usability of C<Digest::SHA>,
+then the programs C<openssl>, C<sha512sum>, and C<shasum>, in that
+order.  On old-enough Macs, C<openssl> is present but does not have
+the option C<-sha512>, while the separate program C<shasum> does suffice.
+
+Returns the checksum method as a string, and also sets
+C<<$::checksum_method>>, or false if none found.
 
 =cut