• BlackBerry Dynamics
  • Runtime library for iOS applications
  • 7.1.0.193
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...
 
 ~GDKerberosAuthHandler ()
 
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...
 

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()

Constructor.

◆ ~GDKerberosAuthHandler()

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
allowbool 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
usernamechar* pointer to memory containing the user principal name, and a null terminator.
passwordchar* pointer to memory containing the Kerberos authentication password for the user principal, and a null terminator.
allowDelegationbool 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.

Parameters
usernamechar* pointer to memory containing the user principal name, and a null terminator.
passwordchar* 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
allowDelegationbool 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
hostchar* pointer to memory containing the FQDN of the authentication server, and a null terminator.
portint for the port number of the authentication service.
allowDelegationbool 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.

Parameters
hostchar* pointer to memory containing the FQDN of the authentication server, and a null terminator.
portint 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.

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

Returns
true if implicit credentials are allowed.
false otherwise.

The documentation for this class was generated from the following file:
GD::KRB_API::GDKerberosAuthHandler::setUpKerberosTicket
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.
GD::KRB_API::GDKerberosAuthHandler::getAllowDelegation
static bool getAllowDelegation()
Check whether Kerberos authentication delegation is allowed or disallowed.