UPDATE
While most features in LEADTOOLS are backwards-compatible and older how-tos still apply in newer versions, the features discussed in this post have changed significantly in Version 20. Please refer to the following forum post for an updated version of this tutorial:
Overview
HTTPS (HTTP over SSL/TLS) security is a requirement for many web applications. When properly implemented, HTTPS ensures that the traffic received was really sent from the expected endpoint, protecting the client and server. When a web application is secured via HTTPS, all resources, including web services, must also be secure. Fortunately, HTTPS support is practically ubiquitous and most of the plumbing is already in place. However, HTTPS requires a machine-specific certificate, which is why HTTPS is not enabled in the LEADTOOLS Web Scanning Host demonstration by default.
Web Scanning Host
The LEADTOOLS Web Scanning Host bridges the gap between the browser and client’s desktop. TWAIN is a messaging protocol that relies on a window handle as a target. This means that TWAIN scanners are not available in JavaScript or Silverlight. This is an obvious problem for web developers. A WCF service class can be self-hosted and used as a proxy to cross this boundary. The LEADTOOLS Web Scanning Host demonstration is a self-hosted WCF implementation with CORS and HTTPS support.
The project can be found in the LEADTOOLS installation folder: "C:\LEADTOOLS 19\Examples\DotNet\CS\Leadtools.WebScanning.Host"
In addition to the Web Scanning Host demonstration, LEADTOOLS includes a web scanning demonstration with HTML and TypeScript source code. It may be found in this folder: "C:\LEADTOOLS 19\Examples\JS\Documents\ScanningDemo"
Objectives
Enable HTTPS support in the LEADTOOLS Web Scanning Host demonstration application, so the services can be accessed from secure web applications such as Microsoft Dynamics CRM.
Get LEADTOOLS 19
The first step is to install LEADTOOLS and get a development license. If you just want to test without purchasing a development license, you can register to get a time-limited, but fully-functional evaluation development license. Register for the LEADTOOLS Evaluation SDK for Windows to get an evaluation development license emailed to the address you register. The Main Evaluation SDK also includes the projects and LEADTOOLS binaries that are required to complete this project.
Add HTTPS Support to the Host
Adding HTTPS support to the web scanning host does not require any source code changes. To enable HTTPS support, you need to modify the conditional compilation symbols in the project’s build settings to include HTTPS_SUPPORT.
Once HTTPS_SUPPORT has been defined, the next step is to purchase or create an SSL certificate that can be used to encrypt the traffic between the client and service. There are at least three ways to get an SSL certificate, each with pros and cons.
- Create a self-signed certificate to be used as a trusted root certificate and create a host certificate using the trusted self-signed certificate. This is the easiest for developers to do. The drawback is that the certificate is only trusted on the machine the certificate is created. This means that the web application calling the service will only work on that computer. However, for development and internal deployments, it is hard to beat the cost (nothing).
- Create a certificate signed by an internal or domain Certificate Authority (CA). These certificates are usually trusted across the domain, but the IT department might need to be involved and it is possible that your organization does not have an internal CA. Still, each client that will be running the host will need a machine-specific SSL certificate, but it could allow users to share a scanner.
- Purchase an SSL certificate from an external trusted authority such as Symantec (VeriSign), Thawte, or GoDaddy. This has the same benefits as a domain certificate, but does not require a domain certificate authority. The drawback is that this is the most expensive option, which could be prohibitive.
There are many resources on the Internet that explain each of the options described above in more detail. No matter which certificate option chosen, steps 4-7 of the instructions below will be the same.
For the purposes of demonstrating the Web Scanning Host, the steps to create, store, and bind a self-signed certificate follow. The tools used are MakeCert.exe, MMC or CertUtil.exe, and netsh.
- Start an elevated (run as administrator) Visual Studio 2012 (or newer) command prompt. The version of MakeCert.exe is very important as discussed in the "MakeCert Hell" post. As long as a Visual Studio 2012 or new command prompt is used, the MakeCert version will be correct.
-
Use MakeCert.exe to create a self-signed root certificate that can be used as a Certificate Authority.
This will display a message box asking to set a password. Click the None button.^ makecert -sv SignRoot.pvk -cy authority -r signroot.cer ^ -a sha256 -n "CN=Dev Certification Authority" -ss root ^ -sr localmachine -
Use MakeCert.exe to create an endpoint certificate for HTTPS communication. The host name in the certificate must match the host used to call the self-hosted service. In this example, the loopback address of 127.0.0.1 is used as the host name.
^ makecert -iv SignRoot.pvk -ic signroot.cer -a sha256 ^ -cy end -pe -n CN="127.0.0.1" -eku 1.3.6.1.5.5.7.3.1 ^ -ss my -sr localmachine -sky exchange ^ -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 -
Netsh is used to bind the certificate to a specific IP, port, and application. The certificate thumbprint (hash) is used to identify the certificate.
The thumbprint can be manually retrieved by running MMC and adding the certificate add-in for the Local Computer account. Double-click the certificate, go to the Details tab, select Thumbprint, highlight the value and press Ctrl + C to copy.
Alternatively, you can create a simple batch file to use certutil.exe to get the thumbprint:
@echo off for /F "delims=: tokens=2" %%a in ('certutil -store -silent my 127.0.0.1 ^| findstr /B "Cert Hash(sha1):"') do set _hash=%%a set _hash=%_hash: =% echo %_hash% -
An application id is also required by netsh to identify the application. That is the service host’s assembly GUID and can be found in the AssemblyInfo.cs file of the service project.
// The following GUID is for the ID of the typelib // if this project is exposed to COM [assembly: Guid("813dfac6-3868-4e87-87de-f3d7c5572068")] -
Call netsh to bind the certificate for SSL on the correct IP, port, and application.
Replace the certhash and appid with your values. The binding may be verified by running the following command:^ netsh http add sslcert ipport=0.0.0.0:443 ^ certhash=ff9a8ebcaf68797eff36f8ae9b0739a288292f50 ^ appid={813dfac6-3868-4e87-87de-f3d7c5572068}
Put all of these together into a batch file and you have a simple way to create a self-signed certificate and bind it to the IP and application.netsh http show sslcert ipport=0.0.0.0:443
Conclusion
Enabling HTTPS support is an important first step in bridging the gap between secured browser applications such as Dynamics CRM and the desktop. However, HTTPS is not enabled by default because a machine-specific certificate is required to encrypt the connection. Fortunately, the steps required can be done easily and without the need to purchase a certificate.
Support
Need help getting this sample up and going? Contact our support team for free technical support! For pricing or licensing questions, you can contact our sales team (sales@leadtools.com) or call us at 704-332-5532.
