Version Beta www.capesoft.com Updated 25 Nov 2005

Reference Manual

Jump Start	Examples	FAQs	Templates	Parameters	Version History

Products Required for Safe Update

Nettalk

Contents

JumpStart for Downloading
JumpStart for Uploading

Introduction
Programmer's Guide

The Global Extension

Downloading

JumpStart
Certificate Information
Examples
Local Extensions
The Safe Update Template Utility

Control Templates
The SafeDownload Control Template
The SafeAutoUpdate Control Template

Code Embeds

Uploading

JumpStart
Certificate Information
An Uploader Example (SAFEUP)
The Safe Update Template Utility

Control Templates
The SafeUpload Control Template
The SendFTP Control Template

Code Embeds

FAQ

Installation
Support
Purchasing Safe Update
Distribution

Technical Details
Safe Update Class Method Reference
Safe Update-Defined Events and Equates
Safe Update Class Properties and Global Variables

Saved Settings
Safe Update Options and Parameters

For those that care: the XML Version File
Acknowledgements

Version History
License & Copyright

Introduction

How Safe Update Works
How Downloading Works
How Uploading Works
About Digital Certificates

How Safe Update Works

Safe Update Flow Diagram

This description covers the basic behaviour of Safe Update. Throughout this document, the application update file will be called the Update File, although it could also be any other kind of file that you want to sign digitally.

When you want to upload your Update File, Safe Update generates an XML file with the latest version number of your product embedded in it. Both this XML version file and your Update File are digitally signed using your own digital certificate. Both files are then uploaded to your web site using FTP. All this is done transparently.

When the user runs your application, it downloads and examines the XML file, checking for a newer version number. This is done using HTTP. If a newer version has been found, then the Update File is downloaded, also using HTTP, and installed. In the case of both the update and XML files, their digital signatures are examined. If either one fails then the update is not installed.

The above figure shows the whole process. SafeUpdate handles every part of it for you.

How Downloading Works

Flow Diagram for the Downloader

This section assumes that the Update File and its Version File are already present at the desired location. The above figure shows the flow of the download. When it's time to check for an update, the version file is read. If this file is valid and it shows that a new update file is present, the new update file is downloaded and run.

Setting the Download Source
Downloading can be done either from the web using HTTP or from a local path. The file paths are entered in the SafeDownload extension in the Files tab of the SafeDownload Local Extension. 

After the Download
The download destination is set in the SuOpt:TempLocation option. This is not shown on the template extensions, since the windows directory is a system-dependent name. However, it is settable using the SetOption method. The default temporary folder is 'Windows\Temp\SUpdate'. 

The XML and Update Files are saved in the temporary location. The signatures appended to the XML version file and the Update File are verified. If they pass all the tests and the Update File is to be stored (in a folder other than the temporary one) then this is done. If the Update File is to be run and if the file has been stored in a non-temporary folder, then this copy is run. Otherwise the copy in the temporary folder is run instead.

Advanced Download Options

Downloading a client / server application (options for the server)
Updating could be done in one of two ways.

1. The server and client both download their own Update File from the web.
2. The server downloads its own and the client's Update File from the web. The client downloads its Update File from the server machine (this saves bandwidth). This is the option that is implemented in the Client/Server tab of the SafeDownload extension.

If you choose the 2nd download option, enter the server's file paths in the Files tab of the SafeDownload extension. Check the This is a server application option in the Client/Server tab of the SafeDownload extension. Enter the client's files and install path in the same tab. The install path is where the client files are to be stored after they have been downloaded.

The downloads would occur at midnight since that's when the day number changes. The options on the server for downloading both files would be (all in the SafeDownload Local Extension unless specified):

1. Set the number of days between updates to a non-zero value (Global Extension).
2. Uncheck all the options in the Download tab except the Store File After Download option.
3. Uncheck the Get Location From User option and enter the desired path.
4. You would probably also uncheck the Keep Signature Attached option unless it were needed for an external installer.

Downloading a client / server application (options for the client)
When the client downloads its Update File, the chances are that there are plenty of other clients just like it also trying to access the same file. To spread the bandwidth load, the time when the update file is retrieved can be randomized between any two hours of the day.

