diff options
Diffstat (limited to 'doc/gph/c1.sgml')
| -rw-r--r-- | doc/gph/c1.sgml | 627 |
1 files changed, 627 insertions, 0 deletions
diff --git a/doc/gph/c1.sgml b/doc/gph/c1.sgml new file mode 100644 index 000000000..2839f7c62 --- /dev/null +++ b/doc/gph/c1.sgml @@ -0,0 +1,627 @@ +<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"). +--> + |