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;
char *mechanism = NULL;

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

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.
} 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_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_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. The context will create an instance of the mechanism to use internally and return the name that should be given to the server.

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_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 where 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 either white space or comma separated.

since: 0.1

Hasl.Context:authzid

The identifier for the user who is authenticating. This are times when an administrator wants to authenticate as a user, so they property will be set to the username of the user to authenticate as, but the username and password fields will be proper values for the administrator.

since: 0.1

Hasl.Context:password

The password to use for mechanisms that need it.

since: 0.1

Hasl.Context:tls

Tells the context whether or not the connection is being ran on is 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.