Introduction
     Please Note : Safe
        Update 3 requires Cryptonite,
        StringTheory and NetTalk (Desktop) to work.
        These items are sold separately.
      
      Safe Update allows you to upgrade your program over an internet connection
      
securely and 
automatically.
      It adds a Check for Updates option to your program, and also provides a
      framework for pushing updates to your users in a safe manner.
      
      Safety is important here because if your program is being updated
      automatically, or manually on-demand by the user, then you want to be sure
      that the content they are downloading and using is content you intend for
      them to have. If a hacker accessed your web server, and replaced your
      install file, then you do not want the upgrade to be applied.
      
      Safe Update can update from a shared network drive, from a local intranet
      web server, or from a web server on the internet. 
      
      When your application is updated you need to make sure that the update
      being downloaded is the genuine article and not a malicious file instead.
      To achieve this Safe Update includes security in the form of digital
      signatures. 
      
    
 
    
    Upgrading from Safe Update 1 and 2
     Safe Update 3 has been refactored to make
      implementation much easier to do, and much easier to maintain in the long
      run. To this end the simplest way to update to Safe Update 3 is to remove
      the Safe Update 1 or 2 support, and then re-implement Safe Update 3. Since
      it takes only a few minutes to do this it is a cleaner solution than
      trying to maintain backwards compatibility.
      To remove SafeUpdate 1 or 2 from your application;
      
        - Delete the SafeDownload and SafeAutoUpdate procedures from your app
- Remove the Safe Update local extension to your Main procedure.
ClarionLive
     ClarionLive
      
        webinar number 183 is an excellent walk-through of the Safe Update
      process. Watching the webinar is recommended.
      Tip: Right click on the link, and choose "Save Link As..." to save the
      webinar as a file on your disk. 
 
    The Basics
     If you are keen to get started right away it is
      recommended that you start with the 
JumpStarts
      below, but before you get going it's a good idea to read the rest of this
      section to make sure that you're familiar with the basic concepts and how
      everything fits together.
      
      There are three basic areas of functionality that SafeUpdate provides:
      
        - 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.
 
- Uploading
 
 This is simply the process of getting the update (your application
          installer) to the location that the application will download it from.
          It includes creating an XML version file for the update, and uploading
          the files via FTP to the web site.
- Check for Updates
 
 This includes downloading an update, either from the internet or LAN
          and performing whatever task is required to install that update. This
          usually means running an installer and closing down the application to
          allow the install to work. SafeUpdate handles checking for updates,
          downloading, verifying updates and running the installer for you.
Jump Start
    
      
      Getting a certificate
       The Safe part of Safe Update is done by signing the
        Install file and Version file before they are uploaded to the web site.
        Signing requires a certificate.
        
        Getting a certificate can be a time consuming process, because it needs
        to be issued by a company that trusts that you are who you say you are.
        If you don't already have a code-signing certificate then you can read
        the section "
Getting a Digital
          Certificate" to find out how to get one.
        
        However because this is a JumpStart, and because that process may take
        some time, a sample (UNTRUSTED) certificate called "Safe Update Test"
        has been included in the Safe Update install file. You would not want to
        use this certificate in a real world situation, however it does provide
        a substitute for the purposes of getting the basic process in place. 
      
Adding a Version Resource to your
        Application
       Note that while this section is not required in your
        application, it is recommended.
        
        Adding a Version Resource to your application embeds a standard Version
        Resource file into your EXE. This allows the version information to be
        read from the EXE and also provides the version information displayed
        from the application in Windows (e.g. In Explorer and the Programs and
        Features control panel).
        
        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 to your application.
- Enter the details for your application, including the version
            number (this should be updated each time you update your application
            to a new version). The version number can include an automatically
            generated build-number.
- If you wish to make use of the  WinEvent function  ds_GetFileVersionInfo in your own code, then
            add the WinEvent global extension to your application
 
Adding a "Check for updates" to your
        application 
       This Jump Start shows you how to add Safe Update to
        your application in order to be able to download updates. This guide
        steps you through:
        
          - Adding the global extension to your application
