CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
SSL
CapeSoft Logo

CapeSoft NetTalk
Building Secure Web Sites

Download Latest Version
Installed Version Latest Version

NetTalk WebServer - Building Secure Web Sites

TLS Broken after upgrading to NetTalk 7.11 or later? see Troubleshooting and Common Errors

Introduction

When dealing with sensitive information, it is recommended that the web site you create be made “Secure”. 

TLS or SSL

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 and TLS 1.2.

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.

Why Secure?

A Secure site has several benefits:
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.  

Mixing Secure and Insecure?

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

Cost

Getting a Certificate Authority (such as Verisign, Thwate or Godaddy)  to sign your certificate costs money. Worse, since certificates expire it’s an ongoing annual cost.

If you have a “public” web site, where you are wanting to attract people from everywhere, then you have no choice but to get your certificate signed by an approved authority.

If you have an intranet site though, where you are working within a known network, then you can turn yourself into a Certificate Authority on that network. It’s a bit of work, but only has to be done once (per machine).

Almost always you’ll start off by using yourself as a certificate authority, and then only later get a certificate from a Certificate Authority.

If you are going to be using a certificate from a certificate authority then go to the section Getting a Paid-For Certificate now.

Making Yourself into a Certificate Authority

In order to be an Authority you need to make a CA certificate. This certificate is going to form the “top of the tree” for all the other certificates you produce. You only need to do this once, regardless of how many certificates you create later.

This process is not complicated if you follow the directions carefully, but as with most security related things, mistakes can lead to weird behavior.

  1. Open Windows Explorer. Go to the \clarion\accessory\bin\MakeCertificates folder.
  2. Run the batch file : CreateCACertificate.Bat
  3. Press any key to start the process.
  4. Enter pass phrase for .\YourCARoot\private\YourCA.key:
    This is your magic password that will allow you to create certificates based on this CA Certificate. Think about it. Make something up. Then write it in a safe place. Forget this and you’ll need to start over. Once you’ve thought of something enter it here
  5. Verifying - Enter pass phrase for .\YourCARoot\private\YourCA.key:
    Since you can’t see it when you type it, you’ll need to type it in again here.
  6. Enter pass phrase for .\YourCARoot\private\YourCA.key:
    Then you enter it again (this time it’s being used.) Now you start entering information that will be included (and visible) in your certificate. This information helps people decide if the certificate is legitimate or not.
  7. Country Name (2 letter code) [US]:
    Country Code : Enter your 2 letter country code. For example;
    United States : US
    South Africa : ZA
    Germany : DE
    and so on.
  8. State or Province Name (full name) [Some-State]:
    Enter your state or province name here.
  9. Locality Name (e.g., city) []:
    Enter your locality here. This is typically the name of city closest to you.
  10. Organization Name (e.g., company) [Internet Widgits Pty Ltd]:
    This is the name that will appear on the Certificate. The user will see something like “Do you want to trust content from xxxxx”. And remember this is the CA certificate, not a product certificate. So set the name to something useful that isn’t product related.
  11.  Organizational Unit Name (e.g., section) []:
    If you’re that big then you can enter something here. If you don't have organizational units then you can leave this blank.
  12. Common Name (For Web Certificates use URL (e.g. www.example.com) otherwise YOUR name) []:
    This is just the CA certificate, so this item isn’t as important as it is later on. However you want your certificate to be as “believable” as possible. You can enter anything here, but I recommend adding your web site address.
  13. Email address []: Putting a real email in here allows people to verify your certificate if they want to. Again, you want to make the certificate as trustworthy as possible, so putting in a real email is a good thing.
  14. Press any key to end the batch file.

And voila, your certificate is created in the YourCAroot folder. This certificate is in 2 parts.

Part 1

A file has been created in the \clarion\accessory\bin\MakeCertificates\YourCARoot\private\ folder and is called YourCA.Key

If you open this file using a text editor you'll see it looks something like this

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,6AAD7D6884ADEFD0

I3RXbET0QhlBxNfCh8jvR3PMAnsK7EVcbirJKJCcZ4V4iNIzofFC4/9TQ+GBuUzw
<lots of encrypted stuff here>
 Nu0ME/TcfcMP2NoCejYnsH/mEyxnO+YBT3NNkOybIFvEwgYvvJfG7uswUJL0pCLI
-----END RSA PRIVATE KEY-----


As you can see this is a Private Key. Private Keys are important in the security chain and you need to keep them Private.

Part 2

Another file has been created in the \clarion\accessory\bin\MakeCertificates\YourCARoot\cacert\ folder and is called YourCA.Crt Opening this file in a text editor reveals something like this

-----BEGIN CERTIFICATE----- MIIEoTCCA4mgAwIBAgIJANGGW6IMdDACMA0GCSqGSIb3DQEBBQUAMIGRMQswCQYD
<lots of encrypted stuff here>
V1Y6QVKSM2wxBXlfKDbUIRbxUdDl/dIa+4JEPgek3zpMCL6cmQ==
-----END CERTIFICATE-----

