GSS programming interface, including SPNEGO (Java). More...
This class contains an interface for generating Generic Security Service Application Program Interface (GSS-API) tokens. The tokens are suitable for use in HTTP authentication headers as used in the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), for example. Use of SPNEGO in BlackBerry Dynamics is dependent on use of Kerberos authentication.
The BlackBerry Dynamics runtime stores, in a secure cache, Kerberos tickets obtained in the course of BlackBerry Dynamics secure communication with application servers. These cached tickets can be used to generate GSS tokens. Kerberos tickets could be cached as a side effect of using the GDHttpClient programming interface, for example. In addition, there is a programming interface for working with Kerberos tickets directly: GDKerberosAuthHandler.
This class provides a low-level interface for GSS token generation. It can be used in applications that programmatically form their own HTTP headers for authentication, for example, or that handle other protocol elements at a detailed level.
Use of this class is optional. Higher level parts of the BlackBerry Dynamics secure communication stack, for example GDHttpClient
, handle GSS and SPNEGO automatically, without the need for detailed implementation in the application code.
Classes | |
enum | GssStatusCode |
Generic Security Service Application Program Interface status code. More... | |
enum | NegotiateMechanism |
Generic Security Service Application Program Interface negotiation mechanisms. More... | |
Public Member Functions | |
GDNegotiateScheme () | |
Constructor. More... | |
void | closeScheme () |
Release resources. More... | |
GssStatusCode | getGssApiStatus () |
Get the status of the last GSS-API operation. More... | |
boolean | gssContextEstablishmentInitiated () |
Check whether GSS security context establishment has been initiated. More... | |
String | generateGssApiData (String token, String hostName, boolean allowDelegation) |
Generate an authentication token for a GSS-API header for SPNEGO. More... | |
String | generateGssApiData (String token, NegotiateMechanism mechanism, String servicePrincipalName, boolean allowDelegation) |
Generate an authentication token for a GSS-API header for a specified negotiation scheme and mechanism. More... | |
Constructor.
void closeScheme | ( | ) |
Call this method to ensure release of local resources associated with the instance.
GssStatusCode getGssApiStatus | ( | ) |
Call this function to get the status of the last GSS-API operation, specifically to determine the success or failure of the last call to a generateGssApiData
function.
The STATUS_UNKNOWN
value is returned if there is no current context, for example if token generation hasn't been attempted yet.
GssStatusCode
value representing the status. boolean gssContextEstablishmentInitiated | ( | ) |
Call this function to check whether establishment of a GSS security context has been initiated.
This function doesn't necessarily return false
if security context establishment has completed.
true
if GSS context establishment has been initiated. false
otherwise. String generateGssApiData | ( | String | token, |
String | hostName, | ||
boolean | allowDelegation | ||
) |
Call this function to generate a Generic Security Service (GSS) authentication token that is suitable for use in a GSS-API header for SPNEGO. Pass in the token from a server challenge as a parameter.
Token generation depends on there being a suitable Kerberos ticket in the BlackBerry Dynamics secure cache. If there is a suitable cached Kerberos ticket when this function is called, then it is used to generate the token. Otherwise, token generation fails. After failure, the application could take an action that would cause a Kerberos ticket to be cached, for example calling one of the setUpKerberosTicket functions in the GDKerberosAuthHandler C++ class, and then call this function again.
This method doesn't return a success or failure code. To discover whether token generation succeeded or failed, call the getGssApiStatus method every time.
It might be necessary to call this function more than once, and to pass different server challenge token values. This could happen if the server requires more than one challenge-response exchange, for example. When getGssApiStatus
returns STATUS_GSS_S_COMPLETE
then negotiation is complete.
Pass as a parameter a specifier for the authentication host to be used for the negotiation. Format the value as follows:
server.address.com
:portNumber
Where:
server.address.com
is a fully qualified domain name (FQDN).portNumber
can be omitted if it is 80. If the port number is omitted, also omit the colon (:) separator.token | String containing the Base64-encoded initial token from the server challenge, and a null terminator. |
hostName | String containing the authentication host specifier, and a null terminator. |
allowDelegation | boolean flag for whether to allow Kerberos delegation to be used to obtain the token. Note that delegation might not be allowed by the authentication service, which would take precedence over this parameter value. |
String
containing a Base64-encoded GSS token for SPNEGO. String generateGssApiData | ( | String | token, |
NegotiateMechanism | mechanism, | ||
String | servicePrincipalName, | ||
boolean | allowDelegation | ||
) |
Call this function to generate a Generic Security Service (GSS) authentication token that is suitable for use in a GSS-API header for a specified negotiation scheme and mechanism. Pass in the token from a server challenge as a parameter.
Token generation depends on there being a suitable Kerberos ticket in the BlackBerry Dynamics secure cache. If there is a suitable cached Kerberos ticket when this function is called, then it is used to generate the token. Otherwise, token generation fails. After failure, the application could take an action that would cause a Kerberos ticket to be cached, for example calling one of the setUpKerberosTicket functions in the GDKerberosAuthHandler C++ class, and then call this function again.
This method doesn't return a success or failure code. To discover whether token generation succeeded or failed, call the getGssApiStatus method every time.
It might be necessary to call this function more than once, and to pass different server challenge token values. This could happen if the server requires more than one challenge-response exchange, for example. When getGssApiStatus
returns STATUS_GSS_S_COMPLETE
then negotiation is complete.
Pass as a parameter the service principal name for the negotiation.
token | String containing the Base64-encoded initial token from the server challenge. |
mechanism | NegotiateMechanism value for the negotiation scheme and mechanism. |
servicePrincipalName | String containing the service principal name. |
allowDelegation | bool flag for whether to allow Kerberos delegation to be used to obtain the token. Note that delegation might not be allowed by the authentication service, which would take precedence over this parameter value. |
String
containing a Base64-encoded GSS token for the specified negotiation scheme and mechanism.