- Importing the SafeDownload function into your application
- Entering the Download settings
- Adding the Local extension to the Main procedure
1. Adding the Safe Update Global
          Extensions to your Application.
         To add the Safe Update template to your program,
          add the following to your application's 
Global
            Extensions:
          
            - Activate_NetTalk - Activate CapeSoft's NetTalk.
- Activate_SafeUpdate - Activate CapeSoft Safe Update.
- Activate_Cryptonite - Activate CapeSoft Cryptonite. 
- Activate_StringTheory - Activate CapeSoft StringTheory
2. Import the SafeDownload Function
         Go to the 
Application ->
 Template
            Utility menu item and go to 
Class Safe
            Update - CapeSoft Safe Update. 
          
          Select 
ImportSafeUpdateDownloadABC (for
          ABC apps) or 
ImportSafeUpdateDownloadLegacy (for
          Clarion/Legacy apps). 
          
          A procedure, called 
 SafeDownload will
          then be added to your application. Note that the names of this
          procedure must not be changed. You can however change the "look" of
          the window if you wish to.
3. Customize the Settings in SafeDownload
         On the 
SafeDownload
          procedure extensions go to the 
Safe Update
            Download Controls local extension. 
          
          On the 
Options tab of that extension , fill
          in the URLs of update file, and the XML version file.
          
          NOTE: The file names on this tab are either local, or HTTP. Not FTP.
          The download uses the HTTP protocol, not the FTP protocol. 
          
          NOTE: You can make these names variables in which case you must prime
          the variables in embed code before the call to the SetDownloadOptions
          method call in the 
ThisWindow.Init (or 
PrepareProcedure routine for legacy
          applications).
          
          The XML version file can have any name - it'll match the name you use
          in the SafeUp utility later on. (usually it's the same name as the
          update file, but with an xml extension.)
          
          On the 
Verify tab enter the name of your
          certificate in the 
Must be signed by
          setting.
4. Add the Local extension to your Main procedure
         Go to the local extension of your 
Main
          procedure. 
          Add the 
 AutoUpdate -
            Safe Update Auto Update local extension. This will allow your
          application to check for updates automatically. 
          
          Optionally, if you would like a menu item, or button to trigger an
          immediate "check for updates", then create the item or button and
          enter the use equate for that control on the Manual Update tab. 
Signing and Uploading Updates to
        your HTTP server
      
        Creating an Install File
         The update being downloaded by your program is
          typically an Installer. The installer can be a custom executable or
          created with an install system such as SetupBuilder, Wise or even
          Visual Studio. Using a proper install system to create installers is
          highly recommended as it ensures that updates work well under all
          versions of Windows, including those such as Windows 8, Windows 7,
          Windows Vista and Windows Server 2008, which provide additional
          security and use UAC (User Access Control).
          
          If you don't currently have an installer for your application, then
          you will probably need to create one using SetupBuilder, or your
          preferred tool. 
          
          Before creating the install for the new version increment the
          application version and build the app. If you are entering the version
          directly in the SafeUpdate global extension then change the version
          here, or if you are using a version resource then change it in the
          cwVersion Resource global extension. 
        
        SafeUpdate Utility
        The process of signing and uploading the files is done by a utility
        called SafeUp3.Exe.
        
          - The SafeUpdate Utility (SafeUp3.exe) is installed into  \Clarion\Accessories\bin\SafeUpdate.
- A shortcut to the SafeUpdate Utility is placed in the Start Menu
            under All Programs->Clarion
              Accessories->Safe Update->SafeUpdate Utility
- SafeUp can be accessed directly by selecting the menu Tools->CapeSoft
              Tools->SafeUp utility
- The source code for the utility is provided in the Examples\SafeUpdate\Uploader
            folder. The app can be opened in Clarion 9.1 or later, and requires
            WinEvent, xFiles, Cryptonite and StringTheory to compile.
          - Run the SafeUp.Exe utility. It looks something like this;
 
  
