BlackBerry Dynamics applications can utilize the native URL session programming interface, NSURLSession, to communicate with servers that are behind the enterprise firewall. Communication across the enterprise firewall utilizes the BlackBerry Dynamics proxy infrastructure, which is secure.

Support for the native programming interface is provided by the BlackBerry Dynamics runtime, which has its own URL session implementation based on custom protocols. The BlackBerry Dynamics session implementation will be utilized by default in the application, after BlackBerry Dynamics authorization processing has completed.

The BlackBerry Dynamics URL session implementation doesn't support background tasks.

See also: NSURLSession Class Reference on the apple.com developer website.; GDiOS, for BlackBerry Dynamics authorization.; Background Execution page in the appendix.; GDURLLoadingSystem; GDNetUtility

Usage

The BlackBerry Dynamics URL session can be utilized after authorization processing is complete. Use the native NSURLSession programming interface as usual, for example:

Create a task in the shared session, by referring to the NSURLSession sharedSession property.
Start a new session, by creating a new NSURLSession instance, and then create a task in the new session.

The task will be executed by the BlackBerry Dynamics URL session implementation, but see the limitations below.

The BlackBerry Dynamics secure store will be utilized, as follows:

Browser cookies are persisted in the secure store. See HTTP Cookie Handling below.
The default store isn't used to cache retrieved files. Instead, a separate secure cache is used, see under Secure Cache, below.
Kerberos tickets are persisted on the device in the secure store.

Use of the BlackBerry Dynamics URL session can be switched off and on by using:

Finish any current sessions before switching off use of the BlackBerry Dynamics URL session. Any current sessions other than the shared session will be invalidated when use is switched off.

Enterprise server connection notes

BlackBerry Dynamics secure communication can be used to connect to servers that are behind the enterprise firewall. This applies to socket connections and HTTP requests. Note the following when using this capability.

The addresses of any application servers to which connection is being made must be configured in the enterprise management console. The address could be registered as the application's server, or as an additional server, for example.

Note. The application server configuration set in the management console can be obtained in the application code by using the getApplicationConfig (GDiOS) function.

The connection to the application server will be made through the BlackBerry Dynamics proxy infrastructure. The status of the application's connection to the proxy infrastructure can be checked and monitored by using the GDReachability interface.

See also: System administration tasks; GDReachability class reference.

HTTPS Security

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

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.

Authentication Method Selection

The application code can use the native NSURLSession programming interface to force the connection not to use particular authentication types. There isn't any need to set the GDRejectAuthSupport build option that is documented in the GDURLLoadingSystem class reference.

HTTP Cookie Handling

By default, HTTP cookies received through BlackBerry Dynamics secure communication are handled automatically:

Set-cookie: headers that are received as part of an HTTP response are processed and then added to subsequent matching requests.
Persistent cookies are written to cookie storage in the BlackBerry Dynamics secure store.

The BlackBerry Dynamics cookie store persists between executions of the application, and if the mobile device is switched off. The contents of the store can be managed with the native NSHTTPCookieStorage programming interface, and so can non-persistent cookies received through BlackBerry Dynamics secure communication.

Automatic handling of HTTP cookies received through BlackBerry Dynamics secure communication can be switched off, as follows.

For communication that goes via the GDURLLoadingSystem, such as NSURLSession and NSURLConnection, call the setHTTPShouldHandleCookies: method of the associated NSMutableURLRequest instance.

See also: NSHttpCookieStorage class reference on the apple.com developer website.; NSMutableURLRequest class reference on the apple.com developer website. But see also the Configuration Support notes, below.

Kerberos Authentication

BlackBerry Dynamics secure communication supports Kerberos version 5 authentication. When using Kerberos authentication:

Credentials are initially taken in the same way as other credentials, with the same specified persistence.
The credentials will be a username in the form user@realm, and a password.
The credentials are used to request Kerberos tickets, which are stored.
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 does not accept the stored ticket (e.g. the ticket has expired and cannot be renewed).
The Kerberos realm must be accessible. Usually, this means that the Kerberos realm must be listed as an Additional Server in the management console.

Secure Cache

There is a single URL cache in the BlackBerry Dynamics secure store that is utilized by all BlackBerry Dynamics secure communication in the application. This cache, the secure URL cache, is the only cache that can be used by the BlackBerry Dynamics URL session.

The secure URL cache can be configured via the NSURLCache sharedURLCache object, when the BlackBerry Dynamics URL session is being utilized. The properties of the object can be set as follows.

Setting memoryCapacity isn't supported. A value of zero is assumed.
Setting other properties, such as diskCapacity, is supported.
The additional functions in the NSURLCache(GDURLCache) category can be used.

