Class PEMDecoder

java.lang.Object
java.security.PEMDecoder
public final class PEMDecoder extends Object
PEMDecoder is a preview API of the Java platform.
Programs can only use PEMDecoder when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
PEMDecoder implements a decoder 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 (CRLs). 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.

The decode(String) and decode(InputStream) methods return an instance of a class that matches the data type and implements DEREncodablePREVIEW.

The following lists the supported PEM types and the DEREncodable types that each are decoded as:

  • CERTIFICATE : X509Certificate
  • X509 CRL : X509CRL
  • PUBLIC KEY : PublicKey
  • PUBLIC KEY : X509EncodedKeySpec (Only supported when passed as a Class parameter)
  • PRIVATE KEY : PrivateKey
  • PRIVATE KEY : PKCS8EncodedKeySpec (Only supported when passed as a Class parameter)
  • PRIVATE KEY : KeyPair (if the encoding also contains a public key)
  • ENCRYPTED PRIVATE KEY : EncryptedPrivateKeyInfo
  • ENCRYPTED PRIVATE KEY : PrivateKey (if configured with Decryption)
  • Other types : PEMRecord

The PublicKey and PrivateKey types, an algorithm specific subclass is returned if the underlying algorithm is supported. For example an ECPublicKey and ECPrivateKey for Elliptic Curve keys.

If the PEM type does not have a corresponding class, decode(String) and decode(InputStream) will return a PEMRecordPREVIEW.

The decode(String, Class) and decode(InputStream, Class) methods take a class parameter which determines the type of DEREncodable that is returned. These methods are useful when extracting or changing the return class. For example, if the PEM contains both public and private keys, the class parameter can specify which to return. Use PrivateKey.class to return only the private key. If the class parameter is set to X509EncodedKeySpec.class, the public key will be returned in that format. Any type of PEM data can be decoded into a PEMRecord by specifying PEMRecord.class. If the class parameter doesn't match the PEM content, an IllegalArgumentException will be thrown.

A new PEMDecoder instance is created when configured with withFactory(Provider) and/or withDecryption(char[]). withFactory(Provider) configures the decoder to use only KeyFactory and CertificateFactory instances from the given Provider. withDecryption(char[]) configures the decoder to decrypt all encrypted private key PEM data using the given password. Configuring an instance for decryption does not prevent decoding with unencrypted PEM. Any encrypted PEM that fails decryption will throw a RuntimeException. When an encrypted private key PEM is used with a decoder not configured for decryption, an EncryptedPrivateKeyInfo object is returned.

This class is immutable and thread-safe.

Here is an example of decoding a PrivateKey object: 

    PEMDecoder pd = PEMDecoder.of();
    PrivateKey priKey = pd.decode(priKeyPEM, PrivateKey.class);

Here is an example of a PEMDecoder configured with decryption and a factory provider: 

    PEMEncoder pe = PEMDecoder.of().withDecryption(password).
        withFactory(provider);
    byte[] pemData = pe.decode(privKey);
