wrapped-key-ring: add documentation

DESIGN.mkd

@@ -1,6 +1,7 @@
 # Design Notes on Open-Keychain
 
-This document contains notes on the software design of open keychain. 
+This document contains notes on the software design of open keychain. Points
+with a * are yet to be implemented.
 
 
 ## Database design

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/KeyRing.java

@@ -2,6 +2,17 @@ package org.sufficientlysecure.keychain.pgp;
 
 import org.sufficientlysecure.keychain.pgp.exception.PgpGeneralException;
 
+/** An abstract KeyRing.
+ *
+ * This is an abstract class for all KeyRing constructs. It serves as a common
+ * denominator of available information, two implementations wrapping the same
+ * keyring should in all cases agree on the output of all methods described
+ * here.
+ *
+ * @see org.sufficientlysecure.keychain.pgp.WrappedKeyRing
+ * @see org.sufficientlysecure.keychain.provider.CachedPublicKeyRing
+ *
+ */
 public abstract class KeyRing {
 
     abstract public long getMasterKeyId() throws PgpGeneralException;

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/UncachedKeyRing.java

@@ -23,6 +23,23 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Vector;
 
+/** Wrapper around PGPKeyRing class, to be constructed from bytes.
+ *
+ * This class and its relatives UncachedPublicKey and UncachedSecretKey are
+ * used to move around pgp key rings in non crypto related (UI, mostly) code.
+ * It should be used for simple inspection only until it saved in the database,
+ * all actual crypto operations should work with WrappedKeyRings exclusively.
+ *
+ * This class is also special in that it can hold either the PGPPublicKeyRing
+ * or PGPSecretKeyRing derivate of the PGPKeyRing class, since these are
+ * treated equally for most purposes in UI code. It is up to the programmer to
+ * take care of the differences.
+ *
+ * @see org.sufficientlysecure.keychain.pgp.WrappedKeyRing
+ * @see org.sufficientlysecure.keychain.pgp.UncachedPublicKey
+ * @see org.sufficientlysecure.keychain.pgp.UncachedSecretKey
+ *
+ */
 public class UncachedKeyRing {
 
     final PGPKeyRing mRing;
@@ -62,6 +79,7 @@ public class UncachedKeyRing {
         };
     }
 
+    /** Returns the dynamic (though final) property if this is a secret keyring or not. */
     public boolean isSecret() {
         return mIsSecret;
     }

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/WrappedKeyRing.java

@@ -8,6 +8,15 @@ import org.sufficientlysecure.keychain.util.IterableIterator;
 import java.io.IOException;
 import java.io.OutputStream;
 
+/** A generic wrapped PGPKeyRing object.
+ *
+ * This class provides implementations for all basic getters which both
+ * PublicKeyRing and SecretKeyRing have in common. To make the wrapped keyring
+ * class typesafe in implementing subclasses, the field is stored in the
+ * implementing class, providing properly typed access through the getRing
+ * getter method.
+ *
+ */
 public abstract class WrappedKeyRing extends KeyRing {
 
     private final boolean mHasAnySecret;

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/WrappedPublicKey.java

@@ -1,16 +1,19 @@
 package org.sufficientlysecure.keychain.pgp;
 
-import org.spongycastle.openpgp.PGPException;
-import org.spongycastle.openpgp.PGPOnePassSignature;
 import org.spongycastle.openpgp.PGPPublicKey;
-import org.spongycastle.openpgp.PGPSignature;
-import org.spongycastle.openpgp.operator.jcajce.JcaPGPContentVerifierBuilderProvider;
 import org.spongycastle.openpgp.operator.jcajce.JcePublicKeyKeyEncryptionMethodGenerator;
-import org.sufficientlysecure.keychain.Constants;
 import org.sufficientlysecure.keychain.util.IterableIterator;
 
-import java.security.SignatureException;
+/** Wrapper for a PGPPublicKey.
-
+ *
+ * The methods implemented in this class are a thin layer over
+ * UncachedPublicKey. The difference between the two classes is that objects of
+ * this class can only be obtained from a WrappedKeyRing, and that it stores a
+ * back reference to its parent as well. A method which works with
+ * WrappedPublicKey is therefore guaranteed to work on a KeyRing which is
+ * stored in the database.
+ *
+ */
 public class WrappedPublicKey extends UncachedPublicKey {
 
     // this is the parent key ring

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/WrappedSecretKey.java

@@ -26,6 +26,17 @@ import java.security.NoSuchProviderException;
 import java.security.SignatureException;
 import java.util.List;
 
+/** Wrapper for a PGPSecretKey.
+ *
+ * This object can only be obtained from a WrappedSecretKeyRing, and stores a
+ * back reference to its parent.
+ *
+ * This class represents known secret keys which are stored in the database.
+ * All "crypto operations using a known secret key" should be implemented in
+ * this class, to ensure on type level that these operations are performed on
+ * properly imported secret keys only.
+ *
+ */
 public class WrappedSecretKey extends WrappedPublicKey {
 
     private final PGPSecretKey mSecretKey;

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/WrappedSignature.java

@@ -17,6 +17,14 @@ import java.io.IOException;
 import java.security.SignatureException;
 import java.util.Date;
 
+/** OpenKeychain wrapper around PGPSignature objects.
+ *
+ * This is a mostly simple wrapper around a single bouncycastle PGPSignature
+ * object. It exposes high level getters for all relevant information, methods
+ * for verification of various signatures (uid binding, subkey binding, generic
+ * bytes), and a static method for construction from bytes.
+ *
+ */
 public class WrappedSignature {
 
     public static final int DEFAULT_CERTIFICATION = PGPSignature.DEFAULT_CERTIFICATION;

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/provider/CachedPublicKeyRing.java

@@ -7,6 +7,22 @@ import org.sufficientlysecure.keychain.pgp.KeyRing;
 import org.sufficientlysecure.keychain.pgp.exception.PgpGeneralException;
 import org.sufficientlysecure.keychain.util.Log;
 
+/** This implementation of KeyRing provides a cached view of PublicKeyRing
+ * objects based on database queries exclusively.
+ *
+ * This class should be used where only few points of data but no actual
+ * cryptographic operations are required about a PublicKeyRing which is already
+ * in the database.  This happens commonly in UI code, where parsing of a PGP
+ * key for examination would be a very expensive operation.
+ *
+ * Each getter method is implemented using a more or less expensive database
+ * query, while object construction is (almost) free. A common pattern is
+ * mProviderHelper.getCachedKeyRing(uri).getterMethod()
+ *
+ * TODO Ensure that the values returned here always match the ones returned by
+ * the parsed KeyRing!
+ *
+ */
 public class CachedPublicKeyRing extends KeyRing {
 
     final ProviderHelper mProviderHelper;