File 3481-ssh-Add-a-chapter-about-hardening-to-the-User-s-Guid.patch of Package erlang
From 51648da9cadaffee52bdd097441d7a20495cff90 Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Fri, 14 Feb 2020 16:22:30 +0100
Subject: [PATCH] ssh: Add a chapter about hardening to the User's Guide
---
lib/ssh/doc/src/Makefile | 3 +-
lib/ssh/doc/src/configurations.xml | 4 +
lib/ssh/doc/src/hardening.xml | 238 +++++++++++++++++++++++++++++
lib/ssh/doc/src/ssh.xml | 30 +++-
lib/ssh/doc/src/usersguide.xml | 1 +
5 files changed, 268 insertions(+), 8 deletions(-)
create mode 100644 lib/ssh/doc/src/hardening.xml
diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile
index fa5eab7850..3bad66c948 100644
--- a/lib/ssh/doc/src/Makefile
+++ b/lib/ssh/doc/src/Makefile
@@ -59,7 +59,8 @@ XML_CHAPTER_FILES = \
introduction.xml \
using_ssh.xml \
terminology.xml \
- configure_algos.xml
+ configure_algos.xml \
+ hardening.xml
BOOK_FILES = book.xml
diff --git a/lib/ssh/doc/src/hardening.xml b/lib/ssh/doc/src/hardening.xml
new file mode 100644
index 0000000000..5d65f5da3f
--- /dev/null
+++ b/lib/ssh/doc/src/hardening.xml
@@ -0,0 +1,238 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2017</year>
+ <year>2020</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>Hardening</title>
+ <prepared></prepared>
+ <docno></docno>
+ <approved></approved>
+ <date></date>
+ <rev></rev>
+ <file>hardening.xml</file>
+ </header>
+
+ <section>
+ <marker id="introduction"/>
+ <title>Introduction</title>
+ <p>The Erlang/OTP SSH application is intended to be used in other applications as a library.
+ </p>
+ <p>Different applications using this library may have very different requirements.
+ One application could be running on a high performance server, while another is running on
+ a small device with very limited cpu capacity. For example, the first one may accept many users
+ simultaneously logged in, while the second one wants to limit them to only one.
+ </p>
+ <p>That simple example shows that it is impossible to deliver the SSH application with default
+ values on hardening options as well on other options that suites every need.
+ </p>
+ <p>The purpose of this guide is to discuss the different hardening options available, as a
+ guide to the reader. Configuration in general is described in the
+ <seealso marker="configurations">Configuration in SSH</seealso> chapter.
+ </p>
+ </section>
+
+ <section>
+ <title>Resilience to DoS attacks</title>
+ <p>The following applies to daemons (servers).</p>
+ <p>DoS (Denial of Service) attacks are hard to fight at the node level. Here are firewalls and
+ other means needed, but that is out of scope for this guide.
+ However, some measures could be taken in the configuration of the SSH server to increase the resilence.
+ The options to use
+ are:</p>
+ <taglist>
+ <tag><seealso marker="ssh#type-hello_timeout_daemon_option">hello_timeout</seealso></tag>
+ <item>
+ If the client fails to send the first ssh message after a tcp connection setup
+ within this time (in milliseconds), the connection is closed.
+ The default value is 30 seconds. This is actualy a generous time, so it can lowered
+ to make the daemon less prone to DoS attacks.
+ </item>
+ <tag><seealso marker="ssh#type-negotiation_timeout_daemon_option">negotiation_timeout</seealso></tag>
+ <item>
+ Maximum time in milliseconds for the authentication negotiation.
+ If the client fails to log in within this time, the connection is closed.
+ The default value is 2 minutes. It is quite a long time, but can lowered if the client is
+ supposed to be fast like if it is a program logging in.
+ </item>
+ <tag><seealso marker="ssh#hardening_daemon_options--max_sessions">max_sessions</seealso></tag>
+ <item>
+ The maximum number of simultaneous sessions that are accepted at any time for this daemon.
+ This includes sessions that are being authorized. The default is that an unlimited number of
+ simultaneous sessions are allowed. It is a good candidate to set if the capacity of the server
+ is low or a capacity margin is needed.
+ </item>
+ <tag><seealso marker="ssh#hardening_daemon_options--max_channels">max_channels</seealso></tag>
+ <item>
+ The maximum number of channels that are accepted for each connection. The default is unlimited.
+ </item>
+ <tag><seealso marker="ssh#hardening_daemon_options--parallel_login">parallel_login</seealso></tag>
+ <item>
+ If set to false (the default value), only one login is handled at a time.
+ If set to true, the number of simultaneous login attempts are limited by the value of
+ <seealso marker="ssh#hardening_daemon_options--max_sessions">max_sessions</seealso> option.
+ </item>
+ <tag><seealso marker="ssh#type-max_idle_time_common_option">idle_time<!--sic!--></seealso></tag>
+ <item>
+ Sets a time-out on a connection when no channels are open. Defaults to infinity.
+ </item>
+ </taglist>
+ </section>
+
+
+ <section>
+ <title>Verifying the remote daemon (server) in an SSH client</title>
+ <p>Every SSH server presents a public key - the <i>host key</i> - to the client while keeping the corresponding
+ private key in relatively safe privacy.
+ </p>
+ <p>The client checks that the host that presented the public key also possesses the private key of the key-pair.
+ That check is part of the SSH protocol.
+ </p>
+ <p>But how can the client know that the host <i>really</i> is the one that it tried to connect to and not an
+ evil one impersonating the expected one using its own valid key-pair? There are two alternatives available with the
+ default key handling plugin <seealso marker="ssh_file"><c>ssh_file</c></seealso>.
+ The alternatives are:
+ </p>
+ <taglist>
+ <tag>Pre-store the host key</tag>
+ <item>
+ <list>
+ <item>
+ For the default handler ssh_file, store the valid host keys in the file
+ <seealso marker="ssh_file#FILE-known_hosts"><c>known_hosts</c></seealso> and set the option
+ <seealso marker="ssh#hardening_client_options--silently_accept_hosts">silently_accept_hosts</seealso>
+ to <c>false</c>.
+ </item>
+ <item>or, write a specialized key handler using the <seealso marker="ssh_client_key_api">SSH client key API</seealso>
+ that accesses the pre-shared key in some other way.
+ </item>
+ </list>
+ </item>
+
+ <tag>Pre-store the "fingerprint" (checksum) of the host key</tag>
+ <item>
+ <list>
+ <item>
+ <seealso marker="ssh#hardening_client_options--silently_accept_hosts">silently_accept_hosts</seealso>
+ <list>
+ <item><seealso marker="ssh#type-accept_callback"><c>accept_callback()</c></seealso></item>
+ <item><seealso marker="ssh#type-accept_hosts"><c>{HashAlgoSpec, accept_callback()}</c></seealso></item>
+ </list>
+ </item>
+ </list>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>Hardening in the cryptographic area</title>
+ <section>
+ <title>Algorithm selection</title>
+ <p>One of the cornerstones of security in SSH is cryptography. The development in crypto analysis is fast,
+ and yesterday's secure algorithms are unsafe today. Therefore some algorithms are no longer enabled by default
+ and that group grows with time.
+ See the
+ <seealso marker="SSH_app#supported-specifications-and-standards">SSH (App)</seealso>
+ for a list of supported and of disabled algorithms.
+ In the User's Guide the chapter
+ <seealso marker="configure_algos">Configuring algorithms in SSH</seealso>
+ describes the options for enabling or disabling algorithms -
+ <seealso marker="ssh#type-preferred_algorithms_common_option">preferred_algorithms</seealso> and
+ <seealso marker="ssh#type-modify_algorithms_common_option">modify_algorithms</seealso>.
+ </p>
+ </section>
+
+ <section>
+ <title>Re-keying</title>
+ <p>In the setup of the SSH connection a secret cipher key is generated by co-operation of the
+ client and the server. Keeping this key secret is crucial for keeping the communication secret.
+ As time passes and encrypted messages are exchanged, the probability that a listener could
+ guess that key increases.
+ </p>
+ <p>The SSH protocol therefore has a special operation defined - <i>key re-negotiation</i> or
+ <i>re-keying</i>.
+ Any side (client or server) could initiate the re-keying and the result is a new cipher key.
+ The result is that the eves-dropper has to restart its evil and dirty craftmanship.
+ </p>
+ <p>See the option <seealso marker="ssh#type-rekey_limit_common_option">rekey_limit</seealso> for a
+ description.
+ </p>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Hardening of the SSH protocol - both daemons and clients</title>
+ <section>
+ <title>Disabling shell and exec in a daemon</title>
+ <p>A daemon has two services for evaluating tasks on behalf of a remote client. The <i>exec</i>
+ server-side service takes a string provided by the client, evaluates it and returns the result.
+ The <i>shell</i> function enables the client to open a shell in the shell host.
+ </p>
+ <p>Those service could - and should - be disabled when they are not needed. The options
+ <seealso marker="ssh#type-exec_daemon_option">exec</seealso> and
+ <seealso marker="ssh#type-shell_daemon_option">shell</seealso> are enabled per default but could be
+ set to <c>disabled</c> if not needed. The same options could also install handlers for the string(s)
+ passed from the client to the server.
+ </p>
+ </section>
+
+ <section>
+ <title>The id string</title>
+ <p>One way to reduce the risk of intrusion is to not convey which software and which version
+ the intruder is connected to. This limits the risk of an intruder exploiting known faults or
+ peculiarities learned by reading the public code.
+ </p>
+ <p>Each SSH client or daemon presents themselves to each other with brand and version. This may
+ look like</p>
+ <pre>SSH-2.0-Erlang/4.10</pre>
+ <p>or</p>
+ <pre>SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3</pre>
+ <p>This brand and version may be changed with the option
+ <seealso marker="ssh#type-id_string_common_option">id_string</seealso>.
+ We start a daemon with that option:
+ </p>
+ <code>
+ ssh:daemon(1234, [{id_string,"hi there"}, ... ]).
+ </code>
+ <p>and the deamon will present itself as:</p>
+ <pre>SSH-2.0-hi there</pre>
+ <p>It is possible to replace the string with one randomly generated for each connection attempt.
+ See the reference manual for <seealso marker="ssh#type-id_string_common_option">id_string</seealso>.
+ </p>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Client connection options</title>
+ <p>A client could limit the time for the initial tcp connection establishment with the option
+ <seealso marker="ssh#type-connect_timeout_client_option">connect_timeout</seealso>.
+ The time is in milliseconds, and the initial value is infinity.
+ </p>
+ <p>The negotiation (session setup time) time can be limited with the <i>parameter</i>
+ <c>NegotiationTimeout</c> in a call establishing an ssh session, for example
+ <seealso marker="ssh:ssh#connect/3">ssh:connect/3</seealso>.
+ </p>
+ </section>
+
+</chapter>
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 1864002b70..a0355219a1 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -201,7 +201,10 @@
<name name="fingerprint"/>
<desc>
<taglist>
- <tag><c>silently_accept_hosts</c></tag>
+ <tag>
+ <marker id="hardening_client_options--silently_accept_hosts"/>
+ <c>silently_accept_hosts</c>
+ </tag>
<item>
<p>This option guides the <c>connect</c> function on how to act when the connected server presents a Host
Key that the client has not seen before. The default is to ask the user with a question on stdio of whether to
@@ -212,7 +215,8 @@
<seealso marker="#type-key_cb_common_option">key_cb</seealso>
for the general way to handle keys.
</p>
- <p>The option can be given in three different forms as seen above:</p>
+ <p>The option can be given in three different forms as seen <seealso marker="ssh#type-accept_hosts">above</seealso>:
+ </p>
<list>
<item>The value is a <c>boolean()</c>.
The value <c>true</c> will make the client accept any unknown Host Key without any user interaction.
@@ -692,7 +696,10 @@
<name name="hardening_daemon_options"/>
<desc>
<taglist>
- <tag><c>max_sessions</c></tag>
+ <tag>
+ <marker id="hardening_daemon_options--max_sessions"/>
+ <c>max_sessions</c>
+ </tag>
<item>
<p>The maximum number of simultaneous sessions that are accepted at any time
for this daemon. This includes sessions that are being authorized.
@@ -711,8 +718,11 @@
<p>By default, this option is not set. This means that the number is not limited.
</p>
</item>
-
- <tag><c>max_channels</c></tag>
+
+ <tag>
+ <marker id="hardening_daemon_options--max_channels"/>
+ <c>max_channels</c>
+ </tag>
<item>
<p>The maximum number of channels with active remote subsystem that are accepted for
each connection to this daemon</p>
@@ -720,7 +730,10 @@
</p>
</item>
- <tag><c>parallel_login</c></tag>
+ <tag>
+ <marker id="hardening_daemon_options--parallel_login"/>
+ <c>parallel_login</c>
+ </tag>
<item>
<p>If set to false (the default value), only one login is handled at a time.
If set to true, an unlimited number of login attempts are allowed simultaneously.
@@ -737,7 +750,10 @@
</warning>
</item>
- <tag><c>minimal_remote_max_packet_size</c></tag>
+ <tag>
+ <marker id="hardening_daemon_options--minimal_remote_max_packet_size"/>
+ <c>minimal_remote_max_packet_size</c>
+ </tag>
<item>
<p>The least maximum packet size that the daemon will accept in channel open requests from the client.
The default value is 0.
diff --git a/lib/ssh/doc/src/usersguide.xml b/lib/ssh/doc/src/usersguide.xml
index c160015d6e..aabc12a750 100644
--- a/lib/ssh/doc/src/usersguide.xml
+++ b/lib/ssh/doc/src/usersguide.xml
@@ -38,4 +38,5 @@
<xi:include href="using_ssh.xml"/>
<xi:include href="terminology.xml"/>
<xi:include href="configure_algos.xml"/>
+ <xi:include href="hardening.xml"/>
</part>
--
2.26.2
