 |
 |
||
 |
|||
Version
  www.capesoft.com Updated |
 |
||
 |
 |
 |
 |
|
 |
Introduction
| Introduction | |||
|
|
Safe Update allows you to upgrade your program over an
internet connection securely and automatically.
Safe Update is just the template you
need when you want
your applications to update themselves automatically, either from the web or a local
server. It has been designed to be quick and easy and requires no extra coding
for most applications.
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 appended to both your Update File and the Version
file.
Safe Update is a versatile product that can be used in any
application that requires downloading any
signed or unsigned files from local or remote sites.
Safe Update supports Clarion 5.5 and later, both ABC and Legacy.
Clarion 5 is not supported.
|
||
| Technical Reference | ||
|
|
||
Safe Update 2 introduces new Client/Server updating functionality. This allows the Safe Update Server to download updates, which are then distributed to all client application on the LAN using a direct TCP/IP connection. It also provides automated notification to running clients to allow them to close down and restart when a new update is available, ensuring that all instances of the client application on the network are the same version. Client applications download and install updates at startup, ensuring that they are always running the latest version.
Safe Update 2 is now based on CapeSoft CryptoNite and StringTheory. This means that your installs are a lot more safer and free from potential site hackers.
Safe Update 2 provides a new set of streamlined classes; numerous performance improvements and bug fixes; and additional templates and template options.
Read the Upgrading from Safe Update 1 section on what you need to do to your application when upgrading to Safe Update 2.
Read the Client/Server Updating section of the docs to implement the Client/Server functionality into your applications.
The prototype and parameters for the SafeDownload procedure need to be changed to:
(string pOnStartup, string pXmlFileName, string pVerifyFiles)
Not doing this will result in compile errors:
Syntax Error: Unknown Identifier: pVerifyFiles
Syntax Error: Unknown Identifier: pXmlFileNAme
Syntax Error: Unknown Identifier: pOnStartUp
Welcome to CapeSoft SafeUpdate, the easy way to add secure updating to your Clarion applications. 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.
There are three basic areas of functionality that SafeUpdate provides:
1. Application Updating (Downloading)
This includes downloading an update, either from the internet or LAN and performing whatever task is required to install that update (usually running an installer and closing down the application to allow the install to update it). SafeUpdate handles checking for updates, downloading and verifying updates for you.
2. Uploading
This is simply the process of getting the update (your application installer) to the location that the application will download it from (typically the web). It includes uploading the application; the process of Cryptographically signing it; and creating a signed XML Version File that the Download part of SafeUpdate uses in your app to verify that the update is from a legitimate source and has not been tampered with.
3. 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.
The JumpStarts guide you through the basic process of adding SafeUpdate to your application and uploading updated. The second part of the JumpStarts introduce Certificates and how they are used to secure and validate updates.
Application Updating (Downloading)
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:
- Adding the global extension
- Adding the local extension
- Importing the SafeUpdate functions
- Entering the Download settings
Adding Safe Update to your Application. (For Multi-DLL applications take a look at FAQ 6)
To add the Safe Update template to your program, add the following to your application's Global Extensions:
- Activate_NetTalk - Activate CapeSoft's NetTalk.
- Activate_SafeUpdate - Activate CapeSoft Safe Update.
NOTE
-
For all the following steps, use single-quotes around the parameters that are
not variable names.
- 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).
Two procedures, called SafeDownload and SafeAutoUpdate will then be added to your application. Note that the names of these procedures must not be changed.
- 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.
- On the SafeDownload
procedure extensions go to the Safe Update Download Controls local extension of the .
In the Files tab, fill in the URLs of your Update File (the URL that your application installer will be downloaded from) and the XML Version file (the URL that the version file that SafeUp will create for you will be downloaded from).
NOTES
-
The Update File will be the signed Installer file that is the latest version. The SafeUp application provided with SafeUpdate will sign and upload this for you (this is covered in the Uploading section of the JumpStart below). For example: 'http://www.capesoft.com/ftp/public/MyAppInstall_signed.exe'.
-
To differentiate between the signed and unsigned installers SafeUpdate adds '_signed' to the end of the installer file name, so in the example above the installer file is call MyAppInstall.exe and SafeUp creates a new file called MyAppInstall_signed.exe that will be uploaded.
-
The XML Version File is also created by SafeUp when signing your application. You can give it any name that you prefer, such as the same name as the Installer, except with the XML file extension. For example: 'http://www.capesoft.com/ftp/public/MyAppInstall.xml'.
-
- Go to the Global Extension Options
tab in the global extensions window. Enter the program name
(e.g. 'Safe Update Demo') and
version (e.g. '1.00') on the Options tab.
NOTES- You can use a variable for any of the template settings.
- The version number can be in any form (for example '1.00', '1.00.001' or '1.00 beta 2').
- You'll need to change the version number with every release of your program.
- You can use an external Version Resource file, or a Version Resource compiled into the application (which requires CapeSoft WinEvent to extract the version number). Using an embedded version resource along with WinEvent is recommended and is the simplest way of managing the version numbers. It has the added benefit of allowing the version and other details to be displayed in the Properties for the program in Windows Explorer. See Adding a Version Resource below for a step by step guide.
Finished!
You've now finished part 1 of 2 (the download)! When your application runs it will check for any updates. However, there are presently no updates because you haven't created or uploaded them. Never mind: Safe Update can do it all for you. Proceed to the Uploading Jumpstart to complete the next step.
Adding a Version Resource (optional)
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).
Clarion 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.
-
Add the global extension: cwVersionRes - Version Resource
-
Enter the details for your application, including the version number (this should be updated each time you update your application to a new version)
-
Add the WinEvent global extension to your application
-
In the SafeUpdate Global Extension on the Options tab tick the "Use WinEvent to extract from Version resource"
Technical Information
For those who require the technical details of the
implementation the Programmer's Reference Introduction
has been provided.
Uploading
This section of the JumpStart is made of two parts:
Part 1: Basic Uploading
Part 2: Certificates and Secure Updating
Although you can do both at once they simplest approach is to ensure that the basic process of uploading and retrieving an update is working before moving on to adding a certificate and securing the process (especially if you are not familiar with digitial certificates).
We've done all the hard work for you in creating an Uploader (SafeUp) for your applications. This provides the creation of the XML Version File, allows the Update Installer and Version File to be signed (if a certificate is specified), and allows the files to be uploaded via FTP.
Part 1: Basic Uploading
The first step is to disable Verification in the Application. This will be enabled in the second section of this JumpStart.
Go to the Extensions for the SafeDownload procedure (right click on the procedure and choose Extensions)
-
Go to the Properties for the Safe Update Download Controls extension (double click on the extension name in the list)
-
On the Verify tab set the "Verify the file signature" option to 0 (zero).
The creation of the XML Version File and the uploading of the Installer is done using the SafeUp application provided with SafeUpdate.
The update being downloaded by SafeUpdate is typically an Installer. The installer can be a custom executable or created with an install system such a 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 Vista, Windows 7 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 need to create one using SetupBuilder, or your preferred tool.
Before creating the installer 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.
Once you have built the installer set the version number back to the previous version for testing. If you don't set the version back then the application won't update, as there won't be a newer version to download.
There are a number of free Install creators available for commercial use. The following are free, have no royalties or license requirements, and don't display any advertising on the installer. Please note that we do not provide support for any of these application (refer to the application websites for support options), and we don't recommend a specific install solution.
Free GUI based install builders
Install Jammer - http://www.installjammer.com/
Free script based install builders (no GUI)
InnoSetup - http://www.jrsoftware.org/
NSIS - http://nsis.sourceforge.net/Main_Page
Ghost Installer Free - http://www.ethalone.com
Creating an XML Version File and Uploading the update
Run the SafeUpdate Utility (SafeUp) application provided with SafeUpdate
NOTES
-
The SafeUpdate Utility (SafeUp.exe) is installed into \Clarion\3rdparty\bin (Clarion 5.5/6) or \Clarion\Accessories\bin (Clarion 7 and 8).
-
A shortcut to the SafeUpdate Utility is placed in the Start Menu under All Programs->Clarion Accessories->Safe Update->SafeUpdate Utility
-
In Clarion 7 and up SafeUp can be accessed directly by selecting the menu Tools->CapeSoft Tools->SafeUp utility
-
Click the New button to add a new entry for your app
-
Enter the settings for the Installer and XML Version File
Update File
Enter the name of the installer for the update
XML Version File
The XML file to create with the version information. This file will be signed when a certificate is used (See Part 2 of the Jumpstart)
Update File Version
The version of the update (if the Read File Version From File is not being used).
Read File Version From File
This reads the version resource from the file itself and is the recommended option.
Note: The additional Signing options will be covered in Part 2 of the Jumpstart.
-
Enter the settings for the FTP server to upload the file to. This is optional - uploading can be done using a different process (such as a batch file, scripting system, manually using an FTP client etc.).
FTP Server
The address of the FTP server to upload to.
FTP User/FTP Password
The User name and password to log into the FTP server with
Update File Directory\XML File Directory
Optional directory to upload the signed installer\XML Version file to (blank for the default directory on the server).
Unsigned Update Dir
Optional directory on the FTP server to upload the unsigned version of the installer to if desired.
-
Click OK to save the setting and then click the Sign button to create the copy of the installer and the XML version file or the Sign and Upload button to also upload the created files.
NOTE
- Because no Certificate is specified yet the Sign button won't actually sign the installer - it will create an XML version file without a signature and a copy of the installer with "_signed" added to the file name. Essentially the signature is blank in this case. A Certificate and signature will be added in Part 2 of the guide. This is useful for testing the basic process of creating the XML file and downloading updates in the application.
You will now have an XML version file, a "signed" installer and the application is ready to update. The update process can now be tested by running the "old" version of the application (don't forget to upload the files first, either using the Sign and Upload button in SafeUp or manually if you prefer).
Part 2: Securing the Process using Digital Certificates
The second part of the process involves using a digital certificate to sign the Update Installer and the XML Version File. This is a simple two step process that involves entering the certificate information in the application and SafeUp utility.
NOTES
In addition to securing your updates the code signing certificate can also be used to sign your code (primarily executables, but also DLLs and so on). This is recommended and covered in the Code Signing section of the documentation.
Once you have a certificate this is a simple process. See "Getting a Digital Certificate" below if you don't have a code signing certificate.
The first step is to enable Verification in the Application. This was disabled in the first part of the JumpStart to test updating without the code signing and verification part.
Go to the Extensions for the SafeDownload procedure (right click on the procedure and choose Extensions)
-
Go to the Properties for the Safe Update Download Controls extension (double click on the extension name in the list)
-
On the Verify tab set the "Verify the file signature" option to 1 (one). Enter the setting for verification (leave the Serial Number field blank):
-
Must be Signed By: The name of the company or organization that the certificate was issued to.
NOTES
-
For code signing certificates this is typically the company/organization name. For free email certificates this is the email address (we don't recommend using free email certificates for this process).
-
This value is stored in the Common Name ("CN=") or Organization ("O=") sections of the Subject field of the certificate.
-
See Viewing and Managing Certificates for more information on how to view certificate properties, as well as installing and managing certificates.
-
-
Cert Authority: This optional field can be set to the Organization ("O=") section of the Subject.
NOTES
-
For most code signing certificates this will be identical to the Must be Signed By and contain the company name that the certificate was issued to. For Free Email certificates this is the name of the certificate issuer such as "Thawte".
-
-
Adding the Certificate Details to the SafeUp utility
Run the SafeUp utility and open the entry for the application. On the Signing Tab the fields are identical to those filled in on the local extension in the section above, namely: Certificate Authority (optional) and Signed By. Leave the Serial Number field blank.
-
Click OK to save your changes and press the Sign button to create the signed installer and XML Version file.
Your updates are now signed and secure - the update can be uploaded for testing (don't forget to increment the version before creating each update to ensure that the app detects a new version and downloads it).
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
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.
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:
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) directoryCertificate Manager Snap-in
This is a snap-in for the Microsoft Management Console (MMC) included in most versions of Windows. Adding the snap-in:-
Choose Run from the Windows Start menu (or use the Windows+R hot-key).
-
Enter "mmc" in the Run dialog and press Run to run the MMC
-
From the File menu choose Add/Remove snap-in.. (Ctrl+M)
-
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.
-
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.
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:
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.
- Run the SignTool.exe with the "signwizard" command line option,
for example:
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.
- 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
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 converion:
pvk2pfx.exe: Convert a PVK (Private Key) and CER (Certificate) to a PFX file
-
openssl.exe: The OpenSSL tool for converting between a wide variety of certificate formats.
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:
-
-pvk: The PVK file that contains the private key
-
-pi: The password for the private key (PVK file)
-
-po: The new password that will be used for the PFX file created
-
-spc: The certificate to include in the new PFX file.
-
-pfx: The name of the PFX file to create
Using OpenSSL.exe
-
Converting a PFX to PEM, CRT and KEY files.
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
-
OpenSSL Convert PEM
Convert PEM to DER
openssl x509 -outform der -in certificate.pem -out certificate.derConvert PEM to P7B
openssl crl2pkcs7 -nocrl -certfile certificate.cer -out certificate.p7b -certfile CACert.cerConvert PEM to PFX
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crtOpenSSL Convert DER
Convert DER to PEM
openssl x509 -inform der -in certificate.cer -out certificate.pemOpenSSL Convert P7B
Convert P7B to PEM
openssl pkcs7 -print_certs -in certificate.p7b -out certificate.cerConvert P7B to PFX
openssl pkcs7 -print_certs -in certificate.p7b -out certificate.ceropenssl pkcs12 -export -in certificate.cer -inkey privateKey.key -out certificate.pfx -certfile CACert.cerOpenSSL Convert PFX
Convert PFX to PEM
openssl pkcs12 -in certificate.pfx -out certificate.cer -nodesYou can add -nocerts to only output the private key or add -nokeys to only output the certificates.?
This section covers functionality new to SafeUpdate 2 that provides simple client/server downloading and updating across a network. The Server application downloads updates and stores them, as well as informing any running clients of new updates. The Client application checks the server for new updates, and downloads them across the LAN.
The ClientServer demo application demonstrates this functionality and is highly recommended.
Building the Client
Building a client application is a simple two step process and should take around two minutes.
- Add the SafeUpdate Global Extension to your application (SafeUpdate requires NetTalk so the global extension for NetTalk should also be added).
- Run the Import SuUpdateCheck (ABC or Legacy
depending on your application) utility template to import the SuUpdateCheck
procedure into the application.
- Right click on the SuUpdateCheck procedure and choose Extensions. Under the Safe Update Client extension enter an address for the update server. This is the address on the network on the machine that will run the SafeUpdate Server. By default this is set to '127.0.0.1' for testing, which is the local machine. This can be an IP address or machine name, and a string literal or variable name can be entered.
That's it, your application is now ready to update from a server.
Optional (recommended): Handling automatic close messages from the server. This allows the application to close down automatically when a new update is available, insuring that all clients on the network are up to date.
- Add the Safe Update Client (Auto Close) local
extension to your main procedure (or Frame for MDI applications).
- Set the "Unique Application Name" on the local extension to your application name (this identifies your application across the network for handling automatic application closedowns when a new version is available).
Building the Server
The SafeUpdate Server application is very similar to a standard SafeUpdate application - it downloads an update, verifies the signature and stores the update. In addition is handles client requests for updates and provides the updates over the network as needed; and it informs clients when new updates are available, allowing them to close down so that the new update can be retrieved and installed when they restart,
- Add the SafeUpdate Global Extension to your application (SafeUpdate requires NetTalk so the global extension for NetTalk should also be added).
- Run the ImportSafeUpdateDownload (ABC or Legacy depending on your application) template utility to import the procedures required for automatic updating (SafeDownload and SafeAutoUpdate).
- Right click on the Main procedure and choose Extensions. Add the
following extensions:
- Safe Update Server
- Enter your application name in the "Unique Application Name" field on the local extension. This is the same name that was entered in the Safe Update Client (Auto Close) extension for the Client.
- Safe Update Auto-Update
- Safe Update Server
You now need to configure the downloading options. Right click on the SafeDownload procedure in your app and choose Extensions. The options are listed under the Safe Update Download Controls template.
- Tick the "This is a SafeUpdate Server Application" checkbox on the general tab. This will ensure that the downloading is performed as a SafeUpdate Server, rather than as a standard client. The rest of the options are identical to the normal Download options provided by SafeUpdate. Below is a description of the available options.
 |
Update File The Update installer to download. Typically this is downloaded from a URL such as 'http://www.capesoft.com/ftp/public/EmailServerInstall.exe', however if may also be a local path. XML Version File The URL or path to the XML version file for the download. This file is created by the SafeUp application and is used to check the version and verify the signature.
|
 |
Download and Install Always set to 1 for Server applications Store file after download Always set to 1 for Server applications Keep Signature Attached If this is set to 1, then the digital signature is not removed from the download. It is recommended that this is left as 0 (the signature has already been verified once the installer has been downloaded and the signature is no longer required). Storage Location The location to store the downloaded file on the server Turn Caching off Turns HTTP caching off. Can help in situations where cached versions of the file are being downloaded.
|
 |
Verify the file signatures If ths is set to 1, then the digital signature of downloaded files is verified. This is recommended, as it ensure that the files have not been tampered with, and that the files are from the correct source. Must be signed by The name of the signer (the Common Name in the certificate used for signing). Cert Authority The name of the certificate issuer Cer Serial Not currently used Errors to Check These provide options for how the signature is validated Action if signature fails What action to take (if any) if the signature cannot be verified. |
1) I want to add updating to my application
2) I want to check for updates on startup
3) I want to check for updates every couple of days
4) I want the user to be able to check for updates manually
5) I want to use Safe Update to sign and upload my application update file
6) I want to use Safe Update in a Multi-DLLapplication
7) My application gets sent to the system tray when
the window is closed. How can Safe Update shut it down properly?
8) Stopping SafeDownload when the application closes
9) How to get your application to find the version embedded inside an XML file
10) I want to generate a version for my application externally
11) I want to create my own Uploader.
For more information, please see the FAQ section.
1) I want to add updating to my application
You will need to follow the Download JumpStart.
Some useful information on how Safe Update works can be found in the Introduction
in the Reference Manual.
2) 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.
3) I want to check for updates every couple of days
Go to the Global Options Tab and make sure
Enable Auto Update is checked. Set Check Every x Days
to the interval between update checks.
For client application updating from a SafeUpdate Server this does not apply, as the client will update on startup, or as soon as the server revieves a new version (this setting applies to the Server itself in that scenario).
4) I want the user to be able to check for
updates manually
Add a control to your window, such as a button or menu item, labelled, for
example, 'Check for Updates'. Go to the control's Accepted embed and add the SafeDownload
- Start Safe download (new thread) embed.
5) I want to use Safe Update to sign
and upload my application update file
Go to the Global Options Tab and make sure the
Program Version is a literal string (or is being read from a cwVersionRes
file). Now compile your application.
As you do this, the XML version file for your application will be automatically
generated. Now make your update file as you usually do, using your favourite install-generator,
e.g. Wise or Setup Builder.
Finally, you will need to use SAFEUP to sign and upload your update file. SafeUp ships with SafeUpdate and allows you to add as many program to the database of as you like, so you can simply select the application that you want to sign and upload and press one button to do it all for you.
6) I want to use Safe Update in a multi-DLL application
- Add the global extension for SafeUpdate and NetTalk to the DLL and EXE apps.
- In the root DLL:
- On the Multi-DLL tab of the global extension tick the "This is a part of a Multi-DLL program" checkbox and the "This is the Root DLL" checkbox.
- Import the SafeUpdate Download procedures using the template utility (if you have not already done so).
- In the EXE app:
- On the Multi-DLL tab of the global extension tick the "This is a part of a Multi-DLL program" checkbox and enter the name of the DLL in the "The root DLL name" entry.
Alternatively you can add SafeDownload in the EXE and leave it out of the DLLs. This requires the following options:
- Added NetTalk to the root DLL.
- Add Safe Update and NetTalk to you EXE.
- Make sure that the options in the Multi-DLL tab in the Safe Update Global Extension are left unchecked.
7) My application gets sent to the system tray when the window is
close. 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.
8) Stopping SafeDownload when the application closes
The way to ensure that SafeDownload has closed is to add the AutoUpdate
extension to the application's main procedure.
9) How to get your application to find the version embedded inside an XML
version file
See the SafeDownload Procedure documentation on
how to do this.
10) I want to generate a name and version for
my application externally
Safe Update can use the version file created by the cwVersionRes - Version
Resource global template. The relevant lines from this file are (for example):
PRODUCTVERSION 1,2,3,4
VALUE "PRODUCTNAME", "My
Application\0"
11) Creating your own Uploader
This section shows you how to add Safe Update to your application if you want to write code to sign and upload files.
Adding Safe Update to your Uploader Application.
To add the Safe Update template to your program, add the following to your application's Global Extensions:
- Activate_NetTalk - Activate CapeSoft's NetTalk.
- Activate_SafeUpdate - Activate CapeSoft Safe Update.
Some global parameters will need to be changed in order to get Safe Update working, but only after the next steps.
NOTE: For all the following steps, use single-quotes around the parameters if they are literal strings. If they are variables, leave the single quotes off.
Steps for Uploading
- Go to the Application | Template Utility menu item and go to Class
SafeUpdate - CapeSoft Safe Update. Select ImportSafeUpdateUploadABC or
ImportSafeUpdateUploadLegacy. Two procedures, called SafeUpload and
SendFTP, will then be added to your application. Note
that the names of these procedures must not be changed.
- Add the Call
Safe Update Upload (new thread) code embed to your application where
you want the upload to be called from.
- Fill in the options in the
local extension of the SafeUpload Window as
follows. In the Files tab, fill in the names of the Update
File and the XML version file, including their paths (local or remote). Fill in the
version number of the Update File. This will most probably be a variable or an equate.
- In the Signature tab enter the name of the Digital Certificate owner. This
will be your email address or your name, depending on the type of certificate you own.
- Enter the name of the issuer of the digital certificate, or Certificate Authority (CA). This is a part, or all, of the full identity string of the CA. For example, instead of entering the entire string 'Thawte Personal Freemail CA', you could just enter 'Thawte'. Leave the single quotes in. To get the issuer string, see the Certificate Information section
Filling in the Global Parameters
You now need to fill in the options in the Global
Extension Options tab. Enter the program name and version of your uploader
application. All the other options can be left alone.
Finished!
You're now finished setting up Safe Update for uploading. Reading the Introduction and its associated paragraphs will help
you understand the workings of Safe Update better.
The Global Extension
The SafeDownload Control Template
The SafeAutoUpdate Control Template
The SafeUpload Control Template
The SendFTP Control Template
See the Jump Start for information on how to add the Global Extension. The global extension allows you to set the default listbox style for your application.
NOTE: Most of the options shown in the Global Options Tab correspond to user-settable options using the SetOption method in the global SUpdate class.
Global General Tab
Global Options Tab
Global Multi-DLL Tab
Global Save & Load Tab
Global Classes Tab
| Global General Tab | |||
 |
|
||
| Global Options Tab | |||
 |
Enable downloading Use external file for version External File Use WinEvent to extract from Version resource Program Version If this string is a literal, it is stored in the global equate SafeUpdate:AppVersion. Program Name Enable Auto-update (SuOpt:AutoUpdate) Check every X days
(SuOpt:UpdateFreq) Randomize update time (SuOpt:RandomStart
and SuOpt:RandomEnd) Note: that the random download time will change for every update unless the start and end times are the same. Note: also that randomizing the update time is only meaningful if Check Every X Days is non-zero. Enable Signing and Uploading Display Errors Log Errors (SuOpt:LogErrors) |
||
|
Templates Loaded
|
|||
|
|
|||
| Templates not yet loaded. |
|||
| Global Multi-DLL Tab | |||
|
|
This is part of a Multi-DLL program See the FAQ for more details. This is the Root DLL This option is only activated if the Multi-DLL checkbox is ticked. NOTE: the Options, Load & Save and Classes tabs are not available if this section of the application is a DLL. |
||
| Global Save & Load Tab | |||
|
|
Save Settings Which Storage Method? Save in Program's INI INI File Name
Registry Folder (SuOpt:RegistryFolder) IfOther is checked, the registry entry must not be blank. This entry may be a variable or a literal string, as shown in the figure. |
||
|
Save settings in an INI file |
|||
|
|
|||
|
Save settings in the registry |
|||
You will not need to get a certificate if you are only downloading files: the Update File will already have all the necessary certificate information embedded. 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
Safe Update ships with Certificates.msc (Start->Program Files->Clarion Accessories->SafeUpdate->Certificates Manager).
This will launch the Microsoft Certificates Manager (you could also
open the file CERTMGR.MSC, which is found in the
Windows\system32 directory).
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. Go to the Details tab of the certificate and highlight the Serial Number field. The serial number will appear in the lower listbox. You can now cut and paste the serial number into the template, remembering to enclose it in single quotes.
The template makes provision for three different formats of serial number. Examples are:
- 01 02 03 04 05 (space delimiters)
- 01:02:03:04:05 (colon delimiters)
- 0102030405 (no delimiters)
The 2nd format is useful if the certificate is viewed in an Internet browser.
We strongly recommend using the JumpStarts provided, as this provides the best way to get acquinted with the functionality provided by SafeUpdate.
Demo - Demonstrates downloading and verification of updated using SafeUpdate.
ClientServer - Demonstrates creating a SafeUpdate Server and Client which downloads new client updates it and distributes it to the client over the network.
Certificate Information - Demonstrates retrieving certificate information. For certificate viewing and management use the tools provided.
Uploader - Signing and Uploading application. A compile version of this SafeUp.exe application is shipped with SafeUpdate and installed into the Accessory\bin directory (3rdparty\bin for Clarion 6 and earlier).
Client/Server Demo (Deprecated)
These examples are in your \Clarion\3rdParty\Examples\SafeUpdate directory.
Demo
This is intended to simulate how the uploading and downloading operates. You won't need an FTP site to run the example, since all the files are stored on your PC. However, you will need a Digital Certificate (you can use the certificate that ships with SafeUpdate for testing). See the Upload JumpStart for information on how to get your own certificate for signing your programs.
Directory
Structure
Inside the demo directory there are two sub-directories:
- .\THEWEB: Simulates an FTP or web site where the update files are stores.
- .\NEWSAVE: The directory where the downloaded
files are saved before installation.
The
Applications
There are two applications in this demo. They have been kept as simple as possible (no fancy graphics).
- Demo.APP: The program that is to be updated. This does nothing
more than display some help text and an update button. To check for updates for
this application, click the relevant button.
- Install.APP: This acts as a basic installer program. An
explanation of what it does is shown below in step 9. The installer doesn't
contain any Safe Update code. A separate installer would not normally be
needed if the update file were an EXE file. The installer uses an INI file to specify the source and destination files.
This installer is called by SafeUpdate to copy the new update over the old
program, then run the new version.
How
to Make It All Work
Follow these instructions to get the demo working. With version 1.13 we have greatly simplified this, allowing you to easily get the hang of how SafeUpdate works.
- Compile the Demo.app. This will produce a "version 1.00" demo.exe. This is the program that you run.
- If you did not install a certificate when you installed SafeUpdate you will need to install one. The Demo assumes you are using the safetester@capesoft.com certificate for testing.
- Run the Demo.exe and press the "Check for Update" button.
And that's it! The program downloads and installs a new version, then runs the new version. When it checks for a new version and does the download the signature of the file is checked to ensure that the download is valid.
Explanation
Typically, what you would do to update your program would be to create an EXE file using Wise or another commercial install generator. To keep things simple, this was not done in this demo. This means that the download options in the demo are slightly different to the options you would set if you had used an install generator.
The SafeDownload options for DEMO.EXE are shown in the screenshot below.
 |
