This is info/swbis_swign.info, produced by makeinfo version 4.7 from
stdin.

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* swign: (swbis).               make source packages with embedded GPG signature
END-INFO-DIR-ENTRY



File: swbis_swign.info,  Node: Top,  Next: NAME,  Up: (dir)

1 swign" "1
***********

* Menu:

* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* EXTERNAL EFFECTS::
* EXAMPLES::
* TESTING::
* PSF ATTRIBUTE REPLACEMENT::
* SAMPLE SOURCE PACKAGE PSF::
* ENVIRONMENT::
* RETURN VALUE::
* FILES::
* SEE ALSO::
* IDENTIFICATION::
* BUGS::


File: swbis_swign.info,  Node: NAME,  Next: SYNOPSIS,  Prev: Top,  Up: Top

1.1 NAME
========

swign -- Create a tar archive of a directory with an embedded GPG
signature.


File: swbis_swign.info,  Node: SYNOPSIS,  Next: DESCRIPTION,  Prev: NAME,  Up: Top

1.2 SYNOPSIS
============

     swign [options] [-u gpg-name] [--homedir=gpg-homedir] @-

     swign [options] [-u gpg-name] [--homedir=gpg-homedir] @.

     swign -S [options] [-u gpg-name] [--homedir=gpg-homedir]


File: swbis_swign.info,  Node: DESCRIPTION,  Next: OPTIONS,  Prev: SYNOPSIS,  Up: Top

1.3 DESCRIPTION
===============

swign loads the './catalog/' meta-data directory into the current
directory and then, using GNU tar and the distribution file list,
writes the archive to stdout.  The result is a tar archive written
entirely with GNU tar that contains an embedded GPG signature in the
control file './catalog/dfiles/signature'.  The contents of
'./catalog/' are consistent with the POSIX packaging standard ISO/IEC
15068-2:1999.  The package layout of the resulting archive is unchanged
except for the addition of the './catalog' directory.  The contents of
the archive is the contents of the current directory ".".  The
pathnames in the archive are prefixed by the base name of ".".  The
owner and group of all the files in the emitted archive are specified
by the PSF file and command line options.  In order for the signature
to be valid, the file ownerships specified in the PSF must be
consistent with the 'swign' command.  swign will read the PSF to
determine these ownerships automatically from the 'file_permissions'
directive unless the '-o' or '-g' command line options are used or if
this feature is disabled using the '--no-psf-detect' option is given.
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.  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.


File: swbis_swign.info,  Node: OPTIONS,  Next: EXTERNAL EFFECTS,  Prev: DESCRIPTION,  Up: Top

1.4 OPTIONS
===========

--help

     show help.
--show-psf

     show the PSF to stdout, and then exit.
--no-psf-detect

     Disable automatic detection of the PSF's file ownerships policy.
--no-remove

     Don't remove the ./catalog directory before overwriting.
-u, --local-user name

     Use name as the user ID to sign.
--homedir=DIR

     Set the name of the home directory to DIR.  If not specified then
     use "~/.gnupg".
-s, --source=FILE

     Specify a PSF or '-' for stdin.  If this is not given then the
     internally generated PSF is used.  The PSF is scanned for
     replacement tokens for tag and revision attributes determined from
     the current directoy name. It is expected that the current
     directory name have the form: 'tag-revision'.  The replacement
     string has the form '%__NAME' where NAME is 'tag' or 'revision'.
-T, --show-names-only

     show some info (for help and debugging) and exit.
-t, --run-sanity-check

     Instead of writing stdout, write the archive to
     ../packageDirName.swigntest.tar.gz and run some sanity tests.
-S, --sign-this

     Write the ./catalog/ file containing the digest and signature into
     "." and then exit without writing the archive to stdout.   Same as
     using "." as the target such as 'swign @.'
-D, --with-checkdigest FILE

     Include the checkdigest control script sourced from FILE.  This is
     only needed when not supplying a PSF, that is this option modifies
     an internally generated PSF.
-o, --owner OWNER

     Specify owner.  Use an empty string "" to specify the source file
     owner.
-g, --group GROUP

     Specify group.  Use an empty string "" to specify the source file
     group.
-x format

     Specify the archive format.  Must be one of the formats of
     swpackage.
@-

     Target, only supported target is standard output.


File: swbis_swign.info,  Node: EXTERNAL EFFECTS,  Next: EXAMPLES,  Prev: OPTIONS,  Up: Top

1.5 EXTERNAL EFFECTS
====================