Tip: Resist the urge to rename these files here – you’ll be able to rename them later before you ship your app. But if you rename them here you’ll break the rest of the batch files.

Adding Yourself as a Certificate Authority in the Browser

If you want to add yourself as a certificate authority on a specific client machine then you can follow these steps. Since this has to be done for each client, this is only a useful thing to do if you are in a LAN context, and you have a small (and specific) number of machines that will connect to your server.

this section makes use of the root certificate you created in the section Making yourself into a certificate authority.

Chrome

  1. Select the "Hamburger" menu icon on the top right corner of the screen.
  2. Choose Settings.
  3. Scroll to the bottom of the settings and click on Show Advanced Settings.
  4. Scroll down to the HTTPS/SSL section and click on the Manage Certificates button.
  5. Go to the Trusted Root Certification Authorities tab, and click on the Import button.
  6. Follow the wizard. To specify the file to import, navigate to the YourCA.crt file you created earlier (usually in \clarion\accessory\bin\MakeCertificates\YourCARoot\cacert\) and select the YourCA.CRT file there for import. Then click Next.
  7. Select the Place all certificates in the following store radio option, and make sure the store is set to Trusted Root Certification Authorities. Then click Next.
  8. Click on the Finish button to complete the import.

Firefox

  1. Select the "Hamburger" menu icon on the top right corner of the screen.
  2. Choose Options.
  3. From the tab list on the left, choose Advanced.
  4. Select the Certificates Tab.
  5. Click on the View Certificates button.
  6. Go to the Authorities tab.
  7. Click on the Import button.
  8. navigate to the YourCA.crt file you created earlier (usually in \clarion\accessory\bin\MakeCertificates\YourCARoot\cacert\) and select the YourCA.CRT file there for import.
  9. Select the uses to trust this CA. Usually it will only be for identifying websites, unless you plan to use the CA for other purposes as well. Then click on the OK button.

IE

  1. Select the "Gears" menu icon on the top right corner of the screen.
  2. Select Internet Options.
  3. Select the Content tab
  4. Click on the Certificates button
  5. Go to the Trusted Root Certification Authorities tab, and click on the Import button.
  6. Follow the wizard. To specify the file to import, navigate to the YourCA.crt file you created earlier (usually in \clarion\accessory\bin\MakeCertificates\YourCARoot\cacert\) and select the YourCA.CRT file there for import. Then click Next.
  7. Select the Place all certificates in the following store radio option, and make sure the store is set to Trusted Root Certification Authorities. Then click Next.
  8. Click on the Finish button to complete the import.

Creating a Certificate for your program, with yourself as the Certificate Authority

Note that before you can do this step, you must have completed the steps laid out in the section above Making Yourself into a Certificate Authority.

  1. Open Windows Explorer. Go to the \clarion\accessory\bin\MakeCertificates folder
  2. Run the batch file : CreateSelfSignedCertificate.Bat
  3. Press any key to start the process
  4. Country Name (2 letter code) [US]:
    Enter your 2 letter country code.
  5. State or Province Name (full name) [Some-State]:
    Enter your state or province name here.
  6. Locality Name (e.g., city) []:
    Usually a city name.
  7. Organization Name (e.g., company) [Internet Widgits Pty Ltd]:
    The company name that will appear on the Certificate.
  8. Organizational Unit Name (e.g., section) []:
    Since this certificate will be associated with a product, you may want to put some sort of product related name in here. Or leave it blank.
  9. Common Name (For Web Certificates use URL (e.g. www.example.com) otherise YOUR name) []:
    Ok, now this is very important. Let’s pause for just a second to consider this one in some detail.

When a browser accesses a secure site, the user will enter some URL to get there. For example to get to the CapeSoft web site they enter www.capesoft.com.

If that site is a secure site, then one of the checks is that the name they entered matches the name in the certificate. So if they entered www.kapesoft.com but ended up at a secure site that had a certificate issued for www.capesoft.com then they’ll see a warning.

Now, if the program you are making will appear on the internet, then entering this field is easy. Just enter the URL of the site as the user will enter it, and move on to step number 10.

If you are making an Intranet site though, which might be running on an internal server, then things get harder. You could enter the name of the machine. For example, say the name of the _server machine_ is Hobbes. Then users on that intranet will access the site as https://hobbes . So you can enter Hobbes in the certificate at this point.

But what if you don’t know what the machine will be called? One option is to find out when you deploy, and generate a certificate for that specific machine, with that specific machine name. Of course this would mean generating a different certificate for pretty much all your deployed servers, because it's unlikely all your customers will be serving this from a machine with the same name.

An alternative you could set an entry in the HOSTS file on each workstation on the LAN. This way you can associate some name (which is fixed for all your installs) with an IP address on the LAN. This works well for sites with a small number of workstations, and where the workstations are Desktop machines (ie machines where you can add items to the HOSTS file.)

