• BlackBerry Dynamics
  • Runtime library for Android applications
  • 7.1.0.192
GDHttpClient Class Reference

Secure communications subclass of Apache DefaultHttpClient. More...

Inherits GDDefaultHttpClient.

Description

This class is an extension of Apache HttpClient for utilizing BlackBerry Dynamics secure communication. See the package documentation for an introduction to the BlackBerry Dynamics secure communication feature.

This class is a subclass of the native com.good.gd.apache.http.impl.client.DefaultHttpClient class. It has the same programming interface, with the following exceptions.

  • Some SSL certificate validation checking can be disabled, see the HTTPS Security section, below.
  • The connection manager associated with an instance of this class should always be closed, by calling its shutdown() method, before the instance is released or goes out of scope. This ensures that SSL verification can be switched back on.
  • This class isn't thread-safe. Use of ThreadSafeClientConnManager isn't supported. This class only supports SingleClientConnManager.
  • Data communication doesn't go via the proxy specified in the mobile device's native settings, if any.
  • Kerberos authentication is supported, see under HTTP Authentication, below.

The implementation of this subclass is configured with settings and registered schemes that are suitable for BlackBerry Dynamics secure communications.

See also
DefaultHttpClient class reference for details of the programming interface.
HTTPClient tutorial on the apache.org website for an introduction to their HTTPClient classes.
GDSocket
GDNetUtility

HTTPS Security

BlackBerry Dynamics secure communication supports HTTPS, using a Secure Socket Layer connection or Transport Layer Security (SSL/TLS) to send an HTTP request and receive a response.

Using SSL/TLS requires that the remote end has a suitable certificate, and that the certificate is valid. A number of checks for validity are made, some of which can be switched off by the application.

A typical HTTPS request sequence would be as follows. The application makes a first attempt to send the HTTPS request. In the first attempt, all checking is switched on. If a security error is encountered, this request will fail. The application can then switch off some checking, and attempt to send a second request to the same address as the first request. With less rigorous checking, the second attempt may succeed where the first failed.

The relevant parts of the programming interface are:

  • Use of HTTPS is specified by addressing the request to a URL with "https" as its scheme, as in "https://www.example.com".
  • The methods disableHostVerification and disablePeerVerification can be used to reduce the level of security checking. Setting disablePeerVerification implicitly sets disableHostVerification.

Secure Protocol Selection

Establishing an SSL/TLS connection can involve negotiating and retrying, in order to select a secure protocol that is supported by both client and server. The BlackBerry Dynamics runtime handles client-side negotiation and retrying, if secure communication is in use.

The following protocol versions can be blocked by enterprise management console configuration.

  • SSLv3
  • TLSv1.0
  • TLSv1.1
  • TLSv1.2

The configuration of blocked protocol versions can be done in the enterprise management console user interface. The configuration applies at the deployment level and isn't specific to user, policy group, or application server. The block only affects communication with application servers that is routed via the BlackBerry Dynamics proxy infrastructure.

HTTP proxy support

HTTP and HTTPS requests can be relayed by an HTTP proxy that resides on the Internet or behind the enterprise firewall. Authentication with the proxy is supported.

BlackBerry Dynamics HTTP data communication doesn't go via the proxy specified in the device's native settings, if any.

HTTP authentication

The BlackBerry Dynamics runtime supports the following mechanisms for authentication with HTTP servers: Basic Access, Digest Access, NTLM, and Kerberos. Except for Kerberos, all these mechanisms are also supported for authentication with HTTP proxies.

For NTLM authentication, use an NTCredentials object in the usual way. See the NTCredentials class reference on the android.com site for details. The following forms of the NTLM authentication protocol are supported.

  • NTLMv1.
  • NTLMv2.
  • NTLM2 Session.

When an HTTP server offers a choice of authentication methods, selection is made according to the AUTH_SCHEME_PREF attribute of the HTTP client context, as usual.

