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

Fix oversight with location of logging definitions

Revise syslog initialization in gatekeeper script

This reflects the renaming of the script and moves the syslog details to
one place nearer the top of the file.

The "ndelay" option could be added to the openlog call, but would be
redundant, as the script immediately logs its own startup.

Normalize argument unpacking in gatekeeper script

This shifts arguments out of @_ one at a time in each sub and also
removes a few cases of setting lists containing only one variable.

Update old-style sub calls in gatekeeper script

Merge CheckVulnerabilities module into main script

Move syslog initialization and final configuration check to preliminaries

This also required moving the message reporting subs farther up, since
this code uses ftp_syslog and ftp_die.

Remove sub main in gatekeeper script

Unlike C, Perl allows program code to simply appear at the top level of
the file.  Using this feature is the standard convention in Perl.

Reorganize gatekeeper script to sort subs ahead of their callers

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.

Document change of script name and update copyright years

Fix prototype on ftp_die in gatekeeper script

Currently, this prototype has no effect because the entire script has been
compiled before it is seen.  Moving ftp_die to near the beginning of the script
will cause the prototype to be checked and the incorrect prototype causes
compilation to fail.

Rename the upload-ftp tool to "gatekeeper" and update symlinks

At this time, the tool still reports as "ftp-upload" in syslog.

Remove old version of upload-ftp script

Import existing script generate-ftpindex.sh

Work around Expect bug

Improve handling of test environments in upload testsuite

This removes the argument to the new_test_environment procedure.

Clean up scratchpad files in mock tool testsuite

Remove Emacs time-stamp configuration

The files are now tracked in Git and the actual timestamp was removed
long ago -- the oldest version in the repository does not have it.

Add test for rejection of future directive signature timestamp

Correctly handle both old and new signature timestamps from GPG

Add debugging message reporting directive signature timestamp

Fix critical bug in symlink command handling found during testing

Previously, while symlink targets were checked for the string "..", symlink
names were unchecked; this allowed symlinks to be placed outside of the
permitted areas for which the signing key is authorized and even outside of the
managed file tree, requiring only that the containing directory already exist.
The test case places a symlink directly into the top-level pub/ directory to
demonstrate the issue and confirm that it is fixed.

I consider this bug critical because while the rogue symlink can only refer to
something else at or below its own location, it could replace an existing
symlink.  While I do not expect that this provides any way to crack system
security, careful misuse could certainly cause considerable nuisance, possibly
breaking the entire system if an attacker can find a symlink that is critical
for the system's operation and replace it with a dangling symlink.

Add more tests for loose directives to improve coverage

Add more tests for misconfigured package scenarios

Add more tests for invalid directives in triplets

Change DEBUG, NOMAIL, TSTAMPCHECK mode flags to constants

This simplifies coverage analysis reports, since these flags are only set
while initializing the script and never changed during a run.

Add tests for oversize directive and signature files

Improve log messages for oversize directive or signature files

The new messages are easier for the testsuite to match.

Add idle processing tests for recent uploads

Add infrastructure for testsuite coverage analysis

Tidy whitespace

Add tests for Automake vulnerability filter logic

Add tests for basic triplet handling

Ensure that upload handler syslog messages do not span lines

Meet taint mode requirements for handling test SMTP port

fix for gpgv upgrade 1.4 to 2.2.4

Clean up whitespace using Emacs

Include more information in the test log

Previously, the analyze_file_tree procedure stopped immediately when a
tree that was expected to be empty was found to contain files.  This
change causes a full list of the files found to appear in the log.

Add testsuite support for building tarballs for test cases

Add initial partial testsuite

This does not yet check actual upload handling, but the testsuite
infrastructure seems to be sufficiently developed at this point that no
major changes should be needed to support further tests.

Add "no-op" command for testing uses

This command is only recognized in test mode.

Improve recognizability of debugging message for testsuite

Avoid running generate-ftpindex during tests

The attempt to rebuild the FTP server index is normally harmless, since most
test machines will not actually have /usr/local/bin/generate-ftpindex and the
error from the inability to execute that tool is ignored anyway.

However, if the testsuite is ever actually run on the FTP upload server, this
will prevent a large amount of spurious work rebuilding the FTP indexes.