Factor scanning loop out of directory_keyrings

This allows the same loop to be used to support other per-directory items.

Revise and rename keyring_file to directory_keyrings

This fixes a long-standing bug, due to keyring_file never actually
returning an empty list, even if the "root" keyring does not actually
exist in the filesystem.  The testsuite is adjusted accordingly.

This also introduces another minor issue, in that processing for a
misconfigured package is now abandoned earlier, before email addresses
are gathered.  This will be corrected in later improvements.

This also eliminates the special handling for a "root" keyring, although
the feature remains available as part of the general case:  "pubring.gpg"
at the root of the package configuration tree applies to all directories
in all packages.  Be very careful with the keys on such a ring, as they
would be of immense value to an attacker.

Remove parse_directory_line and guess_uploader_email

The former has been merged into interpret_directive, and the latter is
no longer useful.  Both are now removed.

Remove other call to guess_uploader_email in read_directive_file

The directive has already been parsed and this call is useless here.

Accept failure to verify signature during speculative check

Previously, the tool would stop before examining the directive file if the
signature did not match a keyring somewhere.  Plans to replace this check
with a single check against the collected master keyring ran afoul of plans
to eliminate the collected master keyring.  Current future plans are to use
an index mapping long key IDs to email addresses to replace this, since GPG
will report the long key ID used to produce a signature even if the key is
not in the available keyrings.

This changed the email sent in two cases in the testsuite, which has been
adjusted accordingly in this commit.  Concerns about unauthorized parties
abusing the mechanism to spam ftp-upload-report are not relevant here,
since a reuse of a valid directive with a bogus file would be sufficient
to cause mail to be sent to that box.  In short, that is a separate issue.

Factor email address collection out of directive-scanning loop

Merge parse_directory_line into interpret_directive

The old code is still extant because it is also used elsewhere, but will
be cleaned up in future commits.

Also avoid further processing after other errors in directive files

Avoid processing invalid directive elements

The old code simply abandoned the entire loop at the first error; this
meant that a "directory" element after an error would not be seen and was
fixed in commit 86b458910ddda2c227622cafa3c37b10682d0561.  That commit
allowed the values of the capture variables from the last successful match
to be reused if a later line did not match its filter pattern.

No exploit was possible, since an error was recorded and an exception would
be thrown instead of returning the corrupted operation list, but this had
side effects that caused failures in the testsuite that were traced to this
issue, now fixed.

Adjust pattern in testsuite

An empty "directory" element is considered invalid, but results in the
message "invalid directory" with no following text.  This was hidden by
another issue with the main code, where a failure in parse_directory_line
would add the complete contents of the directive to the message.

Add tests for tighter file name patterns in bad directory names

Also fixes a minor bug in the testsuite that prevented $BDIR from being
properly substituted in messages for these tests.

Revise timestamp check to use new operation list

Recognize that an inability to execute gpgv is a server error

This is an event that should never happen, therefore it now uses ftp_abort.

Refactor directive validity checks

The check for the "replace" element appearing in a v1.1 directive is moved
to interpret_directive and directive processing no longer stops at the
first error, since the documentation states that the order of directive
elements is insignificant.

This also fixes a long-standing bug that resulted in the sending of email
to the registered maintainers for a package depending on the relative
location of the "directory" element; the testsuite is adjusted accordingly.

Reorganize gatekeeper to collect generic GPG support functions

Prior to committing, this was validated with:
(DIFF='git diff --cached';
 comm -3 <($DIFF | grep ^- | sed -e 's/^-//' | sort) \
         <($DIFF | grep ^+ | sed -e 's/^+//' | sort) )

The output shows only blank lines, comments, and a diff header were
added, and only a diff header removed, after all lines are sorted
and paired for analysis.  To replicate, change the "git diff" command
to compare this commit with its parent.

Rename slurp_directive_file to slurp_clearsigned_message

Use epoch timestamp from GPG instead of parsing the display timestamp

The --status-fd option reports timestamps in epoch time directly, although
the documentation indicates that ISO 8601 format is also possible.  This
change eliminates several manipulations and removes the dependency on the
external Date::Manip module.

Replace clearsigned message verification

