GDKerberosAuthHandler Class Reference

Manage the BlackBerry Dynamics cache of Kerberos credentials (C++). More...

#include <GDKerberosAuthHandler.h>

Description

The BlackBerry Dynamics runtime stores, in a secure cache, Kerberos tickets obtained in the course of its secure communication with application servers. This C++ class contains a number of functions for managing tickets in the cache, and for setting default ticket request parameters and configuration.

This class supports Kerberos delegation in a number of forms. However, use of this class alone doesn't necessarily result in delegation being used in all cases. The use of delegation can also depend on configuration in the Kerberos Key Distribution Center (KDC) and in the BlackBerry Dynamics management console.

Public Member Functions
	GDKerberosAuthHandler ()
	Constructor. More...
Krb5ErrorCode	setUpKerberosTicket (const char *username, const char *password, bool allowDelegation)
	Get a Kerberos ticket with a user name and password, and specify whether it can be delegated. More...
Krb5ErrorCode	setUpKerberosTicket (const char *username, const char *password)
	Get a Kerberos ticket with a user name and password. More...
Krb5ErrorCode	setUpKerberosTicket (bool allowDelegation)
	Get a Kerberos ticket via PKINIT authentication. More...
Krb5ErrorCode	setUpKerberosTicket (const char *host, int port, bool allowDelegation)
	Get a Kerberos ticket via Kerberos Constrained Delegation, with implicit credentials, and specify whether it can be delegated. More...
Krb5ErrorCode	setUpKerberosTicket (const char *host, int port)
	Get a Kerberos ticket via delegation, with implicit credentials. More...
bool	implicitCredentialsAllowed ()
	Check whether implicit credentials are allowed. More...
void	setUpKerberosTicketAsync (const char *username, const char *password, bool allowDelegation, GDKerberosAuthCallback &callback)
	Asynchronously get a Kerberos ticket by supplying user name, password, and whether it can be delegated. More...
void	setUpKerberosTicketAsync (const char *username, const char *password, GDKerberosAuthCallback &callback)
	Asynchronously get a Kerberos ticket with a user name and password. More...
void	setUpKerberosTicketAsync (bool allowDelegation, GDKerberosAuthCallback &callback)
	Asynchronously get a Kerberos ticket via PKINIT authentication. More...
void	setUpKerberosTicketAsync (const char *host, int port, bool allowDelegation, GDKerberosAuthCallback &callback)
	Asynchronously get a Kerberos ticket via Kerberos Constrained Delegation, with implicit credentials, and specify whether it can be delegated. More...
void	setUpKerberosTicketAsync (const char *host, int port, GDKerberosAuthCallback &callback)
	Asynchronously get a Kerberos ticket via delegation, with implicit credentials. More...

Static Public Member Functions
static bool	getAllowDelegation ()
	Check whether Kerberos authentication delegation is allowed or disallowed. More...
static void	setAllowDelegation (bool allow)
	Allow or disallow Kerberos authentication delegation. More...
static void	clearCache ()
	Clear cached Kerberos authentication credentials and tickets. More...

Constructor & Destructor Documentation

GDKerberosAuthHandler()

GDKerberosAuthHandler

(

)

Constructor.

Member Function Documentation

getAllowDelegation()

static bool getAllowDelegation ( )

static

Call this function to check whether Kerberos authentication delegation is allowed or disallowed, within BlackBerry Dynamics secure communication.

Kerberos authentication delegation can be allowed and disallowed by calling the setAllowDelegation function, below.

Returns

true if Kerberos delegation is allowed within BlackBerry Dynamics secure communication.

false otherwise

setAllowDelegation()

static void setAllowDelegation ( bool  allow )

static

Call this function to allow or disallow Kerberos delegation within BlackBerry Dynamics secure communications. By default, Kerberos delegation is disallowed.

If Kerberos delegation is allowed, the BlackBerry Dynamics runtime behaves as follows.

• Kerberos requests will be for tickets that can be delegated.
• Application servers that are trusted for delegation can be sent tickets that can be delegated, if such tickets were issued.

