gigapxy.auth − Gigapxy authentication manual.


gws employs helpers − custom scripts − to authenticate and authorize incoming user requests. Any application reading from STDIN and responding via STDOUT could serve as a helper as long as it ’speaks’ one of the two communication protocols: A1P or B2P. This page is dedicated to giving the insight into auth helpers, employed protocols and associated capabilities.

Common features:
Both protocols have things in common. Firstly, they are textual and line-oriented: a message is a text string ending with CRLF ASCII sequence (single LF symbol under Linux and FreeBSD). gws writes messages/lines to helpers via unnamed pipes connecting to the helpers’ STDIN.

Message example: B10 P

Messages contain fields separated by whitespace. An empty (blank) value is always specified as − (dash). Some fields are common for both protocols, the first field is always the same: Session ID.

Session-ID = A|B{1 .. 2147483647} [examples: A100, A1, B150433]
Identifies the request. The first symbol is protocol_id: ’A’ for A1P and ’B’ for B2P. The rest of the field is session_number - non-zero 32-bit unsigned decimal integer; session ID in the incoming message should match the one in the response.

Result-Code = {0 .. 2147483647} [examples: 0, 1, 111]
32-bit unsigned decimal integer, specifies the result of the evaluation. Only 0 (zero) code is treated as APPROVE response, all others currently signify authorization failure.

A1P request:
A1P uses pre-defined sequence of mandatory and optional fields in each request/response message.

The request fields are: Session-ID Peer Source Destination [Listener] (the last field is optional and is added only if ws.auth.aux_params value contains listener-alias).

A1P request example: A102 udp:// - bb1

Peer = address:port
Address/port of the client (that sent the original request to gws)

Source = channel URL
URL of the requested channel, as specified either in udp or src section of the request URL.

Destination = client URL
URL for the destination. For most requests, destination is the socket/connection that started the request (i.e. peer), empty value (dash) is used to specify it.

Listener = alias
Alias of the listener that accepted the request. Do mind that when using this option, alias must be specified for each listener in gws.conf.

A1P response:
A1P response example: A102 0

B2P protocol
B2P is an extension of A1P protocol that mainly addresses the inflexibility of A1P (fixed number of fields come in and come out). The core features that drove towards creating a new protocol were: a) custom URLs and b) endpoint (source/destination) re-write capability. B2P accommodates both of these features and provides future expansion of functionality. B2P adds one mandatory field to Session-ID, the Field-Mask.

Field-Mask = [a-z][A-Z]{16} [example: USDP]
Specifies the fields (up to 16) that will follow (in the order they will appear). A single symbol is designated to each of the recognized fields, the mask is, in effect, a sequence of field identifiers.

Field identifiers:
= Request-URL - the B2P field that holds URL for the HTTP request,
the way it was in the header. Example: /udp/
= Source
= Destination
= Peer
= User-Agent
= Listener
= Result-Code

Field-Mask ’USDP’ means that the message, besides the mandatory two fields, must have four fields of the corresponding types. gws.conf provides ws.auth.b_fields setting to specify what information gws will send to auth helpers with every B2P message.

B2P request:
Example B2P request: B102 UPL /udp/ bb1

Some fields (r) don’t make much sense in the request and will be rejected by gws if specified.

B2P response:
It’s up to the helper implementation what set of fields would be returned, but at least one field should be. Absense of Result-Code is assumed as APPROVE as long as other fields are present in the response. With all the flexibility, only certain fields will be accepted in by gws in the response message.

Response-approved fields:
= source will be re-written to the returned value
= destination will be re-written to the returned value
= APPROVE if 0, DENY otherwise.

A typical B2P denial response would be: B102 r 111 (Don’t you worry about 111, any non-zero number would do).

Custom URLs and source re-write
B2P (and appropriate settings in ws.auth config section) allows completely opaque URLs to be converted to gigapxy-compliant source/destination pairs. Request-URL field matched to helper-specific endpoints allows to reply with the appropriate Source (and Destination is needed) and let gws know what the endpoints are.

Here’s an example scenario:

GET /dc03d03332f09a is the original HTTP request as read by gws.

The auth config specifies:
auth: {
enabled = true;
helper_protocol = "B2P";
b_fields = "USP";
exec = "/usr/local/bin/ /var/log/gigapxy/auth.log";
deny_no_auth = true;
can_rewrite_endpoints = true;
allow_custom_urls = true;

allow_custom_urls lets gws ignore that the URL could not be parsed into gigapxy endpoints, so both Source and Destination remain empty after request has been parsed.

gws sends a B2P request: B1 USP /dc03d03332f09a -

Please note that Source is empty in the request and could be omitted if we know it’s never needed by the helper. The helper translates the data (using its own logic) into the following response:

B1 S udp://

gws reads the response and assumes the request is APPROVED (no r field but another field present). It then takes udp:// as the source endpoint, directing to read from the given multicast channel.

Where do I begin?
Having decided which features you’d need and thus which protocol to select, make a copy of the corresponding example helper in /usr/share/gigapxy/scrpts under Linux (/usr/local/share/.. under FreeBSD). If you understand the logic, but dislike /bin/sh, use any other language. Once your helper (kind of) works, make a text file (requests.txt) with sample requests (the kind you’d be most likely processing) and run:

cat requests.txt | auth-helper /var/log/helper.log

The output will be the response messages. If somethig does not quite work, the log (where your script writes) should help.


Pavel V. Cherenkov