This removes the use of the shell to run gpgv when verifying directives.
This also improves the handling the of gpgv generally, since the use of
the --status-fd option is the recommended mechanism for automatic usage.

Fix bug in testing mock

If nonexistent files appear in the keyring list, grep will return an error
even if a later keyring contains a match; this will cause the mock tool to
incorrectly report not finding a key.  This bug was hidden by the main
gatekeeper only using one keyring on each gpgv run.

Complete initial implementation of new clearsigned message verification

Avoid passing tainted keyrings to signature verification

Use revised ftp_abort in verify_clearsigned_message

Revise ftp_abort to be useful in a forked child process

This commit introduces global variables to control the destination of an
abort message and the default exit code.  These variables are accessed
using lexical aliases and are only accessible in the code that uses them.

Add option to pipe signed message to mock signature verification tool

Begin to implement new gpgv clearsigned message verification

The new code allows presenting gpgv with exactly the directive that was parsed
and eliminates all risk of confusion by keeping the output, log, and status
channels separate.  This also avoids using the shell to run gpgv.

The use of a dedicated pipe with --status-fd protects against CVE-2018-12020
and any similar future vulnerabilities.

Revise execute_commands to use new model

Revise install_files to use new model

Revise use of system() in check_files

The indirect object form of system absolutely does not use the shell.

Revise check_files to use new model

Begin to revise check_files, install_files, execute_commands

This commit removes the local %info hashes in these functions.

Add operation list header to calls to check_files and install_files

Revise execute_commands to use new operation list

Add operation list to execute_commands call

This also adds a simple consistency check in execute_commands.

Change return value of read_directive_file to operation list

Previously, read_directive_file always returned zero or did not return.
We now return an operation list that will eventually replace the global
%info hash.

Tidy check for known Automake CVEs

While it is very unlikely that anyone will still use such an old version
of Automake, the potential risk is significant, so we still check.

Avoid using the shell to run /bin/tar to examine uploads

This new code uses the list-form pipe open introduced in Perl 5.8.0.

Remove intermediate array and send vulnerability check messages to syslog

Revise handling of "filename" directive element

All protocol versions so far imply an "install" command when a directive
is uploaded as part of a triplet.  This commit also adds infrastructure
to support a possible future explicit "install" command, removes a useless
validation of the packet stem against the directive file name, and cleans
up a now-unneeded variable that had been left as scaffolding.

Remove unneeded scratchpad array when reading serials file

Add tests for timestamp ratchet

Fix typo in error message

Factor version check into separate block in interpret_directive

Produced messages are changed; the testsuite is adjusted accordingly.

Add scaffolding for checking "filename" element in read_directive_file

Convert "filename_required" flag in read_directive_file to scaffolding

Further refactoring will eventually remove it entirely.

Factor timestamp ratchet out of read_directive_file

Add tests verifying handling of directives lacking commands

Revise checks for "filename" directive element in read_directive_file

The revised code uses the "filename" directive element as a command to
install an uploaded file.  This change ensures that a legitimate loose
directive will be processed even if accompanied with a bogus file.

This is a definitive break from protocol version 1.0, which was disabled
in 2012 and recently removed.

Revise interpretation of directives into operation lists

The operation list structure replaces the "order" subkey in elements in
the %info hash; as such, the "replace" option should not produce an entry
in the operation list, instead being a global flag stored in the header.

Rearrange validation checks in read_directive_file

This also resolves a TODO item in the testsuite.

Use operation list header instead of %info hash in read_directive_file

Adjust testsuite to copy output to log

Use new slurp_directive_file helper in read_directive_file

This also ensures that unsigned lines in directives are consistently
ignored.  The testsuite is adjusted accordingly; this resolves an issue
with consistently detecting and rejecting unsigned directives.

Tighten allowed file names

Improve RFC4880 conformance

Refactor directive parsing to only read file once

Add POD block for interpret_directive

This was held out of the previous commit to improve diff readability.

Factor element-processing loop out of read_directive_file

Use new read_directive helper in read_directive_file

Move declaration of counter in read_directive_file nearer to loop

Replace file-reading loop with list operations

Remove obsolete comment describing protocol v1.0

Revise main packet processing loop to use new gather_packets result

Remove testsuite handling of obsolete message

