gsasl  1.8.1
Macros | Typedefs | Enumerations | Functions | Variables
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.

Macros

#define GSASL_API
 
#define GSASL_VERSION   "1.8.1"
 
#define GSASL_VERSION_MAJOR   1
 
#define GSASL_VERSION_MINOR   8
 
#define GSASL_VERSION_PATCH   1
 
#define GSASL_VERSION_NUMBER   0x010801
 

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_NO_CB_TLS_UNIQUE = 65, GSASL_NO_SAML20_IDP_IDENTIFIER = 66,
  GSASL_NO_SAML20_REDIRECT_URL = 67, GSASL_NO_OPENID20_REDIRECT_URL = 68, 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_GSSAPI_ENCAPSULATE_TOKEN_ERROR = 60, GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR = 61, GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR = 62, GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR = 63,
  GSASL_GSSAPI_RELEASE_OID_SET_ERROR = 64
}
 
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_DIGEST_MD5_HASHED_PASSWORD = 12,
  GSASL_QOPS = 13, GSASL_QOP = 14, GSASL_SCRAM_ITER = 15, GSASL_SCRAM_SALT = 16,
  GSASL_SCRAM_SALTED_PASSWORD = 17, GSASL_CB_TLS_UNIQUE = 18, GSASL_SAML20_IDP_IDENTIFIER = 19, GSASL_SAML20_REDIRECT_URL = 20,
  GSASL_OPENID20_REDIRECT_URL = 21, GSASL_OPENID20_OUTCOME_DATA = 22, GSASL_SAML20_AUTHENTICATE_IN_BROWSER = 250, GSASL_OPENID20_AUTHENTICATE_IN_BROWSER = 251,
  GSASL_VALIDATE_SIMPLE = 500, GSASL_VALIDATE_EXTERNAL = 501, GSASL_VALIDATE_ANONYMOUS = 502, GSASL_VALIDATE_GSSAPI = 503,
  GSASL_VALIDATE_SECURID = 504, GSASL_VALIDATE_SAML20 = 505, GSASL_VALIDATE_OPENID20 = 506
}
 

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 const char * gsasl_strerror_name (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[])
 
GSASL_API int gsasl_hmac_md5 (const char *key, size_t keylen, const char *in, size_t inlen, char *outhash[])
 
GSASL_API int gsasl_sha1 (const char *in, size_t inlen, char *out[])
 
GSASL_API int gsasl_hmac_sha1 (const char *key, size_t keylen, const char *in, size_t inlen, char *outhash[])
 
GSASL_API void gsasl_free (void *ptr)
 

Variables

GSASL_API const char * GSASL_VALID_MECHANISM_CHARACTERS
 

Macro Definition Documentation

◆ GSASL_API

#define GSASL_API

Definition at line 38 of file gsasl.h.

◆ GSASL_VERSION

#define GSASL_VERSION   "1.8.1"

GSASL_VERSION

Pre-processor symbol with a string that describe the header file version number. Used together with gsasl_check_version() to verify header file and run-time library consistency.

Definition at line 54 of file gsasl.h.

◆ GSASL_VERSION_MAJOR

#define GSASL_VERSION_MAJOR   1

GSASL_VERSION_MAJOR

Pre-processor symbol with a decimal value that describe the major level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 1.

Since: 1.1

Definition at line 65 of file gsasl.h.

◆ GSASL_VERSION_MINOR

#define GSASL_VERSION_MINOR   8

GSASL_VERSION_MINOR

Pre-processor symbol with a decimal value that describe the minor level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 2.

Since: 1.1

Definition at line 76 of file gsasl.h.

◆ GSASL_VERSION_NUMBER

#define GSASL_VERSION_NUMBER   0x010801

GSASL_VERSION_NUMBER

Pre-processor symbol with a hexadecimal value describing the header file version number. For example, when the header version is 1.2.3 this symbol will have the value 0x010203.

Since: 1.1

Definition at line 98 of file gsasl.h.

◆ GSASL_VERSION_PATCH

#define GSASL_VERSION_PATCH   1

