Add additional file signature check to ensure proper staging

There is a (very remote) possibility of the uploaded file being corrupted
while transferring it from the scratch directory to the staging directory,
since this transfer can actually copy data instead of being a simple
rename(2) call.  This commit adds a safeguard against this risk by
rechecking the detached signature after the file pair is moved.

The testsuite is updated accordingly.

Fix documentation detail

Move file staging to installation check step

Document internal Local::Packet::Directive::Upload class

Document internal Local::Packet::Directive class

Reorganize and document internal Local::Packet class

Tidy POD markup

Move replay check to operations list handlers

This also splits the test into separate check and update steps, such that
the timestamp ratchet file is no longer updated when a packet is rejected.

Add empty operation list predicate and use it to test for empty directives

Use packet accessor methods when validating directives

Encapsulating the operation list header fields here is a step towards
moving some of that information up to the packet objects.

Tidy message generation when replacing a file

Eliminate directory_keyrings procedure

This was called in exactly one place, where it has been inlined.

Eliminate undocumented --debug option

The debugging flag was default-on anyway.  The debugging messages can be
filtered using syslog features if desired, since they are sent to the log
with the appropriate "debug" level.

Change handling of utility functions in object classes

Several utilities are implemented in the main package and used throughout.
This commit replaces direct references to most of them with imports from
the "main" package into the various object class packages.

Add documentation for operation list classes

Move implementation of most operation list steps to operation list objects

Move operation list dispatch into new operation list objects

Convert directive interpretation and validation to method calls

Begin to move specialized helpers into their packet classes

Move construction of success report message to packet objects

This also enables additional messages to be included in the report when
processing loose directives.

Tidy conditional near summary report

(Aggregates in Perl, treated as Boolean values, are false if empty.)

Explain conditional when attaching key index

Ensure key index is ready before processing first packet

The key index is never detached, so all packets after the first were
always processed with the index lock held.  Further, the index is needed
to send a report, so ensuring that it is available before processing the
first packet avoids a potential lost report if it cannot be attached.

Move successful completion flag into packet object

Add accessor method for clearsigned message for a packet

For directive-based packets, this returns the full text of the directive,
including its enclosing OpenPGP signature.

This commit trades a small amount of efficiency for encapsulation:
one avoidable gpgv run will occur when the directive is signed with a
known key, but not a key authorized for the target directory.

Add accessor method for reporting key fingerprints from valid signatures

Move remaining main processing code to packet objects

Remove obsolete comment

Move pre-install check to execution phase

This prepares for later refactoring to move this check into a packet
object "install" method and expand other checks to approach an atomic
transaction model, where all foreseeable causes of processing errors
are checked prior to executing any step of the operation list.

The testsuite is updated accordingly.

Move Automake CVE test to packet object method

Rename 'target_filename' accessor to 'upload_filename'

This reflects the actual meaning of its return value, although the two
are currently synonymous.  Future plans may enable renaming a file pair
during its installation.  The current plans for autosigning support will
always rename autosign digest files during installation.

Use directory name objects

Remove unused helper functions

Move package name extraction to directory name object method

Add convenience object type for directory names

Update POD reflecting change to packet objects

Move target_filepair accessor to more-specialized class

Clean up scaffolding

Replace last top-level use of operation list header with accessor method

Remove kludge of storing extra messages in the operation list header

Packet objects now have a direct facility for storing extra messages.

Add accessor method to packet object for "replace" option

Move authentication and authorization checks to packet objects

Move directive parsing into packet objects

This commit also adds accessor methods for fields previously extracted
from the operation list header and moves all email address collection to
the report phase.

Defer packet object initialization

Change packet object representation

Begin to collect packet handling into object-oriented classes

Add documentation for exception accessor methods

Make sub throw a class method on all exceptions

The throw sub can still be called as a function, since its syntax is
easily compatible both ways.  When called as a function, the exception
type may be abbreviated.

Add documentation for "split-zone" keymaster command to manual

Add "split-zone" keymaster command

Replace magic numbers in flock calls with symbolic constants

This also fixes a long-standing bug where the serials file was never
actually unlocked until it was closed, at which time the kernel will
implicitly release the lock.  The cause of the bug, simply, was the use
of the wrong number in place of LOCK_UN.  Using the constant fixes this.

Add separate serials flag file for flock in gatekeeper

