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