Package jenkins.bouncycastle.api

Class PEMEncodable

java.lang.Object

jenkins.bouncycastle.api.PEMEncodable

public final class PEMEncodable
extends Object

A class that provides an API to manage PEM format, providing additional methods to handle Keys, Certificates, Fingerprints, etc The supported algorithms will depend on the underlying version of BouncyCastle

Since:

1.0

Method Summary

Modifier and Type	Method	Description
static PEMEncodable	create(Certificate certificate)	Creates a PEMEncodable from a Certificate object
static PEMEncodable	create(Key key)	Creates a PEMEncodable from a Key object
static PEMEncodable	create(KeyPair keyPair)	Creates a PEMEncodable from a KeyPair object
static PEMEncodable	decode(String pem)	Creates a PEMEncodable by decoding PEM formated data from a String
static PEMEncodable	decode(String pem, char[] passphrase)	Creates a PEMEncodable by decoding PEM formated data from a String
String	encode()	Encodes the current stored information in PEM format and returns it as a String
static byte[]	getKeyDigest(Key k, String algorithm)	Generates an digest from a Key object in the specified digest format.
static byte[]	getKeyDigestMD5(Key k)	Generates an MD5 digest from a Key object
static byte[]	getKeyDigestSHA1(Key k)	Generates an SHA1 digest from a Key object
String	getPrivateKeyFingerprint()	Obtains the fingerprint of the private key in the "ab:cd:ef:...:12" format, which basically is an SHA1 digest from the key, encoded in hex format.
String	getPublicKeyFingerprint()	Obtains the fingerprint of the public key in the "ab:cd:ef:...:12" format, which basically is an MD5 digest from the key, encoded in hex format.
Object	getRawObject()	Obtains raw JCA or BouncyCastle Object from the read PEM.
static PEMEncodable	read(File pemFile)	Creates a PEMEncodable by reading a PEM file
static PEMEncodable	read(File pemFile, char[] passphrase)	Creates a PEMEncodable by reading a PEM file
Certificate	toCertificate()	Obtain Certificate object from the read PEM.
KeyPair	toKeyPair()	Obtain KeyPair object with the public and private key from the decoded PEM.
PrivateKey	toPrivateKey()	Obtain PrivateKey object from the read PEM.
PublicKey	toPublicKey()	Obtain PublicKey object from the read PEM.
void	write(File pemFile)	Writes the current stored information in PEM formated File

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

@NonNull
public static PEMEncodable create(@NonNull
                                  Key key)

Creates a PEMEncodable from a Key object

Parameters:

key - Key object with the key

Returns:

PEMEncodable object

create

@NonNull
public static PEMEncodable create(@NonNull
                                  KeyPair keyPair)

Creates a PEMEncodable from a KeyPair object

Parameters:

keyPair - KeyPair object with the key pair

Returns:

PEMEncodable object

create

@NonNull
public static PEMEncodable create(@NonNull
                                  Certificate certificate)

Creates a PEMEncodable from a Certificate object

Parameters:

certificate - Certificate object with the certificate

Returns:

PEMEncodable object

decode

@NonNull
public static PEMEncodable decode(@NonNull
                                  String pem)
                           throws IOException,
                                  UnrecoverableKeyException

Creates a PEMEncodable by decoding PEM formated data from a String

Parameters:

pem - String with the PEM data

Returns:

PEMEncodable object

Throws:

IOException - launched if a problem exists reading the PEM information

UnrecoverableKeyException - in case PEM is passphrase protected and none or wrong is provided

decode

@NonNull
public static PEMEncodable decode(@NonNull
                                  String pem,
                                  @Nullable
                                  char[] passphrase)
                           throws IOException,
                                  UnrecoverableKeyException

Creates a PEMEncodable by decoding PEM formated data from a String

Parameters:

pem - String with the PEM data

passphrase - passphrase for the encrypted PEM data. null if PEM data is not passphrase protected. The caller is responsible for zeroing out the char[] after use to ensure the password does not stay in memory, e.g. with Arrays.fill(passphrase, (char)0)

Returns:

PEMEncodable object

Throws:

IOException - launched if a problem exists reading the PEM information

UnrecoverableKeyException - in case PEM is passphrase protected and none or wrong is provided

encode

@NonNull
public String encode()
              throws IOException

Encodes the current stored information in PEM format and returns it as a String

Returns:

PEM encoded data

Throws:

IOException - launched if a problem exists generating the PEM information

read

@NonNull
public static PEMEncodable read(@NonNull
                                File pemFile)
                         throws IOException,
                                UnrecoverableKeyException

Creates a PEMEncodable by reading a PEM file

