swverify(8)							   swverify(8)



NAME
       swverify -- Verify Software

SYNOPSIS
       Posix:

       swverify  [-d|-r]  [-F]	[-f file]  [-t targetfile] \
       [-x option=value]  [-X options_file]  [-W option] \
       [software_selections]  [@targets]

       swverify

       swverify -r selection [@ target]

       swverify -d [@ target]

       swverify -d @-	# Note: special meaning for dash as stdin

       swverify -d @.	# Note: special meaning for . as current directory

       Implementation Extension:

       swverify --checksig [portable_archive_file]

       swverify --checksig directory

       swverify [-Wd] -Wemit-signed-file [portable_archive_file]

       swverify [-Wd] [-Wsha1] -Wemit-digest-file [portable_archive_file]

       swverify [-Wd] -Wget-sig-if=sigfilename [portable_archive_file]

DESCRIPTION
       The  swverify  utility checks the accuracy of software in distributions
       and installed_software.	If no options are given, a serial distribution
       on stdin is verified.

       Currently,  swverify  does  not	read  the  defaults files.  "/" is the
       default target for installed software.  Stdin is the default target for
       distributions.	The  built-in value of "installed_software_catalog" is
       "var/lib/swbis/catalog".

OPTIONS
       -d
	      Specify to operate on a distribution rather than installed soft-
	      ware.
       -r
	      Specify to operate on installed software at the target path.


       software_selections
	      See other man pages.


       targets
	      See  other  man  pages.	Currently,  only one (1) target can be
	      specified.


       -x option=value
	      Specify the extended option overriding the defaults file	value.
	      This option not yet implemented.

       -X FILE
	      Specify  the  extended  options  filename, FILE,	overriding the
	      default filename.  This option not yet implemented.

       Other posix options not implemented.

POSIX EXTENDED OPTIONS
       Not yet implemented.

