Fix example given in comment

Revise archive procedure in gatekeeper

 - a structured exception for general processing errors is added
 - the archive sub is renamed to archive_filepair
 - a file and its detached signature are now archived together
 - the archived filename now contains an extra number beyond the timestamp
   only if actually needed for uniqueness
   - the extra number, if used, matches between a file and its signature
   - the archived filename is claimed by creating an "archive stamp" file
 - the option to archive and overwrite a file using "replace" now handles
   the file and its signature as a pair
 - the system mkdir(1) and mv(1) commands are no longer invoked here
 - the testsuite is adjusted accordingly

Add helper procedure implementing "mkdir -p" in Perl

Use File::Spec for symlink operations

Use structured exceptions for empty directive

Add structured exception for GPG signature verification errors

This commit also adjusts check_files to use the package configuration
exception at the check for a lack of keyrings and tidies the syntax for a
similar check at top-level.

Add structured exception for known Automake vulnerabilities

Add structured exception for invalid signature timestamp

Add structured exception for filename mismatch

This commit also changes the exception handling for exceptions carrying
long-form messages, instead of continuing to list their types individually
and removes testsuite support for a long-obsolete log message that could
never actually be produced.

Add structured exception for directive replay

Add structured exception for unknown package error and move email check

The check for a missing per-package email list had to be moved to
validate_commands to allow the unknown package exception to be thrown.

This now makes the server misconfiguration scenario of a missing email
list distinguishable from the user error scenario of an unknown package.
The testsuite is adjusted accordingly.

Add structured exception for package configuration errors

Factor directory_package_name out of directory_email_addresses

Move check for missing "directory" element to interpret_directive

This is now considered a directive syntax error and detected earlier;
the testsuite is adjusted accordingly.

Send the summary for a structured exception to syslog

Add structured exception for directive syntax errors

This also improves the reporting of these errors, with a highlight line
inserted for each error encountered, in context.

Add initial structured exception infrastructure

Revise fatal to throw an exception and move report phase accordingly

This is an intermediate step towards collecting reporting at top-level.

This commit also enables the cleanup processing that has long been present,
but was skipped due to fatal calling exit instead of throwing an exception.
The testsuite is adjusted accordingly.

Add final section dividers to older testsuite files

Fix oversight in find_directory

An empty "directory" element would cause a warning from perl due to the
first element in the @values array being undefined.

Rename configurable directory variables and convert them to globals

Uploads arrive in Inbox_dir and are atomically transferred to Scratch_dir
for processing.  Uploaded files to be published are copied to Stage_dir
and atomically transferred to locations underneath Public_dir, while files
withdrawn from publication are atomically transferred to locations
underneath Archive_dir.  The new variable names better describe the
purposes of these directories.

These variables are also converted from file-scope lexicals to true global
variables, with access scoped lexically using Perl's "our" feature.

Remove testsuite logic that supported optional processing phase tags

All relevant messages now have phase tags in all cases.

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