diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 87 |
1 files changed, 25 insertions, 62 deletions
@@ -1,9 +1,11 @@ # OpenKeychain (for Android) -OpenKeychain is an OpenPGP implementation for Android. -The development began as a fork of Android Privacy Guard (APG). +OpenKeychain is an OpenPGP implementation for Android. +For a more detailed description and installation instructions go to http://www.openkeychain.org . -see http://sufficientlysecure.org/keychain +### Travis CI Build Status + +[](https://travis-ci.org/openpgp-keychain/openpgp-keychain) ## How to help the project? @@ -30,9 +32,9 @@ Development mailinglist at http://groups.google.com/d/forum/openpgp-keychain-dev 1. Have Android SDK "tools", "platform-tools", and "build-tools" directories in your PATH (http://developer.android.com/sdk/index.html) 2. Open the Android SDK Manager (shell command: ``android``). -Expand the Tools directory and select "Android SDK Build-tools" newest version. +Expand the Tools directory and select "Android SDK Build-tools (Version 19.0.3)". Expand the Extras directory and install "Android Support Repository" -Select everything for the newest SDK +Select everything for the newest SDK (API-Level 19) 3. Export ANDROID_HOME pointing to your Android SDK 4. Execute ``./gradlew build`` 5. You can install the app with ``adb install -r OpenPGP-Keychain/build/apk/OpenPGP-Keychain-debug-unaligned.apk`` @@ -53,65 +55,17 @@ I am using the newest [Android Studio](http://developer.android.com/sdk/installi * Select the "OpenPGP-Keychain-API" folder if you want to develop on the API example 3. Import project from external model -> choose Gradle -## Keychain API - -### Intent API -All Intents require user interaction, e.g. to finally encrypt the user needs to press the "Encrypt" button. -To do automatic encryption/decryption/sign/verify use the OpenPGP Remote API. - -#### Android Intent actions: - -* ``android.intent.action.VIEW`` connected to .gpg and .asc files: Import Key and Decrypt -* ``android.intent.action.SEND`` connected to all mime types (text/plain and every binary data like files and images): Encrypt and Decrypt - -#### OpenKeychain Intent actions: - -* ``org.sufficientlysecure.keychain.action.ENCRYPT`` - * To encrypt or sign text, use extra ``text`` (type: ``String``) - * or set data ``Uri`` (``intent.setData()``) pointing to a file - * Enable ASCII Armor for file encryption (encoding to Radix-64, 33% overhead) by adding the extra ``ascii_armor`` with value ``true`` -* ``org.sufficientlysecure.keychain.action.DECRYPT`` - * To decrypt or verify text, use extra ``text`` (type: ``String``) - * or set data ``Uri`` (``intent.setData()``) pointing to a file -* ``org.sufficientlysecure.keychain.action.IMPORT_KEY`` - * Extras: ``key_bytes`` (type: ``byte[]``) - * or set data ``Uri`` (``intent.setData()``) pointing to a file -* ``org.sufficientlysecure.keychain.action.IMPORT_KEY_FROM_KEYSERVER`` - * Extras: ``query`` (type: ``String``) - * or ``fingerprint`` (type: ``String``) -* ``org.sufficientlysecure.keychain.action.IMPORT_KEY_FROM_QR_CODE`` - * without extras, starts Barcode Scanner to get QR Code - -#### OpenKeychain special registered Intents: -* ``android.intent.action.VIEW`` with URIs following the ``openpgp4fpr`` schema. For example: ``openpgp4fpr:73EE2314F65FA92EC2390D3A718C070100012282``. This is used in QR Codes, but could also be embedded into your website. (compatible with Monkeysphere's and Guardian Project's QR Codes) -* NFC (``android.nfc.action.NDEF_DISCOVERED``) on mime type ``application/pgp-keys`` (as specified in http://tools.ietf.org/html/rfc3156, section 7) - -### OpenPGP Remote API -To do fast encryption/decryption/sign/verify operations without user interaction bind to the OpenPGP remote service. - -#### Try out the API -Keychain: https://play.google.com/store/apps/details?id=org.sufficientlysecure.keychain -API Demo: https://play.google.com/store/apps/details?id=org.sufficientlysecure.keychain.demo - -#### Design -All apps wanting to use this generic API -just need to include the AIDL files and connect to the service. Other -OpenPGP apps can implement a service based on this AIDL definition. - -The API is designed to be as easy as possible to use by apps like K-9 Mail. -The service definition defines sign, encrypt, signAndEncrypt, decryptAndVerify, and getKeyIds. - -As can be seen in the API Demo, the apps themselves never need to handle key ids directly. -You can use user ids (emails) to define recipients. -If more than one public key exists for an email, OpenKeychain will handle the problem by showing a selection screen. Additionally, it is also possible to use key ids. +## OpenKeychain's API -Also app devs never need to fiddle with private keys. -On first operation, OpenKeychain shows an activity to allow or disallow access, while also allowing to choose the private key used for this app. -Please try the Demo app out to see how it works. +OpenKeychain provides two APIs, namely the Intent API and the Remote OpenPGP API. +The Intent API can be used without permissions to start OpenKeychain's activities for cryptographic operations, import of keys, etc. +However, it always requires user input, so that no malicious application can use this API without user intervention. +The Remote OpenPGP API is more sophisticated and allows to to operations without user interaction in the background. +When utilizing this API, OpenKeychain asks the user on first use to grant access for the calling client application. -#### Integration -Copy the api library from "libraries/keychain-api-library" to your project and add it as an dependency to your gradle build. -Inspect the ode found in "OpenPGP-Keychain-API" to understand how to use the API. +More technical information and examples about these APIs can be found in the project's wiki: +* [Intent API](https://github.com/openpgp-keychain/openpgp-keychain/wiki/Intent-API) +* [Remote OpenPGP API](https://github.com/openpgp-keychain/openpgp-keychain/wiki/OpenPGP-API) ## Libraries @@ -162,6 +116,15 @@ When changing build files or dependencies, respect the following requirements: * No dependencies from Maven (also a soft requirement for inclusion in [F-Droid](https://f-droid.org)) * Always use a fixed Android Gradle plugin version not a dynamic one, e.g. ``0.7.3`` instead of ``0.7.+`` (allows offline builds without lookups for new versions, also some minor Android plugin versions had serious issues, i.e. [0.7.2 and 0.8.1](http://tools.android.com/tech-docs/new-build-system)) * Commit the corresponding [Gradle wrapper](http://www.gradle.org/docs/current/userguide/gradle_wrapper.html) to the repository (allows easy building for new contributors without the need to install the required Gradle version using a package manager) +* In order to update the build system to a newer gradle version you need to: + * Update every build.gradle file with the new gradle version and/or gradle plugin version + * build.gradle + * OpenPGP-Keychain/build.gradle + * OpenPGP-Keychain-API/build.gradle + * OpenPGP-Keychain-API/example-app/build.gradle + * OpenPGP-Keychain-API/libraries/keychain-api-library/build.gradle + * run ./gradlew wrapper twice to update gradle and download the new jar file + * commit the new jar and property files ### Translations |