The client options to set would be (all in the SafeDownload Extension unless specified):

1. If the client is to be run continuously, then set the number of days between updates to a non-zero value. Otherwise a value of zero can be set to enable checking every time the program starts (Global Extension).
2. Enable the Randomize option and choose a suitable time over which the application can download the update (Global Extension).
3. The Download and Install prompts can optionally be enabled.
4. Check the Run Update After Download option.
5. Uncheck the Store File After Download option.

Downloading using a non-networked PC
This is the basic Safe Update arrangement. Downloading would most likely be done from the web. The options to set would be (all in the SafeDownload Local Extension unless specified):

1. If the application is to be run continuously, then set the number of days between updates to a non-zero value. Otherwise a value of zero can be set to enable checking every time the program starts (Global Extension).
2. The Download and Install prompts can optionally be enabled.
3. Check the Run Update After Download option, unless the file is not an executable and a separate installer is needed. In this case, enable Run Separate Installer and enter its command line.
4. If you want a backup of the update file, enable the Store File After Download option. Getting the storage location from the user can optionally be enabled.

How Uploading Works

Flow Diagram uploading your application

The SafeUpload Local Extension provides a simple way of signing and uploading files to an FTP site or a local folder. The figure above shows how to create and upload a signed update. The blocks marked Safe Update are done for you automatically.

Start by compiling your application that has the Safe Update template installed. As you do this, the XML version file for your application will be automatically generated. Now make your update file using your favourite install-generator, e.g. Wise.

Finally, you will need to use SAFEUP to sign and upload your update file. This is done by first creating a configuration file and then calling SAFEUP with the name of the configuration file as the command line parameter. The section on SAFEUP shows how it's done.

Detailed Explanation of Uploading

Safe Update was designed with automatic version updates in mind. The automatic update relies on the presence of an XML Version file. The rest of this section assumes that you do need the auto-update feature. However, if you are just interested in signing files without needing to update them automatically, the version file can be left out.

Before the Update File can be uploaded, an XML file with the version number of your product must be created. This is done by Safe Update at compile time.

Enter the names of the Update and XML version files in the Files tab of the SafeUpload extension.

The Update File and XML version file can then be signed. Signing is done using your digital certificate. All you will need from the certificate is the Signer's name or e-mail address, the Certificate Authority that issued the certificate and, optionally, the certificate serial number. These parameters are entered in the Signature tab.

You may not want to sign the original update file, so you can make a copy with a filename suffix appended. You can do this in the Signature tab of the SafeUpload extension. This may be handy if the file would not function if it were signed. For example, this is the case with Setup files generated by Wise. When the setup file runs, it performs a self-check to see if it has been changed. If it has, an error is generated. 

Uploading can be done either to an FTP site or to a local path. This can be done from within Safe Update or using a third-party program. The file names are entered in the Update File Directory or XML File Directory fields in the Upload tab of the SafeUpload Local Extension.

You don't have to make both files local or both remote. If you choose, you can send one file to a local folder and the other one to an FTP site. This can also be done in silent mode, where the SendFTP window is hidden. This is done by setting the Hide The Upload Window option in the Upload tab. This would be useful when uploading in batch mode.

About Digital Certificates

A digital certificate is a signature that has been verified by a trusted Certificate Authority (CA), e.g. Verisign or Thawte. It is attached to an electronic message to authenticate the author's identity. Digital certificates are becoming more widely used as the risk of fraud becomes greater. They provide:

• Authentication: Proof that the data was actually created by the person or company who says they did. It also proves that the creator of the data is who they say they are.
• Protection: Data is protected from modification.
• Non-repudiation: The author cannot later deny that they created the data.

In Safe Update, the certificate is appended at the end of the Update File. Only one signature is used, since this provides enough security for this kind of application. In theory, any number of signatures could be appended.

Further information can be found at:

http://wp.netscape.com/security/techbriefs/certificates/

http://www.webopedia.com/TERM/D/digital_certificate.html

http://www.comms.scitech.susx.ac.uk/fft/ (for lots of deeply technical documents on this and related topics).

Installation

Run the supplied installation file. CapeSoft Safe Update adheres to the standards layed out by the C3PA (Clarion 3rd Party Association) for 3rd party Accessory installation.

