gsasl.h File Reference

#include <stdio.h>
#include <stddef.h>
#include <unistd.h>
#include <gsasl-mech.h>
#include <gsasl-compat.h>

Go to the source code of this file.

Defines

#define GSASL_API
#define GSASL_VERSION   "0.2.28"

Typedefs

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

Enumerations

enum  { GSASL_MIN_MECHANISM_SIZE = 1, GSASL_MAX_MECHANISM_SIZE = 20 }
enum  Gsasl_rc {
  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, 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
}
enum  Gsasl_qop { GSASL_QOP_AUTH = 1, GSASL_QOP_AUTH_INT = 2, GSASL_QOP_AUTH_CONF = 4 }
enum  Gsasl_cipher {
  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
}
enum  Gsasl_saslprep_flags { GSASL_ALLOW_UNASSIGNED = 1 }
enum  Gsasl_property {
  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, GSASL_VALIDATE_SIMPLE = 500,
  GSASL_VALIDATE_EXTERNAL = 501, GSASL_VALIDATE_ANONYMOUS = 502, GSASL_VALIDATE_GSSAPI = 503, GSASL_VALIDATE_SECURID = 504
}

Functions

GSASL_API int gsasl_init (Gsasl **ctx)
GSASL_API void gsasl_done (Gsasl *ctx)
GSASL_API const char * gsasl_check_version (const char *req_version)
GSASL_API void gsasl_callback_set (Gsasl *ctx, Gsasl_callback_function cb)
GSASL_API int gsasl_callback (Gsasl *ctx, Gsasl_session *sctx, Gsasl_property prop)
GSASL_API void gsasl_callback_hook_set (Gsasl *ctx, void *hook)
GSASL_API void * gsasl_callback_hook_get (Gsasl *ctx)
GSASL_API void gsasl_session_hook_set (Gsasl_session *sctx, void *hook)
GSASL_API void * gsasl_session_hook_get (Gsasl_session *sctx)
GSASL_API void gsasl_property_set (Gsasl_session *sctx, Gsasl_property prop, const char *data)
GSASL_API void gsasl_property_set_raw (Gsasl_session *sctx, Gsasl_property prop, const char *data, size_t len)
GSASL_API const char * gsasl_property_get (Gsasl_session *sctx, Gsasl_property prop)
GSASL_API const char * gsasl_property_fast (Gsasl_session *sctx, Gsasl_property prop)
GSASL_API int gsasl_client_mechlist (Gsasl *ctx, char **out)
GSASL_API int gsasl_client_support_p (Gsasl *ctx, const char *name)
GSASL_API const char * gsasl_client_suggest_mechanism (Gsasl *ctx, const char *mechlist)
GSASL_API int gsasl_server_mechlist (Gsasl *ctx, char **out)
GSASL_API int gsasl_server_support_p (Gsasl *ctx, const char *name)
GSASL_API int gsasl_client_start (Gsasl *ctx, const char *mech, Gsasl_session **sctx)
GSASL_API int gsasl_server_start (Gsasl *ctx, const char *mech, Gsasl_session **sctx)
GSASL_API int gsasl_step (Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
GSASL_API int gsasl_step64 (Gsasl_session *sctx, const char *b64input, char **b64output)
GSASL_API void gsasl_finish (Gsasl_session *sctx)
GSASL_API int gsasl_encode (Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
GSASL_API int gsasl_decode (Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
GSASL_API const char * gsasl_mechanism_name (Gsasl_session *sctx)
GSASL_API const char * gsasl_strerror (int err)
GSASL_API int gsasl_saslprep (const char *in, Gsasl_saslprep_flags flags, char **out, int *stringpreprc)
GSASL_API int gsasl_simple_getpass (const char *filename, const char *username, char **key)
GSASL_API int gsasl_base64_to (const char *in, size_t inlen, char **out, size_t *outlen)
GSASL_API int gsasl_base64_from (const char *in, size_t inlen, char **out, size_t *outlen)
GSASL_API int gsasl_nonce (char *data, size_t datalen)
GSASL_API int gsasl_random (char *data, size_t datalen)
GSASL_API int gsasl_md5 (const char *in, size_t inlen, char *out[16])
GSASL_API int gsasl_hmac_md5 (const char *key, size_t keylen, const char *in, size_t inlen, char *outhash[16])
GSASL_API void gsasl_free (void *ptr)

Variables

GSASL_API const char * GSASL_VALID_MECHANISM_CHARACTERS

Define Documentation

#define GSASL_API

Definition at line 39 of file gsasl.h.

#define GSASL_VERSION   "0.2.28"

GSASL_VERSION

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.

Definition at line 55 of file gsasl.h.

Typedef Documentation

typedef struct Gsasl Gsasl

Definition at line 137 of file gsasl.h.

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

Gsasl_callback_function:

Parameters:
ctx libgsasl handle.
sctx session handle, may be NULL.
prop enumerated value of Gsasl_property type.
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 , 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.

Return value: Any valid return code, the interpretation of which depend on the value.

Since: 0.2.0

Definition at line 187 of file gsasl.h.

typedef struct Gsasl_session Gsasl_session

Definition at line 138 of file gsasl.h.

Enumeration Type Documentation

anonymous enum

Enumerator:
GSASL_MIN_MECHANISM_SIZE 
GSASL_MAX_MECHANISM_SIZE 

Definition at line 62 of file gsasl.h.

enum Gsasl_cipher

Enumerator:
GSASL_CIPHER_DES 
GSASL_CIPHER_3DES 
GSASL_CIPHER_RC4 
GSASL_CIPHER_RC4_40 
GSASL_CIPHER_RC4_56 
GSASL_CIPHER_AES 

Definition at line 120 of file gsasl.h.

enum Gsasl_property

Enumerator:
GSASL_AUTHID 
GSASL_AUTHZID 
GSASL_PASSWORD 
GSASL_ANONYMOUS_TOKEN 
GSASL_SERVICE 
GSASL_HOSTNAME 
GSASL_GSSAPI_DISPLAY_NAME 
GSASL_PASSCODE 
GSASL_SUGGESTED_PIN 
GSASL_PIN 
GSASL_REALM 
GSASL_VALIDATE_SIMPLE 
GSASL_VALIDATE_EXTERNAL 
GSASL_VALIDATE_ANONYMOUS 
GSASL_VALIDATE_GSSAPI 
GSASL_VALIDATE_SECURID 

Definition at line 141 of file gsasl.h.

enum Gsasl_qop

Enumerator:
GSASL_QOP_AUTH 
GSASL_QOP_AUTH_INT 
GSASL_QOP_AUTH_CONF 

Definition at line 112 of file gsasl.h.

enum Gsasl_rc

Enumerator:
GSASL_OK 
GSASL_NEEDS_MORE 
GSASL_UNKNOWN_MECHANISM 
GSASL_MECHANISM_CALLED_TOO_MANY_TIMES 
GSASL_MALLOC_ERROR 
GSASL_BASE64_ERROR 
GSASL_CRYPTO_ERROR 
GSASL_SASLPREP_ERROR 
GSASL_MECHANISM_PARSE_ERROR 
GSASL_AUTHENTICATION_ERROR 
GSASL_INTEGRITY_ERROR 
GSASL_NO_CLIENT_CODE 
GSASL_NO_SERVER_CODE 
GSASL_NO_CALLBACK 
GSASL_NO_ANONYMOUS_TOKEN 
GSASL_NO_AUTHID 
GSASL_NO_AUTHZID 
GSASL_NO_PASSWORD 
GSASL_NO_PASSCODE 
GSASL_NO_PIN 
GSASL_NO_SERVICE 
GSASL_NO_HOSTNAME 
GSASL_GSSAPI_RELEASE_BUFFER_ERROR 
GSASL_GSSAPI_IMPORT_NAME_ERROR 
GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR 
GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR 
GSASL_GSSAPI_UNWRAP_ERROR 
GSASL_GSSAPI_WRAP_ERROR 
GSASL_GSSAPI_ACQUIRE_CRED_ERROR 
GSASL_GSSAPI_DISPLAY_NAME_ERROR 
GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR 
GSASL_KERBEROS_V5_INIT_ERROR 
GSASL_KERBEROS_V5_INTERNAL_ERROR 
GSASL_SHISHI_ERROR 
GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE 
GSASL_SECURID_SERVER_NEED_NEW_PIN 

Definition at line 70 of file gsasl.h.

enum Gsasl_saslprep_flags

Enumerator:
GSASL_ALLOW_UNASSIGNED 

Definition at line 131 of file gsasl.h.

Function Documentation

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

gsasl_base64_from:

Parameters:
in input byte array
inlen size of input byte array
out pointer to newly allocated output byte array
outlen pointer to size of newly allocated output byte array
Decode Base64 data. The buffer must be deallocated by the caller.

Return value: Returns GSASL_OK on success, GSASL_BASE64_ERROR if input was invalid, and GSASL_MALLOC_ERROR on memory allocation errors.

Since: 0.2.2

Definition at line 74 of file base64.c.

References GSASL_BASE64_ERROR, GSASL_MALLOC_ERROR, and GSASL_OK.

Referenced by gsasl_step64().

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

gsasl_base64_to:

Parameters:
in input byte array
inlen size of input byte array
out pointer to newly allocated output byte array
outlen pointer to size of newly allocated output byte array
Encode data as base64. The string is zero terminated, and holds the length excluding the terminating zero. The buffer must be deallocated by the caller.

Return value: Returns GSASL_OK on success, or GSASL_MALLOC_ERROR if input was too large or memory allocation fail.

Since: 0.2.2

Definition at line 44 of file base64.c.

References GSASL_MALLOC_ERROR, and GSASL_OK.

Referenced by _gsasl_digest_md5_client_start(), _gsasl_digest_md5_server_start(), and gsasl_step64().

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

gsasl_callback:

Parameters:
ctx handle received from gsasl_init(), may be NULL to derive it from .
sctx session handle.
prop enumerated value of Gsasl_property type.
Invoke the application callback. The value indicate what the callback is expected to do. For example, for GSASL_ANONYMOUS_TOKEN, the function is expected to invoke gsasl_property_set(, 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.

Return value: Returns whatever the application callback return, or GSASL_NO_CALLBACK if no application was known.

Since: 0.2.0

Definition at line 75 of file callback.c.

References Gsasl_session::anonymous_token, Gsasl_session::authid, Gsasl_session::authzid, Gsasl::cb, Gsasl_session::ctx, GSASL_NO_CALLBACK, GSASL_OK, GSASL_PASSWORD, gsasl_property_set(), gsasl_property_set_raw(), gsasl_server_callback_anonymous_get(), gsasl_server_callback_external_get(), gsasl_server_callback_gssapi_get(), gsasl_server_callback_retrieve_get(), gsasl_server_callback_securid_get(), gsasl_server_callback_validate_get(), GSASL_SUGGESTED_PIN, GSASL_VALIDATE_ANONYMOUS, GSASL_VALIDATE_EXTERNAL, GSASL_VALIDATE_GSSAPI, GSASL_VALIDATE_SECURID, GSASL_VALIDATE_SIMPLE, Gsasl_session::gssapi_display_name, Gsasl_session::hostname, Gsasl_session::passcode, Gsasl_session::password, and Gsasl_session::pin.

Referenced by _gsasl_anonymous_server_step(), _gsasl_digest_md5_client_step(), _gsasl_external_server_step(), _gsasl_gs2_server_step(), _gsasl_gssapi_server_step(), _gsasl_login_server_step(), _gsasl_plain_server_step(), _gsasl_securid_server_step(), and gsasl_property_get().

GSASL_API void* gsasl_callback_hook_get ( Gsasl *  ctx  ) 

gsasl_callback_hook_get:

Parameters:
ctx libgsasl handle.
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.

Return value: Returns the application specific data, or NULL.

Since: 0.2.0

Definition at line 206 of file callback.c.

References Gsasl::application_hook.

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

gsasl_callback_hook_set:

Parameters:
ctx libgsasl handle.
hook opaque pointer to application specific data.
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

Definition at line 186 of file callback.c.

References Gsasl::application_hook.

GSASL_API void gsasl_callback_set ( Gsasl *  ctx,
Gsasl_callback_function  cb 
)

gsasl_callback_set:

Parameters:
ctx handle received from gsasl_init().
cb pointer to function implemented by application.
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(, 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

Definition at line 44 of file callback.c.

References Gsasl::cb.

GSASL_API const char* gsasl_check_version ( const char *  req_version  ) 

gsasl_check_version:

Parameters:
req_version version string to compare with, or NULL.
Check library version.

See GSASL_VERSION for a suitable string.

Return value: Check that the the version of the library is at minimum the one given as a string in and return the actual version string of the library; return NULL if the condition is not met. If NULL is passed to this function no check is done and only the version string is returned.

Definition at line 42 of file version.c.

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

gsasl_client_mechlist:

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

Return value: Returns GSASL_OK if successful, or error code.

Definition at line 74 of file listmech.c.

References Gsasl::client_mechs, and Gsasl::n_client_mechs.

Referenced by gsasl_client_listmech().

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

gsasl_client_start:

Parameters:
ctx libgsasl handle.
mech name of SASL mechanism.
sctx pointer to client handle.
This functions initiates a client SASL authentication. This function must be called before any other gsasl_client_*() function is called.

Return value: Returns GSASL_OK if successful, or error code.

Definition at line 119 of file xstart.c.

References Gsasl::client_mechs, and Gsasl::n_client_mechs.

Referenced by gsasl_client_suggest_mechanism().

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

gsasl_client_suggest_mechanism:

Parameters:
ctx libgsasl handle.
mechlist input character array with SASL mechanism names, separated by invalid characters (e.g. SPC).
Given a list of mechanisms, suggest which to use.

Return value: Returns name of "best" SASL mechanism supported by the libgsasl client which is present in the input string.

Definition at line 37 of file suggest.c.

References Gsasl::client_mechs, gsasl_client_start(), gsasl_finish(), GSASL_OK, GSASL_VALID_MECHANISM_CHARACTERS, i, j, Gsasl::n_client_mechs, and Gsasl_mechanism::name.

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

gsasl_client_support_p:

Parameters:
ctx libgsasl handle.
name name of SASL mechanism.
Decide whether there is client-side support for a specified mechanism.

Return value: Returns 1 if the libgsasl client supports the named mechanism, otherwise 0.

Definition at line 49 of file supportp.c.

References Gsasl::client_mechs, and Gsasl::n_client_mechs.

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

gsasl_decode:

Parameters:
sctx libgsasl session handle.
input input byte array.
input_len size of input byte array.
output newly allocated output byte array.
output_len size of output byte array.
Decode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

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

Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.

Definition at line 96 of file xcode.c.

References Gsasl_mechanism::client, Gsasl_session::clientp, Gsasl_mechanism_functions::decode, Gsasl_session::mech, and Gsasl_mechanism::server.

Referenced by gsasl_decode_inline().

GSASL_API void gsasl_done ( Gsasl *  ctx  ) 

gsasl_done:

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

Definition at line 33 of file done.c.

References Gsasl_mechanism::client, Gsasl::client_mechs, Gsasl_mechanism_functions::done, i, Gsasl::n_client_mechs, Gsasl::n_server_mechs, Gsasl_mechanism::server, and Gsasl::server_mechs.

Referenced by gsasl_init().

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

gsasl_encode:

Parameters:
sctx libgsasl session handle.
input input byte array.
input_len size of input byte array.
output newly allocated output byte array.
output_len size of output byte array.
Encode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

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

Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.

Definition at line 64 of file xcode.c.

References Gsasl_mechanism::client, Gsasl_session::clientp, Gsasl_mechanism_functions::encode, Gsasl_session::mech, and Gsasl_mechanism::server.

Referenced by gsasl_encode_inline().

GSASL_API void gsasl_finish ( Gsasl_session *  sctx  ) 

gsasl_finish:

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

Definition at line 33 of file xfinish.c.

References Gsasl_session::anonymous_token, Gsasl_session::authid, Gsasl_session::authzid, Gsasl_mechanism::client, Gsasl_session::clientp, Gsasl_mechanism_functions::finish, Gsasl_session::gssapi_display_name, Gsasl_session::hostname, Gsasl_session::mech, Gsasl_session::mech_data, Gsasl_session::passcode, Gsasl_session::password, Gsasl_session::pin, Gsasl_session::realm, Gsasl_mechanism::server, Gsasl_session::service, and Gsasl_session::suggestedpin.

Referenced by gsasl_client_finish(), gsasl_client_suggest_mechanism(), and gsasl_server_finish().

GSASL_API void gsasl_free ( void *  ptr  ) 

gsasl_free:

Parameters:
ptr memory pointer
Invoke free() to de-allocate memory pointer. Typically used on strings allocated by other libgsasl functions.

This is useful on Windows where libgsasl is linked to one CRT and the application is linked to another CRT. Then malloc/free will not use the same heap. This happens if you build libgsasl using mingw32 and the application with Visual Studio.

Since: 0.2.19

Definition at line 41 of file src/free.c.

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

gsasl_hmac_md5:

Parameters:
key input character array with key to use.
keylen length of input character array with key to use.
in input character array of data to hash.
inlen length of input character array of data to hash.
outhash newly allocated character array with keyed hash of data.
Compute keyed checksum of data using HMAC-MD5. The buffer must be deallocated by the caller.

Return value: Returns GSASL_OK iff successful.

Definition at line 92 of file crypto.c.

References GSASL_MALLOC_ERROR.

GSASL_API int gsasl_init ( Gsasl **  ctx  ) 

gsasl_init:

Parameters:
ctx pointer to libgsasl handle.
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().

Return value: GSASL_OK iff successful, otherwise GSASL_MALLOC_ERROR.

Definition at line 132 of file init.c.

References GSASL_CRYPTO_ERROR, gsasl_done(), GSASL_MALLOC_ERROR, and GSASL_OK.

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

gsasl_md5:

Parameters:
in input character array of data to hash.
inlen length of input character array of data to hash.
out newly allocated character array with hash of data.
Compute hash of data using MD5. The buffer must be deallocated by the caller.

Return value: Returns GSASL_OK iff successful.

Definition at line 70 of file crypto.c.

References GSASL_MALLOC_ERROR.

Referenced by _gsasl_digest_md5_client_step(), and _gsasl_digest_md5_server_step().

GSASL_API const char* gsasl_mechanism_name ( Gsasl_session *  sctx  ) 

gsasl_mechanism_name:

Parameters:
sctx libgsasl session handle.
This function returns the name of the SASL mechanism used in the session.

Return value: Returns a zero terminated character array with the name of the SASL mechanism, or NULL if not known.

Since: 0.2.28

Definition at line 38 of file mechname.c.

References Gsasl_session::mech, and Gsasl_mechanism::name.

GSASL_API int gsasl_nonce ( char *  data,
size_t  datalen 
)

gsasl_nonce:

Parameters:
data output array to be filled with unpredictable random data.
datalen size of output array.
Store unpredictable data of given size in the provided buffer.

Return value: Returns GSASL_OK iff successful.

Definition at line 37 of file crypto.c.

Referenced by _gsasl_digest_md5_client_start(), _gsasl_digest_md5_server_start(), and gsasl_randomize().

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

gsasl_property_fast:

Parameters:
sctx session handle.
prop enumerated value of Gsasl_property type, indicating the type of data in .
Retrieve the data stored in the session handle for given property .

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

This function will not invoke the application callback.

Return value: Return property value, if known, or NULL if no value known.

Since: 0.2.0

Definition at line 171 of file property.c.

Referenced by _gsasl_digest_md5_client_step(), and gsasl_property_get().

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

gsasl_property_get:

Parameters:
sctx session handle.
prop enumerated value of Gsasl_property type, indicating the type of data in .
Retrieve the data stored in the session handle for given property , 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.

Return value: Return data for property, or NULL if no value known.

Since: 0.2.0

Definition at line 208 of file property.c.

References Gsasl_session::ctx, GSASL_ANONYMOUS_TOKEN, GSASL_AUTHID, GSASL_AUTHZID, gsasl_callback(), gsasl_client_callback_anonymous_get(), gsasl_client_callback_authentication_id_get(), gsasl_client_callback_authorization_id_get(), gsasl_client_callback_passcode_get(), gsasl_client_callback_password_get(), gsasl_client_callback_pin_get(), gsasl_client_callback_realm_get(), gsasl_client_callback_service_get(), GSASL_HOSTNAME, GSASL_OK, GSASL_PASSCODE, GSASL_PASSWORD, GSASL_PIN, gsasl_property_fast(), gsasl_property_set(), GSASL_REALM, GSASL_SERVICE, and Gsasl_session::suggestedpin.

Referenced by _gsasl_anonymous_client_step(), _gsasl_cram_md5_client_step(), _gsasl_cram_md5_server_step(), _gsasl_digest_md5_client_step(), _gsasl_digest_md5_server_step(), _gsasl_external_client_step(), _gsasl_gs2_client_step(), _gsasl_gs2_server_start(), _gsasl_gssapi_client_step(), _gsasl_gssapi_server_start(), _gsasl_login_client_step(), _gsasl_login_server_step(), _gsasl_ntlm_client_step(), _gsasl_plain_client_step(), _gsasl_plain_server_step(), _gsasl_securid_client_step(), and _gsasl_securid_server_step().

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

gsasl_property_set:

Parameters:
sctx session handle.
prop enumerated value of Gsasl_property type, indicating the type of data in .
data zero terminated character string to store.
Make a copy of and store it in the session handle for the indicated property .

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

Since: 0.2.0

Definition at line 102 of file property.c.

References gsasl_property_set_raw().

Referenced by _gsasl_cram_md5_server_step(), _gsasl_digest_md5_client_step(), _gsasl_digest_md5_server_step(), _gsasl_external_server_step(), _gsasl_login_server_step(), _gsasl_plain_server_step(), _gsasl_securid_server_step(), gsasl_callback(), and gsasl_property_get().

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

gsasl_property_set_raw:

Parameters:
sctx session handle.
prop enumerated value of Gsasl_property type, indicating the type of data in .
data character string to store.
len length of character string to store.
Make a copy of sized and store a zero terminated version of it in the session handle for the indicated property .

You can immediately deallocate 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

Definition at line 128 of file property.c.

Referenced by _gsasl_anonymous_server_step(), _gsasl_external_server_step(), _gsasl_gs2_server_step(), _gsasl_gssapi_server_step(), _gsasl_securid_client_step(), gsasl_callback(), and gsasl_property_set().

GSASL_API int gsasl_random ( char *  data,
size_t  datalen 
)

gsasl_random:

Parameters:
data output array to be filled with strong random data.
datalen size of output array.
Store cryptographically strong random data of given size in the provided buffer.

Return value: Returns GSASL_OK iff successful.

Definition at line 53 of file crypto.c.

Referenced by gsasl_randomize().

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

gsasl_saslprep - prepare internationalized string

Parameters:
in a UTF-8 encoded string.
flags any SASLprep flag, e.g., GSASL_ALLOW_UNASSIGNED.
out on exit, contains newly allocated output string.
stringpreprc if non-NULL, will hold precise stringprep return code.
Prepare string using SASLprep. On success, the variable must be deallocated by the caller.

Return value: Returns GSASL_OK on success, or GSASL_SASLPREP_ERROR on error.

Since: 0.2.3

Definition at line 48 of file saslprep.c.

References GSASL_ALLOW_UNASSIGNED, GSASL_MALLOC_ERROR, GSASL_OK, GSASL_SASLPREP_ERROR, and i.

Referenced by _gsasl_cram_md5_client_step(), _gsasl_cram_md5_server_step(), and _gsasl_plain_server_step().

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

gsasl_server_mechlist:

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

Return value: Returns GSASL_OK if successful, or error code.

Definition at line 93 of file listmech.c.

References Gsasl::n_server_mechs, and Gsasl::server_mechs.

Referenced by gsasl_server_listmech().

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

gsasl_server_start:

Parameters:
ctx libgsasl handle.
mech name of SASL mechanism.
sctx pointer to server handle.
This functions initiates a server SASL authentication. This function must be called before any other gsasl_server_*() function is called.

Return value: Returns GSASL_OK if successful, or error code.

Definition at line 137 of file xstart.c.

References Gsasl::n_server_mechs, and Gsasl::server_mechs.

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

gsasl_server_support_p:

Parameters:
ctx libgsasl handle.
name name of SASL mechanism.
Decide whether there is server-side support for a specified mechanism.

Return value: Returns 1 if the libgsasl server supports the named mechanism, otherwise 0.

Definition at line 66 of file supportp.c.

References Gsasl::n_server_mechs, and Gsasl::server_mechs.

GSASL_API void* gsasl_session_hook_get ( Gsasl_session *  sctx  ) 

gsasl_session_hook_get:

Parameters:
sctx libgsasl session handle.
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.

Return value: Returns the application specific data, or NULL.

Since: 0.2.14

Definition at line 246 of file callback.c.

References Gsasl_session::application_hook.

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

gsasl_session_hook_set:

Parameters: