mirror of
https://github.com/moparisthebest/open-keychain
synced 2024-11-12 03:55:09 -05:00
wrapped-key-ring: add documentation
This commit is contained in:
parent
d891f75339
commit
58edc0af67
@ -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
|
||||
|
@ -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;
|
||||
|
@ -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;
|
||||
}
|
||||
|
@ -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;
|
||||
|
@ -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
|
||||
|
@ -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;
|
||||
|
@ -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;
|
||||
|
@ -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;
|
||||
|
Loading…
Reference in New Issue
Block a user