# Authentication

Xpra’s authentication modules can be useful for: * securing socket connections * making the unix domain socket accessible to other users safely * using the proxy server

For more information on the different types of connections, see network

SSL mode can also be used for authentication using certificates (see #1252)

When using SSH to connect to a server, encryption and authentication can be skipped: by default the unix domain sockets used by ssh do not use authentication.

### Authentication Modules

Xpra supports many authentication modules. Some of these modules require extra dependencies.

Here is the full list:
list of modules

Module | Result | Purpose
--- | --- | ---
allow | always allows the user to login, the username used is the one supplied by the client | dangerous / only for testing
none | always allows the user to login, the username used is the one the server is running as | dangerous / only for testing
fail | always fails authentication, no password required | useful for testing
reject | always fails authentication, pretends to ask for a password | useful for testing
env | matches against an environment variable (`XPRA_PASSWORD` by default) | alternative to file module
password | matches against a password given as a module option, ie: `auth=password:value=mysecret` | alternative to file module
multifile | matches usernames and passwords against an authentication file | proxy: see password-file below
file | compares the password against the contents of a password file, see password-file below | simple password authentication
pam | linux PAM authentication | Linux system authentication
win32 | win32security authentication | MS Windows system authentication
`sys` | system authentication | virtual module which will choose win32 or pam authentication automatically
sqlite | sqlite database authentication | #1488
peercred | `SO_PEERCRED` authentication |
tcp hosts | TCP Wrapper | #1730
exec | Delegates to an external command | #1690
kerberos-password | Uses kerberos to authenticate a username + password | #1691
kerberos-ticket | Uses a kerberos ticket to authenticate a client | #1691
gss_auth | Uses a GSS ticket to authenticate a client | #1691
ldap | Uses ldap via python-ldap | #1791
ldap3 | Uses ldap via python-ldap3 | #1791
u2f | Universal 2nd Factor | #1789

### Syntax

Starting with version 4.0, the preferred way of specifying authentication is within the socket option itself.
ie for starting a seamless server with a `TCP` socket protected by a password stored in a file:

    xpra start --start=xterm -d auth
         --bind-tcp=0.0.0.0:10000,auth=file:filename=password.txt

So that multiple sockets can use different authentication modules, and those modules can more easily be chained:

    xpra start --start=xterm -d auth \
         --bind-tcp=0.0.0.0:10000,auth=hosts,auth=file:filename=password.txt --bind
         --bind-tcp=0.0.0.0:10001,auth=sys

more examples

- `XPRA_PASSWORD=mysecret xpra start --bind-tcp=0.0.0.0:10000,auth=env`
- `SOME_OTHER_ENV_VAR_NAME=mysecret xpra start --bind-tcp=0.0.0.0:10000,auth=env:name=SOME_OTHER_ENV_VAR_NAME`
- `xpra start --bind-tcp=0.0.0.0:10000,auth=password:value=mysecret`
- `xpra start --bind-tcp=0.0.0.0:10000,auth=file:filename=/path/to/mypasswordfile.txt`
- `xpra start --bind-tcp=0.0.0.0:10000,auth=sqlite:filename=/path/to/userlist.sdb`

Beware when mixing environment variables and password files as the latter may contain a trailing newline character whereas the former often do not.
syntax for older versions

The syntax with older versions used a dedicated switch for each socket type: * `--auth=MODULE` for unix domain sockets and named pipes * `--tcp-auth=MODULE` for TCP sockets * `--vsock-auth=MODULE` for vsock (#983) etc

For more information on the different socket types, see network examples

### Password File

- with the `file` module, the password-file contains a single password, the whole file is the password (including any trailing newline characters). To write a password to a file without the trailing newline character, you can use `echo -n "thepassword" > password.txt`
- with `multifile`, the password-file contains a list of authentication values, see proxy server - this module is deprecated in favour of the `sqlite` module which is much easier to configure

### Usernames

The username can be specified: * in the connection files you can save from the launcher * in the client connection string
tcp example

    xpra attach tcp://username:password@host:port/

When an authentication module is used to secure a single session, many modules will completely ignore the username part and it can be omitted from the connection string.
example: specifying the password only

for connecting to the `TCP` socket and specifying the password only:

    xpra attach tcp://:password@host:port/

Since the username is ignored, it can also be replaced with any string of your liking, ie ‘foobar’:

    xpra attach tcp://foobar:password@host:port/

Only the following modules will make use of both the username and password to authenticate against their respective backend: `kerberos-password`, `ldap`, `ldap3`, `sys` (`pam` and `win32`), `sqlite`, `multifile` and `u2f`. In this case, using an invalid username will cause the authentication to fail.

The username is usually more relevant when authenticating against a proxy server (see authentication details there).

## Development Documentation

Authentication Process
The steps below assume that the client and server have been configured to use authentication: * if the server is not configured for authentication, the client connection should be accepted and a warning will be printed * if the client is not configured for authentication, a password dialog may show up, and the connection will fail with an authentication error if the correct value is not supplied * if multiple authentication modules are specified, the client may bring up multiple authentication dialogs * how the client handles the challenges sent by the server can be configured using the `challenge-handlers` option, by default the client will try the following handlers in the specified order: `uri` (whatever password may have been specified in the connection string), `file` (if the `password-file` option was used), `env` (if the environment variable is present), `kerberos`, `gss`, `u2f` and finally `prompt`
module and platform specific notes

- this information applies to all clients except the HTML5 client: regular GUI clients as well as command line clients like `xpra info`
- each authentication module specifies the type of password hashing it supports (usually HMAC)
- some authentication modules (`pam`, `win32`, `kerberos-password`, `ldap` and `ldap3`) require the actual password to be sent across to perform the authentication on the server - they therefore use the weak `xor` hashing, which is insecure
- you must use encryption to be able to use `xor` hashing so that the password is protected during the exchange: the system will refuse to send a `xor` hashed password unencrypted
- encryption is processed before authentication
- when used over TCP sockets, password authentication is vulnerable to man-in-the-middle attacks where an attacker could intercept the initial exchange and use the stolen authentication challenge response to access the session, encryption prevents that
- the client does not verify the authenticity of the server, using encryption effectively does
- enabling `auth` debug logging may leak some authentication information
- if you are concerned about security, use SSH as transport instead

For more information on packets, see network.
Salt handling is important

- 64-bit entropy is nowhere near enough against a serious attacker: If you want to defend against rainbow tables, salts are inevitable, because you need a full rainbow table per unique salt, which is computationally and storage-wise intense
- SHA-512 w/ per User Salts is Not Enough: In the event the hash was disclosed or the database was compromised, the attacker will already have one of the two values (i.e. the salt), used to construct the hash
- about hmac: Those people should know that HMAC is as easy to precompute as naked SHA1 is; you can “rainbow-table” HMAC* and we did get it wrong before…