Secure services API details

The AppConnect for iOS API provides properties and methods that allow an app to:

•

determine whether secure services are available.

•

handle its secure file I/O policy.

•

perform file operations on secure, encrypted files.

•

determine whether secure copy to the pasteboard is available.

For an overview of this feature, see "Data Protection" in Securing and managing the app using the AppConnect library.

The ACSecureServicesAvailability enumeration

The ACSecureServicesAvailability enumeration provides the possible secure services availability statuses for the app:

typedef enum {
    ACSECURESERVICESAVAILABILITY_UNAVAILABLE = 0, // Secure services are 
                                                  // currently unavailable.
    ACSECURESERVICESAVAILABILITY_AVAILABLE   = 1, // Secure services are currently available.
} ACSecureServicesAvailability;

For more information about these values, see The secureServicesAvailability and secureFileIOPolicy properties .

The ACSecureFileIOPolicy enumeration

The ACSecureFileIOPolicy enumeration provides the possible secure file I/O policy statuses for the app:

typedef enum {
    ACSECUREFILEIOPOLICY_OPTIONAL = 0,	// The application may store sensitive files using iOS
	                                // filessytem APIs or AppConnect secure file I/O.
    ACSECUREFILEIOPOLICY_REQUIRED = 1,	// The application must store sensitive files 
	                                // using only AppConnect secure file I/O. 
} ACSecureFileIOPolicy;

NOTE:

This policy is not configurable by the MobileIron server administrator; The server always requires secure file I/O. For more information about these values, see The secureServicesAvailability and secureFileIOPolicy properties .

The secureServicesAvailability and secureFileIOPolicy properties

The following read-only properties on the AppConnect singleton relate to secure services:

Table 1. Secure services properties on the AppConnect singleton

Property	Description
secureServicesAvailability	An ACSecureServicesAvailability value that indicates whether secure services are currently available. Secure services availability depends on the availability of the encryption key. The encryption key is available only when all of the following are true: • the device user has entered the AppConnect passcode, or the device passcode when no AppConnect passcode is required • the app is authorized • the AppConnect singleton is ready (the ready property is YES)
secureFileIOPolicy	An ACSecureFileIOPolicy that contains the current status of the secure file I/O policy for the app. This secure file I/O policy is not configurable by the MobileIron server administrator; The server always requires secure file I/O.

When your app launches:

•

Get the singleton AppConnect object and call its -startWithLaunchOptions: method.

•

Wait for the -appConnectIsReady: callback method before accessing the secureFileIOPolicy property.

After the -appConnectIsReady: callback method is called:

•

if the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_AVAILABLE, use secure file I/O APIs.

•

If the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_UNAVAILABLE, wait for the notification of it changing to ACSECURESERVICESAVAILABILITY_AVAILABLE before using secure file I/O. Secure file I/O APIs fail when secure services are not available. The notification method is -appConnect:secureServicesAvailabilityChangedTo:.

•

disable or enable special user interfaces for copying to the pasteboard if the pasteboard policy is ACPASTEBOARDPOLICY_SECURECOPY. Copying to the pasteboard fails if secure services are unavailable and the pasteboard policy is ACPASTEBOARDPOLICY_SECURECOPY.

NOTE:

Because the secure file I/O policy is always set to required on the MobileIron server, the value of the secureFileIOPolicy property is always ACSECUREFILEIOPOLICY_REQUIRED. When secure file I/O is required, your app should use secure file I/O APIs (but only while secure services are available).

If the app becomes unauthorized, secure services change to unavailable. Similarly, if the AppConnect passcode auto-lock timeout expires, secure services also change to unavailable. When these situations occur, the AppConnect library calls the -appConnect:secureServicesAvailabilityChangedTo: notification method.

NOTE:

Consider the case when the AppConnect passcode auto-lock timeout expires while your app is performing a file operation. The operations will fail. Make sure your app can handle the returned error conditions.

Secure services methods

Your app uses the following methods to receive secure services availability updates and to report how the app handled the updates.

•

The -appConnect:secureServicesAvailabilityChangedTo: callback method

•

The -appConnect:secureFileIOPolicyChangedTo: callback method

•

The -secureFileIOPolicyApplied:message: acknowledgment method

The -appConnect:secureServicesAvailabilityChangedTo: callback method

You optionally implement this method, which is in the AppConnectDelegate protocol:

-(void) appConnect:(AppConnect *)appConnect secureServicesAvailabilityChangedTo:
           (ACSecureServicesAvailability)secureServicesAvailability;

Implement this method only if your app uses secure services.

When secure services availability changes, the AppConnect library:

1.

Updates the secureServicesAvailability property on the AppConnect object.

2.

Calls the -appConnect:secureServicesAvailabilityChangedTo: method, which provides the new value in its parameter.

Your app then changes its use of secure services and takes appropriate logic paths depending on the passed ACSecureServicesAvailability value. For example, if secure services become unavailable, an app should:

•

stop doing any secure file I/O. The app might also notify the user of limited functionality. Limited functionality is necessary because files created using secure file I/O cannot be read or updated with regular file I/O.

•

disable or enable special user interfaces for copying to the pasteboard if the pasteboard policy is ACPASTEBOARDPOLICY_SECURECOPY. Copying to the pasteboard fails if secure services are unavailable and the pasteboard policy is ACPASTEBOARDPOLICY_SECURECOPY.

The -appConnect:secureFileIOPolicyChangedTo: callback method

You optionally implement this method, which is in the AppConnectDelegate protocol:

-(void) appConnect:(AppConnect *)appConnect secureFileIOPolicyChangedTo:
           (ACSecureFileIOPolicy)newSecureFileIOPolicy;

Implement this method only if your app uses secure file I/O AppConnect APIs.

When the secure file I/O policy changes, the AppConnect library:

1.

Updates the secureFileIOPolicy property on the AppConnect object.

2.

Calls the -appConnect:secureFileIOPolicyChangedTo: method, which provides the new value in its parameter.

Your app then changes its use of secure file I/O and takes appropriate logic paths depending on the passed ACSecureFileIOPolicy value.

The -secureFileIOPolicyApplied:message: acknowledgment method

After your app processes the information provided in the callback method, it must call this acknowledgment method on the AppConnect singleton:

-(void)secureFileIOPolicyApplied:(ACPolicyState)policyState message:(NSString *)message;

Your app passes the following parameters to this method:

•

the ACPolicyState value that represents the success or failure of handling the secure file I/O policy update.

Pass the value ACPOLICY_APPLIED if the app successfully handled the update. Otherwise, pass the value ACPOLICY_ERROR. Pass the value ACPOLICY_UNSUPPORTED if your app does not support secure file I/O. If you do not implement the -secureFileIOPolicyApplied:message method, the AppConnect singleton behaves as if you passed it ACPOLICY_UNSUPPORTED.

•

an NSString explaining the ACPolicyState value.

Typically, you use this string to report the reason the app failed to apply the secure file I/O policy update. The string is reported in the MobileIron server log files.