NetTalk WebServer - Building Secure Web Sites using NetTalk WebServer
	Version beta www.capesoft.com Updated 06 April 2006

NetTalk WebServer - Building Secure Web Sites

Learn NetTalk	Examples	Common Features	NetAuto Objects	NetSimple Objects	Dial-Up	Support	Version History

  = recommended reading

Building Secure Web Sites using NetTalk Web Server

Introduction

The example referred to in this section is called;

BasicSSL (6)

And can be found in the \clarion\3rdparty\examples\nettalk\netweb 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:

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

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

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

Making Yourself into a Certificate Authority

In order to be an Authority you need 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 \clarion6\3rdparty\bin\MakeCertificates folder.

2.         Run the batch file : CreateCACertificate.Bat

a.          Press any key to start the process.

b.          “Enter pass phrase”. 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.

c.          Since you can’t see it when you type it, you’ll need to type it in again when asked.

d.          And then you enter it again (this time it’s being used.)

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

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

g.          Locality: Usually a city name.

h.          Organization name: 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.

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

j.            Common Name: This is 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.

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

And voila, your certificate is created.

3.         Press any key to close the batch file.

 

If you now look in the YourCARoot folder you should see 2 files have been created.

One in cacert called YourCA.crt and one in private called YourCa.Key.

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

2.         Run the batch file : CreateSelfSignedCertificate.Bat

3.         Press any key to start the process

4.         Country Name: Enter your 2 letter country code.

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

a.          Locality: Usually a city name.

b.          Organisation Name: The name that will appear on the Certificate.

c.          Organisation Unit Name: 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.

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

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.

In theory you could set an entry in the HOSTS file on the remote LAN, but frankly that’s probably cause more harm than good.

Worst case, 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.

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 your magic password. This is the password you set in step (b) of the section above.

3.         You’ll be asked to confirm certification. Enter a y.

4.         You’ll be asked to commit the certificate. Enter a y.

5.         Press any key to end the process.

 

If you now look in the YourCARoot folder you should see 3 files more have been created.

In the certs folder are 2 certificates, Demo.crt and SignedDemo.crt. In the private folder is a new file Demo.Key.

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

Copying the Certificate to your application folders

Use Windows explorer now to open your application directory. Change to the Web folder that is a sub-directory of your application directory. If there isn’t a Certificates (ie \app\web\certificates) folder then make one there.

Into this folder copy 2 files.

1.  \clarion6\3rdparty\bin\MakeCertificates\YourCARoot\private\Product.key where Product is the name of the file you created in the section above.

2. \clarion6\3rdparty\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

2.         Go to Extensions

3.         NetTalk Object, Settings Tab

4.         Tick on Use SSL to make server secure

5.         Set the port number for the secure server. The default port for secure servers is 443.

6.         Enter the path to the certificate file. DO NOT add an extension to the name. In the example the certificate is in the Certificates directory, and is called Settings.Crt, so in this field we put

7.         ‘certificates\settings’

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

 

There are several authorities you can use.

a.     www.verisign.com the biggest, but not surprisingly also the most expensive.

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

 

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

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.

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

ZnQuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwZjJN9fvrONf

MG9IFXVvGbMhpzvE3pn0RC19owO7yklIjKn6SrQmFL1eIKWzIrORj3+SUHZo1wre

tZULM6fgWRDX5z5QXW+S5GatoANyVNwkNoyETYYLI6fUdLOtXtA2QwyieBj7UaZD

62agY5fLTaX+bs/+LbJSX/smaJpZJy2ub2XJNNt8PLHjgFku2kple95XPA9ufjaI

OMRyXP59klP4bKbmrsaJDx0EgAF0CgGM/p046CwPpsKjtYRaKsKXDe74PV67wvd0

Ir2bTeCFQsyILYgQB7YIwblx4VjoDGQ3Zm7273eFXkcTO9oJ3dHy9Mzbg5MUzw52

Wc31UTYRvQIDAQABo2QwYjAMBgNVHRMBAf8EAjAAMDMGA1UdHwQsMCowKKAmoCSG

Imh0dHA6Ly93d3cudGhhd3RlLmNvbS90ZXN0Y2VydC5jcmwwHQYDVR0lBBYwFAYI

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\web\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\netweb folder.

 

Very few sites consist of only secure pages. Most 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. Typically ‘certificates\site’

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 Advanced 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 called Secure. This sub-directory should be below your Web directory.

 

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\netweb folder.

 

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 Advanced 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 from outside from accessing the web server.

Of course you should be preventing 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.         Advanced Tab

6.         Bind Server to only IP:

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.