1.\" $NetBSD: netpgpkeys.1,v 1.17 2010/11/04 09:30:33 wiz Exp $ 2.\" 3.\" Copyright (c) 2009, 2010 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 November 4, 2010 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 list\-sigs 59.Op options 60.Ar file ... 61.Nm 62.Fl Fl version 63.Nm 64.Op Fl Vgls 65.Op Fl olong-option Ns = Ns value 66.Ar file ... 67.Pp 68where the long options for all commands are: 69.Pp 70.Op Fl Fl cipher Ns = Ns Ar cipher\-algorithm 71.br 72.Op Fl Fl coredumps 73.br 74.Op Fl Fl hash Ns = Ns Ar hash\-algorithm 75.br 76.Op Fl Fl homedir Ns = Ns Ar home\-directory 77.br 78.Op Fl Fl keyring Ns = Ns Ar keyring 79.br 80.Op Fl Fl ssh-keys 81.br 82.Op Fl Fl userid Ns = Ns Ar userid 83.br 84.Op Fl Fl verbose 85.Sh DESCRIPTION 86At the present time, the 87.Nm 88utility is still under development. 89Whilst the signing and verification, encryption and 90decryption parts of 91.Xr netpgp 1 92are considered mature, 93.Nm 94needs more work. 95Other key management utilities should be used in preference 96to this one. 97.Pp 98The 99.Nm 100command is used for all forms of PGP key management, 101from generation of new keys to propagation of public 102keys to key servers, and import of new public 103keys from other identities. 104.Pp 105The 106.Xr netpgp 1 107utility should be used for file management and transformation - encryption, 108decryption, 109signing and verification of files. 110.Pp 111For signing and encryption, a unique identity is needed. 112This identity is made up of a private and public key. 113The public key part is made available and known to everyone. 114The private key is kept secret, and known only to the user 115who created the identity. 116The secret key is protected with a passphrase. 117.Pp 118In rough terms, a digital signature 119is a digest of a file's contents, 120encrypted with the user's private key. 121Since together, the private and public keys identify the user 122uniquely, the signature can be used to identify the exact version 123of the file, and any changes made to the file will mean that the 124signature no longer matches. 125.Pp 126As a corollary, the file can be transformed using a user's public key, 127into text such that the contents can only be viewed by someone 128with the corresponding private key. 129This is called encryption. 130.Pp 131The 132.Nm 133utility can be used to generate a new key-pair for a user. 134As mentioned before, 135this key is in two parts, the public key (which is known 136by other people) and the private key. 137.Pp 138The other use of 139.Nm 140is to maintain keyrings. 141Key and keyring management commands available are: 142.Fl Fl export\-key , 143.Fl Fl find\-key , 144.Fl Fl generate\-key , 145.Fl Fl import\-key , 146and 147.Fl Fl list\-keys . 148Keyrings are collections of public keys belonging to other users. 149By using other means of identification, it is possible to establish 150the bona fides of other users. 151Once trust has been established, the public key of the other 152user will be signed. 153The other user's public key can be added to our keyring. 154The other user will add our public key to their keyring. 155.Pp 156Keys can be listed, exported (i.e. made available to others), 157and imported (i.e. users who have signed our public key). 158.Pp 159Key and keyring management can be done with the 160following commands: 161.Bl -tag -width Ar 162.It Fl Fl export\-key 163Display the current public key in a format suitable for export. 164This can be used to place the keyring on one of the 165public key servers, for example. 166.It Fl Fl find\-key 167Find the appropriate public key from the current keyring. 168If no keyring is provided, the user's public keyring is used. 169.It Fl Fl generate\-key 170This command is used to generate a new public and private key pair. 171If provided on the command line, the argument will be given to the 172key generation routine to be used as the identity of the key. 173This is usually the email address and full name, but can be 174any identification token. 175The newly-generated keys are placed in a sub-directory of the 176.Dq home directory 177which is created at key generation time. 178At present, only RSA keys can be generated. 179The hash algorithm and keysize can be specified on the command 180line. 181.It Fl Fl import\-key 182Import a public key as retrieved from one of the public key servers. 183This is in the form of a file which has previously been 184retrieved from elsewhere. 185.It Fl Fl list\-keys 186List all the public keys in the current keyring. 187If no keyring is provided, the user's public keyring is used. 188.It Fl Fl list\-sigs 189List all the public keys in the current keyring, along with 190the sub-key signatures which provide the key with trust. 191If no keyring is provided, the user's public keyring is used. 192.It Fl Fl version 193Print the version information from the 194.Xr libnetpgp 3 195library. 196.El 197.Pp 198In addition to one of the preceding commands, a number of qualifiers 199or options may be given. 200.Bl -tag -width Ar 201.It Fl Fl cipher Ar cipher\-algorithm 202Specify the cipher to be used for symmetric encryption. 203The default cipher is "CAST5". 204.It Fl Fl hash Ar hash\-algorithm 205Specify the hash algorithm which is used during fingerprint calculation. 206For reference, at the present time, 207.Xr ssh-keygen 1 208uses 209.Dq MD5 210for its fingerprint values. 211.It Fl Fl homedir Ar home\-directory 212Keyrings are normally located, for historical reasons, within 213the user's home directory in a subdirectory called 214.Dq Pa .gnupg 215and this option specifies an alternative location in which to 216find that sub-directory. 217.It Fl Fl keyring Ar keyring 218This option specifies an alternative keyring to be used. 219All keyring operations will be relative to this alternative keyring. 220.It Fl Fl numbits Ar numbits 221specifies the number of bits to be used when generating a key. 222The default number of bits is 2048. 223This is considered the absolute 224minimum which should be chosen at the time of writing (2009). 225Due to advances in computing power every year, this number should 226be reviewed, and increased when it becomes easier to factor 2048 227bit numbers. 228.It Fl Fl userid Ar userid 229This option specifies the user identity to be used for all operations. 230This identity can either be in the form of the full name, or as an 231email address. 232Care should be exercised with these ways of specifying the user identity, 233since the 234.Nm 235utility has no way of verifying that an email address is valid, or 236that a key belongs to a certain individual. 237The trust for a signed key is given by the other signers of that key. 238The 16 hexadecimal digit user identity should be used when specifying 239user identities - email addresses and names are provided as aliases. 240.It Fl Fl pass\-fd Ns = Ns Ar fd 241This option is intended for the use of external programs which may 242like to use the 243.Xr libnetpgp 3 244library through the 245.Nm 246interface, but have their own ways of retrieving and caching 247the passphrase for the secret key. 248In this case, the 249.Nm 250utility will read a line of text from the file descriptor 251passed to it in the command line argument, rather than 252using its own methods of retrieving the passphrase from 253the user. 254.It Fl Fl verbose 255This option can be used to view information during 256the process of the 257.Nm 258requests. 259.It Fl Fl ssh-keys 260specifies that the public and private keys should be taken 261from the 262.Xr ssh 1 263host key files, usually found in 264.Pa /etc/ssh/ssh_host_rsa_key 265and 266.Pa /etc/ssh/ssh_host_rsa_key.pub 267for the private and public host keys. 268.It Fl Fl coredumps 269in normal processing, 270if an error occurs, the contents of memory are saved to disk, and can 271be read using tools to analyse behaviour. 272Unfortunately this can disclose information to people viewing 273the core dump, such as secret keys, and passphrases protecting 274those keys. 275In normal operation, 276.Nm 277will turn off the ability to save core dumps on persistent storage, 278but selecting this option will allow core dumps to be written to disk. 279This option should be used wisely, and any core dumps should 280be deleted in a secure manner when no longer needed. 281.El 282.Pp 283It is often useful to be able to refer to another user's identity by 284using their 285.Nm 286.Dq fingerprint . 287This can be found in the output from normal 288.Fl Fl list\-keys 289and 290.Fl Fl list\-sigs 291commands. 292.Sh PASS PHRASES 293The pass phrase cannot be changed by 294.Nm 295once it has been chosen, and will 296be used for the life of the key, so a wise choice is advised. 297The pass phrase should not be an easily guessable word or phrase, 298or related to information that can be gained through 299.Dq social engineering 300using search engines, or other public information retrieval methods. 301.Pp 302.Xr getpass 3 303will be used to obtain the pass phrase from the user if it is 304needed, 305such as during signing or encryption, or key generation, 306so that any secret information cannot be viewed by other users 307using the 308.Xr ps 1 309or 310.Xr top 1 311commands, or by looking over the shoulder at the screen. 312.Pp 313Since the public and private key pair can be used to verify 314a person's identity, and since identity theft can have 315far-reaching consequences, users are strongly encouraged to 316enter their pass phrases only when prompted by the application. 317.Sh EXIT STATUS 318The 319.Nm 320utility will return 0 for success, 3211 if the file's signature does not match what was expected, 322or 2 if any other error occurs. 323.Sh EXAMPLES 324.Bd -literal 325% netpgpkeys --ssh-keys --sshkeyfile=/etc/ssh/ssh_host_rsa_key.pub --list-keys --hash=md5 3261 key 327pub 1024/RSA (Encrypt or Sign) fcdd1c608bef4c4b 2008-08-11 328Key fingerprint: e935 902d ebf1 76ba fcdd 1c60 8bef 4c4b 329uid osx-vm1.crowthorne.alistaircrooks.co.uk (/etc/ssh/ssh_host_rsa_key.pub) <root@osx-vm1.crowthorne.alistaircrooks.co.uk> 330 331% ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub 3321024 e9:35:90:2d:eb:f1:76:ba:fc:dd:1c:60:8b:ef:4c:4b /etc/ssh/ssh_host_rsa_key.pub (RSA) 333% 334.Ed 335.Pp 336The following is an example of RSA key generation: 337.Bd -literal 338% netpgpkeys --generate\-key 339netpgp: default key set to "C0596823" 340pub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14 341Key fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2 342uid RSA 2048-bit key \*[Lt]agc@localhost\*[Gt] 343netpgp: generated keys in directory /home/agc/.gnupg/5bc707d1b495aaf2 344% ls -al /home/agc/.gnupg/5bc707d1b495aaf2 345total 8 346drwx------ 2 agc agc 512 Apr 13 18:25 . 347drwx------ 6 agc agc 512 Apr 13 18:25 .. 348-rw------- 1 agc agc 596 Apr 13 18:25 pubring.gpg 349-rw------- 1 agc agc 1284 Apr 13 18:25 secring.gpg 350% 351% netpgpkeys --list-keys --home ~/.gnupg/5bc707d1b495aaf2 3521 key 353pub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14 354Key fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2 355uid RSA 2048-bit key \*[Lt]agc@localhost\*[Gt] 356 357% 358.Ed 359.Sh SEE ALSO 360.Xr netpgp 1 , 361.Xr ssh 1 , 362.Xr ssh-keygen 1 , 363.Xr getpass 3 , 364.\" .Xr libbz2 3 , 365.Xr libnetpgp 3 , 366.Xr ssl 3 , 367.Xr zlib 3 368.Sh STANDARDS 369The 370.Nm 371utility is designed to conform to IETF RFC 4880. 372.Sh HISTORY 373The 374.Nm 375command first appeared in 376.Nx 6.0 . 377.Sh AUTHORS 378.An -nosplit 379.An Ben Laurie , 380.An Rachel Willmer , 381and overhauled and rewritten by 382.An Alistair Crooks Aq agc@NetBSD.org . 383This manual page was also written by 384.An Alistair Crooks . 385