Parameters:

pemFile - File pointing to the PEM file to read

Returns:

PEMEncodable object

Throws:

IOException - launched if a problem exists reading the PEM information or the File

UnrecoverableKeyException - in case PEM is passphrase protected and none or wrong is provided

read

@NonNull
public static PEMEncodable read(@NonNull
                                File pemFile,
                                @Nullable
                                char[] passphrase)
                         throws IOException,
                                UnrecoverableKeyException

Creates a PEMEncodable by reading a PEM file

Parameters:

pemFile - File pointing to the PEM file to read

passphrase - passphrase for the encrypted PEM data. null if PEM data is not passphrase protected. The caller is responsible for zeroing out the char[] after use to ensure the password does not stay in memory, e.g. with Arrays.fill(passphrase, (char)0)

Returns:

PEMEncodable object

Throws:

IOException - launched if a problem exists reading the PEM information or the File

UnrecoverableKeyException - in case PEM is passphrase protected and none or wrong is provided

write

public void write(@NonNull
                  File pemFile)
           throws IOException

Writes the current stored information in PEM formated File

Parameters:

pemFile - PEM File to read

Throws:

IOException - launched if a problem exists generating the PEM information or writing the File

toKeyPair

@CheckForNull
public KeyPair toKeyPair()

Obtain KeyPair object with the public and private key from the decoded PEM. No conversion is performed, the read PEM must contain private and public key in order to obtain a KeyPair object, null will be returned in all the other cases.

Returns:

KeyPair object with public and private keys or null if the read PEM didn't contain private and public keys.

toPublicKey

@CheckForNull
public PublicKey toPublicKey()

Obtain PublicKey object from the read PEM. If the PEM data contained other object type like KeyPair or Certificate, the public key will be extracted from them.

Returns:

PublicKey with the public key, null if a public key could not be obtained from the current data

toCertificate

@CheckForNull
public Certificate toCertificate()

Obtain Certificate object from the read PEM.

Returns:

Certificate with the certificate, null if a certificate could not be obtained from the current data

toPrivateKey

@CheckForNull
public PrivateKey toPrivateKey()

Obtain PrivateKey object from the read PEM. If the PEM data contained other object type like KeyPair, the private key will be extracted from them.

Returns:

PrivateKey with the private key, null if a private key could not be obtained from the current data

getRawObject

@CheckForNull
public Object getRawObject()

Obtains raw JCA or BouncyCastle Object from the read PEM. Depending on the PEM nature or the object passed to the PEMEncodable(Object pemObject), the returned object can be one of the following (not exhaustive list) and any classes that inherit from them:

• JCA
  • Certificate
  • CRL
  • KeyPair
  • PublicKey
  • PrivateKey

• Bouncy Castle
  • ContentInfo
  • ECNamedCurveParameterSpec
  • PKCS10CertificationRequest
  • X509CertificateObject
  • X509V2AttributeCertificate

Returns:

Object read from the PEM

getPrivateKeyFingerprint

@CheckForNull
public String getPrivateKeyFingerprint()

Obtains the fingerprint of the private key in the "ab:cd:ef:...:12" format, which basically is an SHA1 digest from the key, encoded in hex format.

Returns:

private key fingerprint in hex format "ab:cd:ef:...:12", null if the private key could not be obtained from the current PEM data.

getPublicKeyFingerprint

@CheckForNull
public String getPublicKeyFingerprint()

Obtains the fingerprint of the public key in the "ab:cd:ef:...:12" format, which basically is an MD5 digest from the key, encoded in hex format.

Returns:

public key fingerprint in hex format "ab:cd:ef:...:12", null if the public key could not be obtained from the current PEM data.

getKeyDigestSHA1

@NonNull
public static byte[] getKeyDigestSHA1(@NonNull
                                      Key k)

Generates an SHA1 digest from a Key object

Parameters:

k - the key to generate the digest from

Returns:

the generated digest

getKeyDigestMD5

@NonNull
public static byte[] getKeyDigestMD5(@NonNull
                                     Key k)

Generates an MD5 digest from a Key object

Parameters:

k - the key to generate the digest from

Returns:

the generated digest

getKeyDigest

@NonNull
public static byte[] getKeyDigest(@NonNull
                                  Key k,
                                  @NonNull
                                  String algorithm)
                           throws NoSuchAlgorithmException

Generates an digest from a Key object in the specified digest format. The supported digest formats will depend on the JVM API.

Parameters:

k - key to generate the digest from

algorithm - digest format

Returns:

the generated digest

Throws:

NoSuchAlgorithmException - when provided digest algorithm is not available