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, a
ClassCastException 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:
PEMDecoder pd = PEMDecoder.of().withDecryption(password).
withFactory(provider);
byte[] pemData = pd.decode(privKey);