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

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. 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 object, the API surrounds PEM#content() with a PEM header and footer based on PEM#type(). The value returned by PEM#leadingData() 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: PEM#type()

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

Modifier and Type	Field and Description
private final SecretKey	key
private static final PEMEncoder	PEM_ENCODER

Access	Constructor and Description
private	PEMEncoder(PBEKeySpec keySpec) Creates a PEMEncoder instance configured for the given keySpec.

Method Summary

Modifier and Type	Method and Description
private byte[]	buildKey(byte[] publicEncoding, byte[] privateEncoding) Build the PEM encoding for AsymmetricKey and KeyPair
public byte[]	Returns: a PEM-encoded byte array encode(BinaryEncodable the `BinaryEncodable` to encode be) Encodes the specified `BinaryEncodable` and returns a PEM-encoded byte array.
public String	Returns: a `String` containing the PEM-encoded data encodeToString(BinaryEncodable the `BinaryEncodable` to encode be) Encodes the specified `BinaryEncodable` and returns a PEM-encoded string.
public static PEMEncoder	Returns: a `PEMEncoder` of() Returns an instance of `PEMEncoder`.
public PEMEncoder	Returns: a new `PEMEncoder` instance configured for encryption withEncryption(char[] the encryption password. The array is cloned and stored in the new instance. password) Returns a copy of this `PEMEncoder` configured to encrypt and encode using the specified password and the default encryption algorithm.

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

key	back to summary
private final SecretKey key

PEM_ENCODER	back to summary
private static final PEMEncoder PEM_ENCODER

PEMEncoder	back to summary
private PEMEncoder(PBEKeySpec keySpec) Creates a PEMEncoder instance configured for the given keySpec.

Method Detail

buildKey	back to summary
private byte[] buildKey(byte[] publicEncoding, byte[] privateEncoding) Build the PEM encoding for AsymmetricKey and KeyPair

encode back to summary

encode	back to summary
public byte[] encode(BinaryEncodable be) Encodes the specified `BinaryEncodable` and returns a PEM-encoded byte array. Parameters be:BinaryEncodable the `BinaryEncodable` to encode Returns:byte[] a PEM-encoded byte array Exceptions IllegalArgumentException: if `be` has no encoding, is an unsupported class, or cannot be used with encryption NullPointerException: if `be` is `null` CryptoException: if an error occurs during encryption Since 27 See Also `withEncryption(char[])`

public byte[] encode(BinaryEncodable be)

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

Parameters

be:BinaryEncodable: the BinaryEncodable to encode

Returns:byte[]

a PEM-encoded byte array

Exceptions

IllegalArgumentException:: if be has no encoding, is an unsupported class, or cannot be used with encryption
NullPointerException:: if be is null
CryptoException:: if an error occurs during encryption

Since

See Also

withEncryption(char[])

encodeToString back to summary

encodeToString	back to summary
public String encodeToString(BinaryEncodable be) Encodes the specified `BinaryEncodable` and returns a PEM-encoded string. Parameters be:BinaryEncodable the `BinaryEncodable` to encode Returns:String a `String` containing the PEM-encoded data Exceptions IllegalArgumentException: if `be` has no encoding, is an unsupported class, or cannot be used with encryption NullPointerException: if `be` is `null` CryptoException: if an error occurs during encryption Since 27 See Also `withEncryption(char[])`

public String encodeToString(BinaryEncodable be)

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

Parameters

be:BinaryEncodable: the BinaryEncodable to encode

Returns:String

a String containing the PEM-encoded data

Exceptions

IllegalArgumentException:: if be has no encoding, is an unsupported class, or cannot be used with encryption
NullPointerException:: if be is null
CryptoException:: if an error occurs during encryption

Since

See Also

withEncryption(char[])

of back to summary

of	back to summary
public static PEMEncoder of() Returns an instance of `PEMEncoder`. Returns:PEMEncoder a `PEMEncoder`

public static PEMEncoder of()

Returns an instance of PEMEncoder.

Returns:PEMEncoder: a PEMEncoder

withEncryption back to summary

withEncryption	back to summary
public PEMEncoder 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:char[] the encryption password. The array is cloned and stored in the new instance. Returns:PEMEncoder a new `PEMEncoder` instance configured for encryption Exceptions NullPointerException: if `password` is `null` CryptoException: if generating the encryption key fails

public PEMEncoder 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:char[]: the encryption password. The array is cloned and stored in the new instance.

Returns:PEMEncoder

a new PEMEncoder instance configured for encryption

Exceptions

NullPointerException:: if password is null
CryptoException:: if generating the encryption key fails

public final Class PEMEncoder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail