Manage the BlackBerry Dynamics cache of Kerberos credentials (C++). More...
#include <GDKerberosAuthHandler.h>
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.
Constructor.
| 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.
true if Kerberos delegation is allowed within BlackBerry Dynamics secure communication. false otherwise | 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.
If Kerberos delegation isn't allowed, the BlackBerry Dynamics runtime behaves as follows.
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.
| allow | bool for the setting: true to allow delegation, false to disallow. |
| 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.
| 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.
| 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. |
KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure. | Krb5ErrorCode setUpKerberosTicket | ( | const char * | username, |
| const char * | password | ||
| ) |
Calling this function is equivalent to calling the following.
setUpKerberosTicket(username, password, getAllowDelegation())
| 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. |
KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure. | 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.
| allowDelegation | bool for whether to request a ticket that can be delegated. |
KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure. | 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.
| 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. |
KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure. | Krb5ErrorCode setUpKerberosTicket | ( | const char * | host, |
| int | port | ||
| ) |
Calling this function is equivalent to calling the following.
setUpKerberosTicket(host, port, getAllowDelegation())
| 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. |
KDC_ERR_NONE if ticket creation succeeded, or a different Krb5ErrorCode value representing the reason for failure. | 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).
true if implicit credentials are allowed. false otherwise.