IMPLEMENTATION EXTENSION OPTIONS
       -W option[,option,...]
	      Specify the implementation extension option.
	       Syntax: -W option[=option_argument[,option...]
	       Options may be separated by a comma.

       --checksig | -W checksig
	      If target file is not a directory then verify  archive  md5  and
	      sha1  and  gpg signature directly from the file.	If target file
	      is a directory, attempt to verify the signature  using  GNU  tar
	      and  gpg	and  if  successful  execute the distributor extension
	      script checksig.	If checksig does  not  exist  then  exit  with
	      failure.
	       FILE may be "." (current directory) or "-" (standard input).  A
	      serial archive file may be compressed with gzip, bzip2, or  Unix
	      compress.

       -W emit-signed-file | -W C
	      Read  archive  file  FILE or standard input and write the signed
	      file (i.e. gpg's signed stuff) to stdout.  This is  the  catalog
	      section of the Posix package.

       -W emit-digest-file | -W S
	      Read  archive  file FILE or standard input and write the archive
	      section of the file (that was used to make the md5 and sha1 mes-
	      sage  digests)  to  stdout.   This is the storage section of the
	      Posix package.

       -W show-auth-files | -W d
	      Writes the relevent security file to stderr.  Applies  to  emit-
	      digest-file and emit-signed-file modes.

       -W sig-number=N
	      Operates on the Nth signature, 0 is last, 1 is the first.

       -W get-sig-if=outputfile
	      Verifies	the archive digests by comparing to the digests in the
	      catalog and if they match write the sigfile  to  outputfile  and
	      the signed data to stdout.

DISTRIBUTOR SCRIPTS
       Not yet implemented.

IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS
   checksig <path>/catalog/<dfiles>/checksig
       A  software  distributor  may choose to provide a checksig script.  The
       checksig  script is part of the distribution object.   It  is  used  to
       verify  the  directory  form  of a distribution	(as distinguished from
       installed_software).  The verified attributes are  the  same  as  those
       verified  from the archive file form with the addition of the distribu-
       tion file list.	In  addition  the  script  may	chose  to  verify  the
       adjunct_md5sum  and  file.md5  digests  and symbolic links.  Due to the
       constraints of reproducing the archive message digests from the	direc-
       tory,  which include tar utility dependence and file owner/group speci-
       fication, this script may not be useful to all distributors.

   Execution Environment
       The script should require the SW_CONTROL_TAG  environment  variable  be
       set to "checksig" and if not exit with failure.

VERIFYING SIGNATURES
       The  design  separates the payload and catalog, therefore, verification
       requires verifying the storage section md5 and sha1 message digests and
       then verifying the signature of the catalog.  Naturally, it is required
       that the signed data include the storage section  message  digests  and
       that  they match the storage sections.  The storage section digests are
       stored as separate attribute files in the dfiles catalog directory.

       The checksig mode checks all the security files in the package  and  is
       the  preferred  way  to	authenticate a package.  The emit-signed-file,
       emit-digest-file modes are useful for testing, sanity checks and custom
       applications.  The get-sig-if is the function used by checksig.

   Verifying a POSIX distribution Archive Manually
       The  design  of the authentication attributes supports manual verifica-
       tion of the archive file (e.g. tarball) form of the distribution,  that
       is verification take place on the uncompressed archive using 'gpg', GNU
       'tar'  and  the	swbis  utility	'swverify'  (or  the  library  utility
       'arf2arf').

       The authentication requires the following steps:

       1) Obtain the signature from the package.
       2) Recreate the signed data and present this byte stream and
	  the signature to GNU privacy guard (gpg) for authentication.
       3) Obtain the message digest (md5, sha1,) contained in the
	  control file in the authenticated archive byte stream.
       4) Recreate the digest byte stream and present to the appropriate
	  hash generation program to generate the message digest.
       5) Compare the digest message generated in step 4 to the
	  authenicated digest obtained in step 3.

       1) Obtain the signature from the package.

	 #!/bin/sh
	 tar zxf - -O \*/catalog/dfiles/signature < swbis-0.460.tar.gz

       2)  Recreate the signed data

	 #!/bin/sh
	 swverify -WC < swbis-0.460.tar.gz | gpg --verify /dev/tty -
	 # Cut and paste the signature file obtained in step 1

       3)  Obtain the message digest

	 #!/bin/sh
	 swverify -WC < swbis-0.460.tar.gz | tar xf - -O \*/catalog/dfiles/md5sum

       4)  Create the digested byte stream

	 #!/bin/sh
	 swverify -WS < swbis-0.460.tar.gz | md5sum


   Verifying a POSIX distribution Directory Manually
       The  design  of the authentication attributes supports manual verifica-
       tion of the directory (unpacked) form of the distribution, that is ver-
       ification  takes  place	on  the leading package directory and its con-
       tents. It should be noted that it is left to the user  to  verify  that
       the  archive installed no files outside of this directory as this would
       likely indicate a trojan'ed package.

       If authenticating on a GNU/Linux system using GNU tar it is possible to
       validate the archive message digests and signature if the following are
       true:


       1) The package file is a tar archive.
       2) The installed version of GNU tar produces archives with
	  bit-for-bit sameness relative to the swpackage(8) utility
	  that generated the signature and message digests.
       3) The package has a single leading package directory.
       4) The package catalog contains the 'checksig' script.
       5) The package catalog contains the distribution file list.
       6) The ownership names are present and have the same uid's and gid's.
       7) The package was unpacked with a version of tar that
	  preserves all file times.


       In this example, the package has a  single  path  name  prefix  called,
       namedir	and  the  file	owner/group  are root.	These restrictions are
       suited to source packages.

       Verify the signature:

	 #!/bin/sh
	 tar cf - -b1 --owner=root --group=root \
	 --exclude=namedir/catalog/dfiles/signature  \
	 namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -

       If this fails try using GNU tar option --posix.	If  this  fails  then,
       try  experimenting  with  the owner, group, and numeric-id options.  If
       you are unable to verify a tar byte stream using gpg(1)	that  contains
       the storage section message digests, then the package cannot be authen-
       ticated.


       Assuming you successfully verified the catalog as shown above, now gen-
       erate  the  message  digest and compare it to the md5sum file attribute
       from the same byte stream that gpg(1) claims is authenticate.

	 #!/bin/sh
	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
	 tar cf - -b1 --owner=root --group=root \
	 --files-from=- --no-recursion | md5sum

	 tar cf - -b1 --owner=root --group=root \
	 --exclude=namedir/catalog/dfiles/signature  \
	 namedir/catalog | tar xf - -O	namedir/catalog/dfiles/md5sum

       Likewise for the sha1 digest.

       If the package has symbolic links, Verify the adjunct_md5sum:

	 #!/bin/sh
	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
	 ( while read file; do if [ ! -h $file ]; then echo $file; fi done; )|\
	 tar cf - -b1 --owner=root --group=root \
	 --files-from=- --no-recursion | md5sum
	 cat namedir/catalog/dfiles/adjunct_md5sum

       The symbolic link files must be verified manually by comparing  to  the
       INFO file information.

   Verifying a POSIX distribution in tar format
       Below  is  output  from	successful authentication.  The authentication
       requires checking the archive md5 message digest (and sha1 if present).
       All  present  message digests must succeed and if this is true then the
       signed file is written and gpg proceeds to check the signature.	If the
       sig_header  file is present then the requirement that its data be iden-
       tical to the ustar header of every signature file is enforced.  If  any
       one of these checks fails, authentication fails.


	  #!/bin/sh
	  swverify --checksig mypackage-00.1.tar.gz
	       # - or -
	  swverify -d @- < mypackage-00.1.tar.gz


       gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
       gpg: please use "keyserver-options honor-http-proxy" instead
       gpg: WARNING: using insecure memory!
       gpg: please see http://www.gnupg.org/faq.html for more information
       swbis: Archive digest: md5 OK (Good)
       swbis: Archive digest: sha1 OK (Good)
       gpg: Signature made Sun Mar 16 20:28:23 2003 EST using DSA key ID 82B0DBE4
       gpg: Good signature from "Test User (pass=Iforgot) localhost>"
       Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4


   Verifying the directory (unpacked) form of a Distribution.
       Authenticating  using  'swverify' is subject to the same constraints as
       verifying manually using GNU tools  because  swverify  implements  this
       using GNU tools.

       authenticate  the  exported  catalog  signature and if it is successful
       executes the catalog.  If the 'checksig' script does not exist, authen-
       tication fails. 'swverify' will only attempt to run 'checksig' if it is
       found in the dfiles directory of an authenticated catalog.

       file storage structure) of a directory form POSIX distribution  besides
       execution of the distributor extension script 'checksig'.

       If  filemypackage-00.1 is a directory unpacked with a tar reading util-
       ity that preserved file times then try,


	  #!/bin/sh
	  swverify --checksig mypackage-00.1

	or change directory into mypackage-00.1 and use the posix syntax:

	  swverify -d @.



	  swverify -d @`pwd`/mypackage-00.1

	Below is example output of a package with a 'checksig' script.


       swverify: Attempting to verify using --posix tar option.
       gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
       gpg: please use "keyserver-options honor-http-proxy" instead
       gpg: WARNING: using insecure memory!
       gpg: please see http://www.gnupg.org/faq.html for more information
       gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
       gpg: BAD signature from "Test User (pass=Iforgot) localhost>"
       swverify: First attempt failed.
       swverify: Attempting to verify without using --posix tar option.
       gpg: /home/jhl/.gnupg/options:82: deprecated option "honor-http-proxy"
       gpg: please use "keyserver-options honor-http-proxy" instead
       gpg: WARNING: using insecure memory!
       gpg: please see http://www.gnupg.org/faq.html for more information
       gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
       gpg: Good signature from "Test User (pass=Iforgot) localhost>"
       gpg: WARNING: This key is not certified with a trusted signature!
       gpg:	     There is no indication that the signature belongs to the owner.
       Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4
       swverify: GPG signature verified.
       swverify: Got it!
       swverify: The vendor extension script checksig can now be executed.
       checksig: Checking files OK (Good)
       checksig: Checking Archive md5 OK (Good)
       checksig: Checking Archive sha1 OK (Good)
       gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
       gpg: please use "keyserver-options honor-http-proxy" instead
       gpg: WARNING: using insecure memory!
       gpg: please see http://www.gnupg.org/faq.html for more information
       gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
       gpg: Good signature from "Test User (pass=Iforgot) localhost>"
       gpg: WARNING: This key is not certified with a trusted signature!
       gpg:	     There is no indication that the signature belongs to the owner.
       Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4
       checksig: Signature proper OK (Good)
       checksig: /usr/bin/gpg exit status : 0


   Verifying Installed Software
       (This capability is only partially implemented.)   Verifying  Installed
       Software involves comparing the package meta-data to the live file sys-
       tem.  The validity of a successful comparison depends on  the  validity
       of  the installed software catalog.  swverify makes no attempt to check
       the validity of the entire catalog, however, it can use	the  distribu-
       tion GPG signature, which is stored in the catalog, to authenticate the
       meta-data of the selected package.

       Below is an example. Note, the package is selected on the basis of  its
       product or bundle tag.

       $ swverify -r your_product_tag @ /
       swverify: verifying installed software at:
       swverify: //var/lib/swbis/catalog/swbis/your_product_tag/0.000/0
       gpg: WARNING: --honor-http-proxy is a deprecated option.
       gpg: please use "--keyserver-options honor-http-proxy" instead
       gpg: Signature made Fri Feb 20 00:21:00 2004 EST using DSA key ID 82B0DBE4
       gpg: Good signature from "Test User (pass=Iforgot) localhost>"
       gpg: WARNING: This key is not certified with a trusted signature!
       gpg:	     There is no indication that the signature belongs to the owner.
       Fingerprint: 77BB B98D A3A2 ED4C 217E  9A25 8BF4 05AB 82B0 DBE4
       swverify: Warning: file checks not implemented
       swverify: signature verification return status=0


   Create the digest byte stream -Wemit-digest-file mode:
       Here are some examples that verify the archive digests.


	  #!/bin/sh
	  cat your-tarball | swverify -Wd -WS | md5sum


       Your  should  see a pair of identical digests. Use the -Wsha1 option to
       check the sha1 digest in a similar manner.

       ** IMPORTANT **

       This does not mean that the data is authenticate in the sense of  being
       attributable  to  a  person,  merely  that the md5sum attribute and the
       payload byte stream match.

       To inspect the digested data, try:

	 #!/bin/sh
	 cat your-tarball | swverify -WS | tar tvf -


   Create the signed byte stream -Wemit-signed-file mode:
       Here is an example which allows inspection of the signed file.


	 cat your-tarball | swverify -WC | tar tvf -


   -Wget-sig-if mode:
       This is the mode used by --checksig.  Here is an example.


	 #!/bin/sh
	 cat your-tarball | swverify -Wget-sig-if=/dev/tty | \
	 gpg --verify  /dev/tty -


       Now try to copy and paste the sigfile and gpg should attempt to	verify
       the signature.

	      Note:   This verifies the md5 or sha1 digests before writing the
	      signed data to stdout.  If the sha1 or md5 match fails  then  an
	      empty file is written to stdout.

EXAMPLES
       Examples of verifying distributions and installed software.

   Distribution Verification
       * Verify a tar archive

	 swverify -d < foo-1.1.tar.gz
		  or
	 swverify -d @`pwd`/foo-1.1.tar.gz

		 Note: --checksig and '-d' perform the same operations.


       * Verify a unpacked distribution

	 swverify -d @`pwd`/foo-1.1
		  or
	 swverify -d @.

		 Note: --checksig and '-d' perform the same operations.


   Installed Software Verification
       * Verify installed software

	 swverify -r foo.foo @/tmp/test
		  or
	 swverify -r foo.foo

		 Note: This will attempt to verify the GPG signature.
		       The posix operations are not yet implemented.


RETURN VALUE
       Exit status of the checksig script or gpg utility for --checksig direc-
       tory operation.	0 if successful on all targets, 1  if  failed  on  all
       targets, 2 if failed on some targets.

FILES
       None


APPLICABLE STANDARDS
       IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701.

SEE ALSO
       info swbis


       sw(5), swign(1), swpackage(8), gpg(1), libexec/swbis/arf2arf


IDENTIFICATION
	swverify: The verification utility of the swbis project.
	Author: J. Lowe jhlowe@acm.org
	Version: 0.473
	Date: 2005-11-03
	Copying: GNU Free Documentation License

BUGS
       The signature file's archive header (or data) is not part of the signed
       data therefore it may be subject to  undetectable  tampering,  however,
       swverify  does  perform	sanity checks on the pathname, permissions and
       filetype if the sig_header file (See sw(5) manual page.) is not present
       [due  to being signed by a old swpackage version], and if sig_header is
       present, swverify requires that it match  the  sig  file  header.   The
       ability to verify the unpacked directory form of the package depends on
       many factors not immediately obvious, among them  are  the  tar	header
       uname and gname, and whether they are preserved by the reading utility,
       and whether these names are in the system  database  files  /etc/passwd
       and  /etc/group, and if so, whether they assign the same uid/gid as the
       package.

       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.



								   swverify(8)