If you cannot do with of these, the user will see a warning each time they use the site, which they can get past by clicking on “yes”.

For an intranet, there’s no perfect solution here. Anyway, go ahead and enter something for the Common Name.

Tip: If you use a * as the first part of the common name, for example *.capesoft.com then you will be able to host multiple, secure, sites on the same server. These sites would then be differentiated by the first name - for example;
admin.capesoft.com 
www.capesoft.com

blogs.capesoft.com

and so on.

  1. Email Address []:
    Putting a real email in here allows people to verify your certificate if they want to. Again, you want to make the certificate as trustworthy as possible, so putting in a real email is a good thing.
  2. Enter A Challenge Password for this certificate.
  3. Enter an optional Company Name for this certificate.
  4. Enter pass phrase for ./YourCARoot/private/YourCA.key:
    The batch file is now using your Private Key that you created earlier. Notice that it's using the name, as it was created, so that's why renaming the file would not be a good idea. This is the password you set in step 4 of the Making Yourself into a Certificate Authority section above.
  5. Press any key to end the process.

Files Created

If you now look in the \clarion\accessory\bin\MakeCertificates\YourCARoot\certs folder there is a new file Demo.crt

If you look in Demo.Crt using a text editor you'll see something like this;

-----BEGIN CERTIFICATE-----
MIIEoTCCA4mgAwIBAgIJANGGW6IMdDACMA0GCSqGSIb3DQEBBQUAMIGRMQswCQYD
V1Y6QVKSM2wxBXlfKDbUIRbxUdDl/dIa+4JEPgek3zpMCL6cmQ==
-----END CERTIFICATE-----


In the \clarion\accessory\bin\MakeCertificates\YourCARoot\private\ folder there is also a new file Demo.Key. Inside this key file is something like this;

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAvob64lPrLT3caekb9UCtCPpinP3AvPhNzqjlAR59/XDwNO1d
b0IYspkAxQCLFf4DHKGHrjInLinooJankgx88CbgCNOhDkocf8bcGw==
-----END RSA PRIVATE KEY-----

As before this is the private part of the key, and it must be looked after.

Renaming

Now is a good time to rename these certificates. We’ll copy them from here to the application directory in a moment, but before we do so we’ll rename them.

Note: We DON’T want to rename the CA certificate. Leave that alone.

In the \clarion\accessory\bin\MakeCertificates\YourCARoot\certs  folder rename Demo.Crt to Product.Crt, where Product is some name related to your application. For the examples I’ve renamed mine to Settings.Crt (we won’t need the SignedDemo.crt one, so you can leave that alone for now.)

In the \clarion\accessory\bin\MakeCertificates\YourCARoot\private folder rename Demo.Key to Product.Key, where Product is the same name you used for the Crt file. For the example I’ve renamed mine to Settings.Key

Tip: In your NetTalk web server program you will need to enter the names of your certificate and private key in the WebServer procedure, on the security tab. The names you enter there needs to match the names you called the file here. In the examples this is set to 'certificates\settings.crt' and  'certificates\settings.key' - Certificates being the Folder part where the certificate is stored, and Settings.crt being the name part. This name is relative to the application folder, not the web folder.

Tip: If you install the YourCA.Crt file into Internet Explorer (or any other browser) as a "Trusted Root Certification Authority" then the browser will stop complaining that the certificate is issued by an untrusted source. Obviously this approach is not possible if you are creating a site for the world at large, but it is possible when creating intranet applications.    

Copying the Certificate to your application folders

  1. Use Windows explorer now to open your application directory.
  2. Change to  your application directory.
  3. If there isn’t a Certificates (i.e. \app\certificates) folder then make one there.
  4. Into this folder copy 2 files;
    \clarion\accessory\bin\MakeCertificates\YourCARoot\private\Product.key where Product is the name of the file you created in the section above and
    \clarion\accessory\bin\MakeCertificates\YourCARoot\certs\Product.Crt where Product is the name of the file you created in the section above.   

Changing your Application so that the Server is a Secure Server

  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 Port Number for your secure server. The default port for secure servers is 443.
  4. Go to the Security tab.
  5. Tick on Use TLS to make server secure.
  6. Set the name of the certificate to use. This is the name of the CRT file that you either purchased, or created earlier. Typically it is named for the site you are serving.

    In the example these files are in the \certificates folder. In the example, the name of this file is Settings.Crt.  So in this setting on the template there is 'certificates\settings.crt'. Notice the path is relative to the application  folder. If your file is called say www.capesoft.com.crt then you would enter 'certificates\www.capesoft.com.crt'
  7. Set the name of the key file to use. This typically matches the name of the CRT file (used above) except with the extension key.
  8. Click Ok, then Ok, then compile and Run.  
Note that from NetTalk 9 Server Name Indication (SNI) support has been added. This means that the certificate and key fields can contain multiple values as a comma separated list. For more information about SNI see the section below.