The secure cache can be switched off by doing any of the following.

Create a new NSURLSession instance that is based on an NSURLSessionConfiguration in which the URLCache property is nil. Tasks in the session won't utilize the cache.
Set the NSURLCache sharedURLCache object to nil.
Change NSURLCache sharedURLCache to a different object when the BlackBerry Dynamics URL session is being utilized.

See also: NSURLCache Class Reference on the apple.com developer website.

Secure Cache Code Snippets

The following snippet illustrates setting disk capacity in the secure cache.

[NSURLCache sharedURLCache].diskCapacity = 20 * 1024 * 1024; // 20 Megabytes

The following snippet illustrates switching off caching.

NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];

configuration.URLCache = nil;

The following snippet shows some code that would result in caching being switched off.

NSUInteger capacity = 10 * 1024 * 1024; // 10 Megabytes
NSURLCache *urlCache = [[NSURLCache alloc] initWithMemoryCapacity:capacity
                                                     diskCapacity:capacity
                                                         diskPath:nil];
[NSURLCache setSharedURLCache:URLCache];

Limitations

The following limitations apply to the BlackBerry Dynamics URL session implementation, compared to the native.

Upload and download tasks can't be configured to run in background. The following constructor functions always fail:
- NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier:
- NSURLSessionConfiguration backgroundSessionConfiguration:
When BlackBerry Dynamics authorization completes, the NSURLSession sharedSession property value is changed. The new value refers to a session that is executed by the BlackBerry Dynamics runtime in the application. Tasks subsequently created in the session referred to by sharedSession aren't handed off to the system shared session.
Custom protocol classes that are registered before BlackBerry Dynamics authorization processing has completed are subscribed to the system shared session and won't be protected by BlackBerry Dynamics secure communication. This would apply to NSURLProtocol implementations for which registerClass: is called, for example.
Task suspension isn't supported. Calling the NSURLSessionTask suspend function has no effect on a task in a BlackBerry Dynamics URL session. The task will continue, and delegate callback functions in the application code could be invoked.
Stream tasks aren't supported. A task created by a streamTask constructor won't connect via the BlackBerry Dynamics proxy infrastructure.
Most metrics aren't provided. The NSURLSessionTaskMetrics object associated with a BlackBerry Dynamics URL session may only include the URL, the request start and end times, and the response start time.
NSURLSessionTask earliestBeginDate isn't supported. The NSURLSessionTaskDelegate willBeginDelayedRequest method is never invoked.
BlackBerry Dynamics doesn't support canceling upload task with latest resuming process of uploading data. Upload task created by resumeData constructors (uploadTaskWithResumeData:, uploadTaskWithResumeData:completionHandler: ) won't connect via the BlackBerry Dynamics proxy infrastructure.
Not all configuration options are supported. See the notes under Configuration Support, below.

The limitations apply whenever the BlackBerry Dynamics URL session is used, whether or not the connection goes via the proxy infrastructure.

Configuration Support

The native NSURLSessionConfiguration class offers a number of configuration properties, but not all are supported by the BlackBerry Dynamics URL session. See the following notes.

Supported

HTTPAdditionalHeaders is supported.
timeoutIntervalForRequest is supported.
timeoutIntervalForResource is supported.
TLSMaximumSupportedProtocol is supported.
TLSMinimumSupportedProtocol is supported.
requestCachePolicy is supported.
protocolClasses is supported.
connectionProxyDictionary is supported.
HTTPCookieStorage is supported.

Unsupported

networkServiceType: NSURLNetworkServiceTypeDefault is assumed.
allowsCellularAccess: YES is assumed.
sharedContainerIdentifier is ignored.
HTTPCookieAcceptPolicy is ignored.
HTTPShouldSetCookies is ignored.
URLCredentialStorage is ignored.
URLCache can be set to nil but isn't otherwise supported, also see under Secure Cache, above.
sessionSendsLaunchEvents is ignored. Background tasks aren't supported.
discretionary is ignored. Background tasks aren't supported.
HTTPMaximumConnectionsPerHost is ignored.
HTTPShouldUsePipelining isn't supported.
multipathServiceType: NSURLSessionMultipathServiceTypeNone is assumed.
waitsForConnectivity: NO is assumed. The NSURLSessionTaskDelegate taskIsWaitingForConnectivity method is never invoked.
requiresDNSSECValidation is ignored.
allowsExpensiveNetworkAccess is ignored.
allowsConstrainedNetworkAccess is ignored.
proxyConfigurations is ignored.