KeyMaster integration

Functions
int	auth_verify_signature_username (char *expected_username, char *token)
	Verify that the supplied token is for the expected username. More...
int	signature_check (char *key_id, char *token)
	Provides a mechanism for validating a KeyMaster-generated encrypted single-use token. More...

Detailed Description

The Caplin KeyMaster generates single-use encrypted tokens that are used as the client login password to the Liberator. The KeyMaster uses a private key to encrypt the token and the Liberator holds the corresponding public key that is used for decryption. This ensures that only the KeyMaster could possibly generate a valid token that is used for login. When the KeyMaster server is protected behind a single-signon system this allows the Liberator to use the same single signon mechanism without the need for direct connection to the signon database or back-end system.

The Liberator Auth API provides a mechanism for validating these tokens by using the signature_check() function.

If a user is known to be presenting a KeyMaster token as a password during login, then a call to this method will cause the Liberator to check the validity of the token. This return value can then be used as the return to the _authfuncs::new_user() function.

Function Documentation

int auth_verify_signature_username	(	char *	expected_username,
		char *	token
	)

Verify that the supplied token is for the expected username.

Parameters

expected_username	- The expected username
token	- The supplied token

Return values

AUTH_DENY	- The username does not match that in the token.
AUTH_OK	- The username does match that in the token.

int signature_check	(	char *	key_id,
		char *	token
	)

Provides a mechanism for validating a KeyMaster-generated encrypted single-use token.

The token is usually provided during a _authfuncs::new_user() call as the password parameter. This function can then be used to check that the provided token is valid.

The key_id parameter is used to uniquely identify which key the Liberator should use when decrypting the token (this matches the corresponding key-id option within the add-sigkey section of the Liberator configuration file

The Liberator may be configured to use multiple decryption keys, which are uniquely identified by the key-id option.

Parameters

key_id	KeyMaster key identifier
token	KeyMaster token

Return values

AUTH_INVALID_USER	- The supplied identifier does not match any configured.
AUTH_DENY	- The supplied token was invalid
AUTH_USER_LC_EXCEEDED	- The token supplied has already been used to log in.
AUTH_OK	- Authorisation succeeded