Secure Sockets Layer (SSL) was a name coined by Netscape who did most of the original work on securing the web. When the protocol was developed further outside of Netscape it was renamed to Transport Layer Security (TLS). The first version of TLS (version 1.0) was an incremental improvement on SSL version 3. (Think of it as a sort-of SSL version 3.1)

For many years SSL v3 and TLS 1.0 lived happily side by side. (SSL v2 was deprecated in 2011). However in 2014 SSL v3 was broken, and it was officially deprecated in June 2015. TLS has also been extended resulting in TLS 1.1,TLS 1.2. and now TLS 1.3.

TLS 1.0 and TLS 1.1 are considered to be less secure and TLS 1.0 is already banned by sites conforming to the PCI standard. Both TLS 1.0 and TLS 1.1 became obsolete in March 2020 as all browser makers removed support for those protocols around that time.

Therefore it is more correct to talk about TLS when talking about secure communications than SSL. Of course the SSL name endures (not least as part of the name of various DLL's etc) but as from NetTalk 9 the term TLS is preferred over SSL.

A Secure site has several benefits:

• You can be sure that the site you are talking to is the real version of that site, and not some spoofed version of the site.
• The packets that travel between the browser and the server are encrypted. This means that no machine along the way can “sniff” the packets to see the information.
• Search Engines (eg Google, Bing etc) are starting to rank secure sites (even information sites) with a higher score than insecure sites.

A secure site uses a Certificate to hold all the relevant information about the site. The Certificate is Signed by a Certificate Authority, which means the certificate is right. Almost all the effort in making a secure site goes into getting the certificates right. Fortunately this only has to be done once, and is simple enough if you follow the directions exactly.  

Some years ago it was acceptable to have a site that was mostly insecure, but then switched to secure when certain sensitive information was required. Today this is less acceptable and should be avoided if possible.

As from NetTalk build 9.24, sessions are no longer shared between secure and insecure parts of a site.

While it is still possible to have a mixed-site approach, internally the two are treated as separate sessions - the data from the insecure session is no longer available to the secure site. This is in accordance with best practices and is enforced in modern browsers.

TLS works by having the server make use of a Certificate. If this certificate is issued by a Certificate Authority (CA) then it is considered to be "trusted". If it is simply generated by the server (known as Self-Signed) then it is considered to be untrusted (and hence less-secure), and a scary warning will appear in the browser. In some cases (but not all) the user is able to click through to the site anyway. Outside of some very narrow use cases Self-Signed certificates are not a good solution.

In order to prove control of the domain the server can perform one of several tasks. These tasks are known as Challenges. Up to NetTalk 14 the only challenge supported was HTTP. This means that the server (or some other program on the server computer) MUST be listening on Port 80. It also limits certificates to those servers that are directly visible to the internet.

NetTalk 14 introduces support for another challenge method - DNS. This method is restricted to cases where your DNS registrar supports an API, but in cases where it does, it allows for providing certificates for LAN servers, and servers where opening port 80 is not an option.  You'll find more information on this new method at Adding Support for DNS Challenge to a WebServer.

NetTalk also adds another option - the option to use an intermediate DNS API server. This adds a layer of protection to you the developer (by not exposing your DNS API credentials to the customer machine.) It is not required to use this, it's a nice-to-have. This is discussed at Getting a Certificate via an API.

1. Open the app in the Clarion IDE and go to the WebServer procedure, to the Window Designer
2. Add a new tab to the sheet control. Call the Tab "Settings"
3. Populate the NetWebServerSettings control template onto the tab [1]
4. Compile and Run.
5. Follow the instructions in Runtime Server Settings below.

1. Go to the WebServer procedure in your app and click on the Extensions button. 
2. Go to the Settings tab of the NetTalk Web Server  object.
3. Set the Host Names [2] for the server as a comma separated list. (You will need a certificate for each host name. [3], [4] ,[7])
   For example;
   'capesoft.com,capesoft.com'
   
4. Set the Listen on Secure Port. The default port for secure servers is 443.
5. Set the Listen on Insecure Port. The default port is 80. (It MUST be 80 to use LetsEncrypt HTTP Challenges). This will redirect all traffic on this port to the secure port. (Worried about port 80? see Port 80 Concerns.)
6. Click Ok, then Ok, then compile and Run.  

[1] Populating control templates can be tricky when the template contains another sheet control. For best results watch the NetTalk User Group Webinar #185, from 0:12 to 0:15.
 
[2] From NetTalk 9 Server Name Indication (SNI) support has been added. This means that the Host Name field can contain multiple values as a comma separated list. For more information about SNI see the section below.

[3] Certificates are located in the certificates subfolder under your exe. There's no template setting for this location, but you can set the s_web._SitesQueue.defaults.CertificatesPath field in the WebServer in the Override Default Server Settings embed point. If you are using the Settings Control template the location can be set at runtime (to anywhere).

[4] Certificates require the .crt and .key files. These must have the same name as the domain, plus the crt or key extension. So for the domain capesoft.com the files capesoft.com.crt and capesoft.com.key should be in the certificates folder.

[5] Runtime settings does not mean you have to use LetsEncrypt certificates. Paid-For certificates can be placed in the certificates folder, and used with Runtime settings with no problems.

[6] Runtime settings does not mean the server has to be secure at all. Using the runtime settings the server can be set up in insecure mode as well.

[7] Certificates can be supplied in many forms. If you get your certificates via some other method, then you need to get it in the correct form, or convert it to the correct form (Google will help with that.) The correct form is CRT and KEY files. The Key can contain a password, or not, as you desire.

You can set the .TLSMethod property in the ThisWebServer.Open method in the WebServer procedure.
Possible values are;

NET:SSLMethodTLS         ! TLS 1.0 or higher
NET:SSLMethodTLS_PCI     ! TLS 1.1 or higher ; from NT 11.26 means TLS 1.2 or higher.
NET:SSLMethodTLSv1       ! TLS 1.0 only
NET:SSLMethodTLSv1_1     ! TLS 1.1 only  
NET:SSLMethodTLSv1_2     ! TLS 1.2 only
NET:SSLMethodTLSv1_3     ! TLS 1.3 only
NET:SSLMethodTLS_MIN1_1  ! TLS 1.1 or higher
NET:SSLMethodTLS_MIN1_2  ! TLS 1.2 or higher ! Default since NetTalk 12.00 
NET:SSLMethodTLS_MIN1_3  ! TLS 1.3 or higher
NET:SSLMethodMaxOnly     ! highest level of TLS only (currently TLS 1.3)

Hint: This property used to be called SSLMethod, and that name still works. Future releases may remove the name though.

The term "TLS" covers a number of encryption schemes which may be implemented by both the server and the client. If the server and client can agree on a scheme, then the conversation goes ahead.

You can test for the schemes supported by your server using the SSLScan tool.

You can download a Windows version of SSLScan from http://code.google.com/p/sslscan-win/.
Some documentation for the SSLScan tool can be found at https://www.mankier.com/1/sslscan

The two tests I recommend running are;

sslscan --no-failed localhost:443

Where localhost and 443 are the server, and port numbers respectively.
This test shows all the Ciphers supported by your server.

For a list of all the ciphers that SSLScan will test, along with the result, use

sslscan localhost:443

The default cipher level will be  TLSv1.x High level ciphers only.

It is possible to have complete control over the cipher list you support. the ThisWebServer.SSLCertificateOptions.CiphersAllowed property is set to a Cipher List.

This property is set in the WebServer procedure, in the INIT method, around priority 3000. It should come just after the generated line that sets the ThisWebServer.SSLCertificateOptions.PrivateKeyFile property.

The Cipher List string is a colon-separated list, where + means include, and ! means exclude. The format of the cipher list is documented at http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT .

The default Cipher List (currently) looks like this;
ThisWebServer.SSLCertificateOptions.CiphersAllowed =
'ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS!RSA'

Note that this default changes from time to time depending on the current best practice. For the best security leave this setting alone, that way when the default is updated your program updates as well (the next time you compile.)

From build 9.18 NetTalk supports ciphers which provide perfect forward security (ECDH). Not all clients support ECDH, and so those clients can fall back on the DH cipher. The DH cipher requires a file called dh2048.pem, which is in your application folder. You need to deploy this file with your application to get the DH cipher.

If the client does not support ECDH and you do not ship dh2048.pem, then they will fall back to using AES (which is still very good.)

Here's an example alternate cipher list;
ThisWebServer.SSLCertificateOptions.CiphersAllowed = 'DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256'
You may need to add more if you want to support older IE11 and Safari releases.

The primary use case for DNS challenges are Intranet servers or servers running on machines that cannot listen on port 80.

As discussed earlier, the HTTP challenge requires port 80 on the server to be open, and for the server to have a Internet IP address (ie a DNS name that resolves to a public IP address.) Intranet servers though cannot get a certificate this way. This results in the server getting a self-signed certificate, which then generates a scary warning when the site is accessed via a browser.

The basic concept to solve this problem (first suggested by Jane Fleming) is to create a regular Domain Name, and to get a certificate for that domain, but have the domain name point to an Intranet IP address.

The domain name itself is not important - it's just a name. It does not need to be related to the client. It DOES need to be registered at a DNS Provider that offers an API, and which is supported by a NetDNS class. (At the time of writing this is limited to DNSimple [1].)

For example, we have a commercial product called EcoTime. So, at DNSimple we've registered EcoTimeLan.Com .

Now for each client we create a different subdomain (something.EcoTimeLan.com), and set the IP address for that domain to the IP of the local Intranet server on the LAN. So, for example, at one of our customers (hulk) our server is installed on a machine with the IP address of 192.168.2.11 . So the domain hulk.ecotimelan.com points to 192.168.2.11 . If you go to that address in your browser, you obviously see nothing (unless you happen to have a server on your LAN on that specific IP address.) BUT, users on the LAN can simply put https://hulk.ecotimelan.com into their browser, and that translates to 192.168.2.11, and hence they get to our intranet server.

So to be clear, the users on the customer site use your (provided to them) name to get to the server.

So we have an intranet server, and we have installed our program on that server, AND we've created a DNS record for that server. The final part of the puzzle is to get the certificate. This is easy to do simply by setting the challenge type to DNS, and filling in some DNS API settings. (There's also a way to skip past the DNS API settings. see Getting a Certificate via an API)

Note 1: The Link includes our affiliate ID. If you DO sign up, we get $5, and you get a $5 credit :), or just go to dnsimple.com ) ).

Another use case are Internet servers, but ones that can't manage HTTP challenges.

If for some reason you have an Internet server, but access to the server over port 80 (to any program running on the server) is unavailable [2], then the DNS Challenge approach can also work. However since this requires that the domain be registered at a supported DNS provider (currently DNSimple) this is more work, and more expensive, to set up. That said, in some cases it may be advantageous to do so.

Note 2: Incidentally browsers still default to HTTP when the user types in a URL. If your NetTalk server is listening on port 80, then it is able to issue a redirect command to the browser, so that the browser switches to HTTPS. If you are not listening on port 80 then the user will just get a "site unavailable" message - and they would need to know to change the URL to start with HTTPS. So a better approach is listening on Port 80. See above if you have Port 80 concerns.

1. Add a NetTalk Object Extension Template to the WebServer procedure.
   Object name should be set to DnsClient.
   Base Class should be set to NetDnsDNSimple.
   On the Settings Tab Use In WebServer should be set ON.
2. Make sure the Settings Control Template is populated on the WebServer window.
   (You may need to re-populate this control template if upgrading from before NetTalk 14).
3. Sign up to a supported DNS Service Provider. Currently DNSimple [3]
4. Register a domain there. (For example EcoTimeLan.Com - well, that's what we registered, you can't have that one.)

