NAME
netpgp —
signing, verification,
encryption, and decryption utility
SYNOPSIS
netpgp |
--encrypt
[--output=filename]
[options] file ... |
netpgp |
--decrypt
[--output=filename]
[--pass-fd=fd]
[--num-tries=attempts]
[options] file ... |
netpgp |
--sign
[--armor]
[--detach]
[--hash=algorithm]
[--output=filename]
[--pass-fd=fd]
[--from=sig-valid-from]
[--num-tries=attempts]
[--duration=sig-valid-duration]
[options] file ... |
netpgp |
--verify
[options] file ... |
netpgp |
--cat
[--output=filename]
[options] file ... |
netpgp |
--clearsign
[--output=filename]
[--pass-fd=fd]
[options] file ... |
netpgp |
--list-packets
[--pass-fd=fd]
file ... |
netpgp |
[-Vdesv]
[-olong-option=value]
file ...
where the long options for all commands are:
[--cipher=ciphername]
[--coredumps]
[--homedir=home-directory]
[--keyring=keyring]
[--results=filename]
[--ssh-keys]
[--userid=userid]
[--verbose] |
DESCRIPTION
The
netpgp command can digitally sign files and verify that
the signatures attached to files were signed by a given user identifier.
netpgp can also encrypt files using the public or private
keys of users and, in the same manner, decrypt files which were encrypted.
For signing and encryption, a unique identity is needed. This identity is made
up of a private and public key. The public key part is made available and
known to everyone. The private key is kept secret, and known only to the user
who created the identity. The secret key is protected with a passphrase.
In rough terms, a digital signature is a digest of a file's contents, encrypted
with the user's private key. Since together, the private and public keys
identify the user uniquely, the signature can be used to identify the exact
version of the file, and any changes made to the file will mean that the
signature no longer matches.
As a corollary, the file can be transformed using a user's public key, into text
such that the contents can only be viewed by someone with the corresponding
private key. This is called encryption.
To manipulate keys themselves, a separate utility is provided, called
netpgpkeys(1).
Keyrings are collections of public keys belonging to other users. By using other
means of identification, it is possible to establish the bona fides of other
users. Once trust has been established, the public key of the other user will
be signed. The other user's public key can be added to our keyring. The other
user will add our public key to their keyring.
Keys can be listed, exported (i.e. made available to others), and imported (i.e.
users who have signed our public key).
The
--list-packets command can be used for
debugging purposes.
The following commands are used to sign and verify signatures:
-
-
- --cat
- The signature of the signed file named on the command line
is verified against the contents of the file itself. If the two match,
then the original contents are sent to standard out. If the signature does
not match, no output is generated.
-
-
- --clearsign
- The signature of the file named on the command line is
calculated in the same manner as the
--sign command, but the text is added
to the file such that the text itself is not in binary format, but can be
read by mere mortals.
-
-
- --sign
- The private key is used to digitally sign the files named
on the command line. The file and its attached signature are created with
a “.gpg” extension to the original file
name. The user will be prompted for their pass phrase using
getpass(3).
-
-
- --verify
- For each of the files named on the command line, the
signature of the file is verified, checking the contents against the
user's public signature.
The following commands can be used to encrypt and decrypt files:
-
-
- --decrypt
- Decrypt the file using the user's private key. The pass
phrase will be obtained by prompting the user to type it in, using
getpass(3).
-
-
- --encrypt
- Use the user's public key to encrypt the files named on the
command line.
-
-
- --list-packets
- List all the “packets” in an encrypted or
signed file. Internally, netpgp splits an encrypted or
signed file into separate packets, and this option is used to give a
verbose representation of these packets on standard output.
-
-
- --version
- Print the version information from the
libnetpgp(3)
library.
In addition to one of the preceding commands, a number of qualifiers or options
may be given.
-
-
- --armour,
--armor
- This option, however it is spelled, wraps the signature as
an ASCII-encoded piece of text, for ease of use.
-
-
- --cipher
ciphername
- can be used to specify the symmetric encryption algorithm
(or cipher) which is used when encrypting data. To decrypt this data, the
same cipher will be needed, so care should be taken at encryption time to
make sure that the person who decrypts the data has access to the cipher
used. The default cipher algorithm is the “CAST5”
algorithm.
-
-
- --detach,
--detached
- When signing a file, place the resulting signature in a
separate file from the one being signed.
-
-
- --hash-alg
hash-algorithm
- can be used to specify the hash algorithm (sometimes called
a digest algorithm) which is used with RSA keys when signing text. The
default hash algorithm is the “SHA256” algorithm. At the
present time, “SHA1” may also be used, although it is
recommended that SHA256 be used, due to recent advances in generating
collisions for the SHA1 hashing algorithm.
-
-
- --homedir
home-directory
- Keyrings are normally located, for historical reasons,
within the user's home directory in a subdirectory called
“.gnupg” and this option specifies an
alternative location in which to find that sub-directory.
-
-
- --keyring
keyring
- This option specifies an alternative keyring to be used.
All keyring operations will be relative to this alternative keyring.
-
-
- --output
- specifies a filename to which verified output from a signed
file may be redirected. The default is to send the verified output to
stdout, and this may also be specified using the “-”
value.
-
-
- --results
filename
- specifies a filename to which the results of the operation
should be sent. The default is to send the results to stderr.
-
-
- --ssh-keys
- specifies that the public and private keys should be taken
from the ssh(1) host key files,
usually found in /etc/ssh/ssh_host_rsa_key and
/etc/ssh/ssh_host_rsa_key.pub for the private and public
host keys.
-
-
- --userid
userid
- This option specifies the user identity to be used for all
operations. This identity can either be in the form of the full name, or
as an email address. Care should be exercised with these ways of
specifying the user identity, since the netpgp utility
has no way of verifying that an email address is valid, or that a key
belongs to a certain individual. The trust for a signed key is given by
the other signers of that key. The 16 hexadecimal digit user identity
should be used when specifying user identities —email addresses and
names are provided as aliases.
-
-
- --pass-fd=fd
- This option is intended for the use of external programs
which may like to use the
libnetpgp(3) library
through the netpgp interface, but have their own ways of
retrieving and caching the passphrase for the secret key. In this case,
the netpgp utility will read a line of text from the
file descriptor passed to it in the command line argument, rather than
using its own methods of retrieving the passphrase from the user.
-
-
- --num-tries=attempts
- This option sets the maximum number of attempts to get the
correct passphrase from the user. A value of
unlimited
means that there is no maximum number of
attempts, and the utility will loop endlessly until the correct passphrase
has been entered, or the utility is terminated.
-
-
- --from=signature-valid-from
- This option allows the signer to specify a time as the
starting point for validity of the signature. In this way it is possible
to prevent files from being verified until a specific point in time. The
time can be specified either in
YYYY-MM-DD
format,
or as the number of seconds since the epoch.
-
-
- --duration=signature-valid-to
- This option allows the signer to specify a time as the end
point for validity of the signature. In this way it is possible to prevent
files from being verified after a specific point in time. The time can be
specified either in
YYYY-MM-DD
format, or as the
number of seconds.
-
-
- --verbose
- This option can be used to view information during the
process of the netpgp requests.
-
-
- --coredumps
- in normal processing, if an error occurs, the contents of
memory are saved to disk, and can be read using tools to analyse
behaviour. Unfortunately this can disclose information to people viewing
the core dump, such as secret keys, and passphrases protecting those keys.
In normal operation, netpgp will turn off the ability to
save core dumps on persistent storage, but selecting this option will
allow core dumps to be written to disk. This option should be used wisely,
and any core dumps should be deleted in a secure manner when no longer
needed.
PASS PHRASES
At the present time, the pass phrase cannot be changed by
netpgpkeys(1) once it has
been chosen, and will be used for the life of the key, so a wise choice is
advised. The pass phrase should not be an easily guessable word or phrase, or
related to information that can be gained through “social
engineering” using search engines, or other public information retrieval
methods.
getpass(3) will be used to obtain
the pass phrase from the user if it is needed, such as during signing or
encryption, or key generation, so that any secret information cannot be viewed
by other users using the
ps(1) or
top(1) commands, or by looking over
the shoulder at the screen.
Since the public and private key pair can be used to verify a person's identity,
and since identity theft can have far-reaching consequences, users are
strongly encouraged to enter their pass phrases only when prompted by the
application.
SIGNING AND VERIFICATION
Signing and verification of a file is best viewed using the following example:
% netpgp --sign --userid=agc@netbsd.org a
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks <alistair@hockley-crooks.com>
netpgp passphrase:
% netpgp --verify a.gpg
Good signature for a.gpg made Thu Jan 29 03:06:00 2009
using RSA (Encrypt or Sign) key 1B68DCFCC0596823
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <alistair@hockley-crooks.com>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@alistaircrooks.com>
%
In the example above, a signature is made on a single file called
“
a” using a user identity corresponding to
“agc@netbsd.org” The key located for the user identity is
displayed, and the user is prompted to type in their passphrase. The resulting
file, called “
a.gpg” is placed in the same
directory. The second part of the example shows a verification of the signed
file taking place. The time and user identity of the signatory is displayed,
followed by a fuller description of the public key of the signatory. In both
cases, the exit value from the utility was a successful one.
If a detached signature of a file called “
a” is
requested, the signature would be placed in a file called
“
a.sig”.
To encrypt a file, the user's public key is used. Subsequent decryption of the
file requires that the secret key is known. When decrypting, the key is
displayed, and the passphrase protecting the secret key must be typed in to
access the data in the encrypted file.
% netpgp --encrypt --userid=c0596823 a
% netpgp --decrypt a.gpg
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks <alistair@hockley-crooks.com>
netpgp passphrase:
%
If no file name is provided, the data will be read from standard input, and
displayed on standard output:
% netpgp --encrypt < a | netpgp --decrypt > b
netpgp: default key set to "C0596823"
netpgp: default key set to "C0596823"
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks <alistair@hockley-crooks.com>
netpgp passphrase:
%
This simple (and contrived) example shows that
netpgp commands
can be used together in a pipeline to produce the desired effect.
% netpgp --sign < a | netpgp --cat > b
netpgp: default key set to "C0596823"
netpgp: default key set to "C0596823"
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks <alistair@hockley-crooks.com>
netpgp passphrase:
Good signature for <stdin> made Mon Dec 21 18:25:02 2009
using RSA (Encrypt or Sign) key 1b68dcfcc0596823
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <alistair@hockley-crooks.com>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
%
For operations like signing and encrypting a file at the same time, the best way
is to make use of pipelines:
% netpgp --sign < example | netpgp --encrypt --userid=c0596823 > example.gpg
netpgp: default key set to "C0596823"
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <alistair@hockley-crooks.com>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
netpgp passphrase:
% netpgp --decrypt < example.gpg | netpgp --cat
netpgp: default key set to "C0596823"
netpgp: default key set to "C0596823"
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <alistair@hockley-crooks.com>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
netpgp passphrase:
Good signature for <stdin> made Mon Feb 22 07:21:19 2010
using RSA (Encrypt or Sign) key 1b68dcfcc0596823
pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
uid Alistair Crooks <alistair@hockley-crooks.com>
uid Alistair Crooks <agc@pkgsrc.org>
uid Alistair Crooks <agc@netbsd.org>
uid Alistair Crooks <agc@alistaircrooks.com>
uid Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
...contents of original file...
%
EXIT STATUS
The
netpgp utility will return 0 for success, 1 if the file's
signature does not match what was expected, or 2 if any other error occurs.
SEE ALSO
netpgpkeys(1),
ssh(1),
getpass(3),
libnetpgp(3),
ssl(3),
zlib(3)
STANDARDS
J. Callas, L.
Donnerhacke, H. Finney, D.
Shaw, and R. Thayer, OpenPGP
Message Format, RFC 4880,
November 2007.
HISTORY
The
netpgp command first appeared in
NetBSD
6.0.
AUTHORS
Ben Laurie,
Rachel Willmer, and
overhauled and rewritten by
Alistair Crooks
<
agc@NetBSD.org>. This
manual page was also written by
Alistair Crooks.