Skip to content

Commit 3ca6e1f

Browse files
manfred-kaisermanfred-kaiser
authored
Update fingerprint.rst
1 parent e74373e commit 3ca6e1f

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎doc/fingerprint.rst

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,170 @@
11
SSH Fingerprints
22
================
33

4+
With SSH, unlike HTTPS secured websites, there are no central certificate providers to ensure that you are connecting to the correct server.
5+
6+
In most cases, a new key is automatically generated during installation. When a client connects to this server for the first time, the offered key is still unknown and you are asked if you want to connect to the server.
7+
8+
.. warning::
9+
10+
The fingerprint ensures that you do not connect to a wrong server. One of the most common reasons for unknown fingerprints is the reinstallation of a system where new keys are generated.
11+
12+
However, it can also be a Man in the Middle attack, where the connection was redirected to another server.
13+
14+
For this reason, the fingerprint must always be compared against a trusted source.
15+
16+
Checking the fingerprint
17+
------------------------
18+
19+
The first time you connect to a server, you will be asked if you want to connect to the server.
20+
21+
.. code-block:: none
22+
23+
$ ssh github.com
24+
The authenticity of host 'github.com (140.82.121.3)' can't be established.
25+
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
26+
Are you sure you want to continue connecting (yes/no/[fingerprint])?
27+
28+
In this case, the SSH client wants to connect to Github.com and you are asked if you want to continue with the connection.
29+
30+
You should not simply confirm this query, but compare the fingerprint with a trusted source. Github has published the fingerprints at the following address: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
31+
32+
If the SSH client offers the possibility to enter a fingerprint, this method is always preferable. You just have to copy the fingerprint from the website and paste it into the terminal.
33+
34+
The reason is that if you compare fingerprints manually, errors can occur and you confirm a similar fingerprint and connect to the wrong server.
35+
36+
.. warning::
37+
38+
If the fingerprint is unknown, you should ask the server administrator for the correct fingerprint.
39+
40+
You can also contact support if the server is a rented server. They should be able to give you information. However, don't let support trick you into simply accepting the connection and insist that the fingerprint be provided to you in writing via a trusted source.
41+
42+
43+
Warning for changed fingerprints
44+
--------------------------------
45+
46+
However, for all further contacts from now on, the ssh program uses asymmetric cryptography to ensure that the server also has the correct private key that matches the public one stored in the ~/.ssh/known_hosts file, and refuses to establish the connection if in doubt. Here is a sample output:
47+
48+
.. code-block:: none
49+
50+
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
51+
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
52+
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
53+
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
54+
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
55+
It is also possible that a host key has just been changed.
56+
The fingerprint for the ED25519 key sent by the remote host is
57+
SHA256:2iJAHZZHlYMrlrBGw3t7Ma62TuZ0p7p+av3O4W+cpHY.
58+
Please contact your system administrator.
59+
Add correct host key in /home/tux/.ssh/known_hosts to get rid of this message.
60+
Offending ECDSA key in /home/tux/.ssh/known_hosts:6
61+
remove with:
62+
ssh-keygen -f "/home/tux/.ssh/known_hosts" -R 172.217.22.227
63+
ED25519 host key for 172.217.22.227 has changed and you have requested strict checking.
64+
Host key verification failed.
65+
66+
There are several reasons for changed fingerprints. One of the most common is the reinstallation of a system. However, this can also be a sign that you are connecting to the wrong server.
67+
68+
If you get a warning, you should contact the server administrator or support and ask if the server has been reinstalled or the keys have been regenerated. If this is the case, get the latest fingerprints in writing again via a trusted source.
69+
70+
If the fingerprint has changed for a legitimate reason, you can remove the old fingerprint with the following command:
71+
72+
.. code-block:: none
73+
74+
ssh-keygen -f <DATEI> -R <HOST>
75+
76+
So in the above example
77+
78+
.. code-block:: none
79+
80+
ssh-keygen -f "/home/tux/.ssh/known_hosts" -R 172.217.22.227
81+
82+
83+
Determine fingerprint of the server
84+
-----------------------------------
85+
86+
Determining the fingerprint after a new installation can be a particular challenge. This is especially true for automatically installed systems.
87+
88+
If it is a virtual machine, you often have the option to start a terminal session in the administration interface. Such administration interfaces are usually secured by HTTPS and thus the connection should be trustworthy.
89+
90+
The fingerprint of a server can be determined afterwards in a local terminal with the system program ssh-keygen.
91+
92+
MD5 and SHA256 are supported as formats for the fingerprints. Currently SHA256 is being used more and more, but MD5 fingerprints can still be found in some cases. For this reason, the fingerprints should be determined in both formats.
93+
94+
.. code-block:: none
95+
96+
ssh-keygen -f /etc/ssh/ssh_host_ecdsa_key.pub -l -E md5
97+
ssh-keygen -f /etc/ssh/ssh_host_ecdsa_key.pub -l -E sha256
98+
99+
In most cases, multiple keys are generated for an SSH server. The following one-liner determines the SHA256 fingerprints for all keys.
100+
101+
.. code-block:: none
102+
103+
find /etc/ssh/ -name 'ssh_*.pub' -exec ssh-keygen -f {} -l -E sha256 \;
104+
105+
Analogously, you can also calculate the MD5 fingerprints:
106+
107+
.. code-block:: none
108+
109+
find /etc/ssh/ -name 'ssh_*.pub' -exec ssh-keygen -f {} -l -E md5 \;
110+
111+
SSHFP Records - The fingerprint in DNS
112+
--------------------------------------
113+
114+
SSHFP records are special entries in the DNS zone of a domain. Thus, a basic requirement is that a DNS name exists for the server to which you want to connect.
115+
116+
Another requirement is that the DNS zone is protected by DNSSEC. If the zone is not protected by DNSSEC, an SSHFP record does not provide any security gain.
117+
118+
Server configuration
119+
""""""""""""""""""""
120+
121+
On a server the SSHFP records can be created with the following command:
122+
123+
.. code-block:: none
124+
125+
$ ssh-keygen -r examplehost.example.org
126+
examplehost.example.org IN SSHFP 1 1 d004948e1d359f2a267f03a599c3efe5d8285ae1
127+
examplehost.example.org IN SSHFP 1 2 f94a95111db1158903bc23e61f75843d029f9d3edabfd74c200f201d4b80b330
128+
examplehost.example.org IN SSHFP 3 1 3b355dc1e3a508e4594e7f8aa30d315d820eb602
129+
examplehost.example.org IN SSHFP 3 2 cacc4090df702522c977ea5dac7bb5d64b9b0968ca63879cc821f8b2b4b099d7
130+
examplehost.example.org IN SSHFP 4 1 4a1923a588b2426b6353699dfe9a69102fd5a29d
131+
examplehost.example.org IN SSHFP 4 2 67be5c3169884615436ec3068cb08d150466e1fae39c18cd4952d2594ad1d512
132+
133+
These DNS records can then be stored in the DNS zone. The zone file must then be re-signed.
134+
135+
To check whether the new DNS records work, you can check this with the program dig.
136+
137+
.. code-block:: none
138+
139+
dig SSHFP examplehost.example.org +short
140+
141+
Client configuration
142+
""""""""""""""""""""
143+
144+
By default, the OpenSSH client does not check the fingerprint against an SSHFP record. For this reason, the following entry must be added to the .ssh/config configuration file:
145+
146+
.. code-block:: none
147+
148+
VerifyHostKeyDNS yes
149+
150+
If you then connect to the new server, you no longer need to confirm the fingerprint.
151+
152+
Troubleshooting
153+
"""""""""""""""
154+
155+
If the SSH client still asks for confirmation, it may be because DNSSEC is not being used or has been configured incorrectly.
156+
157+
.. code-block:: none
158+
159+
The authenticity of host 'examplehost.example.org (192.0.2.123)' can't be established.
160+
ECDSA key fingerprint is SHA256:MH85JK0yq+JNl1lPKUlxit+dGFqWMS/MmohcINp/e9Q.
161+
Matching host key fingerprint found in DNS.
162+
Are you sure you want to continue connecting (yes/no/[fingerprint])?
163+
164+
In this case, the fingerprint must still be checked against a trusted source.
165+
166+
However, the fingerprint stored in the DNS is no longer considered trustworthy in this case. The reason for this is that the integrity of the DNS zone is no longer guaranteed due to an incorrect DNSSEC configuration.
167+
4168
Recognizing clients with known fingerprints
5169
-------------------------------------------
6170

0 commit comments

Comments
 (0)