Package eu.emi.security.authn.x509.impl

Class CertificateUtils

java.lang.Object
eu.emi.security.authn.x509.impl.CertificateUtils
public class CertificateUtils extends Object
Utility class with methods simplifying typical certificate related operations.
Author:
K. Benedyczak, J. Hahkala

  • Field Details

  • Constructor Details

    • CertificateUtils

      public CertificateUtils()

  • Method Details

    • configureSecProvider

      public static void configureSecProvider()
      Configures security providers which are used by the library. Can be called multiple times (subsequent calls won't have any effect).

      This method must be called before any other usage of the code from canl API.

    • convertToX509Chain

      public static X509Certificate[] convertToX509Chain(Certificate[] chain) throws ClassCastException
      Performs a trivial conversion by use of casting of a Certificate array into X509Certificate array
      Parameters:
      chain - to convert
      Returns:
      converted chain
      Throws:
      ClassCastException - if at least one entry in the source chain is not an X509Certificate

    • format

      public static String format(X509Certificate cert, FormatMode mode)
      Produces a human readable text representation of the provided certificate. It uses X509Formatter internally.
      Parameters:
      cert - input certificate
      mode - controls how detailed the string representation should be
      Returns:
      the text representation

    • format

      public static String format(X509Certificate[] certChain, FormatMode mode)
      Produces a human readable text representation of the provided certificate chain. It uses X509Formatter internally.
      Parameters:
      certChain - input certificates
      mode - controls how detailed the string representation should be
      Returns:
      the text representation

    • loadCertificate

      public static X509Certificate loadCertificate(InputStream is, CertificateUtils.Encoding format) throws IOException
      Loads a single certificate from the provided input stream. The stream is always closed afterwards.
      Parameters:
      is - input stream to read encoded certificate from
      format - encoding type
      Returns:
      loaded certificate
      Throws:
      IOException - if certificate can not be read or parsed

    • loadPrivateKey

      public static PrivateKey loadPrivateKey(InputStream is, CertificateUtils.Encoding format, char[] password) throws IOException
      Loads a private key from the provided input stream. The input stream must be encoded in the PKCS8 format (PEM or DER). Additionally in case of PEM encoding the legacy OpenSSL format for storing private keys is supported. Such PEM header names has algorithm {RSA|DSA|EC} placed before the PRIVATE KEY string.

      Currently supported key encryption algorithms are DES and 3 DES. RC2 is unsupported.

      NOTE: currently it is unsupported to load DER private keys which were encoded with openssl legacy encoding (e.g. with @verbatim openssl rsa -outform der ... @endverbatim). PEM files in openssl legacy encoding are supported.

      Parameters:
      is - input stream to read encoded key from
      format - encoding type (PEM or DER)
      password - key's encryption password (can be null is file is not encrypted)
      Returns:
      loaded key
      Throws:
      IOException - if key can not be read or parsed

    • loadPEMPrivateKey

      public static PrivateKey loadPEMPrivateKey(InputStream is, PasswordSupplier pf) throws IOException
      Loads a private key from the provided input stream. The input stream must be encoded in the PEM format. This method is a special purpose version of the loadPrivateKey(InputStream, Encoding, char[]). It allows to provide PasswordSupplier instead of the actual password. The PasswordSupplier implementation will be used only if the source is encrypted.

      All other limitations and features are as in the loadPrivateKey(InputStream, Encoding, char[]) method.

      Parameters:
      is - input stream to read encoded key from
      pf - password finder used to discover key's encryption password. It is used only if the password is actually needed.
      Returns:
      loaded key
      Throws:
      IOException - if key can not be read or parsed

    • loadCertificates

      public static X509Certificate[] loadCertificates(InputStream is, CertificateUtils.Encoding format) throws IOException
      Loads a set of (possibly unrelated to each other) certificates from the provided input stream. The input stream is always closed afterwards.
      Parameters:
      is - input stream to read encoded certificates from
      format - encoding type
      Returns:
      loaded certificates array
      Throws:
      IOException - if certificates can not be read or parsed

    • loadCertificateChain

      public static X509Certificate[] loadCertificateChain(InputStream is, CertificateUtils.Encoding format) throws IOException
      Loads a chain of certificates from the provided input stream. The input stream is always closed afterwards.
      Parameters:
      is - input stream to read encoded certificates from
      format - encoding type
      Returns:
      loaded certificates array
      Throws:
      IOException - if certificates can not be read or parsed

    • loadPEMKeystore

      public static KeyStore loadPEMKeystore(InputStream is, char[] password, char[] ksPassword) throws IOException
      Loads certificates and private keys from the PEM input stream (usually from file). Order of entries is not relevant. However it is assumed that the input contains:
      1. one private key K,
      2. one certificate C corresponding to the private key K,
      3. zero or more certificates that if present form a chain of the certificate C.
      If more then one certificate is found then this method tries to sort them to form a consistent chain (inability to do so is thrown as an exception) and assumes that the last certificate in chain is the user's certificate corresponding to the private key.
      Parameters:
      is - input stream to read from
      password - private key's encryption password or null if key is not encrypted.
      ksPassword - password which is used to encrypt the private key in the keystore. Can not be null.
      Returns:
      KeyStore with one private key typed entry, with alias DEFAULT_KEYSTORE_ALIAS of the JKS type. If password is != null then it is also used to crypt the key in the keystore. If it is null then #
      Throws:
      IOException - if input can not be read or parsed

    • loadPEMKeystore

      public static KeyStore loadPEMKeystore(InputStream is, PasswordSupplier pf, char[] ksPassword) throws IOException
      As loadPEMKeystore(InputStream, char[], char[]) but this version allows for providing input key's encryption password only when needed. Input stream is always closed afterwards.
      Parameters:
      is - input stream to read from
      pf - implementation will be used to get the password needed to decrypt the private key from the PEM keystore. Won't be used if the key happens to be unencrypted.
      ksPassword - password which is used to encrypt the private key in the keystore. Can not be null.
      Returns:
      KeyStore with one private key typed entry, with alias DEFAULT_KEYSTORE_ALIAS of the JKS type. If password is != null then it is also used to crypt the key in the keystore. If it is null then #
      Throws:
      IOException - if input can not be read or parsed

    • saveCertificate

      public static void saveCertificate(OutputStream os, X509Certificate cert, CertificateUtils.Encoding format) throws IOException
      Saves the provided certificate to the output file, using the requested encoding. WARNING The output stream IS NOT closed afterwards. This is on purpose, so it is possible to write additional output.
      Parameters:
      os - where to write the encoded certificate to
      cert - certificate to save
      format - format to use
      Throws:
      IOException - if the data can not be written

    • savePrivateKey

      public static void savePrivateKey(OutputStream os, PrivateKey pk, CertificateUtils.Encoding format, String encryptionAlg, char[] encryptionPassword) throws IOException, IllegalArgumentException
      As savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) with the last argument equal to false
      Parameters:
      os - where to write the encoded key to
      pk - key to save
      format - format to use
      encryptionAlg - encryption algorithm to be used. See savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) documentation for details about allowed values.
      encryptionPassword - encryption password to be used.
      Throws:
      IOException - if the data can not be written
      IllegalArgumentException - if encryptionAlg is unsupported

    • savePrivateKey

      public static void savePrivateKey(OutputStream os, PrivateKey pk, CertificateUtils.Encoding format, String encryptionAlg, char[] encryptionPassword, boolean opensslLegacyFormat) throws IOException, IllegalArgumentException
      Saves the provided private key to the output file, using the requested encoding. Allows for using PKCS #8 or the legacy openssl PKCS #1 encoding. WARNING The output stream IS NOT closed afterwards. This is on purpose, so it is possible to write additional output.
      Parameters:
      os - where to write the encoded key to
      pk - key to save
      format - format to use
      encryptionAlg - encryption algorithm to be used. Use null if output must not be encrypted. For PKCS8 output see JceOpenSSLPKCS8EncryptorBuilder constants for available names. For the legacy openssl format, one can use the algorithm names composed from 3 parts glued with hyphen. The first part determines algorithm, one of AES, DES, BF and RC2. The second part determines key bits and is used for AES and optionally for RC2. For AES it is possible to use values 128, 192 and 256. For RC2 64, 40 can be used or nothing - then value 128 is used. The last part determines the block mode: CFB, ECB, OFB, EDE and CBC. Additionally EDE3 can be used in combination with DES to use DES3 with EDE. Examples: AES-192-ECB or DES-EDE3.
      encryptionPassword - encryption password to be used.
      opensslLegacyFormat - if true the key is saved in the legacy openssl format. Otherwise a PKCS #8 is used.
      Throws:
      IOException - if the data can not be written
      IllegalArgumentException - if encryptionAlg is unsupported
      Since:
      1.1.0

    • saveCertificateChain

      public static void saveCertificateChain(OutputStream os, X509Certificate[] chain, CertificateUtils.Encoding format) throws IOException
      Saves the provided certificate chain to the output stream, using the requested encoding. WARNING The output stream IS NOT closed afterwards. This is on purpose, so it is possible to write additional output.
      Parameters:
      os - where to write the encoded certificate to
      chain - certificate chain to save
      format - format to use
      Throws:
      IOException - if the data can not be written

    • savePEMKeystore

      public static void savePEMKeystore(OutputStream os, KeyStore ks, String alias, String encryptionAlg, char[] keyPassword, char[] encryptionPassword) throws IOException, KeyStoreException, IllegalArgumentException, UnrecoverableKeyException, NoSuchAlgorithmException
      See savePEMKeystore(OutputStream, KeyStore, String, String, char[], char[], boolean) with the last argument equal to false.
      Parameters:
      os - where to write the encoded data to
      ks - keystore to read from
      alias - alias of the private key entry in the keystore
      encryptionAlg - encryption algorithm to be used. See savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) documentation for details about allowed values.
      keyPassword - password of the private key in the keystore
      encryptionPassword - encryption password to be used.
      Throws:
      IOException - if the data can not be written
      KeyStoreException - if the provided alias does not exist in the keystore or if it does not correspond to the private key entry.
      IllegalArgumentException - if encriptionAlg is unsupported or alias is wrong
      NoSuchAlgorithmException - if algorithm is not known
      UnrecoverableKeyException - if key can not be recovered

    • savePEMKeystore

      public static void savePEMKeystore(OutputStream os, X509Credential toSave, String encryptionAlg, char[] encryptionPassword, boolean opensslLegacyFormat) throws IOException, KeyStoreException, IllegalArgumentException, UnrecoverableKeyException, NoSuchAlgorithmException
      See savePEMKeystore(OutputStream, KeyStore, String, String, char[], char[], boolean). This method allows for using the CANL X509Credential instead of low level KeyStore as argument.
      Parameters:
      os - where to write the encoded data to
      toSave - CANL X509Credential to read from
      encryptionAlg - encryption algorithm to be used. See savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) documentation for details about allowed values.
      encryptionPassword - encryption password to be used.
      opensslLegacyFormat - if true the key is saved in the legacy openssl format. Otherwise a PKCS #8 is used.
      Throws:
      IOException - if the data can not be written
      KeyStoreException - if the provided alias does not exist in the keystore or if it does not correspond to the private key entry.
      IllegalArgumentException - if encriptionAlg is unsupported or alias is wrong
      NoSuchAlgorithmException - if algorithm is not known
      UnrecoverableKeyException - if key can not be recovered

    • savePEMKeystore

      public static void savePEMKeystore(OutputStream os, KeyStore ks, String alias, String encryptionAlg, char[] keyPassword, char[] encryptionPassword, boolean opensslLegacyFormat) throws IOException, KeyStoreException, IllegalArgumentException, UnrecoverableKeyException, NoSuchAlgorithmException
      Saves the chosen private key entry from the provided keystore as a plain text PEM data. The produced PEM contains the private key first and then all certificates which are stored in the provided keystore under the given alias. The order from the keystore is preserved. The output stream is closed afterwards only if the write operation was successful (there was no exception).
      Parameters:
      os - where to write the encoded data to
      ks - keystore to read from
      alias - alias of the private key entry in the keystore
      encryptionAlg - encryption algorithm to be used. See savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) documentation for details about allowed values.
      keyPassword - password of the private key in the keystore
      encryptionPassword - encryption password to be used.
      opensslLegacyFormat - if true the key is saved in the legacy openssl format. Otherwise a PKCS #8 is used.
      Throws:
      IOException - if the data can not be written
      KeyStoreException - if the provided alias does not exist in the keystore or if it does not correspond to the private key entry.
      IllegalArgumentException - if encriptionAlg is unsupported or alias is wrong
      NoSuchAlgorithmException - if algorithm is not known
      UnrecoverableKeyException - if key can not be recovered

    • getPF

      public static PasswordSupplier getPF(char[] password)