sigildocs

(sigil irc sasl)

(sigil irc sasl) - SASL authentication state machines

SASL is the AUTHENTICATE-based authentication protocol used by IRCv3. The on-the-wire pattern, in both directions, is:

<- AUTHENTICATE PLAIN              (client picks mechanism)
-> AUTHENTICATE +                  (server says: send payload)
<- AUTHENTICATE <base64-chunk>     (client sends payload, in
   AUTHENTICATE <next-chunk>      400-byte base64 chunks)
   ...
   AUTHENTICATE +                  (last chunk shorter than 400
                                    OR an explicit empty `+`
                                    when the payload was an
                                    exact multiple of 400)
-> 900 / 903                        (success — RPL-LOGGEDIN /
                                    RPL-SASLSUCCESS)
   OR 902/904/905/906/907          (failure)

Mechanisms supported here:

PLAIN base64(authzid 0 authcid 0 password) — ships fully EXTERNAL base64(authzid) (TLS client cert) — ships fully SCRAM-SHA-256 RFC 5802 challenge-response — see (sigil irc sasl-scram)

The state machines are pure values: state + advance returning outbound wire strings. The consumer owns I/O.

Exports

encode-authenticate-payloadprocedure

Encode a raw payload (string) as a list of AUTHENTICATE lines per the IRCv3 SASL chunking rules. Each line carries up to 400 base64 chars; if the encoded payload length is an exact multiple of 400, an additional AUTHENTICATE +\r\n is appended as the explicit terminator. An empty payload produces a single AUTHENTICATE +\r\n.

Returns a list of complete wire-format lines (each ending in CRLF). The consumer writes them in order.

decode-authenticate-chunksprocedure

Reassemble a list of incoming AUTHENTICATE chunk strings (just the base64 portion of each, without the AUTHENTICATE keyword) into the decoded raw payload. A trailing + chunk is the terminator and is stripped before decoding. A single + chunk by itself is treated as an empty payload signal.

Returns a string. (sigil-crypto's base64-decode returns a bytevector for arbitrary inputs; we convert here so the payload is consumable by string-split etc.)

plain-payloadprocedure

Build the raw PLAIN payload (pre-base64): authzid 0 authcid 0 password. authzid may be #f (empty); authcid and password are required.

parse-plain-payloadprocedure

Parse a raw PLAIN payload back into (authzid authcid password). Returns three values; if malformed, returns three #f values.

%sasl-client-state--typevariable

Parse a raw PLAIN payload back into (authzid authcid password). Returns three values; if malformed, returns three #f values.

sasl-client-stateprocedure

Construct a sasl-client-state struct.

sasl-client-state?procedure

Test if a value is a sasl-client-state struct.

sasl-client-state-mechanismprocedure

Get the mechanism field of a sasl-client-state struct.

sasl-client-state-authcidprocedure

Get the authcid field of a sasl-client-state struct.

sasl-client-state-passwordprocedure

Get the password field of a sasl-client-state struct.

sasl-client-state-authzidprocedure

Get the authzid field of a sasl-client-state struct.

sasl-client-state-phaseprocedure

Get the phase field of a sasl-client-state struct.

sasl-client-state-resultprocedure

Get the result field of a sasl-client-state struct.

sasl-client-state-scram-driverprocedure

Get the scram-driver field of a sasl-client-state struct.

set-sasl-client-state-phase!procedure

Set the phase field of a sasl-client-state struct.

set-sasl-client-state-result!procedure

Set the result field of a sasl-client-state struct.

set-sasl-client-state-scram-driver!procedure

Set the scram-driver field of a sasl-client-state struct.

make-sasl-client-statevariable

Construct a client SASL state. mechanism must be one of the SASL-* constants. For PLAIN/SCRAM-SHA-256 supply authcid: and password:; for EXTERNAL supply only authzid: if you want to assert a specific identity (otherwise empty = use the cert's CN).

sasl-client-startprocedure

Begin SASL: returns the AUTHENTICATE <mech>\r\n line to send, transitions to the 'awaiting-server-+ phase. The CAP layer is expected to have already negotiated sasl.

sasl-client-advanceprocedure

Process one incoming message and advance the state. Returns a list of wire-format strings to send.

sasl-server-stateprocedure

Construct a sasl-server-state struct.

sasl-server-state?procedure

Test if a value is a sasl-server-state struct.

sasl-server-state-supported-mechanismsprocedure

Get the supported-mechanisms field of a sasl-server-state struct.

sasl-server-state-mechanismprocedure

Get the mechanism field of a sasl-server-state struct.

sasl-server-state-phaseprocedure

Get the phase field of a sasl-server-state struct.

sasl-server-state-resultprocedure

Get the result field of a sasl-server-state struct.

sasl-server-state-verifyprocedure

Get the verify field of a sasl-server-state struct.

sasl-server-state-chunksprocedure

Get the chunks field of a sasl-server-state struct.

sasl-server-state-authcidprocedure

Get the authcid field of a sasl-server-state struct.

sasl-server-state-server-nameprocedure

Get the server-name field of a sasl-server-state struct.

sasl-server-state-scram-driverprocedure

Get the scram-driver field of a sasl-server-state struct.

set-sasl-server-state-mechanism!procedure

Set the mechanism field of a sasl-server-state struct.

set-sasl-server-state-phase!procedure

Set the phase field of a sasl-server-state struct.

set-sasl-server-state-result!procedure

Set the result field of a sasl-server-state struct.

set-sasl-server-state-chunks!procedure

Set the chunks field of a sasl-server-state struct.

set-sasl-server-state-authcid!procedure

Set the authcid field of a sasl-server-state struct.

set-sasl-server-state-scram-driver!procedure

Set the scram-driver field of a sasl-server-state struct.

sasl-server-advancevariable

Process one incoming AUTHENTICATE and advance the state. Returns a list of wire-format strings to send back. client-prefix is the client's nick (or * if unknown) used in numeric prefixes.

SASL-PLAINvariable

(No description)

SASL-EXTERNALvariable

(No description)

SASL-SCRAM-SHA-256variable

(No description)

make-sasl-server-statevariable

(No description)