Documenting the character conversion issue with PBE.

NOKEYCHECK=True
PiperOrigin-RevId: 516220120

1 files changed, 20 insertions, 0 deletions

diff --git a/java/com/google/security/wycheproof/testcases/JsonPbeTest.java b/java/com/google/security/wycheproof/testcases/JsonPbeTest.java
index e8de2b4..01c98ee 100644
--- a/java/com/google/security/wycheproof/testcases/JsonPbeTest.java
+++ b/java/com/google/security/wycheproof/testcases/JsonPbeTest.java
@@ -42,6 +42,26 @@ import org.junit.runners.JUnit4;
  * Password based encryption modes with a different set of parameters will use a different JSON
  * schema.
  *
+ * <p>One issue with the JCE interface for PBES1 and PBES2 is that the definition of these functions
+ * in RFC 2898 assumes that the password is given as an array of bytes. However, the java class
+ * PBEKeySpec expects an array of characters. The conversion between characters and bytes is not
+ * defined in RFC 2898. Rather this conversion is defined by the protocols using PBES1 and PBES2.
+ * Different protocols use different conversions: RFC 2898, Section 3 recommends either ASCII or
+ * UTF-8 encodings. PKCS #12, RFC 7292, Section B.1 specifies that passwords are represented as
+ * BMPStrings (2 bytes per character with a NULL terminator).
+ *
+ * <p>Hence, PBEKeySpec is not a well designed interface for implementing PBES1 and PBES2. The class
+ * forces an implementation of PBES1 or PBES2 to make decisions that would better be made by the
+ * caller. The tests below assume that standard algorithm names are used for PBES1 and PBES2 and
+ * that a PBEKeySpec is either converted to bytes by using UTF-8 encoding or rejecting non-ASCII
+ * characters. Some provider introduce alternative algorithm names and use different character to
+ * byte conversions. These alternative algorithms are not tested here.
+ *
+ * <p>The test vectors represent passwords as hexadecimal encoded byte arrays and thus remove the
+ * ambiguity caused by string conversion. Some test vectors have been constructed so that they are
+ * valid encodings generated by these conversions. Flags that are added to the test vectors describe
+ * the type of the encodings.
+ *
  * @author bleichen@google.com (Daniel Bleichenbacher)
  */
 @RunWith(JUnit4.class)