Annotation of htdocs/developers/pgp.xml, Revision 1.15
1.1 jschauma 1: <?xml version="1.0"?>
2: <!DOCTYPE webpage
1.8 hrs 3: PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
4: "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
1.1 jschauma 5:
1.9 heinz 6: <webpage id="developers-pgp">
1.1 jschauma 7: <config param="desc" value="PGP Key Management Guide for NetBSD developers"/>
1.15 ! ryoon 8: <config param="cvstag" value="$NetBSD: pgp.xml,v 1.14 2010/11/21 16:45:26 kano Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2010/11/21 16:45:26 $"/>
1.1 jschauma 10: <head>
11: <title>PGP Key Management Guide for NetBSD developers</title>
12: </head>
13:
14: <sect1 id="pgp-management">
15:
16: <sect2 id="scope">
17: <title>Scope</title>
18: <para>
19: The topic of this guide is PGP key management. It assumes that
20: you understand the concept of asymmetric cryptography (using
21: a private and a public key), that you know how to create and
22: use PGP keys, and that you know how to integrate PGP support
23: into your favourite e-mail client. It assumes that you understand
24: the concept of signing, and encrypting, a digital message.
25: </para>
26: <para>
27: More information about using PGP keys can be found at:
28: </para>
29: <itemizedlist>
1.5 jschauma 30: <listitem>
1.14 kano 31: <ulink url="http://www.gnupg.org/faq/GnuPG-FAQ.html"/>
1.5 jschauma 32: </listitem>
33: <listitem>
1.14 kano 34: <ulink url="http://www.gnupg.org/documentation/howtos.en.html"/>
1.5 jschauma 35: </listitem>
36: <listitem>
37: <ulink url="http://www.gnupg.org/gph/en/manual.html"/>
38: </listitem>
1.1 jschauma 39: </itemizedlist>
40: </sect2>
41:
42: <sect2 id="audience">
43: <title>Intended Audience</title>
44: <para>
45: NetBSD developers and applicants for NetBSD Project membership.
46: </para>
47: </sect2>
48:
49: <sect2 id="rationale">
50: <title>Rationale: Why we need PGP enabled developers</title>
51: <para>
52: The NetBSD project needs to be able to establish the authenticity of
53: requests and other communications originating from project members around
54: the world. The simplest way to do this is to establish a PGP web-of-trust
55: amongst its members.
56: </para>
57: <para>
58: Typical examples activities requiring this web of trust are:
59: </para>
60: <itemizedlist>
61: <listitem>
62: <para>
63: the ability to sign messages to admins, e.g. for mails
64: pertaining to the change of account details
65: </para>
66: </listitem>
67: <listitem>
68: <para>
69: the ability to sign someone else's key (to build a project
70: wide web-of-trust, see below), and to be able to sign an applicants
71: key
72: </para>
73: </listitem>
74: <listitem>
75: <para>
76: the ability to receive encrypted e-mails, e.g. in communications
77: about security issues not to be disclosed to the outside
78: </para>
79: </listitem>
80: </itemizedlist>
81: <para>
82: The most popular program for creating, managing, and using PGP keys is
1.5 jschauma 83: probably gpg (GNU Privacy Guard), readily available as
1.10 rpaulo 84: <filename role="pkg">security/gnupg</filename> from pkgsrc.
85: Examples given in this document
1.5 jschauma 86: use gnupg (rather than the alternative, pgp).
1.1 jschauma 87: </para>
88: </sect2>
89:
90: <sect2 id="approach">
91: <title>Web-of-trust approach</title>
92: <para>
93: Everyone can create an arbitrary number of keys: any key with any identity;
94: it may not be her/his real identity. He or she may upload these keys to any
95: key server. This implies that a person could pretend to be the key owner
96: (who is given as the user-id) although she/he isn't.
97: </para>
98: <para>
99: There are two fundamentally different concepts to address the problem of
100: how one can establish that a certain PGP key belongs to a specific person:
101: </para>
102: <itemizedlist>
103: <listitem>
104: <para>
105: Certification Authority (CA), usually under control of a government,
106: verifies the identity of a person and testifies that a certain key
107: belongs to a person (or organization). This service usually costs money.
108: </para>
109: </listitem>
110: <listitem>
111: <para>
112: Web-of-trust: whenever two PGP key holders meet, they verify
113: their identity and sign each other's keys (see below about the
114: significance of signing someone's key). Although not controlled
115: by a government, if a key is signed by many persons you know you
1.13 snj 116: can be pretty sure about its authenticity. Crucial to the
1.1 jschauma 117: web-of-trust approach is that many key holders participate.
118: </para>
119: </listitem>
120: </itemizedlist>
121: <para>
122: In a web-of-trust approach, if A has signed the key of B and B has signed
1.7 jschauma 123: the Key of C, then A can be confident about the authenticity of C. For
124: this to work, A has to trust B not to make irresponsible signatures.
125: The path from A to C is referred to as "chain-of-trust".
1.1 jschauma 126: </para>
127: </sect2>
128:
129: <sect2 id="significance">
130: <title>What is the significance of signing someone's key?</title>
131: <para>
132: Often one encounters statements like: "I do not approve of Foo's actions,
133: therefore I will not sign his key." or "If Foo signs his threat mail with
1.5 jschauma 134: a key that carries my signature that means that I will be held legally
135: liable." These and similar statements are false.
1.1 jschauma 136: </para>
137: <para>
1.2 jschauma 138: What it means when you sign someone's PGP key with your signature is:
1.1 jschauma 139: "I have verified that PGP key x belongs to person y." Not more, not less.
140: </para>
141: <para>
142: There's no reason not to sign someone's key, provided you have carefully
143: verified his identity.
144: </para>
145: </sect2>
146:
147: <sect2 id="keygen-recommendations">
148: <title>Recommendations for key generation</title>
149: <para>
150: First of all, to ensure maximum security over time, it is advisable to
151: choose long key lengths. The key size limitation of a maximum of 1024 bits
152: in the current DSA standard may limit the security of DSA. For maximum
153: security it is therefore advisable to use 2048-bit RSA keys for both,
1.15 ! ryoon 154: encrypting and signing.
1.1 jschauma 155: keys).
156: </para>
157: <note><title/>
158: <programlisting>
159: % gpg --gen-key
1.15 ! ryoon 160: gpg (GnuPG) 1.4.12; Copyright (C) 2012 Free Software Foundation, Inc.
! 161: This is free software: you are free to change and redistribute it.
! 162: There is NO WARRANTY, to the extent permitted by law.
! 163:
1.1 jschauma 164: Please select what kind of key you want:
1.15 ! ryoon 165: (1) RSA and RSA (default)
! 166: (2) DSA and Elgamal
! 167: (3) DSA (sign only)
! 168: (4) RSA (sign only)
! 169: Your selection? 1
! 170: RSA keys may be between 1024 and 4096 bits long.
! 171: What keysize do you want? (2048) 2048
! 172: Requested keysize is 2048 bits
1.1 jschauma 173: Please specify how long the key should be valid.
174: 0 = key does not expire
175: <n> = key expires in n days
176: <n>w = key expires in n weeks
177: <n>m = key expires in n months
178: <n>y = key expires in n years
179: Key is valid for? (0) 0
180: Key does not expire at all
1.15 ! ryoon 181: Is this correct? (y/N) y
! 182:
! 183: You need a user ID to identify your key; the software constructs the user ID
! 184: from the Real Name, Comment and Email Address in this form:
1.1 jschauma 185: "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
186:
1.15 ! ryoon 187: Real name: Joe Doe
1.1 jschauma 188: Email address: joe@doe.org
1.15 ! ryoon 189: Comment: NetBSD
! 190: You selected this USER-ID:
! 191: "Joe Doe (NetBSD) <joe@doe.org>"
! 192:
! 193: Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
! 194: You need a Passphrase to protect your secret key.
1.1 jschauma 195: Enter passphrase:
196: Repeat passphrase:
1.15 ! ryoon 197:
! 198: gpg: /home/joe/.gnupg/trustdb.gpg: trustdb created
! 199: gpg: key 7CEBFEBC marked as ultimately trusted
1.1 jschauma 200: public and secret key created and signed.
201:
202: gpg: checking the trustdb
1.15 ! ryoon 203: gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
! 204: gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
! 205: pub 2048R/7CEBFEBC 2012-05-20
! 206: Key fingerprint = 67A7 FC80 8140 5F9B CE96 E19D E5B7 BF68 7CEB FEBC
! 207: uid Joe Doe (NetBSD) <joe@doe.org>
! 208: sub 2048R/6F64A1B1 2012-05-20
1.1 jschauma 209: </programlisting>
210: </note>
211: <para>
212: ... and you're done!
213: </para>
214: <para>
1.5 jschauma 215: Another question is whether a key should initially have an expiration
216: date, or not. As the expiration date can set or changed later on (unlike
217: PGP 2.x keys), this question is mostly a matter of personal choice. A
218: good reason to put an expiration date on a key is that people sometimes
219: forget their passphrase or lose the secret key. With an expiration date,
220: there is a drop-dead date after which the key is not going to be used.
1.1 jschauma 221: </para>
222: <para>
1.11 heinz 223: After key creation, uids for all e-mail addresses you use should be added
1.1 jschauma 224: to your key. Don't forget to add a @NetBSD.org uid! Consider making your
225: @NetBSD.org uid the primary uid.
226: </para>
227: </sect2>
228:
229: <sect2 id="manage-recommendations">
230: <title>Recommendations for managing your private PGP key(s)</title>
231: <para>
232: As soon as you have created a PGP key pair, you may want to create a
233: blank revocation certificate, so that you will be able to revoke your
234: key in the event that it is compromised, or that you lose the private
1.2 jschauma 235: key (disk crash) or forget the passphrase. Be sure to store the revocation
1.1 jschauma 236: certificate in a safe place, preferably separate from the private key.
237: Printing it out and keeping it in a safe is a good idea.
238: </para>
239: <para>
240: Always keep your private PGP keys on a machine to which only you have
241: administrative access, or better yet, store your private key only on
242: a removable USB stick (the tiniest ones sold are sufficient). Remove
243: the USB stick whenever you are not using the key.
244: </para>
245: <para>
246: Protect your private PGP keys with strong passphrases.
247: </para>
248: <para>
249: Regularly backup your keys.
250: </para>
251: </sect2>
252:
253: <sect2 id="distribution-recommendations">
254: <title>Recommendations for the distribution of your public PGP key</title>
255: <para>
256: In a public/private key model, it is essential that the private key is
257: guarded securely, while the public key is distributed as widely as possible.
258: Anyone wanting to send you an encrypted message, or wanting to verify your
1.3 jschauma 259: signature needs your public key.
1.1 jschauma 260: </para>
261: <para>
262: Therefore you should:
263: </para>
264: <itemizedlist>
1.5 jschauma 265: <listitem>
266: <para>submit your public key to public key servers</para>
267: </listitem>
268: <listitem>
269: <para>commit your key to localsrc/security/publickeys/developers</para>
270: </listitem>
1.1 jschauma 271: </itemizedlist>
272: <para>
273: The canonical key servers these days are www.pgp.net, pgp.mit.edu, and
1.5 jschauma 274: www.keyserver.net. The default keyserver can be specified in
275: ~/.gnupg/gpg.conf with:
1.1 jschauma 276: </para>
277: <note><title/>
1.5 jschauma 278: keyserver pgp.mit.edu
1.1 jschauma 279: </note>
280: <para>
281: localsrc/security/publickeys/developers/README describes how to commit your
282: public PGP key to NetBSD's local source repository. Having the public PGP
283: keys of all developers in this directory makes it very easy to import all
284: keys (with all signatures) with just one command.
285: </para>
286: </sect2>
287:
288: <sect2 id="sign-recommendations">
289: <title>Recommended procedure for signing keys</title>
290: <para>
291: <emphasis type="strong">Important:</emphasis> Do not sign a key without
292: checking the components of the key and without checking the authenticity.
293: Make sure the key belongs to the person who pretends to be the key owner.
294: Keep in mind that not you, but others will rely on your signature!
295: </para>
296: <para>
297: Here is the recommended step-by-step procedure:
298: </para>
299: <orderedlist>
1.12 mishka 300: <listitem id="signsteps-bcard-prep">
1.1 jschauma 301: <para>
1.5 jschauma 302: Prepare a "business card" type of document with the following
303: information on your PGP key:
1.1 jschauma 304: </para>
305: <itemizedlist>
306: <listitem><para>Key length</para></listitem>
307: <listitem><para>Key type</para></listitem>
308: <listitem><para>Key Id</para></listitem>
309: <listitem><para>Creation date</para></listitem>
310: <listitem><para>Expiration date, if any</para></listitem>
311: <listitem><para>all uids</para></listitem>
312: <listitem><para>Public key fingerprint</para></listitem>
313: </itemizedlist>
314: <para>
315: The output of "gpg --fingerprint" for your key provides exactly what is
1.5 jschauma 316: needed. (You may want to redirect the output of "gpg --fingerprint"
317: into a file, duplicate the entries multiple times, and print it with
1.1 jschauma 318: "a2ps -2 --borders no -B ..." cut out the individual stripes
319: and staple them.)
320: </para>
321: </listitem>
1.12 mishka 322: <listitem id="signsteps-bcard-carry">
1.1 jschauma 323: <para>
324: Carry this PGP "business card" and a solid photo ID (passport) with
325: you when you're going to meet another developer (or any PGP key holder).
326: </para>
327: </listitem>
1.12 mishka 328: <listitem id="signsteps-bcard-exchange">
1.1 jschauma 329: <para>
330: When you meet another developer in person, give him one of your PGP
331: "business cards" and hand him over your passport for inspection.
332: Likewise, obtain his PGP "business card" and his passport.
333: Verify his identity by checking his passport and compare the name
1.2 jschauma 334: on his PGP "business card" with the name mentioned in his passport.
1.1 jschauma 335: </para>
336: <para>
337: Be extremely pedantic with checking the person's identity, doing
338: this correctly is what signing PGP keys is all about.
339: </para>
340: <para>
341: It may happen that the person's name on a PGP key uid does not exactly
342: correspond to the name in his passport. Common examples are the use of
343: "Bill" instead of "William" or "Dick" instead of "Richard" as first
344: names. If you're in doubt whether you should confirm the identity of a
345: person with your signature, don't do it. Instead, ask the other party to
346: add a new uid with his name, exactly as in the photo ID, to his key, and
347: sign that uid.
348: </para>
349: <para>
350: If everything matches, make a note on his PGP "business card" that
351: the identity check was successful (with date). This does seem an odd
352: thing to do when you meet a single developer, but is really the only
353: way to reliably keep track of things at key signing parties and
354: therefore is considered good practice.
355: </para>
356: </listitem>
1.12 mishka 357: <listitem id="signsteps-pkey-import">
1.1 jschauma 358: <para>
359: When back at your computer, import the other party's public key
360: (either from a public key server, or from localsrc). With gnupg, this
361: is simply done with:
362: </para>
363: <note><title/><programlisting>
1.7 jschauma 364: % gpg --import moe_pgp_key.asc
1.1 jschauma 365: </programlisting></note>
366: <para>
367: Importing the same key multiple times does not cause problems.
368: </para>
369: <para>
370: Importing from a public key server is done with:
371: </para>
372: <note><title/><programlisting>
1.4 jschauma 373: % gpg --recv-key <keyid>
1.1 jschauma 374: </programlisting></note>
375: </listitem>
1.12 mishka 376: <listitem id="signsteps-pkey-verify-contents">
1.1 jschauma 377: <para>
1.5 jschauma 378: Verify that at least the following key components of the freshly
379: imported PGP key correspond to the information on his PGP "business
380: card":
1.1 jschauma 381: </para>
382: <itemizedlist>
383: <listitem><para>Key type</para></listitem>
384: <listitem><para>Key length</para></listitem>
385: <listitem><para>Key ID</para></listitem>
386: <listitem><para>Key fingerprint</para></listitem>
387: </itemizedlist>
388: <para>
389: It is possible to generate keys for any given Key ID, and it is (due to
390: a design flaw) even possible to create PGP keys for every fingerprint!
391: These keys will, however, have odd key lengths.
392: </para>
393: <para>
1.5 jschauma 394: It is currently thought impossible to generate a key for a given
395: arbitrary tuple of (key length, key ID, key fingerprint).
1.1 jschauma 396: </para>
397: <para>
398: If all components described above on the PGP key correspond to their
399: counterparts on the PGP "business card" you can be sure that the public
1.5 jschauma 400: PGP key really belongs to the person that gave you the PGP "business
401: card".
1.1 jschauma 402: </para>
403: </listitem>
1.12 mishka 404: <listitem id="signsteps-pkey-verify-email">
1.1 jschauma 405: <para>
406: The remaining task prior to signing is to determine whether the other
407: party has control over the e-mails given in all uids. To check this,
408: generate a random number and send this number, encrypted with his key,
1.12 mishka 409: to the other party. The task of the other party is to encrypt this
1.1 jschauma 410: random number and send it back, this time encrypted with your public
411: key (the requirement for the encrypted return channel is to spoil any
1.12 mishka 412: crypto-analysis attacks). It is important for the other party
413: to sign the message he sends back, so that you can verify
414: his identify in step <xref linkend="signsteps-pkey-verify-signature"/>.
1.1 jschauma 415: </para>
416: <para>
417: If you're checking multiple uids for one PGP key, keep track of which
418: random number you send to which e-mail address.
419: </para>
420: <para>
1.12 mishka 421: Here is an example of this step using gnupg:
1.1 jschauma 422: </para>
423: <note><title/><programlisting>
1.4 jschauma 424: % cat >> moe@doe.org
425: Hi Moe,
426:
427: please return this message to me. Please sign and encrypt it.
428:
429: Thanks,
1.7 jschauma 430: Joe
1.4 jschauma 431: ^D
432: % dd if=/dev/urandom count=1 | md5 >> moe@doe.org
433: % gpg --armor --encrypt moe@doe.org > moe@doe.org.asc
1.1 jschauma 434: </programlisting></note>
435: </listitem>
1.12 mishka 436: <listitem id="signsteps-pkey-verify-signature">
1.1 jschauma 437: <para>
1.2 jschauma 438: Once you've received his reply, decrypt it and check his signature.
1.1 jschauma 439: If that is successful, that concludes the necessary tests and you can
440: signs his public key.
441: </para>
442: <para>
443: Using GPG, signing a key is done like this:
444: </para>
445: <note><title/><programlisting>
1.4 jschauma 446: % gpg --edit-key <Key ID>
447: sign
1.1 jschauma 448: </programlisting></note>
449: </listitem>
1.12 mishka 450: <listitem id="signsteps-pkey-update">
1.1 jschauma 451: <para>
452: The last step of the procedure is to export the freshly signed PGP key
453: and to send it to the owner.
454: </para>
455: <para>
456: Note: You should not directly send someone else's PGP key to a public
457: key server, unless you received it from that key server in the first
458: place. Although you signed it, and although it is called a "public" key,
459: it is up to the key holder to decide how he wants to distribute his key.
460: Instead, send the signed key to the key holder and let him deal with
461: distributing the key.
462: </para>
463: <note><title/><programlisting>
1.4 jschauma 464: % gpg --armor --export <Key ID>
1.1 jschauma 465: </programlisting></note>
466: <para>
467: or, if you use mutt, you can take advantage of mutt's "mail-key"
468: function:
469: </para>
470: <note><title/><programlisting>
1.4 jschauma 471: % mutt
472: <ESC>k
1.7 jschauma 473: To: moe@NetBSD.org
1.4 jschauma 474: Subject: Your signed PGP key
475: Please enter the key ID: 4461CF46
476: <Select key>
477: ...
1.1 jschauma 478: </programlisting></note>
479: <para>
480: Finally, you may want to update the public keys on your key ring with
481: new signatures. This can be done using the command
482: </para>
483: <note><title/><programlisting>
1.6 jschauma 484: % gpg --refresh-keys [--keyserver ...]
1.1 jschauma 485: </programlisting></note>
486: <para>
487: which retrieves and merges in any extra signatures that have been
488: published on the keyserver since you received the key.
489: </para>
490: </listitem>
491: </orderedlist>
492: </sect2>
493:
494: <sect2 id="applicants">
495: <title>Key signing procedure for applicants</title>
496: <para>
497: The Executive Committee for Membership requires that membership applicants
498: send e-mails pertaining to their account creation signed with a PGP key
499: which bears the signature of a current NetBSD developer. This requirement
500: entails that the applicant must have met a current NetBSD developer prior
501: to his account creation. At that time, his @NetBSD.org uid can not yet be
502: signed. It is, of course, worthwhile that his @NetBSD.org uid be signed as
503: soon as his account has been created, without requiring a new meeting. This
504: can easily be achieved:
505: </para>
506: <para>
1.12 mishka 507: The key signing procedure for the applicant is performed as
508: described above. Of course, initially only his non-NetBSD uids
509: are signed. After his @NetBSD.org account has been created,
510: steps <xref linkend="signsteps-pkey-verify-email"/> to <xref
511: linkend="signsteps-pkey-update"/> of the procedure are carried
512: out for his @NetBSD.org uid. There is no need for an additional
513: meeting with the applicant, as the correspondence of key and
514: person have been checked previously.
1.1 jschauma 515: </para>
516: </sect2>
517:
518: </sect1>
519: </webpage>
CVSweb <webmaster@jp.NetBSD.org>