CapeSoft.Com
Clarion Accessories
Safe Update
Documentation
CapeSoft Logo

CapeSoft Safe Update
Documentation

Download Latest Version JumpStart History
Installed Version Latest Version
Please Note: Products required for Safe Update - NetTalk, Cryptonite, StringTheory

Introduction

Please Note : Safe Update 3 requires Cryptonite, StringTheory and NetTalk to work. These items are sold separately.

Safe Update allows you to upgrade your program over an internet connection securely and automatically. It adds a Check for Updates option to your program, and also provides a framework for pushing updates to your users in a safe manner.

Safety is important here because if your program is being updated automatically, or manually on-demand by the user, then you want to be sure that the content they are downloading and using is content you intend for them to have. If a hacker accessed your web server, and replaced your install file, then you do not want the upgrade to be applied.

Safe Update can update from a shared network drive, from a local intranet web server, or from a web server on the internet.

When your application is updated you need to make sure that the update being downloaded is the genuine article and not a malicious file instead. To achieve this Safe Update includes security in the form of digital signatures.

Safe Update supports Clarion 5.5 and later, both ABC and Legacy template chains. Clarion 5 is not supported.

Upgrading from Safe Update 1 and 2

Safe Update 3 has been refactored to make implementation much easier to do, and much easier to maintain in the long run. To this end the simplest way to update to Safe Update 3 is to remove the Safe Update 1 or 2 support, and then re-implement Safe Update 3. Since it takes only a few minutes to do this it is a cleaner solution than trying to maintain backwards compatibility.
To remove SafeUpdate 1 or 2 from your application;
  1. Delete the SafeDownload and SafeAutoUpdate procedures from your app
  2. Remove the Safe Update local extension to your Main procedure.

ClarionLive

ClarionLive webinar number 183 is an excellent walk-through of the Safe Update process. Watching the webinar is recommended.
Tip: Right click on the link, and choose "Save Link As..." to save the webinar as a file on your disk.

The Basics

If you are keen to get started right away it is recommended that you start with the JumpStarts below, but before you get going it's a good idea to read the rest of this section to make sure that you're familiar with the basic concepts and how everything fits together.

TThere are three basic areas of functionality that SafeUpdate provides:
  1. Securing

    SafeUpdate uses certificates to secure the entire update process. These certificates use the industry standard Public/Private key architecture to sign and authenticate updates. Cryptography can get complicated, so we have endeavored to make the process as simple as possible.
  2. Uploading

    This is simply the process of getting the update (your application installer) to the location that the application will download it from.  It includes creating an XML version file for the update, and uploading the files via FTP to the web site.
  3. Check for Updates

    This includes downloading an update, either from the internet or LAN and performing whatever task is required to install that update. This usually means running an installer and closing down the application to allow the install to work. SafeUpdate handles checking for updates, downloading,  verifying updates and running the installer for you.

Jump Start

Getting a certificate

TThe Safe part of Safe Update is done by signing the Install file, and Version file before they are uploaded to the web site. Signing requires a certificate.
Getting a certificate can be a time consuming process, because it needs to be issued by a company that trusts that you are who you say you are. If you don't already have a code-signing certificate then you can read the section "Getting a Digital Certificate" to find out how to get one.

However because this is a JumpStart, and because that process may take some time, a sample (UNTRUSTED) certificate called "Safe Update Test" has been included in the Safe Update install file. You would not want to use this certificate in a real world situation, however it does provide a substitute for the purposes of getting the basic process in place.

Adding a Version Resource to your Application

Note that while this section is not required in your application, it is recommended.

Adding a Version Resource to your application embeds a standard Version Resource file into your EXE. This allows the version information to be read from the EXE and also provides the version information displayed from the application in Windows (e.g. In Explorer and the Programs and Features control panel).

CClarion (6 and later) provides a Global Extension that adds this Version Resource to your application and CapeSoft WinEvent provides the ability to extract that information and use it with SafeUpdate (and elsewhere in your application).
 
  1. Add the global extension: cwVersionRes - Version Resource to your application.
  2. Enter the details for your application, including the version number (this should be updated each time you update your application to a new version). The version number can include an automatically generated build-number./li>
  3. IIf you wish to make use of the WinEvent function ds_GetFileVersionInfo in your own code, then add the WinEvent global extension to your application

 

Adding a "Check for updates" to your application

This Jump Start shows you how to add Safe Update to your application in order to be able to download updates. This guide steps you through:
  1. Adding the global extension to your application
  2. Importing the SafeDownload function into your application
  3. Entering the Download settings
  4. Adding the Local extension to the Main procedure

