Authentication
Define users in the configuration, give each slot a list of users and permissions, and have clients log in with u and p.
No Ghoti listener implements TLS, so the p command, and the HTTP Basic Auth header on the http transport, carry the password in the clear. Anyone who can observe the traffic can read it. Terminate TLS in a reverse proxy or load balancer in front of the server, or keep the traffic on loopback or an equivalent trusted network. See SECURITY.md for the full security model.
Users#
Define users and passwords in a top-level users map:
users:
my_service: "my_password"
other_service: "another_password"
upstream: "123456"
Usernames and passwords follow the login rules below. A user that breaks them stops the server at startup.
The users block is read as a map, and map entries can't be injected from GHOTI_ environment variables, so user passwords have to come from the configuration file. Keep that file outside the repository, owned by the service user and readable only by it. See SECURITY.md.
Slot permissions#
Each slot can have its own users map, giving each user one of three permissions:
| Value | Permission |
|---|---|
r | Read only |
w | Write only |
a | All: read and write |
slot_001:
kind: simple_memory
users:
my_service: "r"
other_service: "w"
upstream: "a"
slot_002:
kind: simple_memory
users:
my_service: "a"
slot_003:
kind: simple_memory
With this configuration my_service can read slots 001 and 002 but only write slot 002.
users map is open to everyone
Slot 003 above has no users, so anyone can read and write it, logged in or not. As soon as a slot has a users map, anonymous connections and unlisted users can't use it.
- A read without read permission fails with
008(READ_PERMISSION), and a write without write permission with006(WRITE_PERMISSION). Over HTTP both are403. sanddneed read permission.- Broadcast events reach every connection, and every SSE stream, regardless of the slot's permissions. Permissions control who can read and write a broadcast slot, not who receives its events. Don't put anything in a broadcast slot that every connected client must not see.
Logging in#
On standard and telnet, a client logs in with u followed by the username, then p followed by the password. Both answer v and the username:
> umy_service
< vmy_service
> pmy_password
< vmy_service
> w000secret
< v000secret
Every later command on that connection runs as the logged-in user. On the http transport there is no login exchange: send the credentials as an HTTP Basic Auth header on every request. A request without the header is anonymous, and a request with wrong credentials gets 401.
Login rules#
A client has to follow these rules exactly:
- Send both commands, in order.
uonly records the name on the connection. It doesn't check the name against the configured users, souwith an unknown name still answersvand that name. Credentials are only verified whenparrives. A connection that sendsuand never sendspstays anonymous. - Username and password must each be at least 4 bytes long, and at most 39, the limit of a 40-byte request. The username must also match
^[a-zA-Z][a-zA-Z0-9_]*$: it starts with a letter and continues with letters, digits or underscores. - Any login failure closes the connection. The server writes the error and disconnects, so the client has to open a new connection to try again. This applies to a malformed username (
002), a password that is too short (003), and a username and password that don't match the configuration (004). - A
prequest shorter than the 4-byte protocol minimum, such aspab, is a parse error (exxx001) rather than003, and the connection stays open. - Sending
uagain on an authenticated connection drops the authentication: the connection is anonymous until a matchingpis accepted.
Captured failures, each on a new connection:
> umy_service
< vmy_service
> pwrong_pass
< exxx004
# connection closed
> u1bad
< exxx002
# connection closed