NAME
netpgpkeys —
PGP key management
utility
SYNOPSIS
netpgpkeys |
--export-key
[options] file ... |
netpgpkeys |
--find-key
[options] file ... |
netpgpkeys |
--generate-key
[options] file ... |
netpgpkeys |
--import-key
[options] file ... |
netpgpkeys |
--list-keys
[options] file ... |
netpgpkeys |
--list-sigs
[options] file ... |
netpgpkeys |
--trusted-keys
[options] key ... |
netpgpkeys |
[-Vgls]
[-olong-option=value]
file ...
where the long options for all commands are:
[--cipher=cipher-algorithm]
[--coredumps]
[--hash=hash-algorithm]
[--homedir=home-directory]
[--keyring=keyring]
[--ssh-keys]
[--userid=userid]
[--verbose] |
DESCRIPTION
At the present time, the
netpgpkeys utility is still under
development. Whilst the signing and verification, encryption and decryption
parts of
netpgp(1) are
considered mature,
netpgpkeys needs more work. Other key
management utilities should be used in preference to this one.
The
netpgpkeys command is used for all forms of PGP key
management, from generation of new keys to propagation of public keys to key
servers, and import of new public keys from other identities.
The
netpgp(1) utility should be
used for file management and transformation —encryption, decryption,
signing and verification of files.
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.
The
netpgpkeys utility can be used to generate a new key-pair
for a user. As mentioned before, this key is in two parts, the public key
(which is known by other people) and the private key.
The other use of
netpgpkeys is to maintain keyrings. Key and
keyring management commands available are:
--export-key,
--find-key,
--generate-key,
--import-key, and
--list-keys. 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).
Key and keyring management can be done with the following commands:
-
-
- --export-key
- Display the current public key in a format suitable for
export. This can be used to place the keyring on one of the public key
servers, for example.
-
-
- --find-key
- Find the appropriate public key from the current keyring.
If no keyring is provided, the user's public keyring is used.
-
-
- --generate-key
- This command is used to generate a new public and private
key pair. If provided on the command line, the argument will be given to
the key generation routine to be used as the identity of the key. This is
usually the email address and full name, but can be any identification
token. The newly-generated keys are placed in a sub-directory of the
“home directory” which is created at key generation time. At
present, only RSA keys can be generated. The hash algorithm and keysize
can be specified on the command line.
-
-
- --import-key
- Import a public key as retrieved from one of the public key
servers. This is in the form of a file which has previously been retrieved
from elsewhere.
-
-
- --list-keys
- List all the public keys in the current keyring. If no
keyring is provided, the user's public keyring is used.
-
-
- --list-sigs
- List all the public keys in the current keyring, along with
the sub-key signatures which provide the key with trust. If no keyring is
provided, the user's public keyring is used.
-
-
- --trusted-keys
- Prints a list of keys in a more machine-readble format than
is normally used, which can be used as input to other parsing engines. The
output from this command is sent to
stdout
. Normal
key-matching rules apply.
-
-
- --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.
-
-
- --cipher
cipher-algorithm
- Specify the cipher to be used for symmetric encryption. The
default cipher is “CAST5”.
-
-
- --hash
hash-algorithm
- Specify the hash algorithm which is used during fingerprint
calculation. For reference, at the present time,
ssh-keygen(1) uses
“MD5” for its fingerprint values.
-
-
- --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.
-
-
- --numbits
numbits
- specifies the number of bits to be used when generating a
key. The default number of bits is 2048. This is considered the absolute
minimum which should be chosen at the time of writing (2009). Due to
advances in computing power every year, this number should be reviewed,
and increased when it becomes easier to factor 2048 bit numbers.
-
-
- --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 netpgpkeys
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 netpgpkeys interface, but have their own
ways of retrieving and caching the passphrase for the secret key. In this
case, the netpgpkeys 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.
-
-
- --verbose
- This option can be used to view information during the
process of the netpgpkeys requests.
-
-
- --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.
-
-
- --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, netpgpkeys 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.
It is often useful to be able to refer to another user's identity by using their
netpgpkeys “fingerprint”. This can be found in
the output from normal
--list-keys and
--list-sigs commands.
PASS PHRASES
The pass phrase cannot be changed by
netpgpkeys 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.
EXIT STATUS
The
netpgpkeys 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.
EXAMPLES
% netpgpkeys --ssh-keys --sshkeyfile=/etc/ssh/ssh_host_rsa_key.pub --list-keys --hash=md5
1 key
pub 1024/RSA (Encrypt or Sign) fcdd1c608bef4c4b 2008-08-11
Key fingerprint: e935 902d ebf1 76ba fcdd 1c60 8bef 4c4b
uid osx-vm1.crowthorne.alistaircrooks.co.uk (/etc/ssh/ssh_host_rsa_key.pub) <root@osx-vm1.crowthorne.alistaircrooks.co.uk>
% ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub
1024 e9:35:90:2d:eb:f1:76:ba:fc:dd:1c:60:8b:ef:4c:4b /etc/ssh/ssh_host_rsa_key.pub (RSA)
%
The following is an example of RSA key generation:
% netpgpkeys --generate-key
netpgp: default key set to "C0596823"
pub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14
Key fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2
uid RSA 2048-bit key <agc@localhost>
netpgp: generated keys in directory /home/agc/.gnupg/5bc707d1b495aaf2
% ls -al /home/agc/.gnupg/5bc707d1b495aaf2
total 8
drwx------ 2 agc agc 512 Apr 13 18:25 .
drwx------ 6 agc agc 512 Apr 13 18:25 ..
-rw------- 1 agc agc 596 Apr 13 18:25 pubring.gpg
-rw------- 1 agc agc 1284 Apr 13 18:25 secring.gpg
%
% netpgpkeys --list-keys --home ~/.gnupg/5bc707d1b495aaf2
1 key
pub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14
Key fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2
uid RSA 2048-bit key <agc@localhost>
%
SEE ALSO
netpgp(1),
ssh(1),
ssh-keygen(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
netpgpkeys 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.