OpenJDK 27 · java.security.PEMDecoder · APIdia, the JavaDoc alternative

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, 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

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 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 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);

Field Summary

Modifier and Type	Field and Description
private final Provider	factory
private final PBEKeySpec	keySpec
private static final PEMDecoder	PEM_DECODER

Constructor Summary

Access	Constructor and Description
private	PEMDecoder(Provider Key/Certificate factory provider withFactory, PBEKeySpec PBEKeySpec for EncryptedPrivateKeyInfo decryption withKeySpec) Creates an instance with a specific provider and/or password.

Method Summary

Modifier and Type	Method and Description
private BinaryEncodable	decode(PEM pem) After the header, footer, and base64 have been separated, identify the header and footer and proceed with decoding the base64 for the appropriate type.
public BinaryEncodable	Returns: a `BinaryEncodable` decode(String a `String` containing PEM data str) Decodes and returns a `BinaryEncodable` from the given `String`.
public BinaryEncodable	Returns: a `BinaryEncodable` decode(InputStream `InputStream` containing PEM data is) Decodes and returns a `BinaryEncodable` from the given `InputStream`.
public < class type parameter that extends `BinaryEncodable` S extends BinaryEncodable> S	Returns: a `BinaryEncodable` specified by `tClass` decode(String the `String` containing PEM data str, Class<S> the returned object class that extends or implements `BinaryEncodable` tClass) Decodes and returns a `BinaryEncodable` of the specified class from the given PEM string.
public < class type parameter that extends `BinaryEncodable` S extends BinaryEncodable> S	Returns: a `BinaryEncodable` of type `tClass` decode(InputStream an `InputStream` containing PEM data is, Class<S> the returned object class that extends or implements `BinaryEncodable` tClass) Decodes and returns a `BinaryEncodable` of the specified class from the given `InputStream`.
private CertificateFactory	getCertFactory(String algorithm)
private KeyFactory	getKeyFactory(String algorithm)
public static PEMDecoder	Returns: the default `PEMDecoder` of() Returns the default `PEMDecoder` instance.
public PEMDecoder	Returns: a new `PEMDecoder` instance configured for decryption withDecryption(char[] the password to decrypt the encrypted PEM data. This array is cloned and stored in the new instance. password) Returns a copy of this `PEMDecoder` that decodes and decrypts encrypted private keys using the specified password.
public PEMDecoder	Returns: a new `PEMDecoder` instance configured with the `Provider` withFactoriesOf(Provider the factory `Provider` provider) Returns a copy of this `PEMDecoder` instance that uses `KeyFactory` and `CertificateFactory` implementations from the specified `Provider` to produce cryptographic objects.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

factory	back to summary
private final Provider factory

keySpec	back to summary
private final PBEKeySpec keySpec

PEM_DECODER	back to summary
private static final PEMDecoder PEM_DECODER

Constructor Detail

PEMDecoder	back to summary
private PEMDecoder(Provider withFactory, PBEKeySpec withKeySpec) Creates an instance with a specific provider and/or password. Parameters withFactory:Provider Key/Certificate factory provider withKeySpec:PBEKeySpec PBEKeySpec for EncryptedPrivateKeyInfo decryption

PEMDecoder

back to summary

private PEMDecoder(Provider withFactory, PBEKeySpec withKeySpec)

Creates an instance with a specific provider and/or password.

Parameters

withFactory:Provider: Key/Certificate factory provider
withKeySpec:PBEKeySpec: PBEKeySpec for EncryptedPrivateKeyInfo decryption

Method Detail

decode	back to summary
private BinaryEncodable decode(PEM pem) After the header, footer, and base64 have been separated, identify the header and footer and proceed with decoding the base64 for the appropriate type.

decode back to summary

decode	back to summary
public BinaryEncodable 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:String a `String` containing PEM data Returns:BinaryEncodable a `BinaryEncodable` Exceptions IllegalArgumentException: if decoding fails or no PEM data is found NullPointerException: if `str` is `null` CryptoException: if an error occurs during decryption Since 27

public BinaryEncodable 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:String: a String containing PEM data

Returns:BinaryEncodable

a BinaryEncodable

Exceptions

IllegalArgumentException:: if decoding fails or no PEM data is found
NullPointerException:: if str is null
CryptoException:: if an error occurs during decryption

Since

decode back to summary

decode	back to summary
public BinaryEncodable 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. 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. If no PEM data is found, an `EOFException` is thrown. Parameters is:InputStream `InputStream` containing PEM data Returns:BinaryEncodable a `BinaryEncodable` Exceptions 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: if an error occurs during decryption Since 27

public BinaryEncodable 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: InputStream containing PEM data

Returns:BinaryEncodable

a BinaryEncodable

Exceptions

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:: if an error occurs during decryption

Since

decode back to summary

decode	back to summary
public <S extends BinaryEncodable> 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`. Parameters <S> class type parameter that extends `BinaryEncodable` str:String the `String` containing PEM data tClass:Class<S> the returned object class that extends or implements `BinaryEncodable` Returns:S a `BinaryEncodable` specified by `tClass` Exceptions 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: if an error occurs during decryption Since 27

public <S extends BinaryEncodable> 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.

Parameters

<S>: class type parameter that extends BinaryEncodable
str:String: the String containing PEM data
tClass:Class<S>: the returned object class that extends or implements BinaryEncodable

Returns:S

a BinaryEncodable specified by tClass

Exceptions

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:: if an error occurs during decryption

Since

decode back to summary

decode	back to summary
public <S extends BinaryEncodable> 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. 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 `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. If no PEM data is found, an `EOFException` is thrown. Parameters <S> class type parameter that extends `BinaryEncodable` is:InputStream an `InputStream` containing PEM data tClass:Class<S> the returned object class that extends or implements `BinaryEncodable` Returns:S a `BinaryEncodable` of type `tClass` Exceptions 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: if an error occurs during decryption Since 27 See Also `decode(InputStream)`, `decode(String, Class)`

public <S extends BinaryEncodable> 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.

Parameters

<S>: class type parameter that extends BinaryEncodable
is:InputStream: an InputStream containing PEM data
tClass:Class<S>: the returned object class that extends or implements BinaryEncodable

Returns:S

a BinaryEncodable of type tClass

Exceptions

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:: if an error occurs during decryption

Since

getCertFactory	back to summary
private CertificateFactory getCertFactory(String algorithm)

getKeyFactory	back to summary
private KeyFactory getKeyFactory(String algorithm)

of back to summary

of	back to summary
public static PEMDecoder of() Returns the default `PEMDecoder` instance. Returns:PEMDecoder the default `PEMDecoder`

public static PEMDecoder of()

Returns the default PEMDecoder instance.

Returns:PEMDecoder: the default PEMDecoder

withDecryption back to summary

withDecryption	back to summary
public PEMDecoder 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:char[] the password to decrypt the encrypted PEM data. This array is cloned and stored in the new instance. Returns:PEMDecoder a new `PEMDecoder` instance configured for decryption Exceptions NullPointerException: if `password` is `null`

public PEMDecoder 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:char[]: the password to decrypt the encrypted PEM data. This array is cloned and stored in the new instance.

Returns:PEMDecoder

a new PEMDecoder instance configured for decryption

Exceptions

NullPointerException:: if password is null

withFactoriesOf back to summary

withFactoriesOf	back to summary
public PEMDecoder 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:Provider the factory `Provider` Returns:PEMDecoder a new `PEMDecoder` instance configured with the `Provider` Exceptions NullPointerException: if `provider` is `null` Since 27

public PEMDecoder 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:Provider: the factory Provider

Returns:PEMDecoder

a new PEMDecoder instance configured with the Provider

Exceptions

NullPointerException:: if provider is null

Since

public final Class PEMDecoder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail