API documentation

OpenPGP-Keychain/AndroidManifest.xml

@@ -18,7 +18,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="org.sufficientlysecure.keychain"
     android:installLocation="auto"
-    android:versionCode="21100"
+    android:versionCode="21101"
     android:versionName="2.1.1" >
 
     <!--

OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpCallback.aidl

@@ -22,10 +22,22 @@ import org.openintents.openpgp.OpenPgpError;
 interface IOpenPgpCallback {
     
     /**
-     * CryptoSignatureResult is only returned if the Callback was used from decryptAndVerify
+     * onSuccess returns on successful OpenPGP operations.
      * 
+     * @param outputBytes
+     *            contains resulting output bytes (decrypted content/content without signature)
+     * @param signatureResult
+     *            signatureResult is only non-null if decryptAndVerify() was called and the content
+     *            was encrypted or signed-and-encrypted.
      */
     oneway void onSuccess(in byte[] outputBytes, in OpenPgpSignatureResult signatureResult);
 
+    /**
+     * onError returns on errors or when allowUserInteraction was set to false, but user interaction
+     * was required execute an OpenPGP operation.
+     * 
+     * @param error
+     *            See OpenPgpError class for more information.
+     */
     oneway void onError(in OpenPgpError error);
 }

OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpService.aidl

@@ -27,6 +27,8 @@ interface IOpenPgpService {
     /**
      * Encrypt
      * 
+     * After successful encryption, callback's onSuccess will contain the resulting output bytes.
+     * 
      * @param inputBytes
      *            Byte array you want to encrypt
      * @param encryptionUserIds
@@ -44,8 +46,10 @@ interface IOpenPgpService {
     /**
      * Sign
      * 
+     * After successful signing, callback's onSuccess will contain the resulting output bytes.
+     *
      * @param inputBytes
-     *            Byte array you want to encrypt
+     *            Byte array you want to sign
      * @param asciiArmor
      *            Encode for ASCII (Radix-64, 33 percent overhead compared to binary)
      * @param allowUserInteraction
@@ -59,8 +63,10 @@ interface IOpenPgpService {
     /**
      * Sign then encrypt
      * 
+     * After successful signing and encryption, callback's onSuccess will contain the resulting output bytes.
+     *
      * @param inputBytes
-     *            Byte array you want to encrypt
+     *            Byte array you want to sign and encrypt
      * @param encryptionUserIds
      *            User Ids (emails) of recipients
      * @param signatureUserId
@@ -76,8 +82,11 @@ interface IOpenPgpService {
             in boolean asciiArmor, in boolean allowUserInteraction, in IOpenPgpCallback callback);
     
     /**
-     * Decrypts and verifies given input bytes. If no signature is present this method
-     * will only decrypt.
+     * Decrypts and verifies given input bytes. This methods handles the encrypted-only, signed-and-encrypted,
+     * and also signed-only inputBytes.
+     * 
+     * After successful decryption, callback's onSuccess will contain the resulting output bytes.
+     * callback's onSuccess will return the signatureResult for signed-and-encrypted and signed-only inputs.
      * 
      * @param inputBytes
      *            Byte array you want to decrypt and verify

OpenPGP-Keychain/src/org/openintents/openpgp/OpenPgpSignatureResult.java

@@ -20,9 +20,13 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 public class OpenPgpSignatureResult implements Parcelable {
+    // generic error on signature verification
     public static final int SIGNATURE_ERROR = 0;
+    // successfully verified signature, with trusted public key
     public static final int SIGNATURE_SUCCESS_TRUSTED = 1;
+    // no public key was found for this signature verification
     public static final int SIGNATURE_UNKNOWN = 2;
+    // successfully verified signature, but with untrusted public key
     public static final int SIGNATURE_SUCCESS_UNTRUSTED = 3;
 
     int signatureStatus;

OpenPGP-Keychain/src/org/sufficientlysecure/keychain/service/remote/OpenPgpService.java

@@ -62,7 +62,7 @@ public class OpenPgpService extends RemoteService {
         if (passphrase == null) {
             if (!allowUserInteraction) {
                 throw new UserInteractionRequiredException(
-                        "Passphrase not found in cache! User interaction required!");
+                        "Passphrase not found in cache, please enter your passphrase!");
             }
 
             Log.d(Constants.TAG, "No passphrase! Activity required!");