blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal

NegotiateScheme Class Reference

GSS programming interface, including SPNEGO (C++). More...

#include <GDNegotiateScheme.h>

List of all members.

Public Member Functions


Detailed 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 GDURLLoadingSystem, NSURLSession, or GDHttpRequest programming interfaces, 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 GDURLLoadingSystem and GDHttpRequest, 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.

Constructor & Destructor Documentation

Constructor.


Member Function Documentation

char* generateGssApiData ( const char *  token,
const char *  hostname,
const bool  allow_delegation 
)

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 class, and then call this function again.

This function doesn't return a success or failure code. To discover whether token generation succeeded or failed, call the getGssApiStatus() function 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:
tokenchar* pointer to memory containing the Base64-encoded initial token from the server challenge, and a null terminator.
hostnamechar* pointer to memory containing the authentication host specifier, and a null terminator.
allow_delegationbool 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:
char* pointer to memory containing a Base64-encoded token for a GSS token, and a null terminator.
The returned value, if non-null, will be a pointer to memory that has been allocated from the heap. The caller of this function must release the memory.
char* generateGssApiData ( const char *  token,
NegotiateMechanism  mechanism,
const char *  service_principal_name,
const bool  allow_delegation 
)

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 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 class, and then call this function again.

This function doesn't return a success or failure code. To discover whether token generation succeeded or failed, call the getGssApiStatus() function 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:
tokenchar* pointer to memory containing the Base64-encoded initial token from the server challenge, and a null terminator.
mechanismNegotiateMechanism value for the negotiation mechanism.
service_principal_namechar* pointer to memory containing the service principal name, and a null terminator.
allow_delegationbool 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:
char* pointer to memory containing a Base64-encoded GSS token for the specified negotiation scheme and mechanism, and a null terminator.
The returned value, if non-null, will be a pointer to memory that has been allocated from the heap. The caller of this function must release the memory.
GssStatusCode getGssApiStatus ( ) const

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.
bool gssContextEstablishmentInitiated ( ) const

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.

The documentation for this class was generated from the following file: