From 9d66aea843df22fa5c2cf11ecf2f263898900040 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Mon, 17 Nov 2014 13:49:46 +0100 Subject: [PATCH] Documentation and changelog entries updated --- CHANGELOG.md | 4 + docs/api/apps.rst | 170 +++++++++++++++++++++++++++++++++++++++++++ docs/api/general.rst | 4 +- docs/api/index.rst | 1 + 4 files changed, 177 insertions(+), 2 deletions(-) create mode 100644 docs/api/apps.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index daa806b9..a506f93b 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/docs/api/apps.rst b/docs/api/apps.rst new file mode 100644 index 00000000..46ee73c8 --- /dev/null +++ b/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 `. + + 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 ` 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 `_: + +.. 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----- + diff --git a/docs/api/general.rst b/docs/api/general.rst index e7c22919..9e6a67fc 100644 --- a/docs/api/general.rst +++ b/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 -custom API key via the "Change password" dialog. +configured one, a user specific one if "Access Control" is enabled or an ref:`App Session Key `. +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. diff --git a/docs/api/index.rst b/docs/api/index.rst index 3099b22d..8afb96c7 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -9,6 +9,7 @@ API Documentation general.rst version.rst + apps.rst fileops.rst connection.rst printer.rst