DynamicsWatch Class Reference

BlackBerry Dynamics WatchOS interface to support secure messaging between WatchOS and iOS applications. More...

#import <DynamicsWatch.h>

Description

This class enables secure communication from a Dynamics app running on WatchOS with a companion Dynamics app running on iOS.

Introduction

Use this class from a watchOS app to initiate secure authentication and communication with an iOS companion app. This interface is not required within the iOS app. Instead the companion app should be built with BlackBerry Dynamics and utilize Apple's WCSession API to perform messaging with the watch.

Prerequisites:

• The watchOS app and iOS companion app must be integrated with BlackBerry Dynamics v12.1 or later.
• The Apple watch must be paired with the same user's iPhone.
• Enterprise policy must permit the use of a wearable device.
• The watch must be unlocked and worn on the wrist.

Setting Up Secure Communications

Setup and pairing of the watch and companion app is done using secureCommunicationSession within the WatchOS app. When successful, the completion block authStatus will be YES and the WatchCommunicationState changed to WatchCommunicationReady. The other states and transitions are shown in the following diagram.

Diagram of watchCommunicationState for BlackBerry Dynamics WatchOS application

Behavior On Companion App

It is best practice to first negotiate a secure communication session from the WatchOS app. This is because secureCommunicationSession is not available on the iOS companion app. If a WCSession sendMessage or sendMessageData is sent from the companion app prior to negotiation of the secure communication session then this will trigger the negotiation of the keys and the user will be required to confirm the 6 digit code on both devices. In this case the initiating message will need to be resent. Other APIs which initiate communication from the companion app to the watch are not currently handled in the same way, for example, transferFile, transferUserInfo, transferCurrentComplicationUserInfo and updateApplicationContext. Therefore use of these APIs without a secureCommunicationSession may fail.

Monitoring Watch Communication State

The WatchCommunicationState can be monitored by subscribing to the Notification for the key WatchCommunicationStateKey

NotificationCenter.default.addObserver(self, selector: #selector(watchCommStateChanged(_: )), name: Notification.Name.WatchCommunicationStateWillUpdate, object: nil)

The notification can be processed per this example code:

 @objc func watchCommStateChanged(_ notification:Notification?) {
   guard let notif = notification else {
   //No notification
       return
   }
   if let watchCommState = WatchCommunicationState(rawValue: notif.userInfo?[WatchCommunicationStateKey] as! Int) {
      updateWatchCommString(state:watchCommState)
   }
}
 * 

Sending Messages

Once secure communication is setup, use Apple's WCSession object to handle sending and receive messages between the watchOS and iOS companion app. An example using the 'sendMessage' function and associated 'replyHandler' can be found in the Dynamics WatchMessenger sample app (see below).

Handling Messaging Errors

If an error is encountered when sending a message, the replies from the replyHandler in WCSessionDelegate session(_:didReceiveMessageData:) will be in the form of:

@{WatchMessageErrorKey:[NSError errorWithDomain:WatchMessageErrorDomain
                                           code:WatchMessageErrorNeedsCommunicationSecured 
                                       userInfo:@{WatchMessageErrorUserInfoKey:@"Waiting to establish trust."}]}

The error code in the NSError object indicates what the reason is for the error.

Possible errors are:

• WatchMessageErrorPolicyNotAllowed
• WatchMessageErrorRemoteLocked
• WatchMessageErrorIncompliant
• WatchMessageErrorNeedsCommunicationSecured
• WatchMessageErrorOther

Secure File System

The secure file system is part of the BlackBerry Dynamics Watch Secure Storage feature.

For applications, the BlackBerry Dynamics secure file system behaves like the default file system, with the following differences. All data within the secure file system is stored on the device in an encrypted form. Directory and file names are also encrypted. The secure file system cannot be accessed until the Watch Communication is secured, see

Setting Up Secure Communications

.

Use GDFileManager instead of NSFileManager in the Watch app to access the Secure File System.

For more info see GDFileManager

Sample Application

Get started using the WatchOS and iOS sample app called 'WatchMessenger' located on BlackBerry's GitHub.

See BlackBerry Dynamics iOS Samples.

Instance Methods
(void)	- secureCommunicationSession:
	Setup Secure Communication. More...
(WatchCommunicationState)	- watchCommunicationState
	Watch Communication States. More...
(void)	- resetTrustBetweenDevices
	Reset the connection between watch and companion app. More...

Class Methods
(instancetype)	+ sharedBBDWatchIOS
	Get a reference to the BBDWatchIOS interface object. More...

Protected Types
enum	WatchCommunicationState {   WatchCommunicationStateNotSet,   WatchCommunicationResetting,   WatchCommunicationReady,   WatchCommunicationNeedsConfirmOnBoth,   WatchCommunicationNeedsConfirmOnPhone,   WatchCommunicationNeedsConfirmOnWatch,   WatchCommunicationNeedsWristDetected,   WatchCommunicationNeedsFirstLaunch,   WatchCommunicationSecuringFailed,   WatchCommunicationNotAllowedByPolicy,   WatchCommunicationNotAllowedRemoteLocked,   WatchCommunicationNotAllowedIncompliant,   WatchCommunicationNotAllowedWiped }
	Constants for WatchCommunicationState type. More...
typedef void(^	authCompletionBlock) (BOOL)
	Conditional block indicating if authentication between the watch and companion app is successful. More...

Member Typedef Documentation

authCompletionBlock

- (typedef void(^ authCompletionBlock(BOOL))

protected

Returns

boolean indicating if the communication has been secured.

YES indicates communication is secured between the watch and companion app. When the result is YES watchCommunicationState will also be set to WatchCommunicationReady.

Member Enumeration Documentation

WatchCommunicationState

- (enum) WatchCommunicationState

protected

This enumeration represents the state of the communication channel between watch and companion app.

Enumerator
WatchCommunicationStateNotSet	The secure communication between watch and iOS application has not been started. This is the initial state. 0
WatchCommunicationResetting	The secure communication between watch and iOS companion application is being reset. This state is triggered by calling resetTrustBetweenDevices or if an encrypted message is received that cannot be decrypted with the currently provisioned encryption keys. 1
WatchCommunicationReady	The secure communication between watch and iOS companion application is authenticated and ready for use. 2
WatchCommunicationNeedsConfirmOnBoth	Validation codes have been sent to both the phone and the watch which the user needs to confirm. 3
WatchCommunicationNeedsConfirmOnPhone	A validation code has been sent to the phone which the user needs to confirm. 4
WatchCommunicationNeedsConfirmOnWatch	A validation code has been received on the watch which the user needs to confirm. 5
WatchCommunicationNeedsWristDetected	The watch must be worn by the user and secured with a passcode to enable communication. 6
WatchCommunicationNeedsFirstLaunch	The companion app must be launched on iPhone to establish a connection. 7
WatchCommunicationSecuringFailed	Securing of the communication channel was cancelled by the user or a validation code was rejected. 8
WatchCommunicationNotAllowedByPolicy	Communication failed because the enterprise policy does not permit use of a wearable device. 9
WatchCommunicationNotAllowedRemoteLocked	Communication failed because the companion app is remote locked. 10
WatchCommunicationNotAllowedIncompliant	Communication failed because the devices are incompliant with Device policies. 11
WatchCommunicationNotAllowedWiped	Communication blocked because the iPhone app has been wiped. 12

Method Documentation

sharedBBDWatchIOS

+ (instancetype) sharedBBDWatchIOS

Communication must be started by initializing sharedBBDWatchIOS prior to sending or receiving secure messages. If the watch receives a secured message prior to this initialization it will not be decrypted.

This function returns a reference to the Dynamics Watch object. It can be called in the session(_:activationDidCompleteWith:error:) handler of the watch application.

Returns

Reference that can be used to call, for example secureCommunicationSession.

secureCommunicationSession:

- (void) secureCommunicationSession:

(authCompletionBlock)

authStatus

Communication must be secured by running this method prior to sending and receiving messages with the watch. Authentication status is available in the authStatus callback.

If a companion app is unavailable the watch displays an alert indicating that the companion app cannot be reached.

The enterprise policy assigned to the user must permit the use of a wearable device. If it is disabled the watch displays an alert indicating that the policy is disabled and the organization administrator should be contacted.

watchCommunicationState

- (WatchCommunicationState) watchCommunicationState

See enumeration WatchCommunicationState

resetTrustBetweenDevices

- (void) resetTrustBetweenDevices

Invoke this API to reset trust between watch and companion app. This action will wipe all contents from the Dynamics watch app and initiate the setup of a new trust negotiation.

---

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

• DynamicsWatch.h