/[gentoo]/xml/htdocs/proj/en/infrastructure/cvs-sshkeys.xml
Gentoo

Contents of /xml/htdocs/proj/en/infrastructure/cvs-sshkeys.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.9 - (hide annotations) (download) (as text)
Sun Jan 6 18:03:56 2013 UTC (20 months, 3 weeks ago) by antarus
Branch: MAIN
Changes since 1.8: +18 -17 lines
File MIME type: application/xml
Update key guidelines to something recent.

1 klieber 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 nightmorph 1.6 <guide>
6 klieber 1.1 <title>SSH access to cvs.gentoo.org</title>
7 nightmorph 1.6
8 klieber 1.1 <author title="Author">
9 nightmorph 1.6 <mail link="swift"/>
10 klieber 1.1 </author>
11 robbat2 1.4 <author title="Author">
12 nightmorph 1.6 <mail link="robbat2"/>
13     </author>
14 antarus 1.7 <author title="Author">
15     <mail link="antarus"/>
16     </author>
17 nightmorph 1.6 <author title="Editor">
18     <mail link="nightmorph"/>
19 robbat2 1.4 </author>
20 nightmorph 1.6
21 klieber 1.1 <abstract>
22     This mini-guide explains on how to create and use ssh-keys, especially
23     for use on cvs.gentoo.org.
24     </abstract>
25 nightmorph 1.6
26 antarus 1.9 <version>1.4</version>
27     <date>2012-05-28</date>
28 klieber 1.1
29     <chapter>
30     <title>SSH keys</title>
31     <section>
32 antarus 1.7 <title>Key Handling</title>
33     <body>
34     <p>
35     Your SSH keypair authenticates you to Gentoo Infrastructure. Properly
36     handling these keys is vital to keeping our machines safe. Please try to
37 antarus 1.9 follow these guidelines:
38 antarus 1.7 </p>
39    
40     <ul>
41 robbat2 1.8 <li>Place your private keys <b>only</b> on machines you trust. This means only you have root
42 antarus 1.7 on these machines and they are not shared with other users.
43     </li>
44     <li>Do not trust Gentoo Infrastructure. Do not place copies of your keys
45     on Gentoo machines (like dev.gentoo.org.) You may forward your SSH agent
46     through Gentoo managed machines if they are configured to allow users to
47     agent forward (more on forwarding later.)
48     </li>
49     <li>Encrypt your keys with a strong passphrase. If you have trouble making
50     a passphrase try emerge pwgen; pwgen -sB 25
51     </li>
52     <li>Do not access Gentoo infrastructure from untrusted machines such as business
53     kiosks at hotels, internet cafes, or machines at computer conferences. Many of these machines
54     are infected with malware.</li>
55     <li>If you believe your keys were compromised, contact infrastructure immediately.
56     You can do this via #gentoo-infra on irc.freenode.net or by emailing incidents@gentoo.org.
57     </li>
58 robbat2 1.8 <li>Official hostkey fingerprints for Gentoo Infrastructure servers are
59     available on the <uri link="/proj/en/infrastructure/server-specs"> server
60     specifications </uri> page.
61     </li>
62 antarus 1.7 </ul>
63     </body>
64     </section>
65     <section>
66 klieber 1.1 <title>Creating the SSH keys</title>
67     <body>
68 nightmorph 1.6
69 klieber 1.1 <p>
70     First of all, be physically logged on to your own computer. Make sure
71     that no-one will see you typing stuff in, since we are going to type in
72 klieber 1.2 passphrases and such. So get your pepperspray and fight all untrusted
73 klieber 1.1 entities until you are home alone.
74     </p>
75 nightmorph 1.6
76 klieber 1.1 <p>
77 antarus 1.9 Now we are going to create our ssh keys, RSA keys to be exact. The key should
78     be at least 2048 bits in length, but 4096 bits is recommended. Log onto
79 klieber 1.1 your computer as the user that you are going to be using when you want
80 antarus 1.9 to access cvs.gentoo.org. Then issue <c>ssh-keygen -t rsa -b 4096</c>:
81 klieber 1.1 </p>
82 nightmorph 1.6
83     <pre caption="Creating SSH keys">
84 antarus 1.9 $ <i>ssh-keygen -t rsa -b 4096</i>
85     Generating public/private rsa key pair.
86     Enter file in which to save the key (/home/temp/.ssh/id_rsa): <comment>(Press enter)</comment>
87 klieber 1.1 Created directory '/home/temp/.ssh'.
88 klieber 1.2 Enter passphrase (empty for no passphrase): <comment>(Enter your passphrase)</comment>
89     Enter same passphrase again: <comment>(Enter your passphrase again)</comment>
90 antarus 1.9 Your identification has been saved in /home/temp/.ssh/id_rsa.
91     Your public key has been saved in /home/temp/.ssh/id_rsa.pub.
92 klieber 1.1 The key fingerprint is:
93 robbat2 1.8 85:35:81:a0:87:56:78:a2:da:53:6c:63:32:d1:34:48 user@examplehost <comment>This is the fingerprint of your new key</comment>
94 klieber 1.1 </pre>
95 nightmorph 1.6
96 klieber 1.1 <note>
97     Please be sure to set a strong passphrase on your private key. Ideally,
98 antarus 1.7 this passphrase should be at least eight characters and contain a mixture of
99 klieber 1.1 letters, numbers and symbols.
100     </note>
101 nightmorph 1.6
102 antarus 1.7 <warn>
103     Do not set an empty passphrase on your ssh key. If infra finds out this is the
104     case; your account will be suspended.
105     </warn>
106 nightmorph 1.6
107     <pre caption="Created files">
108 klieber 1.1 # <i>ls ~/.ssh</i>
109 antarus 1.9 id_rsa id_rsa.pub
110 klieber 1.1 </pre>
111 nightmorph 1.6
112 klieber 1.1 <p>
113 antarus 1.7 You may have more files than this, but the two files listed above
114 klieber 1.1 are the ones that are really important.
115     </p>
116 nightmorph 1.6
117 klieber 1.1 <p>
118 antarus 1.9 The first file, <path>id_rsa</path>, is your <e>private</e> key. Don't
119 antarus 1.7 give this to anyone; never decrypt it on an untrusted machine. Gentoo Staff
120     will never ask you for a copy of your private key.
121 klieber 1.1 </p>
122 nightmorph 1.6
123 klieber 1.1 <warn>
124 antarus 1.7 Be very careful which machines you put your private key on. If you have
125     several (<e>trusted!</e>) hosts from which you want to connect to
126 antarus 1.9 cvs.gentoo.org, you should copy <path>id_rsa</path> to the
127 antarus 1.7 <path>~/.ssh</path> directories on those hosts. Trusted machines are machines
128     that only you have root on; these machines are not shared with other users.
129 klieber 1.1 </warn>
130 nightmorph 1.6
131 klieber 1.1 <p>
132 antarus 1.9 The second file, <path>id_rsa.pub</path>, is your <e>public</e> key.
133 klieber 1.1 Distribute this file amongst all hosts that you want to be able to
134     access through SSH pubkey authentification. This file should be appended
135     to <path>~/.ssh/authorized_keys</path> on those remote hosts. Also add it
136     to your local host so you can connect to that one too if you have several
137     boxes.
138     </p>
139 nightmorph 1.6
140     <pre caption="Adding the SSH key to the box">
141 antarus 1.9 $ <i>cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys</i>
142 klieber 1.1 </pre>
143 nightmorph 1.6
144 klieber 1.1 </body>
145     </section>
146     <section>
147 nightmorph 1.6 <title>
148     Installing your public key on a machine using LDAP authentication for SSH
149     </title>
150 robbat2 1.4 <body>
151 nightmorph 1.6
152     <note>
153     If you are a new developer, your recruiter will put your first SSH key into
154     LDAP, so that you can login. You can then add any additional SSH keys yourself
155     using the following procedure.
156     </note>
157    
158 antarus 1.7 <note>
159 robbat2 1.4 For most of the Gentoo infrastructure, we use LDAP to distribute user
160     information including SSH public keys. On these machines,
161     <path>~/.ssh/authorized_keys</path> should generally not contain your key.
162 antarus 1.7 </note>
163 nightmorph 1.6
164 robbat2 1.4 <p>
165 antarus 1.7 You should place your public key into LDAP, using
166 robbat2 1.4 <path>perl_ldap</path>, or <path>ldapmodify</path> directly.
167     The Infrastructure <uri link="/proj/en/infrastructure/ldap.xml">LDAP
168     guide</uri> describes this in more detail.
169     </p>
170 nightmorph 1.6
171     <pre caption="Adding the SSH key with perl_ldap on dev.gentoo.org">
172 antarus 1.9 $ <i>perl_ldap -b user -C sshPublicKey "$(cat ~/.ssh/id_rsa.pub)" &lt;username&gt;</i>
173 robbat2 1.4 </pre>
174 nightmorph 1.6
175     <warn>
176     Each <path>sshPublicKey</path> attribute must contain exactly one public key. If you have multiple public keys, you must have multiple attributes!
177     </warn>
178    
179 robbat2 1.4 </body>
180     </section>
181     <section>
182 klieber 1.1 <title>Using keychain</title>
183     <body>
184 nightmorph 1.6
185 klieber 1.1 <p>
186     Every time you want to log on to a remote host using SSH public key
187 klieber 1.2 authentification, you will be asked to enter your passphrase. As much as
188 nightmorph 1.6 everybody likes typing, too much is sometimes too much. Luckily, there is
189     <c>keychain</c> to the rescue. There is an document on this one <uri
190     link="/doc/en/keychain-guide.xml">here</uri>, but I'll give you a quick
191     introduction.
192 klieber 1.1 </p>
193 nightmorph 1.6
194 klieber 1.1 <p>
195     First, install <c>keychain</c>:
196     </p>
197 nightmorph 1.6
198     <pre caption="Installing keychain">
199 klieber 1.1 # <i>emerge keychain</i>
200     </pre>
201 nightmorph 1.6
202 klieber 1.1 <p>
203 nightmorph 1.6 Now have keychain load up your private ssh key when you log on to your local
204     box. To do so, add the following to <path>~/.bash_profile</path>. Again, this
205     should be done on your <e>local</e> machine where you work at the Gentoo CVS.
206 klieber 1.1 </p>
207 nightmorph 1.6
208 antarus 1.7 <warn>
209     <b>NEVER</b> run keychain or decrypt your private key on an untrusted host.
210     </warn>
211    
212 nightmorph 1.6 <pre caption="Add this to .bash_profile">
213 antarus 1.9 keychain ~/.ssh/id_rsa
214 klieber 1.1 . .keychain/<comment>hostname</comment>-sh
215     </pre>
216 nightmorph 1.6
217 klieber 1.1 <p>
218     Be sure to substitute <c>hostname</c> with your hostname.
219     </p>
220 nightmorph 1.6
221 klieber 1.1 </body>
222     </section>
223     </chapter>
224     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20