Encrypt Manager

Stagenow - 2.7

Overview

The Encrypt Manager (EncryptMgr) allows apps to manage the Key Storage Database, activate or deactivate Full Storage Card Encryption, and create or delete Encrypted File Systems (EFSes). To configure encryption, certain questions must be answered:

  • What data will be encrypted?
  • Where will the encrypted version of the data be physically stored?
  • How will the unencrypted version of the data be accessed by applications?
  • Which keys will be used to encrypt and decrypt the data?

Zebra Android devices support encrypting data that is stored in the device file system using two modes of operation:

  • Full Storage Card Encryption Mode allows a single Storage Card, usually the one that is physically removable (e.g. a Micro SD Card) to be formatted as one single encrypted file system. This mode is particularly useful, from a security point of view, because it protects all data stored on the Storage Card from being accessed externally if the card is physically removed from the device. In this mode, the entire card is encrypted, and the key used to perform the encryption is not stored on the card. Since data is encrypted and decrypted transparently, applications running on the device can access all the data on the Storage Card as if it were not encrypted. Applications access an encrypted Storage Card using the same paths they would use if the Storage Card was not encrypted.

Different kinds of devices can respond differently when "Full Storage Card Encryption Mode" is turned on, such as:

  • If a device (such as the MC40) does not have a removable Storage Card, then the built-in Primary External Storage volume will be encrypted in the same way that a removable Storage Card would be encrypted.
  • If the device does support a removable Storage Card and the slot for it is empty, MXMS will return an error indicating that no card was found and the built-in Primary External Storage will not be encrypted.

Note: If "Full Storage Card Encryption Mode" is turned on while a removable Storage Card is in the slot, the removable Storage Card will be encrypted. It will remain encrypted after being removed from the device and will mountable only in the device that originally encrypted it, provided its key is present.

Note: Changing a Storage Card from unencrypted to encrypted or encrypted to unencrypted requires reformatting the card, which erases all data on the card. If there is data that must be preserved, it must be copied to another location before activating or deactivating encryption and copied back after the card is reformatted.

  • Folder Encryption Mode allows any number of Encrypted File Systems (EFS) to be created. The data for each EFS resides in a single file that must be stored on some non-encrypted file system. This file is called the Backing Storage File (BSF). A BSF can be located on internal storage (e.g. /data) or on the Primary Storage Card. The BSF is named based on the name of the EFS. An EFS is mounted at a virtual path, called its Mount Point. The Mount Point for an EFS could specify a path on the same non-encrypted file system where the BSF is located or could specify a path on a different file system. Since data is encrypted and decrypted transparently, applications running on the device can access all the data on an EFS as if it was not encrypted. Applications must access an EFS using the Mount Point path that is established when the EFS is created.

Note: While the BSF for an EFS can be stored on a Storage Card that is removable, it cannot be stored on a Storage Card that is encrypted using Full Storage Card Encryption Mode. If an attempt is made to create an EFS, whose BSF is on a Storage Card that is encrypted using Full Storage Card Encryption, then an error will be returned in the Result XML.

Zebra Android devices have a Key Storage Database of named encryption keys. Each Named Key has an associated Key Value that can be used to encrypt a Full Storage Card and/or to encrypt any number of EFSes. When activating Full Storage Card Encryption or creating an EFS, a Named Key must be specified and must exist in the Key Storage Database. If a Named Key is removed from the Key Storage Database, Full Storage Card Encryption and/or EFSes that are encrypted using that Named Key will become inaccessible. Adding the Named Key (with the same Key Value) will restore accessibility.

Main Functionality

  • Add and Remove Named Keys
  • Create and Delete Encrypted File Systems
  • Format the Storage Card as Encrypted or Unencrypted

Install Key

Used to choose whether to Add a Named Key to the Key Storage Database on the device. Adding a Named Key to the Key Storage Database on the device makes a key available for use when activating Full Storage Card Encryption or when creating EFSes.