Calling your secure server from your browser

When accessing a site from your browser you usually use the form
http://127.0.0.1:88
where 127.0.0.1 is the name of the server, and 88 is the port it is running on. 

To access Secure servers you must use the HTTPS protocol. For the example, running on port 881, this is
https://127.0.0.1:881

What happens in your browser

When your app runs in the client’s browser 3 checks are done on the certificate, and three warnings may appear.

Internet Explorer

In IE the warning window looks something like this:

Simply clicking YES will allow the site to continue. However the next time IE is run the same error will appear.

In order to make this warning go away you need to register the Certificate on this computer.

Tip: Had we used a Signed Certificate, which was called DemoSigned in the steps earlier, then the next bit will not work. If the Certificate is signed the we have to install the CA Certificate, which I’ll describe a bit later.

If you want to permanently accept this certificate, then click on the View Certificate button.

Click on Install Certificate.

You’ll get the Certificate Import Wizard.

You can accept all the default options and click on the Finish button.

Since this is an unsigned certificate You’ll get a security warning. Click Ok.

Close the windows back to the original Security Alert, and click on Yes.  

Firefox

In Firefox the error looks something like this:

If you click on Accept This Certificate Permanently then you won’t see this error again for this certificate. For FireFox it is not necessary to install the CA Certificate.   

But wait, there’s more (problems)

When we created the certificate we spoke about the Common Name for that certificate. You had to set the common name to something, preferably the machine name, or IP address of the machine.

In the examples I’ve set the name of the machine to Hobbes, which happens to be the name of my machine. It’s extremely unlikely your machine is called Hobbes. So if you run the TLS example on your computer you’ll also see another error when you open the site in your browser. 

In Internet Explorer the Error looks like this:

 In Firefox like this:

There’s no real way to suppress these errors simply because that’s the whole point of the certificate in the first place.  If you are accessing a secure site you must do so in the way which the certificate has specified.

In IE clicking on Yes, and in Firefox clicking on OK bypasses the error and you move on. 

The only real solution is to generate a certificate that matches the name of the machine. If you are deploying commercial apps this means probably generating a different certificate for each site. 

Getting a Paid-For certificate

If you are creating a public web site, then clearly having all these warnings pop up is unacceptable.  In that case you need to have your certificate signed by a Trusted Certificate Authority. This process usually takes a day or two as the CA is supposed to verify that you are who you claim to be. The process can however take several weeks, so make sure you get the certificate in good time.

There are several authorities you can use; www.verisign.com the biggest, but not surprisingly also the most expensive. www.thwate.com  is the next biggest, is owned by Verisign, and is quite a bit cheaper. c. Another popular one is www.godaddy.com  which is cheaper still.  For Clarion-centric apps, Lindersoft have partnered with Comodo.

All three follow a similar process.

  1.  You create a Certificate Signing Request (CSR)
  2. They take your money, and sign your CSR
  3. They give you back a Certificate which
  4. You put into a CRT file.

If you think this sounds like a lot of money for very little work, well, you’d be right. However these CA’s have their CA certificates already inside IE and Firefox and others, so that’s what makes them valuable.  

Create Certificate Signing Request

To help you create a CSR we’ve made a batch file called CreateCertificateSigningRequest which you’ll find in your \clarion\accessory\bin\MakeCertificates folder. 

  1.  Open Windows Explorer. Go to the \clarion\accessory\bin\MakeCertificates folder
  2.  Run the batch file : CreateCertificateSigningRequest.Bat

    a. Press any key to start the process

    b. Country Code : Enter your 2 letter country code.

    c. State or Province: Enter your state or province name here.

    d. Locality: Usually a city name.

    e. Organization name: This is the name that will appear on the Certificate.

    f. Organizational Unit Name: If you’re that big then you can enter something here.

    g. Common Name: this is the URL that people will use to access your web site. For example www.capesoft.com . If you are purchasing a wildcard certificate then the common name is something like *.capesoft.com .

    h. Email address: Putting a real email in here allows people to verify your certificate if they want to. You want to make the certificate as trustworthy as possible, so putting in a real email is a good thing.

    i. Challenge password: when the CA contact you, possibly by phone, they will use this password to make sure you are the person who submitted the request. Use something simple, and make a note of what it is because you’ll need to provide it later on.

    j. Optional Company name: Put in a company name if you like.

    k. Press any key to end the process.

This has created a file called ForRealCSR.CRT in the certs folder. Go ahead and open it in Notepad. It’ll look something like this;

-----BEGIN CERTIFICATE REQUEST-----
MIIC8jCCAdoCAQAwgYExCzAJBgNVBAYTAlpBMRUwEwYDVQQIEwxXZXN0ZXJuIENh cGUxEjAQBgNVBAcTCUNhcGUgdG93bjERMA8GA1UEChMIQ2FwZXNvZnQxEDAOBgNV BAsTB3Rlc3RpbmcxDzANBgNVBAMTBmhvYmJlczERMA8GCSqGSIb3DQEJARYCYWEw ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDQRS99ub9W6foSfKYYhl9S 7f36OADRoannYysfCVv04fEkhLtgmmZg5M1dlDS3MD4vf4whhpFdZ26R/Ty2mtJI lM+t/13YC03vLZ2UWRsuinI9/BQY8OMAQkr+qGh74Sg2UkJI2usd0H2Ly3d8L1x9 HbRNOvxc83ZatXjWMEZjeps6EoVcW7VYuFARQYZ+iToZYO8oRcOCl7rmvyjJJL3P Y5lTg1rND+hKo/QL2eVUfZIdha+Z9aX21kLu9UwzNqwWV9JMoMoLlEOn/GT2zRxI oY8/2wAg5yXbVcrCw2fSEgctAYEFw6RFGAQc0icVdGaezrTnvdSAts3enk7Roewx AgMBAAGgKzATBgkqhkiG9w0BCQIxBhMEY2FwZTAUBgkqhkiG9w0BCQcxBxMFaGVs bG8wDQYJKoZIhvcNAQEFBQADggEBALUo3jKd7l1TBVcBEADWvgSj+pcvWjlCLfkk y33EzAvaFYJpRRzY6bKqFws7mEmahM9eynmIwnYWYx4budTIJvNsNOPe8+Vo8VVP 6aE5n+z/Jbp8NslmzvrOdIquEV7W6FGV/zhI2myN7WP4HSd1dM4MvR3tn8hj2uPq pm7ABBWdddVUMh3k3q4qBd9G5gkSPfnoleApN+8DV2y9MANPHloQq4d8/i7sMD2o /k41da+DrAuX6R4+m5Y5XYmjhYLIS499Ykyd+eLgk7xPqzZ5LiSRnBcu+gHRZxTa 1YfDaRRBMSJ8rpW+sR1IQnT3eUBUNRepe2+HCnnFpbGzU+WMTes=
-----END CERTIFICATE REQUEST-----  

Whichever service you use, this is the bit they’ll want from you.   

Tip: The private key you need, that matches this certificate, is called ForReal.key and it’s in the private folder.  

Tip: The CRT file they supply to you, and the ForReal.key file are the two files that need to be transferred to your application \certificates folder. Give then a suitable name, and set that name in the Web Server options.  

Give it a Try

Thwate has a simple web site that allows you to test this in action.

  1.  Go to: https://www.thawte.com/cgi/server/try.exe
  2.  Then click next.
  3.  Then leave everything unticked, and click next.
  4.  Cut and paste your CSR into text box and click next.  They’ll give you back a page that looks something like this; 

    -----BEGIN CERTIFICATE-----
    MIIDoTCCAwqgAwIBAgIJAMwfOdh3903EMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYD VQQGEwJaQTEiMCAGA1UECBMZRk9SIFRFU1RJTkcgUFVSUE9TRVMgT05MWTEdMBsG A1UEChMUVGhhd3RlIENlcnRpZmljYXRpb24xFzAVBgNVBAsTDlRFU1QgVEVTVCBU RVNUMRwwGgYDVQQDExNUaGF3dGUgVGVzdCBDQSBSb290MB4XDTA2MDIxNDEzMTQ0 N1oXDTA2MDMwNzEzMTQ0N1owgbIxCzAJBgNVBAYTAlpBMRUwEwYDVQQIEwxXZXN0 ZXJuIENhcGUxEjAQBgNVBAcTCUNhcGUgVG93bjEkMCIGA1UEChMbQ2FwZVNvZnQg U29mdHdhcmUgKFB0eSkgTHRkMRwwGgYDVQQLExNUaHdhdGUgVGVzdGluZyBVbml0 MQ8wDQYDVQQDEwZob2JiZXMxIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2FwZXNv ZtQuY29tMIzBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwZjJN9fvrONf MG9IFXVvGbMhpzvE3pn0RC19owO7yklIjKn6SrQmFL1eIKWzIrORj3+SUHZo1wre tZULM6fgWRDX5z5QXW+S5GatoANyVNwkNoyETYYLI6fUdLOtXtA2QwyieBj7UaZD 62agY5fLTaX+bs/+LbJSX/smaJpZJy2ub2XJNNt8PLHjgFku2kple95XPA9ufjaI OMRyXP59klP4bKbmrsaJDx0EgAF0CgGM/p046CwPpsKjtYRaKsKXDe74PV67wvd0 Ir2bTeCFQsyILYgQB7YIwblx4VjoDGQ3Zm7273eFXkcTO9oJ3dHy9Mzbg5MUzw52 Wc31UTYRvQIDAQABo2QwYjAMBgNVHRMBAf8EAjAAMDMGA1UdHwQsMCowKKAmoCSG Imh0dHA6Ly91d3cudGhhd3RlLmNvbS90ZXN0Y2VydC5jcmwwHQYDVR0lBBYwFAYI KwYBBQUHAwEGCCsGAQUFBwMCMA0GCSqGSIb3DQEBBAUAA4GBAK254X2QCl4Qu1Yh NCyrpGB/me8ZGkYlpcODFh0qZ5v4Yi/+4jpRDljh5CLTagI6C8o7L0UBYF7j0xJ/ K53GivGwuqefGgMmhnfZAeDLIxlxvkoT3HlTZGyncoLldiU2X+OUTP5wyAz34/8e a8Tf5B+cJ2ozpB9I8WstNcAeEw4q
    -----END CERTIFICATE-----  
  5. Make a new text file in the certs folder. Call it say Site.CRT where Site is the name of your site.
  6. Copy the certificate out of the browser certificate and paste into the CRT file.

Tip: The private key you need, that matches this certificate, is called ForReal.key and it’s in the private folder.  

Tip: The CRT file, and the ForReal.key file are the two files that need to be transferred to your application \certificates folder. Give then a suitable name, and set that name in the Web Server options.  

Creating a Server that has both secure and normal web pages

The example referred to in this section is called MixedTLS (8) and can be found in the \clarion\accessory\examples\nettalk\web server folder.

Tip: Please take note of the files you need to copy into this application folder (in the Distribution section of the main NetTalk document).  

Some sites contain some mix of secure and normal web pages. The first thing this means is that your Web server is listening on 2 ports. One for unencrypted traffic, and one for encrypted traffic. Since the Web Server object cannot listen on 2 ports simultaneously, this is accomplished by adding a second web server object to the WebServer procedure.

Tip: Start with a WebApp that is already serving Normal (insecure) web pages. To add the server on the second port:

  1. Go to the WebServer procedure in your app and click on the Extensions button.
  2. Then click on Insert, and select IncludeNetTalkObject from the available list.
  3. Set the thisObjectName to something like ThisWebSecure and the Base Class to NetWebServer.
  4. On the Settings tab set the Port Number to something other than the port used by the normal server. (The default for normal servers is 80, the default for Secure servers is 443)
  5. Go to the Security tab
  6. Tick on Use TLSL to make the server secure.
  7. Set the name of the certificate to use. This is the name of the CRT file that you either purchased, or created earlier. Typically it is named for the site you are serving.

    In the example these files are in the \certificates folder. In the example, the name of this file is Settings.Crt.  So in this setting on the template there is 'certificates\settings.crt'. Notice the path is relative to the application  folder. If your file is called say www.capesoft.com.crt then you would enter 'certificates\www.capesoft.com.crt'
  8. SeSet the name of the key file to use. This typically matches the name of the CRT file (used above) except with the extension key.
  9. Set all the other settings to match the settings of the other NetWebServer object here. Specifically both objects can use the same NetWebHandler procedure. 

Secure Dynamic Pages

 If you have procedures in your application that should only be served via the Secure port then go to those procedures (NetWebPage, NetWebBrowse and NetWebForm) and tick on the option Only Serve if Secure TLS. (You’ll find this option on the Security tab). 

Secure Static Pages

IfIf you want static pages in your system that can only be accessed via the secure server, then place them in a subdirectory of Web called Secure. This sub-directory should be below your Web directory. i.e. \web\secure

In example 8, there is a page in the secure directory called welcome.htm  

Creating a Site that is all-secure, but which also listens on Port 80 for incoming connections.

 The example referred to in this section is called AlwaysTLS (9) and can be found in the \clarion\accessory\examples\nettalk\web server folder.

Tip: Please take note of the files you need to copy into this application folder (in the Distribution section of the main NetTalk document).

One thing you might like to do is make your whole site secure, but still listen on port 80 for incoming connections.

For example, let’s say you had a site called www.buyme.com. You want to make this site 100% secure. Which means all your pages will be served by the server running on port 443. But if a user goes to http://www.buyme.com he’ll be coming in on Port 80. So you need to listen on port 80 as well, redirecting incoming traffic to https://www.buyme.com

To do this, make sure there are 2 objects in your WebServer procedure, as detailed in the section above called Creating a Server that has both secure, and normal web pages.

Go to the Not-Secure server. The one running on Port 80. Go to the Settings Tab, and on that go to the Security Tab. Then tick on the option Always Redirect To Secure Site. Enter the secure site port here.

Server Name Indication (SNI)

When a browser connects to a server it desires the server to use a certificate which matches the URL it is connecting to. For example if it is connecting to www.capesoft.com it becomes upset if the server uses a certificate issued to www.clarionshop.com.

Because the connection is made (and hence the certificate chosen) before any data is transferred the server does not know which host name the browser is connecting to, and hence which certificate to use.

This means that it has been impossible for multiple secure sites to share a single IP:Port address. Each server could only use one certificate, and hence different servers were required for different sites.

