org.eclipse.californium.elements.util

Class SslContextUtil

java.lang.Object

org.eclipse.californium.elements.util.SslContextUtil

public class SslContextUtil
extends Object

Utility functions for SSLContext. This utility converts between the informations used by the javax SSL implementation and the plain credentials used by scandium. It offers reading KeyStores, extracting credentials, and creating KeyManager and TrustManager from the KeyStores or extracted credentials. Java SSLContext is able to maintain different key-certificate pairs for different key and signing algorithms. The californium-scandium concentrates on embedded client and therefore supports only one key-signing algorithm. This utility therefore helps, to select the right credentials or create a javax security classes for javax SSL implementation from that selected credentials. The utility provides a configurable mapping of URI endings with key store type, enable to use different KeyStore implementations and formats. The URI ending is defined as the part starting with the last "." after all "/" separator. e.g.: "cert/keyStore.p12" has ending ".p12", and "cert/keyStore.p12/test" has no ending. The currently pre-configured mapping contains:

 ".jks" to "JKS"
 ".bks" to "BKS"
 ".p12" to "PKCS12"
 "*" to system default
 

The utility provides also a configurable input stream factory of URI schemes. Currently only CLASSPATH_SCHEME is pre-configured to load key stores from the classpath. If the scheme of the URI has no configured input stream factory, the URI is loaded with URL.URL(String). Note: currently this class provides a class access based API. Depending on the usage, this may change to instance access based API. It is not intended, that the configuration is changed during usage, this may cause race conditions!

See Also:

configure(String, String), configure(String, InputStreamFactory)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SslContextUtil.Credentials Credentials.
static interface	SslContextUtil.InputStreamFactory Scheme specific input stream factory.

Field Summary

Fields

Modifier and Type	Field and Description
static String	BKS_ENDING Ending for key stores with type BKS_TYPE.
static String	BKS_TYPE Key store type BKS.
static String	CLASSPATH_PROTOCOL Deprecated. use CLASSPATH_SCHEME instead!
static String	CLASSPATH_SCHEME Scheme for key store URI.
static String	DEFAULT_ENDING Label to provide default key store type.
static String	DEFAULT_SSL_PROTOCOL Default protocol used for createSSLContext(String, PrivateKey, X509Certificate[], Certificate[]).
static String	JKS_ENDING Ending for key stores with type JKS_TYPE.
static String	JKS_TYPE Key store type JKS.
static String	PARAMETER_SEPARATOR Separator for parameters.
static String	PKCS12_ENDING Ending for key stores with type PKCS12_TYPE.
static String	PKCS12_TYPE Key store type PKCS12.

Constructor Summary

Constructors

Constructor and Description
SslContextUtil()

Method Summary

Methods

Modifier and Type	Method and Description
static X509Certificate[]	asX509Certificates(Certificate[] certificates) Return certificates as x509 certificates.
static SslContextUtil.InputStreamFactory	configure(String scheme, SslContextUtil.InputStreamFactory streamFactory) Configure input stream factory for URI scheme.
static String	configure(String ending, String keyStoreType) Configure key store types for URI endings.
static void	configureDefaults() Configure defaults.
static KeyManager[]	createKeyManager(String alias, PrivateKey privateKey, X509Certificate[] chain) Create key manager from private key and certificate path.
static SSLContext	createSSLContext(String alias, PrivateKey privateKey, X509Certificate[] chain, Certificate[] trusts) Create SSLContext with provided credentials and trusts.
static SSLContext	createSSLContext(String alias, PrivateKey privateKey, X509Certificate[] chain, Certificate[] trusts, String protocol) Create SSLContext with provided credentials and trusts.
static TrustManager[]	createTrustManager(String alias, Certificate[] trusts) Create trust manager from trusted certificates.
static X509Certificate[]	loadCertificateChain(String keyStoreUri, String alias, char[] storePassword) Load certificate chain from key store.
static SslContextUtil.Credentials	loadCredentials(String credentials) Load credentials from key store.
static SslContextUtil.Credentials	loadCredentials(String keyStoreUri, String alias, char[] storePassword, char[] keyPassword) Load credentials from key store.
static KeyManager[]	loadKeyManager(String keyStoreUri, String alias, char[] storePassword, char[] keyPassword) Load KeyManager from key store.
static Certificate[]	loadTrustedCertificates(String trust) Load trusted certificates from key store.
static Certificate[]	loadTrustedCertificates(String keyStoreUri, String aliasPattern, char[] storePassword) Load trusted certificates from key store.
static TrustManager[]	loadTrustManager(String keyStoreUri, String aliasPattern, char[] storePassword) Load TrustManager from key store.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASSPATH_SCHEME

public static final String CLASSPATH_SCHEME

Scheme for key store URI. Used to load the key stores from classpath.

See Also:

Constant Field Values

CLASSPATH_PROTOCOL

public static final String CLASSPATH_PROTOCOL

Deprecated. use CLASSPATH_SCHEME instead!

See Also:

Constant Field Values

PARAMETER_SEPARATOR

