1212import java .io .Serializable ;
1313
1414// DISCUSS: Do we want to treat this as if it should be replaceable too???
15- // If so, perhaps we need to define the service provider side.
15+ // If so, perhaps we need to define the service provider side and define
16+ // some appropriate 'setters'. More details in DefaultCipherText.
1617// Also, check the method names to see if they make sense / are intuitive.
1718
1819/**
@@ -119,7 +120,12 @@ public interface CipherText extends Serializable {
119120 * Return a base64-encoded representation of the raw ciphertext alone. Even
120121 * in the case where an IV is used, the IV is not prepended before the
121122 * base64-encoding is performed.
122- *
123+ * <p>
124+ * If there is a need to store an encrypted value, say in a database, this
125+ * is <i>not</i> the method you should use unless you are using a <i>fixed</i>
126+ * IV. If you are <i>not</i> using a fixed IV, you should normally use
127+ * {@link #getEncodedIVCipherText()} instead.
128+ * </p>
123129 * @see #getEncodedIVCipherText()
124130 */
125131 public String getBase64EncodedRawCipherText ();
@@ -129,8 +135,14 @@ public interface CipherText extends Serializable {
129135 * IV was used, the IV if first prepended to the raw ciphertext before
130136 * base64-encoding. If an IV is not used, then this method returns the same
131137 * value as {@link #getBase64EncodedRawCipherText()}.
132- *
138+ * <p>
139+ * Generally, this is the method that you should use unless you only
140+ * are using a fixed IV and a storing that IV separately, in which case
141+ * using {@link #getBase64EncodedRawCipherText()} can reduce the storage
142+ * overhead.
143+ * </p>
133144 * @return The base64-encoded ciphertext or base64-encoded IV + ciphertext.
145+ * @see #getBase64EncodedRawCipherText()
134146 */
135147 public String getEncodedIVCipherText ();
136148
@@ -157,7 +169,15 @@ public interface CipherText extends Serializable {
157169 * expensive.
158170 *
159171 * @param secret_key The secret key with which the plaintext is encrypted.
160- */
172+ */ // DISCUSS - Should this be secret_key or plaintext or neither? Have
173+ // post out to two former colleagues with more crypto knowledge.
174+ // May post to sci.crypt.research or elsewhere if no response.
175+ // Secret key would be preferable since we can test MIC via
176+ // validateMIC() even when decryption fails and results in
177+ // BadPaddingException. If we definitely decide its safe to
178+ // use the secret key, recommend changing arg for this method
179+ // and validateMIC() to use SecretKey rather than the encoded
180+ // secret key bytes.
161181 public void computeAndStoreMIC (byte [] secret_key );
162182
163183 /**
@@ -167,27 +187,8 @@ public interface CipherText extends Serializable {
167187 * <i>not</i> detect the case where an attacker simply substitutes one
168188 * valid ciphertext with another ciphertext.
169189 *
170- * @param ciphertext The raw ciphertext bytes.
190+ * @param secretKey The raw bytes of the secret encryption key .
171191 * @return True if the ciphertext has not be tampered with, and false otherwise.
172- *
173- * @see #getNonce()
174192 */
175- public boolean validateMIC (byte [] ciphertext );
176-
177- /**
178- * Obtain the nonce used to calculate the message integrity code (MIC).
179- * The purpose of this is two-fold: first is to ensure the integrity of
180- * the ciphertext and second is to help us detect if the wrong encryption
181- * key was used to attempt to decrypt (something that is very important
182- * when one occasionally does key change operations [i.e., rotates keys]).
183- * <p>
184- * Note that the nonce itself should be treated as an opaque object. That
185- * is, no meaning should be inferred from it by users of this class.
186- *
187- * @return The nonce (number used once) used in creating the MIC.
188- *
189- * @see #validateMIC(byte[])
190- */
191- byte [] getNonce ();
192-
193+ public boolean validateMIC (byte [] ciphertext ); // DISCUSS: See above discussion.
193194}
0 commit comments