|
gsasl
2.2.1
|
#include <stdio.h>#include <stddef.h>#include <unistd.h>#include <gsasl-version.h>#include <gsasl-mech.h>Go to the source code of this file.
Macros | |
| #define | _GSASL_API |
Typedefs | |
| typedef struct Gsasl | Gsasl |
| typedef struct Gsasl_session | Gsasl_session |
| typedef int(* | Gsasl_callback_function) (Gsasl *ctx, Gsasl_session *sctx, Gsasl_property prop) |
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 int | gsasl_property_set (Gsasl_session *sctx, Gsasl_property prop, const char *data) |
| _GSASL_API int | gsasl_property_set_raw (Gsasl_session *sctx, Gsasl_property prop, const char *data, size_t len) |
| _GSASL_API void | gsasl_property_free (Gsasl_session *sctx, Gsasl_property prop) |
| _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_mechanism_name_p (const char *mech) |
| _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_nonce (char *data, size_t datalen) |
| _GSASL_API int | gsasl_random (char *data, size_t datalen) |
| _GSASL_API size_t | gsasl_hash_length (Gsasl_hash hash) |
| _GSASL_API int | gsasl_scram_secrets_from_salted_password (Gsasl_hash hash, const char *salted_password, char *client_key, char *server_key, char *stored_key) |
| _GSASL_API int | gsasl_scram_secrets_from_password (Gsasl_hash hash, const char *password, unsigned int iteration_count, const char *salt, size_t saltlen, char *salted_password, char *client_key, char *server_key, char *stored_key) |
| _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_hex_to (const char *in, size_t inlen, char **out, size_t *outlen) |
| _GSASL_API int | gsasl_hex_from (const char *in, char **out, size_t *outlen) |
| _GSASL_API void | gsasl_free (void *ptr) |
| #define _GSASL_API |
| typedef int(* Gsasl_callback_function) (Gsasl *ctx, Gsasl_session *sctx, Gsasl_property prop) |
Gsasl_callback_function:
| 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 @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.
Return value: Any valid return code, the interpretation of which depend on the @prop value.
Since: 0.2.0
| typedef struct Gsasl_session Gsasl_session |
| enum Gsasl_hash |
Gsasl_hash:
| GSASL_HASH_SHA1 | Hash function SHA-1. |
| GSASL_HASH_SHA256 | Hash function SHA-256. |
Hash functions. You may use gsasl_hash_length() to get the output size of a hash function.
Currently only used as parameter to gsasl_scram_secrets_from_salted_password() and gsasl_scram_secrets_from_password() to specify for which SCRAM mechanism to prepare secrets for.
Since: 1.10
| Enumerator | |
|---|---|
| GSASL_HASH_SHA1 | |
| GSASL_HASH_SHA256 | |
| enum Gsasl_hash_length |
Gsasl_hash_length:
| GSASL_HASH_SHA1_SIZE | Output size of hash function SHA-1. |
| GSASL_HASH_SHA256_SIZE | Output size of hash function SHA-256. |
| GSASL_HASH_MAX_SIZE | Maximum output size of any Gsasl_hash_length. |
Identifiers specifying the output size of hash functions.
These can be used when statically allocating the buffers needed for, e.g., gsasl_scram_secrets_from_password().
Since: 1.10
| Enumerator | |
|---|---|
| GSASL_HASH_SHA1_SIZE | |
| GSASL_HASH_SHA256_SIZE | |
| GSASL_HASH_MAX_SIZE | |
Gsasl_mechname_limits:
| GSASL_MIN_MECHANISM_SIZE | Minimum size of mechanism name strings. |
| GSASL_MAX_MECHANISM_SIZE | Maximum size of mechanism name strings. |
SASL mechanisms are named by strings, from 1 to 20 characters in length, consisting of upper-case letters, digits, hyphens, and/or underscores. See also gsasl_mechanism_name_p().
| Enumerator | |
|---|---|
| GSASL_MIN_MECHANISM_SIZE | |
| GSASL_MAX_MECHANISM_SIZE | |
| enum Gsasl_property |
Gsasl_property:
| GSASL_AUTHID | Authentication identity (username). |
| GSASL_AUTHZID | Authorization identity. |
| GSASL_PASSWORD | Password. |
| GSASL_ANONYMOUS_TOKEN | Anonymous identifier. |
| GSASL_SERVICE | Service name |
| GSASL_HOSTNAME | Host name. |
| GSASL_GSSAPI_DISPLAY_NAME | GSS-API credential principal name. |
| GSASL_PASSCODE | SecurID passcode. |
| GSASL_SUGGESTED_PIN | SecurID suggested PIN. |
| GSASL_PIN | SecurID PIN. |
| GSASL_REALM | User realm. |
| GSASL_DIGEST_MD5_HASHED_PASSWORD | Pre-computed hashed DIGEST-MD5 password, to avoid storing passwords in the clear. |
| GSASL_QOPS | Set of quality-of-protection values. |
| GSASL_QOP | Quality-of-protection value. |
| GSASL_SCRAM_ITER | Number of iterations in password-to-key hashing. |
| GSASL_SCRAM_SALT | Salt for password-to-key hashing. |
| GSASL_SCRAM_SALTED_PASSWORD | Hex-encoded hashed/salted password. |
| GSASL_SCRAM_SERVERKEY | Hex-encoded SCRAM ServerKey derived from users' passowrd. |
| GSASL_SCRAM_STOREDKEY | Hex-encoded SCRAM StoredKey derived from users' passowrd. |
| GSASL_CB_TLS_UNIQUE | Base64 encoded tls-unique channel binding. |
| GSASL_CB_TLS_EXPORTER | Base64 encoded tls-exporter channel binding. |
| GSASL_SAML20_IDP_IDENTIFIER | SAML20 user IdP URL. |
| GSASL_SAML20_REDIRECT_URL | SAML 2.0 URL to access in browser. |
| GSASL_OPENID20_REDIRECT_URL | OpenID 2.0 URL to access in browser. |
| GSASL_OPENID20_OUTCOME_DATA | OpenID 2.0 authentication outcome data. |
| GSASL_SAML20_AUTHENTICATE_IN_BROWSER | Request to perform SAML 2.0 authentication in browser. |
| GSASL_OPENID20_AUTHENTICATE_IN_BROWSER | Request to perform OpenID 2.0 authentication in browser. |
| GSASL_VALIDATE_SIMPLE | Request for simple validation. |
| GSASL_VALIDATE_EXTERNAL | Request for validation of EXTERNAL. |
| GSASL_VALIDATE_ANONYMOUS | Request for validation of ANONYMOUS. |
| GSASL_VALIDATE_GSSAPI | Request for validation of GSSAPI/GS2. |
| GSASL_VALIDATE_SECURID | Reqest for validation of SecurID. |
| GSASL_VALIDATE_SAML20 | Reqest for validation of SAML20. |
| GSASL_VALIDATE_OPENID20 | Reqest for validation of OpenID 2.0 login. |
Callback/property types.
| enum Gsasl_qop |
Gsasl_qop:
| GSASL_QOP_AUTH | Authentication only. |
| GSASL_QOP_AUTH_INT | Authentication and integrity. |
| GSASL_QOP_AUTH_CONF | Authentication, 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 @GSASL_QOP_AUTH 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 | |
| enum Gsasl_rc |
Gsasl_rc:
| GSASL_OK | Successful return code, guaranteed to be always 0. |
| GSASL_NEEDS_MORE | Mechanism expects another round-trip. |
| GSASL_UNKNOWN_MECHANISM | Application requested an unknown mechanism. |
| GSASL_MECHANISM_CALLED_TOO_MANY_TIMES | Application requested too many round trips from mechanism. |
| GSASL_MALLOC_ERROR | Memory allocation failed. |
| GSASL_BASE64_ERROR | Base64 encoding/decoding failed. |
| GSASL_CRYPTO_ERROR | Cryptographic error. |
| GSASL_SASLPREP_ERROR | Failed to prepare internationalized string. |
| GSASL_MECHANISM_PARSE_ERROR | Mechanism could not parse input. |
| GSASL_AUTHENTICATION_ERROR | Authentication has failed. |
| GSASL_INTEGRITY_ERROR | Application data integrity check failed. |
| GSASL_NO_CLIENT_CODE | Library was built with client functionality. |
| GSASL_NO_SERVER_CODE | Library was built with server functionality. |
| GSASL_NO_CALLBACK | Application did not provide a callback. |
| GSASL_NO_ANONYMOUS_TOKEN | Could not get required anonymous token. |
| GSASL_NO_AUTHID | Could not get required authentication identity (username). |
| GSASL_NO_AUTHZID | Could not get required authorization identity. |
| GSASL_NO_PASSWORD | Could not get required password. |
| GSASL_NO_PASSCODE | Could not get required SecurID PIN. |
| GSASL_NO_PIN | Could not get required SecurID PIN. |
| GSASL_NO_SERVICE | Could not get required service name. |
| GSASL_NO_HOSTNAME | Could not get required hostname. |
| GSASL_NO_CB_TLS_UNIQUE | Could not get required tls-unique CB. |
| GSASL_NO_CB_TLS_EXPORTER | Could not get required tls-exporter CB. |
| GSASL_NO_SAML20_IDP_IDENTIFIER | Could not get required SAML IdP. |
| GSASL_NO_SAML20_REDIRECT_URL | Could not get required SAML redirect URL. |
| GSASL_NO_OPENID20_REDIRECT_URL | Could not get required OpenID redirect URL. |
| GSASL_GSSAPI_RELEASE_BUFFER_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_IMPORT_NAME_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_UNWRAP_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_WRAP_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_ACQUIRE_CRED_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_DISPLAY_NAME_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR | An unsupported quality-of-protection layer was requeted. |
| GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR | GSS-API library call error. |
| GSASL_GSSAPI_RELEASE_OID_SET_ERROR | GSS-API library call error. |
| GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE | SecurID mechanism needs an additional passcode. |
| GSASL_SECURID_SERVER_NEED_NEW_PIN | SecurID mechanism needs an new PIN. |
Error codes for library functions.
| enum Gsasl_saslprep_flags |
Gsasl_saslprep_flags:
| GSASL_ALLOW_UNASSIGNED | Allow unassigned code points. |
Flags for the SASLprep function, see gsasl_saslprep(). For background, see the GNU Libidn documentation.
| Enumerator | |
|---|---|
| GSASL_ALLOW_UNASSIGNED | |
| _GSASL_API int gsasl_base64_from | ( | const char * | in, |
| size_t | inlen, | ||
| char ** | out, | ||
| size_t * | outlen | ||
| ) |
gsasl_base64_from:
| 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 @out 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
| _GSASL_API int gsasl_base64_to | ( | const char * | in, |
| size_t | inlen, | ||
| char ** | out, | ||
| size_t * | outlen | ||
| ) |
gsasl_base64_to:
| in | input byte array. |
| inlen | size of input byte array. |
| out | pointer to newly allocated base64-encoded string. |
| outlen | pointer to size of newly allocated base64-encoded string. |
Encode data as base64. The @out string is zero terminated, and @outlen holds the length excluding the terminating zero. The @out 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
| _GSASL_API int gsasl_callback | ( | Gsasl * | ctx, |
| Gsasl_session * | sctx, | ||
| Gsasl_property | prop | ||
| ) |
gsasl_callback:
| ctx | handle received from gsasl_init(), may be NULL to derive it from @sctx. |
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type. |
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.
Return value: Returns whatever the application callback returns, or GSASL_NO_CALLBACK if no application was known.
Since: 0.2.0
Definition at line 71 of file callback.c.
| _GSASL_API void* gsasl_callback_hook_get | ( | Gsasl * | ctx | ) |
gsasl_callback_hook_get:
| 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 120 of file callback.c.
| _GSASL_API void gsasl_callback_hook_set | ( | Gsasl * | ctx, |
| void * | hook | ||
| ) |
gsasl_callback_hook_set:
| 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 100 of file callback.c.
| _GSASL_API void gsasl_callback_set | ( | Gsasl * | ctx, |
| Gsasl_callback_function | cb | ||
| ) |
gsasl_callback_set:
| 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(@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
Definition at line 45 of file callback.c.
| _GSASL_API const char* gsasl_check_version | ( | const char * | req_version | ) |
gsasl_check_version:
| req_version | version string to compare with, or NULL. |
Check GNU SASL Library version.
See GSASL_VERSION for a suitable @req_version 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 @req_version 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.
| _GSASL_API int gsasl_client_mechlist | ( | Gsasl * | ctx, |
| char ** | out | ||
| ) |
gsasl_client_mechlist:
| 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. @out 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 75 of file listmech.c.
| _GSASL_API int gsasl_client_start | ( | Gsasl * | ctx, |
| const char * | mech, | ||
| Gsasl_session ** | sctx | ||
| ) |
gsasl_client_start:
| 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.
| _GSASL_API const char* gsasl_client_suggest_mechanism | ( | Gsasl * | ctx, |
| const char * | mechlist | ||
| ) |
gsasl_client_suggest_mechanism:
| 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, or NULL if no supported mechanism is found.
| _GSASL_API int gsasl_client_support_p | ( | Gsasl * | ctx, |
| const char * | name | ||
| ) |
gsasl_client_support_p:
| 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 50 of file supportp.c.
| _GSASL_API int gsasl_decode | ( | Gsasl_session * | sctx, |
| const char * | input, | ||
| size_t | input_len, | ||
| char ** | output, | ||
| size_t * | output_len | ||
| ) |
gsasl_decode:
| sctx | libgsasl session handle. |
| input | input byte array. |
| input_len | size of input byte array. |
| output | newly allocated output byte array. |
| output_len | pointer to output variable with size of output byte array. |
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 gsasl_free(@output).
Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.
| _GSASL_API void gsasl_done | ( | Gsasl * | ctx | ) |
| _GSASL_API int gsasl_encode | ( | Gsasl_session * | sctx, |
| const char * | input, | ||
| size_t | input_len, | ||
| char ** | output, | ||
| size_t * | output_len | ||
| ) |
gsasl_encode:
| sctx | libgsasl session handle. |
| input | input byte array. |
| input_len | size of input byte array. |
| output | newly allocated output byte array. |
| output_len | pointer to output variable with size of output byte array. |
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 gsasl_free(@output).
Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.
| _GSASL_API void gsasl_finish | ( | Gsasl_session * | sctx | ) |
| _GSASL_API void gsasl_free | ( | void * | ptr | ) |
gsasl_free:
| ptr | memory pointer |
Invoke free(@ptr) 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 size_t gsasl_hash_length | ( | Gsasl_hash | hash | ) |
gsasl_hash_length:
| hash | a Gsasl_hash element, e.g., GSASL_HASH_SHA256. |
Return the digest output size for hash function @hash. For example, gsasl_hash_length(GSASL_HASH_SHA256) returns GSASL_HASH_SHA256_SIZE which is 32.
Returns: size of supplied Gsasl_hash element.
Since: 1.10
| _GSASL_API int gsasl_hex_from | ( | const char * | in, |
| char ** | out, | ||
| size_t * | outlen | ||
| ) |
gsasl_hex_from:
| in | input byte array |
| out | pointer to newly allocated output byte array |
| outlen | pointer to size of newly allocated output byte array |
Decode hex data. The @out 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: 1.10
| _GSASL_API int gsasl_hex_to | ( | const char * | in, |
| size_t | inlen, | ||
| char ** | out, | ||
| size_t * | outlen | ||
| ) |
gsasl_hex_to:
| in | input byte array. |
| inlen | size of input byte array. |
| out | pointer to newly allocated hex-encoded string. |
| outlen | pointer to size of newly allocated hex-encoded string. |
Hex encode data. The @out string is zero terminated, and @outlen holds the length excluding the terminating zero. The @out 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: 1.10
| _GSASL_API int gsasl_init | ( | Gsasl ** | ctx | ) |
gsasl_init:
| 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.
| _GSASL_API const char* gsasl_mechanism_name | ( | Gsasl_session * | sctx | ) |
gsasl_mechanism_name:
| sctx | libgsasl 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 39 of file mechname.c.
| _GSASL_API int gsasl_mechanism_name_p | ( | const char * | mech | ) |
gsasl_mechanism_name_p:
| mech | input variable with mechanism name string. |
Check if the mechanism name string @mech follows syntactical rules. It does not check that the name is registered with IANA. It does not check that the mechanism name is actually implemented and supported.
SASL mechanisms are named by strings, from 1 to 20 characters in length, consisting of upper-case letters, digits, hyphens, and/or underscores.
Returns: non-zero when mechanism name string @mech conforms to rules, zero when it does not meet the requirements.
Since: 2.0.0
| _GSASL_API int gsasl_nonce | ( | char * | data, |
| size_t | datalen | ||
| ) |
| _GSASL_API const char* gsasl_property_fast | ( | Gsasl_session * | sctx, |
| Gsasl_property | prop | ||
| ) |
gsasl_property_fast:
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type, indicating the type of data in @data. |
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.
Return value: Return property value, if known, or NULL if no value known.
Since: 0.2.0
Definition at line 262 of file property.c.
| _GSASL_API void gsasl_property_free | ( | Gsasl_session * | sctx, |
| Gsasl_property | prop | ||
| ) |
gsasl_property_free:
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type to clear |
Deallocate associated data with property @prop in session handle. After this call, gsasl_property_fast(@sctx, @prop) will always return NULL.
Since: 2.0.0
Definition at line 159 of file property.c.
| _GSASL_API const char* gsasl_property_get | ( | Gsasl_session * | sctx, |
| Gsasl_property | prop | ||
| ) |
gsasl_property_get:
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type, indicating the type of data in @data. |
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.
Return value: Return data for property, or NULL if no value known.
Since: 0.2.0
Definition at line 292 of file property.c.
| _GSASL_API int gsasl_property_set | ( | Gsasl_session * | sctx, |
| Gsasl_property | prop, | ||
| const char * | data | ||
| ) |
gsasl_property_set:
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type, indicating the type of data in @data. |
| data | zero terminated character string to store. |
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.
Return value: GSASL_OK iff successful, otherwise GSASL_MALLOC_ERROR.
Since: 0.2.0
Definition at line 189 of file property.c.
| _GSASL_API int gsasl_property_set_raw | ( | Gsasl_session * | sctx, |
| Gsasl_property | prop, | ||
| const char * | data, | ||
| size_t | len | ||
| ) |
gsasl_property_set_raw:
| sctx | session handle. |
| prop | enumerated value of Gsasl_property type, indicating the type of data in @data. |
| data | character string to store. |
| len | length of character string to store. |
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.
Return value: GSASL_OK iff successful, otherwise GSASL_MALLOC_ERROR.
Since: 0.2.0
Definition at line 218 of file property.c.
| _GSASL_API int gsasl_random | ( | char * | data, |
| size_t | datalen | ||
| ) |
| _GSASL_API int gsasl_saslprep | ( | const char * | in, |
| Gsasl_saslprep_flags | flags, | ||
| char ** | out, | ||
| int * | stringpreprc | ||
| ) |
| _GSASL_API int gsasl_scram_secrets_from_password | ( | Gsasl_hash | hash, |
| const char * | password, | ||
| unsigned int | iteration_count, | ||
| const char * | salt, | ||
| size_t | saltlen, | ||
| char * | salted_password, | ||
| char * | client_key, | ||
| char * | server_key, | ||
| char * | stored_key | ||
| ) |
gsasl_scram_secrets_from_password:
| hash | a Gsasl_hash element, e.g., GSASL_HASH_SHA256. |
| password | input parameter with password. |
| iteration_count | number of PBKDF2 rounds to apply. |
| salt | input character array of @saltlen length with salt for PBKDF2. |
| saltlen | length of @salt. |
| salted_password | pre-allocated output array with derived salted password. |
| client_key | pre-allocated output array with derived client key. |
| server_key | pre-allocated output array with derived server key. |
| stored_key | pre-allocated output array with derived stored key. |
Helper function to generate SCRAM secrets from a password. The @salted_password, @client_key, @server_key, and @stored_key buffers must have room to hold digest for given @hash, use GSASL_HASH_MAX_SIZE which is sufficient for all hashes.
Return value: Returns GSASL_OK if successful, or error code.
Since: 1.10
| _GSASL_API int gsasl_scram_secrets_from_salted_password | ( | Gsasl_hash | hash, |
| const char * | salted_password, | ||
| char * | client_key, | ||
| char * | server_key, | ||
| char * | stored_key | ||
| ) |
gsasl_scram_secrets_from_salted_password:
| hash | a Gsasl_hash element, e.g., GSASL_HASH_SHA256. |
| salted_password | input array with salted password. |
| client_key | pre-allocated output array with derived client key. |
| server_key | pre-allocated output array with derived server key. |
| stored_key | pre-allocated output array with derived stored key. |
Helper function to derive SCRAM ClientKey/ServerKey/StoredKey. The @client_key, @server_key, and @stored_key buffers must have room to hold digest for given @hash, use GSASL_HASH_MAX_SIZE which is sufficient for all hashes.
Return value: Returns GSASL_OK if successful, or error code.
Since: 1.10
| _GSASL_API int gsasl_server_mechlist | ( | Gsasl * | ctx, |
| char ** | out | ||
| ) |
gsasl_server_mechlist:
| 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. @out 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 94 of file listmech.c.
| _GSASL_API int gsasl_server_start | ( | Gsasl * | ctx, |
| const char * | mech, | ||
| Gsasl_session ** | sctx | ||
| ) |
gsasl_server_start:
| 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.
| _GSASL_API int gsasl_server_support_p | ( | Gsasl * | ctx, |
| const char * | name | ||
| ) |
gsasl_server_support_p:
| 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 67 of file supportp.c.
| _GSASL_API void* gsasl_session_hook_get | ( | Gsasl_session * | sctx | ) |
gsasl_session_hook_get:
| 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 160 of file callback.c.
| _GSASL_API void gsasl_session_hook_set | ( | Gsasl_session * | sctx, |
| void * | hook | ||
| ) |
gsasl_session_hook_set:
| sctx | libgsasl session handle. |
| hook | opaque 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 140 of file callback.c.
| _GSASL_API int gsasl_simple_getpass | ( | const char * | filename, |
| const char * | username, | ||
| char ** | key | ||
| ) |
gsasl_simple_getpass:
| filename | filename of file containing passwords. |
| username | username string. |
| key | newly allocated output character array. |
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.
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.
| _GSASL_API int gsasl_step | ( | Gsasl_session * | sctx, |
| const char * | input, | ||
| size_t | input_len, | ||
| char ** | output, | ||
| size_t * | output_len | ||
| ) |
gsasl_step:
| sctx | libgsasl session handle. |
| input | input byte array. |
| input_len | size of input byte array. |
| output | newly allocated output byte array. |
| output_len | pointer to output variable with size of output byte array. |
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 gsasl_free(@output).
Return value: Returns GSASL_OK if authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.
| _GSASL_API int gsasl_step64 | ( | Gsasl_session * | sctx, |
| const char * | b64input, | ||
| char ** | b64output | ||
| ) |
gsasl_step64:
| sctx | libgsasl client handle. |
| b64input | input base64 encoded byte array. |
| b64output | newly 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 @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 gsasl_free(@b64output).
Return value: Returns GSASL_OK if authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.
| _GSASL_API const char* gsasl_strerror | ( | int | err | ) |
gsasl_strerror:
| err | libgsasl 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 @err.
| _GSASL_API const char* gsasl_strerror_name | ( | int | err | ) |
gsasl_strerror_name:
| err | libgsasl 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 @err, or NULL if the error code is not known.
Since: 0.2.29
1.9.1