/**
 * PEMEncoder is an immutable Privacy-Enhanced Mail (PEM) encoding class.
 * PEM is a textual encoding used for storing and transferring security
 * objects, such as asymmetric keys, certificates, and certificate revocation
 * lists (CRL). Defined in RFC 1421 and RFC 7468, PEM consists of a
 * Base64-formatted binary encoding surrounded by a type identifying header
 * and footer.
 * <p>
 * Encoding may be performed on objects that implement {@link DEREncodable}.
 * <p>
 * Encrypted private key PEM data can be built by calling the encode methods
 * on a PEMEncoder instance returned by {@link #withEncryption(char[])} or
 * by passing an {@link EncryptedPrivateKeyInfo} object into the encode methods.
 * <p>
 * PKCS8 v2.0 allows OneAsymmetric encoding, which is a private and public
 * key in the same PEM.  This is supported by using the {@link KeyPair} class
 * with the encode methods.
 * <p>
 * PEMEncoder supports the follow types:
 * <pre>
 *     PRIVATE KEY, PUBLIC KEY, CERTIFICATE, CRL, and ENCRYPTED PRIVATE KEY.
 * </pre>
 *
 * @apiNote
 * Here is an example of encoding a PrivateKey object:
 * <pre>
 *     PEMEncoder pe = PEMEncoder.of();
 *     byte[] pemData = pe.encode(privKey);
 * </pre>
 *
 * @since 24
 */


@PreviewFeature(feature = PreviewFeature.Feature.PEM_API)
public final class PEMEncoder 


    /**
     * Returns an instance of PEMEncoder.
     *
     * @return PEMEncoder instance
     */
    static public PEMEncoder of() {


    /**
     * Encoded a given {@code DEREncodable} and return the PEM encoding in a
     * String
     *
     * @param so a cryptographic object to be PEM encoded that implements
     *           DEREncodable.
     * @return PEM encoding in a String
     * @throws IllegalArgumentException when the passed object returns a null
     * binary encoding. An exception is thrown when PEMEncoder is
     * configured for encryption while encoding a DEREncodable that does
     * not support encryption.
     * @throws NullPointerException when object passed is null.
     * @see #withEncryption(char[])
     */
    public String encodeToString(DEREncodable so) {

    /**
     * Encoded a given {@code DEREncodable} into PEM.
     *
     * @param so the object that implements DEREncodable.
     * @return a PEM encoded byte[] of the given DEREncodable.
     * @throws IllegalArgumentException when the passed object returns a null
     * binary encoding. An exception is thrown when PEMEncoder is
     * configured for encryption while encoding a DEREncodable that does
     * not support encryption.
     * @throws NullPointerException when object passed is null.
     * @see #withEncryption(char[])
     */
    public byte[] encode(DEREncodable so) {

    /**
     * Returns a new immutable PEMEncoder instance configured to the default
     * encryption algorithm and a given password.
     *
     * <p> Only {@link PrivateKey} will be encrypted with this newly configured
     * instance.  Other {@link DEREncodable} classes that do not support
     * encrypted PEM will cause encode() to throw an IllegalArgumentException.
     *
     * <p> Default algorithm defined by Security Property {@code
     * jdk.epkcs8.defaultAlgorithm}.  To configure all the encryption options
     * see {@link EncryptedPrivateKeyInfo#encryptKey(PrivateKey, char[], String,
     * AlgorithmParameterSpec, Provider)} and use the returned object with
     * {@link #encode(DEREncodable)}.
     *
     * @param password the password
     * @return a new PEMEncoder
     * @throws NullPointerException if password is null.
     */
    public PEMEncoder withEncryption(char[] password) {