# swign(1)

### Contents

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

### 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.

           -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-checksig FILE
                  Include the checksig control script sourced from FILE.  This  is
                  only  needed when not supplying a PSF, that is this option modi-
                  fies 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 checksig script is included then you should unpack the package at
           a new location and run  swverify -d @. in the new location.  The check-
           sig  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 inten-
           tion is that it be used to verify the contents of the package directory
           using GNU tools such as md5sum, sha1sum, and tar.  It serves to  verify
           'swbis'  utilities  and offers a way for the package consumer to verify
           file integrity using non-swbis GNU utilities by parsing the  INFO  file
           and  comparing  to the unpacked files, and re-creating the archive byte
           stream digests and comparing to './catalog/dfiles/md5sum' and

           If a checksig script is not included, then the package user  will  have
           to  manually  execute the commands that would have been executed by the
           script.  When verifying the unpacked directory form of a package,   the
           swverify  program  will return an error if the checksig 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
           checksig.sh is found in ./bin of the source distribution.)

                  swign -D $HOME/checksig.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

           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 checksig script in ./catalog/dfiles/checksig
           # For a description of the checksig script see the info document for
           # 'swbis', type: info swbis, and the swign and swverify man pages.

             checksig  < bin/checksig.sh

           # The vendor object provides attributes to describe
           # the distributor.  At this time, how these attributes
           # are used is not addressed.

           vendor
              the_term_vendor_is_misleading True  # One of: True, False
              tag your@email
              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.

           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 your@email            # Match vendor.tar 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.

               exclude catalog

           # End of PSF

### ENVIRONMENT

           The  environment  variable  SWPACKAGEPASSFD  sets  the  passphrase file
           descriptor.

### 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.481
            Date: 2006-02-14
            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 checksig script (if any)  and
           the  command line options must agree.  The default file ownership poli-
           cies of this program are suited to packaged products  where  file  user
           and group ownerships are not a critical feature.

                                                                          swign(1)

[ Index ] [ Back ]