en/infrastructure/cvs-sshkeys.xml

<?xml version='1.0' encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide>
<title>SSH access to cvs.gentoo.org</title>

<author title="Author">
  <mail link="swift"/>
</author>
<author title="Author">
  <mail link="robbat2"/>
</author>
<author title="Author">
  <mail link="antarus"/>
</author>
<author title="Editor">
  <mail link="nightmorph"/>
</author>

<abstract>
This mini-guide explains on how to create and use ssh-keys, especially
for use on cvs.gentoo.org.
</abstract>

<version>1.3</version>
<date>2011-10-14</date>

<chapter>
<title>SSH keys</title>
<section>
<title>Key Handling</title>
<body>
<p>
Your SSH keypair authenticates you to Gentoo Infrastructure. Properly
handling these keys is vital to keeping our machines safe. Please try to
follow these guidelines.
</p>

<ul>
  <li>Place your private keys <b>only</b> on machines you trust. This means only you have root
    on these machines and they are not shared with other users.
  </li>
  <li>Do not trust Gentoo Infrastructure. Do not place copies of your keys
    on Gentoo machines (like dev.gentoo.org.) You may forward your SSH agent
    through Gentoo managed machines if they are configured to allow users to
    agent forward (more on forwarding later.)
  </li>
  <li>Encrypt your keys with a strong passphrase. If you have trouble making
    a passphrase try emerge pwgen; pwgen -sB 25
  </li>
  <li>Do not access Gentoo infrastructure from untrusted machines such as business
    kiosks at hotels, internet cafes, or machines at computer conferences. Many of these machines
    are infected with malware.</li>
  <li>If you believe your keys were compromised, contact infrastructure immediately.
    You can do this via #gentoo-infra on irc.freenode.net or by emailing incidents@gentoo.org.
  </li>
  <li>Official hostkey fingerprints for Gentoo Infrastructure servers are
    available on the <uri link="/proj/en/infrastructure/server-specs"> server
    specifications </uri> page.
  </li>
</ul>
</body>
</section>
<section>
<title>Creating the SSH keys</title>
<body>

<p>
First of all, be physically logged on to your own computer. Make sure
that no-one will see you typing stuff in, since we are going to type in
passphrases and such. So get your pepperspray and fight all untrusted
entities until you are home alone.
</p>

<p>
Now we are going to create our ssh keys, DSA keys to be exact. Log onto
your computer as the user that you are going to be using when you want
to access cvs.gentoo.org. Then issue <c>ssh-keygen -t dsa</c>:
</p>

<pre caption="Creating SSH keys">
$ <i>ssh-keygen -t dsa</i>
Generating public/private dsa key pair.
Enter file in which to save the key (/home/temp/.ssh/id_dsa): <comment>(Press enter)</comment>
Created directory '/home/temp/.ssh'.
Enter passphrase (empty for no passphrase): <comment>(Enter your passphrase)</comment>
Enter same passphrase again: <comment>(Enter your passphrase again)</comment>
Your identification has been saved in /home/temp/.ssh/id_dsa.
Your public key has been saved in /home/temp/.ssh/id_dsa.pub.
The key fingerprint is:
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>
</pre>

<note>
Please be sure to set a strong passphrase on your private key.  Ideally,
this passphrase should be at least eight characters and contain a mixture of
letters, numbers and symbols.
</note>

<warn>
Do not set an empty passphrase on your ssh key. If infra finds out this is the
case; your account will be suspended.
</warn>

<pre caption="Created files">
# <i>ls ~/.ssh</i>
id_dsa  id_dsa.pub
</pre>

<p>
You may have more files than this, but the two files listed above
are the ones that are really important.
</p>

<p>
The first file, <path>id_dsa</path>, is your <e>private</e> key. Don't
give this to anyone; never decrypt it on an untrusted machine. Gentoo Staff
will never ask you for a copy of your private key.
</p>

<warn>
Be very careful which machines you put your private key on. If you have
several (<e>trusted!</e>) hosts from which you want to connect to 
cvs.gentoo.org, you should copy <path>id_dsa</path> to the
<path>~/.ssh</path> directories on those hosts. Trusted machines are machines
that only you have root on; these machines are not shared with other users.
</warn>

<p>
The second file, <path>id_dsa.pub</path>, is your <e>public</e> key.
Distribute this file amongst all hosts that you want to be able to
access through SSH pubkey authentification. This file should be appended
to <path>~/.ssh/authorized_keys</path> on those remote hosts. Also add it
to your local host so you can connect to that one too if you have several
boxes.
</p>

<pre caption="Adding the SSH key to the box">
$ <i>cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys</i>
</pre>

</body>
</section>
<section>
<title>
  Installing your public key on a machine using LDAP authentication for SSH
</title>
<body>

<note>
If you are a new developer, your recruiter will put your first SSH key into
LDAP, so that you can login. You can then add any additional SSH keys yourself
using the following procedure.
</note>

<note>
For most of the Gentoo infrastructure, we use LDAP to distribute user
information including SSH public keys. On these machines,
<path>~/.ssh/authorized_keys</path> should generally not contain your key.
</note>

<p>
You should place your public key into LDAP, using
<path>perl_ldap</path>, or <path>ldapmodify</path> directly.
The Infrastructure <uri link="/proj/en/infrastructure/ldap.xml">LDAP
guide</uri> describes this in more detail.
</p>

<pre caption="Adding the SSH key with perl_ldap on dev.gentoo.org">
$ <i>perl_ldap -b user -C sshPublicKey "$(cat ~/.ssh/id_dsa.pub)" &lt;username&gt;</i>
</pre>

<warn>
Each <path>sshPublicKey</path> attribute must contain exactly one public key. If you have multiple public keys, you must have multiple attributes!
</warn>

</body>
</section>
<section>
<title>Using keychain</title>
<body>

<p>
Every time you want to log on to a remote host using SSH public key
authentification, you will be asked to enter your passphrase. As much as
everybody likes typing, too much is sometimes too much. Luckily, there is
<c>keychain</c> to the rescue. There is an document on this one <uri
link="/doc/en/keychain-guide.xml">here</uri>, but I'll give you a quick
introduction.
</p>

<p>
First, install <c>keychain</c>:
</p>

<pre caption="Installing keychain">
# <i>emerge keychain</i>
</pre>

<p>
Now have keychain load up your private ssh key when you log on to your local
box. To do so, add the following to <path>~/.bash_profile</path>.  Again, this
should be done on your <e>local</e> machine where you work at the Gentoo CVS.
</p>

<warn>
<b>NEVER</b> run keychain or decrypt your private key on an untrusted host.
</warn>

<pre caption="Add this to .bash_profile">
keychain ~/.ssh/id_dsa
. .keychain/<comment>hostname</comment>-sh
</pre>

<p>
Be sure to substitute <c>hostname</c> with your hostname.
</p>

