Product Documentation

PKI Entities

Mar 29, 2016

A XenMobile Public Key Infrastructure (PKI) entity configuration represents a component performing actual PKI operations (issuance, revocation, and status information). These components may either be internal to XenMobile, in which case they are called discretionary, or external to XenMobile if they are part of your corporate infrastructure.

XenMobile supports the following types of PKI entities:

  • Discretionary Certificate Authorities (CAs)
  • Generic PKIs (GPKIs)
  • Microsoft Certificate Services

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, you must indicate to XenMobile which CA certificate is going to be the signer of certificates issued by (or recovered from) that entity. One and the same PKI entity may return (fetched or newly signed) certificates signed by any number of different CAs. You must provide the certificate of each of these CAs as part of the PKI entity configuration. To do so, you upload the certificates to XenMobile and then reference them in the PKI entity. For discretionary CAs, the certificate is implicitly the signing CA certificate, but for external entities, you must specify the certificate manually.

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 is capable of taking CSRs, transmitting them to the PKI, and returning newly signed certificates.
  • fetch: The adapter is capable of retrieving (recovering) existing certificates and key pairs (depending on input parameters) from the PKI.
  • revoke: The adapter is able to 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. In other words, there is a GPKI adapter for RSA, another for EnTrust, and so on.

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 are defined by the GPKI adapter for a specific operation and for which you need to provide values to XenMobile. XenMobile determines which operations the adapter supports (which capabilities it has) and which parameters the adapter requires for each of the operations by parsing the WSDL file. 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 Configure > Settings > More > PKI Entities.
  2. On the PKI Entities page, click Add.

    A list showing the types of PKI entities you can add appears.



  3. Click Generic PKI Entity.

    The Generic PKI Entity: General Information page appears.



  4. On the Generic PKI Entity: General Information page, do the following:
    1. Name: Type a descriptive name for the PKI entity.
    2. WSDL URL: Type the location of the WSDL describing the adapter.
    3. Authentication type: Click the authentication method you want to use.
      • None
      • HTTP Basic: Provide the user name and password needed to connect to the adapter.
      • Client certificate: Select the correct SSL client certificate.
    4. Click Next.

      The Generic PKI Entity: Adapter Capabilities page appears.

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

  6. On the Generic PKI Entity: Issuing CA Certificates page, select the certificates you want to use for the entity.
    Note: Although entities may return certificates signed by different CAs, all certificates obtained through a given certificate provider must be signed by the same CA. Accordingly, when configuring the Credential Provider setting, on the Distribution page, select one of the certificates configured here.
  7. Click Save.

    The entity appears on the PKI Entities table.

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.

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.

To add a Microsoft Certificate Services entity

  1. In the XenMobile console, click Configure > Settings > More > PKI Entities.
  2. On the PKI Entities page, click Add.

    A list showing the types of PKI entities you can add 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, do the following:
    1. Name: Type a name for your new entity, which you will use later to refer to that entity. Entity names must be unique.
    2. 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.
    3. certnew.cer page name: The name of the certnew.cer page. Use the default name unless you have renamed it for some reason.
    4. certfnsh.asp: The name of the certfnsh.asp page. Use the default name unless you have renamed it for some reason.
    5. Authentication type: Click the authentication method you want to use.
      • None
      • HTTP Basic: Provide the user name and password needed to connect.
      • Client certificate: Select the correct SSL client certificate.
      • 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.

  5. 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.
  6. Click Next.

    The Microsoft Certificate Services Entity: HTTP parameters page appears. On this page, you specify custom parameters that XenMobile should inject in the HTTP request to the Microsoft Web Enrollment interface. This will only be useful if you have customized scripts running on the CA.

  7. 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 are required to inform XenMobile of the signers of the certificates that the system will obtain through this entity. When your CA certificate is renewed, update it in XenMobile and then the change is applied to the entity transparently.

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

    The entity appears on the PKI Entities table.

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 have the option to activate Online Certificate Status Protocol (OCSP) support for that CA. If, and only if you enable OCSP support, the CA adds an id-pe-authorityInfoAccess extension to the certificates that the CA issues, pointing to the XenMobile internal OCSP Responder at the following location.

https://server/instance/ocsp

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

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

To add discretionary CAs

  1. In the XenMobile console, click Configure > Settings > More > PKI Entities.
  2. On the PKI Entities page, click Add.

    A list showing the types of PKI entities you can add appears.

  3. Click Discretionary CA.

    The Discretionary CA: General Information page appears.



  4. On the Discretionary CA: General Information page, do the following:
    1. Name: Type a descriptive name for the discretionary CA.
    2. 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.
    3. Click Next.

      The Discretionary CA: Parameters page appears.



  5. On the Discretionary CA: Parameters page, do the following:
    1. 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.
    2. Next serial number: Type a value to determine the next number issued.
    3. Certificate valid for: Type the number of days the certificate is valid.
    4. 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 certificated for those purposes.
    5. Extended key usage: To add additional parameters, click Add, type the key name and then click Save.
    6. Click Next.

      The Discretionary CA: Distribution page appears.

  6. 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 and stored on the user devices. This distributed mode uses SCEP and requires an RA encryption certificate with the keyUsage keyEncryption and an RA signing certificate with the KeyUsage digitalSignature. The same certificate can be used for both encryption and signing.
  7. Click Next.

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

  8. On the Discretionary CA: Online Certificate Status Protocol (OCSP) page, do the following:
    1. 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's OCSP responder at https://server/instance/ocsp.
    2. If you enabled OCSP support, select an OSCP signing CA certificate. This list of certificates is generated from the CA certificates you uploaded at XenMobile at Configure > Settings > Certificates.
  9. Click Save.

    The discretionary CA appears on the PKI Entities table.