xref: /netbsd-src/crypto/external/bsd/netpgp/dist/src/netpgpkeys/netpgpkeys.1 (revision cdcd95784de72332cf79fe6a43f9e9ed5caf89d3)
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