The program will remove and replace a file in "." named ./catalog/.
Nothing outside of './catalog/' is modified.  Standard output is the
target for the tar archive.  When using the '-t' option an archive file
is written to ../packageDirName.swigntest.tar.gz A copy of the PSF is
made in /var/tmp/swign$$.  It is normally created and erased by the
program.


File: swbis_swign.info,  Node: EXAMPLES,  Next: TESTING,  Prev: EXTERNAL EFFECTS,  Up: Top

1.6 EXAMPLES
============

Show the internally generated PSF to stdout.  Change directory into the
directory to package, then type
        swign --show-psf
             -or-
        swign -o 0 -g 0 --show-psf
Generate the package (and verify it) using a PSF that you supply on
standard input.  Change directory into the directory to package, then
type
        swign -o 0 -g 0 --show-psf | swign -s - -u "gpgName" @- | swverify -d @-


File: swbis_swign.info,  Node: TESTING,  Next: PSF ATTRIBUTE REPLACEMENT,  Prev: EXAMPLES,  Up: Top

1.7 TESTING
===========

After running successfully with options -S  and -D FILE  the following
should be true (report no error).
               swverify --checksig .   # Deprecated form
                   -or-
               swverify -d @.     # Posix syntax
Similarly,
               swign -u "your GPG Name" @- | swverify --checksig -
                   -or-
               swign -u "your GPG Name" @- | swverify -d @-
If a checkdigest script is included then you should unpack the package
at a new location and run  swverify -d @. in the new location.  The
checkdigest script is a vendor extension control file that is part of
the GPG signed ./catalog directory.  As an implementation extension
behavior the swverify program will execute this script after
verification of the signature.  The script may take any action at this
point, but the intention is that it be used to verify the contents of
the package directory using GNU tools such as md5sum, sha1sum, and tar.
If a checkdigest script is not included, then the package user will
have to manually execute the commands that would have been executed by
the script using the file meta-data in an authenticated INFO file.
When verifying the unpacked directory form of a package,  the swverify
program will return an error if the checkdigest script is not present,
though, it is not required for verification of the tar archive file
itself using swverify.  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: the script checkdigest.sh is found in ./bin of the source
distribution.)
            swign -D $HOME/checkdigest.sh -u "Test User" -o "" -g "" -S;
            swverify -d @.


File: swbis_swign.info,  Node: PSF ATTRIBUTE REPLACEMENT,  Next: SAMPLE SOURCE PACKAGE PSF,  Prev: TESTING,  Up: Top

1.8 PSF ATTRIBUTE REPLACEMENT
=============================

A PSF that is provided using the '-s' option will be scanned for a
special character sequence '%__NAME'  where NAME is either 'tag' or
'revision'.  'tag' is replaced with the package name portion of the
currrent directory.  'revision' is replaced with the version portion.


File: swbis_swign.info,  Node: SAMPLE SOURCE PACKAGE PSF,  Next: ENVIRONMENT,  Prev: PSF ATTRIBUTE REPLACEMENT,  Up: Top

1.9 SAMPLE SOURCE PACKAGE PSF
=============================

     # PSF.in  -- INPUT file to swign
     # This file contains the replacement macros %__tag and %__revision which
     # are only processed by swign.
     # The distribution object need not have any attributes.
     distribution
     # Attributes in the distribution are mostly ignored although
     # distributor control files that pertain to the distribution
     # as a whole are properly placed here.  Two examples of files
     # that are useful here are:
       AUTHORS < AUTHORS   # This places the file in ./catalog/dfiles
       COPYING < COPYING   # This places the file in ./catalog/dfiles
     # This places the checkdigest script in ./catalog/dfiles/checkdigest
     # For a description of the checkdigest script see the info document for
     # 'swbis' or the swverify manual page.
     # The checkdigest script is a verification hook for swverify used when
     # verifying the unpacked tarball (i.e. the package path name
     # prefix directory).
       checkdigest  < bin/checkdigest.sh
     # The vendor object provides attributes to describe
     # the distributor.  At this time, how these attributes
     # are used is not addressed.
     # The Vendor object is optional
     vendor
        the_term_vendor_is_misleading True  # One of: True, False
        tag shortName    # Other vendor tags could be the short name of your
                              # organization name, or  your initials, etc.
        title Your Name
        qualifier author
        description "Maintainer of somepackage"
     # Most packages do not need a bundle.  At this point in swbis'
     # development 'bundles' are mostly ignored.  Bundles are meta
     # packages, it is an object that contains other bundles and
     # products whether included in this distribution tarball or not.
     # The Bundle object is optional
     bundle
        tag somepackage
     # The product object contains the attributes of common
     # interest such as the description, version and name.
     product
        description "somepackage description
     can be mult-line"
        tag %__tag                       # This is the package name
        revision %__revision             # This is the package version
        vendor_tag shortName             # Match vendor.tag above
        title "somepackage - software"
        control_directory ""             # Empty string, Important
     # The fileset object contains the files.  The tag, revision,
     # and description attributes are mostly ignored.
     # At this time swbis supports only one (1) fileset.
     fileset
         tag sources
         control_directory ""   # Empty string, Important
         title somepackage source code
         description "The source distribution of somepackage"
     # file_permissions:
     # Here is an important policy.  This will cause 'swpackage'
     # to create the tar achive with all files owned by uid and
     # gid zero (0), the user name 'root' will not be included
     # in the uname and gname tar header fields.  This is similar
     # to the effect of GNU tar options --numeric --owner=root
     # --group=root .
     # To use the name and ids of the source files delete the line
     # or reset the file_permissions adding after or changing to:
     #    file_permissions -u 000
     #
     # NOTE:  Using "file_permissions -o 0 -g 0"  is preferred
     # because it will allow the end user to more easily verify
     # the directory (unpacked) form of the package using standard
     # non-swbis tools.
     #   file_permissions -u 000  # To use ownerships of source files
         file_permissions -o 0 -g 0
     # The following two (2) lines mean include every file in the current
     # directory.
         directory .
         file *
     # You want to exclude the files in ./catalog because it
     # should not be part of the paylaod section.  This is
     # mandatory.
        exclude catalog
     # You may also want other excludes
        exclude CVS
        exclude */CVS
        # exclude .svn
        # exclude */.svn
     # End of PSF