1. Adding the Safe Update Global Extensions to your Application.

To add the Safe Update template to your program, add the following to your application's Global Extensions:
  1. Activate_NetTalk - Activate CapeSoft's NetTalk.
  2. Activate_SafeUpdate - Activate CapeSoft Safe Update.
  3. Activate_Cryptonite - Activate CapeSoft Cryptonite.
  4. Activate_StringTheory - Activate CapeSoft StringTheory

2. Import the SafeDownload Function

Go to the Application -> Template Utility menu item and go to Class Safe Update - CapeSoft Safe Update.

Select ImportSafeUpdateDownloadABC (for ABC apps) or ImportSafeUpdateDownloadLegacy (for Clarion/Legacy apps).

A procedure, called SafeDownload will then be added to your application. Note that the names of this procedure must not be changed. You can however change the "look" of the window if you wish to.

3. Customize the Settings in SafeDownload

On the SafeDownload procedure extensions go to the Safe Update Download Controls local extension.

On the Files tab of that extension , fill in the URLs of update file, and the XML version file.

Note that the file names on this tab are either local, or HTTP. Not FTP. The download uses the HTTP protocol, not the FTP protocol.

The XML version file can have any name - it'll match the name you use in the SafeUp utility later on. (usually it's the same name as the update file, but with an xml extension.)

On the Verify tab enter the name of your certificate in the Must be signed by setting.

4. Add the Local extension to your Main procedure

Go to the local extension of your Main procedure.
Add the AutoUpdate - Safe Update Auto Update local extension. This will allow your application to check for updates automatically.

Optionally, if you would like a menu item, or button to trigger an immediate "check for updates", then create the item or button and enter the use equate for that control on the Manual Update tab.

Signing and Uploading Updates to your FTP server

Creating an Install File

The update being downloaded by your program is typically an Installer. The installer can be a custom executable or created with an install system such as SetupBuilder, Wise or even Visual Studio. Using a proper install system to create installers is highly recommended as it ensures that updates work well under all versions of Windows, including those such as Windows 8, Windows 7, Windows Vista and Windows Server 2008, which provide additional security and use UAC (User Access Control).

If you don't currently have an installer for your application, then you will probably need to create one using SetupBuilder, or your preferred tool.

Before creating the install for the new version increment the application version and build the app. If you are entering the version directly in the SafeUpdate global extension then change the version here, or if you are using a version resource then change it in the cwVersion Resource global extension.

SafeUpdate Utility

The process of signing and uploading the files is done by a utility called SafeUp3.Exe.
  1. Run the SafeUp.Exe utility. It looks something like this;

  2. The first thing to do, when running it for the first time, is to click on the Import Certificate (PFX Format) button. This will import the PFX file into the Windows Certificate Manager.



    If you have your own code signing certificate, then go ahead and enter the details for it here. You will need to know the password to the PFX file in order to import it correctly. If you do not have a certificate yet, then go ahead an import the Safetester.Pfx file (which is in the \examples\safeupdate\uploader folder). The password to this certificate is capesoft - one word, all lower case, no punctuation. You can leave the Store field blank.

    Once you have imported the certificate you can open the Windows Certificate Manager using the button provided. If you expand the Personal Certificates item in the tree, then you should see your certificate (or the Safe Update Test certificate) listed there.


     
  3. Ok, back to the SafeUp main screen. Time to add your product to the list. Click the Insert button to add a new entry for your install file. The form looks something like this;



    Note there are two tabs of settings, one to do with the signing, and the other to do with the FTP uploading.
  4. Enter the settings for the Installer and XML Version File
    Update File (Exe)The name of the Install file which contains the update.
    XML Version FileThe name of the xml file which will contain the version number, and signatures
    Update File VersionThe version of the update (if you are not using the File Version Resource)
    Read File Version from FileTick this on so that the file version as set by your install script is used.
    Signed ByThe name of the certificate. The example certificate name is Safe Update Test
    FTP ServerThe URL of the FTP server.
    FTP UserThe User Id required by the server (ie the server login)
    FTP PasswordThe password for the user.
    Update File DirectoryThe remote directory, on the server, where the update file must be placed.
    XML File DirectoryThe remote directory on the server where the xml file must be placed. (Usually the same place as above.)
    It's also probable that your install file is code-signed as part of the installer-creation process. The signature added by Safe Update does not "code sign" the installer, so you should continue to code sign the install file yourself as part of your build process.
    Click on OK to save the new record.
  5. Click on the Sign button if you wish to just create the signed files. A copy of the Exe will be created and signed, and the XML version file will be created and signed.
  6. Click on the Sign and Upload button to sign the file, and also upload it to the web server.

