diff options
Diffstat (limited to 'doc/gph/c1.sgml')
| -rw-r--r-- | doc/gph/c1.sgml | 627 |
1 files changed, 0 insertions, 627 deletions
diff --git a/doc/gph/c1.sgml b/doc/gph/c1.sgml deleted file mode 100644 index 2839f7c62..000000000 --- a/doc/gph/c1.sgml +++ /dev/null @@ -1,627 +0,0 @@ -<chapter id="intro" xreflabel="1"> -<docinfo> -<date> -$Id$ -</date> -</docinfo> -<title> -Getting Started -</title> - -<para> -&Gnupg; is a tool for secure communication. -This chapter is a quick-start guide that covers the core functionality -of &gnupg;. -This includes keypair creation, exchanging and verifying keys, encrypting -and decrypting documents, and making and verifying signatures. -It does not explain in detail the concepts behind public-key cryptography, -encryption, and digital signatures. -This is covered in Chapter <xref linkend="concepts">. -It also does not explain how to use &gnupg; wisely. -This is covered in Chapters <xref linkend="management"> and -<xref linkend="wise">. -</para> - -<para> -&Gnupg; uses public-key cryptography so that users may communicate securely. -In a public-key system, each user has a public/private keypair. -A user's private key is kept secret; it need never be revealed. -The public key may be given to anyone with whom the user wants to -communicate. -&Gnupg; uses a somewhat more sophisticated scheme in which a user has -a primary keypair and then zero or more additional subordinate keypairs. -The primary and subordinate keypairs are bundled to facilitate key -management and the bundle can often be considered simply as one keypair. -</para> - -<sect1> -<title> -Generating a new keypair -</title> - -<para> -The command-line option <link linkend="gen-key"><option>--gen-key</option></link> -is used to create a new primary keypair. - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --gen-key</userinput> -gpg (GnuPG) 0.9.4; Copyright (C) 1999 Free Software Foundation, Inc. -This program comes with ABSOLUTELY NO WARRANTY. -This is free software, and you are welcome to redistribute it -under certain conditions. See the file COPYING for details. - -Please select what kind of key you want: - (1) DSA and ElGamal (default) - (2) DSA (sign only) - (4) ElGamal (sign and encrypt) -Your selection? -</screen> - -<!-- -REWRITE -From Thomas Zander ([email protected]): -In GPG you can create 3 type of keypairs. A keypair is the combination -of a publ ic key and a private key, see chapter X. A DSA keypair can -only be used to sign a message. A ElGamal subordinate keypair can be -used for encryption as well as s igning, but is not as compatible with -former standards. - -Option 1 creates 2 keypairs; a DSA (signing) and a ElGamal (Encryption). -Option 2 creates a DSA keypair (Signing) -Option 4 creates a ElGemal keypair (Signing & Encryption). - -note: option 3 xxxx - -This doesn't quite work, but I agree the following paragraph is rough. ---> - -&Gnupg; is able to create several different types of keypairs, but a primary -key must be capable of making signatures. -There are therefore only three options. -Option 1 actually creates two keypairs. -A DSA keypair is the primary keypair usable only for making signatures. -An ElGamal subordinate keypair is also created for encryption. -Option 2 is similar but creates only a DSA keypair. -Option 4<footnote><para>Option 3 is to generate an ElGamal keypair that is -not usable for making signatures.</para></footnote> creates a single ElGamal -keypair usable for both making signatures and performing encryption. -In all cases it is possible to later add additional subkeys for encryption -and signing. -For most users the default option is fine. -</para> - -<para> -You must also choose a key size. -The size of a DSA key must be between 512 and 1024 bits, and an ElGamal -key may be of any size. -&Gnupg;, however, requires that keys be no smaller than 768 bits. -Therefore, if Option 1 was chosen and you choose a keysize larger than -1024 bits, the ElGamal key will have the requested size, but the DSA -key will be 1024 bits. - -<screen width="80"> -About to generate a new ELG-E keypair. - minimum keysize is 768 bits - default keysize is 1024 bits - highest suggested keysize is 2048 bits -What keysize do you want? (1024) -</screen> - -The longer the key the more secure it is against brute-force attacks, -but for almost all purposes the default keysize is adequate since -it would be cheaper to circumvent the encryption than try to break it. -Also, encryption and decryption will be slower as the -key size is increased, and a larger keysize may affect signature length. -Once selected, the keysize can never be changed. -</para> - -<para> -Finally, you must choose an expiration date. -If Option 1 was chosen, the expiration date will be used for both the -ElGamal and DSA keypairs. - -<screen width="80"> -Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years -Key is valid for? (0) -</screen> - -For most users a key that does not expire is adequate. -The expiration time should be chosen with care, however, -since although it is possible to change the expiration date after the key -is created, it may be difficult to communicate a change -to users who have your public key. -</para> - -<para> -You must provide a user ID in addition to the key parameters. -The user ID is used to associate the key being created with a real -person. - -<screen width="80"> -You need a User-ID to identify your key; the software constructs the user id -from Real Name, Comment and Email Address in this form: - "Heinrich Heine (Der Dichter) <[email protected]>" - -Real name: -</screen> - -Only one user ID is created when a key is created, but it is possible -to create additional user IDs if you want to use the key in two or -more contexts, ⪚, as an employee at work and a political activist -on the side. -A user ID should be created carefully since it cannot be edited after -it is created. -</para> - -<para> -&Gnupg; needs a passphrase to protect the primary and subordinate -private keys that you keep in your possession. - -<screen width="80"> -You need a Passphrase to protect your private key. - -Enter passphrase: -</screen> - -There is no limit on the length of a passphrase, and it should be -carefully chosen. -From the perspective of security, the passphrase to unlock the private -key is one of the weakest points in &gnupg; (and other public-key -encryption systems as well) since it is the only protection you -have if another individual gets your private key. -Ideally, the passphrase should not use words from a dictionary and -should mix the case of alphabetic characters as well as use -non-alphabetic characters. -A good passphrase is crucial to the secure use of &gnupg;. -</para> - -<sect2 id="revocation"> -<title> -Generating a revocation certificate -</title> - -<para> -After your keypair is created you should immediately generate a revocation -certificate for the primary public key using the option -<link linkend="gen-revoke"><option>--gen-revoke</option></link>. -If you forget your passphrase or if your private key is compromised -or lost, this revocation certificate may be published to notify others -that the public key should no longer be used. -A revoked public key can still be used to verify signatures made -by you in the past, but it cannot be used to encrypt future messages -to you. -It also does not affect your ability to decrypt messages sent to -you in the past if you still do have access to the private key. - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output revoke.asc --gen-revoke mykey</userinput> -[...] -</screen> - -The argument <userinput>mykey</userinput> must be a <emphasis>key -specifier</emphasis>, -either the key ID of your primary keypair or any part of a user ID -that identifies your keypair. -The generated certificate will be left in the file -<parameter>revoke.asc</parameter>. -If the <link linkend="output"><option>--output</option></link> option is -omitted, the result will be placed on standard output. -Since the certificate is short, you may wish to print a hardcopy of -the certificate to store somewhere safe such as your safe deposit box. -The certificate should not be stored where others can access it since -anybody can publish the revocation certificate and render the -corresponding public key useless. -</para> -</sect2> -</sect1> - -<sect1> -<title> -Exchanging keys -</title> - -<para> -To communicate with others you must exchange public keys. -To list the keys on your public keyring use the command-line -option <link linkend="list-keys"><option>--list-keys</option></link>. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --list-keys</userinput> -/users/alice/.gnupg/pubring.gpg ---------------------------------------- -pub 1024D/BB7576AC 1999-06-04 Alice (Judge) <[email protected]> -sub 1024g/78E9A8FA 1999-06-04 -</screen> - -<sect2> -<title> -Exporting a public key -</title> - -<para> -To send your public key to a correspondent you must first export it. -The command-line option <link linkend="export"><option>--export</option></link> -is used to do this. -It takes an additional argument identifying the public key to export. -As with the <option>--gen-revoke</option> option, either the key ID or any part of -the user ID may be used to identify the key to export. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output alice.gpg --export [email protected]</userinput> -</screen> - -<para> -The key is exported in a binary format, but this can be inconvenient -when the key is to be sent though email or published on a web page. -&Gnupg; therefore supports a command-line option -<link linkend="armor"><option>--armor</option></link><footnote> -<para>Many -command-line options that are frequently used can also be set in a -<link linkend="optionsfile">configuration file</link>. -</para> -</footnote> -that that -causes output to be generated in an ASCII-armored format similar to -uuencoded documents. -In general, any output from &gnupg;, ⪚, keys, encrypted documents, and -signatures, can be ASCII-armored by adding the <option>--armor</option> option. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --armor --export [email protected]</userinput> ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: GnuPG v0.9.7 (GNU/Linux) -Comment: For info see http://www.gnupg.org - -[...] ------END PGP PUBLIC KEY BLOCK----- -</screen> -</sect2> - -<sect2> -<title> -Importing a public key -</title> - -<para> -A public key may be added to your public keyring with the -<link linkend="import"><option>--import</option></link> option. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --import blake.gpg</userinput> -gpg: key 9E98BC16: public key imported -gpg: Total number processed: 1 -gpg: imported: 1 -<prompt>alice%</prompt> <userinput>gpg --list-keys</userinput> -/users/alice/.gnupg/pubring.gpg ---------------------------------------- -pub 1024D/BB7576AC 1999-06-04 Alice (Judge) <[email protected]> -sub 1024g/78E9A8FA 1999-06-04 - -pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <[email protected]> -sub 1024g/5C8CBD41 1999-06-04 -</screen> - -<para> -Once a key is imported it should be validated. -&Gnupg; uses a powerful and flexible trust model that does not require -you to personally validate each key you import. -Some keys may need to be personally validated, however. -A key is validated by verifying the key's fingerprint and then signing -the key to certify it as a valid key. -A key's fingerprint can be quickly viewed with the -<link linkend="fingerprint"><option>--fingerprint</option></link> -command-line option, but in order to certify the key you must edit it. - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --edit-key [email protected]</userinput> - -pub 1024D/9E98BC16 created: 1999-06-04 expires: never trust: -/q -sub 1024g/5C8CBD41 created: 1999-06-04 expires: never -(1) Blake (Executioner) <[email protected]> - -<prompt>Command></prompt> <userinput>fpr</userinput> -pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <[email protected]> - Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A08 9E98 BC16 -</screen> - -Key verification is a weak point in public-key cryptography, so you -must be sure that the fingerprint is correct. -The fingerprint displayed should be checked with the key's owner. -This may be done in person or over the phone or through any other means -as long as you can guarantee that you are communicating with the key's -true owner. -Once verified you may sign the key to validate it. -</para> - -<screen width="80"> -<prompt>Command></prompt> <userinput>sign</userinput> - -pub 1024D/9E98BC16 created: 1999-06-04 expires: never trust: -/q - Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A08 9E98 BC16 - - Blake (Executioner) <[email protected]> - -Are you really sure that you want to sign this key -with your key: "Alice (Judge) <[email protected]>" - -Really sign? -</screen> - -<para> -Once signed you can check the key to list the signatures on it and -see the signature that you have added. -Every user ID on the key will have one or more self-signatures as well -as a signature for each user that has validated the key. -</para> - -<screen width="80"> -<prompt>Command></prompt> <userinput>check</userinput> -uid Blake (Executioner) <[email protected]> -sig! 9E98BC16 1999-06-04 [self-signature] -sig! BB7576AC 1999-06-04 Alice (Judge) <[email protected]> -</screen> -</sect2> -</sect1> - -<sect1> -<title> -Encrypting and decrypting documents -</title> - -<para> -To encrypt a document the option -<link linkend="encrypt"><option>--encrypt</option></link> is used. -You must have the public keys of the intended recipients. -The software expects the name of the document to encrypt as input or, if -omitted, on standard input. -The encrypted result is placed on standard output or as specified using -the option <option>--output</option>. -The document is compressed for additional security in addition to -encrypting it. - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --encrypt --recipient [email protected] doc</userinput> -</screen> - -The <link linkend="recipient"><option>--recipient</option></link> option -is used once for each recipient and takes an extra argument specifying -the public key to which the document should be encrypted. -The encrypted document can only be decrypted by someone with a private -key that complements one of the recipients' public keys. -In particular, you cannot decrypt a document encrypted by you unless -you included your own public key in the recipient list. -</para> - -<para> -To decrypt a message the option -<link linkend="decrypt"><option>--decrypt</option></link> is used. -You need the private key to which the message was encrypted. -Similar to the encryption process, the document to decrypt is -input, and the decrypted result is output. -</para> - -<screen width="80"> -<prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.gpg</userinput> - -You need a passphrase to unlock the secret key for -user: "Blake (Executioner) <[email protected]>" -1024-bit ELG-E key, ID 5C8CBD41, created 1999-06-04 (main key ID 9E98BC16) - -Enter passphrase: -</screen> - -<para> -Documents may also be encrypted without using public-key cryptography. -Instead, only a symmetric cipher is used to encrypt the document. -The key used to drive the symmetric cipher is derived from a passphrase -supplied when the document is encrypted, and for good security, it -should not be the same passphrase that you use to protect your private key. -Symmetric encryption is useful for securing documents when the -passphrase does not need to be communicated to others. -A document can be encrypted with a symmetric cipher by using the -<link linkend="symmetric"><option>--symmetric</option></link> option. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --symmetric doc</userinput> -Enter passphrase: -</screen> -</sect1> - -<sect1> -<title> -Making and verifying signatures -</title> - -<para> -A digital signature certifies and timestamps a document. -If the document is subsequently modified in any way, a verification -of the signature will fail. -A digital signature can serve the same purpose as a hand-written signature -with the additional benefit of being tamper-resistant. -The &gnupg; source distribution, for example, is signed so that users can -verify that the source code has not been modified since it was packaged. -</para> - -<para> -Creating and verifying signatures uses the public/private keypair -in an operation different from encryption and decryption. -A signature is created using the private key of the signer. -The signature is verified using the corresponding public key. -A consequence is that it is difficult to deny that you made a digital -signature since that would imply your private key had been compromised. -</para> - -<para> -The command-line option <link linkend="sign"><option>--sign</option></link> is -used to make a digital signature. -The document to sign is input, and the signed document is output. - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output doc.sig --sign doc</userinput> - -You need a passphrase to unlock the private key for -user: "Alice (Judge) <[email protected]>" -1024-bit DSA key, ID BB7576AC, created 1999-06-04 - -Enter passphrase: -</screen> - -The document is compressed before signed, and the output is in binary -format. -</para> - -<para> -Given a signed document, you can either check the signature or -check the signature and recover the original document. -To check the signature use the -<link linkend="verify"><option>--verify</option></link> option. -To verify the signature and extract the document use the -<option>--decrypt</option> -option. -The signed document to verify and recover is input and the recovered -document is output. -</para> - -<screen width="80"> -<prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.sig</userinput> -gpg: Signature made Fri Jun 4 12:02:38 1999 CDT using DSA key ID BB7576AC -gpg: Good signature from "Alice (Judge) <[email protected]>" -</screen> - -<sect2> -<title> -Clearsigned documents -</title> - -<para> -A common use of digital signatures is to sign usenet postings or -email messages. -In such situations it is undesirable to compress the document while -signing it. -The option -<link linkend="clearsign"><option>--clearsign</option></link> -causes the document to be wrapped in an ASCII-armored signature but -otherwise does not modify the document. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --clearsign doc</userinput> - -You need a passphrase to unlock the secret key for -user: "Alice (Judge) <[email protected]>" -1024-bit DSA key, ID BB7576AC, created 1999-06-04 - ------BEGIN PGP SIGNED MESSAGE----- -Hash: SHA1 - -[...] ------BEGIN PGP SIGNATURE----- -Version: GnuPG v0.9.7 (GNU/Linux) -Comment: For info see http://www.gnupg.org - -iEYEARECAAYFAjdYCQoACgkQJ9S6ULt1dqz6IwCfQ7wP6i/i8HhbcOSKF4ELyQB1 -oCoAoOuqpRqEzr4kOkQqHRLE/b8/Rw2k -=y6kj ------END PGP SIGNATURE----- -</screen> -</sect2> - -<sect2> -<title> -Detached signatures -</title> - -<para> -A signed document has limited usefulness. -Other users must recover the original document from the signed -version, and even with clearsigned documents, the signed document -must be edited to recover the original. -Therefore, there is a third method for signing a document that -creates a detached signature. -A detached signature is created using the -<link linkend="detach-sig"><option>--detach-sig</option></link> -option. -</para> - -<screen width="80"> -<prompt>alice%</prompt> <userinput>gpg --output doc.sig --detach-sig doc</userinput> - -You need a passphrase to unlock the secret key for -user: "Alice (Judge) <[email protected]>" -1024-bit DSA key, ID BB7576AC, created 1999-06-04 - -Enter passphrase: -</screen> - -<para> -Both the document and detached signature are needed to verify -the signature. -The <option>--verify</option> option can be to check the -signature. -</para> - -<screen width="80"> -<prompt>blake%</prompt> <userinput>gpg --verify doc.sig doc</userinput> -gpg: Signature made Fri Jun 4 12:38:46 1999 CDT using DSA key ID BB7576AC -gpg: Good signature from "Alice (Judge) <[email protected]>" -</screen> -</sect2> -</sect1> -</chapter> - -<!-- -In the "Getting Started" chapter, it would be interesting to provide -a checklist of assumptions that the reader can consult to determine -whether or not she fits the "most users" profile. Perhaps put this -at the end of the chapter (perhaps w/ forward pointer?). You could -include cross references for each item on the list. For example: - - 23. Your use of public key encryption has property X with attribute Y. - (see Section 3.4.1 for a more detailed discussion of other - attributes of property X) - -What prompted this was wondering, as I read through the generating keypair -section, "under what circumstances would these defaults be inappropriate?" - -The notion of using the same key with different user IDs "as an employee at -work and a political activist on the side" is interesting. Knowing one, -could you be traced to the other? (Are they separate numeric ids, and is -that enough?) (seems someone could just match the public keys) - -It's a very nice touch that you don't cover every single prompt that the -system throws at you, but instead treat them functionally. For example, -I can imagine other books going through the "Comment:" and "Email Address:" -prompts. ---> - -<!-- -"Key verification is a weak point in public-key cryptography ..." -Saying "weak point" makes it sound like a slam on public key stuff. -Although we've talked about weaknesses of the trust model, I'm guessing -the point here is that communication is only secure if you verify the -identity of the key's owner. - -Key verification can be done through any means "as long as you can -guarantee that you are communicating with the key's true owner". -I suspect we'd also like to prevent leaking information that an -interceptor could use to pose as us in a key verification step with -another party. I suppose the notion of bootstrapping may not be widely -appreciated as an analogy. - -I'm almost inclined to want to see a section in the Getting Started -guide called "Why you should read the rest of this book". Failing -that, or perhaps better yet, maybe it would work to have some margin -notes that point to other sections of the book for more information -("a discussion of trust models begins on p. 95"). ---> - |