Notes:

  • Only one Encrypted File System (EFS) can be mounted at a time using a given mount point.
  • Attempts to create an EFS with a mount point that is already in use by a mounted EFS will result in creation of a new EFS that will not be mounted.
  • Named keys added to the Key Storage Database can impact storage cards or EFSes previously encrypted using that key.
  • Storage that became inaccessible by removing its key will become accessibe and could be re-mounted when a key of the same name and value is added.

Parm Name: InstallKeyAction

Option Name Description Device Group Requires
0 Do Nothing This value (or the absence of this parm from the XML) will cause no change to the Key Storage Database. A

OSX: 1.0+

MX: 4.3+

1 Install Key Adds the Named Key and its associated Key Value to the Key Storage Database. A

OSX: 1.0+

MX: 4.3+

Install Key Name

Used to specify the name of the Named Key that will be added to the Key Storage Database.

Note: If an attempt is made to add a Named Key that is already in the Key Storage Database, then an error will be returned in the Result XML.

Parm value input rules:

  • String with a minimum size of 1 character

Shown if: The Install Key action is "Install key"

Parm Name: InstallKeyName

Requires:

  • OSX: 1.0+
  • MX: 4.3+

Install Key Value

Used to specify the Key Value to be associated with a Named Key being added to the Key Storage Database. Specifying an empty (length of zero) value (or the absence of this parm from the XML) will cause a random key value to be automatically generated and used on the device. Read important notes below regarding random key generation.

Important: Random, machine-generated keys are generally considered the most secure. Such keys are virtually impossible to guess because of their length, and cannot be accidentally revealed because they are never known to the user. However, if a random key is lost, data encrypted using that key is also lost. Persistent data could be rendered irretrievable on a device following an Enterprise Reset or other erasure event if the only copy of the encryption key is erased during that event. The Install Key Value parameter accepts 256-bit AES encryption values generated using any desired mechanism. Once generated, Key Values should be managed and preserved carefully.

Zebra recommends that the persistence of encryption keys match that of the device data.

Parm value input rules:

  • HEX string that is either empty (length of zero) or exactly 64 HEX characters ("0-9" and/or "A-F" characters) to be used as an AES encryption Key Value to encode a 256-bit binary value

Shown if: The Install Key action is "Install key"

Parm Name: InstallKeyValue

Requires:

  • OSX: 1.0+
  • MX: 4.3+

Revoke Key

Used to choose whether to Remove a Named Key from the Key Storage Database.

Note: If an attempt is made to Remove a Named Key that is not currently in the Key Storage Database, an error will be returned in the Result XML.

Removing a Named Key from the Key Storage Database prevents that key from subsequently being used when activating Full Storage Card Encryption or when creating EFSes.

Note: When a Named Key is successfully Removed from the Key Storage Database, any Storage Card or Encrypted File Systems that were encrypted using that key and that were mounted will be un-mounted and become inaccessible.

Parm Name: RevokeKeyAction

Option Name Description Device Group Requires
0 Do Nothing This value (or the absence of this parm from the XML) will cause no change to the Key Storage Database. A

OSX: 1.0+

MX: 4.3+

1 Revoke Key Removes an Encryption Key from the Key Storage Database. A

OSX: 1.0+

MX: 4.3+

Revoke Key Name(s)

Used to specify the name(s) of the Named Key(s) to be Removed from the Key Storage Database.

Parm value input rules:

  • String with a minimum size of 1 character
  • The names must be separated by commas

Shown if: The Revoke Key action is "Revoke key"

Parm Name: RevokeKeyName

Requires:

  • OSX: 1.0+
  • MX: 4.3+

Create EFS

Used to choose whether to create an Encrypted File System on the device.

Note: The process of Creating an Encrypted File System (EFS) takes time since it must create the Backing Storage File (BSF) and mount the EFS on its designated Mount Point. As a result, applications will not be able to access an EFS via its Mount Point until it is successfully mounted. Further, an EFS could later be un-mounted if the Key Name it is using is Removed from the Key Storage Database. Applications that use an EFS should thus include error handling logic that can deal with situations where the EFS is not mounted and cannot be accessed.

