Cert Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

EMDK For Android - 6.10

Overview

The Certificate Manager (CertMgr) manages certificates and the Android Keystore on a device. The CertMgr can initialize the Android Keystore, install or uninstall CA Certificates to the Trusted Store and Android Keystore, and install or uninstall CA and/or Client Certificates to the Android Keystore.

Main Functionality

  • Initialize Android Keystore
  • Install or uninstall CA Certificates
  • Install or uninstall Client Certificates

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 through Certificate Validation prove to other entities that it is entitled to assert that identity. Certificate Validation is based on verification that an entity has the Private Key associated with the valid Public Certificate for the asserted identity, and that it 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 requester, 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 the Validity Window. A Certificate is not generally considered valid unless the current date is within the Validity Window for that Certificate. This requirement has two key implications. First, it means that entities that use Digital Certificates--especially those that perform Certificate Validation--need to know the correct date. Second, it means that entities that use Digital Certificates must periodically refresh them by replacing a soon-to-expire Certificate (in which the current date is near the end of its Validity Window) with a newer, but compatible Certificate (in which 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 by Android in two ways:

  • A Public Certificate can be used to establish trust by a device or some other entity, such as a server. The most common use of Public Certificates alone is to establish trust of a CA and hence of all Certificates issued by that CA. Such a Public Certificate is generally referred to as a CA Certificate. In addition, a Public Certificate could be used to verify that an application to be run on the device came from a trusted developer or to verify that a Server being accessed by the device is authentic.
  • Second, a Public Certificate can be paired with a Private Key to allow the device to assert and prove an identity to another entity. Such a pairing of a Public Certificate with a Private Key is often referred to as a Client Certificate because it is commonly used by a Client on device to prove an identity that it asserts to a Server. A Client Certificate might be used to authenticate the device to a Wireless Local Area Network (e.g. EAP-TLS) or to a Web Server (e.g. HTTPS).

Zebra Android devices can store Digital Certificates in two primary areas:

  • The Trusted Store is a protected area of the device that can only hold CA Certificates. The Trusted Store is present in the device by default and contains CA Certificates for many well-known and universally trusted CAs. The Trusted Store allows various system applications to establish trust of CAs that issue other Certificates.

  • The Android Keystore is a protected area of the device that can hold both CA Certificates and Client Certificates. The Android Keystore must be initialized before it can be used and starts out empty. By adding CA Certificates to the Android Keystore, trust of additional CAs and Servers is established. By adding Client Certificates to the Android Keystore, the device can be provided with the ability to assert and prove various identities. The Android Keystore can be initialized only once; re-initialization requires an Enterprise Reset.

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 variations include .CRT and .DER. DER also can 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 File 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 require the original password to be supplied before they can be processed.

Certificate Action

Used to Install or Uninstall a certificate or to initialize the Android Keystore. If a certificate is installed with the same alias as one that already exists in the Keystore, the existing certificate is overwritten by the new one.

Notes:

  • The Android Keystore can be "initialized" only once; subsequent uses of the Initialize Android Keystore function will simply reset the password, leaving the Keystore intact. To return the Android Keystore to a pre-initialized state, see the Enterprise Reset and Factory Reset functions of Power Manager.
  • To verify certificate installation on the device:
    • Go to Settings -> Wifi -> AddNetwork
    • From Security drop-down, select "802.1xEAP"
    • From EAP method drop-down, select "TLS" menu
    • Installed certificate appears under "User certificate"

Parm Name: CertAction

Option Name Description Note Requires
1 Install certificate Installs the specified certificate on the device.

OSX: 1.0+

MX: 4.1+

2 Uninstall certificate Removes the specified certificate from the device.

OSX: 1.0+

MX: 4.1+

3 Initialize Android Keystore Causes a new Android Keystore to be initialized or the password reset (see Note above).

OSX: 1.0+

MX: 4.2+

Certificate Alias

Used to enter the Alias 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 is replaced with the value entered here. When uninstalling a Certificate, enter the Alias associated with a previously installed Certificate. If a match is found, the matching Certificate is removed. If an attempt is made to uninstall a Certificate for which no match is found, an error is returned in the Result XML.

Input value rules:

  • String of at least 1 character

Parm Name: CertAlias

Requires:

  • OSX: 1.0+
  • MX: 4.1+

Certificate Type

This parm is used to enter 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 Note 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+

Certificate Method

This parm is used to enter the method to use to install the certificate.

Shown if: The Certificate Action is "Install certificate"

Parm Name: CertMethod

Option Name Description Note 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+

Certificate File CA

Used to enter 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 contain the data for a valid Certificate of the specified type, an error is returned in the Result XML.

Input value rules:

  • String from 1–255 characters

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+

Certificate File Client

used to enter 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)"

Input value rules:

  • String with a minimum size of 1 character and a maximum size of 255 characters

Parm Name: CertFileClient

Requires:

  • OSX: 1.0+
  • MX: 4.1+

Adjust Clock

Used to select whether 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. If set to "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.

Note: This option can solve the issue of a device that's 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 factory-fresh device) and hence the Certificate appears to be invalid (expired or not yet valid). 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 using that network (also see Clock).

Input value rules:

  • String with a value of "true" or "false"

Parm Name: CertAdjustClock

Requires:

  • MX: 4.2+
  • Android API: 1.0+

Private Key Password

Used to enter 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.

Input value rules:

  • String with a minimum of 1 character and a maximum of 32 characters

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+

Keystore Password

Used to enter the password that will be used to Initialize the Android Keystore. Entering 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.

Input value rules:

  • String with a minimum of 1 character and a maximum of 32 characters

Shown if: The Certificate Action is "Initialize Android Keystore"

Parm Name: KeystorePassword

Requires:

  • OSX: 1.0+
  • MX: 4.1+

Examples

Initialize the Android Keystore

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>

Install a CA Certificate (.PEM file)


<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.

Install a Client Certificate (.PEM file)


<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.

Install a Client Certificate and Private Key (.PFX file)


<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.

Remove a Certificate


<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>