GSS programming interface, including SPNEGO (C++). More...
#include <GDNegotiateScheme.h>
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 or NSURLSession 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 GDURLLoadingSystem handle GSS and SPNEGO automatically, without the need for detailed implementation in the application code.
| NegotiateScheme | ( | ) |
Constructor.
| ~NegotiateScheme | ( | ) |
| 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.| token | char* pointer to memory containing the Base64-encoded initial token from the server challenge, and a null terminator. |
| hostname | char* pointer to memory containing the authentication host specifier, and a null terminator. |
| allow_delegation | 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. |
char* pointer to memory containing a Base64-encoded token for a GSS token, and a null terminator.| 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.
| token | char* pointer to memory containing the Base64-encoded initial token from the server challenge, and a null terminator. |
| mechanism | NegotiateMechanism value for the negotiation mechanism. |
| service_principal_name | char* pointer to memory containing the service principal name, and a null terminator. |
| allow_delegation | 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. |
char* pointer to memory containing a Base64-encoded GSS token for the specified negotiation scheme and mechanism, and a null terminator.| 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.
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.
true if GSS context establishment has been initiated. false otherwise.