MAM SDK

API for iOS

March 4, 2024

Contributed by:

The XenMobile API for iOS is based on Objective-C. This article summarizes the Citrix Endpoint Management APIs by feature and provides the API definitions.

App management

isAppManaged

Interaction with Secure Hub

isMDXAccessManagerInstalled
logonMdxWithFlag
isAppLaunchedByWorxHome

MDX policies

getValueOfPolicy

Shared vault

getVaultDataFromVault
saveVaultData
updateAndSynchronizeVaultItem
updateAndSynchronizeVaultItems
deleteVault
deleteVaultWithError

User data

managedUserInformation

Class MdxManager

Methods

getValueOfPolicy

+(NSString*) getValueOfPolicy:(NSString*)policyName error:(NSError **) error;

For managed apps, returns the policy value set by Citrix Endpoint Management administrators. For unmanaged Premium apps, returns the policy value set in Applications/Citrix/MDXToolkit/data/MDXSDK/default_policies.xml. For unmanaged General apps, returns nil.

Parameters:

policyName – The name of the policy to search for in default_policies.xml.

Example:

+(NSString*) getValueOfPolicy:(NSString*)DisableCamera error:(NSError **) error;
isMDXAccessManagerInstalled

+(BOOL) isMDXAccessManagerInstalled: (NSError **) error;

Checks if Secure Hub is installed, which means that MDX control of the app is enabled even if the app isn’t managed. Returns true if Secure Hub is installed.
isAppManaged

+(BOOL) isAppManaged;

Checks if the app is currently managed by MDX, which means that the MDX policy bundle is embedded in the app as an XML file. The Citrix Endpoint Management backend infrastructure (key vaults) are queried for data encryption partial keys (secrets), which MDX will use to encrypt app database data (iOS 9 and later). Returns true if the app is managed.
logonMdxWithFlag

+(BOOL) logonMdxWithFlag:(BOOL)force error:(NSError**) error;

Initiates an MDX Logon request with Secure Hub.
isAppLaunchedByWorxHome

+(BOOL) isAppLaunchedByWorxHome;

Checks whether an inter-application URL request is from Secure Hub or some other app on the device, which is necessary if an app needs to be aware of MDX control communication. On iOS, apps can register for specific URL schemes. A URL scheme is the first part of a URL, up to but not including the colon. If a URL starts with http://, the scheme is http.

MDX-enabled apps and Secure Hub communicate using custom URL schemes. For example, to handle mailto: URLs from other apps, Secure Mail requires the URL scheme ctxmail. To handle http or https URLs from other apps, Secure Web requires the URL scheme ctxmobilebrowser or ctxmobilebrowsers, respectively. For details about the MDX App URL schemes policy and Allowed URLs policy, see MDX policies for iOS apps.

Returns accurate results when queried anytime or anywhere during or after the following UIApplication delegate event calls:
- When the app loads from springboard or an openURL call:
```
 application:willFinishLaunchingWithOptions:

 application:didFinishLaunchingWithOptions:

 applicationDidFinishLaunching:
```
- When the app is activated or re-activated by users from the device springboard
```
 applicationDidBecomeActive:
```
Important:

You must not query during applicationWillEnterForeground:.
- When the app is activated or re-activated by an openURL call:
```
 application:openURL:sourceApplication:annotation:

 application:handleOpenURL:
```
managedUserInformation

extern __attribute__((visibility ("default"))) NSString *const kXenMobileUsername; +(NSDictionary*) managedUserInformation;

Returns a string containing the UserName of an enrolled user running an MDX-managed app, regardless of the user sign-on status. Returns an empty string if the user isn’t enrolled, the app isn’t managed, or the app isn’t wrapped.

Class XenMobileSharedKeychainVault

Methods

initWithVaultName

- (instancetype) initWithVaultName:(NSString*)vaultName accessGroup:(NSString*)accessGroup;

Initializes a Citrix Endpoint Management shared vault.

Use the shared vault API to share managed content between apps that have the same keychain access group. For example, you can share user certificates through an enrolled app so that apps can obtain a certificate from the secure vault instead of from Secure Hub.

Parameters:

vaultName – The name of the Citrix Endpoint Management shared vault.

accessGroup – The name of the keychain access group. This can be the default MDX access group, named TEAMID_A.appOriginalBundleID, or a keychain access group you will use to share data between apps.
Vault Data Type Properties
```
   @property(nonatomic,readonly) BOOL exists;

   @property(nonatomic,readonly) BOOL isAccessible;

   @property(nonatomic,strong) NSMutableDictionary\* vaultData
   
```
After you initialize a vault, these vault data type properties are returned:

exists – Indicates whether the vault with the specified vaultName was found.

isAccessible – Indicates whether the vault is in the specified accessGroup and can be accessed.

vaultData – Is the contents of the shared vault. When you first initialize the vault, vaultData is a nil dictionary.
getVaultDataFromVault

+ (NSDictionary*) getVaultDataFromVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;

Reads data from the Citrix Endpoint Management shared vault. This is one of three ways to read vault data, as follows:
- Directly use getVaultDataFromVault:accessGroup:error.
- Create the XenMobileSharedKeychainVault instance and then read the vaultData property.
- Create the XenMobileSharedKeychainVault instance and then reload vault data using -(BOOL) loadDataWithError:(NSError *__autoreleasing *)error; and reading the vaultData property.
For example code, see the Shared Vault Example in this article.

Parameters:

vaultName – The name of the Citrix Endpoint Management shared vault.

