


	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

CryptoNite

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

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 apps 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. 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 storing and retrieving of 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.

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)

Safe Update 2 provides a new Client/Server template and classes which provide automated updating across the LAN (without any file sharing).

See the Client/Server section in the main documentation.

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

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).
The Download and Install prompts can optionally be enabled.
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.
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 Updatele 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.

EEnter 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. SiEnter 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 Information. 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:

hhttp://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.

Safe Update Items	Path	Files
Template	Clarion\3rdParty\template\	SafeUpdate.tpl SafeUpdate1.tpw
Source Code Header files TXA Files	Clarion\3rdParty\libsrc\
DLLsbr Executables	Clarion\3rdParty\bin\	libxml2.dll iconv.dll zlib1.dll Safeup.exe
Libraries	Clarion\3rdParty\lib\	crypt32.lib
Images	Clarion\3rdParty\Images\
EExamples	Clarion\3rdParty\Examples\SafeUpdate\

Support

Your questions, comments and suggestions are welcome. Check our web page ( www.capesoft.com/accessories/downloads.htm) for new versions. You can also contact us in one of the following ways:

CapeSoft Support
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Snail Mail	PO Box 511, Plumstead, 7801, South Africa

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

CapeSoft Sales
	Web	www.capesoft.com
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Snail Mail	PO Box 511, Plumstead, 7801, South Africa

Distribution

No extra files are needed for distribution unless you are using SafeUpload. If this is the case you will need to ship the following items with the application.

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

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

