1*cdcd9578Sagc.\" $NetBSD: netpgpkeys.1,v 1.20 2014/02/17 07:23:18 agc Exp $ 27e613096Sagc.\" 35aae2c74Sagc.\" Copyright (c) 2009, 2010 The NetBSD Foundation, Inc. 47e613096Sagc.\" All rights reserved. 57e613096Sagc.\" 67e613096Sagc.\" This manual page is derived from software contributed to 77e613096Sagc.\" The NetBSD Foundation by Alistair Crooks (agc@NetBSD.org). 87e613096Sagc.\" 97e613096Sagc.\" Redistribution and use in source and binary forms, with or without 107e613096Sagc.\" modification, are permitted provided that the following conditions 117e613096Sagc.\" are met: 127e613096Sagc.\" 1. Redistributions of source code must retain the above copyright 137e613096Sagc.\" notice, this list of conditions and the following disclaimer. 147e613096Sagc.\" 2. Redistributions in binary form must reproduce the above copyright 157e613096Sagc.\" notice, this list of conditions and the following disclaimer in the 167e613096Sagc.\" documentation and/or other materials provided with the distribution. 177e613096Sagc.\" 187e613096Sagc.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 197e613096Sagc.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 207e613096Sagc.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 217e613096Sagc.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 227e613096Sagc.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 237e613096Sagc.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 247e613096Sagc.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 257e613096Sagc.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 267e613096Sagc.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 277e613096Sagc.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 287e613096Sagc.\" POSSIBILITY OF SUCH DAMAGE. 297e613096Sagc.\" 301ce8f15cSagc.Dd February 21, 2012 317e613096Sagc.Dt NETPGPKEYS 1 327e613096Sagc.Os 337e613096Sagc.Sh NAME 347e613096Sagc.Nm netpgpkeys 357e613096Sagc.Nd PGP key management utility 367e613096Sagc.Sh SYNOPSIS 377e613096Sagc.Nm 389e52ba5cSagc.Fl Fl export\-key 397e613096Sagc.Op options 40*cdcd9578Sagc.Ar 417e613096Sagc.Nm 429e52ba5cSagc.Fl Fl find\-key 437e613096Sagc.Op options 44*cdcd9578Sagc.Ar 457e613096Sagc.Nm 469e52ba5cSagc.Fl Fl generate\-key 477e613096Sagc.Op options 48*cdcd9578Sagc.Ar 497e613096Sagc.Nm 509e52ba5cSagc.Fl Fl import\-key 517e613096Sagc.Op options 52*cdcd9578Sagc.Ar 537e613096Sagc.Nm 549e52ba5cSagc.Fl Fl list\-keys 557e613096Sagc.Op options 56*cdcd9578Sagc.Ar 577e613096Sagc.Nm 589e52ba5cSagc.Fl Fl list\-sigs 595aae2c74Sagc.Op options 60*cdcd9578Sagc.Ar 615aae2c74Sagc.Nm 621ce8f15cSagc.Fl Fl trusted\-keys 631ce8f15cSagc.Op options 641ce8f15cSagc.Ar key ... 651ce8f15cSagc.Nm 667e613096Sagc.Fl Fl version 679b987001Sagc.Nm 689b987001Sagc.Op Fl Vgls 699b987001Sagc.Op Fl olong-option Ns = Ns value 70*cdcd9578Sagc.Ar 717e613096Sagc.Pp 729b987001Sagcwhere the long options for all commands are: 737e613096Sagc.Pp 74f8aefef3Sagc.Op Fl Fl cipher Ns = Ns Ar cipher\-algorithm 75f8aefef3Sagc.br 767e613096Sagc.Op Fl Fl coredumps 777e613096Sagc.br 78f8aefef3Sagc.Op Fl Fl hash Ns = Ns Ar hash\-algorithm 7947561e26Sagc.br 80f8aefef3Sagc.Op Fl Fl homedir Ns = Ns Ar home\-directory 817e613096Sagc.br 827e613096Sagc.Op Fl Fl keyring Ns = Ns Ar keyring 837e613096Sagc.br 841e9d36d8Sagc.Op Fl Fl ssh-keys 851e9d36d8Sagc.br 867e613096Sagc.Op Fl Fl userid Ns = Ns Ar userid 877e613096Sagc.br 887e613096Sagc.Op Fl Fl verbose 897e613096Sagc.Sh DESCRIPTION 907e613096SagcAt the present time, the 917e613096Sagc.Nm 927e613096Sagcutility is still under development. 937e613096SagcWhilst the signing and verification, encryption and 947e613096Sagcdecryption parts of 957e613096Sagc.Xr netpgp 1 967e613096Sagcare considered mature, 977e613096Sagc.Nm 987e613096Sagcneeds more work. 997e613096SagcOther key management utilities should be used in preference 1007e613096Sagcto this one. 1017e613096Sagc.Pp 1027e613096SagcThe 1037e613096Sagc.Nm 1047e613096Sagccommand is used for all forms of PGP key management, 1057e613096Sagcfrom generation of new keys to propagation of public 106b0c00dcfSwizkeys to key servers, and import of new public 1077e613096Sagckeys from other identities. 1087e613096Sagc.Pp 1097e613096SagcThe 1107e613096Sagc.Xr netpgp 1 111*cdcd9578Sagcutility should be used for file management and transformation \(emencryption, 1127e613096Sagcdecryption, 1137e613096Sagcsigning and verification of files. 1147e613096Sagc.Pp 1157e613096SagcFor signing and encryption, a unique identity is needed. 1167e613096SagcThis identity is made up of a private and public key. 1177e613096SagcThe public key part is made available and known to everyone. 1187e613096SagcThe private key is kept secret, and known only to the user 1197e613096Sagcwho created the identity. 1207e613096SagcThe secret key is protected with a passphrase. 1217e613096Sagc.Pp 1227e613096SagcIn rough terms, a digital signature 1237e613096Sagcis a digest of a file's contents, 1247e613096Sagcencrypted with the user's private key. 1257e613096SagcSince together, the private and public keys identify the user 1267e613096Sagcuniquely, the signature can be used to identify the exact version 1277e613096Sagcof the file, and any changes made to the file will mean that the 1287e613096Sagcsignature no longer matches. 1297e613096Sagc.Pp 1307e613096SagcAs a corollary, the file can be transformed using a user's public key, 1317e613096Sagcinto text such that the contents can only be viewed by someone 1327e613096Sagcwith the corresponding private key. 1337e613096SagcThis is called encryption. 1347e613096Sagc.Pp 1357e613096SagcThe 1367e613096Sagc.Nm 1377e613096Sagcutility can be used to generate a new key-pair for a user. 1387e613096SagcAs mentioned before, 1397e613096Sagcthis key is in two parts, the public key (which is known 1407e613096Sagcby other people) and the private key. 1417e613096Sagc.Pp 1427e613096SagcThe other use of 1437e613096Sagc.Nm 1447e613096Sagcis to maintain keyrings. 1457e613096SagcKey and keyring management commands available are: 1469e52ba5cSagc.Fl Fl export\-key , 1479e52ba5cSagc.Fl Fl find\-key , 1489e52ba5cSagc.Fl Fl generate\-key , 1499e52ba5cSagc.Fl Fl import\-key , 1507e613096Sagcand 1519e52ba5cSagc.Fl Fl list\-keys . 1527e613096SagcKeyrings are collections of public keys belonging to other users. 1537e613096SagcBy using other means of identification, it is possible to establish 1547e613096Sagcthe bona fides of other users. 1557e613096SagcOnce trust has been established, the public key of the other 1567e613096Sagcuser will be signed. 1577e613096SagcThe other user's public key can be added to our keyring. 1587e613096SagcThe other user will add our public key to their keyring. 1597e613096Sagc.Pp 1607e613096SagcKeys can be listed, exported (i.e. made available to others), 1617e613096Sagcand imported (i.e. users who have signed our public key). 1627e613096Sagc.Pp 1637e613096SagcKey and keyring management can be done with the 1647e613096Sagcfollowing commands: 1657e613096Sagc.Bl -tag -width Ar 1669e52ba5cSagc.It Fl Fl export\-key 1677e613096SagcDisplay the current public key in a format suitable for export. 1687e613096SagcThis can be used to place the keyring on one of the 1697e613096Sagcpublic key servers, for example. 1709e52ba5cSagc.It Fl Fl find\-key 1717e613096SagcFind the appropriate public key from the current keyring. 1727e613096SagcIf no keyring is provided, the user's public keyring is used. 1739e52ba5cSagc.It Fl Fl generate\-key 1747e613096SagcThis command is used to generate a new public and private key pair. 175dbd4d2dbSagcIf provided on the command line, the argument will be given to the 176dbd4d2dbSagckey generation routine to be used as the identity of the key. 177dbd4d2dbSagcThis is usually the email address and full name, but can be 178dbd4d2dbSagcany identification token. 179dbd4d2dbSagcThe newly-generated keys are placed in a sub-directory of the 180dbd4d2dbSagc.Dq home directory 181dbd4d2dbSagcwhich is created at key generation time. 182dbd4d2dbSagcAt present, only RSA keys can be generated. 183dbd4d2dbSagcThe hash algorithm and keysize can be specified on the command 184dbd4d2dbSagcline. 1859e52ba5cSagc.It Fl Fl import\-key 1867e613096SagcImport a public key as retrieved from one of the public key servers. 1877e613096SagcThis is in the form of a file which has previously been 1887e613096Sagcretrieved from elsewhere. 1899e52ba5cSagc.It Fl Fl list\-keys 1907e613096SagcList all the public keys in the current keyring. 1917e613096SagcIf no keyring is provided, the user's public keyring is used. 1929e52ba5cSagc.It Fl Fl list\-sigs 1935aae2c74SagcList all the public keys in the current keyring, along with 1945aae2c74Sagcthe sub-key signatures which provide the key with trust. 1955aae2c74SagcIf no keyring is provided, the user's public keyring is used. 1961ce8f15cSagc.It Fl Fl trusted\-keys 1971ce8f15cSagcPrints a list of keys in a more machine-readble format than is 1981ce8f15cSagcnormally used, which can be used as input to other parsing 1991ce8f15cSagcengines. 2001ce8f15cSagcThe output from this command is sent to 2011ce8f15cSagc.Dv stdout . 2021ce8f15cSagcNormal key-matching rules apply. 2037e613096Sagc.It Fl Fl version 2047e613096SagcPrint the version information from the 2057e613096Sagc.Xr libnetpgp 3 2067e613096Sagclibrary. 2077e613096Sagc.El 2087e613096Sagc.Pp 2097e613096SagcIn addition to one of the preceding commands, a number of qualifiers 2107e613096Sagcor options may be given. 2117e613096Sagc.Bl -tag -width Ar 212f8aefef3Sagc.It Fl Fl cipher Ar cipher\-algorithm 213f8aefef3SagcSpecify the cipher to be used for symmetric encryption. 214*cdcd9578SagcThe default cipher is 215*cdcd9578Sagc.Dq CAST5 . 216f8aefef3Sagc.It Fl Fl hash Ar hash\-algorithm 21747561e26SagcSpecify the hash algorithm which is used during fingerprint calculation. 21847561e26SagcFor reference, at the present time, 21947561e26Sagc.Xr ssh-keygen 1 22047561e26Sagcuses 22147561e26Sagc.Dq MD5 22247561e26Sagcfor its fingerprint values. 223f8aefef3Sagc.It Fl Fl homedir Ar home\-directory 2247e613096SagcKeyrings are normally located, for historical reasons, within 2257e613096Sagcthe user's home directory in a subdirectory called 2267e613096Sagc.Dq Pa .gnupg 2277e613096Sagcand this option specifies an alternative location in which to 2287e613096Sagcfind that sub-directory. 2297e613096Sagc.It Fl Fl keyring Ar keyring 2307e613096SagcThis option specifies an alternative keyring to be used. 2317e613096SagcAll keyring operations will be relative to this alternative keyring. 2327e613096Sagc.It Fl Fl numbits Ar numbits 2337e613096Sagcspecifies the number of bits to be used when generating a key. 2347e613096SagcThe default number of bits is 2048. 2357e613096SagcThis is considered the absolute 2367e613096Sagcminimum which should be chosen at the time of writing (2009). 2377e613096SagcDue to advances in computing power every year, this number should 2387e613096Sagcbe reviewed, and increased when it becomes easier to factor 2048 2397e613096Sagcbit numbers. 2407e613096Sagc.It Fl Fl userid Ar userid 2417e613096SagcThis option specifies the user identity to be used for all operations. 2427e613096SagcThis identity can either be in the form of the full name, or as an 2437e613096Sagcemail address. 2447e613096SagcCare should be exercised with these ways of specifying the user identity, 2457e613096Sagcsince the 2467e613096Sagc.Nm 2477e613096Sagcutility has no way of verifying that an email address is valid, or 2487e613096Sagcthat a key belongs to a certain individual. 2497e613096SagcThe trust for a signed key is given by the other signers of that key. 2507e613096SagcThe 16 hexadecimal digit user identity should be used when specifying 251*cdcd9578Sagcuser identities \(ememail addresses and names are provided as aliases. 252f8aefef3Sagc.It Fl Fl pass\-fd Ns = Ns Ar fd 2537e613096SagcThis option is intended for the use of external programs which may 2547e613096Sagclike to use the 255e34d4852Swiz.Xr libnetpgp 3 2567e613096Sagclibrary through the 2577e613096Sagc.Nm 2587e613096Sagcinterface, but have their own ways of retrieving and caching 2597e613096Sagcthe passphrase for the secret key. 2607e613096SagcIn this case, the 2617e613096Sagc.Nm 2627e613096Sagcutility will read a line of text from the file descriptor 2637e613096Sagcpassed to it in the command line argument, rather than 2647e613096Sagcusing its own methods of retrieving the passphrase from 2657e613096Sagcthe user. 2667e613096Sagc.It Fl Fl verbose 2677e613096SagcThis option can be used to view information during 2687e613096Sagcthe process of the 2697e613096Sagc.Nm 2707e613096Sagcrequests. 2711e9d36d8Sagc.It Fl Fl ssh-keys 2721e9d36d8Sagcspecifies that the public and private keys should be taken 2731e9d36d8Sagcfrom the 2741e9d36d8Sagc.Xr ssh 1 2751e9d36d8Sagchost key files, usually found in 2761e9d36d8Sagc.Pa /etc/ssh/ssh_host_rsa_key 2771e9d36d8Sagcand 2781e9d36d8Sagc.Pa /etc/ssh/ssh_host_rsa_key.pub 2791e9d36d8Sagcfor the private and public host keys. 2807e613096Sagc.It Fl Fl coredumps 2817e613096Sagcin normal processing, 2827e613096Sagcif an error occurs, the contents of memory are saved to disk, and can 2837e613096Sagcbe read using tools to analyse behaviour. 284b0c00dcfSwizUnfortunately this can disclose information to people viewing 2857e613096Sagcthe core dump, such as secret keys, and passphrases protecting 2867e613096Sagcthose keys. 2877e613096SagcIn normal operation, 2887e613096Sagc.Nm 2897e613096Sagcwill turn off the ability to save core dumps on persistent storage, 2907e613096Sagcbut selecting this option will allow core dumps to be written to disk. 2917e613096SagcThis option should be used wisely, and any core dumps should 2927e613096Sagcbe deleted in a secure manner when no longer needed. 2937e613096Sagc.El 2943b87f49fSagc.Pp 2953b87f49fSagcIt is often useful to be able to refer to another user's identity by 2963b87f49fSagcusing their 2973b87f49fSagc.Nm 2983b87f49fSagc.Dq fingerprint . 2993b87f49fSagcThis can be found in the output from normal 3009e52ba5cSagc.Fl Fl list\-keys 3013b87f49fSagcand 3029e52ba5cSagc.Fl Fl list\-sigs 3033b87f49fSagccommands. 3047e613096Sagc.Sh PASS PHRASES 3057e613096SagcThe pass phrase cannot be changed by 3067e613096Sagc.Nm 3077e613096Sagconce it has been chosen, and will 3087e613096Sagcbe used for the life of the key, so a wise choice is advised. 3097e613096SagcThe pass phrase should not be an easily guessable word or phrase, 3107e613096Sagcor related to information that can be gained through 3117e613096Sagc.Dq social engineering 3127e613096Sagcusing search engines, or other public information retrieval methods. 3137e613096Sagc.Pp 3147e613096Sagc.Xr getpass 3 3157e613096Sagcwill be used to obtain the pass phrase from the user if it is 3167e613096Sagcneeded, 3177e613096Sagcsuch as during signing or encryption, or key generation, 3187e613096Sagcso that any secret information cannot be viewed by other users 3197e613096Sagcusing the 3207e613096Sagc.Xr ps 1 3217e613096Sagcor 3227e613096Sagc.Xr top 1 3237e613096Sagccommands, or by looking over the shoulder at the screen. 3247e613096Sagc.Pp 3257e613096SagcSince the public and private key pair can be used to verify 3267e613096Sagca person's identity, and since identity theft can have 3277e613096Sagcfar-reaching consequences, users are strongly encouraged to 3287e613096Sagcenter their pass phrases only when prompted by the application. 329c0597ae8Sjoerg.Sh EXIT STATUS 3307e613096SagcThe 3317e613096Sagc.Nm 3327e613096Sagcutility will return 0 for success, 3337e613096Sagc1 if the file's signature does not match what was expected, 3347e613096Sagcor 2 if any other error occurs. 3355543ce71Swiz.Sh EXAMPLES 336600b302bSagc.Bd -literal 3375cee6a1fSwiz% netpgpkeys --ssh-keys --sshkeyfile=/etc/ssh/ssh_host_rsa_key.pub --list-keys --hash=md5 338600b302bSagc1 key 33947561e26Sagcpub 1024/RSA (Encrypt or Sign) fcdd1c608bef4c4b 2008-08-11 34047561e26SagcKey fingerprint: e935 902d ebf1 76ba fcdd 1c60 8bef 4c4b 34147561e26Sagcuid osx-vm1.crowthorne.alistaircrooks.co.uk (/etc/ssh/ssh_host_rsa_key.pub) <root@osx-vm1.crowthorne.alistaircrooks.co.uk> 34247561e26Sagc 34347561e26Sagc% ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub 34447561e26Sagc1024 e9:35:90:2d:eb:f1:76:ba:fc:dd:1c:60:8b:ef:4c:4b /etc/ssh/ssh_host_rsa_key.pub (RSA) 345600b302bSagc% 346600b302bSagc.Ed 347dbd4d2dbSagc.Pp 348dbd4d2dbSagcThe following is an example of RSA key generation: 349dbd4d2dbSagc.Bd -literal 3509e52ba5cSagc% netpgpkeys --generate\-key 351dbd4d2dbSagcnetpgp: default key set to "C0596823" 352dbd4d2dbSagcpub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14 353dbd4d2dbSagcKey fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2 354dbd4d2dbSagcuid RSA 2048-bit key \*[Lt]agc@localhost\*[Gt] 355dbd4d2dbSagcnetpgp: generated keys in directory /home/agc/.gnupg/5bc707d1b495aaf2 356dbd4d2dbSagc% ls -al /home/agc/.gnupg/5bc707d1b495aaf2 357dbd4d2dbSagctotal 8 358dbd4d2dbSagcdrwx------ 2 agc agc 512 Apr 13 18:25 . 359dbd4d2dbSagcdrwx------ 6 agc agc 512 Apr 13 18:25 .. 360dbd4d2dbSagc-rw------- 1 agc agc 596 Apr 13 18:25 pubring.gpg 361dbd4d2dbSagc-rw------- 1 agc agc 1284 Apr 13 18:25 secring.gpg 362dbd4d2dbSagc% 363dbd4d2dbSagc% netpgpkeys --list-keys --home ~/.gnupg/5bc707d1b495aaf2 364dbd4d2dbSagc1 key 365dbd4d2dbSagcpub 2048/RSA (Encrypt or Sign) 5bc707d1b495aaf2 2010-04-14 366dbd4d2dbSagcKey fingerprint: 08cb 4867 eeed 454c ce30 610d 5bc7 07d1 b495 aaf2 367dbd4d2dbSagcuid RSA 2048-bit key \*[Lt]agc@localhost\*[Gt] 368dbd4d2dbSagc 369dbd4d2dbSagc% 370dbd4d2dbSagc.Ed 3717e613096Sagc.Sh SEE ALSO 3727e613096Sagc.Xr netpgp 1 , 3731e9d36d8Sagc.Xr ssh 1 , 37447561e26Sagc.Xr ssh-keygen 1 , 3757e613096Sagc.Xr getpass 3 , 3767e613096Sagc.\" .Xr libbz2 3 , 3777e613096Sagc.Xr libnetpgp 3 , 3787e613096Sagc.Xr ssl 3 , 3797e613096Sagc.Xr zlib 3 3807e613096Sagc.Sh STANDARDS 381*cdcd9578Sagc.Rs 382*cdcd9578Sagc.%A J. Callas 383*cdcd9578Sagc.%A L. Donnerhacke 384*cdcd9578Sagc.%A H. Finney 385*cdcd9578Sagc.%A D. Shaw 386*cdcd9578Sagc.%A R. Thayer 387*cdcd9578Sagc.%D November 2007 388*cdcd9578Sagc.%R RFC 4880 389*cdcd9578Sagc.%T OpenPGP Message Format 390*cdcd9578Sagc.Re 3917e613096Sagc.Sh HISTORY 3927e613096SagcThe 3937e613096Sagc.Nm 3947e613096Sagccommand first appeared in 3957e613096Sagc.Nx 6.0 . 3967e613096Sagc.Sh AUTHORS 3977e613096Sagc.An -nosplit 3987e613096Sagc.An Ben Laurie , 3997e613096Sagc.An Rachel Willmer , 4007e613096Sagcand overhauled and rewritten by 401a5684d07Swiz.An Alistair Crooks Aq Mt agc@NetBSD.org . 4027e613096SagcThis manual page was also written by 4037e613096Sagc.An Alistair Crooks . 404