HOW TO: Enable HTTPS in the LEADTOOLS Web Scanning Host

• Original Blog Post (v19): https://www.leadtools.com/blog/document-imaging/enable-https-web-scanning-host-demo/
  
• MakeCert Tool (for old post): https://docs.microsoft.com/en-us/windows/desktop/seccrypto/makecert
  
• New-SelfSignedCertificate Cmdlet: https://learn.microsoft.com/en-us/powershell/module/pki/new-selfsignedcertificate?view=windowsserver2022-ps
  
• RFC5280 - X.509 Standard: https://tools.ietf.org/html/rfc5280
  
  • Module Syntax: https://tools.ietf.org/html/rfc5280#appendix-A.2

• 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.

• Step 1: Start an elevated (run as administrator) PowerShell window.
  
  
• Step 2: Use New-SelfSignedCertificate to create a self-signed certificate that can be used as a Certificate Authority:
  Code:

  $ca = New-SelfSignedCertificate -Type Custom -HashAlgorithm sha256 `
      -Subject "CN=Dev Certification Authority" -CertStoreLocation "Cert:\LocalMachine\My" `
      -TextExtension @("2.5.29.19={text}cA=true") -KeyUsage None `
      -FriendlyName "WebScanning HTTPS Authority"

  
  
• Step 3: Copy this certificate into the root certificate store (the cmdlet does not support creating certificates in the root certificate store):
  Code:

  $store = Get-Item -Path Cert:\LocalMachine\Root
  $store.Open("ReadWrite")
  $store.Add($ca)
  $store.Close()

  
  
• Step 4: Use New-SelfSignedCertificate 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 “localhost” (default for the Web Scanning Host project) is used as the host name.
  Code:

  $cert = New-SelfSignedCertificate -Signer $ca -HashAlgorithm sha256 `
      -KeyExportPolicy Exportable -Subject "CN=localhost" -DnsName "localhost" `
      -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1","2.5.29.19={text}cA=false") `
      -CertStoreLocation "Cert:\LocalMachine\My" -KeySpec "KeyExchange" `
      -Provider "Microsoft RSA SChannel Cryptographic Provider" -KeyUsage None `
      -FriendlyName "WebScanning HTTPS Certificate"

• Step 5: Once you have an SSL certificate, you’ll need to bind it to the port used by the Web Scanning Host. This will be performed using netsh. 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 PowerShell script to use Get-Item to get the thumbprint:
  Code:

  $cert = Get-Item Cert:\LocalMachine\My\* | Where Subject -eq "CN=localhost"
  $certhash = $cert.Thumbprint
  Write-Output $certhash
  

  
  
  
• Step 6: 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.
  Code:

  // The following GUID is for the ID of the typelib
  // if this project is exposed to COM
  [assembly: Guid("813dfac6-3868-4e87-87de-f3d7c5572068")]

  
  
• Step 7: Call netsh to bind the certificate for SSL on the correct IP, port, and application:
  Code:

  netsh http add sslcert ipport=0.0.0.0:443 certhash=$certhash "appid=$appid"

  Ensure your thumbnail and project’s GUID are stored in $certhash and $appid respectively.
  
  
• Step 8 (optional): The binding may be verified by running the following command:
  Code:

  netsh http show sslcert ipport=0.0.0.0:443

# 1. Run this as administrator

# 2. Create the authority certificate
$ca = New-SelfSignedCertificate -Type Custom -HashAlgorithm sha256 `
    -Subject "CN=Dev Certification Authority" -CertStoreLocation "Cert:\LocalMachine\My" `
    -TextExtension @("2.5.29.19={text}cA=true") -KeyUsage None `
    -FriendlyName "WebScanning HTTPS Authority"

# 3. Copy to the root certificate store
$store = Get-Item -Path Cert:\LocalMachine\Root
$store.Open("ReadWrite")
$store.Add($ca)
$store.Close()

# 4. Create the endpoint certificate
$cert = New-SelfSignedCertificate -Signer $ca -HashAlgorithm sha256 `
    -KeyExportPolicy Exportable -Subject "CN=localhost" -DnsName "localhost" `
    -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1","2.5.29.19={text}cA=false") `
    -CertStoreLocation "Cert:\LocalMachine\My" -KeySpec "KeyExchange" `
    -Provider "Microsoft RSA SChannel Cryptographic Provider" -KeyUsage None `
    -FriendlyName "WebScanning HTTPS Certificate"

# 5. Get the created certificate (if not already stored in $cert)
If ($cert -eq $null) {
    # Get the list of certificates (order by date)
    $certs = Get-Item Cert:\LocalMachine\My\* | Where Subject -eq "CN=localhost" `
        | Sort NotBefore -Descending
    If ($certs -eq $null -OR $certs.Count -eq 0) {
        Write-Output "Unable to locate certificate"
        Break
    }
    # Take the first entry (most recently created)
    $cert = $certs[0]
}
# 5b. Extract the thumbprint
$certhash = $cert.Thumbprint
# 5c. Log for testing
Write-Output $certhash

# 6. Configure your GUID
$appid = " 813dfac6-3868-4e87-87de-f3d7c5572068"

# 7. Bind to the 443 port
netsh http add sslcert ipport=0.0.0.0:443 certhash=$certhash "appid=$appid"

# 8. Verify the binding
netsh http show sslcert ipport=0.0.0.0:443

Edited by moderator Wednesday, December 27, 2023 1:51:05 PM(UTC)  | Reason: Added FriendlyName to both certificates

Anthony Northrup
Developer Support Engineer
LEAD Technologies, Inc.