Server Name Indication (SNI) is used to overcome this problem. It is implemented in all modern browsers (*). It is also implemented in the NetTalk 9 Server allowing NetTalk Web Servers to use multiple certificates on a single server. SNI basically includes an unencrypted Host name (the "server part" of a URL) when creating the connection, before the connection is secured. Using this name the server is able to decide which certificate to use.

In the server app the Certificate setting has been expanded to Certificates (CSL), Private Keys (CSL) and Host Names (CSL). All three fields can be comma separated lists, and all 3 are required for SNI support. The Certificates setting contains a comma separated list of the CRT files, the Key setting contains the list of matching KEY files (in the same order) and the Hostname setting contains the third list, this time containing the matching hostname for the certificates. For example;

Certificates (CSL): 'certificates\capesoft.crt,certificates\clarionshop.crt'
Private Keys (CSL): 'certificates\capesoft.key,certificates\clarionshop.key'
Host Names (CSL): 'capesoft.com,clarionshop.com'

On the client side there is nothing you need to do to implement SNI. The NetTalk WebClient class also supports SNI automatically.

(*) Any version of IE on Windows XP or Windows Server 2003 does not support SNI. Any other browser on XP is fine, and any version of IE7 or later on any other version of Windows is fine. For a full list of supported, and unsupported browsers, see Wikipedia.

Connections made from browsers that do not support SNI will use the first certificate specified on the server. Connections made from browsers using an unrecognized hostname will also default to the first certificate.

Binding Apps to an IP address

Quite apart from any TLS considerations, it’s possible to limit access to the server based on the IP that the server is listening on.

By default the server listens on all the IP addresses that are valid for the server. It will listen on 127.0.0.1 (which means the browser is on the same machine), and it will listen on any network cards, or other network interfaces, installed in the machine.

If you are adding a web interface to a program, and you only want that interface to be accessed from that machine, then you can BIND the server to address 127.0.0.1. None of the other network cards will work.

Another situation where this is handy is if the machine has 1 network card for the LAN, and another for the Internet. (Or maybe even a dial-up modem for the internet). By binding the server to the LAN card you prevent people outside the LAN from accessing the web server. Of course you should be preventing unwanted outside traffic anyway via a Firewall, but this provides an additional level of security.

You can bind a server to a specific IP address by going to

  1. The WebServer procedure
  2. Extensions
  3. NetTalk Object
  4. Settings tab
  5. Security Tab
  6. Bind Server to only IP:  set this to the IP address (of this machine) you wish to bind the program to.

If you are making a web interface to a Service (a program that you run on a machine in Service mode) then strongly consider limiting the web interface to 127.0.0.1 . This means only browsers running on this same machine will be able to interact with your service. 

Managing Certificates on Windows

For your testing you may find it useful to remove a certificate that has been installed on your machine.  To do this:

1. Click on the Windows Start button, and select RUN.

2.2. Type certmgr.msc and press enter.

3. Look through the installed certificates and remove the ones that belong to you (that you want to remove).

The most likely places that your certificate will end up is in the Trusted Root Certification Authorities \ Certificates folder and the Other People \ Certificates folder. You can remove a certificate by right-clicking on it, and selecting Delete.   

Extracting an existing certificate from IIS 6

If you have an existing secure web site (i.e. one using a certificate) running on IIS 6 then you can extract it using the following steps;

Part 1

  1. Right-Click on My Computer, Manage
  2. Services & Applications
  3. IIS
  4. Highlight the website in question
  5. Right-Click, Properties
  6. Directory Security tab
  7. Server Certificate button, this brings up a wizard.
  8. Walk through the wizard to Export the current certificate to a .pfx file. (For the password use something simple to remember.)
  9. Save the PFX file to a temporary folder.

Part 2