The flag file is zero-length and simply exists as a place to use flock.
This will eventually allow maintaining a lock while rewriting the serials
file using the traditional copy-and-rename method.

Ensure that directories mentioned in keymaster test configurations exist

Copy filename validation patterns to keymaster

Add direct serials file database checks to timestamp ratchet tests

Add serials file timestamp database checks to upload triplet tests

Add testsuite infrastructure for checking use of timestamp database

Combine shared testsuite infrastructure code

Move testsuite tool init files to dedicated directory

Tidy whitespace

Add initial preliminary manual

Ignore generated documentation files

Fix misunderstanding in FTP index builder

Handle tainted values if --with-gpgv or --with-lsof options are used

Expand FTP index builder tool

Use FTP index builder in gatekeeper source tree

Remove "send-gpg-public-keys.sh"

With the ongoing attacks on the public synchronizing keyservers, this tool is
no longer useful.

Rename "generate-ftpindex.sh" to "make-ftpindex.sh"

The shorter name fits better in Info menus.

Document "--with-gpg" keymaster option

Fix documentation error

Fix documentation formatting error

Remove "serials" configuration parameter

The serials file is now always name "serials" in pkgstatedir.

Rename "maintainermap" configuration item to "maintainerlist"

Use proper pkgstatedir with testsuite

Move email addresses to configuration file

The testsuite is expanded to cover the new options.

Ignore default configuration file

This prevents a user's configuration from being picked up into a local
repository and complicating future updates from upstream repositories.

Enforce MAX_FILE_NAME_LEN on implied directory names

A test is added to verify this check.

Remove symlinks to gatekeeper

Update online help to reflect move of zones to configuration

Import GNU Free Documentation License 1.3

Import Texinfo macros

Remove unneeded "global spawn_id" links in testsuite

Fix bug in test driver

This bug was exposed in commit fc58d8e82444d9f949f2ac5cbbed928ad6b12c30,
but only affected testsuite runs when coverage data is collected.

The exact cause is unknown, but that commit changed the processing used
for verifying signatures and the bug caused the testsuite to prematurely
declare the gatekeeper run complete and move on to the next test when a
signature was verified.  Presumably, the improved signature verification
somehow interacted poorly with Expect.

Bizarrely, the issue only occurred when Devel::Cover was used to check
the coverage of the testsuite and did not occur under regular testing.
The root cause is surely timing related, since perl is much slower when
collecting code coverage data.  This is also the reason the bug went
unnoticed for so long:  coverage runs are infrequent except when making
improvements to the testsuite.

Refactor configuration as constants in the gatekeeper

This commit also allows some parameters to be optional.

Revise global storage for serials file name

The serials file is now stored in the package state directory and is
named relative to that directory in the configuration.

Remove ZONE constant and rename variable

Remove obsolete "-s" alias for --zone option

Add tests to complete code coverage for configuration parsing

Add overlooked configuration item

Add tests for gatekeeper configuration parsing

Add blank line in testsuite output before version message

The keymaster tests already have this line.

Add initial configuration support to gatekeeper

Add options for specifying gpgv and lsof tools

This aligns the gatekeeper with the keymaster and permits the external
tools to be placed in a nonstandard location if desired.

Report an error if an unrecognized option is given to the gatekeeper

Revise version message in gatekeeper

This brings the output of ./gatekeeper.pl --version in line with current
GNU standards and moves the copyright notice to the top of the file so
Emacs can easily find it for future updates.

Update copyright notice

Rename directive parsing phase and change tag "PV" to "PS"

While there is still some syntactic validation performed during this
phase, using the word "validation" for two steps seems likely to risk
confusion, so this phase is renamed in the interests of clarity.

The testsuite is adjusted accordingly.

Remove testsuite support for signature verifications during parsing

This was only present to accommodate the extra signature verification
that as previously used to obtain an email address.  The key index now
fills that requirement.

Align actual behavior with stated intent

Any directive with a valid signature from any known key should be sent
to the public archive; the internal archive catches the rest that could
include abusive messages from anonymous parties.  Previously, the code
could only reliably recognize a valid signature if the directive syntax
is valid.  The testsuite is adjusted accordingly.

Remove scaffolding that guessed email addresses from signatures

The key index is now queried for email addresses associated with the
key used to sign the directive.