Support

Purchasing Safe Update

Safe Update is now in beta development. It is on sale for the price shown below.

Buy Online
	Purchase CapeSoft Safe Update for $139 from:	www.clarionshop.com

Distribution

• Three public-domain DLLs are needed to handle XML processing. These are provided along with Safe Update. However, the latest versions can be obtained at the following locations:
  
  libxml2.dll    http://www.dlldump.com/download-dll-files_new.php/dllfiles/L/libxml2.dll/-/download.html
  iconv.dll       http://www.dlldump.com/download-dll-files_new.php/dllfiles/I/iconv.dll/1.9/download.html
  zlib1.dll       http://www.dlldump.com/download-dll-files_new.php/dllfiles/Z/zlib1.dll/1.2.1.1429r/download.html
  
  
  License to use these files is given in the MIT license as described here:
  
  http://www.opensource.org/licenses/mit-license.html

Technical Details

The SUpdate Class

This is the API you will need for accessing the Safe Update class. If you don't allow the user to make any changes, then none of these methods needs to be called. However, if options need to be changed within your program, then these methods are the ones to use.

The more-frequently called methods are used to set options within Safe Update. The less-frequently used ones are documented in case you want to perform Safe Update functions without using the template utility procedures.

More-frequently used methods

GetOption
SetOption
SetLogging
ShowErrors

Less-frequently used methods

CopyUpdateFile
GetSignatureStatus
MakeVersionFile
RunProgram
SignFile
VerifyFile

More-frequently used methods

GetOption (long pOption),?

Description:
Returns the option specified.

Parameters:
pOption: The option whose value is to be returned. This is an enumerated value and a description of each one can be found in the Global Options and Local Options tables.

Return value: Returns the value of the option. If an error occurred, zero is returned.

SafeUpdate options used in the method: none.

Example:
  !-- Get the location of the registry folder.
    DATA
  RegFolder string(255)
    CODE
    !-- Cannot do this with strings (OK for other types).
    if gSafeUpdate.GetOption (SuOpt:RegistryFolder) = 'ThisProgram'
      ...
    end

    !-- Must do this instead.
    RegFolder = gSafeUpdate.GetOption (SuOpt:RegistryFolder)
    if RegFolder = 'ThisProgram'
      ...
    end

SetOption (long pOption, ? pValue)

Description:
Sets the option to the specified value.

Parameters:
pOption: The option to be set. This is an enumerated value and a description of each one can be found in the Global Options and Local Options tables.

pValue: This must be of the same type as the option being set.

Return value: none.

SafeUpdate options used in the method: none.

Example:
  !-- Set the application to check for updates once a week.
  gSUpdate.SetOption (SuOpt:UpdateFreq, 7)

SetLogging (long pLevel)

Description:
Set the level of logging detail. 

Parameters:
pLevel: The logging detail level. The enumerated values are described in the Global Options table.

Return value: none.

SafeUpdate options used in the method: none.

Example:
  !-- Set full logging.
  gSUpdate.SetLogging (ErrLevel:Full)

ShowErrors (bool pShow)

Description:
Turns the display of errors on or off.

Parameters:
pShow: Boolean value: if set to false, the errors are not displayed. Any other value causes the errors to be shown.

Return value: none.

SafeUpdate Options Used: none.

Example:
  !-- Show the error messages.
  gSUpdate.ShowErrors (true)

Less-Frequently Used Methods

CopyUpdateFile(),bool,proc

Description:
Makes a copy of the update file. The name of the copy is the same as the original, but with the filename suffix appended. The suffix is entered in the SafeUpload template.

Parameters: none

Return value: Returns Safeup:OK on success, Safeup:NOTOK otherwise.

SafeUpdate options used in the method: 

• SuOpt:AppendToUpdate
• SuOpt:UpdateUpFilename
• SuOpt:SignedUpdateFilename

Example:
  !-- Examine a file's digital signature. loc:Status is a long
  if gSUpdate.VerifyFile ('Datafile.SAF',,,, loc:Status) <> Safeup:OK
    message ('Error in the update file.')
  else
    if loc:Status
       message (clip(gSUpdate.GetSignatureStatus (loc:Status)))
    else
      message ('Signature OK')
    end
  end

