PKI entities

A XenMobile Public Key Infrastructure (PKI) entity configuration represents a component performing actual PKI operations (issuance, revocation, and status information). These components are either internal or external to XenMobile. Internal components are referred to as discretionary. External components are part of your corporate infrastructure.

XenMobile supports the following types of PKI entities:

  • Generic PKIs (GPKIs)

XenMobile Server GPKI support includes Symantec Managed PKI.

  • Microsoft Certificate Services
  • Discretionary Certificate Authorities (CAs)

XenMobile supports the following CA servers:

  • Windows Server 2008 R2
  • Windows Server 2012
  • Windows Server 2012 R2

Common PKI concepts

Regardless of its type, every PKI entity has a subset of the following capabilities:

  • Sign: Issuing a new certificate, based on a Certificate Signing Request (CSR).
  • Fetch: Recovering an existing certificate and key pair.
  • Revoke: Revoking a client certificate.

About CA Certificates

When you configure a PKI entity, indicate to XenMobile which CA certificate is the signer of certificates issued by (or recovered from) that entity. That PKI entity can return (fetched or newly signed) certificates signed by any number of different CAs.

Provide the certificate of each of these CAs as part of the PKI entity configuration. To do so, upload the certificates to XenMobile and then reference them in the PKI entity. For discretionary CAs, the certificate is implicitly the signing CA certificate. For external entities, you must specify the certificate manually.

Important:

When you create a Microsoft Certificate Services Entity template, avoid possible authentication issues with enrolled devices: Don’t use special characters in the template name. For example, don’t use: ! : $ ( ) # % + * ~ ? | { } [ ]

Generic PKI

The Generic PKI (GPKI) protocol is a proprietary XenMobile protocol running over a SOAP Web Service layer for purposes of uniform interfacing with various PKI solutions. The GPKI protocol defines the following three fundamental PKI operations:

  • Sign: The adapter can take CSRs, transmit them to the PKI, and return newly signed certificates.
  • Fetch: The adapter can retrieve (recover) existing certificates and key pairs (depending on input parameters) from the PKI.
  • Revoke: The adapter can cause the PKI to revoke a given certificate.

The receiving end of the GPKI protocol is the GPKI adapter. The adapter translates the fundamental operations to the specific type of PKI for which it was built. For example, there are GPKI adapters for RSA and Entrust.

The GPKI adapter, as a SOAP Web Services endpoint, publishes a self-describing Web Services Description Language (WSDL) definition. Creating a GPKI PKI entity amounts to providing XenMobile with that WSDL definition, either through a URL or by uploading the file itself.

Support for each of the PKI operations in an adapter is optional. If an adapter supports a given operation, the adapter is said to have the corresponding capability (sign, fetch, or revoke). Each of these capabilities may be associated with a set of user parameters.

User parameters are parameters that the GPKI adapter defines for a specific operation and for which you must provide values to XenMobile. XenMobile parses the WSDL file to determine which operations the adapter has and which parameters the adapter requires for each of those operations. If you choose, use SSL client authentication to secure the connection between XenMobile and the GPKI adapter.

To add a generic PKI

  1. In the XenMobile console, click Settings > PKI Entities.

  2. On the PKI Entities page, click Add.

    A menu of PKI entity types appears.

    Image of PKI Entities configuration screen

  3. Click Generic PKI Entity.

    The Generic PKI Entity: General Information page appears.

    Image of PKI Entities configuration screen

  4. On the Generic PKI Entity: General Information page, do the following:

    • Name: Type a descriptive name for the PKI entity.
    • WSDL URL: Type the location of the WSDL describing the adapter.
    • Authentication type: Click the authentication method you want to use.
    • None
    • HTTP Basic: Provide the user name and password required to connect to the adapter.
    • Client certificate: Select the correct SSL client certificate.
  5. Click Next.

    The Generic PKI Entity: Adapter Capabilities page appears.

  6. On the Generic PKI Entity: Adapter Capabilities page, review the capabilities and parameters associated with your adapter and then click Next.

    The Generic PKI Entity: Issuing CA Certificates page appears.

  7. On the Generic PKI Entity: Issuing CA Certificates page, select the certificates you want to use for the entity.

    Although entities may return certificates signed by different CAs, the same CA must sign all certificates obtained through a given certificate provider. Thus, when configuring the Credential Provider setting, on the Distribution page, select one of the certificates configured here.

  8. Click Save.

    The entity appears on the PKI Entities table.

Symantec Managed PKI

XenMobile Server GPKI support includes Symantec Managed PKI, also referred to as MPKI. This section describes how to set up Windows Server and XenMobile Server for Symantec Managed PKI.

Prerequisites

  • Access to Symantec Managed PKI Infrastructure
  • Windows Server 2012 R2 server with the following components installed, as described in this article:
    • Java
    • Apache Tomcat
    • Symantec PKI Client
    • Portecle
  • Access to the XenMobile downloads site

Install Java on Windows Server

Download Java from https://java.com/en/download/faq/java_win64bit.xml and then install it. In the Security Warning dialog box, click Run.

Install Apache Tomcat on Windows Server

Download the Apache Tomcat 32-bit/64-bit Windows Service Installer from https://tomcat.apache.org/download-80.cgi and then install it. In the Security Warning dialog box, click Run. Complete the Apache Tomcat setup, using the following examples as a guide.

Image of Apache Tomcat Setup screen

Image of Apache Tomcat Setup screen

Image of Apache Tomcat Setup screen

Image of Apache Tomcat Setup screen

Image of Apache Tomcat Setup screen

Next, go to Windows Services and change Startup Type from Manual to Automatic.

Image of Windows Services configuration screen

Image of Windows Services configuration screen

Install Symantec PKI Client on Windows Server

Download the installer from the PKI Manager console. If you don’t have access to that console, download the installer from the Symantec support page How to download Symantec PKI Client. Unzip and run the installer.

Image of Symantec PKI Client installation

Image of Symantec PKI Client installation

In the Security Warning dialog box, be sure to click Run. Follow the instructions in the installer to complete the setup. When the installer completes, it prompts you to restart.

Install Portecle on Windows Server

Download the installer from https://sourceforge.net/projects/portecleinstall/files/ and then unzip and run the installer.

Generate the registration authority (RA) certificate for Symantec Managed PKI

The keystore for client certificate authentication is contained in a registration authority (RA) certificate, named RA.jks. The following steps describe how to generate that certificate by using Portecle. You can also generate the RA certificate by using the Java CLI.

This article also describes how to upload the RA and public certificates.

  1. In Portecle, go to Tools > Generate Key Pair, provide the required information, and generate the key pair.

    Image of Portecle configuration screen

  2. Right-click the key pair and then click Generate Certification Request.

    Image of Portecle configuration screen

  3. Copy the CSR.

  4. In Symantec PKI Manager, generate an RA certificate: Click Settings, click Get a RA Certificate, paste the CSR, and then click Continue.

    Image of Symantec PKI Manager configuration screen

  5. Click Download to download the generated RA certificate.

    Image of Symantec PKI Manager configuration screen

  6. In Portecle, import the RA certificate: Right-click the key pair and then click Import CA Reply.

    Image of Portecle configuration screen

  7. In Symantec PKI Manager: Go to Resources > Web Services and then download the CA certificates.

    Image of Symantec PKI Manager configuration screen

  8. In Portecle, import the RA intermediate and root certificates into the keystore: Go to Tools > Import Trusted Certificates.

    Image of Portecle configuration screen

  9. After importing the CAs, save the keystore as RA.jks under the C:\Symantec folder on the Windows server.

    Image of Portecle configuration screen

Configure Symantec PKI Adapter on Windows Server

  1. Log in to Windows Server as an administrator.

  2. Upload the RA.jks file that you generated in the preceding section. Also upload the public certificates (cacerts.jks) for your Symantec MPKI server.

  3. From the XenMobile Server 10 download page, expand Tools, and download the Symantec PKI Adapter file. The filename is XenMobile_Symantec_PKI_Adapter.zip. Unzip the file and copy these files to the Windows Server C: drive:

    • custom_gpki_adapter.properties

    • Symantec.war

  4. Open custom_gpki_adapter.properties in Notepad and edit the following values:

    Gpki.CaSvc.Url=https://<managed PKI URL>
    
    # keystore for client-cert auth
    
    keyStore=C:\\Symantec\\RA.jks
    
    # truststore for server with self-signed root CA
    
    trustStore=C:\\Symantec\\cacerts.jks
    
  5. Copy Symantec.war under the folder <tomcat dir>\webapps and then start Tomcat.

  6. Verify that the application deployed: Open a web browser and navigate to http://localhost/Symantec.

  7. Navigate to the folder <tomcat dir>\webapps\Symantec\WEB-INF\classes and edit gpki_adapter.properties. Modify the property CustomProperties to point it to the custom_gpki_adapter file under the C:\Symantec folder:

    CustomProperties=C:\\Symantec\\custom_gpki_adapter.properties

  8. Restart Tomcat, navigate to http://localhost/Symantec, and then copy the endpoint address. In the next section, you paste that address when configuring the PKI adapter.

    Image of Symantec PKI configuration screen

Configure XenMobile Server for Symantec Managed PKI

Complete the Windows Server setup before performing the following XenMobile Server configuration.

To import the Symantec CA certificates and configure the PKI Entity

  1. Import the Symantec CA certificates that issue the end-user certificate: In the XenMobile Server console, go to Settings > Certificates and click Import.

    Image of Certificates configuration screen

  2. Add and configure the PKI Entity: Go to Settings > PKI Entities, click Add, and then choose Generic PKI Entity. In WSDL URL, paste the endpoint address that you copied when configuring the PKI adapter in the previous section, and then append ?wsdl as shown below.

    Image of PKI Entities configuration screen

  3. Click Next. XenMobile populates the parameter names from the WSDL.

    Image of PKI Entities configuration screen

  4. Click Next, select the correct CA certificate, and then click Save.

    Image of PKI Entities configuration screen

  5. On the Settings > PKI Entities page, verify that the State of the PKI Entity you added is Valid.

    Image of PKI Entities configuration screen

To create the credential provider for Symantec Managed PKI

  1. In the Symantec PKI Manager console, copy the Certificate Profile OID from the Certificate Template.

    Image of Symantec PKI Manager configuration screen

  2. In the XenMobile Server console, go to Settings > Credential Providers, click Add, and then configure the settings as follows.

    • Name: Type a unique name for the new provider configuration. This name is used to refer to the configuration in other parts of the XenMobile console.

    • Description: Describe the credential provider. Although this field is optional, a description can be useful when you need details about the credential provider.

    • Issuing entity: Choose the certificate issuing entity.

    • Issuing method: Choose Sign as the method that the system uses to obtain client certificates from the configured entity.

    • certParams: Add the following value: commonName=${user.mail},otherNameUPN=${user.userprincipalname},mail=${user.mail}

    • certificateProfileid: Paste the Certificate Profile OID that you copied in Step 1.

    Image of Credential Providers configuration screen

  3. Click Next. On each of the remaining pages (Certificate Signing Request through Renewal), accept the default settings. When you are finished, click Save.

To test and troubleshoot the configuration

  1. Create a Credentials device policy: Go to Configure > Device Policies, click Add, start typing Credentials, and then click Credentials.

  2. Specify a Policy Name.

  3. Configure the platform settings as follows:

    • Credential type: Choose Credential Provider.

    • Credential provider: Choose the Symantec provider.

    Image of Credential Providers configuration screen

  4. After you complete the platform settings, continue to the Assignment page, assign the policy to delivery groups, and click Save.

  5. To check whether the policy deployed to the device, go to Manage > Devices, select the device, click Edit, and click Assigned Policies. The following example shows a successful policy deployment.

    Image of Manage Devices configuration screen

    If the policy didn’t deploy, log in to the Windows Server and check if the WSDL is loading properly.

    Image of Windows Server screen

