1.\" $NetBSD: netpgp.1,v 1.19 2014/02/17 07:23:18 agc 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 February 16, 2014 31.Dt NETPGP 1 32.Os 33.Sh NAME 34.Nm netpgp 35.Nd signing, verification, encryption, and decryption utility 36.Sh SYNOPSIS 37.Nm 38.Fl Fl encrypt 39.Op Fl Fl output Ns = Ns Ar filename 40.Op options 41.Ar file ... 42.Nm 43.Fl Fl decrypt 44.Op Fl Fl output Ns = Ns Ar filename 45.Op Fl Fl pass\-fd Ns = Ns Ar fd 46.Op Fl Fl num\-tries Ns = Ns Ar attempts 47.Op options 48.Ar file ... 49.Pp 50.Nm 51.Fl Fl sign 52.Op Fl Fl armor 53.Op Fl Fl detach 54.Op Fl Fl hash Ns = Ns Ar algorithm 55.Op Fl Fl output Ns = Ns Ar filename 56.Op Fl Fl pass\-fd Ns = Ns Ar fd 57.Op Fl Fl from Ns = Ns Ar sig-valid-from 58.Op Fl Fl num\-tries Ns = Ns Ar attempts 59.Op Fl Fl duration Ns = Ns Ar sig-valid-duration 60.Op options 61.Ar file ... 62.Nm 63.Fl Fl verify 64.Op options 65.Ar file ... 66.Nm 67.Fl Fl cat 68.Op Fl Fl output Ns = Ns Ar filename 69.Op options 70.Ar file ... 71.Nm 72.Fl Fl clearsign 73.Op Fl Fl output Ns = Ns Ar filename 74.Op Fl Fl pass\-fd Ns = Ns Ar fd 75.Op options 76.Ar file ... 77.Nm 78.Fl Fl list\-packets 79.Op Fl Fl pass\-fd Ns = Ns Ar fd 80.Ar file ... 81.Nm 82.Fl Fl version 83.Nm 84.Op Fl Vdesv 85.Op Fl olong-option Ns = Ns value 86.Ar file ... 87.Pp 88where the long options for all commands are: 89.Pp 90.Op Fl Fl cipher Ns = Ns Ar ciphername 91.br 92.Op Fl Fl coredumps 93.br 94.Op Fl Fl homedir Ns = Ns Ar home\-directory 95.br 96.Op Fl Fl keyring Ns = Ns Ar keyring 97.br 98.Op Fl Fl results Ns = Ns Ar filename 99.br 100.Op Fl Fl ssh\-keys 101.br 102.Op Fl Fl userid Ns = Ns Ar userid 103.br 104.Op Fl Fl verbose 105.Sh DESCRIPTION 106The 107.Nm 108command can digitally sign files and verify that the signatures 109attached to files were signed by a given user identifier. 110.Nm 111can also encrypt files using the public or private keys of 112users and, in the same manner, decrypt files which were encrypted. 113.Pp 114For signing and encryption, a unique identity is needed. 115This identity is made up of a private and public key. 116The public key part is made available and known to everyone. 117The private key is kept secret, and known only to the user 118who created the identity. 119The secret key is protected with a passphrase. 120.Pp 121In rough terms, a digital signature 122is a digest of a file's contents, 123encrypted with the user's private key. 124Since together, the private and public keys identify the user 125uniquely, the signature can be used to identify the exact version 126of the file, and any changes made to the file will mean that the 127signature no longer matches. 128.Pp 129As a corollary, the file can be transformed using a user's public key, 130into text such that the contents can only be viewed by someone 131with the corresponding private key. 132This is called encryption. 133.Pp 134To manipulate keys themselves, a separate utility is provided, called 135.Xr netpgpkeys 1 . 136.Pp 137Keyrings are collections of public keys belonging to other users. 138By using other means of identification, it is possible to establish 139the bona fides of other users. 140Once trust has been established, the public key of the other 141user will be signed. 142The other user's public key can be added to our keyring. 143The other user will add our public key to their keyring. 144.Pp 145Keys can be listed, exported (i.e. made available to others), 146and imported (i.e. users who have signed our public key). 147.Pp 148The 149.Fl Fl list\-packets 150command can be used for debugging purposes. 151.Pp 152The following commands are used to sign and verify signatures: 153.Bl -tag -width Ar 154.It Fl Fl cat 155The signature of the signed file named on the command line 156is verified against the contents of the file itself. 157If the two match, then the original contents 158are sent to standard out. 159If the signature does not match, no output is generated. 160.It Fl Fl clearsign 161The signature of the file named on the command line is calculated 162in the same manner as the 163.Fl Fl sign 164command, but the text is added to the file such that 165the text itself is not in binary format, but can be read by mere mortals. 166.It Fl Fl sign 167The private key is used to digitally sign the files named on the 168command line. 169The file and its attached signature are created with a 170.Dq Pa .gpg 171extension to the original file name. 172The user will be prompted for their pass phrase using 173.Xr getpass 3 . 174.It Fl Fl verify 175For each of the files named on the command line, the signature of the file 176is verified, checking the contents against the user's public signature. 177.El 178.Pp 179The following commands can be used to encrypt and decrypt files: 180.Bl -tag -width Ar 181.It Fl Fl decrypt 182Decrypt the file using the user's private key. 183The pass phrase will be obtained by prompting the user 184to type it in, using 185.Xr getpass 3 . 186.It Fl Fl encrypt 187Use the user's public key to encrypt the files named on the command line. 188.It Fl Fl list\-packets 189List all the 190.Dq packets 191in an encrypted or signed file. 192Internally, 193.Nm 194splits an encrypted or signed file into separate packets, and 195this option is used to give a verbose representation 196of these packets on standard output. 197.It Fl Fl version 198Print the version information from the 199.Xr libnetpgp 3 200library. 201.El 202.Pp 203In addition to one of the preceding commands, a number of qualifiers 204or options may be given. 205.Bl -tag -width Ar 206.It Fl Fl armour , Fl armor 207This option, however it is spelled, wraps the signature as an 208ASCII-encoded piece of text, for ease of use. 209.It Fl Fl cipher Ar ciphername 210can be used to specify the symmetric encryption algorithm (or 211cipher) which is used when encrypting data. 212To decrypt this data, the same cipher will be needed, 213so care should be taken at encryption time to make sure 214that the person who decrypts the data has 215access to the cipher used. 216The default cipher algorithm is the 217.Dq CAST5 218algorithm. 219.It Fl Fl detached 220When signing a file, place the resulting signature in a separate 221file from the one being signed. 222.It Fl Fl hash-alg Ar hash-algorithm 223can be used to specify the hash algorithm (sometimes called 224a digest algorithm) which is used with RSA keys when signing 225text. 226The default hash algorithm is the 227.Dq SHA256 228algorithm. 229At the present time, 230.Dq SHA1 231may also be used, although it is recommended that 232SHA256 be used, due to recent advances in generating 233collisions for the SHA1 hashing algorithm. 234.It Fl Fl homedir Ar home\-directory 235Keyrings are normally located, for historical reasons, within 236the user's home directory in a subdirectory called 237.Dq Pa .gnupg 238and this option specifies an alternative location in which to 239find that sub-directory. 240.It Fl Fl keyring Ar keyring 241This option specifies an alternative keyring to be used. 242All keyring operations will be relative to this alternative keyring. 243.It Fl Fl output 244specifies a filename to which verified output from a signed file 245may be redirected. 246The default is to send the verified output to stdout, 247and this may also be specified using the 248.Dq - 249value. 250.It Fl Fl results Ar filename 251specifies a filename to which the results of the operation 252should be sent. 253The default is to send the results to stderr. 254.It Fl Fl ssh\-keys 255specifies that the public and private keys should be taken 256from the 257.Xr ssh 1 258host key files, usually found in 259.Pa /etc/ssh/ssh_host_rsa_key 260and 261.Pa /etc/ssh/ssh_host_rsa_key.pub 262for the private and public host keys. 263.It Fl Fl userid Ar userid 264This option specifies the user identity to be used for all operations. 265This identity can either be in the form of the full name, or as an 266email address. 267Care should be exercised with these ways of specifying the user identity, 268since the 269.Nm 270utility has no way of verifying that an email address is valid, or 271that a key belongs to a certain individual. 272The trust for a signed key is given by the other signers of that key. 273The 16 hexadecimal digit user identity should be used when specifying 274user identities \(ememail addresses and names are provided as aliases. 275.It Fl Fl pass\-fd Ns = Ns Ar fd 276This option is intended for the use of external programs which may 277like to use the 278.Xr libnetpgp 3 279library through the 280.Nm 281interface, but have their own ways of retrieving and caching 282the passphrase for the secret key. 283In this case, the 284.Nm 285utility will read a line of text from the file descriptor 286passed to it in the command line argument, rather than 287using its own methods of retrieving the passphrase from 288the user. 289.It Fl Fl num-tries Ns = Ns Ar attempts 290This option sets the maximum number of attempts to get the 291correct passphrase from the user. 292A value of 293.Dv unlimited 294means that there is no maximum number of attempts, and the 295utility will loop endlessly until the correct passphrase has been 296entered, or the utility is terminated. 297.It Fl Fl from Ns = Ns Ar signature-valid-from 298This option allows the signer to specify a time as the 299starting point for validity of the signature. 300In this way it is possible to prevent files from being verified 301until a specific point in time. 302The time can be specified either in 303.Dv YYYY-MM-DD 304format, or as the number of seconds since the epoch. 305.It Fl Fl duration Ns = Ns Ar signature-valid-to 306This option allows the signer to specify a time as the 307end point for validity of the signature. 308In this way it is possible to prevent files from being verified 309after a specific point in time. 310The time can be specified either 311in 312.Dv YYYY-MM-DD 313format, or as the number of seconds. 314.It Fl Fl verbose 315This option can be used to view information during 316the process of the 317.Nm 318requests. 319.It Fl Fl coredumps 320in normal processing, 321if an error occurs, the contents of memory are saved to disk, and can 322be read using tools to analyse behaviour. 323Unfortunately this can disclose information to people viewing 324the core dump, such as secret keys, and passphrases protecting 325those keys. 326In normal operation, 327.Nm 328will turn off the ability to save core dumps on persistent storage, 329but selecting this option will allow core dumps to be written to disk. 330This option should be used wisely, and any core dumps should 331be deleted in a secure manner when no longer needed. 332.El 333.Sh PASS PHRASES 334At the present time, the pass phrase cannot be changed by 335.Xr netpgpkeys 1 336once it has been chosen, and will 337be used for the life of the key, so a wise choice is advised. 338The pass phrase should not be an easily guessable word or phrase, 339or related to information that can be gained through 340.Dq social engineering 341using search engines, or other public information retrieval methods. 342.Pp 343.Xr getpass 3 344will be used to obtain the pass phrase from the user if it is 345needed, 346such as during signing or encryption, or key generation, 347so that any secret information cannot be viewed by other users 348using the 349.Xr ps 1 350or 351.Xr top 1 352commands, or by looking over the shoulder at the screen. 353.Pp 354Since the public and private key pair can be used to verify 355a person's identity, and since identity theft can have 356far-reaching consequences, users are strongly encouraged to 357enter their pass phrases only when prompted by the application. 358.Sh SIGNING AND VERIFICATION 359Signing and verification of a file is best viewed using the following example: 360.Bd -literal 361% netpgp --sign --userid=agc@netbsd.org a 362pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 363Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 364uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 365uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 366uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 367uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 368netpgp passphrase: 369% netpgp --verify a.gpg 370Good signature for a.gpg made Thu Jan 29 03:06:00 2009 371using RSA (Encrypt or Sign) key 1B68DCFCC0596823 372pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 373Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 374uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 375uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 376uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 377uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 378% 379.Ed 380.Pp 381In the example above, a signature is made on a single file called 382.Dq Pa a 383using a user identity corresponding to 384.Dq agc@netbsd.org 385The key located for the user identity is displayed, and 386the user is prompted to type in their passphrase. 387The resulting file, called 388.Dq Pa a.gpg 389is placed in the same directory. 390The second part of the example shows a verification of the signed file 391taking place. 392The time and user identity of the signatory is displayed, followed 393by a fuller description of the public key of the signatory. 394In both cases, the exit value from the utility was a successful one. 395.Pp 396If a detached signature of a file called 397.Dq Pa a 398is requested, the signature would be placed 399in a file called 400.Dq Pa a.sig . 401.Pp 402To encrypt a file, the user's public key is used. 403Subsequent decryption of the file requires that the secret 404key is known. 405When decrypting, the key is displayed, 406and the passphrase protecting 407the secret key must be typed in to access the data in the encrypted file. 408.Bd -literal 409% netpgp --encrypt --userid=c0596823 a 410% netpgp --decrypt a.gpg 411pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 412Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 413uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 414uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 415uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 416uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 417netpgp passphrase: 418% 419.Ed 420.Pp 421If no file name is provided, the data will be read from standard input, 422and displayed on standard output: 423.Bd -literal 424% netpgp --encrypt \*[Lt] a | netpgp --decrypt \*[Gt] b 425netpgp: default key set to "C0596823" 426netpgp: default key set to "C0596823" 427pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 428Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 429uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 430uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 431uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 432uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 433netpgp passphrase: 434% 435.Ed 436.Pp 437This simple (and contrived) example shows that 438.Nm 439commands can be used together in a pipeline to produce the desired effect. 440.Bd -literal 441% netpgp --sign \*[Lt] a | netpgp --cat \*[Gt] b 442netpgp: default key set to "C0596823" 443netpgp: default key set to "C0596823" 444pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 445Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 446uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 447uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 448uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 449uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 450netpgp passphrase: 451Good signature for \*[Lt]stdin\*[Gt] made Mon Dec 21 18:25:02 2009 452using RSA (Encrypt or Sign) key 1b68dcfcc0596823 453pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 454Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 455uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 456uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 457uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 458uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 459uid Alistair Crooks (Yahoo!) \*[Lt]agcrooks@yahoo-inc.com\*[Gt] 460% 461.Ed 462.Pp 463For operations like signing and encrypting a file at the same time, 464the best way is to make use of pipelines: 465.Bd -literal 466% netpgp --sign \*[Lt] example | netpgp --encrypt --userid=c0596823 \*[Gt] example.gpg 467netpgp: default key set to "C0596823" 468pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 469Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 470uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 471uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 472uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 473uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 474uid Alistair Crooks (Yahoo!) \*[Lt]agcrooks@yahoo-inc.com\*[Gt] 475netpgp passphrase: 476% netpgp --decrypt \*[Lt] example.gpg | netpgp --cat 477netpgp: default key set to "C0596823" 478netpgp: default key set to "C0596823" 479pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 480Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 481uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 482uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 483uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 484uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 485uid Alistair Crooks (Yahoo!) \*[Lt]agcrooks@yahoo-inc.com\*[Gt] 486netpgp passphrase: 487Good signature for \*[Lt]stdin\*[Gt] made Mon Feb 22 07:21:19 2010 488using RSA (Encrypt or Sign) key 1b68dcfcc0596823 489pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12 490Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823 491uid Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt] 492uid Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt] 493uid Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt] 494uid Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt] 495uid Alistair Crooks (Yahoo!) \*[Lt]agcrooks@yahoo-inc.com\*[Gt] 496\&...contents of original file... 497% 498.Ed 499.Sh EXIT STATUS 500The 501.Nm 502utility will return 0 for success, 5031 if the file's signature does not match what was expected, 504or 2 if any other error occurs. 505.Sh SEE ALSO 506.Xr netpgpkeys 1 , 507.Xr ssh 1 , 508.Xr getpass 3 , 509.\" .Xr libbz2 3 , 510.Xr libnetpgp 3 , 511.Xr ssl 3 , 512.Xr zlib 3 513.Sh STANDARDS 514.Rs 515.%A J. Callas 516.%A L. Donnerhacke 517.%A H. Finney 518.%A D. Shaw 519.%A R. Thayer 520.%D November 2007 521.%R RFC 4880 522.%T OpenPGP Message Format 523.Re 524.Sh HISTORY 525The 526.Nm 527command first appeared in 528.Nx 6.0 . 529.Sh AUTHORS 530.An -nosplit 531.An Ben Laurie , 532.An Rachel Willmer , 533and overhauled and rewritten by 534.An Alistair Crooks Aq Mt agc@NetBSD.org . 535This manual page was also written by 536.An Alistair Crooks . 537