Documentation and changelog entries updated

CHANGELOG.md

@@ -18,6 +18,7 @@
   support is enabled -- STL) files to automatically add.
 * OctoPrint now has a [plugin system](http://docs.octoprint.org/en/devel/plugins/index.html) which allows extending its 
   core functionality.
+* New type of API key: [App Session Keys](http://docs.octoprint.org/en/devel/api/apps.html) for trusted applications
 
 ### Improvements
 
@@ -48,6 +49,8 @@
 * "Slicing Done" and "Streaming Done" notifications now have a green background ([#558](https://github.com/foosel/OctoPrint/issues/558))
 * Files that are currently in use, be it for slicing, printing or whatever, are now tracked and can not be deleted as
   long as they are in use
+* Settings in UI get refreshed when opening settings dialog
+* New event "SettingsUpdated"
 
 ### Bug Fixes
 
@@ -62,6 +65,7 @@
     queue
 * Various fixes without tickets:
   * GCODE viewer now doesn't stumble over completely extrusionless GCODE files
+  * Do not deliver the API key on settings API unless user has admin rights
 
 ## 1.1.2 (Unreleased)
 

docs/api/apps.rst

@@ -0,0 +1,170 @@
+.. _sec-api-apps:
+
+****
+Apps
+****
+
+.. contents::
+
+.. _sec-api-apps-sessionkey:
+
+Session Keys
+============
+
+OctoPrint offers a special API key type for apps to use, the so called App Session Key. These keys have a time based
+validity and are generated by OctoPrint for requesting apps.
+
+Obtaining those keys is based on a handshake procedure backed by cryptographic signatures using RSA. OctoPrint needs to
+be aware of apps and their associated public keys (this can be achieved either via entries in ``config.yaml`` or by
+installing app specific plugins which implement the ``AppPlugin`` type).
+
+Apps can be registered within OctoPrint via ``config.yaml`` by adding them to the ``api`` > ``apps`` section, using the
+application's id concatenated with its version as key, with the public key provided as item ``pubkey`` (stripped of the
+``BEGIN RSA PUBLIC KEY`` and ``END RSA PUBLIC KEY`` separators and also newlines) and optionally also whether the app is
+enabled or not (defaults to enabled, so can be left out if it's not to be set to disabled explicitly).
+
+Example:
+
+.. sourcecode:: yaml
+
+   api:
+     apps:
+       "com.example.my_octoprint_app:0.9":
+         pubkey: MEgCQQDYkr5Fv/YXK5ZL1uwRN4A61IagZaYLGqJ5JJGFo8wDrmpAMRqE9kK4+5hIDblC5DzfEr5oP7OA3tRO48Rf5yInAgMBAAE=
+         enabled: false
+       "com.example.my_octoprint_app:1.0":
+         pubkey: MEgCQQCIWfi7Nc8bcnfZJJtA6a4RyMC+sKBlMOb25OVNNB4L2v0TiGO72jVKR4osvb4oztlbRW5GkdiY0T2LJcfDYvkJAgMBAAE=
+
+In the example, the app ``com.example.my_octoprint_app`` in version 0.9 has been disabled (e.g. due to the key having
+leaked) whereas version 1.0 is fully registered with OctoPrint and may verify app session keys.
+
+
+.. _sec-api-apps-sessionkey-workflow:
+
+Workflow
+--------
+
+Apps perform the handshake by first requesting a temporary key with very limited validity,
+then sending a message back to OctoPrint containing their id, version, the temporary key and a signature created with their
+private key over these three pieces of data. OctoPrint then tries to verify the signature and if successful unlocks the
+key to be used as a fully recognized API key.
+
+For performing the handshake a special API exists within OctoPrint for which no API key is needed which is described below.
+
+.. _sec-api-apps-sessionkey-get:
+
+Obtaining a temporary session key
+---------------------------------
+
+.. http:get:: /apps/auth
+
+   Retrieve a temporary session key with a minimum validity. It can only be used as a proper API key after having been
+   :ref:`verified <sec-api-apps-sessionkey-verify>`.
+
+   Returns the temporary session key and the timestamp until it's valid.
+
+   **Example**:
+
+   .. sourcecode:: http
+
+      GET /apps/auth HTTP/1.1
+      Host: example.com
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "unverifiedKey": "F43A844750F74AD080FE9F438D47B33C",
+        "validUntil": 1416220357.011
+      }
+
+   :statuscode 200: No error
+
+.. _sec-api-apps-sessionkey-verify:
+
+Verifying a temporary session key
+---------------------------------
+
+.. http:post:: /apps/auth
+
+   Verify a formerly :ref:`retrieved <sec-api-apps-sessionkey-get>` temporary session key by providing credentials and a
+   cryptographic signature over these credentials and the temporary key.
+
+   Returns the now verified session key and the new validity.
+
+   **Example**:
+
+   .. sourcecode:: http
+
+      POST /apps/auth HTTP/1.1
+      Host: example.com
+      Content-Type: application/json
+
+      {
+        "appid": "com.example.my_octoprint_app",
+        "appversion": "1.0",
+        "key": "F43A844750F74AD080FE9F438D47B33C",
+        "_sig": "LGVCiolQWDc4AVn1DOcWljY0cFQxWF4pldVveUjjmL9JhiL0LnCKBbGwZ/CwKBWswFAxPaxQ0kDusVdOmCUa/w=="
+      }
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "key": "F43A844750F74AD080FE9F438D47B33C",
+        "validUntil": 1416227497.011
+      }
+
+.. _sec-api-apps-sessionkey-signature:
+
+Creating the signature
+----------------------
+
+The signature is created by concatenating the ``appid``, ``appversion`` and ``key`` fields, separated by a ``:`` (colon),
+signing the result with the app's private key using SHA-1 and then BASE64-encoding the result, stripping newlines.
+
+Example for signature generation using Python and the `Python RSA library <https://pypi.python.org/pypi/rsa>`_:
+
+.. sourcecode:: python
+
+   import base64
+   import rsa
+
+   appid = "com.example.my_octoprint_app"
+   version = "1.0"
+   unverified_key = "F43A844750F74AD080FE9F438D47B33C"
+   message_to_sign = appid + ":" + version + ":" + unverified_key
+   // => "com.example.my_octoprint_app:1.0:F43A844750F74AD080FE9F438D47B33C"
+
+   private_key = rsa.PrivateKey.load_pkcs1("...")
+   signature = base64.encodestring(rsa.sign(message_to_sign, private_key, "SHA-1")).replace("\n", "")
+   // => "LGVCiolQWDc4AVn1DOcWljY0cFQxWF4pldVveUjjmL9JhiL0LnCKBbGwZ/CwKBWswFAxPaxQ0kDusVdOmCUa/w=="
+
+
+.. _sec-api-apps-sessionkey-testing:
+
+Testing your implementation
+---------------------------
+
+If you want to use app session keys, here is the key pair with which the above examples were created, in order for you
+to verify your signature implementation::
+
+   -----BEGIN RSA PRIVATE KEY-----
+   MIIBPQIBAAJBAIhZ+Ls1zxtyd9kkm0DprhHIwL6woGUw5vbk5U00Hgva/ROIY7va
+   NUpHiiy9vijO2VtFbkaR2JjRPYslx8Ni+QkCAwEAAQJARK4lFo+FEcs3yR2iQjEy
+   p+yaAbNQJ4hZXlVvltLAYICzOM3kyKx53/eKU59NjskLz9q6QxfleymYPWAgl4NW
+   fQIjAJVH8MjwNcaAquTM9z2OiFi3OC8WgaKOi5W/T+r2+B70wG8CHwDp08dqOZ/u
+   xcBiy4Wzpcme9bckqoVuS3gWMm+YqgcCIwCMFU07kkY0NyumtzxPdIA4F/7OGSWf
+   IHqWFEfvasAddHlbAh8A5UgkB3Zf7Bt+7aFSBnlvve6FWm/XDPL12xYztYgrAiIa
+   W3miN6FjIm+8TDowrk+nyYXG2GZefeY7QXOjYr6tlDn0
+   -----END RSA PRIVATE KEY-----
+
+   -----BEGIN RSA PUBLIC KEY-----
+   MEgCQQCIWfi7Nc8bcnfZJJtA6a4RyMC+sKBlMOb25OVNNB4L2v0TiGO72jVKR4os
+   vb4oztlbRW5GkdiY0T2LJcfDYvkJAgMBAAE=
+   -----END RSA PUBLIC KEY-----
+

docs/api/general.rst

@@ -12,8 +12,8 @@ Authorization
 =============
 
 OctoPrint's API expects an API key to be supplied with each request. This API key can be either the globally
-configured one or a user specific one if "Access Control" is enabled. Users are able to generate and revoke their
+configured one, a user specific one if "Access Control" is enabled or an ref:`App Session Key <sec-api-apps-sessionkey>`.
-custom API key via the "Change password" dialog.
+Users are able to generate and revoke their custom API key via the "Change password" dialog.
 
 The API key must be supplied in the custom HTTP header ``X-Api-Key``, e.g.
 

docs/api/index.rst

@@ -9,6 +9,7 @@ API Documentation
 
    general.rst
    version.rst
+   apps.rst
    fileops.rst
    connection.rst
    printer.rst