ssh: extend hardening guide

Add sections on SFTP enablement, network-level security and advanced
authentication:
- SFTP subsystem enablement with root option and rights model reference
- Non-root VM recommendation in introduction
- IP binding restrictions (daemon/3 vs daemon/2 default behavior)
- MFA limitations and VPN alternative recommendation
- Public key validation via key_cb with pk_check_user
- Account lockout using pwdfun with cross-connection ETS tracking

Author: u3s

lib/ssh/doc/assets/ssh_timeouts.jpg

@@ -26,6 +26,10 @@ limitations under the License.
 The Erlang/OTP SSH application is intended to be used in other applications as a
 library.
 
+Ensure the Erlang VM runs as a non-root OS user. All SSH services (shell,
+exec, SFTP) inherit the OS-level rights of the VM process. See
+[Terminology](terminology.md) for details on the rights model.
+
 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
@@ -53,7 +57,7 @@ increase the resilence. The options to use are:
 
 - **[max_sessions](`m:ssh#hardening_daemon_options-max_sessions`)** - 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
+  daemon. This includes sessions that are being authenticated. 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.
@@ -96,9 +100,19 @@ increase the resilence. The options to use are:
   receiving any message back. Alive messages are typically used to detect that a connection
   became unresponsive.
 
-A figure clarifies when a timeout is started and when it triggers:
+The following table clarifies when a timeout is started and when it triggers:
 
-![SSH server timeouts](assets/ssh_timeouts.jpg "SSH server timeouts")
+| # | Event | Timeout started | Timeout ended |
+|---|-------|-----------------|---------------|
+| 1 | TCP connected | `hello_timeout`, `negotiation_timeout` | |
+| 2 | First SSH message received | | `hello_timeout` |
+| 3 | Key Exchange finished | | |
+| 4 | Authenticated | `max_initial_idle_time` | `negotiation_timeout` |
+| 5 | Channel 1 opened | | `max_initial_idle_time` |
+| 6 | Channel *n* opened | | |
+| 7 | Channel *x_1* closed | | |
+| 8 | Channel *x_n* closed (all channels closed) | `idle_time` | |
+| 9 | Connection closed | | `idle_time` |
 
 ### Resilience to compression-based attacks
 
@@ -220,20 +234,18 @@ 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 `m:ssh_file`. The alternatives are:
 
-- **Pre-store the host key** - \* For the default handler ssh_file, store the
+- **Pre-store the host key** - For the default handler ssh_file, store the
   valid host keys in the file [`known_hosts`](`m:ssh_file#FILE-known_hosts`) and
   set the option
   [silently_accept_hosts](`m:ssh#hardening_client_options-silently_accept_hosts`)
-  to `false`.
-
-  - or, write a specialized key handler using the
-    [SSH client key API](`m:ssh_client_key_api`) that accesses the pre-shared
-    key in some other way.
+  to `false`. Alternatively, write a specialized key handler using the
+  [SSH client key API](`m:ssh_client_key_api`) that accesses the pre-shared
+  key in some other way.
 
-- **Pre-store the "fingerprint" (checksum) of the host key** - \*
+- **Pre-store the "fingerprint" (checksum) of the host key** - Use
   [silently_accept_hosts](`m:ssh#hardening_client_options-silently_accept_hosts`)
-  - [`accept_callback()`](`t:ssh:accept_callback/0`)
-  - [`{HashAlgoSpec, accept_callback()}`](`t:ssh:accept_hosts/0`)
+  with a callback: [`accept_callback()`](`t:ssh:accept_callback/0`)
+  or [`{HashAlgoSpec, accept_callback()}`](`t:ssh:accept_hosts/0`).
 
 ## Verifying the remote client in a daemon (server)
 
@@ -308,6 +320,24 @@ The options [exec](`t:ssh:exec_daemon_option/0`) and
 The same options could also install handlers for
 the string(s) passed from the client to the server.
 