GetSignatureStatus (long pStatus),string

Description:
Returns an error string depending on the value of the status parameters. See the VerifyFile documentation for a full listing of errors. This method is only valid immediately after a call to VerifyFile.

Parameters:
pStatus: The status word of the signature verified with VerifyFile.

Return value: The error string.

SafeUpdate options used in the method: none.

Example:
  !-- Examine a file's digital signature. loc:Status is a long
  if gSUpdate.VerifyFile ('Datafile.SAF',,,, loc:Status) <> Safeup:OK
    message ('Error in the update file.')
  else
    if loc:Status
       message (clip(gSUpdate.GetSignatureStatus (loc:Status)))
    else
      message ('Signature OK')
    end
  end

MakeVersionFile (<string pFilename>, <string pVersion>),bool,proc

Description:
Creates a digitally-signed XML file.

Parameters:
pFilename: The name of the XML file.

pVersion: The version string to be embedded in the file.

Return value: Returns Safeup:OK on success, Safeup:NOTOK otherwise.

SafeUpdate options used in the method: none.

Example:
  !-- Make a version file. loc:Version is a string.
  if gSUpdate.MakeVersionFile ('ThisVersion.XML', loc:Version) <> Safeup:OK
    message ('Error creating the version file')
  else
    message ('OK')
  end 

RunProgram (string pProgram, string pParams, string pDir),long,proc

Description:
Runs a program using the Windows API function ShellExecute.

Parameters:
pProgram: The name of the program to be run. The path must not be included in this parameter.

pParams: Any parameters that the program takes.

pDir: The path to the file.

Return value: Returns Safeup:OK on success, Safeup:NOTOK otherwise.

SafeUpdate options used in the method: none.

Example:
  !-- Remove the tags from the list box.
  if gSUpdate ('notepad.exe', '', 'c:\windows') <> Safeup:OK
    message ('Could not run the program')
  else
    message ('OK')
  end

SignFile (string pFileName, <string pSigner>, <string pIssuer>),long,proc

Description:
Digitally signs the specified file, whether binary or XML. The signature is attached to the end of the file, so is therefore an enveloped signature, as opposed to an enveloping one.

Parameters:
pFilename: The name of the file to be signed

pSigner: The owner of the signer certificate. For example, if the certificate is issued by Thawte but is not part of their Web of Trust, this would be an e-mail address. Otherwise the owner's name would be entered. If this parameter is omitted, the value entered in the option SuOpt:SignedBy will be used.

pIssuer: The name of the certificate issuer. This does not have to be the entire issuer name string, but the more of the string you use, the better the security. If this parameter is omitted, the value entered in the option SuOpt:CertProviderUp will be used.

Return value: Returns Safeup:OK on success, Safeup:NOTOK otherwise.

SafeUpdate options used in the method:

• SuOpt:SignedBy      (only if the 2nd SignFile parameter is omitted)
• SuOpt:CertProviderUp  (only if the 3rd SignFile parameter is omitted)
• SuOpt:SerialNumber   (you may leave this blank)

Example:
  !-- Sign a version file using the global signer and issuer.
  gSUpdate.SetOption (SuOpt:Signedby, 'me@mycompany.com')
  gSUpdate.SetOption (SuOpt:CertProviderUp, 'Thawte')
  gSUpdate.SetOption (SuOpt:SerialNumber, '')
  if gSUpdate.SignFile ('VersionFile.XML') <> Safeup:OK
    message ('Error signing the version file.')
  else
    message ('OK')
  end 

   !-- Sign an Update File.
  gSUpdate.SetOption (SuOpt:SerialNumber, '')
  if gSUpdate.SignFile ('UpdateFile.SAF', 'someone@capesoft.com', 'Thawte') <> Safeup:OK
    message ('Error signing the update file.')
  else
    message ('OK')
  end 

VerifyFile (string pFilename, <*string pSigner>, <*string pCertInfo>, <*string pCertChain>, <*long pStatus>),bool,proc

Description:
Verify the digital signature of a file. The file can be either XML or a binary file. The Certificate Info example uses this method.

