DOCSEARCHbyAlgolia
Submit Docs

WinSparkle Documentation

repository·master·Indexed 20 days ago

https://github.com/vslavik/winsparkle

An automatic update framework for Windows applications inspired by the Mac Sparkle framework. It utilizes appcasts for update definitions and supports secure cryptographic signing using EdDSA (Ed25519) and legacy DSA. The framework provides a C API with bindings for C#/.NET, Python, Go, and Pascal, and includes the winsparkle-tool utility for key generation and update signing.

Tokens
10.8K
Snippets
23
Records
76
Agent score
81%

What's inside WinSparkle

  2. How update signing works in WinSparkle

    master

    WinSparkle requires updates to be cryptographically signed to prevent tampering. It uses the EdDSA algorithm with the Ed25519 curve. The public key must be embedded in your application, and the update enclosures in your appcast must contain the corresponding signature.

    While legacy DSA-based signatures are supported, they are deprecated and scheduled for removal. It is recommended to use EdDSA.

  3. Coordinate application shutdown with shutdown callbacks

    master

    WinSparkle provides a two-step mechanism to coordinate application shutdown before launching an installer.

    1. Query readiness: Use win_sparkle_set_can_shutdown_callback() to provide a function that returns TRUE if the application can safely shut down (e.g., no unsaved documents) or FALSE otherwise.
    2. Execute shutdown: If the readiness check returns TRUE, WinSparkle will call the callback registered via win_sparkle_set_shutdown_request_callback() to request an immediate, graceful termination.

    Important: These callbacks are called from a background thread, not the application's main thread. Ensure your implementations are thread-safe.

  4. Specify minimum OS version in Appcast

    master

    You can restrict updates to specific Windows versions using the <sparkle:minimumSystemVersion> extension. The value is a tuple of 1-3 numbers: major[.minor[.build]].

    Examples:

    • 10.0 (Windows 10)
    • 6.2 (Windows 8)
    • 10.0.22000 (Windows 11)

    Compatibility Note: For versions older than 0.8.3, the third component is treated as a service pack number. To support both old and new versions of WinSparkle, use the syntax major.minor-build (e.g., 10.0-22000), which newer versions parse as a build number and older versions parse as major.minor.

  5. Understand the WinSparkle update user experience

    master

    WinSparkle is designed to avoid disrupting a user's first impression. The update lifecycle follows these stages:

    1. First Launch: WinSparkle remains silent and performs no actions.
    2. Subsequent Launches: The user is presented with a dialog asking if they want to enable automatic update checks.
    3. Background Checks: If enabled, WinSparkle checks for updates silently in the background during app startup.
    4. Update Notification: If a newer version is found in the appcast, a window appears displaying update information and optional HTML release notes.
    5. User Actions:
      • Remind me later: Postpones the notification until the next time the application is launched.
      • Install update: Downloads the new version's installer and launches it immediately.

  6. Create an Appcast feed for WinSparkle

    master

    WinSparkle uses an RSS 2.0 feed (an appcast) to discover available updates. The feed must be served over HTTPS to prevent intermediaries from tampering with updates.

    An appcast item requires a <sparkle:version> and an <enclosure> containing the download URL. While the length attribute in the <enclosure> is optional, it is recommended to set it to 0 if the file size is unknown.

    <?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
    <channel>
        <title>WinSparkle Test Appcast</title>
        <description>Most recent updates to WinSparkle Test</description>
        <language>en</language>
        <item>
            <title>Version 1.5.5880</title>
            <sparkle:version>1.5.5880</sparkle:version>
            <sparkle:releaseNotesLink>
                https://your_domain/your_path/release_notes.html
            </sparkle:releaseNotesLink>
            <pubDate>Fri, 06 Feb 2016 22:49:00 +0100</pubDate>
            <enclosure url="https://your_domain/your_path/setup.exe"
                       length="0"
                       type="application/octet-stream" />
        </item>
    </channel>
</rss>

  8. Sign your update with EdDSA

    master

    Once your update file (e.g., Updater.exe) is ready, sign it using winsparkle-tool and include the resulting signature in your appcast file.

    1. Sign the file:
    $ winsparkle-tool sign -f private.key Updater.exe
    1. Update Appcast: Take the standard output from the sign command and add it as the sparkle:edSignature attribute to the enclosure node in your appcast XML.

    Example Output:

    $ winsparkle-tool sign --verbose --private-key-file private.key Updater.exe
sparkle:edSignature="JhQ69mgRxjNxS35zmMu6bMd9UlkCC/tkCiSR4SXQOfBwwH1FkqYSgNyT5dbWjnw5F1c/6/LqbCGw+WckvJiOBw==" length="1736832"

  9. Trigger manual update checks

    master

    If automatic updates are disabled, or if you want to provide a "Check for updates..." menu item, use one of the following manual check functions. All these functions return immediately as the check runs in a background thread.

    • With Progress UI: win_sparkle_check_update_with_ui() shows a progress window during the check. If an update is found, it shows the standard update prompt. This function ignores the user's "Skip this version" preference.
    • With Progress UI and Auto-Install: win_sparkle_check_update_with_ui_and_install() shows a progress window and, if an update is found, skips the prompt and installs it immediately. This is ideal for applications where users should always be on the latest version.
    • Without Progress UI: win_sparkle_check_update_without_ui() performs the check silently (no progress window). However, if an update is found, the standard "update available" window will still be shown. This function respects the user's "Skip this version" preference.

  11. Use legacy DSA signatures

    master
    If you are currently using DSA signatures, you can continue to use them by utilizing the bin/legacy_*.bat scripts provided in the repository. However, you should plan to upgrade to EdDSA signatures as DSA support is deprecated and will be removed in a future version.

  12. Prepare EdDSA signing with winsparkle-tool

    master

    The winsparkle-tool is a companion utility used to generate keys and sign updates. It is included in the bin directory of the binary package, in the tools directory of the NuGet package, or can be compiled from source.

    1. Generate EdDSA keys

    Run the following command once to create your key pair. Back up your private key (eddsa_priv.pem) securely; if lost, you cannot issue new updates.

    $ winsparkle-tool generate-key --file private.key

    2. Add the public key to your project

    You must provide the public key to your application using one of two methods:

    **Method A: Windows Resource **Add the public key to your resource file using this format: EdDSAPub EDDSA {"YOUR_PUBLIC_KEY"}

    Method B: API Call **Call the following function in your code: win_sparkle_set_eddsa_public_key("YOUR_PUBLIC_KEY");

    $ winsparkle-tool generate-key --file private.key
Private key saved to private.key
Public key: pXAx0wfi8kGbeQln11+V4R3tCepSuLXeo7LkOeudc/U=

# Example Resource entry:
EdDSAPub EDDSA {"pXAx0wfi8kGbeQln11+V4R3tCepSuLXeo7LkOeudc/U="}

# Example API call:
win_sparkle_set_eddsa_public_key("pXAx0wfi8kGbeQln11+V4R3tCepSuLXeo7LkOeudc/U=");