+### Enabling the SFTP subsystem
+
+The SFTP subsystem is not enabled by default. When enabled, SFTP provides
+access to the file system with the rights of the OS process running the
+Erlang emulator, regardless of the authenticated SSH user. See the
+[Terminology](terminology.md) section for details.
+
+The [subsystems](`t:ssh:subsystem_daemon_option/0`) option controls which
+subsystems are available. To enable SFTP:
+
+```erlang
+ssh:daemon({192, 168, 1, 10}, Port,
+           [{subsystems, [ssh_sftpd:subsystem_spec([])]} | Options]).
+```
+
+Use the `root` option to restrict SFTP users to a specific directory
+tree (see [Root Directory Isolation](#root-directory-isolation) below).
+
 ### The id string
 
 One way to reduce the risk of intrusion is to not convey which software and
@@ -332,7 +362,7 @@ This brand and version may be changed with the option
 option:
 
 ```erlang
-	ssh:daemon(1234, [{id_string,"hi there"}, ... ]).
+        ssh:daemon({192, 168, 1, 10}, 1234, [{id_string,"hi there"}, ... ]).
 ```
 
 and the daemon will present itself as:
@@ -383,3 +413,82 @@ using OS-level mechanisms (PAM chroot, containers, file permissions).
 **Defense-in-depth:** For high-security deployments, combine the `root` option
 with OS-level isolation mechanisms such as chroot jails, containers, or
 mandatory access control (SELinux, AppArmor).
+
+## Network-Level Security
+
+### IP Binding Restrictions
+
+`ssh:daemon/1` and `ssh:daemon/2` bind to **all network interfaces** by
+default. For hardened deployments, use `ssh:daemon/3` with an explicit
+IP address or `loopback`:
+
+```erlang
+ssh:daemon({192, 168, 1, 10}, 2222, Options).  % Specific interface
+ssh:daemon(loopback, 2222, Options).            % Localhost only
+```
+
+**Note**: In the examples above, `HostAddress` (1st argument) takes precedence
+over a potentially provided `{ip, Address}` in `Options` (3rd argument).
+
+## Advanced Authentication
+
+The following techniques provide enhanced authentication controls using
+custom callbacks. These require implementation specific to your environment.
+
+### Public Key Validation
+
+Use a custom [`key_cb`](`t:ssh:key_cb_common_option/0`) module implementing
+the `m:ssh_server_key_api` behaviour. The `is_auth_key` callback can enforce
+client key strength requirements (e.g. reject RSA keys shorter than 2048 bits)
+and log key usage for auditing. Enable
+[`pk_check_user`](`m:ssh#option-pk_check_user`) to verify that the username
+is known before accepting public key authentication.
+
+```erlang
+ssh:daemon({192, 168, 1, 10}, Port, [
+    {key_cb, {my_key_handler, []}},
+    {pk_check_user, true}
+]).
+```
+
+### Account Lockout Policies
+
+Use [`pwdfun`](`t:ssh:pwdfun_4/0`) with an ETS table to track failed
+attempts across connections and lock accounts after repeated failures.
+Return `disconnect` when the account is locked — this immediately
+terminates the connection with `SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE`:
+
+> #### Note {: .info }
+>
+> The lockout example below is conceptual. With
+> [`parallel_login`](`m:ssh#hardening_daemon_options-parallel_login`) enabled,
+> race conditions may reduce lockout accuracy.
+
+```erlang
+lockout_pwdfun(User, Password, _PeerAddr, State) ->
+    case ets:lookup(ssh_lockouts, {locked, User}) of
+        [_] ->
+            disconnect;
+        [] ->
+            case validate_password(User, Password) of
+                true ->
+                    ets:delete(ssh_lockouts, {attempts, User}),
+                    {true, State};
+                false ->
+                    N = ets:update_counter(ssh_lockouts,
+                            {attempts, User}, 1,
+                            {{attempts, User}, 0}),
+                    case N >= ?LOCKOUT_THRESHOLD of
+                        true ->
+                            ets:insert(ssh_lockouts,
+                                {{locked, User}, true}),
+                            ets:delete(ssh_lockouts,
+                                {attempts, User});
+                        false ->
+                            ok
+                    end,
+                    {false, State}
+            end
+    end.
+```
+

lib/ssh/doc/assets/ssh_timeouts.jpg.license

@@ -119,7 +119,7 @@ Channels come in the following three flavors:
   The Erlang `ssh` daemon can be configured to run any Erlang-implemented SSH
   subsystem.
 - _Shell_ \- Interactive shell. By default the Erlang daemon does not expose the Erlang
-  shell. It can be enabled with option `{shell, {shell, start, []}}`
+  shell. It can be enabled with option `{shell, {shell, start, []}}`.
   The shell can be customized by providing your own read-eval-print loop.
   You can also provide your own Command-Line Interface (CLI) implementation, but
   that is much more work.

lib/ssh/doc/guides/hardening.md

@@ -165,7 +165,7 @@ To collect the channel messages in a program, use `receive...end` instead of
 ```erlang
 5> receive
 5>     {ssh_cm, ConnectionRef, {data, ChannelId, Type, Result}} when Type == 0 ->
-5>         {ok,Result}
+5>         {ok,Result};
 5>     {ssh_cm, ConnectionRef, {data, ChannelId, Type, Result}} when Type == 1 ->
 5>         {error,Result}
 5> end.
@@ -359,7 +359,7 @@ The error return in the Erlang client (The text as data type 1 and exit_status
 {ok,<0.92.0>}
 3> {ok, ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity).
 {ok,0}
-4> success = ssh_connection:exec(ConnectionRef, ChannelId, "1+ 2.").
+4> success = ssh_connection:exec(ConnectionRef, ChannelId, "1+ 2.", infinity).
 success
 5> flush().
 Shell got {ssh_cm,<0.106.0>,{data,0,1,<<"**Error** {bad_input,\"1+ 2.\"}">>}}
@@ -565,7 +565,7 @@ described in Section
 1> ssh:start().
 ok
 2> ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon"},
-                     {user_dir, "/tmp/otptest_user/.ssh"}
+                     {user_dir, "/tmp/otptest_user/.ssh"},
                      {subsystems, [{"echo_n", {ssh_echo_server, [10]}}]}]).
 {ok,<0.54.0>}
 3>

lib/ssh/doc/guides/introduction.md

@@ -1044,7 +1044,7 @@ supporting ext-info.
        equiv => pwdfun_4/0}).
 -type pwdfun_2() :: fun((User::string(), Password::string()|pubkey) -> boolean()) .
 -doc """
-- **`auth_method_kb_interactive_data`** - Sets the text strings that the daemon
+- **`auth_method_kb_interactive_data`{: #option-auth_method_kb_interactive_data }** - Sets the text strings that the daemon
   sends to the client for presentation to the user when using
   `keyboard-interactive` authentication.
 

lib/ssh/doc/guides/using_ssh.md

@@ -2117,14 +2117,17 @@ replace_options_enable_services(Config) when is_list(Config) ->
     ?CT_LOG("Checking SFTP is unavailable before replace", []),
     {error, _} = ssh_sftp:start_channel(C1),
     ?CT_LOG("All services confirmed disabled", []),
-    ssh:close(C1),
 
     %% Enable shell, exec and SFTP
+    %% Keep C1 open during replace — its connection_sup acts as a
+    %% keepalive preventing auto_shutdown of ssh_system_sup while
+    %% the acceptor is being restarted.
     ?CT_LOG("Replacing options: enabling shell, exec and SFTP", []),
     {ok, Pid} = ssh:daemon_replace_options(Pid,
                     [{shell, {shell, start, []}},
                      {exec, erlang_eval},
                      {subsystems, [ssh_sftpd:subsystem_spec([])]}]),
+    ssh:close(C1),
 
     %% Verify all services work after replace
     C2 = ssh_test_lib:connect(Host, Port, ConnOpts),