From a70562daf21d3dde0a5d67b34f34f5339d5eef0f Mon Sep 17 00:00:00 2001 From: Zorg Date: Sat, 29 Aug 2015 03:06:22 -0400 Subject: [PATCH 1/3] Update Security Documentation This updates Sparkle's security documentation to reflect the current codebase. More weight is now given to https and DSA signatures, and more info is given on how Sparkle uses code signing. --- documentation/index.md | 36 ++++++++++++++++++++----------- documentation/publishing/index.md | 4 ++-- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/documentation/index.md b/documentation/index.md index 4f232e5..46e5295 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -40,18 +40,30 @@ If you are using [CocoaPods](https://cocoapods.org), then follow these [alternat ### 3. Segue for security concerns * Since Sparkle is downloading executable code to your users' systems, you must be very careful about security. -* To let Sparkle be sure an update came from you (instead of a malicious attacker), you must do one of two things: - * If you're updating a regular app (not preference pane or plugin), then sign your updates via Apple's Developer ID program or your own certificate. Sparkle will ensure the new version's author matches the old version's. This is the recommended solution, as you don't need to manage DSA keys this way. This feature doesn't work with .pkg-based updates or binary-delta updates: for those, you'll have to use the signatures described below. - * Note that embedding the Sparkle.framework into the bundle of a Developer ID application requires that you code-sign the framework with your Developer ID keys. Xcode should do this automatically if you let it "Code Sign on Copy" Sparkle's framework. - * You can diagnose code signing problems with [RB App Checker app](http://brockerhoff.net/RB/AppCheckerLite/) and by checking logs in the Console.app. - * If you can't code sign your app, you can include a [DSA signature](https://en.wikipedia.org/wiki/Digital_signature) of the SHA-1 hash of your published update file. - * First, make yourself a pair of DSA keys; Sparkle includes a tool to help: - * (from the Sparkle distribution root):
-./bin/generate_keys.sh - * You can use the keys this tool generates to sign your updates. - * Back up your private key (dsa_priv.pem) and keep it safe. You don't want anyone else getting it, and if you lose it, you won't be able to issue any new updates. - * Add your public key (dsa_pub.pem) to the Resources folder of your Xcode project. - * Add a SUPublicDSAKeyFile key to your Info.plist; set its value to your public key's filename—unless you renamed it, this will be dsa_pub.pem. +* To let Sparkle be sure an update after being downloaded is not corrupted and came from you (instead of a malicious attacker), we recommend: + * Serving the update over https + * Code-signing the application via Apple's Developer ID program or with your own certificate + * Specifying a [DSA Signature](https://en.wikipedia.org/wiki/Digital_signature) of the SHA-1 hash of the published update archive and including a public DSA key inside your update + +* While signing your archive using DSA Signatures strengthens your update and may open up to additional features, they are not required to be used if the update is: + * Served over https (serving over http without using DSA Signatures is now deprecated) + * Packaged as a regular app (i.e, not a preference pane, plug-in, package installer, or some other type) + * Distributed without providing binary delta patches for more efficient updates + +* If you are code-signing your application via Apple's Developer ID program or your own certificate, Sparkle will ensure the new version's author matches the old version's. Sparkle also performs basic (but not deep) validation for testing if the new application is archived/distributed correctly as you intended. + * Note that embedding the Sparkle.framework into the bundle of a Developer ID application requires that you code-sign the framework with your Developer ID keys. Xcode should do this automatically if you let it "Code Sign on Copy" Sparkle's framework. + * You can diagnose code signing problems with [RB App Checker app](http://brockerhoff.net/RB/AppCheckerLite/) and by checking logs in the Console.app. + +* If you are specifying a DSA Signature of your update's archive: + * First, make yourself a pair of DSA keys; Sparkle includes a tool to help: + * (from the Sparkle distribution root):
+ ./bin/generate_keys.sh + * You can use the keys this tool generates to sign your updates. + * Back up your private key (dsa_priv.pem) and keep it safe. You don't want anyone else getting it, and if you lose it, you may not be able to issue any new updates. + * Add your public key (dsa_pub.pem) to the Resources folder of your Xcode project. + * Add a SUPublicDSAKeyFile key to your Info.plist; set its value to your public key's filename—unless you renamed it, this will be dsa_pub.pem. + +* If you decide to both code-sign your application and include a public DSA key for signing your update archive, Sparkle allows issuing a new update that changes either your code signing certificate or your DSA keys. Note however this is a last resort and should *only* be done if you lose access to one of them. ### 4. Publish your appcast diff --git a/documentation/publishing/index.md b/documentation/publishing/index.md index 91e3c65..9c80e56 100644 --- a/documentation/publishing/index.md +++ b/documentation/publishing/index.md @@ -15,9 +15,9 @@ Alternatively, create an Installer .pkg with the same name as your app and put t ### Secure your update -In order to prevent man-in-the-middle attacks against your users, you must cryptographically sign your updates. You can do that using Apple's code signing tools, with a Developer ID. +In order to prevent corruption and man-in-the-middle attacks against your users, you must serve your updates over https or cryptographically sign your updates (or choose to do both!). -If you can't code sign your app, you can make a DSA signature of the archive instead. Sparkle includes a script to help you sign your update. From the Sparkle distribution: +To cryptographically sign your updates, Sparkle includes a script to help you make a DSA signature of the archive. From the Sparkle distribution: ./bin/sign_update.sh path_to_your_update.zip path_to_your_dsa_priv.pem From 4cc0c88be1f4d50711a64ada55e8d5c9110ad8ed Mon Sep 17 00:00:00 2001 From: Zorg Date: Sat, 29 Aug 2015 10:04:32 -0400 Subject: [PATCH 2/3] Grammar improvements --- documentation/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/index.md b/documentation/index.md index 46e5295..b29b716 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -40,13 +40,13 @@ If you are using [CocoaPods](https://cocoapods.org), then follow these [alternat ### 3. Segue for security concerns * Since Sparkle is downloading executable code to your users' systems, you must be very careful about security. -* To let Sparkle be sure an update after being downloaded is not corrupted and came from you (instead of a malicious attacker), we recommend: +* To let Sparkle know that a downloaded update is not corrupted and came from you (instead of a malicious attacker), we recommend: * Serving the update over https * Code-signing the application via Apple's Developer ID program or with your own certificate - * Specifying a [DSA Signature](https://en.wikipedia.org/wiki/Digital_signature) of the SHA-1 hash of the published update archive and including a public DSA key inside your update + * Specifying a [DSA signature](https://en.wikipedia.org/wiki/Digital_signature) of the SHA-1 hash of the published update archive and including a public DSA key inside your update -* While signing your archive using DSA Signatures strengthens your update and may open up to additional features, they are not required to be used if the update is: - * Served over https (serving over http without using DSA Signatures is now deprecated) +* While signing your archive using DSA signatures strengthens your update and may open up to additional features, they are not required to be used if the update is: + * Served over https (serving over http without using DSA signatures is now deprecated) * Packaged as a regular app (i.e, not a preference pane, plug-in, package installer, or some other type) * Distributed without providing binary delta patches for more efficient updates @@ -54,14 +54,14 @@ If you are using [CocoaPods](https://cocoapods.org), then follow these [alternat * Note that embedding the Sparkle.framework into the bundle of a Developer ID application requires that you code-sign the framework with your Developer ID keys. Xcode should do this automatically if you let it "Code Sign on Copy" Sparkle's framework. * You can diagnose code signing problems with [RB App Checker app](http://brockerhoff.net/RB/AppCheckerLite/) and by checking logs in the Console.app. -* If you are specifying a DSA Signature of your update's archive: +* If you are specifying a DSA signature of your update's archive: * First, make yourself a pair of DSA keys; Sparkle includes a tool to help: * (from the Sparkle distribution root):
./bin/generate_keys.sh * You can use the keys this tool generates to sign your updates. * Back up your private key (dsa_priv.pem) and keep it safe. You don't want anyone else getting it, and if you lose it, you may not be able to issue any new updates. * Add your public key (dsa_pub.pem) to the Resources folder of your Xcode project. - * Add a SUPublicDSAKeyFile key to your Info.plist; set its value to your public key's filename—unless you renamed it, this will be dsa_pub.pem. + * Add an SUPublicDSAKeyFile key to your Info.plist; set its value to your public key's filename—unless you renamed it, this will be dsa_pub.pem. * If you decide to both code-sign your application and include a public DSA key for signing your update archive, Sparkle allows issuing a new update that changes either your code signing certificate or your DSA keys. Note however this is a last resort and should *only* be done if you lose access to one of them. From bdf373601615e2eea73183dad10ef9455eb544fd Mon Sep 17 00:00:00 2001 From: Zorg Date: Sat, 29 Aug 2015 10:05:24 -0400 Subject: [PATCH 3/3] Remove .sh from tool names --- documentation/index.md | 2 +- documentation/publishing/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/index.md b/documentation/index.md index b29b716..c773a4b 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -57,7 +57,7 @@ If you are using [CocoaPods](https://cocoapods.org), then follow these [alternat * If you are specifying a DSA signature of your update's archive: * First, make yourself a pair of DSA keys; Sparkle includes a tool to help: * (from the Sparkle distribution root):
- ./bin/generate_keys.sh + ./bin/generate_keys * You can use the keys this tool generates to sign your updates. * Back up your private key (dsa_priv.pem) and keep it safe. You don't want anyone else getting it, and if you lose it, you may not be able to issue any new updates. * Add your public key (dsa_pub.pem) to the Resources folder of your Xcode project. diff --git a/documentation/publishing/index.md b/documentation/publishing/index.md index 9c80e56..524ef71 100644 --- a/documentation/publishing/index.md +++ b/documentation/publishing/index.md @@ -19,7 +19,7 @@ In order to prevent corruption and man-in-the-middle attacks against your users, To cryptographically sign your updates, Sparkle includes a script to help you make a DSA signature of the archive. From the Sparkle distribution: - ./bin/sign_update.sh path_to_your_update.zip path_to_your_dsa_priv.pem + ./bin/sign_update path_to_your_update.zip path_to_your_dsa_priv.pem The output string is your update's DSA signature; you'll add this as an attribute to your enclosure in the next step. You can remove any newlines in this string.