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 BinaryEncodablePREVIEW. 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 PEMPREVIEW 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:

When used with a PEMEncoder instance configured for encryption:

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:
25
External Specifications
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    encode(BinaryEncodablePREVIEW be)
    Encodes the specified BinaryEncodable and returns a PEM-encoded byte array.
    String
    encodeToString(BinaryEncodablePREVIEW be)
    Encodes the specified BinaryEncodable and returns a PEM-encoded string.
    static PEMEncoderPREVIEW
    of()
    Returns an instance of PEMEncoder.
    PEMEncoderPREVIEW
    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()
    Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
    boolean
    equals(Object o)
    Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    May cause performance issues, deadlocks and hangs.
    final Class<? extends Object>
    getClass()
    Answers the unique instance of java.lang.Class which represents the class of the receiver.
    int
    hashCode()
    Answers an integer hash code for the receiver.
    final void
    notify()
    Causes one thread which is waiting on the receiver to be made ready to run.
    final void
    notifyAll()
    Causes all threads which are waiting on the receiver to be made ready to run.
    String
    toString()
    Answers a string containing a concise, human-readable description of the receiver.
    final void
    wait()
    Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
    final void
    wait(long time)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
    final void
    wait(long time, int frac)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.

  • 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
      CryptoExceptionPREVIEW - if an error occurs during encryption
      Since:
      27
      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
      CryptoExceptionPREVIEW - if an error occurs during encryption
      Since:
      27
      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
      CryptoExceptionPREVIEW - if generating the encryption key fails