Terminology

View Source

General Information

In the following terms that may cause confusion are explained.

The term "user"

A "user" is a term that everyone understands intuitively. However, the understandings may differ which can cause confusion.

The term is used differently in OpenSSH and SSH in Erlang/OTP. The reason is the different environments and use cases that are not immediately obvious.

This chapter aims at explaining the differences and giving a rationale for why Erlang/OTP handles "user" as it does.

In OpenSSH

Many have been in contact with the command 'ssh' on a Linux machine (or similar) to remotly log in on another machine. One types

ssh host

to log in on the machine named host. The command prompts for your password on the remote host and then you can read, write and execute as your user name has rights on the remote host. There are stronger variants with pre-distributed keys or certificates, but that are for now just details in the authentication process.

You could log in as the user anotheruser with

ssh anotheruser@host

and you will then be enabled to act as anotheruser on the host if authorized correctly.

So what does "your user name has rights" mean? In a UNIX/Linux/etc context it is exactly as that context: The user could read, write and execute programs according to the OS rules. In addition, the user has a home directory ($HOME) and there is a $HOME/.ssh/ directory with ssh-specific files.

SSH password authentication

When SSH tries to log in to a host, the ssh protocol communicates the user name (as a string) and a password. The remote ssh server checks that there is such a user defined and that the provided password is acceptable.

If so, the user is authorized.

SSH public key authentication

This is a stronger method where the ssh protocol brings the user name, the user's public key and some cryptographic information which we could ignore here.

The ssh server on the remote host checks:

  • That the user has a home directory,
  • that home directory contains a .ssh/ directory and
  • the .ssh/ directory contains the public key just received in the authorized_keys file

if so, the user is authorized.

The SSH server on UNIX/Linux/etc after a successful authentication

After a successful incoming authentication, a new process runs as the just authenticated user.

Next step is to start a service according to the ssh request. In case of a request of a shell, a new one is started which handles the OS-commands that arrives from the client (that's "you").

In case of a sftp request, an sftp server is started in with the user's rights. So it could read, write or delete files if allowed for that user.

In Erlang/OTP SSH

For the Erlang/OTP SSH server the situation is different. The server executes in an Erlang process in the Erlang emulator which in turn executes in an OS process. The emulator does not try to change its user when authenticated over the SSH protocol. So the remote user name is only for authentication purposes in the Erlang/OTP SSH application.

Password authentication in Erlang SSH

The Erlang/OTP SSH server checks the user name and password in the following order:

  1. If a pwdfun is defined, that one is called and the returned boolean is the authentication result.
  2. Else, if the user_passwords option is defined and the username and the password matches, the authentication is a success.
  3. Else, if the option password is defined and matches the password the authentication is a success. Note that the use of this option is not recommended in non-test code.

Public key authentication in Erlang SSH

The user name, public key and cryptographic data (a signature) that is sent by the client are used as follows (some steps left out for clarity):

  1. A callback module is selected using the options key_cb.
  2. The callback module is used to check that the provided public key is one of the user's pre-stored. In case of the default callback module, the files authorized_keys and authorized_keys2 are searched in a directory found in the following order:
  • If the option user_dir_fun is defined, that fun is called and the returned directory is used,
  • Else, If the option user_dir is defined, that directory is used,
  • Else the subdirectory .ssh in the home directory of the user executing the OS process of the Erlang emulator is used.

If the provided public key is not found, the authentication fails.

  1. Finally, if the provided public key is found, the signature provided by the client is checked with the public key.

The Erlang/OTP SSH server after a successful authentication

After a successful authentication an Erlang process is handling the service request from the remote ssh client. The rights of that process are those of the user of the OS process running the Erlang emulator.

If a shell service request arrives to the server, an Erlang shell is opened in the server's emulator. The rights in that shell is independent of the just authenticated user.

In case of an sftp request, an sftp server is started with the rights of the user of the Erlang emulator's OS process. So with sftp the authenticated user does not influence the rights.

So after an authentication, the user name is not used anymore and has no influence.

Connection, Channel, and Session

The SSH protocol uses a layered architecture where the terms connection, channel, and session have distinct meanings. Erlang/OTP SSH options that reference these terms may behave differently from similarly named OpenSSH options.

Connection

A connection is an SSH-level association between an SSH client and an SSH daemon, established over a single TCP connection. One connection carries all channels between those two endpoints, and it is unauthenticated until user authentication has succeeded. In Erlang/OTP SSH, the max_sessions option limits the total number of TCP connections accepted by the daemon, counted before the SSH handshake starts and therefore regardless of whether the client authenticates. Compare with OpenSSH MaxStartups, which limits only unauthenticated connections.

Channel

A channel is a logical data path multiplexed inside a single SSH connection. Multiple channels can share one connection. Channel types include session, direct-tcpip (local forwarding), and forwarded-tcpip (remote forwarding). In Erlang/OTP SSH, the max_channels option limits all channel types per connection. Compare with OpenSSH MaxSessions, which limits only session channels.

Session

A session is one specific type of channel used for interactive shells, command execution, or subsystems (such as SFTP). In OpenSSH terminology, MaxSessions counts only these session channels. In Erlang/OTP SSH, the term "session" in max_sessions refers to TCP connections, not session channels — a naming difference that can cause confusion.