Note 3:  This link includes our affiliate ID. If you DO sign up, we get $5, and you get a $5 credit :) 

1. First Set up the DNS Domain, this is done outside your program;
   Go to the DNSimple dashboard in your browser.
   Add a subdomain for your domain, as an identifier to this server (for example hulk.ecotimelan.com). 
   This can be an A (Ipv4) or AAAA(IPv6) entry (to match the protocol your server is using.)
   Set the IP address to the address of the server (LAN addresses are permissible.) For example hulk.EcoTimeLan.com, set to 192.168.2.11
2. In the running server, go to the Settings / Certificates tab, and set the Challenge Method to DNS.
3. In the running server, go to the Settings / DNS tab. Enter your DNSimple User ID and Password here.
4. Once you have entered the User and Password  you can get the Account ID using the lookup button.
   Or enter your Account ID if you know what it is.
5. Set the Root Domain.
   The Root Domain is the domain that you registered earlier (for example EcoTimeLan.Com)
6. On the certificates tab, set the Domains list with the subdomain name (for example hulk.ecotimelan.com).
7. On the certificates tab click the Check / Get Certificates button. (As with all deployments it's suggested you use the Testing Server until the process completes - then switch to the non-testing server once you have verified that the setup is all correct.)

The API server requires Secwin 7 and xFiles 4 to compile. This implies MyTable is required as well. It has ABC Defaults added as well, but this can be dropped if you don't have it.

The documentation for the server is in NetTalk DNS Api Server.

This is covered in the documentation for the DNS API Server above.

A stand-alone API client exists as a testing tool. It is located in \Examples\NetTalk\NetDns\apiClient .

1. Make sure the Settings Control Template is populated on the WebServer window.
   (You may need to re-populate this control template if upgrading from before NetTalk 14).

1. First Set up the DNS Domain, this is done outside your program;
   Go to the DNS API  Server in your browser (this is the DNS API Server you deployed earlier).
   Add a subdomain for your domain, as an identifier to this server (for example hulk.ecotimelan.com). 
   Set the IP address to the address of the server (LAN addresses are permissible.) For example hulk.EcoTimeLan.com, set to 192.168.2.11
2. In the running server at the customer, go to the Settings / Certificates tab, and set the Challenge Method to API.
3. In the running server at the customer, go to the Settings / API Challenge tab. Enter the API Server URL to your DNS API Server here.
   Also set your DNS API User ID and Password here.
4. On the certificates tab, set the Domains list with the subdomain name (for example hulk.ecotimelan.com).
5. On the certificates tab click the Check / Get Certificates button. (As with all deployments it's suggested you use the Testing Server until the process completes - then switch to the non-testing server once you have verified that the setup is all correct.)

Secure sites need a .CRT and a .KEY file. This is usually in the app\certificates folder. If one of these files are missing you'll get this error.

The TLS functionality in NetTalk requires the  LibCrypto-1_1.DLL and LibSsl-1_1.DLL files. These can be found in your application folder or in the \clarion\accessory\bin folder. Copy these two DLL's to your application folder (and include them in your program install.)
You also need to ship CAROOT.PEM and DH2048.PEM.

You may also need to install the Visual Studio 2017 (x86) runtime on the target machine. On most desktop machines this will be installed already, but on Server machines you will most-likely need to install it.

When getting certificates from the LetsEncrypt server the process is logged in the text control on the window. This helps you to see where it might be going wrong. Here are some common messages when the process does not work.

VCRuntime140.DLL Missing

Unable to get certificate - Challenge was invalid