Secure communications subclass of Apache DefaultHttpClient. More...
Inherits GDDefaultHttpClient.
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.
com.good.gd.apache.http.impl.client.DefaultHttpClient
class. It has the same programming interface, with the following exceptions.shutdown()
method, before the instance is released or goes out of scope. This ensures that SSL verification can be switched back on.ThreadSafeClientConnManager
isn't supported. This class only supports SingleClientConnManager
.The implementation of this subclass is configured with settings and registered schemes that are suitable for BlackBerry Dynamics secure communications.
When using GDHttpClient to support a WebView, it is important to handle WebView's threading model correctly in order to achieve good performance.
A WebView instance allocates a pool of threads and, when a web page is being loaded, uses this thread pool to make multiple concurrent calls to the WebViewClient shouldInterceptRequest method in order to fetch each resource required by the web page. If each such call creates a new GDHttpClient object, it will result in a new connection being created for every call. This will not perform well, as the latency involved in connection establishment is usually prohibitive. The ideal implementation will preserve the GDHttpClient object for each thread, so that connections can be re-used. This is easily achieved by storing the GDHttpClient object in a ThreadLocal reference, and fetching it at the start of each shouldInterceptRequest call.
More information is available in the Connection Persistence section of the apache.org website.
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:
disableHostVerification
and disablePeerVerification
can be used to reduce the level of security checking. Setting disablePeerVerification
implicitly sets disableHostVerification
.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.
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 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.
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 developer website for details. The following forms of the NTLM authentication protocol are supported.
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.
The BlackBerry Dynamics runtime supports Kerberos version 5 authentication. If using Kerberos authentication:
@
realm long form. The short form shortrealm\
user isn't supported.The following limitations apply to Kerberos authentication in BlackBerry Dynamics:
GDHttpClient
instances.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.)AuthScope
object in which the host address and port are also set.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.
The following code snippets illustrate some common tasks.
The following snippet shows construction of a new instance of this class, and the closure of the connection.
After the closure of the connection, the instance could be released or go out of scope safely.
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... | |
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.
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.
This method should be called before executing a request.
Switching off host name verification doesn't switch off authenticity verification, see 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.
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.
This method should be called before executing a request.
Switching off authenticity verification implicitly also switches off host name verification.
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.)
scheme | One 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. |
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.
If Kerberos delegation isn't allowed, the BlackBerry Dynamics runtime behaves as follows.
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.
allow | boolean for the setting: true to allow delegation, false to disallow. |