Background​

The HttpEndpoint can be bound to an SSL certificate but it must be available in the Windows Certificate Store. This howto article describes how to provide a certificate using the win-acme tool and the IIS web server and how to bind the HttpClient to it.

On the Let's Encrypt homepage you can find details on how the client can prove that he has sovereignty over the domain and is entitled to a certificate: https://letsencrypt.org/de/docs/challenge-types/.

The certificate challange must always be performed via port 80. Here the HttpEndpoint with its certificate is bound to SSL port 443, which is why IIS and HttpEndpint can coexist.

Steps​

The procedure is divided into the following steps:
  1. Installation of the win-acme client
  2. Configuration of the IIS web server
  3. Requesting the SSL certificate with the win-acme tool
  4. Checkin the system modifications
  5. Binding of the certificate to the WebHandler

Installation of the win-acme client​

Download the win-acme client from https://www.win-acme.com/. The recommended package not including plugin support is sufficient in this case. Extract the contents of the zip archive to c:\win-acme.

Configuration of the IIS web server​

Make sure that the web server is accessible under the domain name for which the certificate is to be created. For example, if you want to create the certificate for "mydomain.com", start a browser - not on the machine you want to create the certificate on - and navigate to the URL mydomain.com. The browser must display the default page of the server.

Requesting the SSL certificate with the win-acme tool​

The win-acme tool is a interactive command line utility. Start a command line (cmd.exe) with administration privileges and navigate to the directory c:\win-acme. The certificate authority limits the number of certificates that can be issued within a period of time. It is therefore a good idea to start the win-acme client in test mode first, where only a self-signed certificate is created. After all steps for certification were successful, the certification can then be performed without the test mode. The result will be a trusted certificate.
For a better overview the single command line parameters are wrapped and have to be executed as one single line in the command line. Details about the individual options can be found in the win-acme client documentation by running wacs.exe with the command line --help.

wacs.exe --test --verbose --accepttos --closeonfinish --usedefaulttaskuser --setuptaskscheduler
--target manual --host mydomain.com​
--emailaddress yourmailaddress@mydomain.com​
--webroot "C:\inetpub\wwwroot"​

The win-acme tool asks you if the certificate should be renewed and installed. Confirm both with the "y" key.

Checking the system system modifications​

Certificate availability​


The certificate should have been installed in the WebHosting Store. Verify it's existance and remove the certificate thereafter:
  1. Open the Microsoft Management Console mmc.exe with administration privileges.
  2. Select "Add Remove snapin" from the File menu
    step1.PNG
  3. Select the "Certificates" item from the "Available snap-ins" list. Click on "add", select "Computer account" and Next
    step2.PNG
  4. Confirm the selection for the local computer with Finish
    step3.PNG

In the list of certificates select "Web Hosting" and "Certificates You should see the one requested above with the name of the host.

step4.PNG

Scheduled task for renewal​

The win-acme client has set up a task for certificate renewal. You can check this in the Task Scheduler.
The renewal for the test certificate is not needed and the corresponding task can be deleted in the scheduler. After a trusted certificate has been created in the second step, a task for the renewal is also created. This task is started daily to check whether a renewal is pending and, if necessary, performs the renewal.
step5.PNG

Requesting trusted Certificate​

After the certification process runs satisfactorily, you can generate a trusted certificate by running the win-acme client without the "--test" command line option.

Implement the HttpEndpoint​

The binding of the certificate is demonstrated using the example from the HttpEndpont documentation: https://doc.alaska-software.com/content/cls_xppcref_httpendpoint.html

The following modifications are required:
  • Select the default SSL port 443 as port: #define PORT 443
  • Bind the default host with the parameter "*": HttpEndpoint:New( PORT, "*" )
  • The certificate must be bound before the method :start() is called:
    • lOk := oHttpEndpoint:setCertificate( "machine\webhosting\<certificate subject eg. mydomain.com>" )
If port 443 is open in the firewall, then the web handler is accessible with the web browser at https://<mydomain.com>/default.html. The browser must indicate a valid certificate for this server.

Further Readings​

More information about the Let's Encrypt certificate can be found here: https://letsencrypt.org/de/
Using the Let's Encrypt certificate requires knowledge about it's rate limits: https://letsencrypt.org/de/docs/rate-limits/