.\" $NetBSD: netpgpverify.1,v 1.13 2018/04/04 21:39:35 sevan Exp $
.\"
.\" Copyright (c) 2013,2014,2015 Alistair Crooks <agc@NetBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 3, 2018
.Dt NETPGPVERIFY 1
.Os
.Sh NAME
.Nm netpgpverify
.Nd standalone program for digital signature verification
.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl S Ar ssh-pub-key-file
.Op Fl c Ar command
.Op Fl k Ar keyring
.Ar file ...
.Sh DESCRIPTION
The
.Nm
implements digital signature verification.
It is designed to be simple and standalone; no external libraries, except
for
.Xr libz
and
.Xr libbz2
are used, in order to ensure maximum portability.
.Pp
It is completely rewritten from the version of the program that appeared in
.Nx 6.0
as part of the
.Xr netpgp 1
suite of commands.
.Pp
The
.Nm
utility requires a file containing public keys, commonly called a
.Dq keyring .
Digitally-signed information can be fed to
.Nm
in two ways: as standard input, or as files provided on the command line.
The public key part of the key which was used to sign the file must be
present, or the signature verification will fail.
Files may be signed in two distinct ways: as text documents, and as binary
files.
Text documents modify the contents to add different line-ending
characters, and behave differently at the final byte of the input document.
Binary files are read verbatim, and are not modified in any way.
.Pp
The
.Fl k
command line argument allows a keyring to be specified.
.Pp
The
.Fl v
command line argument prints the version of the
.Nm
command and then exits.
.Pp
The
.Fl c
argument allows a
.Dq command
to be given, modifying the behaviour of the
.Nm
command.
This command can take one of three values:
.Dq verify
which is also the default, which verifies the signature
on the data;
.Dq cat
will also verify the signature on the data, and, if
successfully verified, will display the verified
data on
.Dv stdout ;
and
.Dq dump
which will dump the individual PGP packets to standard out, along
with a hexadecimal dump of the first part of the contents of each
packet.
Please note that the packets from the public key ring will also be dumped
using this command.
The key ring packets will be displayed immediately before the packets in the
file being verified.
.Pp
The
.Fl S
argument allows an ssh public key file to be used as the source of
truth for the key.
This ssh-key-based signature can be created using the
.Xr netpgp 1
utility.
.Pp
If a detached signature
.Dq .sig
is given on the command line, the signing information will be retrieved
from that file, and the original data is expected to be found in a file in the same
directory with the same name with the
.Dq .sig
suffix removed.
.Pp
Both text mode signatures, and binary signatures, can be verified by
.Nm
.Sh SIGNING AND VERIFICATION
Verification of a file's signature is best viewed using the following example:
.Bd -literal
% netpgpverify -k pubring.gpg NetBSD-6.0_RC1_hashes.asc
Good signature for NetBSD-6.0_RC1_hashes.asc made Thu Aug 23 11:47:50 2012
signature     4096/RSA (Encrypt or Sign) 064973ac4c4a706e 2009-06-23
fingerprint   ddee 2bdb 9c98 a0d1 d4fb dbf7 0649 73ac 4c4a 706e 
uid           NetBSD Security Officer <security-officer@NetBSD.org>
%
.Ed
.Sh EXIT STATUS
The
.Nm
utility will return 0 for a successful verification,
1 if the file's signature does not match what was expected,
or 2 if any other error occurs.
.Sh SEE ALSO
.Xr netpgp 1 ,
.\" .Xr libbz2 3 ,
.Xr zlib 3
.Sh STANDARDS
.Rs
.%A J. Callas
.%A L. Donnerhacke
.%A H. Finney
.%A D. Shaw
.%A R. Thayer
.%D November 2007
.%R RFC 4880
.%T OpenPGP Message Format
.Re
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 7.0 .
.Sh AUTHORS
.An Alistair Crooks Aq agc@NetBSD.org .