Examples

We strongly recommend using the JumpStart provided, as this provides the best way to get acquainted with the functionality provided by SafeUpdate.

Demo - Demonstrates downloading and verification of updated using SafeUpdate.

Certificate Information - Demonstrates retrieving certificate information. For certificate viewing and management use the tools provided.

Uploader - Signing and Uploading application. A compiled version of this SafeUp3.exe application is shipped with SafeUpdate and installed into the Accessory\bin directory (or 3rdparty\bin for Clarion 6 and earlier).

These examples are in your \Clarion\Examples\SafeUpdate directory. 

Getting a Digital Certificate

A Digital Certificate is needed in order to sign your update file. For SafeUpdate a Code Signing certificate is required (other certificates types can also be used, although a code signing certificate is recommended). For testing purposes free mail certificates can also be used.

Purchase a code signing certificate from a vendor such as Comodo. Other options are Thawte and VeriSign, although both are typically a great deal more expensive. Certificates can be renewed every year, two years, or three years. Purchasing a three year certificate is slightly cheaper per year. For SetupBuilder users, Comodo certificates can be purchased through Lindersoft for a major discount.

Comodo

Certificates cost (at the time of writing) $179/year, or $167 per year if a 3 year certificate is purchased. For SetupBuilder users purchasing Comodo certificates through Lindersoft brings the price down to $79 per year, $143 for 2 years, and $200 for three years.

http://www.comodo.com/e-commerce/ssl-certificates/code-signing-certificate.php

For Lindersoft SetupBuilder users, who need a code signing certificate to sign their application anyway, purchasing certificates through LinderSoft is a no-brainer (they also offer SSL certificates for securing web sites at a major discount):

Comodo allows the inclusion of a support email address in the certificate details (the only provider who does so at last check).

Verisign and Thawte

Verisign ($499/year): http://www.verisign.com/code-signing/index.html?sl=a_box

Thawte ($299/year, no three year option): http://www.thawte.com/code-signing/index.html

Installing Certificates

This section covers installation of PFX certificate files (which is the file format used by Windows). Certificates come in a variety of formats, and often the certificate will be provided separately from the private key. If your certificate is not provided as a PFX file then it can be converted to one - see Converting Certificate Formats.

Installing a PFX is as simple as double clicking on it and following the import wizard. You can also use either of the tools in the Viewing and Managing Certificates section below to install (import) and export certificates, as well as viewing their contents.

Alternatively you can use the SafeUp utility to import the certificate.

Viewing and Managing Certificates

Certificates and private keys are provided in a variety of formats, such as PFX, PEM, CRT etc. Converting between the various formats can be done using the tools provided with SafeUdate. See Converting Certificate Formats below.

Certificates can be viewed and managed using one of two tools:
  1. Certmgr.exe

    Provided with SafeUpdate and installed into the Clarion\3rdparty\bin\SafeUpdate (Clarion 6 and earlier) or Clarion\Accessories\bin\SafeUpdate (Clarion 7 and later) directory
  2. Certificate Manager Snap-in

    This is a snap-in for the Microsoft Management Console (MMC) included in most versions of Windows. Adding the snap-in:

    1. Choose Run from the Windows Start menu (or use the Windows+R hot-key).
    2. Enter "mmc" in the Run dialog and press Run to run the MMC
    3. From the File menu choose Add/Remove snap-in.. (Ctrl+M)
    4. Select Certificates from the list, click Add and then OK to add the certificates for the User account (repeat this to add the Computer account if desired). Click OK to close the Add/Remove dialog.
    5. Choose File->SaveAs to save this console for further use (the save file can be double clicked on to reopen the console with the Certificates snap-in).
Both tools allow you to view certificates as well as import and export them. The Console snap-in also allows certificates to be moved or copied between stores using drag and drop (hold the Control key while dragging to copy rather than move), and also allows you to view certificates for all stores rather than just the user store (although typically the User store will be used).

The screenshot below shows an example of a code signing certificate. The Subject field contains the details used by SafeUpdate for locating the certificate when signing and verifying.

In this case the CN (Common Name) and O (Organization) fields would be used to set the Signed By and Certificate Authority in the verification and signing settings.


Code Signing

Install tools such as SetupBuilder provide built in code signing support, which is the simplest approach. Code signing can also be done using the signtool.exe that SafeUpdate installs in the Clarion\3rdparty\bin\SafeUpdate (Clarion 6 and earlier) or Clarion\Accessories\bin\SafeUpdate (Clarion 7 and later) directory.

