1.\" $NetBSD: netpgpkeys.1,v 1.2 2009/06/10 14:38:14 wiz Exp $ 2.\" 3.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This manual page is derived from software contributed to 7.\" The NetBSD Foundation by Alistair Crooks (agc@NetBSD.org). 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 9, 2009 31.Dt NETPGPKEYS 1 32.Os 33.Sh NAME 34.Nm netpgpkeys 35.Nd PGP key management utility 36.Sh SYNOPSIS 37.Nm 38.Fl Fl export-key 39.Op options 40.Ar file ... 41.Nm 42.Fl Fl find-key 43.Op options 44.Ar file ... 45.Nm 46.Fl Fl generate-key 47.Op options 48.Ar file ... 49.Nm 50.Fl Fl import-key 51.Op options 52.Ar file ... 53.Nm 54.Fl Fl list-keys 55.Op options 56.Ar file ... 57.Nm 58.Fl Fl version 59.Pp 60where the options for all commands are: 61.Pp 62.Op Fl Fl coredumps 63.br 64.Op Fl Fl homedir Ns = Ns Ar home-directory 65.br 66.Op Fl Fl keyring Ns = Ns Ar keyring 67.br 68.Op Fl Fl userid Ns = Ns Ar userid 69.br 70.Op Fl Fl verbose 71.Sh DESCRIPTION 72At the present time, the 73.Nm 74utility is still under development. 75Whilst the signing and verification, encryption and 76decryption parts of 77.Xr netpgp 1 78are considered mature, 79.Nm 80needs more work. 81Other key management utilities should be used in preference 82to this one. 83.Pp 84The 85.Nm 86command is used for all forms of PGP key management, 87from generation of new keys to propagation of public 88keys to key servers, and import of new public 89keys from other identities. 90.Pp 91The 92.Xr netpgp 1 93utility should be used for file management and transformation - encryption, 94decryption, 95signing and verification of files. 96.Pp 97For signing and encryption, a unique identity is needed. 98This identity is made up of a private and public key. 99The public key part is made available and known to everyone. 100The private key is kept secret, and known only to the user 101who created the identity. 102The secret key is protected with a passphrase. 103.Pp 104In rough terms, a digital signature 105is a digest of a file's contents, 106encrypted with the user's private key. 107Since together, the private and public keys identify the user 108uniquely, the signature can be used to identify the exact version 109of the file, and any changes made to the file will mean that the 110signature no longer matches. 111.Pp 112As a corollary, the file can be transformed using a user's public key, 113into text such that the contents can only be viewed by someone 114with the corresponding private key. 115This is called encryption. 116.Pp 117The 118.Nm 119utility can be used to generate a new key-pair for a user. 120As mentioned before, 121this key is in two parts, the public key (which is known 122by other people) and the private key. 123.Pp 124The other use of 125.Nm 126is to maintain keyrings. 127Key and keyring management commands available are: 128.Fl Fl export-key , 129.Fl Fl find-key , 130.Fl Fl generate-key , 131.Fl Fl import-key , 132and 133.Fl Fl list-keys . 134Keyrings are collections of public keys belonging to other users. 135By using other means of identification, it is possible to establish 136the bona fides of other users. 137Once trust has been established, the public key of the other 138user will be signed. 139The other user's public key can be added to our keyring. 140The other user will add our public key to their keyring. 141.Pp 142Keys can be listed, exported (i.e. made available to others), 143and imported (i.e. users who have signed our public key). 144.Pp 145Key and keyring management can be done with the 146following commands: 147.Bl -tag -width Ar 148.It Fl Fl export-key 149Display the current public key in a format suitable for export. 150This can be used to place the keyring on one of the 151public key servers, for example. 152.It Fl Fl find-key 153Find the appropriate public key from the current keyring. 154If no keyring is provided, the user's public keyring is used. 155.It Fl Fl generate-key 156This command is used to generate a new public and private key pair. 157The user id is taken from the command line, and the user will be 158prompted to provide a suitable pass phrase. 159.It Fl Fl import-key 160Import a public key as retrieved from one of the public key servers. 161This is in the form of a file which has previously been 162retrieved from elsewhere. 163.It Fl Fl list-keys 164List all the public keys in the current keyring. 165If no keyring is provided, the user's public keyring is used. 166.It Fl Fl version 167Print the version information from the 168.Xr libnetpgp 3 169library. 170.El 171.Pp 172In addition to one of the preceding commands, a number of qualifiers 173or options may be given. 174.Bl -tag -width Ar 175.It Fl Fl homedir Ar home-directory 176Keyrings are normally located, for historical reasons, within 177the user's home directory in a subdirectory called 178.Dq Pa .gnupg 179and this option specifies an alternative location in which to 180find that sub-directory. 181.It Fl Fl keyring Ar keyring 182This option specifies an alternative keyring to be used. 183All keyring operations will be relative to this alternative keyring. 184.It Fl Fl numbits Ar numbits 185specifies the number of bits to be used when generating a key. 186The default number of bits is 2048. 187This is considered the absolute 188minimum which should be chosen at the time of writing (2009). 189Due to advances in computing power every year, this number should 190be reviewed, and increased when it becomes easier to factor 2048 191bit numbers. 192.It Fl Fl userid Ar userid 193This option specifies the user identity to be used for all operations. 194This identity can either be in the form of the full name, or as an 195email address. 196Care should be exercised with these ways of specifying the user identity, 197since the 198.Nm 199utility has no way of verifying that an email address is valid, or 200that a key belongs to a certain individual. 201The trust for a signed key is given by the other signers of that key. 202The 16 hexadecimal digit user identity should be used when specifying 203user identities - email addresses and names are provided as aliases. 204.It Fl Fl pass-fd Ns = Ns Ar fd 205This option is intended for the use of external programs which may 206like to use the 207.Xr netpgp 3 208library through the 209.Nm 210interface, but have their own ways of retrieving and caching 211the passphrase for the secret key. 212In this case, the 213.Nm 214utility will read a line of text from the file descriptor 215passed to it in the command line argument, rather than 216using its own methods of retrieving the passphrase from 217the user. 218.It Fl Fl verbose 219This option can be used to view information during 220the process of the 221.Nm 222requests. 223.It Fl Fl coredumps 224in normal processing, 225if an error occurs, the contents of memory are saved to disk, and can 226be read using tools to analyse behaviour. 227Unfortunately this can disclose information to people viewing 228the core dump, such as secret keys, and passphrases protecting 229those keys. 230In normal operation, 231.Nm 232will turn off the ability to save core dumps on persistent storage, 233but selecting this option will allow core dumps to be written to disk. 234This option should be used wisely, and any core dumps should 235be deleted in a secure manner when no longer needed. 236.El 237.Sh PASS PHRASES 238The pass phrase cannot be changed by 239.Nm 240once it has been chosen, and will 241be used for the life of the key, so a wise choice is advised. 242The pass phrase should not be an easily guessable word or phrase, 243or related to information that can be gained through 244.Dq social engineering 245using search engines, or other public information retrieval methods. 246.Pp 247.Xr getpass 3 248will be used to obtain the pass phrase from the user if it is 249needed, 250such as during signing or encryption, or key generation, 251so that any secret information cannot be viewed by other users 252using the 253.Xr ps 1 254or 255.Xr top 1 256commands, or by looking over the shoulder at the screen. 257.Pp 258Since the public and private key pair can be used to verify 259a person's identity, and since identity theft can have 260far-reaching consequences, users are strongly encouraged to 261enter their pass phrases only when prompted by the application. 262.Sh RETURN VALUES 263The 264.Nm 265utility will return 0 for success, 2661 if the file's signature does not match what was expected, 267or 2 if any other error occurs. 268.Sh SEE ALSO 269.Xr netpgp 1 , 270.Xr getpass 3 , 271.\" .Xr libbz2 3 , 272.Xr libnetpgp 3 , 273.Xr ssl 3 , 274.Xr zlib 3 275.Sh STANDARDS 276The 277.Nm 278utility is designed to conform to IETF RFC 4880. 279.Sh HISTORY 280The 281.Nm 282command first appeared in 283.Nx 6.0 . 284.Sh AUTHORS 285.An -nosplit 286.An Ben Laurie , 287.An Rachel Willmer , 288and overhauled and rewritten by 289.An Alistair Crooks Aq agc@NetBSD.org . 290This manual page was also written by 291.An Alistair Crooks . 292