sshkey.rst 4.4 KB
Newer Older
Andri Steiner's avatar
Andri Steiner committed
1
2
.. index::
   triple: How-to; SSH; Key Generate
3
   :name: howto-sshkey
Andri Steiner's avatar
Andri Steiner committed
4
5
6
7

================
SSH Key Handling
================
Andri Steiner's avatar
Andri Steiner committed
8

Andri Steiner's avatar
Andri Steiner committed
9
10
.. index::
   triple: How-to; SSH; Windows
11
   :name: howto-sshkey_windows
Andri Steiner's avatar
Andri Steiner committed
12

Andri Steiner's avatar
Andri Steiner committed
13
14
Windows
=======
Andri Steiner's avatar
Andri Steiner committed
15

Andri Steiner's avatar
Andri Steiner committed
16
Download and install the Putty Installer from the official `download page <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`__.
Andri Steiner's avatar
Andri Steiner committed
17

Andri Steiner's avatar
Andri Steiner committed
18
19
Create SSH Key Pair
-------------------
Andri Steiner's avatar
Andri Steiner committed
20

Andri Steiner's avatar
Andri Steiner committed
21
22
23
24
25
26
27
* start puttygen
* select `ED25519` and press the `Generate` button
* alternatively you can select `SSH-2 RSA` and increase the `Number of bits in a generated key` field to `4096`
* follow the instructions and generate randomness by moving the mouse over the requested area
* change the `Key comment` to your e-mail address
* enter a secure `Key passphrase` (for security reasons, never create keys without passphrase!)
* press the `Save public key` and `Save private key` button
Andri Steiner's avatar
Andri Steiner committed
28

Andri Steiner's avatar
Andri Steiner committed
29
.. warning::
Andri Steiner's avatar
Andri Steiner committed
30

Andri Steiner's avatar
Andri Steiner committed
31
32
33
   As the name tells, the public key is used to identify you on a remote system,
   and you use the private key on your local machine to identify yourself against the desired
   server. Make sure your private key does not leave your computer.
Andri Steiner's avatar
Andri Steiner committed
34
35

SSH Agent (Pageant)
Andri Steiner's avatar
Andri Steiner committed
36
-------------------
Andri Steiner's avatar
Andri Steiner committed
37
38
39
40
41
42
43
44
45
46

Putty comes with a SSH agent named pageant. It comes bundled with the
putty installer or you can find it on the putty download page. After you
started Pageant, it will hide itselve in the systray. To add your key,
open the Pageant dialog by right clicking on the systray icon. Please
refere to the `Pageant
documentation <http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter9.html#pageant>`__
for more information.

Agent Forwarding
Andri Steiner's avatar
Andri Steiner committed
47
----------------
Andri Steiner's avatar
Andri Steiner committed
48
49
50
51

For several actions like checking out a git repository or copying a site
form stage to prod you need to forward your SSH Agent. First you have to
browse to ``Connection->SSH->Auth`` on the left-hand side, then you have
Andri Steiner's avatar
Andri Steiner committed
52
53
54
to enable the ``Allow agent forwarding`` checkbox.

.. warning::
Andri Steiner's avatar
Andri Steiner committed
55

Andri Steiner's avatar
Andri Steiner committed
56
57
58
59
60
61
62
   "Agent forwarding should be enabled with caution. Users with
   the ability to bypass file permissions on the remote host (for the
   agent's UNIX-domain socket) can access the local agent through the
   forwarded connection. An attacker cannot obtain key material from the
   agent, however they can perform operations on the keys that enable them
   to authenticate using the identities loaded into the agent." (openssh
   manual)
Andri Steiner's avatar
Andri Steiner committed
63

Andri Steiner's avatar
Andri Steiner committed
64
65
.. index::
   triple: How-to; SSH; MacOS
66
   :name: howto-sshkey_macos
Andri Steiner's avatar
Andri Steiner committed
67

Andri Steiner's avatar
Andri Steiner committed
68
69
.. index::
   triple: How-to; SSH; Linux
70
   :name: howto-sshkey_linux
Andri Steiner's avatar
Andri Steiner committed
71
72

Mac, Linux
Andri Steiner's avatar
Andri Steiner committed
73
==========
Andri Steiner's avatar
Andri Steiner committed
74
75

Create an SSH key pair
Andri Steiner's avatar
Andri Steiner committed
76
----------------------
Andri Steiner's avatar
Andri Steiner committed
77

Andri Steiner's avatar
Andri Steiner committed
78
Make sure the openssh-client package is installed and issue this command in your favorite shell:
Andri Steiner's avatar
Andri Steiner committed
79

Andri Steiner's avatar
Andri Steiner committed
80
.. code-block:: bash
Andri Steiner's avatar
Andri Steiner committed
81

Andri Steiner's avatar
Andri Steiner committed
82
   ssh-keygen -t ed25519 -a 100 -C '<e-mail@address>'
Andri Steiner's avatar
Andri Steiner committed
83

Andri Steiner's avatar
Andri Steiner committed
84
.. warning::
Andri Steiner's avatar
Andri Steiner committed
85
86

   Do not create keys without passphrase. If you do so, everyone with access to the key file will gain access to the server immediatelly!
Andri Steiner's avatar
Andri Steiner committed
87
88

Agent Forwarding
Andri Steiner's avatar
Andri Steiner committed
89
----------------
Andri Steiner's avatar
Andri Steiner committed
90
91
92
93
94
95
96

For several actions like checking out a git repository or copying a site
form stage to prod you need to forward your SSH Agent. Use the command
``ssh -F`` or the SSH config directive ``ForwardAgent yes`` to forward
your SSH Agent.

SSH agent
Andri Steiner's avatar
Andri Steiner committed
97
---------
Andri Steiner's avatar
Andri Steiner committed
98
99
100
101
102
103
104
105
106

Since you encrypted your key with a secure passphrase, you have to enter
this passphrase every time you attempt to connect to an SSH Server in
order to decrypt your private key.

An SSH agent caches your decrypted keys and provides them to SSH client
programs. Thus the passphrase must only provided once, when adding your
private key to the agent's cache.

107
.. tip::
Andri Steiner's avatar
Andri Steiner committed
108

Andri Steiner's avatar
Andri Steiner committed
109
110
111
112
   Usually you would start your agent upon login, and let it run
   until you logout. There are many diffrent agents, and they are typically
   well integrated to your OS, SHELL or Desktop Environment. Please refer
   to the documentation of your favorite agent.
Andri Steiner's avatar
Andri Steiner committed
113

Andri Steiner's avatar
Andri Steiner committed
114
.. warning::
Andri Steiner's avatar
Andri Steiner committed
115

Andri Steiner's avatar
Andri Steiner committed
116
117
118
119
120
121
122
   Please use the -c flag to prevent key hijacking. This flag
   ''indicates that added identities should be subject to confirmation
   before being used for authentication''. That means, you have to confirm
   all uses of your key, espessially when you are logged in to a server
   (with enabled AgentForwarding) and another user tries to steal your
   identity. Please refere to the documentation of your favorite agent on
   how to prevent key hijacking.
Andri Steiner's avatar
Andri Steiner committed
123

Andri Steiner's avatar
Andri Steiner committed
124
125
126
   Confirmation is performed by the SSH\_ASKPASS program mentioned below.
   Successful confirmation is signaled by a zero exit status from the
   SSH\_ASKPASS program, rather than text entered into the requester.
Andri Steiner's avatar
Andri Steiner committed
127