This document contains "SmartDocs" capabilities. This will allow you to easily see only the content that is relevant to the Zebra device you are working with.
MX Features will be available on a device based on a combination of factors:
After identifying the version information for your device, simply select them in the SmartDocs bar. Any section that does not apply to your device will be greyed out. You can clear all settings by hitting the SmartDocs button. Clicking the back and next buttons on the SmartDocs bar will navigate to the sections that are relevant to your device.
The CertMgr provides management of certificates and the Android Keystore on a device.
A Digital Certificate is an electronic document that can be used to prove an asserted identity. By possessing a valid Public Certificate and its matching Private Key, an entity can assert an identity and then through Certificate Validation prove to other entities that it is entitled to assert that identity. Certificate Validation is based on verification that an entity possesses the Private Key that is associated with the valid Public Certificate for the asserted identity and that was issued by a trusted Certificate Authority (CA).
To acquire a Public Certificate, an entity first generates a Public/Private Key pair. The entity then submits the Public Key along with identity information to a Certificate Authority (CA). The CA verifies the identity information provided by the requestor, issues a Public Certificate that contains the submitted Public Key and identity information, and signs the Public Certificate using its own Private Key. By signing a Public Certificate with its own Private Key, the CA enables other entities that trust that CA to trust the Public Certificate once they verify that it was signed by that CA. Signing also enables entities to verify that the Public Certificate is genuine and has not been modified since it was signed by the CA.
Digital Certificates are issued for a specific duration, commonly called their Validity Window. A Certificate is not generally considered valid unless the current date is within the Validity Window for that Certificates. This requirement has two key implications. First, it means that entities that utilize Digital Certificates, especially those that perform Certificate Validation, need to know the correct date. Second, it means that entities that use Digital Certificates will need to periodically refresh them by replacing a soon-to-expire Certificate (where the current date is near the end of its Validity Window) with a newer, but compatible Certificate (where the identity information is the same but the current date is further from the end of its Validity Window).
Digital Certificates are most commonly used in Android devices in two primary ways:
Zebra Android devices can store Digital Certificates in two primary areas:
Digital Certificates are commonly acquired in the form of Certificate Files of various formats. Distinguished Encoding Rules (DER) is a standard scheme used to encode Digital Certificates. DER can be used directly to encode a Certificate as a binary Certificate File, which will usually have a file extension of .CER, but may also have a file extension of .CRT or .DER. DER can also be used in conjunction with Base64 encoding to produce a text Certificate File according to the Privacy-enhanced Electronic Mail (PEM) standard. Certificate Files only encode Public Certificates, never Private Keys.
Private Keys are commonly generated or acquired in the form of a text Key File encoded according to the PEM standard. A common practice for Client Certificates is to combine a Public Certificate and a matching Private Key into a Container Files using the Public-Key Cryptography Standards (PKCS) standard PKCS12. PKCS12 is an archive file format for storing multiple cryptography objects as a single binary file, usually with a file extension of .PKCS12, .P12, or .PFX. Container Files constructed according to the PKCS12 standard are typically encrypted based on a password to protect the Private Key contained therein. Encrypted Container Files would require the original password to be supplied before they could be processed.
The CertMgr allows you to initialize the Android Keystore, install or uninstall CA Certificates to the Trusted Store and Android Keystore and the install or uninstalled CA and/or Client Certificates to the Android Keystore.
This parm allows you to specify whether to initialize the Android Keystore, Install a Certificate, or Uninstall a Certificate.
Parm Name: CertAction
Option | Name | Description | Requires |
---|---|---|---|
1 | Install certificate | This value will cause a specified certificate to be installed on the device. |
OSX: 1.0+ MX: 4.1+ |
2 | Uninstall certificate | This value will cause a specified certificate to be uninstalled from the device. |
OSX: 1.0+ MX: 4.1+ |
3 | Initialize Android Keystore | <p>This value will cause a new Android Keystore to be initialized.</p><b>Note:</b> Initializing the Android Keystore can only be done once. If an attempt is made to Initialize the Android Keystore when it has previously been initialized, via the CertMgr or by the device user via the System Settings Menu, then an error will be returned in the Result XML. No method is currently provided, aside from an Enterprise Reset (which can be performed using the PowerMgr) to return the Android Keystore to an uninitialized state or to re-initialize the Android Keystore.</p> |
OSX: 1.0+ MX: 4.2+ |
This parm allows you to specify the Alias to be used to identify a Certificate. When installing a Certificate, the specified Alias is associated with the Certificate (and the corresponding Private Key for a Client Certificate). If a Certificate with the same Alias is already present, it will be replaced. When uninstalling a Certificate, the Alias associated with a previously installed Certificate should be specified. If a match is found, the matching Certificate will be removed. If an attempt is made to uninstall a Certificate for which no match is found, then an error will be returned in the Result XML.
Parm value input rules:
Parm Name: CertAlias
Requires:
- OSX: 1.0+
- MX: 4.1+
This parm is used to specify the type of Certificate to be installed.
Note: The Android Keystore must be initialized exactly once before the CertMgr can be used to Install or Uninstall Certificates. The Android Keystore may be initialized using the CertMgr or by a device user via the System Settings Menu.
Shown if: The Certificate Action is "Install certificate"
Parm Name: CertType
Option | Name | Description | Requires |
---|---|---|---|
5 | CA Certificate (.PEM file) | This value indicates that the Certificate to be installed is a CA Certificate (contained within a .PEM or .CER file) that will be added to both the Trusted Store and Android Keystore. |
OSX: 1.0+ MX: 4.1+ |
6 | Client Certificate (.PEM file) | This value indicates that the Certificate to be installed is the Public Certificate only (contained within a .PEM or .CER file) for a Client Certificate that will be added only to the Android Keystore. |
OSX: 1.0+ MX: 4.1+ |
8 | Client Certificate and Private Key (.PFX file) | This value indicates that the Certificate to be installed is a Public Certificate and Private Key (contained within a .PFX file) for a Client Certificate that will be added only to the Android Keystore. |
OSX: 1.0+ MX: 4.1+ |
9 | Client Certificate and Private Key (.P12 file) | This value indicates that the Certificate to be installed is a Public Certificate and Private Key (contained within a .P12 file) for a Client Certificate that will be added only to the Android Keystore. |
OSX: 1.0+ MX: 4.1+ |
10 | Client Certificate and Private Key (.PKCS12 file) | This value indicates that the Certificate to be installed is a Public Certificate and Private Key (contained within a .PKCS12 file) for a Client Certificate that will be added only to the Android Keystore. |
OSX: 1.0+ MX: 4.1+ |
This parm is used to specify the method to use to install the certificate.
Shown if: The Certificate Action is "Install certificate"
Parm Name: CertMethod
Option | Name | Description | Requires |
---|---|---|---|
2 | Reference certificate file | This value indicates that the data for the Certificate to be Installed is contained with a file that exists in the device file system. |
OSX: 1.0+ MX: 4.1+ |
This parm allows you to specify the path and name of the file in the device file system that contains the data for the Certificate to be installed. If an attempt is made to Install a Certificate using a path and name of a file that does not exist, is not readable, or that does not represent a contain the data for a valid Certificate of the specified type, then an error will be returned in the Result XML.
If the Certificate Action is "Install certificate" AND the Certificate Method is "Reference certificate file" AND the Certificate Type is "CA Certificate (.PEM file)"
Parm value input rules:
Shown if: If the Certificate Action is "Install certificate" AND the Certificate Method is "Reference certificate file" AND the Certificate Type is "Client Certificate (.PEM file)" or "Client Certificate and Private Key (.PFX file)" or "Client Certificate and Private Key (.P12 file)" or "Client Certificate and Private Key (.PKCS12 file)"
Parm Name: CertFileCA
Requires:
- OSX: 1.0+
- MX: 4.1+
This parm allows you to specify the path and name of the file in the device file system that contains the data for the Certificate to be installed. If an attempt is made to Install a Certificate using a path and name of a file that does not exist, is not readable, or that does not represent a contain the data for a valid Certificate of the specified type, then an error will be returned in the Result XML.
If the Certificate Action is "Install certificate" AND the Certificate Method is "Reference certificate file" AND the Certificate Type is "CA Certificate (.PEM file)"
Parm value input rules:
Parm Name: CertFileClient
Requires:
- OSX: 1.0+
- MX: 4.1+
This parm allows you to specify whether or not to the device clock should be adjusted automatically when the Certificate is installed if the current date on the device is outside of the Validity Window for the Certificate.
Note: This option allows you to solve the issue where a device may be unable to use a Certificate to get on a network (e.g. EAP-TLS) because the date on the device is not set properly (as it may not be on a fresh-out-of-the-box device) and hence the Certificate appears to be invalid (expired or not yet valid). If this parm has a value of "true" and if the date is outside the Validity Window for a Certificate that is being installed, the date of the device will be changed to the start date of the Validity Window for a Certificate. A common use case is to use this option to allow a Certificate to be used to join a network and then acquire the real date and time via that network (see Clock).
Parm value input rules:
Parm Name: CertAdjustClock
Requires:
- MX: 4.2+
- Android API Level: 1.0+
This parm allows you to specify the password that will be used to Initialize the Android Keystore. Specifying an empty (length of zero) value (or the absence of this parm from the XML) will cause a random password to be generated to Initialize the Android Keystore.
Note: This password will never need to be supplied again to the CertMgr once the Android Keystore has been successfully initialized since it will be able Install and Uninstall Certificates without needing this password. But the device user might need to know this password to perform management of Certificates using the System Settings Menu. If the password is lost or if a random password is generated, then the device user could not be supplied with the password and hence could never perform such management. This is generally not a problem since management of Certificates is generally a feature best left to MDMs and it is better to prevent the device user from performing such functions.
Parm value input rules:
Shown if: The Certificate Action is "Initialize Android Keystore"
Parm Name: KeystorePassword
Requires:
- OSX: 1.0+
- MX: 4.1+
This parm allows you to specify the password that is required to decrypt a Container File containing the Public Certificate and Private Key for a Client Certificate.
Note: If an attempt is made to use a Container File that is not encrypted or that was not encrypted using the specified password, then an error will be returned in the Result XML.
Parm value input rules:
Shown if: The Certificate Action is "Install certificate" *AND* the Certificate Type is "Client Certificate and Private Key (.PFX file)" or "Client Certificate and Private Key (.P12 file)" or "Client Certificate and Private Key (.PKCS12 file)"
Parm Name: PrivateKeyPassword
Requires:
- OSX: 1.0+
- MX: 4.1+
The Android Keystore must be initialized exactly once before Certificates can be installed or uninstalled. If the device user has not initialized the Android Keystore via the System Settings Menu, and the CertMgr has not previously been used to initialize the Android Keystore, then the CertMgr should be used to initialize the Android Keystore, as shown below:
Without a password:
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="4"/>
</characteristic>
</wap-provisioningdoc>
With a password:
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="4"/>
<characteristic type="keystore-details">
<parm name="KeystorePassword" value="mobility"/>
</characteristic>
</characteristic>
</wap-provisioningdoc>
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="1"/>
<characteristic type="cert-details">
<parm name="CertAlias" value="mxtest"/>
<parm name="CertType" value="5"/>
<parm name="CertMethod" value="2"/>
<parm name="CertFileCA" value="/enterprise/usr/persist/test.pem"/>
<parm name="CertAdjustClock" value="false"/>
</characteristic>
</characteristic>
</wap-provisioningdoc>
Note: The above XML, with just a change of file name, could be used to install a CA Certificate from a .CER or .DER file, since all are DER encoded and hence supported via the same type.
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="1"/>
<characteristic type="cert-details">
<parm name="CertAlias" value="mxtest"/>
<parm name="CertType" value="6"/>
<parm name="CertMethod" value="2"/>
<parm name="CertFileClient" value="/enterprise/usr/persist/test.pem"/>
<parm name="CertAdjustClock" value="false"/>
</characteristic>
</characteristic>
</wap-provisioningdoc>
Note: The above XML would not normally be used to Install brand new Client Certificate since it only installs the Public Certificate and not the Private Key. The primary situation where the above XML might be used is when the Public Certificate and Private Key were previously installed, as in the next example, and the Public Certificate needed to be replaced (such as to renew it before it expires). In such a situation, if the Public and Private Key did not change, then it may be preferable to update the Public Certificate and leave the Private Key alone.
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="1"/>
<characteristic type="cert-details">
<parm name="CertAlias" value="mxtest"/>
<parm name="CertType" value="8"/>
<parm name="CertMethod" value="2"/>
<parm name="CertFileClient" value="/enterprise/usr/persist/test.pfx"/>
<parm name="CertAdjustClock" value="false"/>
<parm name="PrivateKeyPassword" value="mobility"/>
</characteristic>
</characteristic>
</wap-provisioningdoc>
Note: The above XML, with just a change of file name, could be used to install a Client Certificate and Private Key from a .P12 or .PKCS12 file, since all are PKCS12 encoded and hence are supported via the same type.
<wap-provisioningdoc>
<characteristic type="CertMgr" version="4.2" >
<parm name="CertAction" value="2"/>
<characteristic type="cert-details">
<parm name="CertAlias" value="mxtest"/>
</characteristic>
</characteristic>
</wap-provisioningdoc>