An attempt to Create an Encrypted File System creation may fail for various reasons, including:

  • A BSF with the specified EFS name already exists in the specified storage location. Only one EFS of a given name can be created for each storage location.
  • The storage location specified for the BSF is not accessible (e.g. is not mounted) or is not writable.
  • The storage location specified for the BSF has insufficient free space to create the BSF of the specified size.
  • The storage location specified for the BSF is a Storage Card for which Full Storage Card Encryption has been activated.
  • The Named Key specified for the EFS is not present in the Key Storage Database.
  • The size specified for the EFS is invalid.

Parm Name: CreateEFSAction

Option Name Description Device Group Requires
0 Do Nothing This value (or the absence of this parm from the XML) will cause no Encrypted File System to be created. A

OSX: 1.0+

MX: 4.3+

1 Create EFS This value will cause an Encrypted File System to be created. A

OSX: 1.0+

MX: 4.3+

EFS Key Name

Used to specify the Named Key to use when creating the Encrypted File System.

Parm value input rules:

  • String with a minimum size of 1 character

Shown if: The Create EFS action is "Create EFS"

Parm Name: EFSKeyName

Requires:

  • OSX: 1.0+
  • MX: 4.3+

EFS Name

Used to specify the name of the Encrypted File System to be Created.

Parm value input rules:

  • String with a minimum size of 1 character

Shown if: The Create EFS action is "Create EFS"

Parm Name: EFSName

Requires:

  • OSX: 1.0+
  • MX: 4.3+

EFS Location

Used to specify the storage location where the Backing Storage File should be stored for the Encrypted File System to be created.

Shown if: The Create EFS action is "Create EFS"

Parm Name: EFSLocation

Option Name Description Device Group Requires
0 Do Nothing This value indicates that the BSF for the EFS will be created in the internal storage (i.e. /data) of the device. A

OSX: 1.0+

MX: 4.3+

1 Install Key This value indicates that the BSF for the EFS will be created on the Primary Storage Card of the device. A

OSX: 1.0+

MX: 4.3+

EFS Size

Used to specify the size of the Backing Storage File (in MB) for the Encrypted File System to be created.

Parm value input rules:

  • String with a minimum size of 1 character
  • This value must be at least 1MB and cannot exceed 4096MB.

Shown if: The Create EFS action is "Create EFS"

Parm Name: VolumeSize

Requires:

  • OSX: 1.3+
  • MX: 4.3+

EFS Mount Path

Used to specify the Mount Path to be used for the Encrypted File System to be Created.

Parm value input rules:

  • String with a minimum size of 1 character

Shown if: The Create EFS action is "Create EFS"

Parm Name: MountPath

Requires:

  • OSX: 1.0+
  • MX: 4.3+

Delete EFS

Used to choose whether to Delete an Encrypted File System.

Parm Name: DeleteEFSAction

Option Name Description Device Group Requires
0 Do Nothing This value (or the absence of this parm from the XML) will cause no change to the Encrypted File System. A

OSX: 1.0+

MX: 4.3+

1 Delete EFS Deletes an Encrypted File System. A

OSX: 1.0+

MX: 4.3+

Delete EFS Location (internal/SDcard)

Used to specify the storage location of the Backing Storage File (BSF) of the Encrypted File System (EFS) to be deleted.

Shown if: The Create EFS action is "Delete EFS"

Parm Name: DeleteEFSLocation

Option Name Description Device Group Requires
0 Do Nothing Indicates that the BSF for the EFS to be Deleted is in the internal storage (i.e. /data) of the device. A

OSX: 1.0+

MX: 4.3+

1 Install Key This value indicates that the BSF for the EFS to be Deleted is on the Primary Storage Card of the device. A