Implementation Note:
An implementation may support other PEM types and DEREncodables. This implementation additionally supports PEM types: X509 CERTIFICATE, X.509 CERTIFICATE, CRL, and RSA PRIVATE KEY.
Since:
25
External Specifications
See Also:

  • Method Details

    • of

      public static PEMDecoderPREVIEW of()
      Returns an instance of PEMDecoder.
      Returns:
      a PEMDecoder instance

    • decode

      public DEREncodablePREVIEW decode(String str)
      Decodes and returns a DEREncodablePREVIEW from the given String.

      This method reads the String until PEM data is found or the end of the String is reached. If no PEM data is found, an IllegalArgumentException is thrown.

      This method returns a Java API cryptographic object, such as a PrivateKey, if the PEM type is supported. Any non-PEM data preceding the PEM header is ignored by the decoder. Otherwise, a PEMRecordPREVIEW will be returned containing the type identifier and Base64-encoded data. Any non-PEM data preceding the PEM header will be stored in leadingData.

      Input consumed by this method is read in as UTF-8.

      Parameters:
      str - a String containing PEM data
      Returns:
      a DEREncodable
      Throws:
      IllegalArgumentException - on error in decoding or no PEM data found
      NullPointerException - when str is null

    • decode

      public DEREncodablePREVIEW decode(InputStream is) throws IOException
      Decodes and returns a DEREncodablePREVIEW from the given InputStream.

      This method reads from the InputStream until the end of the PEM footer or the end of the stream. If an I/O error occurs, the read position in the stream may become inconsistent. It is recommended to perform no further decoding operations on the InputStream.

      This method returns a Java API cryptographic object, such as a PrivateKey, if the PEM type is supported. Any non-PEM data preceding the PEM header is ignored by the decoder. Otherwise, a PEMRecordPREVIEW will be returned containing the type identifier and Base64-encoded data. Any non-PEM data preceding the PEM header will be stored in leadingData.

      If no PEM data is found, an IllegalArgumentException is thrown.

      Parameters:
      is - InputStream containing PEM data
      Returns:
      a DEREncodable
      Throws:
      IOException - on IO or PEM syntax error where the InputStream did not complete decoding.
      EOFException - at the end of the InputStream
      IllegalArgumentException - on error in decoding
      NullPointerException - when is is null

    • decode

      public <S extends DEREncodablePREVIEW> S decode(String str, Class<S> tClass)
      Decodes and returns a DEREncodable of the specified class from the given PEM string. tClass must extend DEREncodablePREVIEW and be an appropriate class for the PEM type.

      This method reads the String until PEM data is found or the end of the String is reached. If no PEM data is found, an IllegalArgumentException is thrown.

      If the class parameter is PEMRecord.class, a PEMRecord is returned containing the type identifier and Base64 encoding. Any non-PEM data preceding the PEM header will be stored in leadingData. Other class parameters will not return preceding non-PEM data.

      Input consumed by this method is read in as UTF-8.

      Type Parameters:
      S - Class type parameter that extends DEREncodable
      Parameters:
      str - the String containing PEM data
      tClass - the returned object class that implements DEREncodable
      Returns:
      a DEREncodable specified by tClass
      Throws:
      IllegalArgumentException - on error in decoding or no PEM data found
      ClassCastException - if tClass is invalid for the PEM type
      NullPointerException - when any input values are null

    • decode

      public <S extends DEREncodablePREVIEW> S decode(InputStream is, Class<S> tClass) throws IOException
      Decodes and returns the specified class for the given InputStream. The class must extend DEREncodablePREVIEW and be an appropriate class for the PEM type.

      This method reads from the InputStream until the end of the PEM footer or the end of the stream. If an I/O error occurs, the read position in the stream may become inconsistent. It is recommended to perform no further decoding operations on the InputStream.

      If the class parameter is PEMRecord.class, a PEMRecord is returned containing the type identifier and Base64 encoding. Any non-PEM data preceding the PEM header will be stored in leadingData. Other class parameters will not return preceding non-PEM data.

      If no PEM data is found, an IllegalArgumentException is thrown.

      Type Parameters:
      S - Class type parameter that extends DEREncodable.
      Parameters:
      is - an InputStream containing PEM data
      tClass - the returned object class that implements DEREncodable.
      Returns:
      a DEREncodable typecast to tClass
      Throws:
      IOException - on IO or PEM syntax error where the InputStream did not complete decoding.
      EOFException - at the end of the InputStream
      IllegalArgumentException - on error in decoding
      ClassCastException - if tClass is invalid for the PEM type
      NullPointerException - when any input values are null
      See Also:

    • withFactory

      public PEMDecoderPREVIEW withFactory(Provider provider)
      Returns a copy of this PEMDecoder instance that uses KeyFactory and CertificateFactory implementations from the specified Provider to produce cryptographic objects. Any errors using the Provider will occur during decoding.

      If provider is null, a new instance is returned with the default provider configuration.

      Parameters:
      provider - the factory provider
      Returns:
      a new PEMEncoder instance configured to the Provider.
      Throws:
      NullPointerException - if provider is null

    • withDecryption

      public PEMDecoderPREVIEW withDecryption(char[] password)
      Returns a copy of this PEMDecoder that decodes and decrypts encrypted private keys using the specified password. Non-encrypted PEM can still be decoded from this instance.
      Parameters:
      password - the password to decrypt encrypted PEM data. This array is cloned and stored in the new instance.
      Returns:
      a new PEMEncoder instance configured for decryption
      Throws:
      NullPointerException - if password is null