Example:
!-- Show the error messages.
gSUpdate.ShowErrors (truebsp;

Less-Frequently Used Methods

CopyUpdateFile:
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'nbsp; end

GetSignatureStatus (long pStatus )

GetSignatureStatus (long pStatus),string

Description:ation for a fullReturns 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.

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

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

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.

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

Key length: 1024
Issued: 4 Apr 2000
Expires: 18 Apr 2001
Algorithm: RSA MD5RSA
Serial no: 75 f2 8e f8 a8 fb ea 6d 11 52 97 14 95 4b 65 5c

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:

Thawte Freemail Member, someone@capesoft.com

ZA, Thawte Consulting (Pty) Ltd., Thawte Personal Freemail Issuing CA

ZA, Western Cape, Cape Town, Thawte Consulting, Certification Services Division, Thawte Personal Freemail CA, personal-freemail@thawte.com

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

Bit Position	Enumeration (2 ^ bitpos)	Error Meaning
0	Safeup:CERTNOTTRUSTED	Certificate not trusted.
1	Safeup:CERTEXPIRED	Certificate expired
2	Safeup:CERTREVOKED	Certificate revoked
3	Safeup:ISSUERSIGFAILED	Issuer signature failed
4	Safeup:ISSUERCERTNOTFOUND	Issuer certificate not found
5	Safeup:MSG_CERTNOTFOUND	Certificate not found
6	Safeup:MSG_ALTERED	Message altered

Return value: Returns Safeup:OK when no internal errors were encountered, 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 at if you change these settings manually you will also have to save them manually using the Save Setting embed.

SuOpt:AskBeforeInstall	Ask the user before installing.
SuOpt.AskUser	Ask the user before downloading update.
SuOpt:AutoUpdate	Auto-update enabled.
SuOpt:LastUpdate	When the last update occurred.
SuOpt:LogErrors	Log any errors to DebugView.
SuOpt:UpdateFreq	Days between updates.

Safe Update Options and Parameters

These options are accessed through the Safe Update methods SetOption 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

Option Name	Property Type	Description
SuOpt:AskUser	bool	When set to true and there is a new version available, the user is asked whether they would like to download it. When set to false, the new version is downloaded with no prompt.
SuOpt:AutoUpdate	bool	When set to true, the application looks for a new version when it starts up.
SuOpt:LastUpdate	long	The value of the day when the new version was last checked for.
SuOpt:LogErrors	long	When set to true, any errors are captured in DebugView.
SuOpt:RandomEnd	long	End of the time during which the application can start updating. This only happens when SafeAutoUpdate is active. The value is in hundredths of a second since midnight.
SuOpt:RandomStart	long	Start of the time during which the application can start updating. This only happens when SafeAutoUpdate is active. The value is in hundredths of a second since midnight.
SuOpt:RegistryFolder	string(MaxFilenameLen)	The folder in the registry where the Safe Update options are stored. This is only relevant if options are being stored in the registry and not in a .INI file.
SuOpt:UpdateFreq	long	The number of days apart that the application must check for updates. If set to zero, the application checks for updates every time it is run.
SuOpt:UserSaveLocation	bool	When the update is downloaded, it may be that it needs to be stored. This is set to true if the user is allowed to specify the storage path.

System Parameters

Option Name	Property Type	Description
SuOpt:CSP	cstring(MaxFilenameLen)	The Certificate Security Provider. This is set to MS_DEF_PROV. This is not present in the template and must be set using the SetOption method. However, changing this value is not recommended.
SuOpt:HashType	string(40)	The desired hash type. Can be set to either SUSign:MD5_Hash or SUSign:SHA1_Hash. The default is SUSign:SHA1_Hash. This is not present in the template and must be set using the SetOption method.
SuOpt:AutoThread	long	The SafeAutoUpdate thread.
SuOpt:DownThread	long	The SafeDownload thread.
SuOpt:MainThread	long	The thread that started the AutoUpdate thread, usually the Main procedure.

Signing and Uploading Options

Option Name	Property Type	Description
SuOpt:AppendToUpdate	string(MaxFilenameLen)	The filename suffix attached to the signed update file.
SuOpt:CertProviderUp	string(MaxDirLen)	Used when uploading. The name of the Certificate Issuer, e.g. Thawte, Verisign.
SuOpt:CreateVersionFile	bool	This is set to true if you want Safe Update to generate the XML version file for you. It is recommended that you leave this option set to true.
SuOpt:FTPMsgDirectory	string(MaxDirLen)	The directory in the FTP server where the update file will be stored. This can also be a local path.
SuOpt:FTPpassword	string(MaxDirLen)	The user password needed to access your FTP server.
SuOpt:FTPServer	string(MaxDirLen)	The name of the FTP server, e.g. ftp.yourcompany.com
SuOpt:FTPUnsignedDirectory	string(MaxDirLen)	The directory in the FTP server where the unsigned update file will be stored. This can also be a local path.
SuOpt:FTPuser	string(MaxDirLen)	The FTP user.
SuOpt:FTPXmlDirectory	string(MaxDirLen)	The directory in the FTP server where the XML file will be stored. This can also be a local path.
SuOpt:UpdateUpFileName	string(MaxPathLen)	The name of the Update File, including its local path.
SuOpt:SerialNumber	string(MaxPathLen)	The serial number of the Digital Certificate used to sign the files.
SuOpt:SignedBy	string(MaxPathLen)	Used when uploading. This specifies the name of the signer of the file.
SuOpt:SignedUpdateFilename	string(MaxPathLen)	The name of the signed update file.
SuOpt:SignFiles	bool	Set to true if you want the files digitally signed.
SuOpt:UploadFiles	bool	Set to true if the files are to be uploaded.
SuOpt:UploadUsingOther	bool	Set to true if the files are to be uploaded using an external application.
SuOpt:UploadProg	string(MaxDirLen)	If an external program is to be used to upload, this is the command line of the external program.
SuOpt:Version	string(MaxVersionLen)	The version of the Update File being uploaded.
SuOpt:XMLupFileName	string(MaxPathLen)	The name of the XML version file, including its local path.
SuOpt:XMLVersionTag	string(MaxVersionLen)	The XML tag used to identify the version in the XML file. The default value is 'version'

Downloading and Verification Options

Option Name	Property Type	Description
SuOpt:AcquiredVersion	string(MaxVersionLen)	The version contained in the XML file specified when SafeDownload is called. It is available after the event:SUactivateWindow event has been posted by SafeDownload.
SuOpt:AskBeforeInstall	bool	Set to true if you want the user to be prompted to run the Update File.
SuOpt:AutoDownload	bool	Set to true if you want auto-updating to be activated.
SuOpt:CacheOff	bool	Doesn't look at your LAN's cache but downloads the update file directly from the HTTP server.
SuOpt:CertProviderDown	string(MaxDirLen)	Used when downloading. The name of the Certificate Issuer, e.g. Thawte, Verisign.
SuOpt:CertFailures	long	Each bit corresponds to a different type of certificate error that is to be examined. If a bit is set, then that error type will be examined. Each bit and its equate string is shown below.
		Safeup:MSG_ALTERED equate(1)	Message altered.
		Safeup:MSG_CERTNOTFOUND equate(2)	Certificate not found.
		Safeup:ISSUERCERTNOTFOUND equate(8)	Issuer certificate not found. Do not examine this bit unless you're sure the user has the issuer of your certificate available in their certificate registry.
		Safeup:ISSUERSIGFAILED equate(16)	Issuer signature failed.
		Safeup:CERTREVOKED equate(32)	Certificate revoked.
		Safeup:CERTEXPIRED equate(64)	Certificate expired.
		Safeup:CERTNOTTRUSTED equate(128)	Certificate not trusted.
SuOpt:DownloadFiles	bool	Set to true if you want to download the Update File from a remote site.
SuOpt:Installer	string(MaxPathLen)	The name of an external installer file. This may be needed if the Update File is not an EXE.
SuOpt:KeepSignature	bool	Set to true if the Update File is to be opened with another program. This would only be used if the external program recognises digital signatures.
SuOpt:MsgdownFileName	string(MaxPathLen)	The name of the Update File, without any path information.
SuOpt:MustBeSignedBy	string(MaxPathLen)	Used when downloading. This specifies the name of the desired signer of the signature being examined. If this is left blank, then any signer will be accepted.
SuOpt:NotSignedOption	long	This determines what happens when an error is detected in one of the digital signatures while downloading. It is set to one of four values:
		SUSign:Ignore equate(0)	Ignore any signature errors.
		SUSign:Warn equate(1)	Gives the user a choice of either ignoring the signature error or aborting the update
		SUSign:Abort equate(2)	Displays an error message and aborts the update
		SUSign:AbortSilent equate(3)	Aborts the update without any messages
SuOpt:RunFileAfterDownload	bool	Set to true if the Update File is to be run after it is downloaded.
SuOpt:RunInstaller	bool	Set to true if an external installer is needed to install the Update File. This may be needed if the Update File is not an executable.
SuOpt:StoreFileAfterDownload	bool	Set to true if the Update File is to be stored after it is downloaded.
SuOpt:StoreLocation	string(MaxDirLen)	The path where the Update File is to be stored.
SuOpt:TempLocation	string(MaxDirLen)	The path where all downloads go. When the user's application starts, all the files in this path are deleted.
SuOpt:VerifyFiles	bool	Set to true to verify the digital signatures.
SuOpt:XMLDownFileName	string(MaxPathLen)	The name of the XML version file, without any path information.

For those that care: the XML Version File

SafeUpdate can create XML version files for you automatically, and it is recommended that you do this. An example unsigned XML file created by Safe Update looks like this:

<?xml version="1.0"?>
<info>
<filename>"demo.xml"</filename>
<version>2.00</version>
<date>4 AUG 2005</date>
<time>12:06:29</time>
</info>

The filename has been included to make sure that the name of the file has not been changed. The date and time have been included so that there is an excellent chance that SafeUpdate won't ever create the same signature twice.

Making your own XML version file
If you decide to create your own XML files, although there's no need for that, only the <filename> and <version> fields are necessary. These fields must be enclosed in the <info> section. The <?xml version="1.0"?> tag is added when the file is signed.

After the file above is signed by Safe Update, it will look like this:

<?xml version="1.0"?>
<Envelope xmlns="urn:envelope">
<info>
<filename>"demo.xml"</filename>
<version>2.00</version>
<date>4 AUG 2005</date>
<time>12:11:54</time>
</info>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <ds:Reference URI="#obj" Type="http://www.w3.org/2000/09/xmldsig#;Object"/>
      <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
    </ds:SignedInfo>
<ds:SignatureValue>MIIDngYJKoZIhvcNAQcCoIIDjzCCA4sCAQExDzANBgkqhkiG9w0BAQUFADALBgkqhkiG9w0BBwGg
ggJPMIICSzCCAbSgAwIBAgIDDsbTMA0GCSqGSIb3DQEBBAUAMGIxCzAJBgNVBAYTAlpBMSUwIwYD
VQQKExxUaGF3dGUgQ29uc3VsdGluZyAoUHR5KSBMdGQuMSwwKgYDVQQDEyNUaGF3dGUgUGVyc29u
YWwgRnJlZW1haWwgSXNzdWluZyBDQTAeFw0wNTA1MjQxMjU5MTVaFw0wNjA1MjQxMjU5MTVaMEMx
HzAdBgNVBAMTFlRoYXd0ZSBGcmVlbWFpbCBNZW1iZXIxIDAeBgkqhkiG9w0BCQEWEXBhdWxAY2Fw
ZXNvZnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4a7oQlzHnuMF56IqbaZ8ALM3k
Upfd74EIfSIELCDmIOzzURjuzWz0+B0yfB3DW50wNN+LutW5rQ0+eK2c8RIVqcPwlSgwB+H40/fE
N2mBH8UkkdMmbZIy/fWyZBzzDmmgOTV0JLb8Rf/jIt1mNyaBUHVVowBQPZo1Uurcp/qnoQIDAQAB
oy4wLDAcBgNVHREEFTATgRFwYXVsQGNhcGVzb2Z0LmNvbTAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3
DQEBBAUAA4GBAJnqx0oTLwn08bvaU3SZMGJy+PDqNdgQq6AWxo5FuIcciudGEWeaWYXfYVZxB2Wd
b0hcpYLC4VAdJ9Mvd/6Wd6D9Spj3k8QD13dF2dXCxGcFgZb2Sa5RkuMco/z1JQoZdazGKQRsr2Ph
0QuiDsBd+M+dUd6G3Icr6TFxZZQqcE7BMYIBEzCCAQ8CAQEwaTBiMQswCQYDVQQGEwJaQTElMCMG
A1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNv
bmFsIEZyZWVtYWlsIElzc3VpbmcgQ0ECAw7G0zANBgkqhkiG9w0BAQUFADANBgkqhkiG9w0BAQEF
AASBgJhcYbfIBXbxcpHRayBYRQVCdU0/2A7qBdaaAEWA/Qe48xN7LAl8KaLEXOrS+p6Fg0TGyo6X
sQkoC/7a0uv1SMnFxTgFYkFw/7NkA170MqB2AMVkkbSQ/he8efkG3BjJekx5h3WC7mEK3POkrvpC
5MznL8A/SZxPCnxPmH7th04X</ds:SignatureValue>
</ds:Signature>
</Envelope>

The ds:SignedInfo section is for information only and is not used. Changing this part of the file will not cause a signature error.

Incidentally, one character in the signature in the above file is incorrect (for security purposes, of course): you'll have to use SafeUpload to generate the proper signature.

Acknowledgements

This template was written with the aid of the following software:

LibXML2. LibXML2 stuff can be found at http://xmlsoft.org/downloads.html