Add processing phase tag "PV" for directive parsing and validation phase

Add processing phase tag "AA" for authentication/authorization phase

Add processing phase tag "EX" for execution phase

Add processing phase tag "RP" for report phase

Add processing phase tag "SC" for scan phase

Add infrastructure to support logging current processing phase

This also collects the definition of $Log_Style to the Logging group in
preparation for future documentation improvements.

Replace ftp_warn with general warning handler in gatekeeper

This also sends any warnings generated by perl itself to syslog, which
will cause random test failures with the current testsuite, thus ensuring
that all such warnings will be fixed.

Fix use of uninitialized values in interpret_directive

Move test for missing version to interpret_directive

This changes the handling for this type of invalid directive.  These are
no longer sent to the ftp-upload-report address, but instead go only to
the ftp-upload-script box.  The testsuite is adjusted accordingly.

Regularize mail sent by debug as compared to mail sent by mail

Factor SMTP client out of mail and debug

Fix bug in find_directory

Contrary to documentation, the return value was tainted.

Remove useless check of operation list

The interpret_directive function either returns an operation list or
throws an exception, so testing the returned value is silly.  This code
had been carried over from previous refactoring when the return value of
read_directive_file was changed to an operation list; it had been a flag
nominally, but was actually a constant in read_directive_file.

Revise main code to prepare for future improvements

Use File::Spec in validate_commands

Remove temporary scaffolding

Split read_directive_file into smaller functions

The overall logic was pulled up to top-level, while most of the code is now
in new functions without side-effects.

Remove old model in interpret_directive

This removes most of the keys stored in the quasi-global %info hash, but
the current package and collection of email addresses remain to resolve.

Revise directory_email_addresses

Addresses are now collected in an array; repeated addresses are accepted at
this stage, and filtered out in the mail function.

Add central email address non-repetition filter

Revise exclude_mail_blacklist

Add tests for email address handling

Add testsuite infrastructure for detecting repeated email addresses

Fix emission of repeated email addresses

This bug was discovered when support for checking for repeated email
addresses was developed for the testsuite.

Reject blatantly invalid email addresses

This was added after discovering that, while the maintainers file and
regular email lists were screened for validity, the addresses reported
by GPG were not.  Tests for this will soon be added to the testsuite.

Revise email_addresses and rename it to directory_email_addresses

This also adds a new feature:  email addresses can be registered only for
certain subdirectories belonging to a package if desired, by listing them
in an "email" file at the corresponding location in the configuration tree.
This uses the same code as is used to locate authorized keyrings.

The use of pattern matching to extract email addresses is a precaution,
although observant readers may notice that the patterns are very lax.
Perl taint mode checks do not require this, since the email addresses will
be written to a socket rather than passed as command arguments, and hash
keys, used here for efficient de-duplication, do not carry taintedness.

Change example to mention only packages that actually exist

Mentioning a package that does not exist in a message reporting an attempt
to upload a file for a package that does not exist is certainly a clever
joke, but might be confusing to the recipient.

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.