Add checks that the rename builtin works as expected

The tool assumes that the Perl rename builtin can atomically move files
from the inbox to the scratchpad directory and among the staging, public,
and archive directories.  This commit extends the configuration checks
to confirm that the system can actually move files as expected.

Change storage of other mode flags to constants

This eliminates the global variables previously used to indicate if the
--help and/or --version flags had been specified and allows the relevant
conditionals to be resolved during the compilation phase.

Change current zone from a global variable to a constant

Only one zone is processed on each run of the tool, and the zone does not
change after the command arguments are parsed, so this is appropriate.

Change terminology:  "style" is now "zone"

The zone definitions will eventually be sections in a configuration file,
instead of being hardwired in the tool.  Backwards compatibility at the
command line for the old short option (which was used at the GNU FTP site)
has been preserved for now, although this support is undocumented and
therefore deprecated.

Simplify return sequence in signature verification

Factor out similar code for spawning gpgv subprocess

Rename automake_tests to check_automake_vulnerabilities and simplify

This also moves the checks for known GNU Automake CVE issues to the
top-level, and eliminates the now-otherwise-useless check_vulnerabilities
and check_files procedures.  The major impetus for this simplification
of the call graph was the observation that check_vulnerabilities, while
named generically, was associated with a log message citing specifically
CVE-2009-4029 and CVE-2012-3386, combined with noticing that all other
functionality had been factored out of check_files.

Factor uploaded file signature check up to top-level

Use new detached signature verification

Add verify_detached_signature

Factor analysis out of verify_clearsigned_message

This is in preparation for also using --status-fd when verifying detached
signatures for uploaded files.

Add check for scalar context in find_directive_elements

This avoids building a list when the only important detail is whether a key
is present in the directive.

Add check for existence when removing a symlink

While the later check to verify that the symlink to be removed actually is
a symlink will also fail if no such file exists, this produces a message
that confusingly reports a refusal to remove a non-symlink file.

Remove use of Cwd module

Since all file manipulations now use absolute file names, there is no
longer any need to query the current working directory.

Remove use of chdir

All file manipulations now use absolute file names.

Use File::Spec when reading directive file at top-level

Use File::Spec in success_upload and success_directive

Revise and document cleanup_dir and cleanup

Remove leftover variable in execute_commands

Tidy comment left when removing fatal

Revise exception handling

The directive processed is now still emailed if a simple exception
terminates processing a packet.  Previously, the directive text was only
emailed during normal processing or if a structured exception was thrown.

Remove fatal

The uses of fatal have been entirely converted to simple and structured
exceptions, allowing the gatekeeper to continue processing after a bad
upload is encountered.

Normalize simple exception messages

Remove remaining calls to fatal

These reflect system errors and are replaced with simple exceptions.

Use structured exception to report an unsigned directive

Use structured exceptions in execute_commands

Fix incorrect error messages for empty directives

Revise install_files

 - eliminate unneeded intermediate variable
 - add separate variable for external public file name
 - adjust layout
 - replace call to fatal with structured exception

The message produced for an existing file is changed and shortened;
the testsuite is adjusted accordingly.

Rearrange comment to match pattern

Use new mkdir_p helper in install_files

Instead of using File::Path or invokgin the system mkdir, we now emulate
"mkdir -p" using about 5 lines of Perl elsewhere in the script.

Tidy split line that now fits on one line

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