Class PEMEncoder

java.lang.Object

java.security.PEMEncoder

public final class PEMEncoder extends Object

PEMEncoder is a preview API of the Java platform.

Programs can only use PEMEncoder when preview features are enabled.

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

PEMEncoder implements an encoder 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 a Base64-encoded content enclosed by a type-identifying header and footer.

Encoding can be performed on cryptographic objects that implement BinaryEncodable^PREVIEW. The encode(BinaryEncodable) and encodeToString(BinaryEncodable) methods encode a BinaryEncodable into PEM and return the data in a byte array or String.

Private keys can be encrypted and encoded by configuring a PEMEncoder with the withEncryption(char[]) method, which takes a password and returns a new PEMEncoder instance configured to encrypt the key with that password.

PKCS #8 v2.0 defines the ASN.1 OneAsymmetricKey structure, which may contain both private and public keys. KeyPair objects passed to the encode or encodeToString methods are encoded as a OneAsymmetricKey structure using the "PRIVATE KEY" type.

When encoding a PEM^PREVIEW object, the API surrounds PEM.content()^PREVIEW with a PEM header and footer based on PEM.type()^PREVIEW. The value returned by PEM.leadingData()^PREVIEW is not included in the output.

The following lists the supported BinaryEncodable classes and the PEM types they encode to:

X509Certificate: CERTIFICATE
X509CRL: X509 CRL
PublicKey: PUBLIC KEY
PrivateKey: PRIVATE KEY
EncryptedPrivateKeyInfo: ENCRYPTED PRIVATE KEY
KeyPair: PRIVATE KEY
X509EncodedKeySpec: PUBLIC KEY
PKCS8EncodedKeySpec: PRIVATE KEY
PEM^PREVIEW: PEM.type()^PREVIEW

When used with a PEMEncoder instance configured for encryption:

PrivateKey: ENCRYPTED PRIVATE KEY
KeyPair: ENCRYPTED PRIVATE KEY
PKCS8EncodedKeySpec: ENCRYPTED PRIVATE KEY

This class is immutable and thread-safe.

Example: encode a private key:

    PEMEncoder pe = PEMEncoder.of();
    byte[] pemData = pe.encode(privKey);

Example: encrypt and encode a private key using a password:

    PEMEncoder pe = PEMEncoder.of().withEncryption(password);
    byte[] pemData = pe.encode(privKey);

Implementation Note:

Implementations may support additional PEM types.

Since:

External Specifications

See Also:

Method Summary

Modifier and Type	Method	Description
`byte[]`	`encode(BinaryEncodable^PREVIEW be)`	Encodes the specified `BinaryEncodable` and returns a PEM-encoded byte array.
`String`	`encodeToString(BinaryEncodable^PREVIEW be)`	Encodes the specified `BinaryEncodable` and returns a PEM-encoded string.
`static PEMEncoder^PREVIEW`	`of()`	Returns an instance of `PEMEncoder`.
`PEMEncoder^PREVIEW`	`withEncryption(char[] password)`	Returns a copy of this `PEMEncoder` configured to encrypt and encode using the specified password and the default encryption algorithm.

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 PEMEncoderPREVIEW of()

Returns an instance of PEMEncoder.

Returns:: a PEMEncoder

encodeToString

public String encodeToString(BinaryEncodablePREVIEW be)

Encodes the specified BinaryEncodable and returns a PEM-encoded string.

Parameters:

be - the BinaryEncodable to encode

Returns:

a String containing the PEM-encoded data

Throws:

IllegalArgumentException - if be has no encoding, is an unsupported class, or cannot be used with encryption

NullPointerException - if be is null

CryptoException^PREVIEW - if an error occurs during encryption

Since:

See Also:

encode

public byte[] encode(BinaryEncodablePREVIEW be)

Encodes the specified BinaryEncodable and returns a PEM-encoded byte array.

Parameters:

be - the BinaryEncodable to encode

Returns:

a PEM-encoded byte array

Throws:

IllegalArgumentException - if be has no encoding, is an unsupported class, or cannot be used with encryption

NullPointerException - if be is null

CryptoException^PREVIEW - if an error occurs during encryption

Since:

See Also:

withEncryption

public PEMEncoderPREVIEW withEncryption(char[] password)

Returns a copy of this PEMEncoder configured to encrypt and encode using the specified password and the default encryption algorithm.

Only PrivateKey, KeyPair, and PKCS8EncodedKeySpec objects can be encoded with this newly configured instance. Attempting to encode other BinaryEncodable objects will throw an IllegalArgumentException.

To use non-default encryption parameters or a different provider, use an encrypt method in EncryptedPrivateKeyInfo, then pass the resulting object to encode(BinaryEncodable).

Implementation Note:: The jdk.epkcs8.defaultAlgorithm security property defines the default encryption algorithm. The AlgorithmParameterSpec defaults are determined by the provider.
Parameters:: password - the encryption password. The array is cloned and stored in the new instance.
Returns:: a new PEMEncoder instance configured for encryption
Throws:: NullPointerException - if password is null; CryptoException^PREVIEW - if generating the encryption key fails

© 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.