Merge pull request #16 from zorgiepoo/security-docs

Update Security Documentation

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):<br />
-<code>./bin/generate_keys.sh</code>
-    * You can use the keys this tool generates to sign your updates.
-    * Back up your private key (dsa_priv.pem) and <strong>keep it safe.</strong> 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 <code>SUPublicDSAKeyFile</code> 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 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
+
+* 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):<br />
+  <code>./bin/generate_keys</code>
+  * You can use the keys this tool generates to sign your updates.
+  * Back up your private key (dsa_priv.pem) and <strong>keep it safe.</strong> 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 an <code>SUPublicDSAKeyFile</code> 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
 

documentation/publishing/index.md

@@ -15,11 +15,11 @@ 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
+    ./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.