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 security objects, such as asymmetric keys, certificates, and certificate revocation lists (CRL). It is defined in RFC 1421 and RFC 7468. PEM consists of a Base64-formatted binary encoding enclosed by a type-identifying header and footer.

Encoding may be performed on Java API cryptographic objects that implement DEREncodablePREVIEW. The encode(DEREncodable) and encodeToString(DEREncodable) methods encode a DEREncodable 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. Alternatively, a private key encrypted as an EncryptedKeyInfo object can be encoded directly to PEM by passing it to the encode or encodeToString methods.

PKCS #8 2.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 PEMRecordPREVIEW, the API surrounds the PEMRecord.content()PREVIEW with the PEM header and footer from PEMRecord.type()PREVIEW. PEMRecord.leadingData()PREVIEW is not included in the encoding. PEMRecord will not perform validity checks on the data.

The following lists the supported DEREncodable classes and the PEM types that each are encoded as:

  • X509Certificate : CERTIFICATE
  • X509CRL : X509 CRL
  • PublicKey: PUBLIC KEY
  • PrivateKey : PRIVATE KEY
  • PrivateKey (if configured with encryption): ENCRYPTED PRIVATE KEY
  • EncryptedPrivateKeyInfo : ENCRYPTED PRIVATE KEY
  • KeyPair : PRIVATE KEY
  • X509EncodedKeySpec : PUBLIC KEY
  • PKCS8EncodedKeySpec : PRIVATE KEY
  • PEMRecord : PEMRecord.type()

This class is immutable and thread-safe.

Here is an example of encoding a PrivateKey object: 

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

Here is an example that encrypts and encodes a private key using the specified password: 

    PEMEncoder pe = PEMEncoder.of().withEncryption(password);
    byte[] pemData = pe.encode(privKey);
Implementation Note:
An implementation may support other PEM types and DEREncodable objects.
Since:
25
External Specifications
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    encode(DEREncodablePREVIEW de)
    Encodes the specified DEREncodable and returns the PEM encoding in a byte array.
    String
    encodeToString(DEREncodablePREVIEW de)
    Encodes the specified DEREncodable and returns a PEM encoded string.
    static PEMEncoderPREVIEW
    of()
    Returns an instance of PEMEncoder.
    PEMEncoderPREVIEW
    withEncryption(char[] password)
    Returns a new PEMEncoder instance configured for encryption with the default algorithm and a given password.

    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.