Class PEMDecoder

java.lang.Object

java.security.PEMDecoder

public final class PEMDecoder extends Object

PEMDecoder is a preview API of the Java platform.

Programs can only use PEMDecoder when preview features are enabled.

Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.

PEMDecoder implements a decoder for Privacy-Enhanced Mail (PEM) data. PEM is a textual encoding used to store and transfer cryptographic objects, such as asymmetric keys, certificates, and certificate revocation lists (CRLs). It is defined in RFC 1421 and RFC 7468. PEM consists of Base64-encoded content enclosed by a header and footer that identify the type of the content.

The decode(String) and decode(InputStream) methods return an instance of a class that matches the PEM type and implements BinaryEncodable^PREVIEW, as follows:

CERTIFICATE: X509Certificate
X509 CRL: X509CRL
PUBLIC KEY: PublicKey
PRIVATE KEY: PrivateKey or KeyPair (if the encoding contains a public key)
ENCRYPTED PRIVATE KEY: EncryptedPrivateKeyInfo
Other types: PEM^PREVIEW

When used with a PEMDecoder instance configured for decryption:

ENCRYPTED PRIVATE KEY: PrivateKey or KeyPair (if the encoding contains a public key)

If the PEM type has no corresponding class, decode(String) and decode(InputStream) return a PEM object.

If application code switches over the BinaryEncodable result of decode(String) or decode(InputStream), the switch cannot be made exhaustive simply by providing a case label for every permitted subtype listed for BinaryEncodable; there also must be a default or case BinaryEncodable label to handle additional subtypes that might be added in the future.

The decode(String, Class) and decode(InputStream, Class) methods accept a parameter specifying the desired BinaryEncodable result. These methods avoid the need for casting and are useful when multiple representations are possible. For example, if the PEM contains both public and private keys, specifying PrivateKey.class returns only the private key. If X509EncodedKeySpec.class is provided, the public key encoding is returned as a X509EncodedKeySpec. To retrieve a PEM^PREVIEW object, use PEM.class. If the specified class does not match the PEM content, a ClassCastException is thrown.

In addition to the types listed above, these methods support the following PEM types and BinaryEncodable classes when specified as parameters:

PUBLIC KEY: X509EncodedKeySpec
PRIVATE KEY: PKCS8EncodedKeySpec
PRIVATE KEY: PublicKey (if the encoding contains a public key)
PRIVATE KEY: X509EncodedKeySpec (if the encoding contains a public key)

When used with a PEMDecoder instance configured for decryption:

ENCRYPTED PRIVATE KEY: PKCS8EncodedKeySpec
ENCRYPTED PRIVATE KEY: PublicKey (if the encoding contains a public key)
ENCRYPTED PRIVATE KEY: X509EncodedKeySpec (if the encoding contains a public key)

A new PEMDecoder instance is created when configured with withFactoriesOf(Provider) or withDecryption(char[]). The withFactoriesOf(Provider) method uses the specified provider when obtaining KeyFactory and CertificateFactory instances used during decoding. The withDecryption(char[]) method configures the decoder to decrypt and decode encrypted private key PEM data using the given password. If decryption fails, a CryptoException^PREVIEW is thrown. If an encrypted PEM is processed by a decoder not configured for decryption, an EncryptedPrivateKeyInfo is returned. A PEMDecoder configured for decryption can also decode unencrypted PEM.

This class is immutable and thread-safe.

Example: decode a private key:

    PEMDecoder pd = PEMDecoder.of();
    PrivateKey priKey = pd.decode(priKeyPEM, PrivateKey.class);

Example: configure decryption and a factory provider:

     PEMDecoder pd = PEMDecoder.of().withDecryption(password).
             withFactoriesOf(provider);
     BinaryEncodable pemData = pd.decode(privKeyPEM);

Implementation Note:

This implementation decodes non-encrypted RSA PRIVATE KEY as PrivateKey, X509 CERTIFICATE and X.509 CERTIFICATE as X509Certificate, and CRL as X509CRL. Other implementations may recognize additional PEM types.

Since:

External Specifications

See Also:

Method Summary

