swign(1)
Contents
swign -- Create a tar archive of a directory with an embedded GPG sig-
nature.
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]
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.
--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.
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.
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 @-
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 @.
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.
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
The environment variable SWPACKAGEPASSFD sets the passphrase file
descriptor.
0 on success, non-zero on failure.
<path>/catalog/
info swbis
swpackage(8), gpg
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
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 ]