This tool can be called using a Wizard interface, on the command line, or automated using a batch file:

  1. Using the Wizard interface for signing
    • Run the SignTool.exe with the "signwizard" command line option, for example:

      c:\Clarion8\Accessory\bin\SafeUpdate\signtool.exe signwizard
    • This can either be directly on the command line (as above), or by adding "signwizard" to the Target of a shortcut to the tool.
  2. Signing on the command line
    • SignTool.exe sign /f mycertificate.pfx /p Password /t http://timestamp.comodoca.com/authenticode /d "Product Name" /du http://www.mywebsite.com /v C:\src\MyApp\*.exe
    • The options used are:
      • /f mycertificate.pfx - the name of the PFX file to use for signing
      • /p Password - where "Password" is the password for the PFX file
      • /t http://timestamp.comodoca.com/authenticode - timestamps the signature so that even when the certificate expires the signature will remain valid (highly recommended)
      • /d "Product Name" - the name of the product being signed
      • /du http://www.mywebsite.com - The URL of the company or product website (optional)
      • /v C:\src\MyApp\*.exe - what to sign, this can be a single file or use wildcards to specify multiple files. This signs all EXEs in a directory.
  3. Signing using a batch file
    • This is identical to signing on the command line except that the calls to SignTool are added to a batch file (a text file with the .bat extension). This batch file can be run to make the calls to SignTool each time that it is needed.

Converting Certificate Formats

Certificates and private keys are provided in a variety of formats, such as PFX, PEM, CRT etc.

SafeUpdate installs a folder called SafeUpdate in the Clarion\3rdparty\bin\SafeUpdate (Clarion 6 and earlier) or Clarion\Accessories\bin\SafeUpdate (Clarion 7 and later) directory. This contains a number of useful tools, including two specifically for certificate and key conversion: Using pvk2pfx

This tool allows a PVK private key file and CER certificate file to be merged into a PFX file. PVK and CER are common formats that keys and certificates are provided in. This tool also protects the private key password by wrapping the new PFX file with a new password that is then used to access the key within the file without the actual private key password ever being needed,

The pvk2fx tool is called on the command line as follows:

pvk2pfx.exe -pvk capesoft.pvk -pi PrivateKeyPassword -po NewPassword -spc capesoft.cer -pfx MyCompany.pfx

The above command line assumes that the CER and PVK files have been copied into the same directory as the pvk2pfx.exe.

The options are as follows: Using OpenSSL.exe The openssl.exe tool needs to be called on the command line:

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

Certificate Information

You will not need to get a certificate if you are only downloading files as the Update File will already have all the necessary certificate information embedded in it. However, if you want to check the the serial number of the certificate, then reading the following paragraph may be useful.

How to Find the Certificate's Serial Number

Open the Windows Certificate Manager. The easiest way to do this is Press Windows-R (Start / Run) and type CertMgr.Msc

This will display a list of all the certificate stores on your computer. The certificate you require should be in the 'Current User/Personal' store.
Double click on the certificate to open it. Then go to the Details tab of the certificate and highlight the Serial Number field. From here you can copy the serial number to the clipboard.

Programmer's Guide

  1. I want to check for updates on startup
    This option is already enabled by default when you add Safe Update to your application. However, you must make sure the AutoUpdate local extension has been added to your application's main window.
  2. I want to check for updates every couple of days
    Go to the SafeDownload procedure, to the Extensions, Auto tab, and enter the options there.
  3. I want the user to be able to check for updates manually
    See here in the JumpStart.
  4. I want to use Safe Update in a multi-DLL application

    The easiest approach is to add SafeUpdate to the exe app as normal.

    1. Add NetTalk, Cryptonite, SafeUpdate and StringTheory to the root DLL, setting their Multi-DLL settings as appropriate.
    2. Add Safe Update,Cryptonite, NetTalk and StringTheory to your EXE setting the Multi-DLL settings as appropriate.
    3. Import the SafeDownload procedure into the exe app.
  5. My application gets sent to the system tray when the window is closed. How can Safe Update shut it down properly?
    You'll have to add your own code in this case. You would probably set a global flag that would tell your application to shut down completely. Add your code to the event:SUshutdown event in your main window. You will need to add the AutoUpdate extension to your main window first.

The Global Extension

Global General Tab

Disable All Safe Update features
Disables all Safe Update code, useful for debugging to find out whether a problem is being caused by Safe Update.

Debugging
Display Errors
Errors will appear
Log Errors

Version Tab

Use WinEvent to extract from Version resource
If you have WinEvent added to this application, then you can check this box for WinEvent to detect the version of this exe. This means you can use an external version resource generator to apply the version resource to your application.