GSASL_VERSION_PATCH

Pre-processor symbol with a decimal value that describe the patch level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 3.

Since: 1.1

Definition at line 87 of file gsasl.h.

Typedef Documentation

◆ Gsasl

typedef struct Gsasl Gsasl

Gsasl:

Handle to global library context.

Definition at line 280 of file gsasl.h.

◆ Gsasl_callback_function

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

Gsasl_callback_function:

Parameters
ctxlibgsasl handle.
sctxsession handle, may be NULL.
propenumerated 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 391 of file gsasl.h.

◆ Gsasl_session

typedef struct Gsasl_session Gsasl_session

Gsasl_session:

Handle to SASL session context.

Definition at line 287 of file gsasl.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
GSASL_MIN_MECHANISM_SIZE 
GSASL_MAX_MECHANISM_SIZE 

Definition at line 105 of file gsasl.h.

◆ Gsasl_cipher

Gsasl_cipher:

Parameters
GSASL_CIPHER_DESCipher DES.
GSASL_CIPHER_3DESCipher 3DES.
GSASL_CIPHER_RC4Cipher RC4.
GSASL_CIPHER_RC4_40Cipher RC4 with 40-bit keys.
GSASL_CIPHER_RC4_56Cipher RC4 with 56-bit keys.
GSASL_CIPHER_AESCipher AES.

Encryption types (DIGEST-MD5) for confidentiality services of application data. We recommend that you use TLS instead as it is generally more secure and have better chance of working.

Enumerator
GSASL_CIPHER_DES 
GSASL_CIPHER_3DES 
GSASL_CIPHER_RC4 
GSASL_CIPHER_RC4_40 
GSASL_CIPHER_RC4_56 
GSASL_CIPHER_AES 

Definition at line 253 of file gsasl.h.

◆ Gsasl_property

Gsasl_property:

Parameters
GSASL_AUTHIDAuthentication identity (username).
GSASL_AUTHZIDAuthorization identity.
GSASL_PASSWORDPassword.
GSASL_ANONYMOUS_TOKENAnonymous identifier.
GSASL_SERVICEService name
GSASL_HOSTNAMEHost name.
GSASL_GSSAPI_DISPLAY_NAMEGSS-API credential principal name.
GSASL_PASSCODESecurID passcode.
GSASL_SUGGESTED_PINSecurID suggested PIN.
GSASL_PINSecurID PIN.
GSASL_REALMUser realm.
GSASL_DIGEST_MD5_HASHED_PASSWORDPre-computed hashed DIGEST-MD5 password, to avoid storing passwords in the clear.
GSASL_QOPSSet of quality-of-protection values.
GSASL_QOPQuality-of-protection value.
GSASL_SCRAM_ITERNumber of iterations in password-to-key hashing.
GSASL_SCRAM_SALTSalt for password-to-key hashing.
GSASL_SCRAM_SALTED_PASSWORDPre-computed salted SCRAM key, to avoid re-computation and storing passwords in the clear.
GSASL_CB_TLS_UNIQUEBase64 encoded tls-unique channel binding.
GSASL_SAML20_IDP_IDENTIFIERSAML20 user IdP URL.
GSASL_SAML20_REDIRECT_URLSAML 2.0 URL to access in browser.
GSASL_OPENID20_REDIRECT_URLOpenID 2.0 URL to access in browser.
GSASL_OPENID20_OUTCOME_DATAOpenID 2.0 authentication outcome data.
GSASL_SAML20_AUTHENTICATE_IN_BROWSERRequest to perform SAML 2.0 authentication in browser.
GSASL_OPENID20_AUTHENTICATE_IN_BROWSERRequest to perform OpenID 2.0 authentication in browser.
GSASL_VALIDATE_SIMPLERequest for simple validation.
GSASL_VALIDATE_EXTERNALRequest for validation of EXTERNAL.
GSASL_VALIDATE_ANONYMOUSRequest for validation of ANONYMOUS.
GSASL_VALIDATE_GSSAPIRequest for validation of GSSAPI/GS2.
GSASL_VALIDATE_SECURIDReqest for validation of SecurID.
GSASL_VALIDATE_SAML20Reqest for validation of SAML20.
GSASL_VALIDATE_OPENID20Reqest for validation of OpenID 2.0 login.

