Working with Secure Pages

EO.Pdf HTML to PDF can convert secure pages through secure socket layer (SSL). The default settings should work for most cases. For example, the following code would convert the secure version of Google's home page:

//Convert the secure version of Google's home page. Note the
//"https:" protocol used in the Url
HtmlToPdf.ConvertUrl("https://www.google.com", "result.pdf");

While the default option should work for most occasions, EO.Pdf offers a number of advanced features related to secure site that you may find useful. This section covers the following topics:

SSL and Certificate Basic

SSL stands for secure socket layer. When a Url with "https://" prefix is requested from the server, a SSL connection is established between the server and the client so that the server and the client can exchange data securely. An X509 certificate is required at least on the server side in order to establish a secure connection.

The main purpose of a certificate is to identify the server or the client. For example, a certificate may be issued to "www.google.com". When a browser tries to access "https://www.google.com", that certificate will be presented by the server to the browser. The browser then verifies this certificate. If it verifies successfully, then the browser can be certain that the site loaded is indeed the official Google site, not a malicious imposter. EO.Pdf HTML to PDF converter can perform all the verification steps a browser performs. For example, you can set EO.Pdf HTML to PDF to reject a page if the server's certificate can not be verified.

Similarity, a client can also present a certificate to the server to identify the client to the server. For example, a Web server may be configured to reject all requests unless a client certificate is presented. That way the Web server can be certain that it only servers certain clients. In this case, the client (usually the browser) must be configured to send a valid certificate to the server. Since EO.Pdf HTML to PDF acts like a client browser, it can also be configured to send a valid certificate to the server.

A certificate used in production environment is usually signed by a trusted certificate authority (CA), such as VeriSign. However it is also very common practice to create test self-signed certificate just for testing purpose in a test/development environment. A self-signed certificate can be used to encrypt the communication but cannot be verified against a trusted certificate authority because it wasn't signed by a CA.

When a certificate is signed by a trusted certificate authority, it is usually signed by an "intermediate certificate authority", which in turn is signed by a higher "intermediate certificate authority", this eventually leads to a "root" certificate authority that is a trusted authority by itself and is not signed by another authority. This forms a "chain" from the end certificate to the root certificate. In order for an end certificate to be successfully verified, such a "chain" must be established and each certificate in the chain except for the root certificate must be successfully verified against a higher level of CA. This usually requires all intermediate certificate authorities to be installed on the system. For example, to install a server certificate on IIS, you should install the certificate issued to you as well as all intermediate certificates that forms the chain to your certificates to the root, otherwise IIS may not be able to establish the certificate chain correctly and would cause problems for verifying the certificate.

Verifying Server Certificate with EO.Pdf

By default, EO.Pdf HTML to PDF converter does not verify the server's certificate. For example, you may create a self-signed certificate for testing purpose on your Web server and then use EO.Pdf HTML to PDF to convert a page from that server. That will work fine by default. However, if you use a browser to open the page from that server, the browser will display a warning message similar to this and gives user the option to proceed or not:

The site's security certifiate is not trusted.

EO.Pdf does not display such message because it has no UI and does not interact with user. By default it would ingore this problem and proceed to convert the page.

You can change this behavior by setting SSLVerificationMode property to either SSLVerificationMode.VerifyCertificate or SSLVerificationMode.VerifyHost. The following table listed all possible values:

Option Remarks
SSLVerificationMode.None Does not verify the server's certificate. This is the default option. Use this option if you are using a self-signed certificate just for testing, or security is not a concern for you.
SSLVerificationMode.VerifyCertificate

Verifies the server's certificate with known certificate authorities. In order for this option to work, the Web server must send the whole certificate chain to the client (EO.Pdf HTML to PDF converter). This requires not only the end certificate, but all intermediate certificates in the chain must be properly configured on the Web server (which is usually required anyway for a Web server to support https). If the server's certificate is not signed by a trusted certificate authority, or one of the intermediate certificates is not properly installed on your web server, you may receive the following exception when using this option:

The server's certificate is invalid.

EO.Pdf contains a list of globally trusted root CA certificates that can be used to verify almost all certificates signed by a CA. If your certifcate is not signed by a CA and you wish to use this option, you can add your certificate as a trusted certificate.

SSLVerificationMode.VerifyHost

When SSLVerificationMode is set to SSLVerificationMode.VerifyCertificate, EO.Pdf only verifies whether the certificate has been signed by a certificate authority, it does not check whether the host name matches. For example, if a certificate issued for "www.essentialobjects.com" is used on "www.essentialobjects.net", then a browser would display a warning message like this:

The security certificate presented by this website was issued for a different website's address.

EO.Pdf would ignore this error and proceed with the conversion unless SSLVerificationMode is set to VerifyHost. When it is set to VeriryHost and the host name does not match, you will receive the following exception:

The server certificate's host name does not match the host name used in the Url.

Adding Trusted Certificates

EO.Pdf contains a list of globally trusted root certificates that can be used to verify most certificates. You can extend this list by adding additional certificates as trusted certificates. Use one of the following functions to add more trusted certificates:

Function Remarks
AddLocalTrustedCertificates

Add all trusted certificates in the local machine's certificate store to EO.Pdf's trusted certificates list.

AddMyTrustedCertificates

Add all trusted certificates in the current user's certificate store to EO.Pdf's trusted certificates list.

AddTrustedCertificate

Add a specific certificate to EO.Pdf's trusted certificates list.

You may use a self-signed test certificate on your test Web server but wish to use SSLVerificationMode.VerifyCertificate option to verify the certificate. Because your test certificate can not be verified against any certificate authority, the call would fail. However you can use the following code to add your test certificate to the trusted certificate lists to pass the verification:

//Load the certificate
X509Certificate cert = X509Certificate.CreateFromCertFile("test_certificate.der");

//Add it to EO.Pdf's trusted list
HtmlToPdf.AddTrustedCertificate(cert);

Sending Client Certificate with EO.Pdf

A web server can be configured to either accept or requires a client certificate. If it is set to require a client certificate, then the client (EO.Pdf HTML to PDF converter) must be configured to send a certificate to the server. When a client certificate is not configured but the server requires one, you will receive the following exception message:

403:The server understood the request, but is refusing to fulfill it. This is an error returned by the Web server, not by the HTML to PDF converter. Please try to visit the same Url with your browser to verify whether the Url is valid.

To configure EO.Pdf to send a client certificate, you must have the client certificate saved as a .pfx file in PKCS12 format. A .pfx file contains both the certificate public key and the password protected private key. The following code loads the client certificate and set EO.Pdf to present that certificate to the server when communicating to a secure server:

//Load the client certificate
ClientCertificate cert = new ClientCertificate("your_certificate.pfx", "your_private_key_password");

//Set EO.Pdf to use this client certificate
HtmlToPdf.Options.ClientCertificate = cert;

In order for the client certificate to work successfully, the server must be able to successfully verify this certificate. If the server can not verify the client certificate, you will still receive the 403 error as if the certificate had not been sent to the server at all. To verify whether this is the problem, try to temporarily add the client certificate to the server's "Trusted Root Certificate Authorities" store. If adding the client certificate into the server's "Trusted Root Certificate Authorities" store solves the problem, then it means the certificate has been successfully sent to the server but the server was having problem verifying it. In this case please check whether you have installed all the intermediate certificates in the client certificate's certificate chain on the server.

External Links

You may find the following links useful while working with certificates:

  1. How to: View Certificates with the MMC Snap-in
  2. A Step-by-Step Guide to Advanced Certificate Management
  3. Configuring Server Certificates in IIS 7