• BlackBerry Dynamics
  • Runtime library for Android applications
  • 12.0.1.79
GDNegotiateScheme Class Reference

GSS programming interface, including SPNEGO (Java). More...

Description

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.

See also
RFC 2743 - Generic Security Service Application Program Interface.
RFC 4178 - The Simple and Protected Generic Security Service Application Program Interface (GSS-API) Negotiation Mechanism.
RFC 4559 - SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows.
All on the ietf.org website.

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 & Destructor Documentation

◆ GDNegotiateScheme()

Constructor.

Member Function Documentation

◆ closeScheme()

void closeScheme ( )

Call this method to ensure release of local resources associated with the instance.

◆ getGssApiStatus()

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.

Returns
GssStatusCode value representing the status.

◆ gssContextEstablishmentInitiated()

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.

Returns
true if GSS context establishment has been initiated.
false otherwise.

◆ generateGssApiData() [1/2]

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.
Parameters
tokenString containing the Base64-encoded initial token from the server challenge, and a null terminator.
hostNameString containing the authentication host specifier, and a null terminator.
allowDelegationboolean 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.
Returns
String containing a Base64-encoded GSS token for SPNEGO.

◆ generateGssApiData() [2/2]

String generateGssApiData ( String  token,
NegotiateMechanism  mechanism,
String  servicePrincipalName,
boolean  allowDelegation 
)
Deprecated:
This function is deprecated and will be removed in a future release. It is no longer required.

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.

Parameters
tokenString containing the Base64-encoded initial token from the server challenge.
mechanismNegotiateMechanism value for the negotiation scheme and mechanism.
servicePrincipalNameString containing the service principal name.
allowDelegationbool 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.
Returns
String containing a Base64-encoded GSS token for the specified negotiation scheme and mechanism.