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 cryptographic objects, such as asymmetric keys, certificates, and certificate revocation lists (CRLs). It is defined in RFC 1421 and RFC 7468. PEM consists of Base64-encoded content enclosed by a type-identifying header and footer.

The decode(String) and decode(InputStream) methods return an instance of a class that matches the PEM type and implements BinaryEncodable^PREVIEW, as follows:

CERTIFICATE: X509Certificate
X509 CRL: X509CRL
PUBLIC KEY: PublicKey
PRIVATE KEY: PrivateKey or KeyPair (if the encoding contains a public key)
ENCRYPTED PRIVATE KEY: EncryptedPrivateKeyInfo
Other types: PEM^PREVIEW

When used with a PEMDecoder instance configured for decryption:

ENCRYPTED PRIVATE KEY: PrivateKey or KeyPair (if the encoding contains a public key)

If the PEM type has no corresponding class, decode(String) and decode(InputStream) will return a PEM object.

The decode(String, Class) and decode(InputStream, Class) methods accept a class parameter specifying the desired BinaryEncodable type. These methods avoid the need for casting and are useful when multiple representations are possible. For example, if the PEM contains both public and private keys, specifying PrivateKey.class returns only the private key. If X509EncodedKeySpec.class is provided, the public key encoding is returned as a X509EncodedKeySpec. To retrieve a PEM^PREVIEW object, use PEM.class. If the specified class does not match the PEM content, a ClassCastException is thrown.

In addition to the types listed above, these methods support the following PEM types and BinaryEncodable classes when specified as parameters:

PUBLIC KEY: X509EncodedKeySpec
PRIVATE KEY: PKCS8EncodedKeySpec
PRIVATE KEY: PublicKey (if the encoding contains a public key)
PRIVATE KEY: X509EncodedKeySpec (if the encoding contains a public key)

When used with a PEMDecoder instance configured for decryption:

ENCRYPTED PRIVATE KEY: PKCS8EncodedKeySpec
ENCRYPTED PRIVATE KEY: PublicKey (if the encoding contains a public key)
ENCRYPTED PRIVATE KEY: X509EncodedKeySpec (if the encoding contains a public key)

A new PEMDecoder instance is created when configured with withFactoriesOf(Provider) or withDecryption(char[]). The withFactoriesOf(Provider) method uses the specified provider when obtaining KeyFactory and CertificateFactory instances used during decoding. The withDecryption(char[]) method configures the decoder to decrypt and decode encrypted private key PEM data using the given password. If decryption fails, a CryptoException^PREVIEW is thrown. If an encrypted PEM is processed by a decoder not configured for decryption, an EncryptedPrivateKeyInfo is returned. A PEMDecoder configured for decryption can also decode unencrypted PEM.

The BinaryEncodable interface may evolve. When using a decode method with switch, always include a default case rather than relying on the classes specified in the permits clause to remain fixed. An exhaustive switch may result in a MatchException.

This class is immutable and thread-safe.

Example: decode a private key:

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

Example: configure decryption and a factory provider:

     PEMDecoder pd = PEMDecoder.of().withDecryption(password).
             withFactoriesOf(provider);
     BinaryEncodable pemData = pd.decode(privKeyPEM);

Implementation Note:

This implementation decodes non-encrypted RSA PRIVATE KEY as PrivateKey, X509 CERTIFICATE and X.509 CERTIFICATE as X509Certificate, and CRL as X509CRL. Other implementations may recognize additional PEM types.

Since:

25

External Specifications

See Also:

Method Summary

Modifier and Type

Method

Description

BinaryEncodable^PREVIEW

decode(InputStream is)

Decodes and returns a BinaryEncodable from the given InputStream.

<S extends BinaryEncodable^PREVIEW> S

decode(InputStream is, Class<S> tClass)

Decodes and returns a BinaryEncodable of the specified class from the given InputStream.

BinaryEncodable^PREVIEW

decode(String str)

Decodes and returns a BinaryEncodable from the given String.

<S extends BinaryEncodable^PREVIEW> S

decode(String str, Class<S> tClass)

Decodes and returns a BinaryEncodable of the specified class from the given PEM string.

static PEMDecoder^PREVIEW

of()

Returns the default PEMDecoder instance.

PEMDecoder^PREVIEW

withDecryption(char[] password)

Returns a copy of this PEMDecoder that decodes and decrypts encrypted private keys using the specified password.

PEMDecoder^PREVIEW

withFactoriesOf(Provider provider)

Returns a copy of this PEMDecoder instance that uses KeyFactory and CertificateFactory implementations from the specified Provider to produce cryptographic objects.

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 PEMDecoder^PREVIEW of()
  
  Returns the default PEMDecoder instance.
  
  Returns:
  
  the default PEMDecoder
