<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V2.4.1//EN">
<!-- 
Copyright (C) 2003 James Lowe, Jr.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or any
later version published by the Free Software Foundation; with no Invariant
Sections, with no Front-Cover Texts, and with no Back-Cover Texts.

     Formatting Instructions: 
      $ docbook-to-man sw_parse_1.sgml | nroff -man 

     docbook-to-man is a free, copyrighted tool that can be obtained from
     many sgml oriented sites.
-- >
<REFENTRY ID="swign">
<REFMETA>
<REFENTRYTITLE>
swign
</REFENTRYTITLE>
<REFMISCINFO>
swign - Tar archive signing utility for source distributions.
</REFMISCINFO>
<MANVOLNUM>1</MANVOLNUM> 
</REFMETA>
<REFNAMEDIV>
<REFNAME>
swign
</REFNAME>
<REFPURPOSE>
Tar archive signing utility for source distributions.
</REFPURPOSE>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<SYNOPSIS>
<FUNCTION>swign</FUNCTION> <OPTIONAL>options</OPTIONAL> <OPTIONAL>-u gpg-name</OPTIONAL> <OPTIONAL>--homedir=gpg-homedir</OPTIONAL> @-
</SYNOPSIS>
<SYNOPSIS>
<FUNCTION>swign</FUNCTION> -S <OPTIONAL>options</OPTIONAL> <OPTIONAL>-u gpg-name</OPTIONAL> <OPTIONAL>--homedir=gpg-homedir</OPTIONAL>
</SYNOPSIS>
</REFSYNOPSISDIV>
<REFSECT1 ID="swign">
<TITLE>
DESCRIPTION
</TITLE>
<PARA>
<FUNCTION>swign</FUNCTION>
loads a signed metadata catalog file into the current directory and then,
using GNU tar and the distribution file list, writes the archive to stdout.
The contents of the archive is the contents of the current directory ".".
The pathnames in the archive are prefixed by the directory name of ".".
The owner and group of all the files in the emitted archive are 
specified by the PSF file and command line options.
</PARA>
<PARA>
If a PSF is provided using the -s option then the specified ownership
must be consistent with the 'swign' command line options for ownerships
otherwise the signature will not be valid.  The default ownerships for all the files
are the current user's owner and group.
If the -o (or -g) option is used with a empty string for the option arg
then the file ownerships of the source files are used.
This script assumes GNU tar is installed.
</PARA>
<PARA>
After writing the ./catalog/ file and before writing the archive, the file list stored in ./catalog/dfiles/files is compared 
to the current directory contents, if any difference is found the 
archive is not written and error returned.
</PARA>
</REFSECT1>

<REFSECT1>
<TITLE>
OPTIONS
</TITLE>
<PARA>
<OPTION>--help</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
show help.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>--psf</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
show the PSF to stdout, and then exit.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-u, --local-user name</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Use name as the user ID to sign.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>--homedir=DIR</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Set the name of the home directory to DIR.  If not specified
then use "~/.gnupg".
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-s, --source=FILE</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Specify a PSF or '-' for stdin.  If this is not given then the internally
generated PSF is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-T, --show-names-only</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
show some info (for help and debugging) and exit.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-t, --run-sanity-check</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Instead of writing stdout, write the archive to ../packageDirName.swigntest.tar.gz and run some sanity tests.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-S, --sign-this</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Write the ./catalog/ file containing the digest and signature into "." and then exit without
writing the archive to stdout.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-D, --with-checksig FILE</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Include the checksig control script sourced from FILE.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-o, --owner OWNER</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Specify owner.
Use an empty string "" to specify the source file owner.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-g, --group GROUP</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Specify group.
Use an empty string "" to specify the source file group.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>-x format</OPTION> 
<GLOSSLIST>
<GLOSSLIST>
Specify the archive format.
Must be one of the formats of swpackage.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<FUNCTION>@-</FUNCTION>
<GLOSSLIST>
<GLOSSLIST>
Target, only supported target is standard output.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT1>

<REFSECT1>
<TITLE>
EXTERNAL EFFECTS
</TITLE>
<PARA>
The program will remove and replace a file in "." named ./catalog/. <SBR>
When using the '-t' option an archive file is written to ../packageDirName.swigntest.tar.gz<SBR>
</PARA>
</REFSECT1>

<REFSECT1>
<TITLE>
TESTING
</TITLE>
<PARA>
After running successfully with options 
<OPTION>-S</OPTION>  and 
<OPTION>-D FILE</OPTION>  the following should be true (report no error).
<PROGRAMLISTING>
<VERB>
          swverify --checksig .
</VERB>
<PROGRAMLISTING>
</PARA>
<PARA>
Similarly,
<PROGRAMLISTING>
<VERB>
          swign -u gpgname @- | swverify --checksig -
</VERB>
</PROGRAMLISTING>
</PARA>
<PARA>
If a checksig script is included then you should unpack the package at a
new location and run  swverify --checksig "." in the new location.
</PARA>

<PARA>
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.)
<PROGRAMLISTING>
<VERB>
       swign -D $HOME/checksig.sh -u "Test User" -o "" -g "" -S;
       swverify -d @.
</VERB>
</PROGRAMLISTING>
</PARA>
</REFSECT1>

<REFSECT1>
<TITLE>
ENVIRONMENT
</TITLE>
<PARA>
The environment variable SWPACKAGEPASSFD sets the passphrase file descriptor.
</PARA>
</REFSECT1>

<REFSECT1>
<TITLE>
RETURN VALUE
</TITLE>
<PARA>
0 on success, non-zero on failure.
</PARA>
</REFSECT1>
<REFSECT1>
<TITLE>
FILES
</TITLE>
<VERB><SBR>
 \<<REPLACEABLE>path</REPLACEABLE>\>/<FUNCTION>catalog</FUNCTION>/
</VERB>
</REFSECT1>
<REFSECT1>
<TITLE>
SEE ALSO
</TITLE>
<PARA>
info swbis
<PARA>
swpackage(8), gpg
</PARA>
</REFSECT1>
<REFSECT1>
<TITLE>
IDENTIFICATION
</TITLE>
<PARA>
<PROGRAMLISTING>
<VERB>
 swign(1): The source directory signing utility of the swbis project.
 Author: J. Lowe jhlowe@acm.org
 Version: 0.473
 Date: 2005-11-05
 Copying: GNU Free Documentation License
</VERB>
</PROGRAMLISTING>
</PARA>
</REFSECT1>
<REFSECT1 ID="R1 sw_parse">
<TITLE>
BUGS
</TITLE>
<PARA>
If a directory is signed using the '-S' option and has a file path greater than
99 chars in length then it will be unverifiable if the 'ustar0' format and
GNU tar 1.13.25 was used.
</PARA>
<PARA>
Verification of the directory form of a distribution (i.e. the installed tarball
path name prefix) such as running 'swverify -d @.' after running 'swign -S' 
will fail if the order of directory entries is not compatible with
traditional Unix file system directory entry ordering.  This incompatibility may be present in
the Ext3, reiserFS, and DarwinOS et.al file systems.
</PARA>
<PARA>
Use of the '-o USER -g GROUP' is dependent on the checksig script.
The default file ownership policies of this program are suited to packaged products
where file user and group ownerships are not a critical feature.
</PARA>
</REFSECT1>
</REFENTRY>
