KeyMaster integration

Macros
#define	DS_SIGNATURE_ALREADY_USED
	KeyMaster token has already been used. More...
#define	DS_SIGNATURE_INVALID_TOKEN
	KeyMaster token was invalid. More...
#define	DS_SIGNATURE_OK
	KeyMaster token was validated correctly. More...
#define	DS_SIGNATURE_UNKNOWN_KEYID
	Unknown key-id supplied to function. More...

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

Detailed Description

The Caplin KeyMaster generates single-use encrypted tokens that are used as the client login password to the Liberator and also for authentication to the Monitoring system. They can also be used by DataSources for authentication purposes.

KeyMaster uses a private key to encrypt the token and the DataSource 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 authentication. When the KeyMaster server is protected behind a single-signon system this allows the DataSource to use the same single signon mechanism without the need for direct connection to the signon database or back-end system.

Macro Definition Documentation

#define DS_SIGNATURE_ALREADY_USED

KeyMaster token has already been used.

#define DS_SIGNATURE_INVALID_TOKEN

KeyMaster token was invalid.

#define DS_SIGNATURE_OK

KeyMaster token was validated correctly.

#define DS_SIGNATURE_UNKNOWN_KEYID

Unknown key-id supplied to function.

Function Documentation

int ds_signature_check	(	char *	key_id,
		char *	token
	)

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

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

The DataSource 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

DS_SIGNATURE_UNKNOWN_KEYID	- The supplied identifier does not match any configured.
DS_SIGNATURE_INVALID_TOKEN	- The supplied token was invalid
DS_SIGNATURE_ALREADY_USED	- The token supplied has already been used to log in.
DS_SIGNATURE_OK	- Authorisation succeeded

int ds_signature_verify_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

DS_SIGNATURE_INVALID_TOKEN	- The username does not match that in the token.
DS_SIGNATURE_OK	- The username does match that in the token.