\input texinfo   @c -*-texinfo-*-
@setfilename swverify.info
@comment direntry.in
@dircategory Individual utilities
@direntry
* swverify: (swbis).               verify POSIX format packages
@end direntry
@comment ===============================================================
@comment WARNING: Do NOT edit this file.  It was produced automatically
@comment by man2info on Tue Sep  7 20:25:45 EDT 2010
@comment for jhl@
@comment from man/man8/swverify.8
@comment in /home/jhl/swbisdoc/swbis/doc
@comment ===============================================================
@comment @documentencoding ISO-8859-1
@comment troff -man typesetting style: headers, footers, no paragraph indentation
@paragraphindent none
@iftex
@parskip = 0.5@normalbaselineskip plus 3pt minus 1pt
@end iftex
@set lq ``
@set rq ''
@comment TROFF INPUT: ...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
@comment ...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: ...\"	transcript compatibility for postscript use.
@comment ...\"	transcript compatibility for postscript use.
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: ...\"	synopsis:  .P! <file.ps>
@comment ...\"	synopsis:  .P! <file.ps>
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: .de P!
@comment .de P!
\.
@comment TROFF INPUT: .fl			\" force out current output buffer
@comment .fl			\" force out current output buffer
\\!%PB
\\!/showpage@{@}def
@comment TROFF INPUT: ...\" the following is from Ken Flowers -- it prevents dictionary overflows
@comment ...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
@comment TROFF INPUT: .fl			\" prolog
@comment .fl			\" prolog
@comment TROFF INPUT: .sy cat \\$1\" bring in postscript file
@comment .sy cat \\$1\" bring in postscript file
@comment TROFF INPUT: ...\" the following line matches the tempdict above
@comment ...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
@comment TROFF INPUT: .sp \\$2u	\" move below the image
@comment .sp \\$2u	\" move below the image
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .de pF
@comment .de pF
@comment TROFF INPUT: .ie     \\*(f1 .ds f1 \\n(.f
@comment .ie     \\*(f1 .ds f1 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f2 .ds f2 \\n(.f
@comment .el .ie \\*(f2 .ds f2 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f3 .ds f3 \\n(.f
@comment .el .ie \\*(f3 .ds f3 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f4 .ds f4 \\n(.f
@comment .el .ie \\*(f4 .ds f4 \\n(.f
@comment TROFF INPUT: .el .tm ? font overflow
@comment .el .tm ? font overflow
@comment TROFF INPUT: .ft \\$1
@comment .ft \\$1
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .de fP
@comment .de fP
@comment TROFF INPUT: .ie     !\\*(f4 \{\
@comment .ie     !\\*(f4 \@{\
@comment TROFF INPUT: .	ft \\*(f4
@comment .	ft \\*(f4
@comment TROFF INPUT: .	ds f4\"
@comment .	ds f4\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f3 \{\
@comment .el .ie !\\*(f3 \@{\
@comment TROFF INPUT: .	ft \\*(f3
@comment .	ft \\*(f3
@comment TROFF INPUT: .	ds f3\"
@comment .	ds f3\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f2 \{\
@comment .el .ie !\\*(f2 \@{\
@comment TROFF INPUT: .	ft \\*(f2
@comment .	ft \\*(f2
@comment TROFF INPUT: .	ds f2\"
@comment .	ds f2\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f1 \{\
@comment .el .ie !\\*(f1 \@{\
@comment TROFF INPUT: .	ft \\*(f1
@comment .	ft \\*(f1
@comment TROFF INPUT: .	ds f1\"
@comment .	ds f1\"
'	br \@}
@comment TROFF INPUT: .el .tm ? font underflow
@comment .el .tm ? font underflow
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .ds f1\"
@comment WARNING: man/man8/swverify.8:49:%%unrecognized define-string command: [.ds f1\"]
@comment TROFF INPUT: .ds f2\"
@comment WARNING: man/man8/swverify.8:50:%%unrecognized define-string command: [.ds f2\"]
@comment TROFF INPUT: .ds f3\"
@comment WARNING: man/man8/swverify.8:51:%%unrecognized define-string command: [.ds f3\"]
@comment TROFF INPUT: .ds f4\"
@comment WARNING: man/man8/swverify.8:52:%%unrecognized define-string command: [.ds f4\"]
@comment TROFF INPUT: .TH "swverify" "8"
@headings off
@everyheading SWVERIFY(8) @| @| SWVERIFY(8)
@everyfooting  @| @thispage @|
@node Top
@chapter swverify" "8
@comment TROFF INPUT: .hy 0
@comment .hy 0
@comment TROFF INPUT: .if n .na
@comment .if n .na
@comment TROFF INPUT: .SH "NAME"
@c DEBUG: print_menu("Top")
@ifnottex
@menu
* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* POSIX EXTENDED OPTIONS::
* IMPLEMENTATION EXTENSION OPTIONS::
* DISTRIBUTOR SCRIPTS::
* IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS::
* VERIFYING SIGNATURES::
* EXAMPLES::
* RETURN VALUE::
* FILES::
* APPLICABLE STANDARDS::
* SEE ALSO::
* IDENTIFICATION::
* BUGS::
@end menu
@end ifnottex
@comment MAN2TEXI: EON
@node NAME
@section NAME
swverify @r{---} Verify Software
@comment TROFF INPUT: .SH "SYNOPSIS"
@c DEBUG: print_menu("NAME")
@comment MAN2TEXI: EON
@node SYNOPSIS
@section SYNOPSIS
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
Posix:
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify}  [-d|-r]  [-F]  [-f @i{file}]  [-t @i{targetfile}] \\
[-x @i{option=value}]  [-X @i{options@t{_}file}]  [-W @i{option}] \\
[software@t{_}selections]  [@@targets]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify}  # Verify standard input
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} selection [@@ target] # Verify Installed Software
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} -d [@@ target]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} -d @@-   # dash means standard input
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [--scm|--order-files] -d @@.  # . means current directory
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [--scm|--order-files] -d @@:package@t{_}directory
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
Implementation Extension:
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [-Wd] -Wemit-digest-file [portable@t{_}archive@t{_}file]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [-Wd] -Wemit-signed-file [portable@t{_}archive@t{_}file]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [-Wd] [-Wsha1] -Wemit-digest-file [portable@t{_}archive@t{_}file]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swverify} [-Wd] -Wget-sig-if=sigfilename [portable@t{_}archive@t{_}file]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "DESCRIPTION"
@c DEBUG: print_menu("SYNOPSIS")
@comment MAN2TEXI: EON
@node DESCRIPTION
@section DESCRIPTION
@comment TROFF INPUT: .PP
The
@b{swverify} utility checks the accuracy of software in distributions and installed@t{_}software.
If no options are given, a serial distribution on stdin is verified.
@comment TROFF INPUT: .PP
Currently,
@b{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@t{_}software@t{_}catalog" is
"var/lib/swbis/catalog".
@comment TROFF INPUT: .SH "OPTIONS"
@c DEBUG: print_menu("DESCRIPTION")
@comment MAN2TEXI: EON
@node OPTIONS
@section OPTIONS
@comment TROFF INPUT: .PP
@b{-d}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify to operate on a distribution rather than installed software.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@b{-r}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify that target is an alternate root target. (Not currently used)
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@b{software@t{_}selections}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
See other man pages.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{targets}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
See other man pages.
Currently, only one (1) target can be specified.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-x option=value}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the extended option overriding the defaults file value.
This option not yet implemented.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-X FILE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the extended options filename, FILE,  overriding the default filename.
This option not yet implemented.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
Other POSIX options not implemented.
@comment TROFF INPUT: .SH "POSIX EXTENDED OPTIONS"
@c DEBUG: print_menu("OPTIONS")
@comment MAN2TEXI: EON
@node POSIX EXTENDED OPTIONS
@section POSIX EXTENDED OPTIONS
@comment TROFF INPUT: .PP
Not yet implemented.
@comment TROFF INPUT: .SH "IMPLEMENTATION EXTENSION OPTIONS"
@c DEBUG: print_menu("POSIX EXTENDED OPTIONS")
@comment MAN2TEXI: EON
@node IMPLEMENTATION EXTENSION OPTIONS
@section IMPLEMENTATION EXTENSION OPTIONS
@comment TROFF INPUT: .PP
@b{-W option[,option,...]}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the implementation extension option.
@comment TROFF INPUT: .br
@comment .br
Syntax: -W option[=option@t{_}argument[,option...]
@comment TROFF INPUT: .br
@comment .br
Options may be separated by a comma.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{@minus{}@minus{}checksig | -W checksig }
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
This is the default action and is the same as the POSIX syntax "-d @@target".
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 @b{checksig}.  If @b{checksig }
does not exist then exit with failure.
@comment TROFF INPUT: .br
@comment .br
FILE may be "." (current directory) or "-" (standard input).  A serial archive file may be compressed
with gzip, bzip2, or Unix compress.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--order-catalog}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Use the order of files in catalog/@i{dfiles}/files to recreate
the signed data when verifying the directory (unpacked tarball) form of the package.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--cvs}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Read and process information in the ./catalog (before it is authenticated) to correct the file sytem
meta-data in an attempt to verify the GPG signature.
It only affects verification on the directory (unpacked tarball), not tarball verification.
It is required when verifying an exported or working SCM (Source Code Management, such as CVS) directory if
the SCM does not preserve and restore file system meta-data.
This option also emliminates the dependency on the order of files in file system directories.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--scm}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Currently, same as the @b{--cvs} option.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--no-checkdigest}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
When verifying the directory form, do not run the checkdigest script even if the GPG signed data contains
the checkdigest script.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--signed-file } [FILE]
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Write the GPG signed portion of the package to stdout without verifying it.
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.
This option is supported for the tarball file and unpacked tarball directory.
Use of the --scm option may be required for the unpacked tarball directory form.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{--digest-file } [FILE]
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Write the payload portion of the package to stdout without verifying its digest
matches the digest in the signed data.
This is the storage section of the Posix package.
This option is not supported for the unpacked tarball form.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W emit-signed-file | -W C}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as @b{--signed-data}.  Also the same as -WC
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W emit-digest-file [FILE]}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as @b{--digest-data}.  Also the same as -WS
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W show-auth-files | -W d}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Writes the relevent security file to stderr.
Applies to emit-digest-file and emit-signed-file modes.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W sig-number=N}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Operates on the Nth signature, 0 is last, 1 is the first.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W get-sig-if=outputfile}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "DISTRIBUTOR SCRIPTS"
@c DEBUG: print_menu("IMPLEMENTATION EXTENSION OPTIONS")
@comment MAN2TEXI: EON
@node DISTRIBUTOR SCRIPTS
@section DISTRIBUTOR SCRIPTS
@comment TROFF INPUT: .PP
Not yet implemented.
@comment TROFF INPUT: .SH "IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS"
@c DEBUG: print_menu("DISTRIBUTOR SCRIPTS")
@comment MAN2TEXI: EON
@node IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS
@section IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS
@comment TROFF INPUT: .SS "checkdigest <\fIpath\fP>/\fBcatalog\fP/<\fIdfiles\fP>/\fBcheckdigest\fP"
@c DEBUG: print_menu("IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS")
@ifnottex
@menu
* checkdigest <@i{path}>/@b{catalog}/<@i{dfiles}>/@b{checkdigest}::
* Execution Environment::
@end menu
@end ifnottex
@comment MAN2TEXI: EON
@node checkdigest <@i{path}>/@b{catalog}/<@i{dfiles}>/@b{checkdigest}
@subsection checkdigest <@i{path}>/@b{catalog}/<@i{dfiles}>/@b{checkdigest}
@comment TROFF INPUT: .PP
This script was named 'checksig'.  As of 2006-03-28, the name of this script should be 'checkdigest'.
The name 'checksig' should be considered deprecated for new packages.
@comment TROFF INPUT: .PP
A software distributor may choose to provide a @b{checkdigest }script.
The @b{checkdigest } script is part of the distribution object.
It is used to verify the directory form of a distribution  (as distinguished
from installed@t{_}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 @i{adjunct@t{_}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 dependence and file owner/group specification,
this script may not be useful to all distributors.
@comment TROFF INPUT: .SS "Execution Environment"
@comment MAN2TEXI: EON
@node Execution Environment
@subsection Execution Environment
 The script may require the SW@t{_}CONTROL@t{_}TAG environment variable be set to "checkdigest" or "checkfile"
and if not exit with failure.
swverify will set this variable to "checkfile" if the --scm or --cvs option is
used, and otherwise to "checkdigest".  The script may take different action based on the value.
Currently, the checkdigest script used by the swbis source package will omit the archive digests
checks if set to SW@t{_}CONTROL@t{_}TAG="checkfile" since reproducing the archive digest is not possible
when the package is exported from CVS due to file system meta-data non-preservation. In this case
the file list is checked and the md5 and sha1 digests are verified for each regular file.
@comment TROFF INPUT: .SH "VERIFYING SIGNATURES"
@comment MAN2TEXI: EON
@node VERIFYING SIGNATURES
@section VERIFYING SIGNATURES
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
The
@b{checksig} (i.e. swverify -d @@-) mode verifies a tarballs embedded signature.
This mode checks all the security files in the package and
is the preferred way to authenticate a package.
The @b{emit-signed-file},
@b{emit-digest-file} modes are useful for testing, sanity checks
and custom applications.
The @b{get-sig-if} is the function used when verifying a tarball.
@comment TROFF INPUT: .SS "Verifying a POSIX Distribution Archive Manually"
@c DEBUG: print_menu("VERIFYING SIGNATURES")
@ifnottex
@menu
* Verifying a POSIX Distribution Archive Manually::
* Verifying a POSIX Distribution Directory Manually::
* Verifying a POSIX distribution in tar format::
* Verifying the Directory Form of a Distribution::
* Verifying Installed Software::
* Create the digest byte stream -Wemit-digest-file mode - ::
* Create the signed byte stream -Wemit-signed-file mode - ::
* -Wget-sig-if mode - ::
@end menu
@end ifnottex
@comment MAN2TEXI: EON
@node Verifying a POSIX Distribution Archive Manually
@subsection Verifying a POSIX Distribution Archive Manually
@comment TROFF INPUT: .PP
The design of the authentication attributes supports manual verification 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').
@comment TROFF INPUT: .PP
The authentication requires the following steps:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
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.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 1) Obtain the signature from the package.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  tar zxf - -O \\*/catalog/dfiles/signature < swbis-0.460.tar.gz
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
2)  Recreate the signed data
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  swverify -WC < swbis-0.460.tar.gz | gpg --verify /dev/tty -
  # Cut and paste the signature file obtained in step 1
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
3)  Obtain the message digest
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  swverify -WC < swbis-0.460.tar.gz | \\
  tar xf - -O \\*/catalog/dfiles/md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
4)  Create the digested byte stream
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  swverify -WS < swbis-0.460.tar.gz | md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Verifying a POSIX Distribution Directory Manually"
@comment MAN2TEXI: EON
@node Verifying a POSIX Distribution Directory Manually
@subsection Verifying a POSIX Distribution Directory Manually
@comment TROFF INPUT: .PP
Verifying the unpacked tarball package form.
@comment TROFF INPUT: .PP
The design of the authentication attributes supports manual verification of
the directory (unpacked) form of the distribution, that is verification
takes place on the leading package directory and its contents. 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.
@comment TROFF INPUT: .PP
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:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
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.  For packages
   made with swbis versions >= 0.474 and with format option "ustar"
   you will need GNU tar 1.14 or 1.15.*
3) The package has a single leading package directory, like a source
   package.
4) The package catalog contains the 'checkdigest' 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.  Use for example "tar xpf".
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
In this example, the package has a single path name prefix called, @b{namedir} and
the file owner/group are root.  These restrictions are suited to
source packages.
@comment TROFF INPUT: .br
@comment .br
 Verify the signature:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  tar cf - -b1 --owner=root --group=root \\
  --exclude=namedir/catalog/dfiles/signature  \\
  namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
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 authenticated.
@comment TROFF INPUT: .PP
Assuming you successfully verified the catalog as shown above, now generate
the message digest and compare it to the md5sum file attribute from
the same byte stream that gpg(1) claims is authenticate.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/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
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
Likewise for the sha1 digest.
@comment TROFF INPUT: .PP
If the package has symbolic links, Verify the adjunct@t{_}md5sum:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/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@t{_}md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
The symbolic link files must be verified manually by comparing to the INFO file
information.
@comment TROFF INPUT: .SS "Verifying a POSIX distribution in tar format"
@comment MAN2TEXI: EON
@node Verifying a POSIX distribution in tar format
@subsection Verifying a POSIX distribution in tar format
@comment TROFF INPUT: .PP
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 @b{sig@t{_}header} file is present then the requirement
that its data be identical to the ustar header of every signature file is
enforced.
If any one of these checks fails, authentication fails.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
   #!/bin/sh
   swverify --checksig mypackage-00.1.tar.gz
        # - or -
   swverify -d @@- < mypackage-00.1.tar.gz
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
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
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Verifying the Directory Form of a Distribution"
@comment MAN2TEXI: EON
@node Verifying the Directory Form of a Distribution
@subsection Verifying the Directory Form of a Distribution
@comment TROFF INPUT: .PP
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.  If it is successful it executes the 'checkdigest'
script found in the 'catalog/dfiles' directory of the exported
catalog.  If the 'checkdigest' script does not exist, authentication fails. 'swverify'
will only attempt to run the 'checkdigest' script if it is found in the dfiles directory of
an authenticated catalog.
'swverify' currently has no provision to verify the archive section (i.e. the
file storage structure) of a directory (unpacked) form of a POSIX distribution.
It is the role of the checkdigest script to do this.
For example, if filemypackage-00.1 is a directory unpacked with a tar reading utility
that preserved file times then try,
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
   #!/bin/sh
   swverify --checksig mypackage-00.1
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 or change directory into mypackage-00.1
and use the POSIX syntax:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
   swverify -d @@.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
   swverify -d @@`pwd`/mypackage-00.1
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 Below is example output of a package with a 'checksig' script.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
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
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Verifying Installed Software"
@comment MAN2TEXI: EON
@node Verifying Installed Software
@subsection Verifying Installed Software
@comment TROFF INPUT: .PP
(This capability is only partially implemented.)
Verifying Installed Software involves comparing the package
meta-data to the live file system.  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 distribution GPG signature, which
is stored in the catalog, to authenticate the meta-data of the selected
package.
@comment TROFF INPUT: .PP
Below is an example. Note, the package is selected on the basis of its
product or bundle tag.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
$ swverify -r your@t{_}product@t{_}tag @@ /
swverify: verifying installed software at:
swverify: //var/lib/swbis/catalog/swbis/your@t{_}product@t{_}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>"
Fingerprint: 77BB B98D A3A2 ED4C 217E  9A25 8BF4 05AB 82B0 DBE4
swverify: Warning: file checks not implemented
swverify: signature verification return status=0
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Create the digest byte stream -Wemit-digest-file mode:"
@comment MAN2TEXI: EON
@node Create the digest byte stream -Wemit-digest-file mode -
@subsection Create the digest byte stream -Wemit-digest-file mode:
@comment TROFF INPUT: .PP
Here are some examples that verify the archive digests.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
   #!/bin/sh
   cat your-tarball | swverify -Wd -WS | md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
Your should see a pair of identical digests. Use the -Wsha1 option to check the
sha1 digest in a similar manner.
@comment TROFF INPUT: .PP
** IMPORTANT **
@comment TROFF INPUT: .br
@comment .br
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.
@comment TROFF INPUT: .PP
To inspect the digested data, try:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  cat your-tarball | swverify -WS | tar tvf -
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Create the signed byte stream -Wemit-signed-file mode:"
@comment MAN2TEXI: EON
@node Create the signed byte stream -Wemit-signed-file mode -
@subsection Create the signed byte stream -Wemit-signed-file mode:
@comment TROFF INPUT: .PP
Here is an example which allows inspection of the signed file.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  cat your-tarball | swverify -WC | tar tvf -
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "-Wget-sig-if mode:"
@comment MAN2TEXI: EON
@node -Wget-sig-if mode -
@subsection -Wget-sig-if mode:
@comment TROFF INPUT: .PP
This is the mode that is used internally when verifying a tarball.
Below is an example of using this mode manually.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  cat your-tarball | swverify -Wget-sig-if=/dev/tty | \\
  gpg --verify  /dev/tty -
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
Now try to copy and paste the sigfile and gpg should attempt to verify the signature.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@b{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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "EXAMPLES"
@comment MAN2TEXI: EON
@node EXAMPLES
@section EXAMPLES
@comment TROFF INPUT: .PP
Examples of verifying distributions and installed software.
@comment TROFF INPUT: .SS "Distribution Verification"
@c DEBUG: print_menu("EXAMPLES")
@ifnottex
@menu
* Distribution Verification::
* Installed Software Verification::
@end menu
@end ifnottex
@comment MAN2TEXI: EON
@node Distribution Verification
@subsection Distribution Verification
@comment TROFF INPUT: .PP
* Verify a tar archive
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  swverify -d < foo-1.1.tar.gz
           or
  swverify -d @@`pwd`/foo-1.1.tar.gz
           or
  swverify -d @@:foo-1.1.tar.gz
           or
  cat foo-1.1.tar.gz | swverify -d @@-
          Note: --checksig and '-d' perform the same operations.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
* Verify a unpacked distribution
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  swverify -d @@`pwd`/foo-1.1
           or
  cd foo-1.1; swverify -d @@.
           or
  swverify -d @@:foo-1.1
          Note: --checksig and '-d' perform the same operations.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
* Verify an exported SCM Directory
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  # This is the same as directory verification except the '--cvs' option is needed.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Installed Software Verification"
@comment MAN2TEXI: EON
@node Installed Software Verification
@subsection Installed Software Verification
@comment TROFF INPUT: .PP
* Verify installed software
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  swverify foo.foo @@/tmp/test
           or
  swverify foo.foo  # at default target
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "RETURN VALUE"
@comment MAN2TEXI: EON
@node RETURN VALUE
@section RETURN VALUE
@comment TROFF INPUT: .PP
Exit status of the checksig script or gpg utility for --checksig directory operation.
0 if successful on all targets, 1 if failed on all targets, 2 if failed on some targets.
@comment TROFF INPUT: .SH "FILES"
@c DEBUG: print_menu("RETURN VALUE")
@comment MAN2TEXI: EON
@node FILES
@section FILES
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
/var/lib/swbis/catalog # Location of installed catalog
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "APPLICABLE STANDARDS"
@c DEBUG: print_menu("FILES")
@comment MAN2TEXI: EON
@node APPLICABLE STANDARDS
@section APPLICABLE STANDARDS
@comment TROFF INPUT: .PP
IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701.
@comment TROFF INPUT: .SH "SEE ALSO"
@c DEBUG: print_menu("APPLICABLE STANDARDS")
@comment MAN2TEXI: EON
@node SEE ALSO
@section SEE ALSO
@comment TROFF INPUT: .PP
info swbis
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
sw(5), swign(1), swpackage(8), gpg(1), libexec/swbis/arf2arf
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "IDENTIFICATION"
@c DEBUG: print_menu("SEE ALSO")
@comment MAN2TEXI: EON
@node IDENTIFICATION
@section IDENTIFICATION
@comment TROFF INPUT: .PP
 swverify: The verification utility of the swbis project.
 Author: James Lowe, Jr.   Email: jhlowe at acm.org
 Version: 1.6
 Last Updated: 2010-02-04
 Copying: GNU Free Documentation License
@comment TROFF INPUT: .SH "BUGS"
@c DEBUG: print_menu("IDENTIFICATION")
@comment MAN2TEXI: EON
@node BUGS
@section BUGS
@comment TROFF INPUT: .PP
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
@comment WARNING: man/man8/swverify.8:770:%%new font B started without closing previous font B
the }@b{sig@t{_}header} file (See sw(5) manual page.) is not present
[due to being signed by a old swpackage version], and if @b{sig@t{_}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.
@comment TROFF INPUT: .PP
Verification of the directory form of a distribution (i.e. the installed tarball
path name prefix) such as running 'swverify -d @@.' after running 'swign @@.'
will fail if the order of directory entries is not compatible with
traditional Unix file system directory entry ordering, which is the order of file creation.
This ordering is almost always apparent on Ext2 file system for small directories (but not
always for big directories).  Ext3, reiserFS, and DarwinOS et.al file systems do not have
this ordering, use of the '--order-catalog' option is therefore required.
Use of the '--cvs' or '--order-catalog' options is theoretically problematic
because it causes the use and interpretation of data in the verification of that
same data therefore opening possible attack vectors.
@comment  created by instant / docbook-to-man, Tue 07 Sep 2010, 20:25
@bye