public static final String PARAMETER_SEPARATOR

Separator for parameters.

See Also:

loadTrustedCertificates(String), loadCredentials(String), Constant Field Values

JKS_ENDING

public static final String JKS_ENDING

Ending for key stores with type JKS_TYPE.

See Also:

Constant Field Values

BKS_ENDING

public static final String BKS_ENDING

Ending for key stores with type BKS_TYPE.

See Also:

Constant Field Values

PKCS12_ENDING

public static final String PKCS12_ENDING

Ending for key stores with type PKCS12_TYPE.

See Also:

Constant Field Values

DEFAULT_ENDING

public static final String DEFAULT_ENDING

Label to provide default key store type.

See Also:

Constant Field Values

JKS_TYPE

public static final String JKS_TYPE

Key store type JKS.

See Also:

Constant Field Values

BKS_TYPE

public static final String BKS_TYPE

Key store type BKS.

See Also:

Constant Field Values

PKCS12_TYPE

public static final String PKCS12_TYPE

Key store type PKCS12.

See Also:

Constant Field Values

DEFAULT_SSL_PROTOCOL

public static final String DEFAULT_SSL_PROTOCOL

Default protocol used for createSSLContext(String, PrivateKey, X509Certificate[], Certificate[]).

See Also:

Constant Field Values

Constructor Detail

SslContextUtil

public SslContextUtil()

Method Detail

loadTrustedCertificates

public static Certificate[] loadTrustedCertificates(String trust)
                                             throws IOException,
                                                    GeneralSecurityException

Load trusted certificates from key store.

Parameters:

trust - trust definition keystore#hexstorepwd#aliaspattern. If no aliaspattern should be used, just leave it blank keystore#hexstorepwd#

Returns:

array with trusted certificates.

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if trust doesn't match keystore#hexstorepwd#aliaspattern or no matching trusts are found

NullPointerException - if trust is null.

See Also:

PARAMETER_SEPARATOR

loadCredentials

public static SslContextUtil.Credentials loadCredentials(String credentials)
                                                  throws IOException,
                                                         GeneralSecurityException

Load credentials from key store.

Parameters:

credentials - credentials definition keystore#hexstorepwd#hexkeypwd#alias.

Returns:

credentials

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if keys doesn't match keystore#hexstorepwd#hexkeypwd#alias or no matching trusts are found

NullPointerException - if credentials is null.

See Also:

PARAMETER_SEPARATOR

loadTrustManager

public static TrustManager[] loadTrustManager(String keyStoreUri,
                              String aliasPattern,
                              char[] storePassword)
                                       throws IOException,
                                              GeneralSecurityException

Load TrustManager from key store.

Parameters:

keyStoreUri - key store URI. Supports configurable URI scheme based input streams and URI ending based key store type.

aliasPattern - regular expression for aliases to load only specific certificates for the TrustManager. null to load all certificates.

storePassword - password for key store.

Returns:

array with TrustManager

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if no matching trusts are found

NullPointerException - if keyStoreUri or storePassword is null.

loadKeyManager

public static KeyManager[] loadKeyManager(String keyStoreUri,
                          String alias,
                          char[] storePassword,
                          char[] keyPassword)
                                   throws IOException,
                                          GeneralSecurityException

Load KeyManager from key store.

Parameters:

keyStoreUri - key store URI. Supports configurable URI scheme based input streams and URI ending based key store type.

alias - alias to load only specific credentials into the KeyManager. null to load all credentials into the KeyManager.

storePassword - password for key store.

keyPassword - password for private key.

Returns:

array with KeyManager

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if no matching credentials are found

NullPointerException - if keyStoreUri, storePassword, or keyPassword is null.

loadTrustedCertificates

public static Certificate[] loadTrustedCertificates(String keyStoreUri,
                                    String aliasPattern,
                                    char[] storePassword)
                                             throws IOException,
                                                    GeneralSecurityException

Load trusted certificates from key store.

Parameters:

keyStoreUri - key store URI. Supports configurable URI scheme based input streams and URI ending based key store type.

aliasPattern - regular expression for aliases to load only specific certificates for trusting. null to load all certificates.

storePassword - password for key store.

Returns:

array with trusted certificates.

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if no matching certificates are found

NullPointerException - if keyStoreUri or storePassword is null.

loadCredentials

public static SslContextUtil.Credentials loadCredentials(String keyStoreUri,
                                         String alias,
                                         char[] storePassword,
                                         char[] keyPassword)
                                                  throws IOException,
                                                         GeneralSecurityException

Load credentials from key store.

Parameters:

keyStoreUri - key store URI. Supports configurable URI scheme based input streams and URI ending based key store type.

alias - alias to load specific credentials.

storePassword - password for key store.

keyPassword - password for private key.

Returns:

credentials for the alias.

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if alias is empty, or no matching credentials are found.

NullPointerException - if keyStoreUri, storePassword, keyPassword, or alias is null.

loadCertificateChain

public static X509Certificate[] loadCertificateChain(String keyStoreUri,
                                     String alias,
                                     char[] storePassword)
                                              throws IOException,
                                                     GeneralSecurityException