Copy the OpenSSL.exe, Msvcr120.dll, Ssleay32.dll, Libssl32.dll and Libeay32.dll files into the same temp folder. (You'll find these files in the \clarion\accessory\bin folder)

Part 3

Open a command prompt window, go to the temp folder

type
openssl pkcs12 -in whatever.pfx -info -out whatever.pem -nodes
openssl pkcs12 -in whatever.pfx -clcerts -nokeys -out whatever.crt
openssl pkcs12 -in whatever.pfx -nocerts -out whatever.key -nodes

Part 4

  1. Copy the pem, crt and key files to your \certificates folder
  2. Delete all the files in the temp directory  

Deploying a Secure Web Server

Deploying a secure web server is really no different from deploying a normal web server. However some additional files are probably necessary. As of the time of writing the files are;
Msvcr120.dll, Ssleay32.dll, Libssl32.dll and Libeay32.dll - These files can all be found in your \clarion\accessory\bin folder.

Note: The SSL DLL's were updated in NetTalk 7.11, and the MSVCR90.DLL is a new dependency, replacing the dependency on MSVCRT71.DLL. Although the MSVCR90.DLL is shipped with NetTalk, the recommended approach to installing this DLL on your target system is to install the Microsoft Visual C++ Redistributable Package (x86) on the target machine.

Note: The SSL DLL's were updated in NetTalk 8.56 to version 1.0.2d which changed the dependency from MSVCR90.DLL to MSVCR120.DLL.  Unlike the MSVCR90.DLL file, Microsoft recommend that you ship this file in your application folder.

In addition you will need to include the Certificates folder in your application folder.

Using Intermediate Certificates

Some certificates available for purchase require the use of an intermediate certificate in order for the site to work without error in all browsers. Usually your certificate supplier will note this, and will supply you with an intermediate certificate in a .CRT file.

All you need to do to use the intermediate certificates is to merge them into your .CRT file using a simple text editor. The intermediate certificates MUST come after, your certificate in the file.

Example

-----BEGIN CERTIFICATE-----   <-- this is the site's certificate
MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVMx
...
qDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZEjYx8WnM25sgVjOuH0aBsXBTWV
U+4=
-----END CERTIFICATE-----    
-----BEGIN CERTIFICATE-----   <-- these are the intermediate certificate(s)
WBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgMQLARzLrUc+cb53S8wGd9D0Vmsf
...
SxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j09VZw==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0
...
IYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMMj4QssxsodyamEwC
W/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd
-----END CERTIFICATE-----

Note: Version 5.07 or later is required for intermediate certificates to work.

Checking if it's Correct

Obviously the easiest way to check if you have got it all working correctly is to open the site in a browser. If you get no warnings when accessing the site in the browser, and the browser has a padlock to indicate the page is secure, then you've got it all right.

There are also a few online services which are able to probe your server to determine if you have set up TLS correctly. However be warned - I've had some mixed results with these. Sometimes they report errors which are clearly incorrect, so evaluate their response very carefully before panicking.

Levels of TLS

TLS (Transport Layer Security) is the general term for the encrypted method for the web. However there are various "versions" of the protocol which all fall under this umbrella. Not surprisingly they're not binary compatible. Typically the browser supports "a lot of them", the server supports "a lot of them" and hopefully there's some overlap.

The various versions of TLS go by different names. SSL version 2  and 3 are now obsolete, are vulnerable, and should no longer be used. TLS 1.0, 1.1 and 1.2 are still in operation.

Regardless of which TLS version you are using, there are also a large number of encryption schemes which are supported. Ultimately you can determine which version of TLS your server will use, and which encryption schemes are allowed.

SSLMethod

You can set the .SSLMethod property in the ThisWebServer.Open method in the WebServer procedure.
Possible values are;
NET:SSLMethodSSLv23  
NET:SSLMethodSSLv2
NET:SSLMethodSSLv3
NET:SSLMethod3TLS  
 ! SSLv3 and TLS 1.0, 1.1 and 1.2
NET:SSLMethodTLS      ! Default, TLS 1.0, 1.1 and 1.2
NET:SSLMethodTLS_PCI ! TLS 1.1 or TLS 1.2
NET:SSLMethodTLSv1    
NET:SSLMethodTLSv1_1    
NET:SSLMethodTLSv1_2

Ciphers

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/.
A good source for SSLScan documentation is here http://www.titania.co.uk/index.php?option=com_content&view=article&id=56&Itemid=68.

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:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS'

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

As you can see this limits the cipher list to only HIGH level ciphers, and removes support for any SSLv2 ciphers. If, for example, you wanted to include MEDIUM level ciphers as well, then you might set;

ThisWebServer.SSLCertificateOptions.CiphersAllowed = 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:!LOW:!SSLv2:!EXPORT'

However you should only reduce the supported cipher level in specific cases where you know what you are doing, as this may introduce security vulnerabilities into your application.

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

Troubleshooting and Common Errors

The first thing to do if there is a problem with the secure server is to go to the WebServer procedure, to the NetTalk extension (for the server) and turn off the option Suppress Errors. This will usually quickly highlight what the error is. Once the error has been corrected you should turn Suppress Errors back on.

Some common errors are;

-65: SSL Failed to Load Certificate

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.

-73: NetTalk Could Not Load SSL DLLs [LIBEAY32.DLL, LIBSSL32.DLL, SSLEAY32.DLL, MSVCR120.DLL]

The SSL functionality in NetTalk requires the MSVCR120.DLL, LIBEAY32.DLL, LIBSSL32.DLL and SSLEAY32.DLL files. These can be found in your application folder or in the \clarion\accessory\bin folder. Copy these four DLL's to your application folder (and include them in your program install.)

Note: Unlike the MSVCR90.DLL, the MSVCR120.DLL should be shipped with your program.

Note: The SSL DLL's were updated in NetTalk 7.11, and the MSVCR90.DLL is a new dependency, replacing the dependency on MSVCRT71.DLL. Although the MSVCR90.DLL is shipped with NetTalk, the recommended approach to installing this DLL on your target system is to install the Microsoft Visual C++ Redistributable Package (x86) on the target machine.
[End of this document]
Return to NetTalk Documentation Index