Authentication

• XPRA_PASSWORD=mysecret xpra seamless --bind-tcp=0.0.0.0:10000,auth=env
• SOME_OTHER_ENV_VAR_NAME=mysecret xpra seamless --bind-tcp=0.0.0.0:10000,auth=env(name=SOME_OTHER_ENV_VAR_NAME)
• xpra seamless --bind-tcp=0.0.0.0:10000,auth=password(value=mysecret)
• xpra seamless --bind-tcp=0.0.0.0:10000,auth=file(filename=/path/to/mypasswordfile.txt)
• xpra seamless --bind-tcp=0.0.0.0:10000,auth=sqlite(filename=/path/to/userlist.sdb)
• xpra seamless --bind-tcp=0.0.0.0:10000,auth=otpscreen(mode=alphanumeric,count=8,timeout=60)

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

The otpscreen module accepts the following options: mode (digits, alpha or alphanumeric, default digits), count (number of characters in the generated secret, default 6), timeout (how long the dialog stays up, in seconds, default 120), and display (which display to open the dialog on, default auto which reuses the server's saved DISPLAY / WAYLAND_DISPLAY).

The ratelimit module protects a socket against brute force attacks: it records how many times each client IP address has recently failed to authenticate, delays the ones that keep failing, and eventually rejects them outright.

It does not authenticate anyone by itself - it is a gate that must be chained before a real authentication module, and it must be listed first so that a blocked address is turned away before the server even sends it a challenge:

xpra start --bind-tcp=0.0.0.0:10000 \
  --tcp-auth=ratelimit(max-failures=3,window=60,ipv6-prefix=64) \
  --tcp-auth=password(value=mysecret)

Once max-failures is reached, the client is rejected until the window expires: the rejected attempts are not counted again, so a legitimate user who gets locked out always recovers after window seconds.

An attacker usually controls an entire IPv6 subnet, so limiting each individual IPv6 address (the default) is easily bypassed by picking a new one for each attempt - use ipv6-prefix=64 to count a whole /64 together.

Loopback addresses, unix domain sockets and named pipes are never rate limited.

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

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

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 using foobar here:

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

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), scram, kerberos, gss, keycloak, u2f and finally prompt

• 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.

A new server-side authentication module is a Python file in xpra/auth/ that defines a class named Authenticator. Two base classes are provided:

• SysAuthenticatorBase — the minimal base. Use this when the username does not need to map to a local system account (e.g. token-based or capability-based authenticators).
• SysAuthenticator (in the same file) — extends the base by loading the local pwd entry for self.username on POSIX. Use this when the module is tied to system users (pam, peercred, exec, etc.).

The methods most commonly overridden:

Helpers in xpra/auth/common.py:

• SessionData — the (uid, gid, displays, env_options, session_options) 5-tuple returned by get_sessions()
• parse_uid(v) / parse_gid(v) — accept either a numeric string or a username/group name, with safe defaults
• get_auth_exec_env(display="auto") — environment dictionary suitable for spawning helper processes (used by exec and otpscreen)

Authenticator instances are constructed by auth_helper.get_auth_module(), which parses the auth=NAME(opt=value,...) syntax and imports xpra.auth.<name>. Each socket can chain multiple authenticators; the first one to require a challenge issues it and subsequent ones either verify additional caps or contribute to get_sessions().

Multi-step authenticators keep their state on the Authenticator instance. After authenticate(caps) succeeds, the server calls get_next_challenge(): return () when the authenticator is complete, or return (challenge_bytes, digest_name, prompt) to send another challenge packet. The next client response arrives in caps["challenge_response"] and is processed by the same authenticator.

Three optional callbacks are called on the authenticators of a connection, if they are defined:

A new Authenticator is instantiated for every connection, so a module that needs to remember something across connections (like ratelimit, which counts the failures of each client IP) must keep that state at the class level and protect it with a lock: verify_auth runs in a separate thread for each connection.

A new client-side challenge handler is a Python file in xpra/challenge/ that defines a class named Handler implementing AuthenticationHandler.

For multi-step handlers, keep protocol state on the handler instance. When handle() returns a response and is_done() is False, the client keeps that handler at the front of the handler list so the next server challenge is routed back to it.

• 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...