<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2017</year>
      <year>2022</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
    <seeguide marker="configurations">Configuration in SSH</seeguide> 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>
    <section>
      <title>Counters and parallelism</title>
      <taglist>
	<tag><seeerl marker="ssh#hardening_daemon_options--max_sessions">max_sessions</seeerl></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><seeerl marker="ssh#hardening_daemon_options--max_channels">max_channels</seeerl></tag>
	<item>
	  The maximum number of channels that are accepted for each connection. The default is unlimited.
	</item>
	<tag><seeerl marker="ssh#hardening_daemon_options--parallel_login">parallel_login</seeerl></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 the
	  <seeerl marker="ssh#hardening_daemon_options--max_sessions">max_sessions</seeerl> option.
	</item>
      </taglist>
    </section>
    
    <section>
      <title>Timeouts</title>
      <taglist>
	<tag><seetype marker="ssh#hello_timeout_daemon_option">hello_timeout</seetype></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 actually a generous time, so it can lowered
	  to make the daemon less prone to DoS attacks.
	</item>
	<tag><seetype marker="ssh#negotiation_timeout_daemon_option">negotiation_timeout</seetype></tag>
	<item>
	  Maximum time in milliseconds for the authentication negotiation counted from the TCP connection establishment.
	  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><seetype marker="ssh#max_idle_time_common_option">idle_time<!--sic!--></seetype></tag>
	<item>
	  Sets a time-out on a connection when no channels are left after closing the final one.
	  It defaults to infinity.
	</item>
	<tag><seetype marker="ssh#max_initial_idle_time_daemon_option">max_initial_idle_time</seetype></tag>
	<item>
	  Sets a time-out on a connection that will expire if no channel is opened on the connection.
	  The timeout is started when the authentication phase is completed.
	  It defaults to infinity.
	</item>
      </taglist>
      <p>A figure clarifies when a timeout is started and when it triggers:
      </p>
      <image file="ssh_timeouts.jpg">
	<icaption>SSH server timeouts</icaption>
      </image>
    </section>
  </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 <seeerl marker="ssh_file"><c>ssh_file</c></seeerl>.
    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
	    <seeerl marker="ssh_file#FILE-known_hosts"><c>known_hosts</c></seeerl> and set the option
	    <seeerl marker="ssh#hardening_client_options--silently_accept_hosts">silently_accept_hosts</seeerl>
	    to <c>false</c>.
	  </item>
	  <item>or, write a specialized key handler using the <seeerl marker="ssh_client_key_api">SSH client key API</seeerl>
	  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>
	    <seeerl marker="ssh#hardening_client_options--silently_accept_hosts">silently_accept_hosts</seeerl>
	    <list>
	      <item><seetype marker="ssh#accept_callback"><c>accept_callback()</c></seetype></item>
	      <item><seetype marker="ssh#accept_hosts"><c>{HashAlgoSpec, accept_callback()}</c></seetype></item>
	    </list>
	  </item>
	</list>
      </item>
    </taglist>
  </section>

  <section>
    <title>Verifying the remote client in a daemon (server)</title>
    <taglist>
      <tag>Password checking</tag>
      <item>
	<p>The default password checking is with the list in the
	<seeerl marker="ssh#option-user_passwords">user_passwords</seeerl> option in the SSH daemon.
	It could be replaced with a <seeerl marker="ssh#option-pwdfun">pwdfun</seeerl> plugin. The
	arity four variant (<seetype marker="ssh#pwdfun_4"><c>pwdfun_4()</c></seetype>)
	can also be used for introducing delays after failed password checking attempts. Here is a simple
	example of such a pwdfun:
	</p>
	<code>
fun(User, Password, _PeerAddress, State) ->
        case lists:member({User,Password}, my_user_pwds()) of
            true ->
                {true, undefined}; % Reset delay time
            false when State == undefined ->
                timer:sleep(1000),
                {false, 2000}; % Next delay is 2000 ms
            false when is_integer(State) ->
                timer:sleep(State),
                {false, 2*State} % Double the delay for each failure
        end
end.
</code>
	<p>If a public key is used for logging in, there is normally no checking of the user name. It
	could be enabled by setting the option
	<seeerl marker="ssh#option-pk_check_user"><c>pk_check_user</c></seeerl>
	to <c>true</c>.
	In that case the pwdfun will get the atom <c>pubkey</c> in the password argument.
	</p>
      </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
      <seeapp marker="SSH_app#supported-specifications-and-standards">SSH (App)</seeapp>
      for a list of supported and of disabled algorithms.
      In the User's Guide the chapter
      <seeguide marker="configure_algos">Configuring algorithms in SSH</seeguide>
      describes the options for enabling or disabling algorithms -
      <seetype marker="ssh#preferred_algorithms_common_option">preferred_algorithms</seetype> and
      <seetype marker="ssh#modify_algorithms_common_option">modify_algorithms</seetype>.
      </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 <seetype marker="ssh#rekey_limit_common_option">rekey_limit</seetype> 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
      <seetype marker="ssh#exec_daemon_option">exec</seetype> and
      <seetype marker="ssh#shell_daemon_option">shell</seetype> 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
      <seetype marker="ssh#id_string_common_option">id_string</seetype>.
      We start a daemon with that option:
      </p>
      <code>
	ssh:daemon(1234, [{id_string,"hi there"}, ... ]).
      </code>
      <p>and the daemon 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 <seetype marker="ssh#id_string_common_option">id_string</seetype>.
      </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
    <seetype marker="ssh#connect_timeout_client_option">connect_timeout</seetype>.
    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
    <seemfa marker="ssh:ssh#connect/3">ssh:connect/3</seemfa>.
    </p>
  </section>

</chapter>