Top |
typedef | Gsasl |
typedef | Gsasl_session |
enum | Gsasl_rc |
enum | Gsasl_property |
enum | Gsasl_mechname_limits |
enum | Gsasl_qop |
enum | Gsasl_saslprep_flags |
enum | Gsasl_hash |
enum | Gsasl_hash_length |
int (*Gsasl_callback_function) (Gsasl *ctx
,Gsasl_session *sctx
,Gsasl_property prop
);
Prototype of function that the application should implement. Use
gsasl_callback_set()
to inform the library about your callback
function.
It is called by the SASL library when it need some information
from the application. Depending on the value of prop
, it should
either set some property (e.g., username or password) using
gsasl_property_set()
, or it should extract some properties (e.g.,
authentication and authorization identities) using
gsasl_property_fast()
and use them to make a policy decision,
perhaps returning GSASL_AUTHENTICATION_ERROR or GSASL_OK
depending on whether the policy permitted the operation.
ctx |
libgsasl handle. |
|
sctx |
session handle, may be NULL. |
|
prop |
enumerated value of Gsasl_property type. |
Since: 0.2.0
int
gsasl_init (Gsasl **ctx
);
This functions initializes libgsasl. The handle pointed to by ctx
is valid for use with other libgsasl functions iff this function is
successful. It also register all builtin SASL mechanisms, using
gsasl_register()
.
void
gsasl_done (Gsasl *ctx
);
This function destroys a libgsasl handle. The handle must not be used with other libgsasl functions after this call.
const char *
gsasl_check_version (const char *req_version
);
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()
.
void gsasl_callback_set (Gsasl *ctx
,Gsasl_callback_function cb
);
Store the pointer to the application provided callback in the
library handle. The callback will be used, via gsasl_callback()
,
by mechanisms to discover various parameters (such as username and
passwords). The callback function will be called with a
Gsasl_property value indicating the requested behaviour. For
example, for GSASL_ANONYMOUS_TOKEN
, the function is expected to
invoke gsasl_property_set(CTX
, GSASL_ANONYMOUS_TOKEN
, "token")
where "token" is the anonymous token the application wishes the
SASL mechanism to use. See the manual for the meaning of all
parameters.
ctx |
handle received from |
|
cb |
pointer to function implemented by application. |
Since: 0.2.0
int gsasl_callback (Gsasl *ctx
,Gsasl_session *sctx
,Gsasl_property prop
);
Invoke the application callback. The prop
value indicate what the
callback is expected to do. For example, for
GSASL_ANONYMOUS_TOKEN
, the function is expected to invoke
gsasl_property_set(SCTX
, GSASL_ANONYMOUS_TOKEN
, "token") where
"token" is the anonymous token the application wishes the SASL
mechanism to use. See the manual for the meaning of all
parameters.
ctx |
handle received from |
|
sctx |
session handle. |
|
prop |
enumerated value of Gsasl_property type. |
Returns whatever the application callback returns, or
GSASL_NO_CALLBACK
if no application was known.
Since: 0.2.0
void gsasl_callback_hook_set (Gsasl *ctx
,void *hook
);
Store application specific data in the libgsasl handle.
The application data can be later (for instance, inside a callback)
be retrieved by calling gsasl_callback_hook_get()
. This is
normally used by the application to maintain a global state between
the main program and callbacks.
Since: 0.2.0
void *
gsasl_callback_hook_get (Gsasl *ctx
);
Retrieve application specific data from libgsasl handle.
The application data is set using gsasl_callback_hook_set()
. This
is normally used by the application to maintain a global state
between the main program and callbacks.
Since: 0.2.0
void gsasl_session_hook_set (Gsasl_session *sctx
,void *hook
);
Store application specific data in the libgsasl session handle.
The application data can be later (for instance, inside a callback)
be retrieved by calling gsasl_session_hook_get()
. This is normally
used by the application to maintain a per-session state between the
main program and callbacks.
Since: 0.2.14
void *
gsasl_session_hook_get (Gsasl_session *sctx
);
Retrieve application specific data from libgsasl session handle.
The application data is set using gsasl_callback_hook_set()
. This
is normally used by the application to maintain a per-session state
between the main program and callbacks.
Since: 0.2.14
int gsasl_property_set (Gsasl_session *sctx
,Gsasl_property prop
,const char *data
);
Make a copy of data
and store it in the session handle for the
indicated property prop
.
You can immediately deallocate data
after calling this function,
without affecting the data stored in the session handle.
sctx |
session handle. |
|
prop |
enumerated value of Gsasl_property type, indicating the
type of data in |
|
data |
zero terminated character string to store. |
Since: 0.2.0
int gsasl_property_set_raw (Gsasl_session *sctx
,Gsasl_property prop
,const char *data
,size_t len
);
Make a copy of len
sized data
and store a zero terminated version
of it in the session handle for the indicated property prop
.
You can immediately deallocate data
after calling this function,
without affecting the data stored in the session handle.
Except for the length indicator, this function is identical to gsasl_property_set.
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. |
Since: 0.2.0
void gsasl_property_free (Gsasl_session *sctx
,Gsasl_property prop
);
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
const char * gsasl_property_get (Gsasl_session *sctx
,Gsasl_property prop
);
Retrieve the data stored in the session handle for given property
prop
, possibly invoking the application callback to get the value.
The pointer is to live data, and must not be deallocated or modified in any way.
This function will invoke the application callback, using
gsasl_callback()
, when a property value is not known.
sctx |
session handle. |
|
prop |
enumerated value of Gsasl_property type, indicating the
type of data in |
Since: 0.2.0
const char * gsasl_property_fast (Gsasl_session *sctx
,Gsasl_property prop
);
Retrieve the data stored in the session handle for given property
prop
.
The pointer is to live data, and must not be deallocated or modified in any way.
This function will not invoke the application callback.
sctx |
session handle. |
|
prop |
enumerated value of Gsasl_property type, indicating the
type of data in |
Since: 0.2.0
int gsasl_client_mechlist (Gsasl *ctx
,char **out
);
Return a newly allocated string containing SASL names, separated by
space, of mechanisms supported by the libgsasl client. out
is
allocated by this function, and it is the responsibility of caller
to deallocate it.
int gsasl_client_support_p (Gsasl *ctx
,const char *name
);
Decide whether there is client-side support for a specified mechanism.
const char * gsasl_client_suggest_mechanism (Gsasl *ctx
,const char *mechlist
);
Given a list of mechanisms, suggest which to use.
int gsasl_server_mechlist (Gsasl *ctx
,char **out
);
Return a newly allocated string containing SASL names, separated by
space, of mechanisms supported by the libgsasl server. out
is
allocated by this function, and it is the responsibility of caller
to deallocate it.
int gsasl_server_support_p (Gsasl *ctx
,const char *name
);
Decide whether there is server-side support for a specified mechanism.
int
gsasl_mechanism_name_p (const char *mech
);
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.
non-zero when mechanism name string mech
conforms to
rules, zero when it does not meet the requirements.
Since: 2.0.0
int gsasl_client_start (Gsasl *ctx
,const char *mech
,Gsasl_session **sctx
);
This functions initiates a client SASL authentication. This function must be called before any other gsasl_client_*() function is called.
int gsasl_server_start (Gsasl *ctx
,const char *mech
,Gsasl_session **sctx
);
This functions initiates a server SASL authentication. This function must be called before any other gsasl_server_*() function is called.
int gsasl_step (Gsasl_session *sctx
,const char *input
,size_t input_len
,char **output
,size_t *output_len
);
Perform one step of SASL authentication. This reads data from the
other end (from input
and input_len
), processes it (potentially
invoking callbacks to the application), and writes data to server
(into newly allocated variable output
and output_len
that
indicate the length of output
).
The contents of the output
buffer is unspecified if this functions
returns anything other than GSASL_OK
or GSASL_NEEDS_MORE
. If
this function return GSASL_OK
or GSASL_NEEDS_MORE
, however, the
output
buffer is allocated by this function, and it is the
responsibility of caller to deallocate it by calling
gsasl_free(output
).
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. |
Returns GSASL_OK
if authenticated terminated
successfully, GSASL_NEEDS_MORE
if more data is needed, or error
code.
int gsasl_step64 (Gsasl_session *sctx
,const char *b64input
,char **b64output
);
This is a simple wrapper around gsasl_step()
that base64 decodes
the input and base64 encodes the output.
The contents of the b64output
buffer is unspecified if this
functions returns anything other than GSASL_OK
or
GSASL_NEEDS_MORE
. If this function return GSASL_OK
or
GSASL_NEEDS_MORE
, however, the b64output
buffer is allocated by
this function, and it is the responsibility of caller to deallocate
it by calling gsasl_free(b64output
).
sctx |
libgsasl client handle. |
|
b64input |
input base64 encoded byte array. |
|
b64output |
newly allocated output base64 encoded byte array. |
Returns GSASL_OK
if authenticated terminated
successfully, GSASL_NEEDS_MORE
if more data is needed, or error
code.
void
gsasl_finish (Gsasl_session *sctx
);
Destroy a libgsasl client or server handle. The handle must not be used with other libgsasl functions after this call.
int gsasl_encode (Gsasl_session *sctx
,const char *input
,size_t input_len
,char **output
,size_t *output_len
);
Encode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.
The output
buffer is allocated by this function, and it is the
responsibility of caller to deallocate it by calling
gsasl_free(output
).
int gsasl_decode (Gsasl_session *sctx
,const char *input
,size_t input_len
,char **output
,size_t *output_len
);
Decode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.
The output
buffer is allocated by this function, and it is the
responsibility of caller to deallocate it by calling
gsasl_free(output
).
const char *
gsasl_mechanism_name (Gsasl_session *sctx
);
This function returns the name of the SASL mechanism used in the session. The pointer must not be deallocated by the caller.
Returns a zero terminated character array with the name of the SASL mechanism, or NULL if not known.
Since: 0.2.28
const char *
gsasl_strerror (int err
);
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()
.
const char *
gsasl_strerror_name (int err
);
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()
.
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
int gsasl_saslprep (const char *in
,Gsasl_saslprep_flags flags
,char **out
,int *stringpreprc
);
Prepare string using SASLprep. On success, the out
variable must
be deallocated by the caller.
in |
a UTF-8 encoded string. |
|
flags |
any SASLprep flag, e.g., |
|
out |
on exit, contains newly allocated output string. |
|
stringpreprc |
if non-NULL, will hold precise stringprep return code. |
Since: 0.2.3
int gsasl_nonce (char *data
,size_t datalen
);
Store unpredictable data of given size in the provided buffer.
int gsasl_random (char *data
,size_t datalen
);
Store cryptographically strong random data of given size in the provided buffer.
size_t
gsasl_hash_length (Gsasl_hash hash
);
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.
Since: 1.10
int gsasl_scram_secrets_from_salted_password (Gsasl_hash hash
,const char *salted_password
,char *client_key
,char *server_key
,char *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.
hash |
a |
|
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. |
Since: 1.10
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
);
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.
hash |
a |
|
password |
input parameter with password. |
|
iteration_count |
number of PBKDF2 rounds to apply. |
|
salt |
input character array of |
|
saltlen |
length of |
|
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. |
Since: 1.10
int gsasl_simple_getpass (const char *filename
,const char *username
,char **key
);
Retrieve password for user from specified file. The buffer key
contain the password if this function is successful. The caller is
responsible for deallocating it.
The file should be on the UoW "MD5 Based Authentication" format, which means it is in text format with comments denoted by # first on the line, with user entries looking as "usernameTABpassword". This function removes CR and LF at the end of lines before processing. TAB, CR, and LF denote ASCII values 9, 13, and 10, respectively.
filename |
filename of file containing passwords. |
|
username |
username string. |
|
key |
newly allocated output character array. |
Return GSASL_OK
if output buffer contains the
password, GSASL_AUTHENTICATION_ERROR
if the user could not be
found, or other error code.
int gsasl_base64_to (const char *in
,size_t inlen
,char **out
,size_t *outlen
);
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.
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. |
Returns GSASL_OK
on success, or GSASL_MALLOC_ERROR
if input was too large or memory allocation fail.
Since: 0.2.2
int gsasl_base64_from (const char *in
,size_t inlen
,char **out
,size_t *outlen
);
Decode Base64 data. The out
buffer must be deallocated by the
caller.
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 |
Returns GSASL_OK
on success, GSASL_BASE64_ERROR
if
input was invalid, and GSASL_MALLOC_ERROR
on memory allocation
errors.
Since: 0.2.2
int gsasl_hex_to (const char *in
,size_t inlen
,char **out
,size_t *outlen
);
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.
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. |
Returns GSASL_OK
on success, or GSASL_MALLOC_ERROR
if input was too large or memory allocation fail.
Since: 1.10
int gsasl_hex_from (const char *in
,char **out
,size_t *outlen
);
Decode hex data. The out
buffer must be deallocated by the
caller.
in |
input byte array |
|
out |
pointer to newly allocated output byte array |
|
outlen |
pointer to size of newly allocated output byte array |
Returns GSASL_OK
on success, GSASL_BASE64_ERROR
if
input was invalid, and GSASL_MALLOC_ERROR
on memory allocation
errors.
Since: 1.10
void
gsasl_free (void *ptr
);
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
Error codes for library functions.
Successful return code, guaranteed to be always 0. |
||
Mechanism expects another round-trip. |
||
Application requested an unknown mechanism. |
||
Application requested too many round trips from mechanism. |
||
Memory allocation failed. |
||
Base64 encoding/decoding failed. |
||
Cryptographic error. |
||
Failed to prepare internationalized string. |
||
Mechanism could not parse input. |
||
Authentication has failed. |
||
Application data integrity check failed. |
||
Library was built with client functionality. |
||
Library was built with server functionality. |
||
Application did not provide a callback. |
||
Could not get required anonymous token. |
||
Could not get required authentication identity (username). |
||
Could not get required authorization identity. |
||
Could not get required password. |
||
Could not get required SecurID PIN. |
||
Could not get required SecurID PIN. |
||
Could not get required service name. |
||
Could not get required hostname. |
||
Could not get required tls-unique CB. |
||
Could not get required SAML IdP. |
||
Could not get required SAML redirect URL. |
||
Could not get required OpenID redirect URL. |
||
Could not get required tls-exporter CB. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
An unsupported quality-of-protection layer was requeted. |
||
SecurID mechanism needs an additional passcode. |
||
SecurID mechanism needs an new PIN. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
||
GSS-API library call error. |
Callback/property types.
Authentication identity (username). |
||
Authorization identity. |
||
Password. |
||
Anonymous identifier. |
||
Service name |
||
Host name. |
||
GSS-API credential principal name. |
||
SecurID passcode. |
||
SecurID suggested PIN. |
||
SecurID PIN. |
||
User realm. |
||
Pre-computed hashed DIGEST-MD5 password, to avoid storing passwords in the clear. |
||
Set of quality-of-protection values. |
||
Quality-of-protection value. |
||
Number of iterations in password-to-key hashing. |
||
Salt for password-to-key hashing. |
||
Hex-encoded hashed/salted password. |
||
Hex-encoded SCRAM ServerKey derived from users' passowrd. |
||
Hex-encoded SCRAM StoredKey derived from users' passowrd. |
||
Base64 encoded tls-unique channel binding. |
||
SAML20 user IdP URL. |
||
SAML 2.0 URL to access in browser. |
||
OpenID 2.0 URL to access in browser. |
||
OpenID 2.0 authentication outcome data. |
||
Base64 encoded tls-exporter channel binding. |
||
Request to perform SAML 2.0 authentication in browser. |
||
Request to perform OpenID 2.0 authentication in browser. |
||
Request for simple validation. |
||
Request for validation of EXTERNAL. |
||
Request for validation of ANONYMOUS. |
||
Request for validation of GSSAPI/GS2. |
||
Reqest for validation of SecurID. |
||
Reqest for validation of SAML20. |
||
Reqest for validation of OpenID 2.0 login. |
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()
.
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.
Flags for the SASLprep function, see gsasl_saslprep()
. For
background, see the GNU Libidn documentation.
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
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()
.
Output size of hash function SHA-1. |
||
Output size of hash function SHA-256. |
||
Maximum output size of any |
Since: 1.10