OSX: 1.0+

MX: 4.3+

SD Card Operation

Used to activate or deactivate Full Storage Card Encryption. An attempt to activate or deactivate Full Storage Card Encryption may fail for various reasons, including:

  • The Storage Card is removable and is not currently present in the device
  • The Storage Card is not currently mounted or is inaccessible
  • The specified Named Key is not present in the Key Storage Database.

Note: Whenever Full Storage Card Encryption is activated or deactivated, the Storage Card must be reformatted as encrypted or unencrypted, respectively. Reformatting causes the loss of all data on the card. If there is data that must be preserved, it would have to be copied to another location before activating or deactivating encryption and then copied back after the card is reformatted.

Parm Name: SdCardOperation

Option Name Description Device Group Requires
0 Do Nothing This value (or the absence of this parm from the XML) will cause no change to the Full Storage Card Encryption activation status. A

OSX: 1.3+

MX: 4.3+

1 Encrypt SDcard Activates the Full Storage Card Encryption, reformatting and encrypting the Storage Card. A

OSX: 1.3+

MX: 4.3+

2 Format SDcard Deactivates the Full Storage Card Encryption, reformatting and removing encryption from the Storage Card. A

OSX: 1.3+

MX: 4.3+

SD Card Encrypt Key

Used to specify the Named Key that will be used to perform Full Storage Card Encryption.

Note: If the Named Key is not present in the Key Storage Database, an error will be returned in the Result XML.

Parm value input rules:

  • String with a minimum size of 1 character

Shown if: The SDcard Operation is "Encrypt SDcard"

Parm Name: SdCardKeyName

Requires:

  • OSX: 1.3+
  • MX: 4.3+

Examples

Encrypt SD Card


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3" >
        <parm name="SdCardOperation" value="1"/>
        <parm name="SdCardKeyName" value=" EncryptKey"/>
    </characteristic>
</wap-provisioningdoc>

Queries

Get Sdcard Encryption State

Input


<wap-provisioningdoc>
    <characteristic type="EncryptMgr">
        <parm-query name="SdCardOperation" />
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3">
        <parm name="SdCardOperation" value="1" />
    </characteristic>
</wap-provisioningdoc>

Get EFS (Encrypted File System) List

Input


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic-query type="CreateEFS"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic type="CreateEFS"/>
            <parm name="CreateEFSAction" value="1" /> 
            <characteristic type="CreateEFSDetails">
                <parm name="EFSName" value=" EFSName1" /> 
                <parm name="EFSKeyName" value=" EFSKeyName1" /> 
                <parm name="EFSLocation" value=" StorageType1" /> 
                <parm name="MountPath" value=" MountPath1" /> 
                <parm name="VolumeSize" value=" VolumeSize1" /> 
            </characteristic>
        </characteristic>
    </characteristic>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic type="CreateEFS"/>
            <parm name="CreateEFSAction" value="1" /> 
            <characteristic type="CreateEFSDetails">
                <parm name="EFSName" value=" EFSName2" /> 
                <parm name="EFSKeyName" value=" EFSKeyName2" /> 
                <parm name="EFSLocation" value=" StorageType2" /> 
                <parm name="MountPath" value=" MountPath2" /> 
                <parm name="VolumeSize" value=" VolumeSize2" /> 
            </characteristic>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Get Key List

Input


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic-query type="InstallKey"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic type="InstallKey"/>
            <parm name="InstallKeyAction" value="1" /> 
            <characteristic type=" InstallKeyDetails ">
                <parm name="InstallKeyName" value=" KeyName1" /> 
            </characteristic>
        </characteristic>
    </characteristic>
    <characteristic type="EncryptMgr" version="4.3">
        <characteristic type="InstallKey"/>
            <parm name="InstallKeyAction" value="1" /> 
            <characteristic type=" InstallKeyDetails ">
                <parm name="InstallKeyName" value=" KeyName2" /> 
            </characteristic>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>