Partager via

SSL Client Authentication (Compact 2013)

  • Article

3/26/2014

Client certificates contain information that identifies the user, as well as information about the organization that issued the certificate. For example, a standard X.509 certificate contains at least the following information:

  • Version
  • Serial number
  • Signature algorithm ID
  • Issuer name
  • Validity period
  • Subject (user) name
  • Subject public key information
  • Signature on the fields just listed

Virtual Root Configuration

It is possible to require or allow a client to provide a certificate during SSL negotiations. Whether to require or allow a client certificate is set on a per-virtual-root basis. The web server will request the web client to send a client certificate, if it has one, if either of the following flags are set as the P parameter of the requested virtual root. For more information, see Virtual Path Registry Settings.

The following code example shows how to set the flags to require or allow SSL client certificates.

HSE_URL_FLAGS_REQUIRE_CERT (0x00000040) Requires SSL client certificates.
HSE_URL_FLAGS_NEGO_CERT (0x00000020)  Allows SSL client certificates.

If the client does not provide a certificate to the web server and HSE_URL_FLAGS_REQUIRE_CERT was set, the request will terminate and an error will be returned to the client. If the HSE_URL_FLAGS_NEGO_CERT was set, but not the HSE_URL_FLAGS_REQUIRE_CERT, then the request will continue.

There are two primary ways to use client certificates on the server. One way is to write an ISAPI extension that uses information in the client certificate to determine information, such as what operations on the extension the user is allowed to perform. In this case, the ISAPI extension maps the user name and permissions allowed for itself. The other way is to use the web server to map client certificates before processing the request further.

Mapping Client Certificate Information to a Web Server User

If the following flag is set in the P value of the virtual root the web server will attempt to match the information in the certificate to a user name upon successfully receiving the SSL client certificate.

HSE_URL_FLAGS_MAP_CERT   0x00000080  // Map SSL cert to user account

By using IIS, the HSE_URL_FLAGS_MAP_CERT flag will map the certificate information to an NT user account. Since Windows Embedded Compact does not have user accounts, this flag will instead map to a web server pseudo-user. This user is then checked against the UserList registry setting for the virtual root that is being accessed, as described in Web Server Access Rights. For information about UserList, see Virtual Path Registry Settings.

Client certificates are mapped to users based on the IssuerCN and/or the certificate's serial number. Web server pseudo users are enumerated in the registry and specified under the website’s SSL\Users key. The name of each registry key under the SSL\Users key specifies the pseudo user's name. The values IssuerCN and SerialNumber under each user name registry entry specify the IssuerCN and SerialNumber of the certificate that must be provided in order to map the user. IssuerCN is a REG_SZ. SerialNumber is a binary entry.

Example of Mapping Client Certificate Information to a Web Server User

The following example shows how to setup a web server registry to require SSL client certificates for a restricted virtual root, create a list of users, and map the certificates to the user name. In this scenario, access is limited to the virtual root /Accounts to the users Alice, Bob, and Carol.

First, the web server is set up to use SSL. The certificate name CE Server Certificate must already be installed in the web server's certificate store. This is the server certificate that the web server sends on all SSL negotiations, not to be confused with the client certificate. It is also assumed that the issuer of the client certificates will have already been set up as a trusted authority in the Windows Embedded Compact trusted or privileged security store.

[HKEY_LOCAL_MACHINE\HTTPD\SSL]
    "IsEnabled"=dword:1
    "CertificateSubject"= "Compact 2013 Server Certificate"

Next, the virtual root /Accounts is set up. A=1 signifies that a user must be authenticated to gain access to resources under this virtual root. P= HSE_URL_FLAGS_EXECUTE | HSE_URL_FLAGS_REQUIRE_CERT | HSE_URL_FLAGS_MAP_CERT | HSE_URL_FLAGS_SSL128. This allows the virtual root resources to be executed (meaning, to run the ISAPI extension), requires the client to send SSL certificates, maps the certificate to a user account, and requires 128 bit encryption. The UserList specifies the users who will be allowed to access this page.

[HKEY_LOCAL_MACHINE\HTTPD\VROOTS\/Accounting/]
    ; ISAPI extension that we're placing restrictions on.
    @="\windows\accounting.dll" 
    "A"=dword:1
    "P"=dword: 0x000001C4
    "UserList"="alice;bob;carol"