Callback/property types.

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_DIGEST_MD5_HASHED_PASSWORD 
GSASL_QOPS 
GSASL_QOP 
GSASL_SCRAM_ITER 
GSASL_SCRAM_SALT 
GSASL_SCRAM_SALTED_PASSWORD 
GSASL_CB_TLS_UNIQUE 
GSASL_SAML20_IDP_IDENTIFIER 
GSASL_SAML20_REDIRECT_URL 
GSASL_OPENID20_REDIRECT_URL 
GSASL_OPENID20_OUTCOME_DATA 
GSASL_SAML20_AUTHENTICATE_IN_BROWSER 
GSASL_OPENID20_AUTHENTICATE_IN_BROWSER 
GSASL_VALIDATE_SIMPLE 
GSASL_VALIDATE_EXTERNAL 
GSASL_VALIDATE_ANONYMOUS 
GSASL_VALIDATE_GSSAPI 
GSASL_VALIDATE_SECURID 
GSASL_VALIDATE_SAML20 
GSASL_VALIDATE_OPENID20 

Definition at line 329 of file gsasl.h.

◆ Gsasl_qop

enum Gsasl_qop

Gsasl_qop:

Parameters
GSASL_QOP_AUTHAuthentication only.
GSASL_QOP_AUTH_INTAuthentication and integrity.
GSASL_QOP_AUTH_CONFAuthentication, integrity and confidentiality.

Quality of Protection types (DIGEST-MD5 and GSSAPI). The integrity and confidentiality values is about application data wrapping. We recommend that you use with TLS as that combination is generally more secure and have better chance of working than the integrity/confidentiality layers of SASL.

Enumerator
GSASL_QOP_AUTH 
GSASL_QOP_AUTH_INT 
GSASL_QOP_AUTH_CONF 

Definition at line 233 of file gsasl.h.

◆ Gsasl_rc

enum Gsasl_rc

Gsasl_rc:

Parameters
GSASL_OKSuccessful return code, guaranteed to be always 0.
GSASL_NEEDS_MOREMechanism expects another round-trip.
GSASL_UNKNOWN_MECHANISMApplication requested an unknown mechanism.
GSASL_MECHANISM_CALLED_TOO_MANY_TIMESApplication requested too many round trips from mechanism.
GSASL_MALLOC_ERRORMemory allocation failed.
GSASL_BASE64_ERRORBase64 encoding/decoding failed.
GSASL_CRYPTO_ERRORCryptographic error.
GSASL_SASLPREP_ERRORFailed to prepare internationalized string.
GSASL_MECHANISM_PARSE_ERRORMechanism could not parse input.
GSASL_AUTHENTICATION_ERRORAuthentication has failed.
GSASL_INTEGRITY_ERRORApplication data integrity check failed.
GSASL_NO_CLIENT_CODELibrary was built with client functionality.
GSASL_NO_SERVER_CODELibrary was built with server functionality.
GSASL_NO_CALLBACKApplication did not provide a callback.
GSASL_NO_ANONYMOUS_TOKENCould not get required anonymous token.
GSASL_NO_AUTHIDCould not get required authentication identity (username).
GSASL_NO_AUTHZIDCould not get required authorization identity.
GSASL_NO_PASSWORDCould not get required password.
GSASL_NO_PASSCODECould not get required SecurID PIN.
GSASL_NO_PINCould not get required SecurID PIN.
GSASL_NO_SERVICECould not get required service name.
GSASL_NO_HOSTNAMECould not get required hostname.
GSASL_NO_CB_TLS_UNIQUECould not get required tls-unique CB.
GSASL_NO_SAML20_IDP_IDENTIFIERCould not get required SAML IdP.
GSASL_NO_SAML20_REDIRECT_URLCould not get required SAML redirect URL.
GSASL_NO_OPENID20_REDIRECT_URLCould not get required OpenID redirect URL.
GSASL_GSSAPI_RELEASE_BUFFER_ERRORGSS-API library call error.
GSASL_GSSAPI_IMPORT_NAME_ERRORGSS-API library call error.
GSASL_GSSAPI_INIT_SEC_CONTEXT_ERRORGSS-API library call error.
GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERRORGSS-API library call error.
GSASL_GSSAPI_UNWRAP_ERRORGSS-API library call error.
GSASL_GSSAPI_WRAP_ERRORGSS-API library call error.
GSASL_GSSAPI_ACQUIRE_CRED_ERRORGSS-API library call error.
GSASL_GSSAPI_DISPLAY_NAME_ERRORGSS-API library call error.
GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERRORAn unsupported quality-of-protection layer was requeted.
GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERRORGSS-API library call error.
GSASL_GSSAPI_DECAPSULATE_TOKEN_ERRORGSS-API library call error.
GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERRORGSS-API library call error.
GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERRORGSS-API library call error.
GSASL_GSSAPI_RELEASE_OID_SET_ERRORGSS-API library call error.
GSASL_KERBEROS_V5_INIT_ERRORInit error in KERBEROS_V5.
GSASL_KERBEROS_V5_INTERNAL_ERRORGeneral error in KERBEROS_V5.
GSASL_SHISHI_ERRORSame as GSASL_KERBEROS_V5_INTERNAL_ERROR.
GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODESecurID mechanism needs an additional passcode.
GSASL_SECURID_SERVER_NEED_NEW_PINSecurID mechanism needs an new PIN.

Error codes for library functions.

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_NO_CB_TLS_UNIQUE 
GSASL_NO_SAML20_IDP_IDENTIFIER 
GSASL_NO_SAML20_REDIRECT_URL 
GSASL_NO_OPENID20_REDIRECT_URL 
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 
GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERROR 
GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR 
GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR 
GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR 
GSASL_GSSAPI_RELEASE_OID_SET_ERROR 

Definition at line 169 of file gsasl.h.

◆ Gsasl_saslprep_flags

Gsasl_saslprep_flags:

Parameters
GSASL_ALLOW_UNASSIGNEDAllow unassigned code points.

Flags for the SASLprep function, see gsasl_saslprep(). For background, see the GNU Libidn documentation.

Enumerator
GSASL_ALLOW_UNASSIGNED 

Definition at line 270 of file gsasl.h.

Function Documentation

◆ gsasl_base64_from()

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

gsasl_base64_from:

Parameters
ininput byte array
inlensize of input byte array
outpointer to newly allocated output byte array
outlenpointer 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.

◆ gsasl_base64_to()

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

gsasl_base64_to:

Parameters
ininput byte array
inlensize of input byte array
outpointer to newly allocated output byte array
outlenpointer 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.

◆ gsasl_callback()

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

gsasl_callback:

Parameters
ctxhandle received from gsasl_init(), may be NULL to derive it from .
sctxsession handle.
propenumerated 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 returns, or GSASL_NO_CALLBACK if no application was known.

Since: 0.2.0

Definition at line 75 of file callback.c.

◆ gsasl_callback_hook_get()

GSASL_API void* gsasl_callback_hook_get ( Gsasl ctx)

gsasl_callback_hook_get:

Parameters
ctxlibgsasl 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 128 of file callback.c.

◆ gsasl_callback_hook_set()

GSASL_API void gsasl_callback_hook_set ( Gsasl ctx,
void *  hook 
)

gsasl_callback_hook_set:

Parameters
ctxlibgsasl handle.
hookopaque 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 108 of file callback.c.

◆ gsasl_callback_set()

GSASL_API void gsasl_callback_set ( Gsasl ctx,
Gsasl_callback_function  cb 
)

gsasl_callback_set:

Parameters
ctxhandle received from gsasl_init().
cbpointer 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.

◆ gsasl_check_version()

GSASL_API const char* gsasl_check_version ( const char *  req_version)

gsasl_check_version:

Parameters
req_versionversion string to compare with, or NULL.

Check GNU SASL Library version.

See GSASL_VERSION for a suitable string.

This function is one of few in the library that can be used without a successful call to gsasl_init().

Return value: Check that 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 45 of file version.c.

◆ gsasl_client_mechlist()

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

gsasl_client_mechlist:

Parameters
ctxlibgsasl handle.
outnewly 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.

◆ gsasl_client_start()

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

gsasl_client_start:

Parameters
ctxlibgsasl handle.
mechname of SASL mechanism.
sctxpointer 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.

◆ gsasl_client_suggest_mechanism()

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

gsasl_client_suggest_mechanism:

Parameters
ctxlibgsasl handle.
mechlistinput 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, or NULL if no supported mechanism is found.

Definition at line 38 of file suggest.c.

◆ gsasl_client_support_p()

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

gsasl_client_support_p:

Parameters
ctxlibgsasl handle.
namename 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.

◆ gsasl_decode()

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

gsasl_decode:

Parameters
sctxlibgsasl session handle.
inputinput byte array.
input_lensize of input byte array.
outputnewly allocated output byte array.
output_lensize 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.

◆ gsasl_done()

GSASL_API void gsasl_done ( Gsasl ctx)

gsasl_done:

Parameters
ctxlibgsasl 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.

◆ gsasl_encode()

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

gsasl_encode:

Parameters
sctxlibgsasl session handle.
inputinput byte array.
input_lensize of input byte array.
outputnewly allocated output byte array.
output_lensize 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.

◆ gsasl_finish()

GSASL_API void gsasl_finish ( Gsasl_session sctx)

gsasl_finish:

Parameters
sctxlibgsasl 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.

◆ gsasl_free()

GSASL_API void gsasl_free ( void *  ptr)

gsasl_free:

Parameters
ptrmemory 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_hmac_md5()

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

gsasl_hmac_md5:

Parameters
keyinput character array with key to use.
keylenlength of input character array with key to use.
ininput character array of data to hash.
inlenlength of input character array of data to hash.
outhashnewly allocated 16-byte 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.

◆ gsasl_hmac_sha1()

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

gsasl_hmac_sha1:

Parameters
keyinput character array with key to use.
keylenlength of input character array with key to use.
ininput character array of data to hash.
inlenlength of input character array of data to hash.
outhashnewly allocated 20-byte character array with keyed hash of data.

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

Return value: Returns GSASL_OK iff successful.

Since: 1.3

Definition at line 139 of file crypto.c.

◆ gsasl_init()

GSASL_API int gsasl_init ( Gsasl **  ctx)

gsasl_init:

Parameters
ctxpointer 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 157 of file init.c.

◆ gsasl_md5()

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

gsasl_md5:

Parameters
ininput character array of data to hash.
inlenlength of input character array of data to hash.
outnewly allocated 16-byte 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.

◆ gsasl_mechanism_name()

GSASL_API const char* gsasl_mechanism_name ( Gsasl_session sctx)

gsasl_mechanism_name:

Parameters
sctxlibgsasl session handle.

This function returns the name of the SASL mechanism used in the session. The pointer must not be deallocated by the caller.

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.

◆ gsasl_nonce()

GSASL_API int gsasl_nonce ( char *  data,
size_t  datalen 
)

gsasl_nonce:

Parameters
dataoutput array to be filled with unpredictable random data.
datalensize 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.

◆ gsasl_property_fast()

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

gsasl_property_fast:

Parameters
sctxsession handle.
propenumerated 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 218 of file property.c.

◆ gsasl_property_get()

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

gsasl_property_get:

Parameters
sctxsession handle.
propenumerated 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 255 of file property.c.

◆ gsasl_property_set()

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

gsasl_property_set:

Parameters
sctxsession handle.
propenumerated value of Gsasl_property type, indicating the type of data in .
datazero 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 150 of file property.c.

◆ gsasl_property_set_raw()

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

gsasl_property_set_raw:

