Certificate Enrollment in Windows CE .NET

Marcus Ash, Igor Dvorkin, David Cross, and Maricia Alforque
Microsoft Corporation

August 2002

Applies to:
    Microsoft® Windows® CE .NET version 4.0 with Microsoft Platform Builder 4.0

Summary: Learn about the certificate enrollment process and various options for acquiring a digital certificate for public key-based services and applications in Windows CE .NET. (9 printed pages)

Contents

Introduction
Using the Enrollment Client Sample
Authenticating the Client
Creating a PKCS #10 Request
Posting the Request
Retrieving the Certificate
Creating an Enrollment Environment
Configuring Enroll.exe
Modifying the ASP Page
Other Enrollment Options
Smart Card Enrollment
For More Information

Introduction

Microsoft® Windows® CE public key-based services and applications require a digital certificate. This certificate and its associated private key establish a trusted identity for an entity using the public key-based services and applications. Certificate enrollment involves a client and a certificate authority. The client is responsible for initiating the enrollment request and with providing all the necessary information to the certificate authority. The certificate authority is responsible for validating the request and issuing a certificate.

Using the Enrollment Client Sample

Windows CE .NET provides a code sample that illustrates the client role for certificate enrollment. The sample is used to obtain a certificate for a Windows CE device from a Microsoft Windows 2000 or Windows Server 2003 with Web enrollment support installed. For the sample, the certificate authority is a Windows 2000 Certificate Server. The client sample is Enroll.exe and it is located in the %_WINCEROOT%\Public\Common\SDK\Samples\Enroll directory.

For more information about the Microsoft Certificate Server, see Windows 2000 Certificate Services and Step-by-Step Guide to Setting up a Certificate Authority technical articles in Microsoft TechNet.

The enrollment process between the client, the sample, Enroll.exe, and the certificate authority, Windows 2000 Certificate Server, involves the following steps:

1. Authenticating the client or user.
2. Creating a PCKS #10 request.
3. Posting the request.
4. Retrieving the certificate.

In a Windows desktop environment, Microsoft Certificate Services provide a set of customizable active server pages (ASP) to handle the various stages of certificate enrollment. Most of these pages communicate with a Windows desktop client through the Certificate Enrollment Control. The Certificate Enrollment Control is a Microsoft ActiveX® control that handles all of the client side operations in an enrollment scenario. The ASP pages combined with the Certificate Enrollment Control provide an Internet browser-based enrollment sample. However, many Windows CE devices do not have a browser and still require certificate enrollment capabilities. Because of that constraint, the Enroll.exe sample provides the capability for enrollment in an environment that does not include a fully functional browser.

Note   Windows CE platform does not contain the Xenroll.dll, therefore it does not support the Icenroll interface available on the standard Windows platform.

The Windows CE enrollment scheme is based on standard Internet and Internet Engineering Task Force (IETF) protocols and can interact with the Windows 2000 Certificate Server without requiring added customization of the supplied templates and sample ASP pages. The following diagram illustrates the basic architecture and components for the enrollment sample included in Windows CE .NET.

Figure 1.

Authenticating the Client

Before a client can request a certificate, the client must be authenticated. Internet Information Server (IIS) authenticates the client by impersonating the client to the Microsoft Certificate Server and prevents anonymous access to the Certificate Server Web Enrollment pages. If the user credentials are not stored in the Windows CE client through the Credential Manager, the server prompts the client for credentials. You can also specify the user credentials in the enrollment configuration file, Enroll.cfg. For more information on enrollment configuration options, see the Configuring Enroll.exe topic.

Creating a PKCS #10 Request

Next, Enroll.exe creates a base64-encoded PKCS #10 certificate request message and sends it to the Windows 2000 Certificate Server. The Windows CE enrollment client generates a public and private key pair if one does not already exist. Then the client generates and signs a PKCS #10 certificate request using the private key.

The PKCS #10 certificate request contains the following information:

• Subject Name. This name is often a placeholder, because a Microsoft enterprise certificate authority will populate the subjectname and subaltname information automatically based on the credentials of the authenticated user and the information stored in the Active Directory. When using a standalone certificate authority, you must specify the subject information in the request and manually validate this information.
• User public key. This public key corresponds to the requestor's private key.

To simplify the enrollment process, Microsoft Certificate Services supports Active Directory-based certificate templates that reduce the amount of information a user has to provide. Instead of filling out a number of fields and specifying several parameters, the user can use a template that specifies most of the parameters required for a certificate. Various default templates include certificates for Client Authentication, Server Authentication, and Code Signing. The user selects the desired certificate template and the enrollment options available in the enrollment configuration file.

For more information about the default templates, see the Windows 2000 Certificate Services article in Microsoft TechNet.

Posting the Request

The enrollment client posts the request over HTTP to the Certfnsh.asp page. IIS acts as the registration authority to the certificate authority to enable Web-enrollment methods. IIS uses CertCli.dll, a Windows 2000 Certificate Server component, to submit the request to the certificate services on behalf of the authenticating user. Note that Enroll.exe specifically uses the Certfnsh.asp page to post the request. Enroll.exe behaves as if the default sample ASP pages were not modified. If you modify the default ASP pages, see the Modifying the ASP Pages topic.

Retrieving the Certificate

When the certificate authority has successfully processed the request and the certificate has been issued, the certificate request ID is returned to the client. The client posts a message to the Windows 2000 Certificate Server that includes the request ID for the certificate and the encoding type. This is specified by the CERT_PICKUP_TEMPLATE option in the enrollment configuration file and can be modified if the default page layout is changed.

