Class PEMEncoder

java.lang.Object
java.security.PEMEncoder
public final class PEMEncoder extends Object
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 binary encoding 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. Alternatively, a private key encrypted as an EncryptedPrivateKeyInfo object can be encoded directly to PEM by passing it to the encode or encodeToString methods.

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 as:

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(BinaryEncodable be)
    Encodes the specified BinaryEncodable and returns a PEM-encoded byte array.
    String
    encodeToString(BinaryEncodable be)
    Encodes the specified BinaryEncodable and returns a PEM-encoded string.
    static PEMEncoder
    of()
    Returns an instance of PEMEncoder.
    PEMEncoder
    withEncryption(char[] password)
    Returns a copy of this PEMEncoder that encrypts and encodes using the specified password and 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 PEMEncoder of()
      Returns an instance of PEMEncoder.
      Returns:
      a PEMEncoder

    • encodeToString

      public String encodeToString(BinaryEncodable 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 lacks encoding data, is an unsupported class, or cannot be used with encryption
      NullPointerException - if be is null
      CryptoException - if an error occurs during encryption
      See Also:

    • encode

      public byte[] encode(BinaryEncodable be)
      Encodes the specified BinaryEncodable and returns a PEM-encoded byte array.
      Parameters:
      be - the BinaryEncodable to be encoded
      Returns:
      a PEM-encoded byte array
      Throws:
      IllegalArgumentException - if be lacks encoding data, is an unsupported class, or cannot be used with encryption
      NullPointerException - if be is null
      CryptoException - if an error occurs during encryption
      See Also:

    • withEncryption

      public PEMEncoder withEncryption(char[] password)
      Returns a copy of this PEMEncoder that encrypts and encodes using the specified password and default encryption algorithm.

      Only PrivateKey, KeyPair, and PKCS8EncodedKeySpec objects can be encoded with this newly configured instance. Encoding other BinaryEncodable objects will throw a CryptoException.

      Implementation Note:
      The jdk.epkcs8.defaultAlgorithm security property defines the default encryption algorithm. The AlgorithmParameterSpec defaults are determined by the provider. To use non-default encryption parameters, or to encrypt with a different encryption provider, use EncryptedPrivateKeyInfo.encrypt(BinaryEncodable, Key, String, AlgorithmParameterSpec, Provider, SecureRandom) and use the returned object with encode(BinaryEncodable).
      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 - if generating the encryption key fails