|
SafeDownload options for Demo |
In the above screenshot you will notice that the SafeDownload options have the Run Separate Installer option checked (in the Download tab). If you had used an install generator you would check the Run Update After Download option instead. Storing the update file would also be optional.
Client/Server
Demo
It is recommended that you go through the first demo before you attempt this one, as it is very similar and a little easier. See the Client/Server section for full instructions on creating a client and server.
Certificate Information
This is a small application that lets you read the certificate information in any file, even those that have not specifically been signed by Safe Update. See the screen shot below for an example.
Local
Extensions
The
AutoUpdate Extension
This extension adds code that allows your application to:
- Check for new updates automatically.
- Shut down after launching an update file.
- Check for client updates if this is a server application.
You will normally add it to the first window that opens, e.g. Main(). This extension cannot be added to source or report procedures.
| AutoUpdate Extension General Tab | |||
|
|
The extension that must be added to your application's main procedure when using Safe Update.
|
||
Embed points added by the Auto-update
The Safe Update Template Utility
These templates are at the heart of Safe Update. You will need to load one of these templates into your application in order to download your files. See the JumpStart for more information.
To load the Download template into your application, open the Application | Template Utility menu option and select the ImportSafeUpdateDownload utility (ABC or Legacy), as shown in the picture below. Doing this will create the windows SafeDownload and SafeAutoUpdate, with a Safe Update control template associated with each one.
Control Templates
The SafeDownload Control Template
The SafeAutoUpdate Control Template
The SafeUpload Control Template
The SendFTP Control Template
The Update Process for client/server applications
The SafeDownload Procedure
The SafeDownload Control Template
This allows you to download files from a remote site using HTTP, or a local site. To add this template, follow the steps shown in the Template Utility section.
Setting the options for this template can be done for a number of configurations:
- A computer connected to the web (no server).
The path to the files would be a web URL. The user may optionally be prompted to allow downloads and auto-installation. Storage of the download file would be optional.
- An office network where there is a server looking for web updates.
The server would download the files from the web to a pre-specified location. No user prompts would be displayed. The global auto-update frequency would be set to a non-zero number of days.
The client would then download the files from the server. User prompts would optionally be displayed, but saving of the files on the client computer would probably not be necessary.
NOTES:
- The options shown in this section all correspond to
user-settable options using the SetOption method
in the global SUpdate class.
- All boolean options can be assigned a variable by clicking on the Var
button in the template extension corresponding to the option (see the
pictures below).
- Safe Update will automatically distinguish between a local and an HTTP path.
SafeDownload General Tab
SafeDownload Files Tab
SafeDownload Downloading Tab
SafeDownload Verification Tab
SafeDownload Client/Server Tab
The update process for client/server applications
| SafeDownload General Tab | |||
|
The general tab for the SafeDownload template control. |
||
| SafeDownload Files Tab | |||
|
Update File (SuOpt:MsgdownFilename) XML version file (SuOpt:XMLdownFileName) XML version tag (obsolete) (SuOpt:XMLVersionTag) |
||
| SafeDownload Downloading Tab | |||
|
Note: the two screenshots in this table show the boolean variables as constants and the second as variables. By clicking on a Var button, the corresponding field will change between a check box and a expression field. You'll want to do this if you're setting the options with a runtime variable - but most of the time you'd simply use the checkboxes (i.e. template settings). Ask before getting new
version (SuOpt:AskUser) Run update after download (SuOpt:RunFileAfterDownload) Run Separate Installer (SuOpt:RunInstaller) Installer Program (SuOpt:Installer) Ask before running update (SuOpt:AskBeforeInstall)
Store file after
download (SuOpt:StoreFileAfterDownload) Keep signature attached (SuOpt:KeepSignature) Get location from user (SuOpt:UserSaveLocation) Storage location (SuOpt:StoreLocation) Turn caching off (SuOpt:CacheOff) Hide the file path details while downloading |
||
|
Tab shown with no Var buttons checked. |
|||
|
|||
|
Tab shown with all Var buttons checked. |
|||
| SafeDownload Verification Tab | |||
|
Note: the two screenshots in this table show the boolean variables as constants and as variables.
Verify the file signatures (SuOpt:VerifyFiles) Must be signed by (SuOpt:MustBeSignedBy) Cert. Authority (SuOpt:CertProviderDown) Cert. Serial Number (SuOpt:SerialNumber) Errors to check (SuOpt:CertFailures) Note: it is not recommended that the No Issuer Certificate option is checked unless the user must have a certificate by the issuer of your certificate present on their machine. Action if signature fails (SuOpt:NotSignedOption) |
||
|
Tab shown with no Var buttons checked. |
|||
|
|||
|
Tab shown with all Var buttons checked. |
|||
The update process for client/server applications
If the 'This is a server application' option is checked in the Client/Server Tab, the following steps must be performed.
Server application options
- The Enable Auto-update option in the Options
Tab of the global extension must be enabled.
- The Safe UpdateAuto-update extension must be added to your main
procedure and the server option must be checked.
- The 'Store the file after download' option in the Download Tab must be enabled and a path specified.
Client application options
- Make sure that the file path entered in the Files
Tab in the SafeDownload extension is the same one you entered in the
Install Path field in the server's Client/Server
tab. You could get around this by sending a message from the server to the
client with the path as part of the message.
- Verify the File Signatures must be disabled in the SafeDownload Verify tab, since the server removed the signature when it downloaded the update file.
Client/Server update process
- The server checks it's version. If a new version is found, the
server is updated in the usual way.
- If no new version of server is found, the server compares the client's
version file on the web with the existing one, stored in the client Install
Path (Client/Server tab option).
- If a new version of client is found, it is downloaded and stored in
the Install Path specified in the Client/Server Tab.
- If you need to upgrade your clients immediately, you can then send them a message to inform them that they need to upgrade. This would be added at the %SafeSendMessageToClients embed in your main procedure. The client would then call SafeDownload. In your message to the clients you could also send the path to the update file. If you did this, you would have to specify the install path as a global variable and set its value before the client called SafeDownload.
The SafeDownload Procedure
SafeDownload (string pHideWindow, string pXMLfile, string pVerify)
Description:
Download and run an Update File, first checking the XML version file to see
if the update is newer than the existing application.
SafeDownload can also be used to find the version embedded in any XML file. This might be used in a client / server application. For example, when a client accesses the server, the server would examine the version of the client somehow. If the client were not up to date, the server would then send a message telling the client to request an update. When finding the version of a non-default XML file, the Update File is not downloaded.
To retrieve the version of an XML file (default or non-default
When SafeDownload closes, the XML file version is placed in the SuOpt:AcquiredVersion parameter. An event:SUactivatewindow event is also sent to the window that started SafeDownload. You can read the version by embedding code at this point. This embed point will already be present if the window has the SafeAutoUpdate template added. Otherwise you will have to add it yourself. See the example below.
NOTE: Only one copy of SafeDownload can be run at one time.
Parameters:
pHideWindow: Set this to '1' to hide the window. Set it to '0' to show
the window. Notice that it is a string parameter.
pXMLfile: This is used when you want to find the version embedded in an XML file that is not the default XML file. If you are finding the version of the default XML file, this parameter can be set to an empty string.
pVerify: Set to '0' to disable signature verification and '1' to enable it. Notice that it is a string parameter. This parameter is used in conjunction with pXMLfile. If pXMLfile is an empty string, this parameter has no effect but must be included anyway.
Return value: none.
Example (ABC):
In TakeAccepted()
....
!-- Start SafeDownload.
of ?ButtonDownload
start
(SafeDownload, '1',
'www.mycompany.com/ClientApp.xml',
'1')
In TakeWindowEvent()
....
!-- SafeDownload ended.
of event:SUactivatewindow
MyVersion = gSUpdate.GetOption (SuOpt:AcquireVersion)
| Screen Shots | |||
|
Searching for the XML version file. |
|
|
|
Asking to download the Update File. |
||
|
Asking to install the Install the Update File. |
||
The
SafeAutoUpdate Control Template
If Auto-Update has been enabled, SafeAutoUpdate checks for updates as often as you have specified. SafeAutoUpdate runs in its own thread and is terminated when the main application procedure shuts down.
This extension can be left out if auto-updating is not required. To add this template, follow the steps shown in the Template Utility section.
SafeAutoUpdate ScreenShot
Code Embeds
Start Safe Download
Save all the INI File Settings
Get an INI File Setting
Save an INI File Setting
Start
Safe Download
This embed calls SafeDownload. It can be attached to the Accepted event of a button or a menu item, for example, in order to start the download process. Choose the embed as shown in the picture below.
If downloading is enabled, the following dialog box will appear:
In the event of your wanting to embed this at the start of your program, check the button. If you want to show the update only some of the time, make the option variable by clicking on the Var button. The window will change to look like the figure below. Enter your own variable in the space provided.
If downloading has been disabled in the Global Extension, the following dialog box will appear:
Save
all the INI File Settings
This saves all the Safe Update settings, as listed in Saved Settings. You would add this code when the user changes one or more of the saveable settings. Select this from the Embeds window.
Get
an INI File Setting
Read an INI file or registry setting. This is actually done indirectly, from the global SUpdate class. The code embed asks for the setting name and the variable that it will be stored in, as shown in the figure below.
Save
an INI File Setting
Save an INI file or registry setting. The setting is stored in the global SUpdate class and also in the INI file or registry. The code embed asks for the setting name and the value that will be stored, as shown in the figure below.
Uploading
Certificate
Information
You will not need to get a certificate if you are only downloading files. The Update File will already have all the necessary certificate information embedded. If this applies to you, then you can safely skip this section.
How do I get a Certificate?
The Upload Jump Start section has information on how to do this.
Certificate Requirements
The certificate needs to:
- Be issued by a Certificate Authority, e.g. Thawte. See the Upload JumpStart
section for more information on how to obtain one.
- Have a private key attached. You can see if this is the case by viewing the certificate (described how in the next paragraph). At the bottom of the General tab you will see the text 'You have a private key that corresponds to this certificate.' if a private key is present. See the picture below.
How to Find the Certificate's Serial Number
If you have a copy of the certificate, simply open the file. Alternatively, you can view the certificate information in Internet Explorer: In your Tools - Internet Options - Content, click the Certificates button and you will see a list of certificates. Double click on the correct one to give you the details for that certificate.
Otherwise you will need to open the file CERTMGR.MSC. This is found in the Windows\system32 directory. The certificate you require should be in the 'Current User/Personal' store. Go to the Details tab of the certificate and highlight the Serial Number field. The serial number will appear in the lower listbox. You can now cut and paste the serial number into the template, remembering to enclose it in single quotes.
The template makes provision for three different formats of serial number. Examples are:
- 01 02 03 04 05 (space delimiters)
- 01:02:03:04:05 (colon delimiters)
- 0102030405 (no delimiters)
The 2nd format is useful if the certificate is viewed in an Internet browser.
How do I find the Issuer Name?
Click on the Certification Path tab, in which you will see a tree of certificates. Select the item that is second from the bottom of the tree and click the View Certificate button. Now click on the Details tab and select the Issuer field. The CN field (in the lower list box) is the issuer name. See the screenshot below for an example.
SafeUp,
the Sign and Upload utility
This is a simple uploader program that allows you to generate XML files, as well as sign and upload your update files. SAFEUP mirrors the options found in the SafeUpload local extension: therefore all the options that are used in SAFEUP are exactly the ones used in the SafeUpload local extension. The SAFEUP screenshot is shown below.
SAFEUP is a complete uploader and can be used without any modifications. It comes with source code so you can see 'under the hood'. The binary SAFEUP.EXE is distributed with Safe Update and can be found in the Clarion\3rdParty\bin directory.
You only need one Uploader for all your SafeUpdated programs. You can enter a record for each one in the list using the details that you entered into the Download Jumpstart as follows:
| Update File | The name of your compiled exe (and local path if different from the SafeUploader's path) |
| XML version file | This should match the XML version file setting in the SafeUpdateDownloadControls template of your application. The difference is that the Template setting will include an HTTP path. |
| Update File version | This should match the version number in the SafeUpdate global extension template on the options tab of your application. |
| Signed by | Matches the Must be signed by in the Verify tab of the SafeUpdateDownloadControls control template of your application. |
| Certificate Authority | Matches the Cert. Authority in the Verify tab of the SafeUpdateDownloadControls control template of your application. |
| Serial Number | Matches the Cert. Serial in the Verify tab of the SafeUpdateDownloadControls control template of your application. |
| FTP Server, User, Password | Contain the FTP server details with which to upload the files to. |
| Update File Directory | Contains the directory in the FTP server where the signed Update File must be FTPed. |
| XML File Directory | Contains the directory where the XML file must be uploaded to on the FTP server. |
| Unsigned Update Directory | This is the directory where the unsigned file will be uploaded to. The first time the program runs it should be an unsigned file - although you may have an alternative method of transport (in which case you can leave this blank, and the unsigned file won't be uploaded). |
SafeUp can be used from the command line using the \File parameter to pass the name of the Update File that it will then be signed, and uploaded if uploading is enabled for that project.
Example:
safeup.exe /File=N:\SafeReader\install\SafeReaderInstall.exe
Configuration Files (Deprecated)
This option is deprecated in favor or the far simpler command line option above, however it is still supported by the application.
SAFEUP can also be used from the command line using a configuration file. A README file which shows the format of the configuration file is supplied with SAFEUP. A configuration file example is also shown at the end of this section. When used with a configuration file, SAFEUP runs hidden.
There are some constraints in the syntax of the config file:
- The parameter names must not be changed. However, they are case-insensitive.
- Each parameter and value must be on its own line.
- The configuration file must be no larger than 8 kB.
These are the things you are allowed to do in the file:
- The order of the parameters in the file doesn't matter.
- Parameter values can be left blank if you don't want them set, or the config line can be left out altogether.
- Empty lines are allowed between parameters.
- Single quotes are allowed around the values.
- Comment lines are allowed, so long as none of the parameter names are present in the comment. There is no format constraint for a comment.
If there is an error in one of the lines of the configuration file, the line is ignored. However, processing of the configuration file will continue until the end of the file.
Example Configuration File
An example configuration file is shown in the figure below. You can copy the
text in this figure to create your own configuration file. The top four
parameters are task options.
The colour of the other parameters show their dependencies on the task options. The black parameters depend on more than one task option.
|
UpdateFile
= Update.exe XMLVersionFile = update.xml UpdateFileVersion = 1.00 CertificateAuthority = Thawte or Verisign etc SerialNumber = 01 02 03 SignedBy = me@mycompany.com FTPPassword = MyPassword FTPServer = ftp.mycompany.com FTPUser = MyUserName UnsignedDirectory = ftp/public UpdateFileDirectory = ftp/signed XMLFileDirectory = utilities |
|
An example configuration file for SafeUp |
The SAFEUP Command Line
Run the application with the following parameters:
uploader [-E] <configfile>
where the parameters are defined as follows:
| Parameter | Description |
| -E | Insert this optional parameter if you want to show the error messages. This is useful when debugging your configuration file. This option is not case sensitive. |
| configfile | The name of the configuration file. |
Note: The demo and pre-compiled versions of SAFEUP include CapeSoft File Manager 2 (FM2) in order to track the changes of the dictionary file. FM2 was not included in the examples because it is not needed with Safe Update. If you have FM2 or FM3, feel free to add it to the SAFEUP example.
Further Information
The Programmer's Guide has more useful information on how to use SAFEUP for signing and uploading.
The
Safe Update Template Utility
These templates are at the heart of Safe Update. You will need to load one of these templates into your application in order to upload your files. See the JumpStart for more information.
To load the Upload template into your application, open the Application | Template Utility menu option and select the ImportSafeUpdateUpload utility (ABC or Legacy), as shown in the picture below. Doing this will create the windows SafeUpload and SendFTP, with a Safe Update control template associated with each one.
Control
Templates
The SafeUpload Control Template
The SendFTP Control Template
The SafeUpload Control Template
This allows you to upload a signed Update File and XML version file to either a remote site using FTP, or local site. To add this template, follow the steps shown in the Template Utility section.
To hide the update process, go to the SendFTP window extension and tick the Hide option.
NOTE:
- The options shown in this section all correspond to
user-settable options using the SetOption method
in the global SUpdate class.
- All boolean options can be assigned a variable by clicking on the Var
button in the template extension corresponding to the option (see the
pictures below).
- Safe Update will automatically distinguish between a local and an FTP path.
SafeUpload General Tab
SafeUpload Files Tab
SafeUpload Signature Tab
SafeUpload Uploading Tab
| SafeUpload General Tab | |||
|
The general tab for the SafeUpload template control. | ||
| SafeUpload Files Tab | |||
|
Note: the two screenshots in this table show the boolean variables as constants and as variables.
Update File
(SuOpt:UpdateUpFileName) Automatically generate XML (SuOpt:CreateVersionFile) Version (SuOpt:Version) XML version tag (SuOpt:XMLVersionTag) |
||
|
Tab shown with no Var buttons checked. |
|||
|
|||
|
Tab shown with all Var buttons checked. |
|||
| Signature TabSafeUpload | |||
|
Note: the two screenshots in this table show the boolean variables as constants and as variables.
Sign the files (SuOpt:SignFiles) Signed by (SuOpt:SignedBy) Certificate Provider (SuOpt:CertProviderUp) Cert. Serial Number (SuOpt:SerialNumber) Warning: the certificate's serial number will change if you re-install your certificate so beware! Append to file name (SuOpt:AppendToUpdate) |
||
|
Tab shown with no Var buttons checked. |
|||
|
|||
|
Tab shown with all Var buttons checked. |
|||
| SafeUpload Uploading Tab | |||
|
Note: the two screenshots in this table show the boolean variables as constants and as variables.
Upload the files (SuOpt:UploadFiles) Use external app to upload (SuOpt:UploadUsingOther) Command line (SuOpt:UploadProg) Server (SuOpt:FTPserver) User (SuOpt:FTPuser) Password (SuOpt:FTPpassword) Update file directory (SuOpt:FTPMsgDirectory) XML file directory (SuOpt:FTPXmlDirectory) Unsigned Update Dir (SuOpt:FTPUnsignedDirectory) |
||
|
Tab shown with no Var buttons checked. |
|||
|
|||
|
Tab shown with all Var buttons checked. |
|||
Why you may need signed and unsigned versions
When the user buys and downloads your application for the first time they would have no means of removing a signature attached to the setup file. Removing the signature is sometimes necessary because setup files created with some programs, such as Wise, perform self-checks to see if they've been modified. A signature is obviously a modification, so the setup file will not run.
It is not always the case that self-checking is performed, however. For example, Setup Builder allows you to turn checking off. In this case a separate unsigned file would not be necessary.
In summary, you will need to upload an unsigned version if the setup file generator doesn't allow you to disable the self-check feature. This is the case with Wise, but not Setup Builder.
If you have uploaded both signed an unsigned versions, direct all manual downloads to the unsigned version, but have your application download the signed version.
The
SendFTP Control Template
This code is loaded in the Template Utility (along with SafeUpload) when you load the Upload TXA file. This is generic code that uploads a file to an FTP site. It is called by SafeUpload. To add this template, follow the steps shown in the Template Utility section.
The parameters in this template can be left alone for most applications.
NOTE: Do not change the name of the SendFTP procedure otherwise a compile error will result.
SendFTP General Tab
SendFTP Options Tab
| SendFTP General Tab | |||
|
The general tab for the SendFTP template control. |
||
Code
Embeds
Start Safe Upload
Save All the INI File Settings
Get an INI File Setting
Save an INI File Setting
Start
Safe Upload
This embed calls SafeUpload. It can be attached to the Accepted event of a button or a menu item, for example, in order to start the upload process. Choose the embed as shown in the picture below.
The code embed will be inserted. However, the following dialog box will appear if uploading has been disabled in the Global Extension:
Save all the INI File Settings
This saves all the Safe Update settings, as listed in Saved Settings. You would add this code when the user changes one or more of the saveable settings. Select this from the Embeds window.
Get
an INI File Setting
Read an INI file or registry setting. This is actually done indirectly, from the global SUpdate class. The code embed asks for the setting name and the variable that it will be stored in, as shown in the figure below.
Save
an INI File Setting
Save an INI file or registry setting. The setting is stored in the global SUpdate class and also in the INI file or registry. The code embed asks for the setting name and the value that will be stored, as shown in the figure below.
FAQ
I've just upgraded from Safe Update 1, what must I change in my application?
- How do I add Safe Update to an existing application?
- I've enabled Auto-Update but nothing's happening. What's going on?
- Multi-DLL: How do I put SafeDownload in a DLL and SafeAutoUpdate in the EXE?
- Can I digitally sign my EXE created by Clarion?
- Can I digitally sign arbitrary EXE's I've created with Wise etc?
- What is the file called SUhasUpload.inc that keeps appearing in my application folder?
- What format must the version number be?
- How do I download multiple files in the same session?
- When my application is updated it says that the digital certificate of one of the files is not trusted. What's the problem?
- How do I upload my files?
-
Why do I get "Unkown Identifier" compile errors after updating to Safe Update 2
1) How do I add Safe Update to an existing application?
Answer: The recommended way to do this is as follows.
Add Safe Update to your application and configure it as described in the Download Jump Start. Before you compile it, determine what the name of the signed update file will be. This must be done by attaching a suffix to the unsigned file name. For example, if the unsigned update file is called Update.exe, make the suffix '_signed' to call the signed file Update_signed.exe. Enter this name in the SafeDownload Files tab.
Now compile your application and make an update file using Wise, for example. Then, using SAFEUP, create a signed copy of the update file and a signed XML version file. Next, upload all three files (signed and unsigned update files and the version file) to your FTP site.
If you use this arrangement you can set up the downloads so that manual downloads will get the unsigned version, whereas automatic updates will get the signed version.
2) I've enabled Auto-Update but nothing's happening. What's going on?
Answer: When you want Auto-updating, the AutoUpdate local extension must be added to your main procedure.
3) Multi-DLL: How do I put SafeDownload in a DLL and SafeAutoUpdate in the EXE?
Answer: Add the ImportSafeUpdateDownload code to your DLL as documented in the Programmer's Guide. Now delete the SafeAutoUpdate procedure. Add the same code to your EXE, but delete SafeDownload.
4) Can I digitally sign my EXE created by Clarion?
Answer: Indeed you can. In fact, any file can be signed, not just executables.
5) Can I digitally sign EXE's I've created with Wise etc?
Answer: Yes you can. However, there is a small caveat with a Wise EXE. When it runs, it performs a self-check to see if it's been modified. If you've signed it, then the CRC will fail and it will halt with an error. You will need to remove the signature before running it. The good news is that Safe Update does this for you automatically.
6) What is the file called SUhasUpload.inc that keeps appearing in my application folder?
Answer: SUhasUpload.inc is created by the Safe Update template when your application is generated and is used to tell whether your application needs the three DLLs mentioned in the Distribution section of this document. This will be the case if you have included SafeUpload in your application.
7) What format must the version number be?
Answer: The version number is a free-form string of up to 40 characters. A string longer than this will be truncated. Comparing version strings works as follows. First of all, the numbers in the string are compared from left to right. If all the numbers have been compared and no difference has been found, then the entire strings are compared without case-sensitivity. Here are a few examples:
- 'Version 1.00 build 5' is newer than 'Version 1.00'
- '1.24.6.200' is newer than '1.24.5.2043'
- 'v1.00' is newer than 'v1.0'
- '10.00' is newer than '9.90'
- 'v1.00a' is the same as 'V1.00A'
Note: the version number entered in the local SafeUpload extension can be a variable or equate. However, the version number entered in the Global Options extension must be a literal string if the XML file is to be generated at compile time.
Also note that the version string entered in the Global Options extension is assigned to a global equate, called SafeUpdate:AppVersion. This is available for use in your application.
8) How do I download multiple files in the same session?
Answer: It would be a lot easier to put all the files you need into a
single self-extracting archive instead. However, here are a few guidelines if
this is not an option.
Instead of using literal strings for the filename fields in
the Files Tab of the SafeDownload extension, assign
these to global variables, e.g.
gUpdateFile and gVersionFile. Then for each file, assign the filenames to the
global variables and then
call SafeDownload, preferably from the SafeDownload embed.
After each download an event:SUactivateWindow
event will be sent back to the calling thread.
Also, don't run an installer until all the files are downloaded, otherwise your downloader program will automatically exit. The way to do this is to assign a global boolean variable to the Run Separate Installer option in the Download Tab of the SafeDownload extension. Set it to false initially, but set it to true just before the final file is downloaded.
9) When my application is updated it says that the digital certificate of one of the files is not trusted. What's the problem?
You may have entered the serial number of your certificate incorrectly when signing the file, or you have re-installed your digital certificate between compiling your application and signing it. If you ever re-install the certificate, its serial number will change. Get the user to ignore the problem, which is only possible if you have set the Failure Option in the SafeDownload extension to Ignore or Warn.
10) How do I upload my files?
See the Uploader Section of the documentation.
11) Why do I get "Unknown Identifier" compile errors after updating to Safe Update 2
Run the ImportSafeUpdateDownload template utility to import the download and autoupdate procedure. Alternatively the prototype and parameters for the SafeDownload procedure can be manually changed to:
(string pOnStartup, string pXmlFileName, string pVerifyFiles)
Not doing this will result in compile errors:
Syntax Error: Unknown Identifier: pVerifyFiles
Syntax Error: Unknown Identifier: pXmlFileNAme
Syntax Error: Unknown Identifier: pOnStartUp
Version History Download latest
version here
Version 2.01 Beta (23 December 2011)
Requires CryptoNite 1.24 or later.
- Added: If the root DLL name is blank then no prototypes for the SuAutoUpdate and SuDownload procedures are exported in Multi-DLL applications. This only applies to those using prototype exporters.
- Fixed: A typo in the template causing an compile error in Legacy when the SafeUpdateDownload template utility was used (TakeEvent called without an object name).
- Fixed: Error in the Server class which
did not always copy the XML version file into the store folder,
resulting in the update being downloaded at each check.
- Merry Christmas!
Version 2.00 Beta (15 April 2011)
Requires CryptoNite 1.15 or later.
- Added: ClientServer example which demonstrates the new client/server update functionality.
- Added: Safe Update Server
- Added: Safe Update Server local extension
- Added: Safe Update Client
- Added: Safe Update Client local extension
- Added: Auto closedown of running clients when using the client/server when a new update is received
- Added: Automatic update from server on startup for client applications
- Added: "SafeUpdate Server" Option to the Safe Update Download Controls local extension. Switches the object to work as an update server, rather than downloading and installing as a client.
- Changed: refactor of the SafeUpdate classes
- Added: CryptoNite base
- Added: SafeDownload class
- Changed: SafeAutoUpdate moved to using new classes rather the all template generated code.
- Changed: All template generated download code moved to the SafeDownload class
- Added: HttpClient class
- Fixed: potential GPF in file verification
- Fixed: incorrect temp directory
- Fixed: incorrect parameter passing to the SafeDownload procedure
- Changed: Moved the file loading class to a base class
- Changed: Refactoring of the XML handling class
- Fixed: error in the SignFile method when assigning the signer
- Fixed: error in the SignFile method when assigning the cetificate provider
- Added: support for additional signer verification parameters
- Fixed: Modified all signing and verification methods with correctly typed parameters
- Added: logging to all methods
- Changed: error handling to be consistent throughout classes and to use a single shared mechanism.
- Fixed: incorrect thread number posting in the the shutdown process
- Changed: Moved all HTTP connection code and error handling to the SuHttpClient class
- Changed: Removed temp files for HTTP handling
- Added: SuHttpClient class methods
- ErrorTrap procedure(string errorStr, string functionName), derived
- PageReceived procedure(), derived
- Process procedure(), derived
- Added: SafeDownload class methods:
- Construct Procedure ()
- Destruct Procedure ()
- Init Procedure (*SafeUpdate su, *Window wnd, string iniFile, bool pOnStartup, string pXmlFileName, bool pVerifyFiles), virtual
- SetControls Procedure (long cStatus, long cPromptNoUpgrade, long cProgress, long cGroupDl), virtual
- SetButtonControls Procedure (long cButtonYes, long cButtonNo, long cButtonOK, long cButtonCancel, long cButtonCancel2, long cButtonInstall), virtual
- SetInfoControls Procedure (long cInfo, long cInfo2, long cInfo3, long cInfo4), virtual
- Display Procedure()
- GetUpdateFile Procedure (), virtual
- GetLocalFile Procedure (), virtual
- VerifyMsgFile Procedure (), virtual
- ProcessVersionInfo Procedure (), virtual
- ProcessFile Procedure (), virtual
- InitialWin Procedure (), virtual
- AskToUpgradeWin Procedure (), virtual
- NoNewVerWin Procedure (), virtual
- NoVersionWantedWin Procedure (), virtual
- SetOption Procedure (long pOpt, ? pVal), virtual
- GetOption Procedure (long pOpt), string,
virtual
- RunSetup Procedure (), virtual
- ButtonYes Procedure (), virtual
- ButtonNo Procedure (), virtual
- ButtonOK Procedure (), virtual
- ButtonCancel Procedure (), virtual
- CheckNoUpgrade Procedure (), virtual
- TakeAccepted Procedure (), virtual
- TakeEvent Procedure (), virtual
- WindowInit Procedure (), virtual ! Call from Windows.Init to load setting and set up the object
- SetDownloadOptions Procedure (bool
askUser=true, bool isServerApp=false, <string clientXmlFile>, |
string downMsgFile, string downXmlFile, <string clientUpdateFile>, |
<string clientInstallPath>, string versionTag), virtual - SetInstallOptions Procedure (bool
downloadAndInstall=true, bool runAfter=true, bool
seperateInstaller=true, |
<string installer>, bool storeDownload=true, bool keepSig=false, bool userLocation=false, |
<string storePath>, bool askFirst=true, bool cacheOff=false), virtual - SetVerificationOptions Procedure (bool
verify=true, <string signer>, <string certProv>, <long serial>, |
long failures, <string csp>, string action), virtual - StartUpdate Procedure (), virtual
- WindowKill Procedure (), virtual
- Changed: Cleanup of SuXml class
- Changed: SuXml is no longer the base class, the generic suFile class is the base class and SuXml inherits and builds on the functionality that it provides.
- Changed: Removed all old source files. SafeUpdate now comprises of suxml.clw, suxml.inc, supdate.clw and supdate.inc. All other core functionality is provided by CryptoNite.
- Deprecated: (and removed) the CheckForHTTPError method. All error handling is done in the HTTP client object itself.
- Changed: Removed temp file stored for HTTP error handling. Error handling and checks are now done directly on the data returned by the server.
- Changed: Refactored the csFile class into a generic file reading and writing class with additional methods for handling signatures etc.
- Fixed: Incorrect parameter passing for the file handling APIs
- Fixed: The Signature reading, writing, removal and verification could fail if the file pointer happened to fall on the same value as the API error code for an invalid file pointer (the API error code is only relavant if GetLastError indicates tha the API failed, otherwise the return value is a valid file pointer).
- Fixed: Certificate fields other than the common name were not correctly parsed and not available for validation.
- Added: Improved certificate field handling. All certificate fields are now processed and available.
- Added: New types for storing certificate and other data to allow easy processing and handling.
- Fixed: AutoUpdate calling the Download function multiple times at startup.
- Added: SafeUpdate Server and Client for automated downloading of client updates and distribution of client updates across a LAN
- Added: New SafeUpdate Server and Client Example
- Deprecated: Old "server" option is now deprecated (use the improve client/server functionality)
- Added: Auto-shutdown for SafeUpdate Servers to inform clients of a new update
- Added: Automated updated on startup for client applications
- Added: Automated retrieval and verification of new versions of the client software by SafeUpdate Servers
- Added: Client update version number retrieval methods
- Added: suServer class to implement the Safe Update Server side of automtatic update notification and client closedown.
- Added: suServerCloseClients class to implement the Client side of automatic update notifications across the LAN and client closedown.
- Fixed: SafeUp application not reporting the status correctly after signing/uploading.
Version 1.27 (18 March 2010)
- Fixed Clarion 7 compatibility (a template issue was preventing the update code from actually being called).
Version 1.26 (7 January 2010)
- Fixed Mult-Proj compatibility. The Crypt32.lib is now included in the correct section of Multi-Proj generated projects.
- Changed docs to cover purchasing a certificate as the free certificate from Thwate is no longer available.
Version 1.25 (8 September 2009)
- Improved support for legacy apps when multiple global class templates are used. (update tpw to edition 1.63)
Version 1.24 Beta (1 September 2009 )
- Updated the SafeUp signing application. An additional SafeUpExtra.app is now also shipped, which includes additional templates to provide enhanced functionality (this app is completely optional and provided for those who have the additional templates).
Version 1.23 Beta (28 April 2009 )
- Fixed: GPF when signing updates and generating an XML signature file.
- Updated the SafeUp signing application.
Version 1.22 Beta (06 January 2009 )
- Fixed incorrect template in C7 install.
Version 1.21 Beta (10 November 2008)
- Clarion 7 compatible install.
Version 1.20 Beta (21 August 2008)
- Fixed: Potential GPF in SafeUpdate when checking signatures.
- Fixed: The Windows\Temp\ directory being used for storage. Temporary files are now stored in the system Temp directory, which is Vista compatible.
- Added: Option to use the version resource information for the ProgramName and Program Version.
Version 1.16 Beta (31 August 2007)
- Store file after download now defaults to 1.
- Template - fix for legacy class generation (includes SafeUpdate01.tpw 1.54).
Version 1.15 Beta (12 June 2006)
- New SafeUp01.tpw - fix for interference with other templates (using the Object01.tpw template).
- The download path is for storing the file defaults to the current directory instead of blank.
- If the download path is set to blank, then the application automatically uses the current directory.
- SafeUp now reports all errors as well as logging them.
- SafeUp displays the status of the last request, informing the user of success or failure.
- Fixed problems with FTP and added an icon to the window to ensure that it does not get "lost" in the background.
- Added error reporting for FTP, so if it encounters an error it is reported to the user etc.
Version 1.14 Beta (24 April 2006)
- New automated certificate installation.
- Fixed problem with an installer than had zero size files.
Version 1.13 Beta (23 January 2006)
- Reworked a number of options, the documentation and main example application in order the make basic use simpler.
- The Demo application can now simply be compiled and run to demonstrate updating, removed the necessity to compile multiple version, copy files etc.
- Added test certificate that can automatically be installed, this certificate is used by the example applications
- Made using the SafeUp program the default rather than creating .cfg files and manually entering details (which is now completely superfluous, enter them once in SafeUp and press the button to sign, or to sign and upload the updates)
- Remove sections of the docs that were superfluous.
- Simplified demo documentation
- Added a compiled version of the "update" file for the demo, allowing the demo to be run and the update to be tested immediately
- New updater application that ships with the demo (source code included), this acts as a "mini installer" allowing an EXE or other file to be downloaded, updated and the program restarted without a full installer.
- Changed the template to use the new mini installer to copy files.
- New Installer, added shortcuts, certificate browser shortcut, test certificate etc.
- Still to do: Overhaul Client\Server example to new format.
Version 1.12 Beta (6 December 2005)
- Simplified the general use of SafeUpdate. This means that a number of options have been removed in order to simplify the product. Options removed: Create (or not) the XML version file, specify the version tag in the XML file, specify an external method of FTP (only NetTalk is used), optional signing removed (always signs). Requires a new version of SafeUploader.
- SafeUploader documented.
- You can now hide the file path details while the update file is downloading.
- Added an option in the AutoUpdate extension to make SafeDownload silent when the procedure is added from the AutoUpdate extension.
- Bug fix: SafeAutoUpdate did not always check for an update on startup.
- Added an item to the AutoUpdate extension so that you can specify a control that will start a manual check for updates. This was done so that you don't have to use the SafeDownload embed. It's much easier to use too.
- Added helpful default values to the templates.
- Bug fix: Programs that only used the SafeUpload template didn't compile in v1.09.
- SafeUp: Removed the Add To Signed Name option. The default name extension is now '_signed'.
- Added the SUshutdown event to the main window. This gets sent immediately after the update file is run by SafeDownload. Put your shutdown code here: this will be needed if your application gets sent to the system tray.
- Bug fix: when an SUactivatewindow event was received, the window was put into AcceptAll mode by the Select() procedure. The Select() code has now been removed.
- Bug fix: When SafeDownload was hidden, no auto-run of the update file took place. Also, the window would remain open but hidden.
- Revised the documents.
- Bug fix: fixed client/server process.
- Bug fix: the update file that is run by SafeDownload was opened maximized.
- Number of days between updates can now be entered as a variable.
- Better-looking icon in the SafeDownload window.
- Extra option in SafeAutoUpdate to show the SafeDownload window as well.
- Bug fix: SafeDownload embed: parameter list options were switched. This made it look as if the download was not working.
- Bug fix: SafeAutoUpdate prototype had changed in v1.06: reverted to old prototype.
- Bug fix: SafeDownload embed also reverted to previous version.
- Bug fix: fixed demo apps. Broken because of the above change.
- Bug fix: Template fix: 'window' should have been '%window'
- Close-down code for SafeDownload has been changed.
- New support for client/server applications has been added. This allows the server to download the latest client update.
- Bug fix: The Start Safe Download code embed didn't work when Auto-update was disabled and a quiet update was required.
- Provision for a variable has now been made in the Start Safe Download code embed.
- Bug fix: SafeDownload didn't display No New Version when the program didn't need updating and an XML file error occurred.
- The digital certificate serial number was not parsed correctly when verifying.
- This document now draws attention to the fact that if you ever need to re-install your digital certificate, the serial number will change.
- Bug fix: minor change to the SendFTP template.
- The issuer certificate is now not checked for by default (SafeDownload verification tab). Checking for this created problems with the demo.
- Bug fix: didn't read the application name from the cwVersionRes file.
- Bug fix: Nettalk error suppression was not turned on in the TXA files.
- Added support for the cwVersionRes template. Can now read the version and application name from the file that this template generates.
- First release of CapeSoft Safe Update.