swverify(8)

Contents

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

VENDOR SCRIPTS

       swverify can execute a vendor supplied fix  script.

       Not yet implemented.

IMPLEMENTATION EXTENSION VENDOR SCRIPTS

   checksig <path>/catalog/<dfiles>/checksig
       A vendor 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 distribution 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 directory, which include tar utility depen-
       dence and file owner/group specification, this script may not be useful
       to all vendors.

   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 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  constant leading path 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.

       'swverify', when  verifying  the  directory  form  of  a  distribution,
       attempts  to  authenticate  the exported catalog signature and if it is
       successful executes the 'checksig' script found in the 'dfiles' distri-
       bution  directory  of  the  exported catalog.  If the 'checksig' script
       does not exist, authentication fails. 'swverify' will only  attempt  to
       run  'checksig'  if it is found in the dfiles directory of an authenti-
       cated catalog.

       'swverify' currently has no provision to  verify  the  archive  section
       (i.e.  the  file storage structure) of a directory form POSIX distribu-
       tion besides execution of the vendor 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 pay-
       load 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.443
        Date: 2004-05-05
        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 leading path directory) 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, reis-
       erFS, and DarwinOS et.al file systems.



                                                                   swverify(8)

[ Index ] [ Back ]