- The first thing to do, when running it for the first time, is to
            click on the Import Certificate (PFX Format) button. This will
            import the PFX file into the Windows Certificate Manager. 
 
  
 
 If you have your own code signing certificate, then go ahead and
            enter the details for it here. You will need to know the password to
            the PFX file in order to import it correctly. If you do not have a
            certificate yet, then go ahead an import the Safetester.Pfx file
            (which is in the \examples\safeupdate\uploader folder). The password
            to this certificate is capesoft
            - one word, all lower case, no punctuation. You can leave the Store
            field blank.
 
 Once you have imported the certificate you can open the Windows
            Certificate Manager using the button provided. If you expand the
            Personal Certificates item in the tree, then you should see your
            certificate (or the Safe Update Test certificate) listed there.
 
  
 
 
- Ok, back to the SafeUp main screen. Time to add your product to
            the list. Click the  Insert button to add
            a new entry for your install file. The form looks something like
            this;
 
  
 
 Note there are two tabs of settings, one to do with the signing, and
            the other to do with the FTP uploading.
- Enter the settings for the Installer and XML Version File
            
              
                
                  | Update File (Exe) | The name of the Install file which contains the update. |  
                  | XML Version File | The name of the xml file which will contain the version
                    number, and signatures |  
                  | Update File Version | The version of the update (if you are not using the File
                    Version Resource) |  
                  | Read File Version from File | Tick this on so that the file version as set by your
                    install script is used. |  
                  | Signed By | The name of the certificate. The example certificate name
                    is Safe Update Test |  
                  | FTP Server | The URL of the FTP server. |  
                  | FTP User | The User Id required by the server (ie the server login) |  
                  | FTP Password | The password for the user. |  
                  | Update File Directory | The remote directory, on the server, where the update file
                    must be placed. |  
                  | XML File Directory | The remote directory on the server where the xml file must
                    be placed. (Usually the same place as above.) |  
 It's also probable that your install file is code-signed as part of
            the installer-creation process. The signature added by Safe Update
            does not "code sign" the installer, so you should continue to code
            sign the install file yourself as part of your build process.
 Click on OK to save the new record.
 
-  Click on the Sign button if you wish to just create the signed
            files. A copy of the Exe will be created and signed, and the XML
            version file will be created and signed.