Program Version
The current version of this application. This can be any string, so long as it is fewer than 40 characters long.

Tip: The global variable SafeUpdate:AppVersion is set when your program starts (using either WinEvent or the template setting) so that it can be used in your program - like on Help / About screens and so on.

Program Name
Used for display purposes only. This name will appear at various places in the SafeDownload window.

Multi-DLL Tab

This is part of a Multi-DLL program
Check this box if the application has multiple DLLs and Safe Update has been added to the root DLL. If this section of the application is a DLL this will be ticked as the default.

Export Class from this DLL
Check this box if this section of the application is the root DLL of a multi-DLL application.

Local Extensions

The AutoUpdate Extension

This extension is added to the Main procedure in your application.

OptionsTab

Manual Control
Select the menu item, or tool bar control, that will allow the end user to trigger an update manually.

Auto check on startup
You can enter an expression here. If it evaluates to true, then the download window will (silently) check for an update when your program starts. (The user will be informed if an upload is available.)

The SafeDownload Control Template

This extension is added to the Safe Download procedure.

Options Tab

Update File
The path to the update file. Can be either a file on the LAN, and intranet URL or a web URL.

XML version file
The path to the version file. Can be either a file on the LAN, and intranet URL or a web URL.

Local Folder for downloaded files
By default downloaded files will be placed (if validated) in the temp folder. However if you want accepted files to be placed in a specific folder then you can enter it here.

INI File
Some settings are stored in an INI file. Enter the ini file name here/

Ask User before Downloading
If this is on then the user will be asked before an update file is downloaded. (The user will always be asked before an update file is applied.)

Installer: Run the following file instead
If the file being downloaded is not an install file, and a separate install program exists, then you can enter that alternate program name here.

Run the program with the following parameters
Allows parameters to be passed to he downloaded file (or alternate installer file) when starting the update.

Auto Tab

Do Automatic Checking
If this is on then the program will continue to check for new versions automatically, at regular intervals.

Check every (days)
Detemine the number of days between checks. Set this to 1 to do a check every day.

Check from Midnight To
this will randomise the check between midnight and some specific time every day. By randomizing the check the server is not overloaded by all the sites checking at the same time. A typical value here is say 4:00 which means that all sites will do their check sometime between midnight an 4am.

Verify Tab

Must be signed by:
Enter the name of the signer who will sign the updates here. Setting this is highly recommended

Cert Authority
(not currently used). This will be used to limit certificates to those issued by a specific authority. Using this will reduce your ability to change to a new certificate authority in the future.

Cert Serial Number
(not currently used). This allows you to require that the update is signed by a certificate with a specific serial number for added security.

Errors to check
Various items in the certificate which should be checked. It is recommended that all these options are set on.

Failure Option
(not currently used). Currently if a certificate check fails the update is discarded.

Objects Tab

Enter the name of the class, and the name of the object to use here. Usually you can, and should, leave the default values as they are here.

Version History

Download latest version here Version 2.02 Beta (23 December 2011)
Requires Cryptonite 1.42 or later.
Version 2.01 Beta (23 December 2011)
Requires Cryptonite 1.24 or later.

Version 2.00 Beta (15 April 2011)

Requires Cryptonite 1.15 or later. Version 1.27 (18 March 2010)
Version 1.26 (7 January 2010) Version 1.25 (8 September 2009) Version 1.24 Beta (1 September 2009 ) Version 1.23 Beta (28 April 2009 ) Version 1.22 Beta (06 January 2009 ) Version 1.21 Beta (10 November 2008) Version 1.20 Beta (21 August 2008) Version 1.16 Beta (31 August 2007) Version 1.15 Beta (12 June 2006) Version 1.14 Beta (24 April 2006) Version 1.13 Beta (23 January 2006) Version 1.12 Beta (6 December 2005) Version 1.11 Beta (25 November 2005) Version 1.10 Beta (16 November 2005) Version 1.09 Beta (21 October 2005) Version 1.08 Beta (6 October 2005) Version 1.07 Beta (4 October 2005) Version 1.06 Beta (3 October 2005) Version 1.05 Beta (29 September 2005) Version 1.04 Beta (23 September 2005) Version 1.03 Beta (21 September 2005) Version 1.02 Beta (20 September 2005) Version 1.01 Beta (16 September 2005) Version 1.00 Beta (14 September 2005)

License & Copyright

This template is copyright 2012 by CapeSoft Software. None of the included files may be distributed. Your programs which use Safe Update can be distributed without any royalties.

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft Software, their employees or affiliates be liable in any way for any damages or losses you may incur as a direct or indirect result of using this product.