
@node Creating Signed Distributions
@chapter Creating Signed Distributions

@ifnottex
@menu
* Creating a signed POSIX archive using @command{swign}::
* Creating a signed directory using @command{swign}::
* Providing a @file{checksig} script::
@end menu
@end ifnottex

The first step in package signing is to obtain GNU Privacy Guard and its command line program
@command{gpg}.  The next step is to invoke it directly to test your gpg configuration.
The @command{gpg} program is invoked by @command{swpackage} with the following options:

@verbatim
      gpg --no-tty --no-secmem-warning --armor --passphrase-fd 3 -sb -o -
@end verbatim

The @option{--passphrase-fd} and @option{--no-tty} options would not be used if running the @command{gpg} utility
from the command line.
The option swpackage @option{--gpg-name} option maps to gpg @option{--local-user} option and
the swpackage @option{--gpg-path} option maps to gpg  @option{--homedir} option.  The default id to
sign and home directory depends on @command{gpg}'s defaults, the default home directory is 
is usually @file{~/.gnupg}.  

If you experience difficulty signing a test file using @command{gpg} then consult the gpg manual,
since configuring @command{gpg} is outside the scope of swbis.

Once you know @command{swpackage} works without signing enabled simply invoke it 
with the additional option @option{--sign} and possibly @option{--gpg-name=YOUR_ID} and
@option{--gpg-path=PATH}.  @command{swpackage} should ask for your passphrase. Note that
the @option{--sign} turns on @option{--archive-digests} automatically since a package
is not easily and fully verifiable without archive digests.

Other @command{swpackage} options you may which to use are @option{--files} and @option{--file-digests}.

For example:
@verbatim
        swpackage -Wsign,files,gpg-name="Test User" -s PSF @- >/dev/null
@end verbatim

There are defaults file options which can be set to your preferences.  The command line options always 
override the the defaults file settings.

@verbatim
     swpackage.swbis_file_digests       = "true"   # true or false
     swpackage.swbis_files              = "false"   # true or false
     swpackage.swbis_sign               = "false"   # true or false
     swpackage.swbis_gpg_name           = 
     swpackage.swbis_gpg_path           = "~/.gnupg"
     swpackage.swbis_signer_pgm	        = "GPG"
@end verbatim

In addition, signed packages can be created using the ad-hoc extension
utility @command{swign}.  It was designed especially to create signed POSIX
packages of free software source packages.

The operational constraints for using @command{swign} are that every file
in the current directory is packaged, all files have the same ownerships,
the archive will have a single leading package directory equal to the current
directory name, and the package will contain the @file{catalog} directory.
Other than the additional @file{catalog} directory, the package can be
identical to the non-POSIX package created with @command{tar}.

@command{swign} is designed to be fail safe. @command{swign} uses @command{swpackage}
and GNU @command{tar} as tools in a fashion such that all data copied to the user is
generated by GNU @command{tar} from a file list generated by @command{swpackage}.
Therefore, there is no chance the archive is corrupt, and because of sanity checks on
the file list using existing GNU file system utilities, little to no chance of missing
data.

@command{swign} requires GNU @command{tar} version 1.13.25, maybe 1.13.19 and 1.13.17 will work
as well.  Using a out-dated version will produce a valid archive, but the signature
may not be valid.


@node Creating a signed POSIX archive using @command{swign}
@unnumberedsec Creating a signed POSIX archive
Creating a signed package with @command{swign} is
easy. Just change directory to the directory you want to archive,
verify the documented side-effect of removing and replacing a
directory name @file{catalog} is not a problem.  If your directory
has a file named catalog (that is not a POSIX exported catalog) that
belongs to your data set you must rename it.  For better or worse
'catalog' is a keyname of the POSIX standard.

Then type:

@verbatim
       swign @- >/dev/null
@end verbatim

@command{swign} writes to stdout.
You must redirect the archive to a more useful file.

You could verify it like this:
@verbatim
       swign @- | swverify -d @-
@end verbatim

If a @file{checksig} script is included then you should unpack the package at
a new location and run  'swverify --checksig "."' in the new location.
@xref{Providing a @file{checksig} script}.

@node Creating a signed directory using @command{swign}
@unnumberedsec Creating a signed directory
Creating a signed directory is actually the first step that
@command{swign} does when creating a signed archive. Using
the @option{-S} simply causes @command{swign} to exit early.

Aside:
@verbatim
      This feature exposes a regression test constraint, namely
      that the byte stream generated by 'swpackage' and installed
      by 'tar' is identical to the byte stream generated by GNU 'tar'
      from the newly installed 'catalog' directory.
@end verbatim

To sign the directory, and then verify it:
@verbatim
       swign -S; swverify -d @.
@end verbatim

This produces the output:
@verbatim
    swign: Generating the catalog and installing with tar...   
    swpackage: Warning: exclude definition source [catalog] does not exist.
    Enter Password: 
    swverify: GPG signature verified.
    swverify: checksig script not found
    swverify: Package authenticity not confirmed.
@end verbatim

For more information about the 'checksig' script:
@sp 1
@xref{(swbis_swverify)IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS}, and
@sp 1
@xref{(swbis_swverify)Verifying the directory (unpacked) form of a Distribution.}.

Swign can be used to sign any directory using the  file  ownerships  of
the  source files.  The following commands act as a test of swpackage's
ability to generate an archive identical to  GNU  tar.
(Note:  checksig.sh is found in ./bin of the source distribution.)

@verbatim
      swign -D $HOME/checksig.sh -u "Test User" -o "" -g "" -S;
      swverify -d @.
@end verbatim

@node Providing a @file{checksig} script
@unnumberedsec Providing a @file{checksig} script

The @file{checksig} script is a distributor extension script.  Only the swbis
implementation of @command{swverify} knows how to use it.
An example file is found in the swbis source package.
 
You need to supply a checksig script only if you wish your customers to be
able to verify the directory form (i.e. unpacked archive) of a POSIX package.
There are constraints on the usefulness of this script which are the
same as when attempting to verify manually.
@xref{(swbis_swverify)Verifying a POSIX distribution Manually}.
 
The script is included in the package one of two ways: using the @option{-D} option of the
@command{swign} command or by specifying in a PSF to be processed by @command{swpackage}.
The syntax for referencing from a PSF is:
@verbatim
      checksig < /path/name/to/your/checksig.sh
@end verbatim

This line should be added in the distribution object of the PSF.

