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 Details

    • 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

    • decodeAll

      @NonNull public static List<PEMEncodable> decodeAll(@NonNull String pem, @Nullable char[] passphrase) throws IOException, UnrecoverableKeyException
      Creates a list of PEMEncodables 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:
      a list of PEMEncodable objects
      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

    • readAll

      @NonNull public static List<PEMEncodable> readAll(@NonNull File pemFile) throws IOException, UnrecoverableKeyException
      Creates PEMEncodables by reading a PEM file
      Parameters:
      pemFile - File pointing to the PEM file to read
      Returns:
      A list of PEMEncodable objects.
      Throws:
      IOException - launched if a problem exists reading the PEM information or the File
      UnrecoverableKeyException - in case PEM is passphrase protected

    • readAll

      @NonNull public static List<PEMEncodable> readAll(@NonNull File pemFile, @Nullable char[] passphrase) throws IOException, UnrecoverableKeyException
      Creates a PEMEncodables 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:
      a list of PEMEncodable objects
      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:
      • 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