Certificate Enrollment in Windows CE .NET
Marcus Ash, Igor Dvorkin, David Cross, and Maricia Alforque
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)
Using the Enrollment Client Sample
Authenticating the Client
Creating a PKCS #10 Request
Posting the Request
Retrieving the Certificate
Creating an Enrollment Environment
Modifying the ASP Page
Other Enrollment Options
Smart Card Enrollment
For More Information
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.
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:
- Authenticating the client or user.
- Creating a PCKS #10 request.
- Posting the request.
- 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.
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.
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.
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.
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.
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
- Start Platform Builder.
- Create a platform for your Windows CE .NET device.
- Ensure that the following variables are set in the platform:
- Build the platform.
Enroll.exe is included in the flat release directory.
- 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
- Make sure that your device is connected to the network.
- From the Start menu, point to Run.
- 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.
- Type your Windows networking user name, domain, and password, and then choose OK.
To verify the certificate
- From the Start menu, point to Settings, and then choose Control Panel.
- In Control Panel, point to Certificates, and then choose My Certificates.
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:
The following table describes the supported options in the configuration file and specifies the default values of Enroll.exe.
|SERVER||Name of the Internet Information Server (IIS) Web server front end to the certificate authority.||No default value. You must provide the server name.|
|USERNAME||User requesting the certificate (domain\user).||No default value. You must provide the user name in the domain\userName format.|
|PASSWORD||User password.||This is mainly for testing purposes. For security reasons, storing the password is not recommended.|
|CERT_STORE||Name of the CryptoAPI system certificate store where the certificate will be saved.||MY|
|KEY_CONTAINER_NAME||Name of CryptoAPI key container.||No default value. If you do not specify a key container name, the application uses the default unnamed key container.|
|KEY_PROVIDER_NAME||Name of cryptographic service provider to use.||Default PROV_RSA_FULL cryptographic service provider type. In most cases this is the Microsoft Enhanced Cryptographic Provider 1.0.|
|DW_KEY_SPEC||Type of public key to use.
1: Key Exchange
|DW_FLAGS||Hexadecimal flags passed in to CryptGenKey. The only flag that may be of interest is 0x1 (CRYPT_EXPORTABLE). This flag marks the private key as exportable.||0|
|DW_PROV_TYPE||Parameter to CryptAcquireContext specifying the type of cryptographic service provider.||1(PROV_RSA_FULL)|
|CERT_OTHER_ATTRIBS||The certificate Attrib field in the certificate request. This is used to specify the certificate template name. This string must be URL content encoded.
For example, if you want to use ClientAuth certificate template, then the new string is CertificateTemplate%3AClientAuth%0D%0A.
For more information, refer to the Certfnsh.asp page and the Windows 2000 Certificate Services article in Microsoft TechNet.
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:
XXXX is 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:
XXX is 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:
### 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.
The following table describes the other enrollment options:
|Control panel applet||You can use the control panel applet to import a certificate and a private key on your platform. To import it onto a Windows CE device, the private key must be in the Private Key (.pvk) format.
Note that Windows 2000 and Windows XP certificate export wizards do not support the .pvk files. However, Windows 2000 Certificate Services supports the ability to export private keys to a .pvk file through an advanced certificate request. For more information, see the Windows 2000 Certificate Services article in Microsoft TechNet.
|Custom enrollment client||To create a custom enrollment client for other certificate authorities, you can leverage CryptoAPI 2.0 functions and other Enroll.exe functionalities.|
|Smart card||Smart cards provide the flexibility of enrollment from any client device that supports smart cards, such as a desktop PC. You can import a certificate onto Windows CE and keep the associated private key on the smart card. This method provides an extra layer of security and prevents the problem of having multiple copies of the private key when you have exportable keys that you import to Windows CE from a private key file.|
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 about the Microsoft Certificate Server, see the following Microsoft TechNet technical articles: