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

[Anthony Scarpino]

On Mon, 21 Oct 2024 19:52:36 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:
> 
>   apparently <p> can't be before a @implNote.. Who know.

@svis

> This JEP is misnamed. The RFC clearly says
> 
> ```
>    For reasons that basically boil down to non-coordination or
>    inattention, many PKIX, PKCS, and CMS libraries implement a text-
>    based encoding that is similar to -- but not identical with -- PEM
>    encoding. 
> ...
> Unlike legacy PEM encoding [[RFC1421](https://www.rfc-editor.org/rfc/rfc1421)], OpenPGP ASCII armor, and the
>    OpenSSH key file format, textual encoding does *not* define or permit
>    headers to be encoded alongside the data.  Empty space can appear
>    between the pre-encapsulation boundary and the base64, but generators
>    SHOULD NOT emit such any such spacing.  (The provision for this empty
>    area is a throwback to PEM, which defined an "encapsulated header
>    portion".)
> ```
> 
> So this RFC is clearly not PEM and this JEP shouldn't be named as such, hence class names neither.

PEM has evolved over time as the RFC states, but that doesn't change that PEM is the established term for this textual format.  RFC1421 was not added to the JEP because it does not need to explain the history.   To quote the whole paragraph:

The tradition within the RFC series can be traced back to Privacy-
Enhanced Mail (PEM) [[RFC1421](https://www.rfc-editor.org/rfc/rfc1421)],
 based on a proposal by Marshall Rose in Message Encapsulation 
[[RFC934](https://www.rfc-editor.org/rfc/rfc934)].  Originally called 
"PEM encapsulation mechanism", "encapsulated PEM message", or 
(arguably) "PEM printable encoding", today the format is sometimes 
referred to as "PEM encoding".  Variations include OpenPGP ASCII 
armor [[RFC4880](https://www.rfc-editor.org/rfc/rfc4880)] and 
OpenSSH key file format [[RFC4716](https://www.rfc-editor.org/rfc/rfc4716)].

The JEP is clear that PKCS#8 and X.509 are supported.  Other variations could be added to the PEM API in the future or by a different API. 

OpenSSL use the "PEM" for `-inform`, `-outform`, and many other examples.  BouncyCastle has PEMReader, PEMWriter, and PEMParser.  Even wikipedia states that "[The PEM format was eventually formalized by the IETF in RFC 7468](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail)".  The Java API using a different term would lead to unnecessary confusion.

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

PR Comment: https://git.openjdk.org/jdk/pull/17543#issuecomment-2427992444