File: swbis_swign.info,  Node: ENVIRONMENT,  Next: RETURN VALUE,  Prev: SAMPLE SOURCE PACKAGE PSF,  Up: Top

1.10 ENVIRONMENT
================

SWPACKAGEPASSFD

     Sets the swpackage --passphrase-fd option.  Set the option arg to
     a integer value of the file descriptor, or to "env" to read the
     passphrase from the environment variable SWPACKAGEPASSPHRASE, or
     to "agent" to cause gpg to use gpg-agent, or "tty" to read from
     the terminal.
SWPACKAGEPASSPHRASE

     Use the value as the passphrase if swpackage's --passphrase-fd is
     set to "env"
GNUPGHOME

     Sets the --gpg-home option of swpackage.
GNUPGNAME

     Sets the --gpg-name option of swpackage, which is turn set the
     --local-user option of gpg.


File: swbis_swign.info,  Node: RETURN VALUE,  Next: FILES,  Prev: ENVIRONMENT,  Up: Top

1.11 RETURN VALUE
=================

0 on success, non-zero on failure.


File: swbis_swign.info,  Node: FILES,  Next: SEE ALSO,  Prev: RETURN VALUE,  Up: Top

1.12 FILES
==========

\<path\>/catalog/


File: swbis_swign.info,  Node: SEE ALSO,  Next: IDENTIFICATION,  Prev: FILES,  Up: Top

1.13 SEE ALSO
=============

info swbis swpackage(8), gpg


File: swbis_swign.info,  Node: IDENTIFICATION,  Next: BUGS,  Prev: SEE ALSO,  Up: Top

1.14 IDENTIFICATION
===================

      swign(1): The source directory signing utility of the swbis project.
      Author: J. Lowe jhlowe@acm.org
      Version: 0.499
      Last Updated: 2006-08-03
      Copying: GNU Free Documentation License


File: swbis_swign.info,  Node: BUGS,  Prev: IDENTIFICATION,  Up: Top

1.15 BUGS
=========

Symbolic links in a package are problematic for verifying the unpacked
form of a package since the modification time is not preserved.  They
have no affect on verification of the tar archive file using 'swverify'.
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.  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.  The file ownership policy of the PSF, the
checkdigest script (if any) and the command line options must agree.
The default file ownership policies of this program are suited to
packaged products where file user and group ownerships are not a
critical feature.



Tag Table:
Node: Top238
Node: NAME576
Node: SYNOPSIS751
Node: DESCRIPTION1053
Node: OPTIONS2810
Node: EXTERNAL EFFECTS4759
Node: EXAMPLES5253
Node: TESTING5781
Node: PSF ATTRIBUTE REPLACEMENT7672
Node: SAMPLE SOURCE PACKAGE PSF8127
Node: ENVIRONMENT12364
Node: RETURN VALUE13105
Node: FILES13269
Node: SEE ALSO13399
Node: IDENTIFICATION13548
Node: BUGS13889

End Tag Table