</body>
</section>
</chapter>
</guide>
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.7	<version>1.3</version>
27			<date>2011-10-14</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			follow these guidelines.
38			</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			Now we are going to create our ssh keys, DSA keys to be exact. Log onto
78			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			</p>
81	nightmorph	1.6
82			<pre caption="Creating SSH keys">
83	klieber	1.1	$ <i>ssh-keygen -t dsa</i>
84			Generating public/private dsa key pair.
85			Enter file in which to save the key (/home/temp/.ssh/id_dsa): <comment>(Press enter)</comment>
86			Created directory '/home/temp/.ssh'.
87	klieber	1.2	Enter passphrase (empty for no passphrase): <comment>(Enter your passphrase)</comment>
88			Enter same passphrase again: <comment>(Enter your passphrase again)</comment>
89	klieber	1.1	Your identification has been saved in /home/temp/.ssh/id_dsa.
90			Your public key has been saved in /home/temp/.ssh/id_dsa.pub.
91			The key fingerprint is:
92	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>
93	klieber	1.1	</pre>
94	nightmorph	1.6
95	klieber	1.1	<note>
96			Please be sure to set a strong passphrase on your private key. Ideally,
97	antarus	1.7	this passphrase should be at least eight characters and contain a mixture of
98	klieber	1.1	letters, numbers and symbols.
99			</note>
100	nightmorph	1.6
101	antarus	1.7	<warn>
102			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			</warn>
105	nightmorph	1.6
106			<pre caption="Created files">
107	klieber	1.1	# <i>ls ~/.ssh</i>
108			id_dsa id_dsa.pub
109			</pre>
110	nightmorph	1.6
111	klieber	1.1	<p>
112	antarus	1.7	You may have more files than this, but the two files listed above
113	klieber	1.1	are the ones that are really important.
114			</p>
115	nightmorph	1.6
116	klieber	1.1	<p>
117			The first file, <path>id_dsa</path>, is your <e>private</e> key. Don't
118	antarus	1.7	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	klieber	1.1	</p>
121	nightmorph	1.6
122	klieber	1.1	<warn>
123	antarus	1.7	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			cvs.gentoo.org, you should copy <path>id_dsa</path> to the
126			<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	klieber	1.1	</warn>
129	nightmorph	1.6
130	klieber	1.1	<p>
131			The second file, <path>id_dsa.pub</path>, is your <e>public</e> key.
132			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			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			boxes.
137			</p>
138	nightmorph	1.6
139			<pre caption="Adding the SSH key to the box">
140	klieber	1.1	$ <i>cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys</i>
141			</pre>
142	nightmorph	1.6
143	klieber	1.1	</body>
144			</section>
145			<section>
146	nightmorph	1.6	<title>
147			Installing your public key on a machine using LDAP authentication for SSH
148			</title>
149	robbat2	1.4	<body>
150	nightmorph	1.6
151			<note>
152			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			using the following procedure.
155			</note>
156
157	antarus	1.7	<note>
158	robbat2	1.4	For most of the Gentoo infrastructure, we use LDAP to distribute user
159			information including SSH public keys. On these machines,
160			<path>~/.ssh/authorized_keys</path> should generally not contain your key.
161	antarus	1.7	</note>
162	nightmorph	1.6
163	robbat2	1.4	<p>
164	antarus	1.7	You should place your public key into LDAP, using
165	robbat2	1.4	<path>perl_ldap</path>, or <path>ldapmodify</path> directly.
166			The Infrastructure <uri link="/proj/en/infrastructure/ldap.xml">LDAP
167			guide</uri> describes this in more detail.
168			</p>
169	nightmorph	1.6
170			<pre caption="Adding the SSH key with perl_ldap on dev.gentoo.org">
171	robbat2	1.4	$ <i>perl_ldap -b user -C sshPublicKey "$(cat ~/.ssh/id_dsa.pub)" <username></i>
172			</pre>
173	nightmorph	1.6
174			<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			</warn>
177
178	robbat2	1.4	</body>
179			</section>
180			<section>
181	klieber	1.1	<title>Using keychain</title>
182			<body>
183	nightmorph	1.6
184	klieber	1.1	<p>
185			Every time you want to log on to a remote host using SSH public key
186	klieber	1.2	authentification, you will be asked to enter your passphrase. As much as
187	nightmorph	1.6	everybody likes typing, too much is sometimes too much. Luckily, there is
188			<c>keychain</c> to the rescue. There is an document on this one <uri
189			link="/doc/en/keychain-guide.xml">here</uri>, but I'll give you a quick
190			introduction.
191	klieber	1.1	</p>
192	nightmorph	1.6
193	klieber	1.1	<p>
194			First, install <c>keychain</c>:
195			</p>
196	nightmorph	1.6
197			<pre caption="Installing keychain">
198	klieber	1.1	# <i>emerge keychain</i>
199			</pre>
200	nightmorph	1.6
201	klieber	1.1	<p>
202	nightmorph	1.6	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			should be done on your <e>local</e> machine where you work at the Gentoo CVS.
205	klieber	1.1	</p>
206	nightmorph	1.6
207	antarus	1.7	<warn>
208			<b>NEVER</b> run keychain or decrypt your private key on an untrusted host.
209			</warn>
210
211	nightmorph	1.6	<pre caption="Add this to .bash_profile">
212	klieber	1.1	keychain ~/.ssh/id_dsa
213			. .keychain/<comment>hostname</comment>-sh
214			</pre>
215	nightmorph	1.6
216	klieber	1.1	<p>
217			Be sure to substitute <c>hostname</c> with your hostname.
218			</p>
219	nightmorph	1.6
220	klieber	1.1	</body>
221			</section>
222			</chapter>
223			</guide>