Then the certificate is encoded and transmitted to the client over HTTP. On the client-side, Enroll.exe loads the certificate in the store specified in the enrollment configuration file; by default this is the "My Certificates" store. The certificate is associated with its private key by setting the CRYPT_KEY_PROV_INFO certificate property. Any certificate-aware application can now access this certificate from the store.

Note that Enroll.exe does not handle PKCS #7 messages. Individual certificates are retrieved from the Windows 2000 Certificate Server and do not include the issuer certificates packaged in a PKCS #7 message. However, you can add code to Enroll.exe to support PKCS #7 messages. Also, you can manually add the issuer certificates into the appropriate store using CryptoAPI 2.0 functions or using the certificate control panel applet provided in Platform Builder.

Creating an Enrollment Environment

To create an enrollment environment between your Windows CE device and a Windows 2000 Certificate Server, complete the following setup. The setup makes these assumptions:

• You have a default Windows 2000 Certificate Server already configured. For more information, see Step-by-Step Guide to Setting up a Certificate Authority technical article in Microsoft TechNet.
• You have not changed the Enroll.exe sample.
• You have specified the correct configuration options in the Enroll.cfg file.

To prepare a Windows CE device for enrollment

1. Start Platform Builder.

2. Create a platform for your Windows CE .NET device.

3. Ensure that the following variables are set in the platform:

   • SYSGEN_WININET
   • SYSGEN_AUTH_NTLM

4. Build the platform.

   Enroll.exe is included in the flat release directory.

5. Download the platform and the Enroll.exe to your Windows CE device.

You are now ready to obtain a certificate for the Windows CE device.

To obtain a certificate

1. Make sure that your device is connected to the network.

2. From the Start menu, point to Run.

3. In the Run dialog box, type enroll -s<name>, where <name> is the name of a certificate server on the Windows XP network, and then choose OK.

   If the Windows CE client does not have the user credentials stored, a Windows logon dialog box appears. The -s option with Enroll.exe causes the application to ignore the configuration file.

   You can use the -f option with Enroll.exe if you want to use the configuration values specified in Enroll.cfg file. Make sure that you specified the correct configuration options.

4. Type your Windows networking user name, domain, and password, and then choose OK.

To verify the certificate

1. From the Start menu, point to Settings, and then choose Control Panel.
2. In Control Panel, point to Certificates, and then choose My Certificates.

Configuring Enroll.exe

Several details of the enrollment can be configured without modifying the source code of Enroll.exe. These options are specified in a configuration file, Enroll.cfg, which is passed as a command line parameter to Enroll.exe.

The following command line causes Enroll.exe to read its settings from the text file Enroll.cfg:

Enroll.exe –fenroll.cfg

The following table describes the supported options in the configuration file and specifies the default values of Enroll.exe.

Modifying the ASP Page

If you modify the default location of Certfnsh.asp page, you must specify the new location through the CERT_REQ_PAGE option in the enrollment configuration file. By default, Enroll.exe expects Windows 2000 Certificate Server to provide Certfnsh.asp. The following code shows the default Enroll.exe certificate request:

?TargetStoreFlags=0&Mode=newreq&SaveCert=yes&CertRequest=XXXX&CertAttrib=
  CertificateTemplate%3AUserSignature%0D%0A

TheXXXXis the base64 URL encoded certificate request.

Enroll.exe expects Certfnsh.asp to display a page containing the request number to pickup the issued certificate. The following example shows the default text in the Web page returned by Certfnsh.asp:

certnew.cer?XXX=###&XXX

TheXXXis any variable length text and ### is the certificate request ID passed to CERT_PICKUP_TEMPLATE.

If you modify Certfnsh.asp, you must change the BuildPutRequest and ParseWebPageToFindReqNo functions in Crypt_web.cpp to match the changes. The Crypt_web.cpp file is located in the %_WINCEROOT%\Public\Common\SDK\Samples\Enroll directory.

If you change the default location of Certnew.cer, you must specify the new location through the CERT_PICKUP_TEMPLATE option in the enrollment configuration file. By default, Enroll.exe expects Windows 2000 Certificate Server to provide Certnew.cer. The following example shows the default request to pickup the certificate:

?ReqId=###&Enc=b64

The###is the certificate request ID returned from Certfnsh.asp. Enroll.exe expects a valid base64 encoded certificate.

If you modify Certnew.cer, you must change the GetCertFromWebBrowser function in Crypt_web.cpp to match the changes.

Other Enrollment Options

The following table describes the other enrollment options:

Smart Card Enrollment

A certificate solution based on smart cards requires a Windows CE Cryptographic Service Provider (CSP) for the specific type of smart card. A typical smart card CSP fulfills the following requirements:

• Exposes a CSP interface compatible with the Microsoft RSA provider (RSAENH.DLL).
• Uses the smart card to save private keys securely.
• Uses the smart card to perform private key operations such as key exchange and digital signing.
• Restricts access to private key operations with a user-supplied PIN.
• Optionally, saves the user certificate on the smart card, by implementing the KP_CERTIFICATE key property. This capability allows the smart card to be used on a different machine.

Smart card certificate enrolment can be done from either a Windows-based desktop PC or a Windows CE device using a tool like Enroll.exe. You should save the certificate to the smart card if possible. On first use, the Windows CE device should extract the certificates stored on the smart card and saves them to the local system store for use by applications. The Windows CE certificate control panel applet is capable of performing this step.

For More Information

For more information about the Microsoft Certificate Server, see the following Microsoft TechNet technical articles:

• Windows 2000 Certificate Services
• Step-by-Step Guide to Setting up a Certificate Authority
• Microsoft Windows 2000 Public Key Infrastructure Introduction
• Planning Your Public Key Infrastructure