Mirrors
/
open-keychain
mirror of https://github.com/open-keychain/open-keychain.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated OpenPGP API (markdown)

Dominik Schürmann 2014-04-06 04:06:26 -07:00
parent cb2b688909
commit 82c4079ff7
1 changed files with 7 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
OpenPGP-API.md

@ -4,7 +4,7 @@ To get an idea how this API works from a user's perspective install [OpenKeychai
## 1. Add the API library to your project
Copy the directory [OpenPGP-Keychain-API/libraries/openpgp-api-library](https://github.com/openpgp-keychain/openpgp-keychain/tree/master/OpenPGP-Keychain-API/libraries/openpgp-api-library) from this git repository into a subfolder of your projects directory.
Copy the directory [OpenKeychain-API/libraries/openpgp-api-library](https://github.com/open-keychain/open-keychain/tree/master/OpenKeychain-API/libraries/openpgp-api-library) from this git repository into a subfolder of your projects directory.
### Gradle/Android Studio
1. Reference the library by including the library project in your ``settings.gradle`` file (adjust the path to your folder layout):
@ -23,13 +23,13 @@ Please read ["Referencing a library project"](http://developer.android.com/tools
## 2. Understand the basic design of the OpenPGP API
The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/openpgp-keychain/openpgp-keychain/wiki/OpenPGP-API#internal-design-decisions).
The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions).
We will go through the basic steps to understand how this API works, following this (greatly simplified) sequence diagram:
![](https://github.com/openpgp-keychain/openpgp-keychain/raw/master/Resources/docs/openpgp_api_1.jpg)
![](https://github.com/open-keychain/open-keychain/raw/master/Resources/docs/openpgp_api_1.jpg)
In this diagram the client app is depicted on the left side, the OpenPGP provider (in this case OpenKeychain) is depicted on the right.
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/IOpenPgpService.aidl).
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/IOpenPgpService.aidl).
It contains only one exposed method which can be invoked remotely:
```java
interface IOpenPgpService {
@ -143,17 +143,17 @@ Intent result = api.executeApi(data, is, os);
## 3. Tipps
* ``api.executeApi(data, is, os);`` is a blocking call. If you want a convenient asynchronous call, use ``api.executeApiAsync(data, is, os, new MyCallback([... ]));``, where ``MyCallback`` is an private class implementing ``OpenPgpApi.IOpenPgpCallback``.
See [``OpenPgpProviderActivity.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java) for an example.
See [``OpenPgpProviderActivity.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java) for an example.
* Using
```java
mServiceConnection = new OpenPgpServiceConnection(this, "org.sufficientlysecure.keychain");
```
connects to OpenKeychain directly.
If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpListPreference.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/util/OpenPgpListPreference.java) like done in the example app.
If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpListPreference.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/util/OpenPgpListPreference.java) like done in the example app.
## 4. Complete example
A complete example can be found in the demo application's [``OpenPgpProviderActivity.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java).
A complete example can be found in the demo application's [``OpenPgpProviderActivity.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java).
## Internal Design Decisions
* 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.