swign(1)							      swign(1)



NAME
       swign  -- Create a tar archive of a directory with an embedded GPG sig-
       nature.

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]

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  './cata-
       log/'   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 writ-
       ten and error returned.


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  ../pack-
	      ageDirName.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.


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 ../pack-
       ageDirName.swigntest.tar.gz

       A copy of the PSF is made in /var/tmp/swign$$.  It is normally  created
       and erased by the program.


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 @-





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 verifica-
       tion 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 @.



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


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



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   SWPACK-
	      AGEPASSPHRASE,  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.



RETURN VALUE
       0 on success, non-zero on failure.

FILES
	<path>/catalog/

SEE ALSO
       info swbis

       swpackage(8), gpg

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


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  'swver-
       ify'.

       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 order-
       ing.   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.



								      swign(1)
