# 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 binary encoding enclosed by a type-identifying header and footer.

Encoding can be performed on cryptographic objects that implement `DEREncodable`PREVIEW. 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 `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`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 `DEREncodable` classes and the PEM types they encode as:

- `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()`

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:
  25
External Specifications
  - RFC 1421: Privacy Enhancement for Internet Electronic Mail
  - RFC 5958: Asymmetric Key Packages
  - RFC 7468: Textual Encodings of PKIX, PKCS, and CMS Structures
See Also:
  - `PEMDecoder`PREVIEW
  - `PEM`PREVIEW
  - `EncryptedPrivateKeyInfo`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `byte[]`
  `encode(DEREncodablePREVIEW de)`
  Encodes the specified `DEREncodable` and returns a PEM-encoded 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 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 PEMEncoderPREVIEW of()
    Returns an instance of `PEMEncoder`.
    Returns:
      a `PEMEncoder`

  - ### encodeToString

    public String encodeToString(DEREncodablePREVIEW de)
    Encodes the specified `DEREncodable` and returns a PEM-encoded string.
    Parameters:
      `de` - the `DEREncodable` to be encoded
    Returns:
      a `String` containing the PEM-encoded data
    Throws:
      `IllegalArgumentException` - if the `DEREncodable` cannot be encoded
      `NullPointerException` - if `de` is `null`
    See Also:
      - `withEncryption(char[])`

  - ### encode

    public byte[] encode(DEREncodablePREVIEW de)
    Encodes the specified `DEREncodable` and returns a PEM-encoded byte array.
    Parameters:
      `de` - the `DEREncodable` to be encoded
    Returns:
      a PEM-encoded byte array
    Throws:
      `IllegalArgumentException` - if the `DEREncodable` cannot be encoded
      `NullPointerException` - if `de` is `null`
    See Also:
      - `withEncryption(char[])`

  - ### withEncryption

    public PEMEncoderPREVIEW 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 `DEREncodable` objects will throw an `IllegalArgumentException`.

    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(DEREncodable, Key, String, AlgorithmParameterSpec, Provider, SecureRandom)`PREVIEW and use the returned object with `encode(DEREncodable)`.
    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`
      `IllegalArgumentException` - if generating the encryption key fails