- decode
  
  public BinaryEncodable^PREVIEW decode(String str)
  
  Decodes and returns a BinaryEncodable 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.
  A BinaryEncodable is returned that best represents the decoded content. If the PEM type is not supported, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.
  The input is interpreted as UTF-8.
  
  Parameters:
  
  str - a String containing PEM data
  
  Returns:
  
  a BinaryEncodable
  
  Throws:
  
  IllegalArgumentException - if decoding fails or no PEM data is found
  
  NullPointerException - if str is null
  
  CryptoException^PREVIEW - if an error occurs during decryption
  
  Since:
  
  27
- decode
  
  public BinaryEncodable^PREVIEW decode(InputStream is) throws IOException
  
  Decodes and returns a BinaryEncodable from the given InputStream.
  This method reads from the InputStream until the end of a PEM footer or the end of the stream. If an I/O error occurs, the stream position may become inconsistent. Further decoding operations on the same InputStream are not recommended.
  A BinaryEncodable is returned that best represents the decoded content. If the PEM type is not supported, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.
  If no PEM data is found, an EOFException is thrown.
  
  Parameters:
  
  is - InputStream containing PEM data
  
  Returns:
  
  a BinaryEncodable
  
  Throws:
  
  IOException - if an I/O error occurs or PEM syntax is invalid
  
  EOFException - if no PEM data is found or the stream ends unexpectedly
  
  IllegalArgumentException - if decoding fails
  
  NullPointerException - if InputStream is null
  
  CryptoException^PREVIEW - if an error occurs during decryption
  
  Since:
  
  27
- decode
  
  public <S extends BinaryEncodable^PREVIEW> S decode(String str, Class<S> tClass)
  
  Decodes and returns a BinaryEncodable of the specified class from the given PEM string.
  tClass must 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 tClass is PEM.class, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.
  The input is interpreted as UTF-8.
  
  Type Parameters:
  
  S - class type parameter that extends BinaryEncodable
  
  Parameters:
  
  str - the String containing PEM data
  
  tClass - the returned object class that extends or implements BinaryEncodable
  
  Returns:
  
  a BinaryEncodable specified by tClass
  
  Throws:
  
  IllegalArgumentException - on error in decoding or no PEM data found
  
  ClassCastException - if tClass does not represent the PEM type
  
  NullPointerException - if any input values are null
  
  CryptoException^PREVIEW - if an error occurs during decryption
  
  Since:
  
  27
- decode
  public <S extends BinaryEncodable^PREVIEW> S decode(InputStream is, Class<S> tClass) throws IOException
  
  Decodes and returns a BinaryEncodable of the specified class from the given InputStream.
  tClass must be an appropriate class for the PEM type.
  This method reads from the InputStream until the end of a PEM footer or the end of the stream. If an I/O error occurs, the stream position may become inconsistent. Further decoding operations on the same InputStream are not recommended.
  If tClass is PEM.class, a PEM object is returned containing the type identifier, Base64-encoded data, and any leading data preceding the PEM header. For BinaryEncodable types other than PEM, leading data is ignored.
  If no PEM data is found, an EOFException is thrown.
  
  Type Parameters:
  
  S - class type parameter that extends BinaryEncodable
  
  Parameters:
  
  is - an InputStream containing PEM data
  
  tClass - the returned object class that extends or implements BinaryEncodable
  
  Returns:
  
  a BinaryEncodable of type tClass
  
  Throws:
  
  IOException - if an I/O error occurs or PEM syntax is invalid
  
  EOFException - if no PEM data is found or the stream ends unexpectedly
  
  IllegalArgumentException - if decoding fails
  
  ClassCastException - if tClass does not represent the PEM type
  
  NullPointerException - if any input values are null
  
  CryptoException^PREVIEW - if an error occurs during decryption
  
  Since:
  
  27
  
  See Also:
  
  decode(InputStream)
  
  decode(String, Class)
- withFactoriesOf
  
  public PEMDecoder^PREVIEW withFactoriesOf(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.
  
  Parameters:
  
  provider - the factory Provider
  
  Returns:
  
  a new PEMDecoder instance configured with the Provider
  
  Throws:
  
  NullPointerException - if provider is null
  
  Since:
  
  27
- withDecryption
  
  public PEMDecoder^PREVIEW withDecryption(char[] password)
  
  Returns a copy of this PEMDecoder that decodes and decrypts encrypted private keys using the specified password. Unencrypted PEM can also be decoded by the returned instance.
  
  Parameters:
  
  password - the password to decrypt the encrypted PEM data. This array is cloned and stored in the new instance.
  
  Returns:
  
  a new PEMDecoder instance configured for decryption
  
  Throws:
  
  NullPointerException - if password is null

Class PEMDecoder

Method Summary

Methods declared in class Object

Method Details

of

decode

decode

decode

decode

withFactoriesOf

withDecryption