Load certificate chain from key store.

Parameters:

keyStoreUri - key store URI. Supports configurable URI scheme based input streams and URI ending based key store type.

alias - alias to load the certificate chain.

storePassword - password for key store.

Returns:

certificate chain for the alias.

Throws:

IOException - if key store could not be loaded.

GeneralSecurityException - if security setup failed.

IllegalArgumentException - if alias is empty, or no matching certificate chain is found.

NullPointerException - if keyStoreUri, storePassword, or alias is null.

configureDefaults

public static void configureDefaults()

Configure defaults. Key store type:

 ".jks" to "JKS"
 ".bks" to "BKS"
 ".p12" to "PKCS12"
 "*" to system default
 

Input stream factory: CLASSPATH_SCHEME to classpath loader.

configure

public static String configure(String ending,
               String keyStoreType)

Configure key store types for URI endings.

Parameters:

ending - URI ending. If DEFAULT_ENDING is used, the key store default type is configured. Ending is converted to lower case before added to the KEY_STORE_TYPES.

keyStoreType - key store type.

Returns:

old key store type for ending, or null, if no key store type was configured before

Throws:

NullPointerException - if ending or key store type is null.

IllegalArgumentException - if ending doesn't start with "." and isn't DEFAULT_ENDING, or key store type is empty.

configure

public static SslContextUtil.InputStreamFactory configure(String scheme,
                                          SslContextUtil.InputStreamFactory streamFactory)

Configure input stream factory for URI scheme.

Parameters:

scheme - URI scheme. Scheme is converted to lower case before added to the INPUT_STREAM_FACTORIES.

streamFactory - input stream factory to read key stores access with this URI scheme.

Returns:

previous stream factory, if already configure, or null, if not stream factory was previously configured.

Throws:

NullPointerException - if scheme or stream factory is null.

IllegalArgumentException - if scheme doesn't end with "://".

asX509Certificates

public static X509Certificate[] asX509Certificates(Certificate[] certificates)

Return certificates as x509 certificates. Ensure, that all provided certificates are x509.

Parameters:

certificates - to check

Returns:

array with x509 certificates.

Throws:

IllegalArgumentException - if null, a empty array is provided or a none x509 certificate was found or a array entry was null.

createSSLContext

public static SSLContext createSSLContext(String alias,
                          PrivateKey privateKey,
                          X509Certificate[] chain,
                          Certificate[] trusts)
                                   throws GeneralSecurityException

Create SSLContext with provided credentials and trusts. Uses DEFAULT_SSL_PROTOCOL.

Parameters:

alias - alias to be used in KeyManager. Used for identification according the X509ExtendedKeyManager API to select the credentials matching the provided key. Though the create KeyManager currently only supports on set of credentials, the alias is only used to select that. If null, it's replaced by a default "californium".

privateKey - private key

chain - certificate trust chain related to private key.

trusts - trusted certificates.

Returns:

created SSLContext.

Throws:

GeneralSecurityException - if security setup failed.

NullPointerException - if private key, or the chain, or the trusts is null.

IllegalArgumentException - if the chain or trusts is empty.

createSSLContext

public static SSLContext createSSLContext(String alias,
                          PrivateKey privateKey,
                          X509Certificate[] chain,
                          Certificate[] trusts,
                          String protocol)
                                   throws GeneralSecurityException

Create SSLContext with provided credentials and trusts.

Parameters:

alias - alias to be used in KeyManager. Used for identification according the X509ExtendedKeyManager API to select the credentials matching the provided key. Though the create KeyManager currently only supports on set of credentials, the alias is only used to select that. If null, it's replaced by a default "californium".

privateKey - private key

chain - certificate trust chain related to private key.

trusts - trusted certificates.

protocol - specific protocol for SSLContext. See SSLContext.getInstance(String).

Returns:

created SSLContext.

Throws:

GeneralSecurityException - if security setup failed.

NullPointerException - if private key, or the chain, or the trusts is null.

IllegalArgumentException - if the chain or trusts is empty.

createKeyManager

public static KeyManager[] createKeyManager(String alias,
                            PrivateKey privateKey,
                            X509Certificate[] chain)
                                     throws GeneralSecurityException

Create key manager from private key and certificate path. Creates a KeyStore to use KeyManagerFactory.

Parameters:

alias - alias to be used for key store

privateKey - private key

chain - certificate chain.

Returns:

key manager.

Throws:

GeneralSecurityException - if security setup failed.

NullPointerException - if private key or the chain is null.

IllegalArgumentException - if the chain is empty.

createTrustManager

public static TrustManager[] createTrustManager(String alias,
                                Certificate[] trusts)
                                         throws GeneralSecurityException

Create trust manager from trusted certificates. Creates a KeyStore to use TrustManagerFactory.

Parameters:

alias - alias to be used for key store.

trusts - trusted certificates

Returns:

trust manager

Throws:

GeneralSecurityException - if security setup failed.

NullPointerException - if trusted certificates is null.

IllegalArgumentException - if trusted certificates is empty.