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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CertificateUtils.Encoding Definition of the encoding that can be used for reading or writing certificates or keys.

Field Summary

Fields

Modifier and Type	Field and Description
static Charset	ASCII
static String	DEFAULT_KEYSTORE_ALIAS

Constructor Summary

Constructors

Constructor and Description
CertificateUtils()

Method Summary

Modifier and Type	Method and Description
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 PasswordSupplier	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 X509Certificate[]	loadCertificates(InputStream is, CertificateUtils.Encoding format) Loads a set of (possibly unrelated to each other) 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, PasswordSupplier 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, PasswordSupplier 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 @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)