Modifier and Type	Method	Description
`BinaryEncodable^PREVIEW`	`decode(InputStream is)`	Decodes and returns a `BinaryEncodable` from the given `InputStream`.
`<S extends BinaryEncodable^PREVIEW> S`	`decode(InputStream is, Class<S> tClass)`	Decodes and returns a `BinaryEncodable` of the specified class from the given `InputStream`.
`BinaryEncodable^PREVIEW`	`decode(String str)`	Decodes and returns a `BinaryEncodable` from the given `String`.
`<S extends BinaryEncodable^PREVIEW> S`	`decode(String str, Class<S> tClass)`	Decodes and returns a `BinaryEncodable` of the specified class from the given PEM string.
`static PEMDecoder^PREVIEW`	`of()`	Returns the default `PEMDecoder` instance.
`PEMDecoder^PREVIEW`	`withDecryption(char[] password)`	Returns a copy of this `PEMDecoder` that decodes and decrypts encrypted private keys using the specified password.
`PEMDecoder^PREVIEW`	`withFactoriesOf(Provider provider)`	Returns a copy of this `PEMDecoder` instance that uses `KeyFactory` and `CertificateFactory` implementations from the specified `Provider` to produce cryptographic objects.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Modifier and Type	Method	Description
`protected Object`	`clone()`	Creates and returns a copy of this object.
`boolean`	`equals(Object obj)`	Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()`	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
`final Class<?>`	`getClass()`	Returns the runtime class of this `Object`.
`int`	`hashCode()`	Returns a hash code value for this object.
`final void`	`notify()`	Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()`	Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()`	Returns a string representation of the object.
`final void`	`wait()`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`	`wait(long timeoutMillis)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis, int nanos)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Method Details

of

public static PEMDecoderPREVIEW of()

Returns the default PEMDecoder instance.

Returns:: the default PEMDecoder

decode

public BinaryEncodablePREVIEW decode(String str)

Decodes and returns a BinaryEncodable from the given String.

This method reads the String until PEM data is found or the end of the String is reached. If no PEM data is found, an IllegalArgumentException is thrown.

A BinaryEncodable is returned that best represents the decoded content. If the PEM type is not supported, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.

The input is interpreted as UTF-8.

Parameters:: str - a String containing PEM data
Returns:: a BinaryEncodable
Throws:: IllegalArgumentException - if decoding fails or no PEM data is found; NullPointerException - if str is null; CryptoException^PREVIEW - if an error occurs during decryption
Since:: 27

decode

public BinaryEncodablePREVIEW decode(InputStream is) throws IOException

Decodes and returns a BinaryEncodable from the given InputStream.

This method reads from the InputStream until the end of a PEM footer or the end of the stream. If an I/O error occurs, the stream position may become inconsistent. Further decoding operations on the same InputStream are not recommended.

If no PEM data is found, an EOFException is thrown.

Parameters:: is - InputStream containing PEM data
Returns:: a BinaryEncodable
Throws:: IOException - if an I/O error occurs or PEM syntax is invalid; EOFException - if no PEM data is found or the stream ends unexpectedly; IllegalArgumentException - if decoding fails; NullPointerException - if InputStream is null; CryptoException^PREVIEW - if an error occurs during decryption
Since:: 27

decode

public <S extends BinaryEncodablePREVIEW> S decode(String str, Class<S> tClass)

Decodes and returns a BinaryEncodable of the specified class from the given PEM string.

tClass must be an appropriate class for the PEM type.

This method reads the String until PEM data is found or the end of the String is reached. If no PEM data is found, an IllegalArgumentException is thrown.

If tClass is PEM.class, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.

The input is interpreted as UTF-8.

Type Parameters:: S - class type parameter that extends BinaryEncodable
Parameters:: str - the String containing PEM data; tClass - the returned object class that extends or implements BinaryEncodable
Returns:: a BinaryEncodable specified by tClass
Throws:: IllegalArgumentException - on error in decoding or no PEM data found; ClassCastException - if tClass does not represent the PEM type; NullPointerException - if any input values are null; CryptoException^PREVIEW - if an error occurs during decryption
Since:: 27

decode

public <S extends BinaryEncodablePREVIEW> S decode(InputStream is, Class<S> tClass) throws IOException

Decodes and returns a BinaryEncodable of the specified class from the given InputStream.

tClass must be an appropriate class for the PEM type.

If no PEM data is found, an EOFException is thrown.

Type Parameters:

S - class type parameter that extends BinaryEncodable

Parameters:

is - an InputStream containing PEM data

tClass - the returned object class that extends or implements BinaryEncodable

Returns:

a BinaryEncodable of type tClass

Throws:

IOException - if an I/O error occurs or PEM syntax is invalid

EOFException - if no PEM data is found or the stream ends unexpectedly

IllegalArgumentException - if decoding fails

ClassCastException - if tClass does not represent the PEM type

NullPointerException - if any input values are null

CryptoException^PREVIEW - if an error occurs during decryption

Since:

See Also:

withFactoriesOf

public PEMDecoderPREVIEW withFactoriesOf(Provider provider)

Returns a copy of this PEMDecoder instance that uses KeyFactory and CertificateFactory implementations from the specified Provider to produce cryptographic objects. Any errors using the Provider will occur during decoding.

Parameters:: provider - the factory Provider
Returns:: a new PEMDecoder instance configured with the Provider
Throws:: NullPointerException - if provider is null
Since:: 27

withDecryption

public PEMDecoderPREVIEW withDecryption(char[] password)

Returns a copy of this PEMDecoder that decodes and decrypts encrypted private keys using the specified password. Unencrypted PEM can also be decoded by the returned instance.

Parameters:: password - the password to decrypt the encrypted PEM data. This array is cloned and stored in the new instance.
Returns:: a new PEMDecoder instance configured for decryption
Throws:: NullPointerException - if password is null

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.