# 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 `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 `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 `PEMRecord`PREVIEW, 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
  - RFC 1421: Privacy Enhancement for Internet Electronic Mail
  - RFC 7468: Textual Encodings of PKIX, PKCS, and CMS Structures
See Also:
  - `PEMDecoder`PREVIEW
  - `PEMRecord`PREVIEW
  - `EncryptedPrivateKeyInfo`

- ## 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`

- ## 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 the PEM encoding in a 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 new `PEMEncoder` instance configured for encryption with the default algorithm and a given password.

    Only `PrivateKey` objects can be encrypted with this newly configured instance. Encoding other `DEREncodable`PREVIEW objects will throw an `IllegalArgumentException`.

    Implementation Note:
      The default password-based encryption algorithm is defined by the `jdk.epkcs8.defaultAlgorithm` security property and uses the default encryption parameters of the provider that is selected. For greater flexibility with encryption options and parameters, use `EncryptedPrivateKeyInfo.encryptKey(PrivateKey, 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` - when password is `null`