Product Documentation

To configure Device Manager to generate identity certificates from OpenTrust adapter

Dec 21, 2015

You will need to generate a certificate from OpenTrust with the following keyUsage:

  • keyEncipherment
  • digitalSignature

Furthermore, you will need an OpenTrust root certificate and a CA certificate.

Caution: This procedure will invalidate all certificates used previously by Device Manager. All devices using a certificate to authenticate, such as iOS and Android, Symbian, and Windows Mobile using Strong Authentication mode will need to be re-enrolled.
  1. Modify pki.xml. This file is located in tomcat/webapps/zdm/WEB-INF/classes. Open it with a text editor, and modify it as follows (the modified parts are in bold text). Keep in mind the following considerations:
    • Path to the certificates.
    • keyUsage of the certs.
    • Name of the OpenTrust connector in the console.
    • The CSR template that has to match your profile definition on the OpenTrust PKI Server.
    <?xml version="1.0" encoding="UTF-8"?> 
     
    <beans xmlns="http://www.springframework.org/schema/beans" 
     
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     
    xmlns:p="http://www.springframework.org/schema/p" 
     
    xsi:schemaLocation=" 
     
    http://www.springframework.org/schema/beans     http://www.springframework.org/schem...-beans-3.0.xsd 
     
    "> 
     
      
     
        <bean id="legacyRoot" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="${ios.mdm.pki.ca-root.certificatefile}" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
        <bean id="legacyIOsDevicesCa" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${ios.mdm.pki.ca-mdm.keystoretype}" 
     
              p:keyStorePath="${ios.mdm.pki.ca-mdm.certificatefile}" 
     
              p:entryAlias="" 
     
              p:keyStorePass="${ios.mdm.pki.ca-mdm.privatekey.password}" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="legacyRoot" 
     
        /> 
     
      
     
        <!-- SHTP is the proprietary protocol ZDM uses to communicate 
     
            with Windows and Android devices --> 
     
      
     
        <bean id="legacyShtpDevicesCa" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${secure.device.keystore.type}" 
     
              p:keyStorePath="${secure.device.certificate.file}" 
     
              p:entryAlias="${secure.device.alias}" 
     
              p:keyStorePass="${secure.device.private.key.password}" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="legacyRoot" 
     
        /> 
     
      
     
        <alias alias="legacyDigitalSigner" name="legacyIOsDevicesCa" /> 
     
      
     
        <bean id="legacySslCert" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${ios.mdm.pki.ssl.keystoretype}" 
     
              p:keyStorePath="${ios.mdm.pki.ssl.certificatefile}" 
     
              p:entryAlias="" 
     
              p:keyStorePass="${ios.mdm.pki.ssl.privatekey.password}" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
      
     
        <bean id="OT_Root_cert" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otroot.cer" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
        <bean id="OT_CA_cert" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otinter.cer" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="OT_Root_cert" 
     
        /> 
     
      
     
        <bean id="OT_RA_cert" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="PKCS12" 
     
              p:keyStorePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otadmin.p12" 
     
              p:entryAlias="" 
     
              p:keyStorePass="opentrust" 
     
              p:issuerParams-ref="OT_CA_cert" 
     
        /> 
     
      
     
        <bean class="com.sparus.nps.pki.spi.impl.GpkiCa" id="OT_CA"> 
     
            <property name="caCertificate"> 
     
                <description> 
     
                    This CA's certificate. 
     
      
     
                    WARNING! In order for tomcat to accept clients presenting identities 
     
                    issued by this CA, tomcat's truststore has to be modified accordingly 
     
                     (e.g. installing in it the certificate referred to here). 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPublic"> 
     
                    <constructor-arg ref="OT_CA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="entityName" value="OTAdapter"> 
     
                <description> 
     
                    This is the GPKI entity name as defined in the console. 
     
                </description> 
     
            </property> 
     
            <property name="requestProperties"> 
     
                <description> 
     
                    If the adapter defines user parameters (i.e., non-injected parameters), 
     
                    then they can be defined here. EMC adapter currently does not define 
     
                    any parameters. 
     
                </description> 
     
                <bean class="com.sparus.nps.pki.gpki.util.SimpleRequestProperties"> 
     
                    <constructor-arg index="0" type="java.util.Map"> 
     
                        <map key-type="java.lang.String" value-type="java.lang.String"> 
     
                            <!--<entry key="[PARAMETER NAME]" value="[PARAMETER VALUE]" />--> 
     
                        </map> 
     
                    </constructor-arg> 
     
                </bean> 
     
            </property> 
     
            <property name="raEncryptionCert"> 
     
                <description> 
     
                    RA encryption cert. MUST be issued by the certificate referred to 
     
                    in property caCertificate, i.e. the CA certificate, i.e. the certificate 
     
                    that will sign device identities. 
     
      
     
                    This cert MUST have keyUsage: keyEncipherment. 
     
      
     
                    RA encryption cert may be the same one as RA signing cert. 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="OT_RA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="raSigningCert"> 
     
                <description> 
     
                    RA signing cert. MUST be issued by the certificate referred to 
     
                    in property caCertificate, i.e. the CA certificate, i.e. the certificate 
     
                    that will sign device identities. 
     
      
     
                    This cert MUST have keyUsage: digitalSignature. 
     
      
     
                    RA signing cert may be the same one as RA encryption cert. 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="OT_RA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="csrTemplate"> 
     
                <bean class="com.sparus.nps.pki.spi.impl.CsrMacroTemplate"> 
     
                    <description> 
     
                        Template for the CSR. 
     
      
     
                        WARNING! Macros have to be specified using '%{...}', instead 
     
                        of '${...}', in XML files. 
     
                    </description> 
     
                    <property name="dnFields"> 
     
                        <list> 
     
                            <description> 
     
                                The following are samples. Remove or add others as you like. 
     
                            </description> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="CN" p:value="%{user.loginname}" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="OU" p:value="aeotn" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="O" p:value="noise" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="C" p:value="DE" /> 
     
                        </list> 
     
                    </property> 
     
                    <property name="altnames"> 
     
                        <list> 
     
                            <description> 
     
                                The following are samples. Remove or add others as you like. 
     
                            </description> 
     
                            <bean class="com.sparus.nps.pki.def.AltNameBean" p:sanType="rfc822Name" p:value="%{user.mail}" /> 
     
                            <bean class="com.sparus.nps.pki.def.AltNameBean" p:sanType="userPrincipalName" p:value="%{user.username}@home.net" /> 
     
                        </list> 
     
                    </property> 
     
                </bean> 
     
            </property> 
     
        </bean> 
     
      
     
      
     
        <!-- 
     
            The new PkiSpi infrastructure is designed to support all the PKI 
     
            capabilities we can reasonably be expected to need in the average term. 
     
            However, the rest (installer / business process) isn't up to par 
     
            yet; as such, we're retrofitting this infrastructure to work with 
     
            our current setup. That's the meaning behind the word "legacy" 
     
            in this context. 
     
        --> 
     
      
     
        <bean id="certFactory" class="com.sparus.nps.pki.def.ZdmCertificateFactory"> 
     
            <description> 
     
                The ZdmCertificateFactory builds public key certificate objects 
     
                from either PublicCertFileParams, PrivateCertFileParams or 
     
                KeyStoreParams; and private key certificate objects (public 
     
                key + private) from PrivateCertFileParams and KeyStoreParams. 
     
      
     
                Factory method for the former is: buildPublic; for the latter: buildPrivate. 
     
            </description> 
     
        </bean> 
     
      
     
        <bean id="serialNumberGen" class="com.sparus.nps.pki.gen.CertificateSerialNumberSequenceImpl" /> 
     
      
     
        <bean id="com.everywan.security.PkiSpi.internal" class="com.sparus.nps.pki.spi.impl.PluggablePki" lazy-init="true"> 
     
            <property name="digitalSignatureRoot"> 
     
                <bean factory-bean="certFactory" factory-method="buildPublic"> 
     
                    <constructor-arg ref="legacyRoot" /> 
     
                </bean> 
     
            </property> 
     
            <property name="sslRoot"><null /></property> <!-- We don't have the config for this... --> 
     
      
     
            <property name="digitalSigningCertificate"> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="legacyDigitalSigner" /> 
     
                </bean> 
     
            </property> 
     
            <property name="sslCertificate"> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="legacySslCert" /> 
     
                </bean> 
     
            </property> 
     
      
     
            <property name="shtpCa" ref="OT_CA" /> 
     
      
     
            <property name="iosMdmCa" ref="OT_CA" /> 
     
        </bean> 
     
      
     
        <bean id="com.everywan.security.PkiSpi" factory-bean="com.everywan.security.PkiSpi.factory" factory-method="getBean" /> 
     
      
     
        <bean id="com.everywan.security.PkiSpi.factory" class="com.sparus.nps.pki.def.PkiSpiFacade"> 
     
            <property name="enabled" value="${zdm.pki.enable}" /> 
     
            <property name="enabledBeanId"><idref local="com.everywan.security.PkiSpi.internal" /></property> 
     
        </bean> 
     
       </beans>

To add certificates to the Device Manager keystore

You now need to add the intermediate and root ca certificates to the Device Manager keystore.

  1. Use the java keytool command (adapt the path to your environment): "C:\Program Files\Java\jdk1.6.0_23\jre\bin\keytool" -importcert -trustcacerts -alias "externalCA" -file "C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\mycert.cer" -keystore "C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\cacerts.pem.jks" -storepass notMeaningFul
  2. Restart the Device Manager service to activate the new PKI usage.