From 8758095d2172f7edaacfbd0be33a954bf7abfec6 Mon Sep 17 00:00:00 2001 From: Jorge Solorzano Date: Sun, 10 May 2026 19:54:30 +0200 Subject: [PATCH] chore(docs): update javadoc for Profile interface --- .../java/com/ongres/stringprep/Profile.java | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/stringprep/src/main/java/com/ongres/stringprep/Profile.java b/stringprep/src/main/java/com/ongres/stringprep/Profile.java index 617fcf9..e9940c9 100644 --- a/stringprep/src/main/java/com/ongres/stringprep/Profile.java +++ b/stringprep/src/main/java/com/ongres/stringprep/Profile.java @@ -12,8 +12,8 @@ * processing options. * *

Stringprep profiles can also exclude characters that should not normally appear in text that - * is used in the protocol. The profile can prevent such characters by changing the characters to be - * excluded to other characters, by removing those characters, or by causing an error if the + * is used in the protocol. The profile can prevent such characters by mapping the prohibited + * characters to replacement characters, by removing those characters, or by causing an error if the * characters would appear in the output. * * @since 2.0 @@ -32,11 +32,11 @@ public interface Profile { * as user-entered names for digital certificate authorities and DNS lookups. * * @implNote The default method sets the storedStrings Stringprep parameter to {@code false}, as - * "queries" MAY include unassigned code points. This method should not necessarily be - * overridden by implementations. + * "queries" MAY include unassigned code points. Overriding this method is + * generally unnecessary unless specific String-based optimizations are required. * * @param string to prepare based on a "stringprep" profile. - * @return The prepared String. + * @return The prepared string. * @throws IllegalArgumentException if there is a prohibited output. * @since 2.1 */ @@ -49,11 +49,19 @@ default char[] prepareQuery(char[] string) { * as user-entered names for digital certificate authorities and DNS lookups. * * @implNote The default method sets the storedStrings Stringprep parameter to {@code false}, as - * "queries" MAY include unassigned code points. This method should not necessarily be - * overridden by implementations. + * "queries" MAY include unassigned code points. Overriding this method is generally + * unnecessary unless specific String-based optimizations are required. + * @apiNote This is a convenience method that delegates to {@link #prepareQuery(char[])}. + *

+ * Security Warning: This method is not recommended for + * handling sensitive data like passwords or private keys. Because {@link String} + * objects are immutable, their contents cannot be zeroed out after use and may persist in + * memory indefinitely. For cryptographic secrets, use + * {@link #prepareQuery(char[])} to ensure the data can be cleared immediately after + * processing. * * @param string to prepare based on a "stringprep" profile. - * @return The prepared String. + * @return The prepared string. * @throws IllegalArgumentException if there is a prohibited output. */ default String prepareQuery(String string) { @@ -65,11 +73,11 @@ default String prepareQuery(String string) { * names in digital certificates and DNS domain name parts. * * @implNote The default method sets the storedStrings Stringprep parameter to {@code true}, as - * "stored strings" MUST NOT contain unassigned code points. This method should not - * necessarily be overridden by implementations. + * "stored strings" MUST NOT contain unassigned code points. Overriding this method is + * generally unnecessary unless specific String-based optimizations are required. * * @param string to prepare based on a "stringprep" profile. - * @return The prepared String. + * @return The prepared string. * @throws IllegalArgumentException if there is a prohibited output. * @since 2.1 */ @@ -82,11 +90,19 @@ default char[] prepareStored(char[] string) { * names in digital certificates and DNS domain name parts. * * @implNote The default method sets the storedStrings Stringprep parameter to {@code true}, as - * "stored strings" MUST NOT contain unassigned code points. This method should not - * necessarily be overridden by implementations. + * "stored strings" MUST NOT contain unassigned code points. Overriding this method is + * generally unnecessary unless specific String-based optimizations are required. + * @apiNote This is a convenience method that delegates to {@link #prepareStored(char[])}. + *

+ * Security Warning: This method is not recommended for + * handling sensitive data like passwords or private keys. Because {@link String} + * objects are immutable, their contents cannot be zeroed out after use and may persist in + * memory indefinitely. For cryptographic secrets, use + * {@link #prepareStored(char[])} to ensure the data can be cleared immediately after + * processing. * * @param string to prepare based on a "stringprep" profile. - * @return The prepared String. + * @return The prepared string. * @throws IllegalArgumentException if there is a prohibited output. */ default String prepareStored(String string) { @@ -97,16 +113,17 @@ default String prepareStored(String string) { * Any additional mapping tables specific to the profile. * * @implSpec Profiles that requires additional mapping tables must implement this method. A code - * point match return the mapped array with the new code points or if there is no match, + * point match returns the mapped array with the new code points or if there is no match, * it should return the same input code point as {@code new int[] {codePoint};}. * Implementations MUST also set {@link Option#ADDITIONAL_MAPPING} to enable the - * proccesing of this rule. + * processing of this rule. * * @implNote The default implementation always return the same code point mapping ({@code new * int[] {codePoint}}), no change is done to the code point. * * @param codePoint the character (Unicode code point) to be mapped. - * @return Mapping with the int[] array or with the same codePoint. + * @return An array containing the mapped code points, or an array containing the original + * code point if no mapping applies. */ default int[] additionalMappingTable(int codePoint) { return new int[] {codePoint}; @@ -116,11 +133,11 @@ default int[] additionalMappingTable(int codePoint) { * Any additional characters that are prohibited as output specific to the profile. * * @implSpec Profiles that prohibit additional characters must implement this method. A code point - * match return {@code true}, or if the code point should not be prohibited it should - * return {@code false}. Implementations MUST also set - * {@link Option#FORBID_ADDITIONAL_CHARACTERS} to enable the proccesing of this rule. + * match returns {@code true}, or if the code point should not be prohibited it returns + * {@code false}. Implementations MUST also set + * {@link Option#FORBID_ADDITIONAL_CHARACTERS} to enable the processing of this rule. * - * @implNote The default implementation always return {@code false}, all characters are accepted. + * @implNote The default implementation always returns {@code false}; all characters are accepted. * * @param codePoint the character (Unicode code point) to be tested. * @return {@code true} if the given {@code codePoint} is prohibited on this profile.