eu.emi.security.authn.x509.impl
Class CertificateUtils

java.lang.Object
  extended by 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

Nested Class Summary
static class CertificateUtils.Encoding
          Definition of the encoding that can be used for reading or writing certificates or keys.
 
Field Summary
static Charset ASCII
           
static String DEFAULT_KEYSTORE_ALIAS
           
 
Constructor Summary
CertificateUtils()
           
 
Method Summary
static void configureSecProvider()
          Configures security providers which are used by the library.
static X509Certificate[] convertToX509Chain(Certificate[] chain)
          Performs a trivial conversion by use of casting of a Certificate array into X509Certificate array
static String format(X509Certificate[] certChain, FormatMode mode)
          Produces a human readable text representation of the provided certificate chain.
static String format(X509Certificate cert, FormatMode mode)
          Produces a human readable text representation of the provided certificate.
static PasswordFinder getPF(char[] password)
           
static X509Certificate loadCertificate(InputStream is, CertificateUtils.Encoding format)
          Loads a single certificate from the provided input stream.
static X509Certificate[] loadCertificateChain(InputStream is, CertificateUtils.Encoding format)
          Loads a chain of certificates from the provided input stream.
static KeyStore loadPEMKeystore(InputStream is, char[] password, char[] ksPassword)
          Loads certificates and private keys from the PEM input stream (usually from file).
static KeyStore loadPEMKeystore(InputStream is, PasswordFinder pf, char[] ksPassword)
          As loadPEMKeystore(InputStream, char[], char[]) but this version allows for providing input key's encryption password only when needed.
static PrivateKey loadPEMPrivateKey(InputStream is, PasswordFinder pf)
          Loads a private key from the provided input stream.
static PrivateKey loadPrivateKey(InputStream is, CertificateUtils.Encoding format, char[] password)
          Loads a private key from the provided input stream.
static void saveCertificate(OutputStream os, X509Certificate cert, CertificateUtils.Encoding format)
          Saves the provided certificate to the output file, using the requested encoding.
static void saveCertificateChain(OutputStream os, X509Certificate[] chain, CertificateUtils.Encoding format)
          Saves the provided certificate chain to the output stream, using the requested encoding.
static void savePEMKeystore(OutputStream os, KeyStore ks, String alias, String encryptionAlg, char[] keyPassword, char[] encryptionPassword)
          See savePEMKeystore(OutputStream, KeyStore, String, String, char[], char[], boolean) with the last argument equal to false.
static void savePEMKeystore(OutputStream os, KeyStore ks, String alias, String encryptionAlg, char[] keyPassword, char[] encryptionPassword, boolean opensslLegacyFormat)
          Saves the chosen private key entry from the provided keystore as a plain text PEM data.
static void savePEMKeystore(OutputStream os, X509Credential toSave, String encryptionAlg, char[] encryptionPassword, boolean opensslLegacyFormat)
          See savePEMKeystore(OutputStream, KeyStore, String, String, char[], char[], boolean).
static void savePrivateKey(OutputStream os, PrivateKey pk, CertificateUtils.Encoding format, String encryptionAlg, char[] encryptionPassword)
          As savePrivateKey(OutputStream, PrivateKey, Encoding, String, char[], boolean) with the last argument equal to false
static void savePrivateKey(OutputStream os, PrivateKey pk, CertificateUtils.Encoding format, String encryptionAlg, char[] encryptionPassword, boolean opensslLegacyFormat)
          Saves the provided private key to the output file, using the requested encoding.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_KEYSTORE_ALIAS

public static final String DEFAULT_KEYSTORE_ALIAS
See Also:
Constant Field Values

ASCII

public static final Charset ASCII
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.


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 openssl rsa -outform der ...). 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,
                                           PasswordFinder 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 PasswordFinder instead of the actual password. The PasswordFinder 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

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

Throws:
IOException
IllegalArgumentException

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

Throws:
IOException
KeyStoreException
IllegalArgumentException
UnrecoverableKeyException
NoSuchAlgorithmException

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 usinf the CANL X509Credential instead of low level KeyStore as argument.

Throws:
IOException
KeyStoreException
IllegalArgumentException
UnrecoverableKeyException
NoSuchAlgorithmException

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
keyPassword - password of the private key in the keystore
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
UnrecoverableKeyException

getPF

public static PasswordFinder getPF(char[] password)


Copyright © 2012-2013 European Middleware Initiative. All Rights Reserved.