Parameters:
pFilename: The name of the file whose signature is to be verified.

pSigner: The returned name of the signer. If this information is not required, omit the parameter from the parameter list.

pCertInfo: The returned information about the certificate. The information consists of the key length and expiry date. If this information is not required, omit the parameter from the parameter list.

SafeUpdate options used in the method:

• SuOpt:MustBeSignedBy
• SuOpt:CertProviderDown
• SuOpt:SerialNumber
• SuOpt:CertFailures

Example string:

pCertChain: The returned information about the certificate chain, i.e. who issued the certificate. Each item in the certificate chain is separated by two carriage-return + line-feed strings, i.e. <13,10,13,10>. If this information is not required, omit the parameter from the parameter list.

Example string:

pStatus: The error status of the certificate. If this information is not required, omit the parameter from the parameter list. The error value is a bitmap and can be any combination of seven different values:

Signature Errors

Return value: Returns Safeup:OK when no internal errors were encounted, Safeup:NOTOK otherwise. However, pStatus must also be examined to determine if the signature was valid. An easy way to do this is to use the GetSignatureStatus method.

Example:
  !-- Examine a file's digital signature. loc:Status is a long.
  gSUpdate.SetOption (SuOpt:MustBeSignedBy, 'me@mycompany.com')
  gSUpdate.SetOption (SuOpt:CertProviderDown, 'Thawte')
  gSUpdate.SetOption (SuOpt:SerialNumber, '')
  gSUpdate.SetOption (SuOpt:CertFailures, 07fh)
  if gSUpdate.VerifyFile ('UpdateFile.exe',,,, loc:Status) <> Safeup:OK
    message ('Error in the update file.')
  else
    if loc:Status
       message (clip(gSUpdate.GetSignatureStatus (loc:Status)))
    else
      message ('Signature OK')
    end
  end

Safe Update-Defined Events and Equates

Safe Update uses a few Events that are defines as follows:

event:SUactivatewindow equate(0E00h)

This event is posted to the window that called SafeAutoUpdate from SafeDownload. It brings the window to the front and activates it. The event is posted when SafeDownload closes, but not if the application is to be shut down. In that case the event:SUshutdown message is posted instead.

event:SUfinished       equate(0E01h)

When SafeUpload has finished, this event is posted to the window that called SafeUpload. You can add your own code to the TakeWindowEvent procedure. e.g.

of event:SUfinished
  post (event:closewindow)

event:SUgetclientversion  equate(0E02h)

This event is posted within the main procedure if the application is a server and the This is a server application option is checked in the Client/Server tab of the SafeDownload extension and the same option is checked in the Safe Update Auto-update extension of the main procedure.

event:SUshutdown       equate(0E03h)

This event is posted to the main procedure from SafeDownload if the application is shutting down after a successful download of its update file.

Safe Update Equates that might come in useful are:

Safeup:OK    equate(0)
Safeup:NOTOK equate(-1)

These values are returned from the methods described in this document, depending on whether an error has occurred or not.

SafeUpdate:AppVersion 

This global equate is set by you in the Safe Update Global Template in the Options tab. It's value is the string that you enter in the Program Version field. This equate can be used by you as a version string for your application if you choose.

Note: this equate is not available if you have entered the version in the global template as a variable.

Class Properties and Global Variables

Global Variables

There are no global variables since the SUpdate class is already declared globally.

Properties

All the properties accessible to the user are described in Safe Update Options. These are accessed using the SetOption and GetOption methods.

Saved Settings

These settings can be saved either to the registry or to a .INI file. See the Save & Load tab of the Global Extension for the details.

The settings that are saved are listed in the following table. Note that if you change these settings manually you will also have to save them manually using the Save Setting embed.

Safe Update Options and Parameters

These options are accessed through the Safe Update methods SetOption and GetOption.

Global Options
System Parameters
Signing and Uploading Options
Downloading and Verification Options

The various string-length equates are defined as follows:

MaxFilenameLen   equate(255)
MaxDirLen        equate(256)
MaxPathLen       equate(MaxFilenameLen + MaxDirLen)
MaxVersionLen    equate(40)

Global Options

System Parameters 

Signing and Uploading Options

Downloading and Verification Options