wrapped-key-ring: add documentation

This commit is contained in:
Vincent Breitmoser 2014-05-31 13:10:41 +02:00
parent d891f75339
commit 58edc0af67
8 changed files with 85 additions and 8 deletions

View File

@ -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

View File

@ -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;

View File

@ -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;
}

View File

@ -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;

View File

@ -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

View File

@ -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;

View File

@ -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;

View File

@ -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;