Kerberos Authentication

The BlackBerry Dynamics runtime supports Kerberos version 5 authentication. If using Kerberos authentication:

  • Supply username and password credentials in a Kerberos5Credentials object.
  • The username must be in the user@realm long form. The short form shortrealm\user isn't supported.
  • The BlackBerry Dynamics runtime will use these credentials to request Kerberos tickets. The tickets are persisted on the device in the BlackBerry Dynamics secure store. (The ticket store isn't generally accessible to the application, but see clearCredentialsForScheme.)
  • The stored Kerberos tickets are then used to authenticate the user on any site that supports Kerberos authentication. So long as the ticket continues to be accepted, there is no need for credentials to be supplied again, and no authentication challenge.
  • This continues until a site doesn't accept the stored ticket (e.g. the ticket has expired and cannot be renewed).
  • The Kerberos realm must be accessible. One way is to configure the Kerberos realm as an Additional Server in the enterprise management console.
  • Kerberos realms are treated differently to server addresses. An unqualified server address may be resolved according to configuration in the enterprise management console, but the short form of a Kerberos realm cannot be resolved in this way. Note that the short form of the Kerberos realm will typically be the form used when logging in to the enterprise LAN at the desktop. The long form is typically the short form with the domain appended.
  • Kerberos delegation can be allowed or disallowed. See com.good.gd.net.GDHttpClient.kerberosAllowDelegation.

The following limitations apply to Kerberos authentication in BlackBerry Dynamics:

  • There can only be one active user per Kerberos realm. If two authentications take place, with different Kerberos users, the second will invalidate the first. Subsequent attempts to access a network resource granted to the first Kerberos authentication won't be issued a service ticket and will fail. This applies even if the connections are made through separate GDHttpClient instances.
  • The Kerberos5Credentials object, see above, must be in place before an execute method is called. The username and password in the credentials object can be blank. The BlackBerry Dynamics runtime can still use cached Kerberos tickets if the password is blank. (Note that the Kerberos5Credentials object includes a hostname. This is because the BlackBerry Dynamics runtime cannot access the hostname in the associated HttpClient object when negotiating authentication.)
  • The Kerberos realm must also be set in an AuthScope object in which the host address and port are also set.
  • Multiple GDHttpClient instances can share Kerberos tickets. All instances that are to share must supply the same Kerberos user name and realm values in their associated Kerberos5Credentials objects.

Kerberos credentials for an HTTP request can be set before executing the request. If this approach is taken, then the runtime will attempt to handle any HTTP 401 Unauthorized responses from the server automatically, without reference to the application. It is possible that automatic handling fails, for example if the supplied credentials are rejected by the server. If automatic handling fails, then the last HTTP 401 Unauthorized response will be passed to the application.

Code Snippets

The following code snippets illustrate some common tasks.

Connection closure

The following snippet shows construction of a new instance of this class, and the closure of the connection.

HttpClient httpclient = new GDHttpClient();
// ...
httpclient.getConnectionManager().shutdown();

After the closure of the connection, the instance could be released or go out of scope safely.

Connection via HTTP proxy

HttpClient client = new GDHttpClient();
client.getCredentialsProvider().setCredentials(
new AuthScope(PROXY_HOST, PROXY_PORT),
new NTCredentials(PROXY_USERNAME, PROXY_PASSWORD, PROXY_HOST, PROXY_DOMAIN));
HttpHost targetHost = new HttpHost(TARGET_URL, TARGET_PORT, "http");
HttpHost proxy = new HttpHost(PROXY_HOST, PROXY_PORT);
client.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY, proxy);
HttpGet httpget = new HttpGet("/");
HttpResponse response = client.execute(targetHost, httpget);

The above snippet shows initiation of an HTTP request through an HTTP proxy. The values all in capitals would be replaced.

Public Member Functions

final void disableHostVerification ()
 Security option: Switch off SSL/TLS host name verification. More...
 