Now the three users are listed, as well as the SSL client certificates that will map to them. Alice and Bob were issued their certificates from CompanyIssuer, which is the certificate server for their company. Because the purpose is not to allow access to anyone that has a certificate issued from CompanyIssuer, access is further restricted based on the serial number of the certificate. In Carol's case, AccountingIssuer is more restrictive about to whom certificates will be issued. To avoid entering a different serial number for each user who has a certificate from AccountingIssuer, the serial number is not included in this case.

[HKEY_LOCAL_MACHINE\HTTPD\SSL\USERS\Alice\MAP-1]
    "IssuerCN"="CompanyIssuer"
    "SerialNumber"=hex: 01,02,03,04,00,00,00,00,00,05
[HKEY_LOCAL_MACHINE\HTTPD\SSL\USERS\Bob\MAP-1]
    "IssuerCN"="CompanyIssuer"
    "SerialNumber"=hex: 01,02,03,04,00,00,00,00,00,06
[HKEY_LOCAL_MACHINE\HTTPD\SSL\USERS\Carol\MAP-1]
    "IssuerCN"="AccountingIssuer"

That is all that is needed for the registry.

When a request comes in over SSL to the virtual root /Accounting, the web server will request a client certificate and fail if one is not provided (because HSE_URL_FLAGS_REQUIRE_CERT has been set.)

If the certificate is provided, the web server will run through each of the users and try to match the provided IssuerCN and SerialNumber.

Before accessing Accounting.dll, the web server will verify that the user mapped by the client certificate is present in the UserList. If this is not the case, the web server will return an error, but will not try to perform basic authentication or NTLM authentication on this virtual root, even if these authentications are supported by the web server. If a client certificate is requested for a given virtual root, no other form of authentication will be supported other than mapping that client certificate to the user name as previously described in this section.

Allowing Certificates that Would Otherwise Be Rejected

Before retrieving any information from the client certificate, the web server will first verify that the certificate is valid. To be valid the certificate must have a valid date, be issued from a trusted authority, among other requirements. The web server makes a call to CertGetCertificateChain to make this determination. If there is an error, CertGetCertificateChain will specify an error of the form CERT_TRUST_xxx (CERT_TRUST flags are defined in Wincrypt.h). If the value specified is anything other than CERT_TRUST_NO_ERROR, by default the web server will terminate the request and return an error to the client.

It is possible to override the web server's default rejection of invalid certificates. To enable this, in the base SSL registry key for the website, set the registry value CertTrustOverride to be a DWORD of the CERT_TRUST_ error flags that you are willing to have the web server ignore. The web server will ignore these error codes, and only these error codes.

For example, to have the default website accept a certificate authority that CertGetCertificateChain displays errors on, set (CERT_TRUST_IS_PARTIAL_CHAIN | CERT_TRUST_IS_UNTRUSTED_ROOT) in CertTrustOverride, as shown in the following example.

[HKEY_LOCAL_MACHINE\COMM\HTTPD\SSL]
    CertTrustOverride=dword: 0x00010020
Dn269515.security(en-us,WinEmbedded.80).gifSecurity Note:
We recommended that CertTrustOverride not be modified from the default value, because of security concerns. This functionality is provided for use in scenarios where appropriate certificates cannot be issued.

Notice About Posting Large Amounts of Data When Using Client Certificates

Because of how the SSL protocol works, together with the security policy of the web server, there may be some difficulty posting very large amounts of data to the web server if SSL client certificates are being used in the same request.

The way the web server typically handles large POST requests (even when doing SSL without client certificates) is to read the first PostReadSize size of bytes into a buffer and then stop reading. It is the responsibility of the ISAPI extension to continue to receive more data at this point by making repeated calls to ReadClient. The web server does this to make sure that it never tries to allocate a buffer that is too large and to guard against malicious users who send very large amounts of data to the device to exhausts its resources.

When a request comes into a virtual root using a client certificate, the web server is unaware that it will need a client certificate until after the initial SSL handshake because it will not know what virtual root is being requested until after the handshake is completed. When the web server detects that it needs a client certificate, the web server will request one in the middle of the request. It is possible that the web client will send its client certificate after it has sent greater than PostReadSize amount of bytes. If the web server has not received the SSL client certificate before it reads PostReadSize bytes, it will terminate the request.

To work around this, increase the size of PostReadSize to be the maximum size of the buffer you are willing to accept. As an alternative, you can create a connection to the virtual root that requires client certificates that does not POST data and that does a keepalive. On this connection, the client certificate can be obtained by the web server without having to deal with this issue. On the next request (as long as keepalives are used), there will be no need for the client to resend its certificate and the previous scenario will not be an issue.

See Also

Tasks

Configure a Web Server to use SSL

Concepts

SSL Support
Web Server Permissions