RFR: 8298420: PEM API: Implementation (Preview) [v20]

[Weijun Wang]

On Wed, 14 May 2025 08:25:41 GMT, Anthony Scarpino <ascarpino at openjdk.org> wrote:

>> Hi all,
>> 
>> I need a code review of the PEM API.  Privacy-Enhanced Mail (PEM) is a format for encoding and decoding cryptographic keys and certificates.  It will be integrated into JDK24 as a Preview Feature.  Preview features does not permanently define the API and it is subject to change in future releases until it is finalized.
>> 
>> Details about this change can be seen at [PEM API JEP](https://bugs.openjdk.org/browse/JDK-8300911).
>> 
>> Thanks
>> 
>> Tony
>
> Anthony Scarpino has updated the pull request incrementally with one additional commit since the last revision:
> 
>   comments

Last API comments.

src/java.base/share/classes/java/security/PEMDecoder.java line 61:

> 59:  * </pre>
> 60:  *
> 61:  * <p>>If the PEM does not have a cryptographic object representation,

Extra `>`.

src/java.base/share/classes/java/security/PEMDecoder.java line 86:

> 84:  * encrypted private key PEM data using the given password.
> 85:  * Configuring an instance for decryption does not prevent decoding with
> 86:  * unencrypted PEM. Any encrypted PEM that does not use the configured password

You mean when decryption fails? "Does not use the configured password" sounds strange to me,

src/java.base/share/classes/java/security/PEMDecoder.java line 87:

> 85:  * Configuring an instance for decryption does not prevent decoding with
> 86:  * unencrypted PEM. Any encrypted PEM that does not use the configured password
> 87:  * will throw a {@link RuntimeException}. When encrypted PEM is used with a

Add "an" before "encrypted PEM".

src/java.base/share/classes/java/security/PEMDecoder.java line 100:

> 98:  *
> 99:  * <p> Here is an example that decryption with a factory provider:
> 100:  * specified password:

"with a factory provider and a specified password".

src/java.base/share/classes/java/security/PEMDecoder.java line 237:

> 235:      * such as a {@code PrivateKey}, if the PEM type is supported.
> 236:      * Any non-PEM data preceding the PEM header is ignored by the decoder.
> 237:      * If no cryptographic object is found, a {@link PEMRecord} will be

Just say "otherwise". Same for other methods.

src/java.base/share/classes/java/security/PEMDecoder.java line 290:

> 288:      * @throws EOFException at the end of the {@code InputStream}.
> 289:      * @throws IllegalArgumentException on error in decoding
> 290:      * @throws NullPointerException when {@code is} is null.

Some still have periods at the end when the description is not a complete sentence. Please go through the whole file.

src/java.base/share/classes/java/security/PEMDecoder.java line 456:

> 454: 
> 455:     /**
> 456:      * Returns a copy of this {@code PEMDecoder} instance that uses

Why use "a copy"? Do you mean the password is kept?

-------------

PR Review: https://git.openjdk.org/jdk/pull/17543#pullrequestreview-2840153891
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088919847
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088931083
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088929195
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088932273
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088935412
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088952541
PR Review Comment: https://git.openjdk.org/jdk/pull/17543#discussion_r2088957451