Class PKIUtils

java.lang.Object
ghidra.net.PKIUtils
public class PKIUtils extends Object
PKIUtils provides supporting utilities for creating and accessing X509 certificate keystore files.

  • Field Details

  • Method Details

    • getTrustManager MODIFIED

      public static X509TrustManager getTrustManager(File caCertsFile) throws GeneralSecurityException, IOException
      removed throws CancelledException
      -static javax.net.ssl.X509TrustManager getTrustManager(java.io.File caCertsFile) throws CancelledException, GeneralSecurityException, IOException
      +static javax.net.ssl.X509TrustManager getTrustManager(java.io.File caCertsFile) throws GeneralSecurityException, IOException
      Establish X509TrustManager for the specified CA certificate storage.
      Parameters:
      caCertsFile - CA certificates storage file
      Returns:
      X509TrustManager
      Throws:
      GeneralSecurityException - if error occured during truststore initialization
      IOException - if file read error occurs
      CancelledException (removed)

    • exportX509Certificates

      public static void exportX509Certificates(Certificate[] certificates, File outFile) throws IOException, CertificateEncodingException
      Export X.509 certificates to the specified outFile.
      Parameters:
      certificates - certificates to be stored
      outFile - output file
      Throws:
      IOException - if error occurs writing to outFile
      CertificateEncodingException - if error occurs while encoding certificate data

    • getCommonName NEW

      public static String getCommonName(X509Certificate cert) throws InvalidNameException
      Returns the Common Name (CN) for an X509 certificate or null if DN does not contain a CN.
      Parameters:
      cert - X509 certificate
      Returns:
      the Common Name (CN) for an X509 certificate or null if DN does not contain a CN
      Throws:
      InvalidNameException - if DN is invalid or contains invalid DN

    • getCommonName NEW

      public static String getCommonName(String distinguishedName) throws InvalidNameException
      Returns the Common Name (CN) for an X509 distinguished name (DN) or null if DN does not contain a CN.
      Parameters:
      distinguishedName - distinguished name (DN)
      Returns:
      the Common Name (CN) for an X509 distinguished name (DN) or null if DN does not contain a CN
      Throws:
      InvalidNameException - if DN is invalid or contains invalid CN

    • saveKeyStore NEW

      public static void saveKeyStore(KeyStore keyStore, File keyFile, char[] protectedPassphrase) throws KeyStoreException, IOException
      Save a keystore
      Parameters:
      keyStore - key store to be saved
      keyFile - file to be written
      protectedPassphrase - protection password
      Throws:
      KeyStoreException - if error occurred while generating keystore
      IOException - if failed to write keystore file

    • createKeyStore

      public static final KeyStore createKeyStore(String alias, String dn, int durationDays, KeyStore.PrivateKeyEntry caEntry, boolean isCA, File keyFile, String keystoreType, Collection<String> subjectAlternativeNames, char[] protectedPassphrase) throws KeyStoreException
      Generate a new X509Certificate with RSA KeyPair and create/update a KeyStore optionally backed by a keyFile.

      Standard usage will include KeyUsage.digitalSignature and KeyUsage.keyEncipherment. For non-CA extended usage will include serverAuth and clientAuth for maximum compatibility.

      Parameters:
      alias - entry alias with keystore
      dn - distinguished name (e.g., "CN=Ghidra Test, O=Ghidra, OU=Test, C=US" )
      durationDays - number of days which generated certificate should remain valid
      caEntry - optional CA private key entry (issuer of new certificate). If null, new certificate will sign itself (self-signed).
      isCA - if true the new certificate will tagged as a CA
      keyFile - optional file to load/store resulting KeyStore (may be null)
      keystoreType - support keystore type (e.g., "JKS", "PKCS12")
      subjectAlternativeNames - an optional list of subject alternative names to be included in certificate (may be null)
      protectedPassphrase - key and keystore protection password
      Returns:
      keystore containing newly generated certification with key pair
      Throws:
      KeyStoreException - if error occurs while updating keystore

    • loadCertificateStore

      public static KeyStore loadCertificateStore(String certsPath) throws IOException, KeyStoreException, NoSuchAlgorithmException, CertificateException
      Load the all certificates from the specified certificate store in a standard X.509 form (e.g., concatenation of Base64 encoded certificates: *.pem, *.crt, *.cer, *.der) or Java JKS (*.jks) form.
      Parameters:
      certsPath - certificate(s) storage file path
      Returns:
      KeyStore containing certificates
      Throws:
      IOException - if failure occurred reading and processing keystore file.
      NoSuchAlgorithmException - if the algorithm used to check the integrity of the keystore cannot be found
      CertificateException - if any of the certificates in the keystore could not be loaded
      KeyStoreException - if a general error occurred opening/processing keystore

    • loadX509PemCertificates NEW

      public static List<X509Certificate> loadX509PemCertificates(File pemFile) throws IOException, CertificateException
      Load all X.509 certificates from an unencrypted PEM file (a concatenation of Base64 encoded certificates). Text surrounding the certificate blocks, such as the certificate details which some tools emit ahead of each one, is ignored.

      Unlike loadCertificateStore(String) this requires the file to be PEM encoded and to contain nothing but complete certificates, as a certificate authority file must (e.g., the PostgreSQL ssl_ca_file) since every entry within it has to be usable: a DER encoded certificate or a keystore yields no certificates rather than being accepted, and a truncated or non-certificate PEM block is an error rather than being skipped.

      Parameters:
      pemFile - PEM certificate file
      Returns:
      the certificates in the order they occur within the file, which is empty if the file contains no PEM block at all
      Throws:
      IOException - if the file cannot be read or a certificate block is truncated
      CertificateException - if a PEM block is not a certificate or cannot be decoded

    • loadX509PemCertificates

      public static List<X509Certificate> loadX509PemCertificates(File pemFile, Consumer<String> unusableBlockConsumer) throws IOException, CertificateException
      Read all X509 certificates contained within a PEM encoded file, optionally tolerating any block which cannot be used.

      Tolerating unusable blocks is appropriate when establishing a trust store, where discarding every valid certificate on account of one defective block would be the greater failure. It is not appropriate when validating a file which the user has supplied for that purpose, where a defect must be reported rather than passed over - such callers use loadX509PemCertificates(File) instead.

      Parameters:
      pemFile - PEM encoded certificate file
      unusableBlockConsumer - if non-null, a description of each unusable PEM block is passed to this consumer and the block is skipped, allowing the remaining certificates to be read. If null, the first unusable block is an error.
      Returns:
      list of X509 certificates read from the file
      Throws:
      IOException - if the file cannot be read
      CertificateException - if a block cannot be used and unusableBlockConsumer is null

    • loadX509CertificateStore

      public static int loadX509CertificateStore(String certsPath, ExceptionalConsumer<X509Certificate, KeyStoreException> certConsumer) throws IOException, CertificateException, KeyStoreException
      Load the all certificates from the specified certificate store in a standard X.509 form (e.g., concatenation of Base64 encoded certificates: *.pem, *.crt, *.cer, *.der)
      Parameters:
      certsPath - certificate(s) storage file path
      certConsumer - consumer callback to be supplied with each certificate
      Returns:
      number of X509 certificates read
      Throws:
      IOException - if failure occurred reading and processing keystore file.
      CertificateException - if any of the certificates in the keystore could not be loaded
      KeyStoreException - thrown by certConsumer

    • getKeyStoreInstance

      public static KeyStore getKeyStoreInstance(String keystorePath, char[] password) throws IOException, KeyStoreException, NoSuchAlgorithmException, CertificateException
      Attempt to load a client/server keystore in a PKCS12 form (*.p12, *.pks, *.pfx) or Java JKS (*.jks) form.
      Parameters:
      keystorePath - JKS or PKCS12 keystore file path
      password - keystore password
      Returns:
      keystore instance
      Throws:
      IOException - if failure occurred reading and processing keystore file or if the given password was incorrect. If the error is due to a wrong password, the cause of the IOException should be an UnrecoverableKeyException
      NoSuchAlgorithmException - if the algorithm used to check the integrity of the keystore cannot be found
      CertificateException - if any of the certificates in the keystore could not be loaded
      KeyStoreException - if a general error occurred opening/processing keystore

    • detectKeyStoreType

      public static String detectKeyStoreType(String keystorePath) throws IOException
      Determine the Java key store type of a file from its leading bytes.

      Only the Java key store forms are identified. A certificate file is not a key store and yields null, which includes a DER encoded certificate: a DER certificate and a PKCS#12 key store cannot be told apart by their leading byte, since both begin with an ASN.1 DER SEQUENCE (0x30). They are distinguished here by the first element within that SEQUENCE, which is an INTEGER version for a PKCS#12 PFX and a nested SEQUENCE (tbsCertificate) for a certificate: 

        PFX         ::= SEQUENCE { version INTEGER {v3(3)}, authSafe ContentInfo, ... }
  Certificate ::= SEQUENCE { tbsCertificate TBSCertificate, ... }  -- itself a SEQUENCE
      Locating that element requires the SEQUENCE length to be decoded, since it may use the DER long form (the Java default cacerts does).

      This remains a determination based upon the leading bytes and not a full parse, so a caller must still be prepared for a key store of the identified type to fail to load.

      Parameters:
      keystorePath - path to the file to be examined
      Returns:
      "JKS" or "PKCS12" if the file is a Java key store of that type, otherwise null (a PEM or DER certificate file among the possibilities)
      Throws:
      IOException - if the file cannot be read

    • logCerts

      public static void logCerts(X509Certificate[] x509Certs)
      Log all X509 certificates contained within array
      Parameters:
      x509Certs - array of certificates

    • formatKeyUsage

      public static String formatKeyUsage(X509Certificate cert)
      Returns the key-usages as sequence of comma-separated names for a specified certificate.
      Parameters:
      cert - x509 certificate
      Returns:
      the key-usages as sequence of comma-separated names for a specified certificate