Auth Client

Auth Client¶

The auth client is a simple SASL implementation supporting the SMTP AUTH extension.

void auth_client_init(void)¶: Initialise the auth client.

Parameters

void: no arguments

Description

Perform any preparation necessary for the auth client modules. Call this before any other auth client APIs.

void auth_client_exit(void)¶: Destroy the auth client.

Parameters

void: no arguments

Description

This clears any work done by auth_client_init() or any global state that may be created by the authentication modules. Auth client APIs after this is called may fail unpredictably or crash.

auth_context_t auth_create_context(void)¶: Create an authentication context.

Parameters

void: no arguments

Description

Create a new authentication context.

Return

The typedef auth_context_t.

int auth_destroy_context(auth_context_t context)¶: Destroy an authentication context.

Parameters

auth_context_t context: The authentication context.

Description

Destroy an authentication context, releasing any resources used.

Return

Zero on failure, non-zero on success.

int auth_set_mechanism_flags(auth_context_t context, unsigned set, unsigned clear)¶: Set authentication flags.

Parameters

auth_context_t context: The authentication context.
unsigned set: Flags to set.
unsigned clear: Flags to clear.

Description

Configure authentication mechanism flags which may affect operation of the authentication modules. The AUTH_PLUGIN_EXTERNAL flag is excluded from the allowable flags.

Return

Zero on failure, non-zero on success.

int auth_set_mechanism_ssf(auth_context_t context, int min_ssf)¶: Set security factor.

Parameters

auth_context_t context: The authentication context.
int min_ssf: The minimum security factor.

Description

Set the minimum acceptable security factor. The exact meaning of the security factor depends on the authentication type.

Return

Zero on failure, non-zero on success.

int auth_set_external_id(auth_context_t context, const char *identity)¶: Set the external id.

Parameters

auth_context_t context: The authentication context.
const char *identity: Authentication identity.

Description

Set the authentication identity for the EXTERNAL SASL mechanism. This call also configures the built-in EXTERNAL authenticator.

The EXTERNAL mechanism is used in conjunction with authentication which has already occurred at a lower level in the network stack, such as TLS. For X.509 the identity is normally that used in the relevant certificate.

Return

Zero on failure, non-zero on success.

int auth_client_enabled(auth_context_t context)¶: Check if mechanism is enabled.

Parameters

auth_context_t context: The authentication context.

Description

Perform various checks to ensure SASL is usable.

Note that this does not check for loaded plugins. This is checked when negotiating a mechanism with the MTA.

Return

Non-zero if the SASL is usable, zero otherwise.

int auth_set_mechanism(auth_context_t context, const char *name)¶: Select authentication mechanism.

Parameters

auth_context_t context: The authentication context.
const char *name: Name of the authentication mechanism.

Description

Perform checks, including acceptable security levels and select the authentication mechanism if successful.

Return

Zero on failure, non-zero on success.