---

10 Utilities

gsasl_saslprep

Function: int gsasl_saslprep (const char * in, Gsasl_saslprep_flags flags, char ** out, int * stringpreprc) ¶

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 out variable must be deallocated by the caller.

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

Since: 0.2.3

gsasl_base64_to

Function: int gsasl_base64_to (const char * in, size_t inlen, char ** out, size_t * outlen) ¶

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_base64_from

Function: int gsasl_base64_from (const char * in, size_t inlen, char ** out, size_t * outlen) ¶

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_hex_to

Function: int gsasl_hex_to (const char * in, size_t inlen, char ** out, size_t * outlen) ¶

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_hex_from

Function: int gsasl_hex_from (const char * in, char ** out, size_t * outlen) ¶

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_simple_getpass

Function: int gsasl_simple_getpass (const char * filename, const char * username, char ** key) ¶

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_nonce

Function: int gsasl_nonce (char * data, size_t datalen) ¶

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.

gsasl_random

Function: int gsasl_random (char * data, size_t datalen) ¶

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.

gsasl_hash_length

Function: size_t gsasl_hash_length (Gsasl_hash hash) ¶

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_scram_secrets_from_salted_password

Function: int gsasl_scram_secrets_from_salted_password (Gsasl_hash hash, const char * salted_password, char * client_key, char * server_key, char * stored_key) ¶

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_scram_secrets_from_password

Function: 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) ¶

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