NETPGPKEYS(1)           NetBSD General Commands Manual           NETPGPKEYS(1)

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 --version
     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 transforma-
     tion --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 pro-
     tected 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 identi-
     fication, 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 algo-
                   rithm 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 previ-
                   ously 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 pars-
                   ing 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 loca-
                   tion 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 consid-
                   ered 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 exer-
                   cised 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 cer-
                   tain 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 identi-
                   ties --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 argu-
                   ment, 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 infor-
                   mation 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 signa-
     ture 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.

NetBSD 7.0                     February 21, 2012                    NetBSD 7.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen