GSASL_VERSION

# define GSASL_VERSION "0.2.15"

String defined via CPP denoting the header file version number. Used together with stringprep_check_version() to verify header file and run-time library consistency.

GSASL_VALID_MECHANISM_CHARACTERS

  extern const char *GSASL_VALID_MECHANISM_CHARACTERS;

A zero-terminated character array, or string, with all ASCII characters that may be used within a SASL mechanism name.

enum Gsasl_rc

  typedef enum
  {
    GSASL_OK = 0,
    GSASL_NEEDS_MORE = 1,
    GSASL_UNKNOWN_MECHANISM = 2,
    GSASL_MECHANISM_CALLED_TOO_MANY_TIMES = 3,
    GSASL_MALLOC_ERROR = 7,
    GSASL_BASE64_ERROR = 8,
    GSASL_CRYPTO_ERROR = 9,
    GSASL_SASLPREP_ERROR = 29,
    GSASL_MECHANISM_PARSE_ERROR = 30,
    GSASL_AUTHENTICATION_ERROR = 31,
    GSASL_INTEGRITY_ERROR = 33,
    GSASL_NO_CLIENT_CODE = 35,
    GSASL_NO_SERVER_CODE = 36,
    GSASL_NO_CALLBACK = 51,
    GSASL_NO_ANONYMOUS_TOKEN = 52,
    GSASL_NO_AUTHID = 53,
    GSASL_NO_AUTHZID = 54,
    GSASL_NO_PASSWORD = 55,
    GSASL_NO_PASSCODE = 56,
    GSASL_NO_PIN = 57,
    GSASL_NO_SERVICE = 58,
    GSASL_NO_HOSTNAME = 59,
    /* Mechanism specific errors. */
    GSASL_GSSAPI_RELEASE_BUFFER_ERROR = 37,
    GSASL_GSSAPI_IMPORT_NAME_ERROR = 38,
    GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR = 39,
    GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR = 40,
    GSASL_GSSAPI_UNWRAP_ERROR = 41,
    GSASL_GSSAPI_WRAP_ERROR = 42,
    GSASL_GSSAPI_ACQUIRE_CRED_ERROR = 43,
    GSASL_GSSAPI_DISPLAY_NAME_ERROR = 44,
    GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR = 45,
    GSASL_KERBEROS_V5_INIT_ERROR = 46,
    GSASL_KERBEROS_V5_INTERNAL_ERROR = 47,
    GSASL_SHISHI_ERROR = GSASL_KERBEROS_V5_INTERNAL_ERROR,
    GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE = 48,
    GSASL_SECURID_SERVER_NEED_NEW_PIN = 49
  } Gsasl_rc;

enum Gsasl_qop

  typedef enum
  {
    GSASL_QOP_AUTH = 1,
    GSASL_QOP_AUTH_INT = 2,
    GSASL_QOP_AUTH_CONF = 4
  } Gsasl_qop;

enum Gsasl_cipher

  typedef enum
  {
    GSASL_CIPHER_DES = 1,
    GSASL_CIPHER_3DES = 2,
    GSASL_CIPHER_RC4 = 4,
    GSASL_CIPHER_RC4_40 = 8,
    GSASL_CIPHER_RC4_56 = 16,
    GSASL_CIPHER_AES = 32
  } Gsasl_cipher;

enum Gsasl_saslprep_flags

  typedef enum
  {
    GSASL_ALLOW_UNASSIGNED = 1
  } Gsasl_saslprep_flags;

Gsasl

  typedef struct Gsasl Gsasl;

Gsasl_session

  typedef struct Gsasl_session Gsasl_session;

enum Gsasl_property

  typedef enum
  {
    /* Information properties, e.g., username. */
    GSASL_AUTHID = 1,
    GSASL_AUTHZID = 2,
    GSASL_PASSWORD = 3,
    GSASL_ANONYMOUS_TOKEN = 4,
    GSASL_SERVICE = 5,
    GSASL_HOSTNAME = 6,
    GSASL_GSSAPI_DISPLAY_NAME = 7,
    GSASL_PASSCODE = 8,
    GSASL_SUGGESTED_PIN = 9,
    GSASL_PIN = 10,
    GSASL_REALM = 11,
    /* Server validation callback properties. */
    GSASL_VALIDATE_SIMPLE = 500,
    GSASL_VALIDATE_EXTERNAL = 501,
    GSASL_VALIDATE_ANONYMOUS = 502,
    GSASL_VALIDATE_GSSAPI = 503,
    GSASL_VALIDATE_SECURID = 504
  } Gsasl_property;

Gsasl_callback_function ()

int         (*Gsasl_callback_function)      (Gsasl *ctx,
                                             Gsasl_session *sctx,
                                             Gsasl_property prop);

Prototype of function that the application should implement. Use gsasl_callback_set() to inform the library about your callback function.

It is called by the SASL library when it need some information from the application. Depending on the value of prop, it should either set some property (e.g., username or password) using gsasl_property_set(), or it should extract some properties (e.g., authentication and authorization identities) using gsasl_property_fast() and use them to make a policy decision, perhaps returning GSASL_AUTHENTICATION_ERROR or GSASL_OK depending on whether the policy permitted the operation.

Since 0.2.0

gsasl_init ()

int         gsasl_init                      (Gsasl **ctx);

This functions initializes libgsasl. The handle pointed to by ctx is valid for use with other libgsasl functions iff this function is successful. It also register all builtin SASL mechanisms, using gsasl_register().

gsasl_done ()

void        gsasl_done                      (Gsasl *ctx);

This function destroys a libgsasl handle. The handle must not be used with other libgsasl functions after this call.

gsasl_check_version ()

const char* gsasl_check_version             (const char *req_version);

Check library version.

See GSASL_VERSION for a suitable req_version string.

gsasl_callback_set ()

void        gsasl_callback_set              (Gsasl *ctx,
                                             Gsasl_callback_function cb);

Store the pointer to the application provided callback in the library handle. The callback will be used, via gsasl_callback(), by mechanisms to discover various parameters (such as username and passwords). The callback function will be called with a Gsasl_property value indicating the requested behaviour. For example, for GSASL_ANONYMOUS_TOKEN, the function is expected to invoke gsasl_property_set(CTX, GSASL_ANONYMOUS_TOKEN, "token") where "token" is the anonymous token the application wishes the SASL mechanism to use. See the manual for the meaning of all parameters.

Since 0.2.0

gsasl_callback ()

int         gsasl_callback                  (Gsasl *ctx,
                                             Gsasl_session *sctx,
                                             Gsasl_property prop);

Invoke the application callback. The prop value indicate what the callback is expected to do. For example, for GSASL_ANONYMOUS_TOKEN, the function is expected to invoke gsasl_property_set(SCTX, GSASL_ANONYMOUS_TOKEN, "token") where "token" is the anonymous token the application wishes the SASL mechanism to use. See the manual for the meaning of all parameters.

Note that if no callback has been set by the application, but the obsolete callback interface has been used, this function will translate the old callback interface into the new. This interface should be sufficient to invoke all callbacks, both new and old.

Since 0.2.0

gsasl_callback_hook_set ()

void        gsasl_callback_hook_set         (Gsasl *ctx,
                                             void *hook);

Store application specific data in the libgsasl handle.

The application data can be later (for instance, inside a callback) be retrieved by calling gsasl_callback_hook_get(). This is normally used by the application to maintain a global state between the main program and callbacks.

Since 0.2.0

gsasl_callback_hook_get ()

void*       gsasl_callback_hook_get         (Gsasl *ctx);

Retrieve application specific data from libgsasl handle.

The application data is set using gsasl_callback_hook_set(). This is normally used by the application to maintain a global state between the main program and callbacks.

Since 0.2.0

gsasl_session_hook_set ()

void        gsasl_session_hook_set          (Gsasl_session *sctx,
                                             void *hook);

Store application specific data in the libgsasl session handle.

The application data can be later (for instance, inside a callback) be retrieved by calling gsasl_session_hook_get(). This is normally used by the application to maintain a per-session state between the main program and callbacks.

Since 0.2.14

gsasl_session_hook_get ()

void*       gsasl_session_hook_get          (Gsasl_session *sctx);

Retrieve application specific data from libgsasl session handle.

The application data is set using gsasl_callback_hook_set(). This is normally used by the application to maintain a per-session state between the main program and callbacks.

Since 0.2.14

gsasl_property_set ()

void        gsasl_property_set              (Gsasl_session *sctx,
                                             Gsasl_property prop,
                                             const char *data);

Make a copy of data and store it in the session handle for the indicated property prop.

You can immediately deallocate data after calling this function, without affecting the data stored in the session handle.

Since 0.2.0

gsasl_property_set_raw ()

void        gsasl_property_set_raw          (Gsasl_session *sctx,
                                             Gsasl_property prop,
                                             const char *data,
                                             size_t len);

Make a copy of len sized data and store a zero terminated version of it in the session handle for the indicated property prop.

You can immediately deallocate data after calling this function, without affecting the data stored in the session handle.

Except for the length indicator, this function is identical to gsasl_property_set.

Since 0.2.0

gsasl_property_get ()

const char* gsasl_property_get              (Gsasl_session *sctx,
                                             Gsasl_property prop);

Retrieve the data stored in the session handle for given property prop, possibly invoking the application callback to get the value.

The pointer is to live data, and must not be deallocated or modified in any way.

This function will invoke the application callback, using gsasl_callback(), when a property value is not known.

If no value is known, and no callback is specified or if the callback fail to return data, and if any obsolete callback functions has been set by the application, this function will try to call these obsolete callbacks, and store the returned data as the corresponding property. This behaviour of this function will be removed when the obsolete callback interfaces are removed.

Since 0.2.0

gsasl_property_fast ()

const char* gsasl_property_fast             (Gsasl_session *sctx,
                                             Gsasl_property prop);

Retrieve the data stored in the session handle for given property prop.

The pointer is to live data, and must not be deallocated or modified in any way.

This function will not invoke the application callback.

Since 0.2.0

gsasl_client_mechlist ()

int         gsasl_client_mechlist           (Gsasl *ctx,
                                             char **out);

Return a newly allocated string containing SASL names, separated by space, of mechanisms supported by the libgsasl client. out is allocated by this function, and it is the responsibility of caller to deallocate it.

gsasl_client_support_p ()

int         gsasl_client_support_p          (Gsasl *ctx,
                                             const char *name);

Decide whether there is client-side support for a specified mechanism.

gsasl_client_suggest_mechanism ()

const char* gsasl_client_suggest_mechanism  (Gsasl *ctx,
                                             const char *mechlist);

Given a list of mechanisms, suggest which to use.

gsasl_server_mechlist ()

int         gsasl_server_mechlist           (Gsasl *ctx,
                                             char **out);

Return a newly allocated string containing SASL names, separated by space, of mechanisms supported by the libgsasl server. out is allocated by this function, and it is the responsibility of caller to deallocate it.

gsasl_server_support_p ()

int         gsasl_server_support_p          (Gsasl *ctx,
                                             const char *name);

Decide whether there is server-side support for a specified mechanism.

gsasl_client_start ()

int         gsasl_client_start              (Gsasl *ctx,
                                             const char *mech,
                                             Gsasl_session **sctx);

This functions initiates a client SASL authentication. This function must be called before any other gsasl_client_*() function is called.

gsasl_server_start ()

int         gsasl_server_start              (Gsasl *ctx,
                                             const char *mech,
                                             Gsasl_session **sctx);

This functions initiates a server SASL authentication. This function must be called before any other gsasl_server_*() function is called.

gsasl_step ()

int         gsasl_step                      (Gsasl_session *sctx,
                                             const char *input,
                                             size_t input_len,
                                             char **output,
                                             size_t *output_len);

Perform one step of SASL authentication. This reads data from the other end (from input and input_len), processes it (potentially invoking callbacks to the application), and writes data to server (into newly allocated variable output and output_len that indicate the length of output).

The contents of the output buffer is unspecified if this functions returns anything other than GSASL_OK or GSASL_NEEDS_MORE. If this function return GSASL_OK or GSASL_NEEDS_MORE, however, the output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling free (output).

gsasl_step64 ()

int         gsasl_step64                    (Gsasl_session *sctx,
                                             const char *b64input,
                                             char **b64output);

This is a simple wrapper around gsasl_step() that base64 decodes the input and base64 encodes the output.

The contents of the b64output buffer is unspecified if this functions returns anything other than GSASL_OK or GSASL_NEEDS_MORE. If this function return GSASL_OK or GSASL_NEEDS_MORE, however, the b64output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling free (b64output).

gsasl_finish ()

void        gsasl_finish                    (Gsasl_session *sctx);

Destroy a libgsasl client or server handle. The handle must not be used with other libgsasl functions after this call.

gsasl_encode ()

int         gsasl_encode                    (Gsasl_session *sctx,
                                             const char *input,
                                             size_t input_len,
                                             char **output,
                                             size_t *output_len);

Encode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

The output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling free(output).

gsasl_decode ()

int         gsasl_decode                    (Gsasl_session *sctx,
                                             const char *input,
                                             size_t input_len,
                                             char **output,
                                             size_t *output_len);

Decode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

The output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling free(output).

gsasl_strerror ()

const char* gsasl_strerror                  (int err);

Convert return code to human readable string.

gsasl_saslprep ()

int         gsasl_saslprep                  (const char *in,
                                             Gsasl_saslprep_flags flags,
                                             char **out,
                                             int *stringpreprc);

Prepare string using SASLprep. On success, the out variable must be deallocated by the caller.

Since 0.2.3

gsasl_simple_getpass ()

int         gsasl_simple_getpass            (const char *filename,
                                             const char *username,
                                             char **key);

Retrieve password for user from specified file. The buffer key contain the password if this function is successful. The caller is responsible for deallocating it.

The file should be on the UoW "MD5 Based Authentication" format, which means it is in text format with comments denoted by # first on the line, with user entries looking as "usernameTABpassword". This function removes CR and LF at the end of lines before processing. TAB, CR, and LF denote ASCII values 9, 13, and 10, respectively.

gsasl_base64_to ()

int         gsasl_base64_to                 (const char *in,
                                             size_t inlen,
                                             char **out,
                                             size_t *outlen);

Encode data as base64. The string is zero terminated, and OUTLEN holds the length excluding the terminating zero. The OUT buffer must be deallocated by the caller.

Since 0.2.2

gsasl_base64_from ()

int         gsasl_base64_from               (const char *in,
                                             size_t inlen,
                                             char **out,
                                             size_t *outlen);

Decode Base64 data. The OUT buffer must be deallocated by the caller.

Since 0.2.2

gsasl_nonce ()

int         gsasl_nonce                     (char *data,
                                             size_t datalen);

Store unpredictable data of given size in the provided buffer.

gsasl_random ()

int         gsasl_random                    (char *data,
                                             size_t datalen);

Store cryptographically strong random data of given size in the provided buffer.

gsasl_md5 ()

int         gsasl_md5                       (const char *in,
                                             size_t inlen,
                                             char *out[16]);

Compute hash of data using MD5. The out buffer must be deallocated by the caller.

gsasl_hmac_md5 ()

int         gsasl_hmac_md5                  (const char *key,
                                             size_t keylen,
                                             const char *in,
                                             size_t inlen,
                                             char *outhash[16]);

Compute keyed checksum of data using HMAC-MD5. The outhash buffer must be deallocated by the caller.