-  Click on the Sign and Upload button to sign the file, and also
            upload it to the web server.
 
     
    Using an Old NetTalk (NetTalk 9 and earlier)
     From build 3.13 the suHttpClient.PageRecieved
      method has been updated to support NetTalk 10.
      If you want to upgrade SafeUpdate, but remain on an older version of
      NetTalk then you will need to change supdate.clw
      
      Search For NetTalk 9 Version of PageReceived and
      uncomment that. Comment the NetTalk 10 version of the method below that.
      
      In the following method (.Process) there is a
      single line which has been commented out and replaced for NetTalk 10.
      Reverse the comments there as well.
    
    
    
      How do I making Updates Mandatory?
       There are certain cases where an update is not
        optional - if an update is available the user must install it, or the
        program will not run. 
        
        Consider for example where a program is installed locally on a LAN where
        every desktop has its own copy of the program, but where all the copies
        use a common data folder. In this situation if one machine on the LAN is
        updated then all the machines HAVE to be updated or the old ones will be
        unable to access the data.
        
        Because the use case for this is data related, it's important to do the
        check-for-update before the Frame opens, and before any data tables have
        been accessed.
        
        If you have a multi-DLL setup it means you should have the SafeDownload
        procedure in the Data DLL and you should set the global switch (as
        described in a moment) in the Data DLL. If the SafeDownload procedure is
        not in the Data DLL then you will need to set the global switch in the
        app with the procedure, but then the startup code in the Data DLL may
        access tables before the update check runs.
        
        To turn on mandatory updates go to the Safe Update global extension (in
        the app with the SafeDownload procedure). Go to the Options tab. And
        turn on the setting Program HAS to be on the latest version.
        
        Optionally turn on the Show check if slow option as well. If this is on,
        and the initial XML file check takes longer than 2 seconds, then the
        SafeDownload window will appear. In most cases the check will take far
        less than 2 seconds to do so the user will not normally see the window
        on startup. If an update IS waiting, then the SafeDownload window will
        appear as soon as it starts downloading the update. If the user Cancels
        the download then the program will terminate.
         
        Once the update has been downloaded the Install program will run and the
        current Exe will terminate. The user can then complete the install, and
        return to the program as usual.
      
      How do I only warn the user of an
        update?
       In your SafeDownload procedure, derive the
        AskToUpgradeWin method, and handcode your condition around the parent
        call. For Example:
        SafeDownloader.AskToUpgradeWin Procedure () 
          code 
            if ThisIsAWorkstation 
              0{prop:hide} = true 
              message('This appears to be a workstation.|There is an update
        ready (version ' & clip(self.newversion) & ') which you need to
        run at the server.','Update Note',icon:exclamation) self.buttoncancel()
        post(event:closewindow) 
            else 
              parent.AskToUpgradeWin() 
            end 
      
     
    Examples
     We strongly recommend using the 
JumpStart
      provided, as this provides the best way to get acquainted with the
      functionality provided by SafeUpdate.
      
      
Demo - Demonstrates downloading and
      verification of updated using SafeUpdate.
      
      
Certificate Information - Demonstrates
      retrieving certificate information. For 
certificate
        viewing and management use the tools provided.
      
      
Uploader - Signing and Uploading application. A
      compiled version of this SafeUp3.exe application is shipped with
      SafeUpdate and installed into the Accessory\bin directory (or 3rdparty\bin
      for Clarion 6 and earlier).
      
      These examples are in your \Clarion\Examples\SafeUpdate directory. 
Getting a Digital Certificate
     A Digital Certificate is needed in order to sign your
      update file. For SafeUpdate a Code Signing certificate is required (other
      certificates types can also be used, although a code signing certificate
      is recommended). For testing purposes free mail certificates can also be
      used.
      
      Purchase a code signing certificate from a vendor such as Comodo. Other
      options are Thawte and VeriSign, although both are typically a great deal
      more expensive. Certificates can be renewed every year, two years, or
      three years. Purchasing a three year certificate is slightly cheaper per
      year. For SetupBuilder users, Comodo certificates can be purchased through
      
        Lindersoft for a major discount.
      
      
Comodo
      
      Certificates cost (at the time of writing) $179/year, or $167 per year if
      a 3 year certificate is purchased. For SetupBuilder users purchasing
      Comodo certificates through 
        Lindersoft brings the price down to $79 per year, $143 for 2 years,
      and $200 for three years.
      
      
http://www.comodo.com/e-commerce/ssl-certificates/code-signing-certificate.php
      
      For Lindersoft SetupBuilder users, who need a code signing certificate to
      sign their application anyway, purchasing certificates through LinderSoft
      is a no-brainer (they also offer SSL certificates for securing web sites
      at a major discount):
      
      Comodo allows the inclusion of a support email address in the certificate
      details (the only provider who does so at last check).
      
      
Verisign and Thawte
      
      Verisign ($499/year):
        http://www.verisign.com/code-signing/index.html?sl=a_box
      
      Thawte ($299/year, no three year option): 
        http://www.thawte.com/code-signing/index.html
      Installing Certificates
      This section covers installation of PFX certificate files (which is the
      file format used by Windows). Certificates come in a variety of formats,
      and often the certificate will be provided separately from the private
      key. If your certificate is not provided as a PFX file then it can be
      converted to one - see 
Converting
        Certificate Formats.
      
      Installing a PFX is as simple as double clicking on it and following the
      import wizard. You can also use either of the tools in the Viewing and
      Managing Certificates section below to install (import) and export
      certificates, as well as viewing their contents.
      
      Alternatively you can use the SafeUp utility to import the certificate.
      
Viewing and Managing
        Certificates
      Certificates and private keys are provided in a variety of formats, such
      as PFX, PEM, CRT etc. Converting between the various formats can be done
      using the tools provided with SafeUdate. See 
Converting
        Certificate Formats below.
      
      Certificates can be viewed and managed using one of two tools:
      
        - Certmgr.exe
 
 Provided with SafeUpdate and installed into the Clarion\3rdparty\bin\SafeUpdate
          (Clarion 6 and earlier) or Clarion\Accessories\bin\SafeUpdate
          (Clarion 7 and later) directory
- Certificate Manager Snap-in
 
 This is a snap-in for the Microsoft Management Console (MMC) included
          in most versions of Windows. Adding the snap-in:
 
 
            - 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.
      
      
 
      Code Signing
      Install tools such as SetupBuilder provide built in code signing support,
      which is the simplest approach. Code signing can also be done using the
      signtool.exe that SafeUpdate installs in the
        Clarion\3rdparty\bin\SafeUpdate (Clarion 6 and earlier) or 
Clarion\Accessories\bin\SafeUpdate (Clarion 7 and
      later) directory.
      
      This tool can be called using a Wizard interface, on the command line, or
      automated using a batch file:
      
      
        - 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.
 
- 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.
 
 
- Signing using a batch file
          
            - This is identical to signing on the command line except that the
              calls to SignTool are added to a batch file (a text file with the
              .bat extension). This batch file can be run to make the calls to
              SignTool each time that it is needed.
 
Converting Certificate Formats
      Certificates and private keys are provided in a variety of formats, such
      as PFX, PEM, CRT etc.
      
      SafeUpdate installs a folder called SafeUpdate in the
        Clarion\3rdparty\bin\SafeUpdate (Clarion 6 and earlier) or 
Clarion\Accessories\bin\SafeUpdate (Clarion 7 and
      later) directory. This contains a number of useful tools, including two
      specifically for certificate and key conversion:
      
        - 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.der
          
         Convert PEM to P7B
          
          openssl crl2pkcs7 -nocrl -certfile certificate.cer -out
            certificate.p7b -certfile CACert.cer
          
         Convert PEM to PFX
          
          openssl pkcs12 -export -out certificate.pfx -inkey
            privateKey.key -in certificate.crt -certfile CACert.crt
          OpenSSL Convert DER
         Convert DER to PEM
          
          openssl x509 -inform der -in certificate.cer -out
            certificate.pem
          OpenSSL Convert P7B
          
         Convert P7B to PEM
          
          openssl pkcs7 -print_certs -in certificate.p7b -out
            certificate.cer
          
         Convert P7B to PFX
          
          openssl pkcs7 -print_certs -in certificate.p7b -out
            certificate.cer
          
          openssl pkcs12 -export -in certificate.cer -inkey privateKey.key
            -out certificate.pfx -certfile CACert.cer
          OpenSSL Convert PFX
          
         Convert PFX to PEM
          
          openssl pkcs12 -in certificate.pfx -out certificate.cer -nodes
          
          You can add -nocerts to only output the private key or add -nokeys to
          only output the certificates.? 
      
Certificate Information
     You will not need to get a certificate if you are only
      downloading files as the Update File will already have all the necessary
      certificate information embedded in it. However, if you want to check the
      the serial number of the certificate, then reading the following paragraph
      may be useful.
      
      How to Find the
        Certificate's Serial Number
      
      Open the Windows Certificate Manager. The easiest way to do this is Press
      Windows-R (Start / Run) and type 
CertMgr.Msc
      
      This will display a list of all the certificate stores on your computer.
      The certificate you require should be in the '
Current
        User/Personal' store. 
      Double click on the certificate to open it. Then go to the Details tab of
      the certificate and highlight the Serial Number field. From here you can
      copy the serial number to the clipboard.
      
    
Programmer's Guide
    
      
        - I want to check for updates on startup - if an
            update exists use is mandatory
 See the section Making Updates Mandatory.
- I
            want to check for updates on startup
 This option is already enabled by default when you add Safe
          Update to your application. the check will run once per day, and will
          only happen after the Frame appears, and the application is running.
          However, you must make sure the AutoUpdate
          local extension has been added to your application's main window.
- I want to check for
            updates every couple of days
 Go to the SafeDownload procedure, to the Extensions, Auto tab,
          and enter the options there.
- I want the user to be
            able to check for updates manually
 See here in the JumpStart.
 
- I
            want to use Safe Update in a multi-DLL application
 
 The easiest approach is to add SafeUpdate to the exe app as normal.
          (However if mandatory updates are required then see here.)
 
 
            - Add NetTalk, Cryptonite, SafeUpdate and StringTheory to the root
              DLL, setting their Multi-DLL settings as appropriate.
- Add Safe Update,Cryptonite, NetTalk and StringTheory to your EXE
              setting the Multi-DLL settings as appropriate.
- Import the SafeDownload procedure into the exe app.
 
- My application gets sent to the system tray when
            the window is closed. How can Safe Update shut it down properly?
 You'll have to add your own code in this case. You would
          probably set a global flag that would tell your application to shut
          down completely. Add your code to the event:SUshutdown
          event in your main window. You will need to add the AutoUpdate
          extension to your main window first.
 
    Template Reference
    
      
      Global Extension
      
        Global General Tab
        
          Disable All SafeUpdate Features
          Disables all Safe Update code. This is useful for debugging to find
          out whether a problem is being caused by Safe Update.
        
 
        Version Tab
        
          Use WinEvent to extract from Version resource
          If you have WinEvent added to this application, then you can check
          this box for WinEvent to detect the version of this exe. This means
          you can use an external version resource generator to apply the
          version resource to your application.
          
Program Version
          The current version of this application. This can be any string, so
          long as it is fewer than 40 characters long.
          
Tip: The global variable 
SafeUpdate:AppVersion
          is set when your program starts (using either WinEvent or the template
          setting) so that it can be used in your program - like on Help / About
          screens and so on.
          
Program Name
          Used for display purposes only. This name will appear at various
          places in the 
SafeDownload window. 
 
        Options Tab
        
          Program HAS to be on the latest version
          If this is on the updates to the system are mandatory, and the old
          program will not run if a new program exists. For more information on
          this setting see 
Making Updates Mandatory.
          
Show Check if Slow
          If Mandatory updates are set, and the check for the XML file takes
          more than 2 seconds, then the SafeDownload window will appear. 
 
        Multi-DLL Tab
        
          This is part of a Multi-DLL program
          Tick this on if this is a DLL, or if this is an EXE and is part of a
          multi-app system.
          
Export SafeUpdate Class from this DLL
          Tick this on if this is the Data DLL where the SafeUpdate class will
          be exported from. 
 
       
      Local Extension to the Main Procedure
       This extension is added to the MAIN procedure in the
        application. It automatically starts the SafeDownload procedure after
        the MAIN procedure starts. Usually the SafeDownload is started hidden,
        so it operates quietly in the background.
        
Manual Control
        If you have a control in the procedure (perhaps a menu item, or toolbar
        button) then you can select that here. When the user selects this
        control then the SafeDownload window will appear, and it will do a check
        immediately.
        
Auto Check on Startup
        You can enter an expression here. If it evaluates to 
true,
        then the download window will (silently) check for an update when your
        program starts. (The user will be informed if an upload is available.)
        This check will happen after the Frame is opened, and potentially after
        the database has been accessed. To force an update check before the
        database is accessed see the section  
Making
          Updates Mandatory.
        
        You can enter an expression here. If it evaluates to 
true,
        then the download window will hide itself (if not already hidden) when
        it is run from the MAIN procedure after the first check. Once hidden it
        will re-check from time to time based on the timer (about once a day).
        If this evaluates to 
false, then the window
        will simply do one check and then close.
      
SafeDownload Control
        Template
       This extension is added to the Safe Download
        procedure.
        
Options Tab
        
          Update File
          The path to the update file. Can be either a file on the LAN, an
          intranet URL or a web URL.
          
XML version file
          The path to the version file. Can be either a file on the LAN, an
          intranet URL or a web URL.
          
Local Folder for downloaded files
          By default downloaded files will be placed (if validated) in the temp
          folder. However if you want accepted files to be placed in a specific
          folder then you can enter it here.
          
INI File
          Some settings are stored in an INI file (Last check date and version
          to ignore). Enter the ini file name here.
          
Ask User before Downloading
          If this is on then the user will be asked before an update file is
          downloaded. (The user will always be asked before an update file is
          applied.)
          
Installer: Run the following file instead
          If the file being downloaded is not an install file, and a separate
          install program exists, then you can enter that alternate program name
          here.
          
Run the program with the following parameters
          Allows parameters to be passed to the downloaded file (or alternate
          installer file) when starting the update. 
 
        Auto Tab
        
          Do Automatic Checking
          If this is on then the program will continue to check for new versions
          automatically, at regular intervals.
          
Check every (days)
          Determine the number of days between checks. Set this to 1 to do a
          check every day.
          
Check from Midnight To
          This will randomise the check between midnight and some specific time
          every day. By randomizing the check the server is not overloaded by
          all the sites checking at the same time. A typical value here is say
          4:00 which means that all sites will do their check sometime between
          midnight and 4am. 
 
        Verify Tab
        
          Must be signed by:
          Enter the name of the signer who will sign the updates here. Setting
          this is highly recommended.
          
Or:
          If the name of the signer is changing, and you know this in advance,
          then set the alternate name here. This will enable you to sign the
          applications with the new signer name after the version with the new
          name is installed.
          
Cert Authority
          (Not currently used). This will be used to limit certificates to those
          issued by a specific authority. Using this will reduce your ability to
          change to a new certificate authority in the future.
          
Cert Serial Number
          (Not currently used). This allows you to require that the update is
          signed by a certificate with a specific serial number for added
          security.
          
Errors to check
          Various items in the certificate which should be checked. It is
          recommended that all these options are set on.
          
Failure Option
          (Not currently used). Currently if a certificate check fails the
          update is discarded. 
        
 
       
     License & Copyright
     This template is copyright 2025 by CapeSoft Software.
      None of the included files may be distributed. Your programs which use
      Safe Update can be distributed without any royalties.
      
      This product is provided as-is. CapeSoft Software and CapeSoft Electronics
      (collectively trading as CapeSoft), their employees and dealers explicitly
      accept no liability for any loss or damages which may occur from using
      this package. Use of this package constitutes agreement with this license.
      This package is used entirely at your own risk. 
      
      Use of this product implies your acceptance of this, along with the
      recognition of the copyright stated above. In no way will CapeSoft , their
      employees or affiliates be liable in any way for any damages or business
      losses you may incur as a direct or indirect result of using this product.
      
      For the full EULA see 
https://capesoft.com/eula.htmlVersion History
     Download latest version 
here
      
      Version 3.21 (2 October 2025) 
      
      
        - Update: Supdate.Inc, SafeUpdateUpload class was using
          StringTheoryDLLMode and StringTheoryLinkMode. Changed to
          SafeUpdateDllMode and SafeUpdateLinkMode.
Version 3.20 (2 June 2025)
        - Fix: Type bug in template caused it to not register.
Version 3.19 (27 May 2025) 
      
      Version 3.18 (9 February 2023)
        - Change: Download progress text.
- Fix: Progress bar during download could fail to update.
- Remove: DOS file declaration
Version 3.17 (24 May 2021)
        - Add: Clarion 11.1 to install.
Version 3.16 (14 Sept 2018)
        - Add: Clarion 11 to install.
Version 3.15 (11 July 2018)
        - Fix: SafeDownload object generated with the potential methods from
          the wrong class.
Version 3.14 (17 April 2018)
      
      Version 3.13 (31 July 2017)
        - Make compatible with NetTalk 10 web client. If you are using an old
          NetTalk then see this Using Old NetTalk.
Version 3.12 (12 January 2017)
        - Updating to Cryptonite 1.85 or later is
            recommended. 
- Add: Make Updates Mandatory feature.
- Internal: Class changed from using StringTheory DLL and Link Mode to
          SafeUpdate DLL and Link Mode.
Version 3.11 (5 December 2016)
        - Updated SafeUp3.Exe (Sign and Uploader.) - some cosmetic visual
          entry field bugs.
- Fix: If statement in ProcessFile was incorrect.
- Update: Some window messages did not have a . on the end of the
          message.
Version 3.10 (14 November 2016)
        - Updated SafeUp3.Exe (Sign and Uploader.)
- Add: csError.Trace method
- Change: SignMessage now includes the whole certificate chain, not
          just the lowest certificate
- Change: VerifySignature can return the message embedded in the
          signature
- Internal: Rename SU_DSGetVerificationCertificate to
          Callback_DSGetVerificationCertificate
- Internal: New Method BuildCertArray
Version 3.09 (25 February 2015)
        - Clarion 10 Install
- Add: Support for SSL options (in SafeUploader template, and
          example).
 Version 3.08 (29 January 2014) 
      
        - Add: Property DontAllowAskNoUpgrade
- Clarion 9.1 Install
Version 3.07 Beta (14 October 2013)
        - Fix: Version number comparison could fail if version on web site is
          older.
- Fix: calls SafeDownload GetFileFailed in the errortrap of the
          suHTTPClient (and pagereceived if the server response is not OK), as
          well as the GetLocalFile of the SafeDownload class.
- suHttpClient.Process calls new SafeDownload.SetProgress (allows
          derived code).
- SafeDownload - new property: keephidden, set if no window must be
          shown (interaction handled by another window).
- Fix: if version currently running is newer than the version on the
          site, does not offer to downgrade (useful for different download
          "areas" - i.e. beta, gold, etc).
- SafeDownload - new methods: CertificateFailed and GetFileFailed
          allow derived methods to handle these two scenarios in your
          application; NextAutoUpdate - determines time and date of next update.
- SafeDownload.ProcessVersionInfo - moved self.gettingxml=false to
          after the errortrap (allows errortrap to be handled differently for
          xml version file and install file).
- Fix: SafeDownload.RunSetup. Was passing equated cstring parameter
          without clipping.
 
Version 3.06 Beta (18 June 2013)
        - Update: Example updated to include StringTheory Global Extension
- Change: Format of date in INI file changed to formatted value, not
          Clarion LONG value.
- Add: DaysToInstall, CheckTimeStart, IgnoreLastCheckDate,
          DownloadCompleteAt, DontCloseDown, TimeBetweenChecking properties.
- Add: CheckATime method.
- Add: Parameter to StartUpdate method (Force).
Version 3.05 Beta (14 May 2013)
        - Update: Installer detects Clarion 9
Version 3.04 Beta (14 March 2013)
        - Changed to Ver4 object/template management system. IMPORTANT
           READ
              THIS.
- Add: support for Multi-Proj in C8
Version 3.03 Beta (20 November 2012)
        - Version stamps were not being updated by build system.
Version 3.02 Beta (11 November 2012)
        - NOTE: You will likely need to
          update Cryptonite and StringTheory
          to use this build.
- Fix: Some FTP servers could change the xml file on upload. (Requires
          StringTheory 1.67)
- Fix: update.clw still referenced deprecated file CryGenApi.inc
- Change: FTP uses / in file names not \. (Template option in
          SafeUp3.app)
Version 3.01 Beta (9 November 2012)
        - Update: Build process fixed.
Version 3.00 Beta (7 November 2012)
      
      Version 2.02 Beta (23 December 2011)
      
      Requires Cryptonite 1.42 or later.
      
        - Update: Compatible with Cryptonite 1.42
- Added File Locked methods
- Added ability to suppress messages
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.
 
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 certificate 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 relevant if GetLastError indicates
          that 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 automatic 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. 
Version 1.11 Beta (25 November 2005)
        - 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.
Version 1.10 Beta (16 November 2005)
        - 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'.
Version 1.09 Beta (21 October 2005)
        - 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.
Version 1.08 Beta (6 October 2005)
        - 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.
Version 1.07 Beta (4 October 2005)
        - 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.
Version 1.06 Beta (3 October 2005)
        - 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.
Version 1.05 Beta (29 September 2005)
        - 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.
Version 1.04 Beta (23 September 2005)
        - 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.
Version 1.03 Beta (21 September 2005)
        - 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.
Version 1.02 Beta (20 September 2005)
        - Bug fix: didn't read the application name from the cwVersionRes
          file.
Version 1.01 Beta (16 September 2005)
        - 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.
Version 1.00 Beta (14 September 2005)
        - First release of CapeSoft Safe Update.