For more troubleshooting information, check the Tomcat logs in <tomcat dir>\logs\catalina.<current date>.

Microsoft Certificate Services

XenMobile interfaces with Microsoft Certificate Services through its web enrollment interface. XenMobile only supports the issuing of new certificates through that interface (the equivalent of the GPKI sign capability). If the Microsoft CA generates a NetScaler Gateway user certificate, NetScaler Gateway supports renewal and revocation for those certificates.

To create a Microsoft CA PKI entity in XenMobile, you must specify the base URL of the Certificate Services web interface. If you choose, use SSL client authentication to secure the connection between XenMobile and the Certificate Services web interface.

Add a Microsoft Certificate Services entity

  1. In the XenMobile console, click the gear icon in the upper-right corner of the console and then click PKI Entities.

  2. On the PKI Entities page, click Add.

    A menu of PKI entity types appears.

  3. Click Microsoft Certificate Services Entity.

    The Microsoft Certificate Services Entity: General Information page appears.

  4. On the Microsoft Certificate Services Entity: General Information page, configure these settings:

    • Name: Type a name for your new entity, which you use later to refer to that entity. Entity names must be unique.
    • Web enrollment service root URL: Type the base URL of your Microsoft CA web enrollment service; for example, https://192.0.2.13/certsrv/. The URL may use plain HTTP or HTTP-over-SSL.
    • certnew.cer page name: The name of the certnew.cer page. Use the default name unless you have renamed it for some reason.
    • certfnsh.asp: The name of the certfnsh.asp page. Use the default name unless you have renamed it for some reason.
    • Authentication type: Choose the authentication method you want to use.
      • None
      • HTTP Basic: Type the user name and password required to connect.
      • Client certificate: Choose the correct SSL client certificate.
  5. Click Test Connection to ensure that the server is accessible. If it is not accessible, a message appears, stating that the connection failed. Check your configuration settings.

  6. Click Next.

    The Microsoft Certificate Services Entity: Templates page appears. On this page, you specify the internal names of the templates your Microsoft CA supports. When creating credential providers, you select a template from the list defined here. Every credential provider using this entity uses exactly one such template.

    For Microsoft Certificate Services templates requirements, see the Microsoft documentation for your Microsoft Server version. XenMobile doesn’t have requirements for the certificates it distributes other than the certificate formats noted in Certificates.

  7. On the Microsoft Certificate Services Entity: Templates page, click Add, type the name of the template and then click Save. Repeat this step for each template you want to add.

  8. Click Next.

    The Microsoft Certificate Services Entity: HTTP parameters page appears. On this page, you specify custom parameters for XenMobile to add to the HTTP request to the Microsoft Web Enrollment interface. Custom parameters are useful only for customized scripts running on the CA.

  9. On the Microsoft Certificate Services Entity: HTTP parameters page, click Add, type the name and value of the HTTP parameters you want to add, and then click Next.

    The Microsoft Certificate Services Entity: CA Certificates page appears. On this page, you must inform XenMobile of the signers of the certificates that the system obtains through this entity. When your CA certificate is renewed, update it in XenMobile. XenMobile applies the change to the entity transparently.

  10. On the Microsoft Certificate Services Entity: CA Certificates page, select the certificates you want to use for this entity.

  11. Click Save.

    The entity appears on the PKI Entities table.

NetScaler Certificate Revocation List (CRL)

XenMobile supports Certificate Revocation List (CRL) only for a third-party Certificate Authority. If you have a Microsoft CA configured, XenMobile uses NetScaler to manage revocation.

When you configure client certificate-based authentication, consider whether to configure the NetScaler Certificate Revocation List (CRL) setting, Enable CRL Auto Refresh. This step ensures that the user of a device in MAM-only mode can’t authenticate using an existing certificate on the device.

XenMobile reissues a new certificate, because it doesn’t restrict a user from generating a user certificate after one is revoked. This setting increases the security of PKI entities when the CRL checks for expired PKI entities.

Discretionary CAs

A discretionary CA is created when you provide XenMobile with a CA certificate and the associated private key. XenMobile handles certificate issuance, revocation, and status information internally, according to the parameters you specify.

When configuring a discretionary CA, you can activate Online Certificate Status Protocol (OCSP) support for that CA. If, and only if you enable OCSP support, the CA adds the extension id-pe-authorityInfoAccess to the certificates that the CA issues. The extension points to the XenMobile internal OCSP Responder at the following location:

https://<server>/<instance>/ocsp

When configuring the OCSP service, specify an OCSP signing certificate for the discretionary entity in question. You can use the CA certificate itself as the signer. To avoid the unnecessary exposure of your CA private key (recommended): Create a delegate OCSP signing certificate, signed by the CA certificate, and include this extension: id-kp-OCSPSigning extendedKeyUsage.

The XenMobile OCSP responder service supports basic OCSP responses and the following hashing algorithms in requests:

  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512

Responses are signed with SHA-256 and the signing certificate key algorithm (DSA, RSA, or ECDSA).

Add discretionary CAs

  1. In the XenMobile console, click the gear icon in the upper-right corner of the console and then click More > PKI Entities.

  2. On the PKI Entities page, click Add.

    A menu of PKI entity types appears.

  3. Click Discretionary CA.

    The Discretionary CA: General Information page appears.

  4. On the Discretionary CA: General Information page, do the following:

    • Name: Type a descriptive name for the discretionary CA.
    • CA certificate to sign certificate requests: Click a certificate for the discretionary CA to use to sign certificate requests.

      This list of certificates is generated from the CA certificates with private keys you uploaded at XenMobile at Configure > Settings > Certificates.

  5. Click Next.

    The Discretionary CA: Parameters page appears.

  6. On the Discretionary CA: Parameters page, do the following:

    • Serial number generator: The discretionary CA generates serial numbers for the certificates it issues. From this list, click Sequential or Non-sequential to determine how the numbers are generated.
    • Next serial number: Type a value to determine the next number issued.
    • Certificate valid for: Type the number of days the certificate is valid.
    • Key usage: Identify the purpose of the certificates issued by the discretionary CA by setting the appropriate keys to On. Once set, the CA is limited issuing certificates for those purposes.
    • Extended key usage: To add more parameters, click Add, type the key name and then click Save.
  7. Click Next.

    The Discretionary CA: Distribution page appears.

  8. On the Discretionary CA: Distribution page, select a distribution mode:

    • Centralized: server-side key generation. Citrix recommends the centralized option. The private keys are generated and stored on the server and distributed to user devices.
    • Distributed: device-side key generation. The private keys are generated on the user devices. This distributed mode uses SCEP and requires an RA encryption certificate with the keyUsage keyEncryption extension and an RA signing certificate with the keyUsage digitalSignature extension. The same certificate can be used for both encryption and signing.
  9. Click Next.

    The Discretionary CA: Online Certificate Status Protocol (OCSP) page appears.

    On the Discretionary CA: Online Certificate Status Protocol (OCSP) page, do the following:

    • If you want to add an AuthorityInfoAccess (RFC2459) extension to the certificates signed by this CA, set Enable OCSP support for this CA to On. This extension points to the CA OCSP responder at https://<server>/<instance>/ocsp.
    • If you enabled OCSP support, select an OSCP signing CA certificate. This list of certificates is generated from the CA certificates you uploaded to XenMobile.
  10. Click Save.

    The discretionary CA appears on the PKI Entities table.