performance: add license headers and some documentation

1 files changed, 17 insertions, 5 deletions

diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/util/Passphrase.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/util/Passphrase.java
index bb54f8024..d47aefdfd 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/util/Passphrase.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/util/Passphrase.java
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2015 Dominik Schürmann <dominik@dominikschuermann.de>
+ * Copyright (C) 2016 Vincent Breitmoser <look@my.amazin.horse>
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -32,8 +33,13 @@ import java.util.Map.Entry;
 
 
 /**
- * Passwords should not be stored as Strings in memory.
- * This class wraps a char[] that can be erased after it is no longer used.
+ * This class wraps a char[] array that is overwritten before the object is freed, to avoid
+ * keeping passphrases in memory as much as possible.
+ *
+ * In addition to the raw passphrases, this class can cache the session key output of an applied
+ * S2K algorithm for a given set of S2K parameters. Since S2K operations are very expensive, this
+ * mechanism should be used to cache session keys whenever possible.
+ *
  * See also:
  * <p/>
  * http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#PBEEx
@@ -43,7 +49,7 @@ import java.util.Map.Entry;
  */
 public class Passphrase implements Parcelable {
     private char[] mPassphrase;
-    HashMap<ComparableS2K, byte[]> mCachedSessionKeys;
+    private HashMap<ComparableS2K, byte[]> mCachedSessionKeys;
 
     /**
      * According to http://stackoverflow.com/a/15844273 EditText is not using String internally
@@ -93,14 +99,20 @@ public class Passphrase implements Parcelable {
         return mPassphrase.length;
     }
 
-    public byte[] getCachedSessionKeyForAlgorithm(int keyEncryptionAlgorithm, S2K s2k) {
+    /** @return A cached session key, or null if none exists for the given parameters. */
+    public byte[] getCachedSessionKeyForParameters(int keyEncryptionAlgorithm, S2K s2k) {
         if (mCachedSessionKeys == null) {
             return null;
         }
         return mCachedSessionKeys.get(new ComparableS2K(keyEncryptionAlgorithm, s2k));
     }
 
-    public void addCachedSessionKey(int keyEncryptionAlgorithm, S2K s2k, byte[] sessionKey) {
+    /** Adds a session key for a set of s2k parameters to this Passphrase object's
+     * cache. The caller should make sure that the supplied session key is the result
+     * of an S2K operation applied to exactly the passphrase stored by this object
+     * with the given parameters.
+     */
+    public void addCachedSessionKeyForParameters(int keyEncryptionAlgorithm, S2K s2k, byte[] sessionKey) {
         if (mCachedSessionKeys == null) {
             mCachedSessionKeys = new HashMap<>();
         }