Class CertificateUtils


  • public class CertificateUtils
    extends Object
    Utility class with methods simplifying typical certificate related operations.
    Author:
    K. Benedyczak, J. Hahkala
    • Constructor Detail

      • CertificateUtils

        public CertificateUtils()
    • Method Detail

      • 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.

      • 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
      • 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,
                                          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,
                                           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