Parameters
sctxsession handle.
propenumerated value of Gsasl_property type, indicating the type of data in .
datacharacter string to store.
lenlength 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 176 of file property.c.

◆ gsasl_random()

GSASL_API int gsasl_random ( char *  data,
size_t  datalen 
)

gsasl_random:

Parameters
dataoutput array to be filled with strong random data.
datalensize 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.

◆ gsasl_saslprep()

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

gsasl_saslprep:

Parameters
ina UTF-8 encoded string.
flagsany SASLprep flag, e.g., GSASL_ALLOW_UNASSIGNED.
outon exit, contains newly allocated output string.
stringpreprcif 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.

◆ gsasl_server_mechlist()

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

gsasl_server_mechlist:

Parameters
ctxlibgsasl handle.
outnewly 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.

◆ gsasl_server_start()

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

gsasl_server_start:

Parameters
ctxlibgsasl handle.
mechname of SASL mechanism.
sctxpointer 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.

◆ gsasl_server_support_p()

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

gsasl_server_support_p:

Parameters
ctxlibgsasl handle.
namename 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.

◆ gsasl_session_hook_get()

GSASL_API void* gsasl_session_hook_get ( Gsasl_session sctx)

gsasl_session_hook_get:

Parameters
sctxlibgsasl 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 168 of file callback.c.

◆ gsasl_session_hook_set()

GSASL_API void gsasl_session_hook_set ( Gsasl_session sctx,
void *  hook 
)

gsasl_session_hook_set:

Parameters
sctxlibgsasl session handle.
hookopaque pointer to application specific data.

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

Definition at line 148 of file callback.c.

◆ gsasl_sha1()

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

gsasl_sha1:

Parameters
ininput character array of data to hash.
inlenlength of input character array of data to hash.
outnewly allocated 20-byte character array with hash of data.

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

Return value: Returns GSASL_OK iff successful.

Since: 1.3

Definition at line 115 of file crypto.c.

◆ gsasl_simple_getpass()

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

gsasl_simple_getpass:

Parameters
filenamefilename of file containing passwords.
usernameusername string.
keynewly allocated output character array.

Retrieve password for user from specified file. The buffer 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.

Return value: Return GSASL_OK if output buffer contains the password, GSASL_AUTHENTICATION_ERROR if the user could not be found, or other error code.

Definition at line 47 of file md5pwd.c.

◆ gsasl_step()

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

gsasl_step:

Parameters
sctxlibgsasl session handle.
inputinput byte array.
input_lensize of input byte array.
outputnewly allocated output byte array.
output_lenpointer to output variable with size of output byte array.

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

The contents of the 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 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 authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.

Definition at line 51 of file xstep.c.

◆ gsasl_step64()

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

gsasl_step64:

Parameters
sctxlibgsasl client handle.
b64inputinput base64 encoded byte array.
b64outputnewly allocated output base64 encoded byte array.

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

The contents of the 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 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 authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.

Definition at line 86 of file xstep.c.

◆ gsasl_strerror()

GSASL_API const char* gsasl_strerror ( int  err)

gsasl_strerror:

Parameters
errlibgsasl error code

Convert return code to human readable string explanation of the reason for the particular error code.

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to gsasl_init().

Return value: Returns a pointer to a statically allocated string containing an explanation of the error code .

Definition at line 228 of file error.c.

◆ gsasl_strerror_name()

GSASL_API const char* gsasl_strerror_name ( int  err)

gsasl_strerror_name:

Parameters
errlibgsasl error code

Convert return code to human readable string representing the error code symbol itself. For example, gsasl_strerror_name(GSASL_OK) returns the string "GSASL_OK".

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to gsasl_init().

Return value: Returns a pointer to a statically allocated string containing a string version of the error code , or NULL if the error code is not known.

Since: 0.2.29

Definition at line 266 of file error.c.

Variable Documentation

◆ GSASL_VALID_MECHANISM_CHARACTERS

GSASL_API const char* GSASL_VALID_MECHANISM_CHARACTERS

GSASL_VALID_MECHANISM_CHARACTERS:

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

Definition at line 51 of file init.c.