Protocol specification - orthanner/coreauth GitHub Wiki

Coreauth protocol is plaintext, with exactly one line representing a single request/response. Lines are separated with \r\n. All binary data are encoded using [Base64](https://en.wikipedia.org/wiki/Base64 base64). Negative server responses are of form -(?:<comment>)? and may contain single-line comments indicating the reason of failure if it matters, however, a client should not rely on their presence. Positive replies that indicate the successful completion of operation are of form +(?:<reply>)?

starttls (?<key>[\w]+)

(optional request) Initiates SSL connection using Diffie-Hellman algorithm. Upon completion, previously established session (if any) will be discarded and all communication will go encrypted. Parameters:

• key client's public key

Reply may be safely ignored. Fails if TLS is unsupported by the server (that is, not configured).

auth (?<login>[^@]+)@(?<realm>[^\s]+) (?<password>[\w]+)

authentication request. Parameters are self-explanatory. A realm is generally an isolated subsistem or program system. It has it's own set of permissions. Password is sent as SHA-512 hash of UTF-8-encoded string. Reply:

• token session identifier (if the client has successfully authenticated)

check (?<token>[A-F0-9]+) (?<tag>[.:\-\w]+) (?<perm>[:.\w]+)

checks whether the user has the permission specified. Parameters:

• token session identifier
• tag client's tag (either "ip:<address>" or "key:<certificate>" depending on whether TLS is used or not)
• perm permission to check

Completes successfully if (and only if) the client specified by token and tag has the permission specified

logout (?<token>[A-F0-9]+)

ends the session identified by token and closes the connection. Reply may be safely ignored.

get (?<token>[A-F0-9]+)/(?<attr>[\w.\-_:]+)

retrieves the value of the specified attribute.

• token session identifier
• attr attribute name

Reply format:

• type:value attribute type and value ($ is the attribute is null)

fails if the operation is not permitted.

set (?<token>[A-F0-9]+)/(?<attribute>[\w.\-_:]+)=(?<type>[\w]+):(?<value>[\w]*|\$)

sets the attribute of the user account bound to the specified token to value of type (where $ indicates a null value). Returns count of updated attributes (0 or 1) if the update has completed successfully.

unset (?<token>[A-Fa-f0-9]+)/(?<attr>[\w.\-_:]+)

removes the specified attr from the account bound to session designated by token