final void disablePeerVerification ()
 Security option: Swich off SSL/TLS authenticity verification. More...
 
final void clearCredentialsForScheme (final int scheme)
 Clear cached authentication credentials. More...
 
final void kerberosAllowDelegation (boolean allow)
 Allow or disallow Kerberos delegation. More...
 

Member Function Documentation

◆ disableHostVerification()

final void disableHostVerification ( )

Call this method to switch off host name verification, when making an HTTPS request. Host name verification is an SSL/TLS security option.

Host Name Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. The certificate includes a number of host names. By default, when using HTTPS, one of the host names in the certificate must match with the host name in the URL being opened, or the connection fails.
If host name verification is switched off, the connection succeeds regardless of whether there is a matching host name in the certificate.
If switched on, the BlackBerry Dynamics runtime checks server identity in a way that conforms with the relevant RFC. See under section 3.1 Server Identity, in RFC 2818.

This class doesn't as such support switching on host name verification after it has been switched off. To make a request with host name verification switched on, after this method has been called, proceed as follows.

  1. Shut down the associated connection manager.
  2. Create a new instance of this class.
See also
HTTPS Security, above

This method should be called before executing a request.

Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.

Returns
void

◆ disablePeerVerification()

final void disablePeerVerification ( )

Call this method to switch off certificate authenticity verification, when making an HTTPS request. Authenticity verification is an SSL/TLS security option.

Certificate Authenticity Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. By default, when using HTTPS, the certificate must be verified as trustworthy, or the connection fails. In this context, trustworthiness derives from a chain of digital signatures, rooted in a certification authority.
If authenticity verification is switched off, the connection succeeds regardless of the certificate's trustworthiness.
If authenticity verification is switched on, the BlackBerry Dynamics runtime checks certificate trustworthiness using operating system services. See the javax.net.ssl and android.net package documentation on the android.com developer website.

This class doesn't as such support switching on authenticity verification after it has been switched off. To make a request with authenticity verification switched on, after this method has been called, proceed as follows.

  1. Shut down the associated connection manager.
  2. Create a new instance of this class.
See also
HTTPS Security, above

This method should be called before executing a request.

Switching off authenticity verification implicitly also switches off host name verification.

Returns
void

◆ clearCredentialsForScheme()

final void clearCredentialsForScheme ( final int  scheme)

Call this function to clear the cached credentials for a particular authentication method, or to clear for all methods. Calling this function clears the session cache, and the permanent cache if present. (Currently, the BlackBerry Dynamics runtime only has a permanent cache for Kerberos authentication tickets.)

Parameters
schemeOne of the following constants, specifying which cache or caches are to be cleared:
HTTP_AUTH_METHOD_BASIC clears Basic Authentication credentials,
HTTP_AUTH_METHOD_DIGEST clears Digest Authentication credentials,
HTTP_AUTH_METHOD_NTLM clears NTLM Authentication credentials,
HTTP_AUTH_METHOD_NEGOTIATE clears Kerberos Authentication credentials and tickets,
HTTP_AUTH_ALL_METHODS clears all of the above.

◆ kerberosAllowDelegation()

final void kerberosAllowDelegation ( boolean  allow)

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.

  • Kerberos requests will be for tickets that can be delegated.
  • Application servers that are trusted for delegation can be sent tickets that can be delegated, if such tickets were issued.

If Kerberos delegation isn't allowed, the BlackBerry Dynamics runtime behaves as follows.

  • Kerberos requests won't be for tickets that can be delegated.
  • Application servers won't be sent tickets that can be delegated, even if such tickets were issued.

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 method is called, the Kerberos ticket and credentials caches will be cleared. I.e. there is an effective call to the clearCredentialsForScheme method with an HTTP_AUTH_METHOD_NEGOTIATE parameter.

Parameters
allowboolean for the setting: true to allow delegation, false to disallow.