UserGuide:SSL for Standalone Web Apps

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

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.

If you'd rather not deal with this yourself, Xojo Cloud has built-in SSL support.

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:

Certificate
CABundle
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:

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

UserGuide

SSL for Standalone Web Apps

From Xojo Documentation

Contents

Set up the SSL Certificate

Configure Web Server to use SSL

Example Project

Generating the Certificate Signing Request

See Also