This message was removed from the gatekeeper along with the rest of the
legacy v1.0 support in commit af0774b9c0ce4907bbdf95e57ffdb534366e19dc.

Add helper procedures for directive handling in gatekeeper

Rename ftp_die to ftp_abort in gatekeeper

Use value from splitting directory line to obtain package name

Use File::Spec::Unix to count directories in parse_directory_line

Use symbolic constant for maximum directory depth

Add report of number of files with bogus names discarded

Finish refactoring of gather_packets/scan_incoming to use absolute names

This eliminates the need to change to the incoming directory and is a
step towards a goal of eliminating any dependency on the current directory
and presenting only absolute file names to the system.

Refactor scan_incoming as helper for gather_packets

The old scan_incoming function was very long and performed two related
but distinct tasks:  collecting a list of files eligible for processing
and collecting those files into packets.  The new scan_incoming now only
produces a list of files; the second loop to collect files into packets
has been moved to a new gather_packets function.

Improve comments

Update testsuite for terminology change

The original concept of "triplets" is now generalized to "packets" that
can contain any number of files.

Revise packet-gathering loop in scan_incoming

Since every packet must contain a directive, the process is now driven
based on the set of directives available.  This change also avoids
considering every file and fixes a related minor bug in the old code:
comments indicated that all files from each triplet were supposed to be
removed from possible consideration, but the loop was actually iterating
over a temporary list containing the keys of the %possible hash as of the
start of the loop.

This change also introduces a new internal format for the result of the
scan_incoming function and some temporary scaffolding code to convert the
new format to the old format to keep the tool working during the change.

Discard names of trash files immediately after unlink

Add comment describing expected issue on modern GNU/Linux

Improve comments in scan_incoming

Revise check for open files in scan_incoming

The old code would incorrectly assume that no files are open if the
lsof program fails to run; this new code uses a list-form pipe open
introduced in Perl 5.8.0 instead of an implied fork.

Also use File::Spec to form the arguments to lsof.

Check file sizes while scanning directory in scan_incoming

Excessively large directive and signature files are now detected while
scanning the incoming files directory and promptly removed afterward;
the testsuite is adjusted accordingly.

Check timestamps while scanning directory in scan_incoming

Recent files are now filtered out very early, before checking if they
are open; the testsuite is adjusted accordingly.

Revise directory scanning loop in scan_incoming

Files with unacceptable names are now removed immediately after scanning
the incoming files directory; the testsuite is adjusted accordingly.

Use arguments instead of globals in scan_incoming

Also move the declaration of the return array.

Use symbolic constants for limits in scan_incoming

Remove comment that does not accurately describe the code

Explicitly return empty list from scan_incoming if no files found

Remove redundant checks on symlink and archive commands

The tighter file name patterns now exclude ".." name components, so
these branches are now dead code.

Collect file name validation patterns

This results in some small semantic changes:  the new patterns are
stricter in handling symlink arguments and slightly looser for the
directory line.  However, this improves consistency, since the old
patterns could imply directories that could not be directly named.

Reduce the visibility of the log style global

While $Log_Style is now a global variable, the use of "strict" means that
it is only accessible in lexical scopes where it has been aliased using
the "our" feature.  These are limited, therefore reducing its scope from
a file-scope quasi-global lexical to only the initialization code and the
ftp_syslog function, where it is actually used.

Eliminate version_information sub that was called exactly once

Import GPLv3 license text as COPYING.GPLv3

Add initial shared directive-reading functions

Move more of the old comment blocks into POD

Use Pod::Usage and begin to develop internal documentation in Perl POD

POD is Perl's native documentation format, designed to embed an
approximate equivalent to a man page inside a Perl program or module.
POD can be particularly useful for docstring-like embedded per-function
documentation but has a different purpose from Texinfo, which will be
used when a reference manual is written.

Finish integration of CheckVulnerabilities code

Remove version 1.0 compatibility mode

Refactor log style tag into ftp_syslog

This removes references to $log_style at every call site and collects a
single reference to the renamed $Log_Style global in the ftp_syslog sub.

Fill long lines in gatekeeper script

Also update testsuite to recognize a message changed by this operation.

Emit stack backtrace if syslog call fails

Revise display of usage information

The script now reports success if run with the --help option.

Use Perl's "or" in conditionals used for control flow