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