Skip to content

Commit 3863f51

Browse files
author
kevin.w.wall
committed
Removed method to obtain the nonce used for the MIC. (Now a private method in DefaultCipherText.).
Many minor changes to Javadoc. Lots of other comment changes.
1 parent feba31e commit 3863f51

1 file changed

Lines changed: 26 additions & 25 deletions

File tree

‎src/main/java/org/owasp/esapi/CipherText.java‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
import 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

Comments
 (0)