API for Android

The API for Android is based on Java. This article summarizes the Citrix Endpoint Management APIs by feature and provides the API definitions.

App management:

• isManaged
• isWrapped

MDX policies:

• getPoliciesXML
• getPolicyValue
• setPolicyChangeMessenger

Shared vault:

• MDXDictionary

User data:

• getUserName

Class com.citrix.worx.sdk.MDXApplication

Methods

• isManaged

  public static boolean isManaged (Context context)

  Checks if the app is currently managed by MDX, which means that the Citrix Secure Hub app is installed on the device and Citrix Endpoint Management policies are enforced on your app. The Endpoint Management backend infrastructure (key vaults) are queried for data encryption partial keys (secrets) which MDX will use to encrypt application file data. Returns true if the app is managed.

  Unmanaged Premium apps use the Endpoint Management policy defaults specified in Applications/Citrix/MDXToolkit/data/MDXSDK_Android/default_sdk_policies.xml. Policies are not enforced for unmanaged General apps.

  Parameters

  context – The Android context that is making this call.

  Example

  boolean bIsManaged = MDXApplication.isManaged(context);

• isWrapped

  public static boolean isWrapped (Context context)

  Returns true if the app is wrapped with the MDX Toolkit.

  Parameters

  context – The Android context that is making this call.

  Example

  boolean bIsWrapped = MDXApplication.isWrapped(context);

• getUserName

  public static String getUserName (Context context)

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

  Parameters

  context – The Android context that is making this call.

  Example

  String userName = MDXApplication.getUserName(context);

Class com.citrix.worx.sdk.MDXPolicies

Methods

• getPoliciesXML

  public static String getPoliciesXML (Context context)

  Returns the contents of default_sdk_policies.xml, as one line per policy, prefixed with (match) to indicate that the value in the XML file matches the value returned by MDXPolicies.getPolicyValue(). Returns an empty string on failure.

  Parameters

  context – The Android context that is making this call.

  Example

  String policiesXML = MDXPolicies.getPoliciesXML(context);

• getPolicyValue

  public static String getPolicyValue (Context context, String policyName)

  Returns a String which contains current value of the named policy. Returns null if no value is found.

  Parameters

  context – The Android context that is making this call.

  policyName – The name of the policy to search for. A policy name is the value of the PolicyName element in a policy XML file.

  Example

  String value = MDXPolicies.getPolicyValue(context"DisableCamera");

• setPolicyChangeMessenger

  public static String setPolicyChangeMessenger (Context context, String policyName. Messenger messenger)

  Registers a Messenger to receive a message when the given policy’s value changes. When MDX detects that a policy value changed in the Citrix Endpoint Management console, MDX notifies this messenger. You can then use the other APIs to re-read the policy values and change your app. Returns null.

  Parameters

  context – The Android context that is making this call.

  policyName – The policy name to monitor. A policy name is the value of the PolicyName element in a policy XML file.

  messenger – The messenger that will receive messages when the policy value changes.

  Example

  MDXPolicies.setPolicyChangeMessenger(context, "DisableCamera", messenger);

Class com.citrix.mdx.common.MDXDictionary

MDXDictionary is a container for reading and storing encrypted Android bundles of key-value pairs. Mobile productivity apps in the same MDX security group share a dictionary. Use the shared vault API to share managed content between apps that have the same MDX dictionary. For example, you can share certificates and private keys through an enrolled app so that apps can obtain a certificate from the secure vault instead of from Secure Hub.

Dictionaries are stored encrypted regardless of the Private file encryption policy and Public file encryption policy settings. Developers must unlock the vault before retrieving dictionaries.

Constructors

• public MDXDictionary( MDXDictionary source )

  Constructs a copy of an existing MDXDictionary.

  Parameters

  source – The MDXDictionary that should be copied.