If Kerberos delegation isn't allowed, the BlackBerry Dynamics runtime behaves as follows.

• Kerberos requests won't be for tickets that can be delegated.
• Application servers won't be sent tickets that can be delegated, even if such tickets were issued.

After this function has been called, delegation will remain allowed or disallowed until this function is called again with a different setting.

Note: User and service configuration in the Kerberos Key Distribution Center (KDC), typically a Microsoft Active Directory server, is required in order for delegation to be successful. On its own, calling this function won't make Kerberos delegation work in the whole end-to-end application.

When this function is called, the Kerberos ticket and credentials caches will be cleared, i.e. there is an effective call to the clearCache function, below.

Parameters

allow

bool for the setting: true to allow delegation, false to disallow.

clearCache()

static void clearCache ( )

static

Call this function to clear the cached Kerberos authentication credentials and tickets. The session cache and permanent cache will both be cleared.

setUpKerberosTicket() [1/5]

Krb5ErrorCode setUpKerberosTicket	(	const char *	username,
		const char *	password,
		bool	allowDelegation
	)

Call this function to create an initial Kerberos ticket for authentication. This will be a Ticket-to-Get-Tickets (TGT), for a specified user principal. If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

Specify in the allowDelegation parameter whether to request a ticket that can be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

BlackBerry Dynamics secure communication supports Kerberos authentication of only one active user principal at a time.

The user principal name must be in the user@realm long form. The short form shortrealm\user isn't supported.

Parameters

username	char* pointer to memory containing the user principal name, and a null terminator.
password	char* pointer to memory containing the Kerberos authentication password for the user principal, and a null terminator.
allowDelegation	bool for whether to request a ticket that can be delegated.

Returns

KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicket() [2/5]

Krb5ErrorCode setUpKerberosTicket	(	const char *	username,
		const char *	password
	)

Calling this function is equivalent to calling the following.

setUpKerberosTicket(username, password, getAllowDelegation())

Parameters

username	char* pointer to memory containing the user principal name, and a null terminator.
password	char* pointer to memory containing the Kerberos authentication password for the user principal, and a null terminator.

Returns

KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicket() [3/5]

Krb5ErrorCode setUpKerberosTicket

(

bool

allowDelegation

)

Call this function to create an initial Kerberos ticket for authentication. This will be a Ticket-to-Get-Tickets (TGT), for an implicit user principal authenticated by using public key cryptography for initial Kerberos authentication (PKINIT). If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

This function depends on the enterprise having deployed PKINIT authentication.

Specify in the allowDelegation parameter whether to request a ticket that can be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

Parameters

allowDelegation

bool for whether to request a ticket that can be delegated.

Returns

KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicket() [4/5]

Krb5ErrorCode setUpKerberosTicket	(	const char *	host,
		int	port,
		bool	allowDelegation
	)

Call this function to create a Kerberos ticket for authentication. This will be a service ticket obtained by Kerberos Constrained Delegation (KCD) to a specified authentication host, with implicit credentials. If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

Specify the authentication service address by its fully qualified domain name (FQDN) and port number.

Specify in the allowDelegation parameter whether to request a ticket that can itself be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

Check that implicit credentials are allowed, by calling the implicitCredentialsAllowed() function, before calling this function.

Parameters

host	char* pointer to memory containing the FQDN of the authentication server, and a null terminator.
port	int for the port number of the authentication service.
allowDelegation	bool for whether to request a ticket that can be delegated.

Returns

KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicket() [5/5]

Krb5ErrorCode setUpKerberosTicket	(	const char *	host,
		int	port
	)

Calling this function is equivalent to calling the following.

setUpKerberosTicket(host, port, getAllowDelegation())

Parameters

host	char* pointer to memory containing the FQDN of the authentication server, and a null terminator.
port	int for the port number of the authentication service.

Returns

KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

implicitCredentialsAllowed()

bool implicitCredentialsAllowed

(

)

