CertificateEnroller Configuration Service Provider

4/8/2010

The CertificateEnroller Configuration Service Provider in Windows Mobile 6.5 enables you to generate certificates and associate them with a key pair to produce and install trusted certificates for your mobile devices. You can define each certificate type and publish them for other client devices and servers in your corporate network. The CertificateEnroller also provides management and certificate renewal features.

Using the CertificateEnroller Configuration Service Provider with the SECROLE_USER_AUTH role on a device, you can add, delete, or query certificates in the HKCU (User) CA and ROOT certificate stores. If SECROLE_USER_AUTH is granted the SECROLE_MANAGER or if you have SECROLE_MANAGER permissions on the device, you can also add certificates to the HKLM (system) certificate stores. For more information about the certificate stores on mobile devices, see Certificate Management in Windows Mobile Devices.

The CertificateEnroller Configuration Service Provider allows you to perform the following tasks:

• Configure a certificate type
• Configure a certificate type and trigger device enrollment
• Securely enroll for a certificate using a pre-configured certificate type
• Query for and renew existing certificate types

The CertificateEnroller will download the full chain of certificates including the root and any intermediates by requesting the .pb7 file from the certificate server. The path to the file is specified in ServerPickupPage parameter of the CertificateEnroller Configuration Service Provider.

The certificates can be used to establish certificate-based authentication. Your Windows Mobile 6.5 users can enroll for the certificate using Desktop Certificate Enrollment.

Definition of a Certificate Type

A certificate type is given a friendly name and configured with the CertificateEnroller Configuration Service Provider specifying the following parms:

• NoSSL
• ServerName
• ServerPickupPage
• ServerRequestPage
• Template
• UIAccess

Note   The friendly name of each certificate type must be unique. If an existing friendly name is used, the certificate type file will be overwritten with the new parms.

The following image shows the Configuration Service Provider in tree format used by OMA DM.

The following image shows the Configuration Service Provider in tree format as used by OMA Client Provisioning.

Characteristics

• Configuration
  The data in the Configuration characteristic defines and provisions a Certificate Type for enrollment.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• <CertificateTypefriendlyname>
  This is the unique friendly name used to identify each configured certificate type enrollment. If a friendly name specified in the Configuration characteristic already exists, the file will be overwritten with the new data. Each Certificate Type friendly name must be unique.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Operation
  Use the Operation characteristic to enroll an existing Certificate Type or to renew an existing certificate with the Enroll or RenewOperation sub-characteristics. The Renew sub-characteristic allows querying for certificates in the store that need to be renewing.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Enroll
  One or more enrollment operations can be specified under this characteristic, each identified by a unique ID characteristic. The required CertificateTypeFriendlyName parameter identifies the certificate to be enrolled.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• <Unique ID>
  The GUID used to identify the Enroll or RenewOperation for a specific configured certificate type.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• RenewOperation
  One or more renewal operations can be specified under the RenewOperation characteristic. The most important parameter under the unique ID characteristic for the RenewOperation action is the RenewCertificateHash parameter, which specifies the hex-encoded SHA-1 hash of the certificate to be renewed.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Renew
  Queries the device to get a list of all certificates that require renewal by performing a recursive query at the Renewal characteristic level.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• CertificateHash
  Used in the Renew characteristic to specify the hex-encoded binary blob specifying the SHA-1 hash of the certificate in question.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

Parameters

• ServerName
  The name of the CA server, without scheme (https://, https://).

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Template
  The template name of the certificate to enroll for (User, ClientAuth).

  The default is User.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• ServerPickupPage
  The virtual application root path of the page on the server where the certificate is to be picked up, usually part of the certificate service's Web interface. This path should point to a page that returns a PKCS#7 blob.

  The default is \certsrv\certnew.cer.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• ServerRequestPage
  The virtual application root path of the page on the server to which the Web enrollment request is sent, usually part of the certificate service's Web interface.

  The default is \certsrv\certfnsh.asp.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• UIAccess
  Specifies whether or not the user can modify parameters of the Certificate Type from any UI. The default value is 0.

  0 = user cannot modify Cert Type

  1 = user can modify Cert Type

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• NoSSL
  Specifies whether or not SSL authentication is required. By default, SSL is used and https:// is prepended to the server name.

  0 = Use SSL

  1 = Do not use SSL

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• CertificateTypeFriendlyName
  Specifies the friendly name of the Certificate Type to be used in this operation.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• DesktopProxyServer
  If specified, the engine connects to the desktop proxy, which handles all the required authentication and UI. On the device, the user will see only the initial security prompt.

  If not specified, the user will be prompted to supply credentials on the device and will see "in Progress" and "Results" notifications (if not performing a silent renewal).

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Username
  The username part of the user's domain credentials used to authenticate the user to the certificate service's Web interface. If Username and Password are specified in the XML, the engine will perform the enrollment silently without prompting the user for any information. User@Domain format is accepted for Username, so that the Domain need not be specified separately.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Password
  The password part of the user's domain credentials used to authenticate the user to the certificate service's Web interface. See the Username parameter for more information.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Domain
  The name of the user's domain. See the Username parameter for more information.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• NotificationParam
  The name of the named event to be set if a client wants to be notified of status changes.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• Status
  Returns a textual string indicating the status pertaining to this request type. A set operation with a client-specified status will result in an error.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• OperationHresult
  The final HRESULT of the operation.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• EnrolledCertificateHash
  This is the hex-encoded binary blob specifying the SHA-1 hash of the certificate that was obtained using this operation.

  The following table shows the default settings.

  Permissions	Read Only
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

• RenewCertificateHash
  This is the hex-encoded binary blob specifying the SHA-1 hash of the certificate that needs to be renewed.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser

See Also

Concepts

CertificateEnroller DDF File

Other Resources

CertificateEnroller Configuration Service Provider Examples for OMA Client Provisioning