• public MDXDictionary( String name, Bundle bundle, long sequence )

  Constructs an MDXDictionary from a name, bundle, and sequence number. If you do not know the sequence number, use the create() factory method.

  Parameters

  name – The name of the dictionary.

  bundle – The Android bundle.

  sequence – A sequence number.

Methods

• public static MDXDictionary create( Context context, String name )

  Creates a dictionary by first checking if a dictionary with the same name already exists. If the dictionary does not exist, then a new dictionary is returned. Otherwise, the existing dictionary is returned. This method never returns null.

  Parameters

  context – The Android context that is making this call.

  name – The name of the dictionary.

  Example

  // Creates a instance of a dictionary.

  MDXDictionary dict = MDXDictionary.create(getContext(), "app-settings");

• public static boolean delete( Context context, String name )

  Deletes a dictionary by name. Returns true on success; returns false on failure.

  Parameters

  context – The Android context that is making this call.

  name – The name of the dictionary.

  Example

  // Creates a instance of a dictionary.

  MDXDictionary.delete(getContext(), "app-settings");

• public static MDXDictionary find( Context context, String name )

  Finds an existing dictionary. Returns an existing dictionary; returns null if no dictionary is found.

  Parameters

  context – The Android context that is making this call.

  name – The name of the dictionary.

  Example

  MDXDictionary dict = MDXDictionary.find(getContext(),"app-settings");

   if( dict != null )
       {
           // Use dictionary
       }
   <!--NeedCopy-->
  

• public boolean isNew( )

  Checks whether this is a new dictionary or an existing dictionary. Returns true if a dictionary does not already exist.

  Example

  MDXDictionary dict = MDXDictionary.create(getContext(), "app-settings");

   if (dict.isNew())
       {
           // Dictionary was not found.
       }
   else
       {
           // Existing dictionary was found.
       }
   <!--NeedCopy-->
  

• public boolean save( Context context )

  Stores an encrypted dictionary. If a dictionary with the same name exists, it will be overwritten. Returns true on success; returns false on failure.

  Parameters

  context – The Android context that is making this call.

  Example

  MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");

   if( dict != null )
       {
           String certificate = getCertificate();
           dict.bundle.putString( "secret-certificate", certificate );
           // Update bundle by overwriting the existing bundle.
           dict.save( getContext() );
       }
   <!--NeedCopy-->
  

• public boolean append( Context context )

  Appends an encrypted dictionary to an existing dictionary. If no dictionary exists, the specified dictionary is stored. Returns true on success; returns false on failure.

  Parameters

  context – The Android context that is making this call.

  Example

  MDXDictionary dict = MDXDictionary.find(getContext(), ";app-settings");

   if( dict != null )
       {
           String certificate = getCertificate();
           Bundle bundle = new Bundle();
           bundle.putString( "secret-certificate", certificate );
           dict.bundle = bundle;
           dict.append( getContext() );
           // Note that dict.bundle may not match the state of the
           // bundle that was stored. The stored bundle could be
           // larger.
       }
   <!--NeedCopy-->
  

• public boolean delete( Context context )

  Deletes the dictionary. Returns true on success; returns false on failure.

  Parameters

  context – The Android context that is making this call.

  Example

  MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");

   if( dict != null )
       {
           dict.delete( getContext() );
       }
   <!--NeedCopy-->
  

Notes and considerations

• Constructors will throw an IllegalArgumentException when bad parameters are passed in.
• The create() operation will never return null. If the encryption policy is enabled, the user is responsible for ensuring it is unlocked before create() is called.
• The append() operation can fail if a stored object that can be parsed or serialized is not a known Java or Android datatype. Secure Hub is unable to unmarshal the dictionary because the class is not known internally to Secure Hub.
• The append() operation will append its bundle to an existing dictionary bundle. If the stored bundle is different than the bundle in the dictionary, the local bundle will not reflect the state of the bundle stored. A find() operation or a create() operation is necessary to query the state of previously stored bundle.