Call this function to check whether implicit credentials are allowed.

If implicit credentials are allowed, then the following ticket set-up variants can be used.

• setUpKerberosTicket(const char* host, int port, bool allowDelegation)
• setUpKerberosTicket(const char* host, int port)

In those variants, a ticket is obtained by Kerberos Constrained Delegation (KCD).

Returns

true if implicit credentials are allowed.

false otherwise.

setUpKerberosTicketAsync() [1/5]

void setUpKerberosTicketAsync	(	const char *	username,
		const char *	password,
		bool	allowDelegation,
		GDKerberosAuthCallback &	callback
	)

Call this function to asynchronously create an initial Kerberos ticket for authentication. This will be a Ticket-to-Get-Tickets (TGT), for a specified user principal. If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

Specify in the allowDelegation parameter whether to request a ticket that can be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

BlackBerry Dynamics secure communication supports Kerberos authentication of only one active user principal at a time.

The user principal name must be in the user@realm long form. The short form shortrealm\user isn't supported.

Parameters

username	char* pointer to memory containing the user principal name, and a null terminator.
password	char* pointer to memory containing the Kerberos authentication password for the user principal, and a null terminator.
allowDelegation	bool for whether to request a ticket that can be delegated.
callback	GDKerberosAuthCallback& if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicketAsync() [2/5]

void setUpKerberosTicketAsync	(	const char *	username,
		const char *	password,
		GDKerberosAuthCallback &	callback
	)

Calling this function is equivalent to calling the following.

setUpKerberosTicketAsync(username, password, getAllowDelegation(), callback)

Parameters

username	char* pointer to memory containing the user principal name, and a null terminator.
password	char* pointer to memory containing the Kerberos authentication password for the user principal, and a null terminator.
callback	GDKerberosAuthCallback& if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicketAsync() [3/5]

void setUpKerberosTicketAsync	(	bool	allowDelegation,
		GDKerberosAuthCallback &	callback
	)

Call this function to asynchronously create an initial Kerberos ticket for authentication. This will be a Ticket-to-Get-Tickets (TGT), for an implicit user principal authenticated by using public key cryptography for initial Kerberos authentication (PKINIT). If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

This function depends on the enterprise having deployed PKINIT authentication.

Specify in the allowDelegation parameter whether to request a ticket that can be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

Parameters

allowDelegation	bool for whether to request a ticket that can be delegated.
callback	GDKerberosAuthCallback& if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicketAsync() [4/5]

void setUpKerberosTicketAsync	(	const char *	host,
		int	port,
		bool	allowDelegation,
		GDKerberosAuthCallback &	callback
	)

Call this function to asynchronously create a Kerberos ticket for authentication. This will be a service ticket obtained by Kerberos Constrained Delegation (KCD) to a specified authentication host, with implicit credentials. If the ticket is created, it will be stored in the BlackBerry Dynamics secure cache.

Specify the authentication service address by its fully qualified domain name (FQDN) and port number.

Specify in the allowDelegation parameter whether to request a ticket that can itself be delegated. Even if a ticket that can be delegated is requested, a ticket that cannot be delegated might be issued, depending on the configuration of the Kerberos KDC.

Check that implicit credentials are allowed, by calling the implicitCredentialsAllowed() function, before calling this function.

Parameters

host	char* pointer to memory containing the FQDN of the authentication server, and a null terminator.
port	int for the port number of the authentication service.
allowDelegation	bool for whether to request a ticket that can be delegated.
callback	GDKerberosAuthCallback& if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.

setUpKerberosTicketAsync() [5/5]

void setUpKerberosTicketAsync	(	const char *	host,
		int	port,
		GDKerberosAuthCallback &	callback
	)

Calling this function is equivalent to calling the following.

setUpKerberosTicketAsync(host, port, getAllowDelegation(), callback)

Parameters

host	char* pointer to memory containing the FQDN of the authentication server, and a null terminator.
port	int for the port number of the authentication service.
callback	GDKerberosAuthCallback& if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure.