From 52cff5b3cb42c7ab35594918c439bfee7832468f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Sch=C3=BCrmann?= Date: Thu, 7 Aug 2014 00:40:48 -0700 Subject: [PATCH] Created API (markdown) --- API.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..7fe80c7 --- /dev/null +++ b/API.md @@ -0,0 +1,10 @@ +### OpenPGP Remote API +Please also read the [Tutorial](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API/_edit) and try out the demo app before reading this. + +* The API does not use the Android permission system due to [its problems](http://commonsware.com/blog/2014/02/12/vulnerabilities-custom-permissions.html) ([details](https://github.com/commonsguy/cwac-security/blob/master/PERMS.md)). Instead OpenKeychain stores its own table of granted applications. +* The API should be as easy as possible and extendable. Because of this, the AIDL file is kept small and all operations are defined by Intents which can be passed through this interface to the remote service. +* The API should be able to work on ``byte[]``, ``Strings``, and files. To implement this, we use ``ParcelFileDescriptors``, which are passed via the AIDL method. ``ParcelFileDescriptors`` are initialized over ``InputStreams``, which can be based on all content types. (Note: ``ParcelFileDescriptors`` can not be part of the Intent, because of constraints in Android OS. They must be part of the AIDL method) +* The client app should be able to define where output is written, thus the calling client defines a ``ParcelFileDescriptor`` used to write the output into. +* Clients should never be able to actually access the private key object +* Clients should only work with private keys explicitly allowed by the user. This is done by API accounts on the side of OpenKeychain. Clients request a specific account based on a unique name and the user can then select the private key for this account. Clients can only decrypt with private keys set for these accounts. +* All user interaction should be happening on the right [task stack](http://developer.android.com/guide/components/tasks-and-back-stack.html) and clients should be able to specify by themselves when user interaction should be shown (consider a background encryption task, where a passphrase input is required. The user interaction for passphrase input should be delayed until the user unlocks his/her phone again). This requirement is implemented by returning ``PendingIntents`` to the client application, which are then started by the client at a chosen time. ``PendingIntents`` are also attached to the client app's task stack. Actitivites are never started from OpenKeychain's background service. \ No newline at end of file