UserGuide

SSL for Standalone Web Apps

From Xojo Documentation

You can deploy standalone web apps that take advantage of SSL (URLs that use the https prefix) starting with Xojo 2014r3.

Note: Secure standalone web apps use TLS v1.2 by default, which may not be supported by some older versions of Internet Explorer (IE 10 and earlier) unless you enable TLS 1.2 in their Security Settings.

Set up the SSL Certificate

First you'll need an SSL certificate, which you can obtain from many sources. If you're doing local testing, feel free to use a self-signed certificate. If your web app will be available on the internet, please be sure to use a real purchased SSL certificate because it adds extra protection from certain kinds of internet attacks. Generally, a self-signed certificate will have two components (the certificate and key file) while a purchased certificate will likely have three or more (certificate, key, CABundle or intermediates).

Once you have a certificate and have downloaded it and the private key to your computer, you need to make a single file, putting all of the pieces together into that file. Create a text file that has the same name as your application with a .crt extension and paste the contents of the certificates into it, one after another in this order:

  1. Certificate
  2. CABundle
  3. Private Key

Make sure to include the entire contents of your primary certificate, intermediate certificate bundle (if required) and private key.

Each file must start on a new line (don't concatenate the last line of one file and the first line of another onto the same line). As mentioned, the name of this file should match your web app name, so if your web app is named MyBestApp or MyBestApp.exe, the certificate file should be named MyBestApp.crt.

If you are running in debug mode, the built app will be named MyBestApp.Debug, but the certificate should still be named MyBestApp.crt.

Now that you have a correctly named and formatted certificate file, you'll need to make sure it is next to the built web app when it runs. A Copy Files Build Automation Step works great for this to make sure it ends up in the right place every time.

An example file might look like this:

-----BEGIN CERTIFICATE-----
MIICuzCCAiQCCQD+1X0TfzZ2qDANBgkqhkiG9w0BAQUFADCBoTELMAkGA1UEBhMC
VUsxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRkwFwYDVQQKDBBG
YWtlIENvbXBhbnkgTExDMQ0wCwYDVQQLDARGYWtlMR0wGwYDVQQDDBRmYWtlZG9t
YWluLmxvY2FsLmNvbTEnMCUGCSqGSIb3DQEJARYYZmFrZWFkbWluQGZha2Vkb21h
aW4uY29tMB4XDTE0MDExNDE5MTk1NloXDTE1MDExNDE5MTk1NlowgaExCzAJBgNV
BAYTAlVLMQ8wDQYDVQQIDAZMb25kb24xDzANBgNVBAcMBkxvbmRvbjEZMBcGA1UE
CgwQRmFrZSBDb21wYW55IExMQzENMAsGA1UECwwERmFrZTEdMBsGA1UEAwwUZmFr
ZWRvbWFpbi5sb2NhbC5jb20xJzAlBgkqhkiG9w0BCQEWGGZha2VhZG1pbkBmYWtl
ZG9tYWluLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA8GJcPMzT/O+v
8x4hoAikz7wQGhLqeNaeu6u0vDaC0lJ25HJ4sTUqNatYzPlBc6cXrDXY1bCpBtSb
nKOdAbQgPpz6aHDyDT8P3dDn/U6QxNaQAm15hjvgtsF2AuXV3f/6xVxE2RAs9/eh
3WRAH1G8fcrP86vKwbJnA5bAIEKoFfUCAwEAATANBgkqhkiG9w0BAQUFAAOBgQAd
1/lv9aRGpqOMrNVgBLTWBjznV56n1CyBx/3a2Yk6y9iLtexRyc57MfmmGwpnZ4mt
qWvdVK/FJkn9SYsefoUxt59yMBaxHNQMgih+EwoMbWrPCOZI3P997HQHRH4qO6Sp
SM3wtzL5PwJ7lczNIdhKdeVZ1ayDG04skIIhqx9J3Q==

-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDwYlw8zNP876/zHiGgCKTPvBAaEup41p67q7S8NoLSUnbkcnix
NSo1q1jM+UFzpxesNdjVsKkG1Juco50BtCA+nPpocPINPw/d0Of9TpDE1pACbXmG
O+C2wXYC5dXd//rFXETZECz396HdZEAfUbx9ys/zq8rBsmcDlsAgQqgV9QIDAQAB
AoGAWRf7m8VG5L5pdjA6wjex7hSD20YbhUH2fxQ63m9NuWo7CpyqwvMze8TQGthf
O+A4U+l5PmpFm3R9YGb7sD/0mshrMCn0+Oiwn14cHh3LRrANljeHZCCgF386Sye3
GeQkfOF27N+SKkwydLE1utQQWPoSiCmcBH2+IhVdkGYLTEECQQD6FUpcDSIFoEGO
fk7LqyIBI352cUTeu7C8aFDiABBiDtBz4ypeK9K+tRkFcng1Pk6JPtPJZEER1a9S
24ktdGu5AkEA9hJTNXLf0wp5eNJ7dbVMNSOaBcU1M4h4oaYcZhR5X6Feo3+nFKmg
2EAU34auPPENW3Tl1ROpkH/LJ2tekzvyHQJBAJ/j7tftuZvZOzDMhrpm3uXVeKxn
fP3fCH9dPqFQIyleiV4ell8BK8usY6P87Og1vua22ZeAVq39bgvOuuTp81kCQQCb
utU2SlEkushNksfXorlsF+/uHvSgfIn7o6jtYZ++yd2fE7al+QR2V3feTtoOb2/I
pZ6ezybM8FOdyvG7tIBxAkAEYS5tAgRSJhy/h4vq5ZpHWaIZ0dMEXxmbq7eAALv5
aCT4ePXIx7xrlKbiWZB0wUBMUBrANhmwCcpM9eE0bKYb
-----END RSA PRIVATE KEY-----

Configure Web Server to use SSL

The last piece of this puzzle is to tell your web app that you want it to listen on a secure port. You cannot set the Secure Port in the Shared Build Settings, so you'll need to use some command-line parameters to get it to work. These are the parameters that you'll be interested in:

Parameter Description
--SecurePort Specifies the port number for secure connections. You must specify a port with this in order to allow secure connections.
--MaxSecureSockets Set the maximum number of secure sockets (default=200).
--Certificate The path to the SSL certificate if you don't want to put it beside the executable (starting with 2015r2).

--certificate=/full/path/to/file

--SslType Specifies the type of security used. These integer values can be used: 0 (SSLv2), 1 (SSLv23), 2 (SSLv3), 3 (TLSv1), 4 (TLSv11), 5 (TLSv12, the default)
--SecureNetworkInterfaceIndex The index value (of NetworkInterfaces) to use as the NIC for secure connections.

The secure port must be different than the port selected in the IDE (or specified with the --port command line property). For example, if you built your web application using port 8080 as the listening port, you might use:

   MyBestApp --secureport=8081

As with the non-ssl version, you may also increase the maximum allowed number of connected sockets if necessary, which is useful if you notice that your app rejects connections when there are a lot of users connected at the same time.

   MyBestApp --secureport=8081 --maxsecuresockets=400

Remember, with the maxsecuresockets option, the number of open sockets does not represent the number of simultaneous users. Depending on the construction of your app, and how your users use it, a browser could have zero open connections (like between keystrokes or mouse clicks) or multiple open connections (if the user is clicking quickly on a control). That being said, you also shouldn't set this value too high. With more open connections comes more memory and CPU use, so you'll need to experiment with this number to find the best threshold for your app/server combination.

If you try to start with SSL but the certificate is not found or is not readable, the app will display an error and quit.

Once you've launched your app, use a browser to connect to it:

   https://127.0.0.1:8081/

Your app should now display the appropriate "secure" indicator in the browser address area.

If you also want to prevent unsecured access to the web app, you can set the number of unsecured sockets to 0:

   MyWebApp --secureport=8081 --maxsockets=0

By default, SSL standalone web apps use TLSv12 for the connection type. This is the most secure method and is recommended. But if you need to choose an older version for compatibility with older web browsers, you can do so using the command line option like this:

   MyWebApp --secureport=8081 --ssltype=3

You can also set the connection type by change the WebApplication.Security.ConnectionType property in your web app's Open event:

Self.Security.ConnectionType = WebAppSecurityOptions.ConnectionTypes.TLSv1

Example Project

You can also refer to the example project: Examples/Web/SSL

Generating the Certificate Signing Request

Here are example commands you can run from the Terminal for Linux/Apache to generate a certificate signing request (CSR):

   # Generate the 2048-Bit private key
   openssl genrsa -out server.key 2048


   # Generate the CSR
   openssl req -new -key server.key -out server.csr


   # Remove the passphrase from the key (so you don't have to type it in to restart Apache)
   cp server.key server.key.org
   openssl rsa -in server.key.org -out server.key


   # Generate a self-signed public key (for testing only)
   openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt