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

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

Introduction

The example referred to in this section is called BasicSSL (6) and it can be found in the \clarion\3rdparty\examples\nettalk\web server\ folder.

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

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.  

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

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 Country Name (2 letter code) [US]:
    Enter your 2 letter country code.
  4. State or Province Name (full name) [Some-State]:
    Enter your state or province name here.
  5. Locality Name (e.g., city) []:
    Usually a city name.
  6. Organization Name (e.g., company) [Internet Widgits Pty Ltd]:
    The company name that will appear on the Certificate.
  7. 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.
  8. 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 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.
  3. Sign the certificate? [y/n]:
    Enter a y.
  4. 1 out of 1 certificate requests certified, commit? [y/n]:
    Enter a y.
  5. Press any key to end the process.

Files Created

If you now look in the \clarion\accessory\bin\MakeCertificates\YourCARoot folder there are 2 new files Demo.crt and SignedDemo.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 SignedDemo.Crt file is an information section starting with something like this

Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: sha1WithRSAEncryption
Issuer: C=ZA, ST=Western Cape, L=Cape Town, O=CapeSoft Software,

and a certificate section with the now familiar

-----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 name of your certificate. The name you enter there needs to match the name you called the file here. In the examples this is set to 'certificates\settings' - certificates being the Folder part where the certificate is stored, and Settings being the name part. Notice the name part does not have an extension as it's actually referring to both the CRT and the KEY file.  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. Tick on Use SSL to make server secure.
  4. Set the Port Number for your secure server. The default port for secure servers is 443.
  5. Set the name of the certificate to use. This is the name of the CRT and KEY files that you either purchased, or created earlier. Typically they are named for the site you are serving. In the example these files are in the \certificates folder. In the example, the name of these files are Settings.Crt and Settings.Key respectively.  So in this setting on the template there is 'certificates\settings' Notice there is no extension. Also notice the path is relative to the application  folder. If your files are called say www.capesoft.com.crt and www.capesoft.com.key then you would enter 'certificates\www.capesoft.com'
  6. Click Ok, then Ok, then compile and Run.  

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 SSL 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
  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\3rdparty\bin\MakeCertificates folder. 

  1.  Open Windows Explorer. Go to the \clarion6\3rdparty\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 MixedSSL (8) and can be found in the \clarion\3rdparty\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. Tick on Use SSL to make the server secure.
  6. Set the name of the certificate to use. This is the name of the CRT and KEY files that you either purchased, or created earlier. Typically they are named for the site you are serving. In the example these files are in the \certificates folder. In the example, the name of these files are Settings.Crt and Settings.Key respectively.  So in this setting on the template there is 'certificates\settings'. Notice there is no extension. Also notice the path is relative to the application folder. If your files are called say www.capesoft.com.crt and www.capesoft.com.key then you would enter 'certificates\www.capesoft.com'
  7. 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 SSL. (You’ll find this option on the Security tab). 

Secure Static Pages

If 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 AlwaysSSL (9) and can be found in the \clarion\3rdparty\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

Binding Apps to an IP address

Quite apart from any SSL 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. 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

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 the SSL 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 SSL

SSL (Secure Sockets Layer) 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 SSL go by different names. SSL version 2 is now obsolete, is vulnerable, and should no longer be used. SSL Version 3 is still in operation, as is TLS v1 (think of this as SSL version 4).

Regardless of which SSL version you are using, there are also a large number of encryption schemes which are supported. Ultimately you can determine which version of SSL 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:SSLMethodTLSv1    
NET:SSLMethodTLSv1_1    
NET:SSLMethodTLSv1_2

Ciphers

The term "SSL" 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 SSLv3 or TLSv1 High level ciphers only. Specifically;

Supported Server Cipher(s):
  Accepted  SSLv3  256 bits  AES256-SHA
  Accepted  SSLv3  128 bits  AES128-SHA
  Accepted  SSLv3  168 bits  DES-CBC3-SHA
  Accepted  TLSv1  256 bits  AES256-SHA
  Accepted  TLSv1  128 bits  AES128-SHA
  Accepted  TLSv1  168 bits  DES-CBC3-SHA

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 looks like this;
ThisWebServer.SSLCertificateOptions.CiphersAllowed = 'ALL:!ADH:RC4+RSA:+HIGH:!MEDIUM:!LOW:!SSLv2:!EXPORT'

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.

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