Class

HaslContext

since: 0.1

Description [src]

final class Hasl.Context : GObject.Object
{
  /* No available fields */
}

The context holds all of the data that the client knows about for authentication. The HaslMechanisms use this data to authenticate.

A client can limit which mechanisms the context will use with hasl_context_set_allowed_mechanisms().

The context also keeps track of which mechanisms have been tried and will mark one as failed when hasl_context_next() is called. The client then can call hasl_context_get_current_mechanism() and repeat until successfully authenticated or all mechanisms have been exhausted.

A simple example is found below.

// After you connect to the server, you can create your context and start
// the authentication process.
HaslContext *context = NULL;
const char *mechanism = NULL;

context = hasl_context_new();
hasl_context_set_username(context, "alice");
hasl_context_set_password(context, "hunter2");

// If the user specified any mechanisms you can set them like so.
hasl_context_set_allowed_mechanisms(context, "PLAIN,EXTERNAL");

// If the server advertised any mechanisms you can set them like so.
hasl_context_set_server_mechanisms(context, server_mechanisms);

// Next will use allowed mechanisms if set, otherwise it will fallback to
// server mechanisms. If neither are set, the result of
// hasl_context_get_supported_mechanisms will be used.
mechanism = hasl_context_next(context);

// Attempt your authentication using the mechanism name stored in
// mechanism.
// In your receive handler you can now pass the data into hasl_context_step.
HaslMechanismResult res;
GError *error = NULL;
guint8 *client_out = NULL;
gsize client_out_length = 0;

// Note that if client_out is not NULL it is your responsibility to free it.
res = hasl_context_step(context, server_input, server_input_length,
                        &client_out, &client_out_length, &error);

if(res == HASL_MECHANISM_RESULT_ERROR) {
    char *mechanism = NULL;

    // Possibly handle error.

    // Tell the context to try the next mechanism.
    mechanism = hasl_context_next(context);

    // If you don't have any more mechanisms, authentication failed.
    if(mechanism == NULL) {
        // Terminate connection.
    }

    // Tell the server you would like to try another mechanism with the
    // value stored in mechanism.
} else if(res == HASL_MECHANISM_RESULT_SUCCESS) {
    // Authentication complete.

    // Optionally you can call done on the context to reset it for reuse
    // later.
    hasl_context_done(context);
} else if(res == HASL_MECHANISM_CONTINUE) {
    // Otherwise send client_out to the server.
}

g_free(client_out);

Available since: 0.1

Ancestors

Constructors

hasl_context_new

Creates a new context.

since: 0.1

Instance methods

hasl_context_add_mechanism

Registers type in ctx with the given name. name should follow the convention from RFC4422ยง3.1.

since: 0.1

hasl_context_done

Sets the context to done and resets it.

since: 0.4

hasl_context_get_allow_clear_text

Gets whether or not it’s okay to use mechanisms that use clear text with a non-TLS connection. Clear text methods are ones that use credentials directly like the PLAIN mechanism which depend on TLS to secure the credentials.

since: 0.1

hasl_context_get_allowed_mechanisms

Gets the list of allowed mechanisms for ctx.

since: 0.1

hasl_context_get_authzid

Gets the authzid of ctx. See HaslContext:authzid for more information.

since: 0.1

hasl_context_get_current_mechanism

Gets the name of the current mechanism that ctx is attempting.

since: 0.1

hasl_context_get_password

Gets the password from ctx.

since: 0.1

hasl_context_get_server_mechanisms

Gets the server mechanisms from a context.

since: 0.4

hasl_context_get_supported_mechanisms

Gets a space separated alphabetically sorted list of all the mechanisms that ctx knows about.

since: 0.1

hasl_context_get_tls

Gets whether or not ctx is working with a TLS connection.

since: 0.1

hasl_context_get_username

Gets the username that has been set on ctx.

since: 0.1

hasl_context_next

Ask the context to move to the next possible mechanism.

since: 0.1

hasl_context_set_allow_clear_text

Sets whether or not mechanisms that depend on clear text credentials are allowed. The PLAIN mechanism is an example of a clear text based mechanism as it depends on TLS to secure the credentials.

since: 0.1

hasl_context_set_allowed_mechanisms

Sets the list of mechanism that are allowed for ctx.

since: 0.1

hasl_context_set_authzid

Sets the authzid of ctx to authzid. See HaslContext:authzid for more information.

since: 0.1

hasl_context_set_password

Sets the password for ctx to password.

since: 0.1

hasl_context_set_server_mechanisms

Sets the mechanisms that the server has advertised.

since: 0.4

hasl_context_set_tls

Sets whether or not ctx is working with a TLS connection to tls.

since: 0.1

hasl_context_set_username

Sets the username of ctx to username.

since: 0.1

hasl_context_step

Calls hasl_mechanism_step() for the currently active mechansim in ctx.

since: 0.1

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Properties

Hasl.Context:allow-clear-text

Determines whether or not mechanisms that depend on transport layer encryption like TLS are allowed to be used on a non-TLS connection.

Hasl.Context:allowed-mechanisms

A list of mechanisms that are allowed to be used by this context. This list can be separated by white space, commas, or a combination of both.

since: 0.1

Hasl.Context:authzid

The identifier for the user who is authenticating.

since: 0.1

Hasl.Context:password

The password to use for mechanisms that need it.

since: 0.1

Hasl.Context:server-mechanisms

A list of mechanisms that the server advertised. This list can be separated by white space, commas, or a combination of both.

since: 0.4

Hasl.Context:tls

Tells the context whether or not the connection is being run over TLS or not.

since: 0.1

Hasl.Context:username

The username of the user that is authenticating for mechanisms that need it.

since: 0.1

Signals

Signals inherited from GObject (1)
GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct HaslContextClass {
  GObjectClass parent_class;
  
}

No description available.

Class members
parent_class: GObjectClass

No description available.