accessGroup – The name of the keychain access group. This can be the default MDX access group, named TEAMID_A.appOriginalBundleID, or a keychain access group you will use to share data between apps.
saveVaultData

+ (BOOL) saveVaultData:(NSDictionary*)vaultData toVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;

Saves data in the Citrix Endpoint Management shared vault. This is one of three ways to save vault data, as follows:
- Directly use saveVaultData:toVault:accessGroup:error:.
- Use updateAndSynchronizeVaultItem: or updateAndSynchronizeVaultItems (described next in this table).
- Use - (BOOL)synchronizeWithError:(NSError *__autoreleasing *)error; by creating the XenMobileSharedKeychainVault instance, loading the vault data, modifying the vault data, and then synchronizing the data.
For example code, see Shared Vault Example in this article.

Parameters:

vaultData – The data to save to the Citrix Endpoint Management shared vault. Data stored in the share vault is a dictionary of key/value pairs, such as @{@”username”:@”;andreo”}.

vaultName – The name of the Citrix Endpoint Management shared vault.

accessGroup – The name of the keychain access group. This can be the default MDX access group, named TEAMID_A.appOriginalBundleID, or a keychain access group you will use to share data between apps.
updateAndSynchronizeVaultItem

updateAndSynchronizeVaultItems

- (BOOL)updateAndSynchronizeVaultItem:(NSString*)vaultItem withValue:(id)itemValue error:(NSError *__autoreleasing *)error;

- (BOOL)updateAndSynchronizeVaultItems:(NSDictionary*)vaultItems error:(NSError *__autoreleasing *)error;

Updates data in the Citrix Endpoint Management shared vault. To use this method, create the XenMobileSharedKeychainVault instance and then synchronize it by adding or updating vault data items. For example, if the existing vault entry has {a:123, b:234, c:305} and we use this API with data to update {c:345, d:456}, this API will update the vault data to {a:123, b:234, c:345, d:456}. For example code, see Shared Vault Example in this article.

See saveVaultData, above, for two other ways to save vault data.

Parameters:

vaultItem – A single key/value pair, in the form @{@";username::@";andreo"}.

vaultItems – A list of key/value pairs.
deleteVault

+ (BOOL) deleteVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;

Deletes the specified shared vault.

Parameters:

vaultName – The name of the Citrix Endpoint Management shared vault.

accessGroup – The name of the keychain access group used by the vault you want to delete.
deleteVaultWithError

-(BOOL) deleteVaultWithError:(NSError *__autoreleasing *)error;

Deletes the shared vault returned by the XenMobileSharedKeychainVault instance. You must free the object after deleting it with deleteVaultWithError.

Shared Vault Example

#import "XenMobileSharedKeychainVault.h"

@interface ClassA ()
...
@property(nonatomic,strong) XenMobileSharedKeychainVault* XenMobileSharedKeychainVault;
...
@end

@implementation ClassA
...
@synthesize XenMobileSharedKeychainVault = _XenMobileSharedKeychainVault;


...
#ifdef USE_CLASS_INSTANCE_METHODS
-(XenMobileSharedKeychainVault*)XenMobileSharedKeychainVault
{
if(_XenMobileSharedKeychainVault==nil) {
_XenMobileSharedKeychainVault = [[XenMobileSharedKeychainVault alloc]
      initWithVaultName:<VAULT_NAME>
      accessGroup:kXenMobileKeychainAccessGroup];
}
return _XenMobileSharedKeychainVault;
}
#endif

-(void)read
{
NSError* error=nil;
#ifdef USE_CLASS_INSTANCE_METHODS
NSDictionary* vaultDictionary = nil;
if([self.XenMobileSharedKeychainVault loadDataWithError:&error]) {
vaultDictionary = [self.XenMobileSharedKeychainVault vaultData];
}
#else
NSDictionary* vaultDictionary = [XenMobileSharedKeychainVault
      getVaultDataFromVault:<VAULT_NAME>
      accessGroup:kXenMobileKeychainAccessGroup error:&error];
#endif

}

-(void)save
{
NSError* error=nil;
/// check error handling here...

NSDictionary* dictToSave = @{<VAULT_DATA_DICTIONARY_OBJECTS>};
#ifdef USE_CLASS_INSTANCE_METHODS
#ifdef USE_CLASS_INSTANCE_METHODS_TO_UPDATE
BOOL result = [self.XenMobileSharedKeychainVault
      updateAndSynchronizeVaultItems:dictToSave error:&error];
#else
self.XenMobileSharedKeychainVault.vaultData = [NSMutableDictionary
      dictionaryWithDictionary:dictToSave];
BOOL result = [self.XenMobileSharedKeychainVault synchronizeWithError:&error];
#endif
#else
BOOL result = [XenMobileSharedKeychainVault
      saveVaultData:dictToSave toVault:<VAULT_NAME>
      accessGroup:kXenMobileKeychainAccessGroup error:&error];
#endif

}

-(void)delete
{
NSError* error=nil;
#ifdef USE_CLASS_INSTANCE_METHODS
BOOL result = [self.XenMobileSharedKeychainVault deleteVaultWithError:&error];
#else
BOOL result = [XenMobileSharedKeychainVault deleteVault:<VAULT_NAME>
      accessGroup:kXenMobileKeychainAccessGroup error:&error];
#endif

}

...

@end
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

API for iOS

March 4, 2024

Contributed by:

March 4, 2024

Contributed by:

API for iOS

Class MdxManager

Methods

Class XenMobileSharedKeychainVault

Methods

Shared Vault Example

In this article