linkLicense-Gated Access

All releases are gated with license validation; meaning, when providing download URLs to your users, you must provide a valid license key within the request or the request will be rejected. We essentially act as a license-gated static file storage system, backed by AWS S3.

For example, you may choose to email the user a download link after they purchase your product. You should include their new license key as a query parameter within the URL, or generate a temporary download link.

Access to releases and updates will remain accessible for as long as a license is valid. If the license becomes invalid, e.g. it expires or is suspended, it will no longer be allowed to access releases.

linkNotes for Squirrel.Windows

When uploading releases for Squirrel.Windows, please ensure that the release files within your RELEASES file are relative paths, not URLs. Keygen Dist will automatically rewrite your release file paths to include the provided licensing information (passed via query parameters).

For example, given a RELEASES file like below,

0XFF… your-app-1.0.0-full.nupkg 0123
0XFF… your-app-2.0.0-delta.nupkg 0123
0XFF… your-app-2.0.0-full.nupkg 0123
0XFF… your-app-1.0.0-full.nupkg 0123
0XFF… your-app-2.0.0-delta.nupkg 0123
0XFF… your-app-2.0.0-full.nupkg 0123
content_copy

When requested like so,

GET https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/RELEASES?key=foobar
GET https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/RELEASES?key=foobar
content_copy

The RELEASES file's contents will automatically be rewritten to,

0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-1.0.0-full.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-delta.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-full.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-1.0.0-full.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-delta.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<account>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-full.nupkg?key=foobar 0123
content_copy

If you wish to opt out of the rewrite behavior, you may supply URLs instead of paths for your release files. For example,

0XFF… https://dist.example.com/download/win32/your-app-1.0.0-full.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-delta.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-full.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-1.0.0-full.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-delta.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-full.nupkg 0123
content_copy

linkNotes for electron-builder

Unlike Electron's native auto-updater, electron-builder does not utilize a normal Squirrel release server. Because of this, electron-builder's auto-updater, electron-updater, will not utilize the /update endpoint. Rather, you will utilize the /releases endpoint for all platforms. In this way, Keygen Dist will act as a license-gated static file store.

Your feedURL should look something like this:

https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}?key=${licenseKey}
https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}?key=${licenseKey}
content_copy

How electron-updater performs an update is like this:

1. For macOS, it will request latest-mac.yml from the release server. For Windows, it will request RELEASES. It does so by appending either /latest-mac.yml or /RELEASES to the feedURL path.
2. It will check the latest version in the returned file against the the current version of the app.
3. It will request the newer version if one is available.

Using the electron-builder code example, and assuming we're on the macos platform, electron-updater will automatically use the above feedURL as a "base URL" to request the following latest-mac.yml file, as explained above:

https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}/latest-mac.yml?key=${licenseKey}
https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}/latest-mac.yml?key=${licenseKey}
content_copy

That yml file will then be downloaded and read, and then used to request the latest app version, if there is one available. It will use similar logic to request the app version, by appending the version to the feedURL path.

linkOther Examples

If you'd like to see examples for another framework or in another language, please let us know.

linkChecksum Calculation

To calculate the first part you have to make a list of MD5 hashes of all the parts, convert it into binary format and take the MD5 hash of it. Afterwards you append a dash and add the number of parts you've split your file into.

For example, the following checksum was constructed from an MD5 hash of 4 separate parts' MD5 hash, then appended with a -4 to indicate the number of parts the file was split into.

c3b6303207d30de3dbb228b5ba94c31f-4
c3b6303207d30de3dbb228b5ba94c31f-4
content_copy

To construct the MD5 hash, you will read the file 8MB at a time (8 * 1024 * 1024 bytes), hashing each part that is read using MD5. Once all parts have been hashed, concatenate all of the hashes, and hash that value also using MD5. Append the hash count at the end, separated by a dash, and you should have a matching checksum value.