org.eclipse.kura.ssl

Interface SslManagerService

public interface SslManagerService

The SslManagerService is responsible to manage the configuration of the SSL connections. It provide APIs to manage the trust certificates and the private keys and public certificates and enforces best practices that are not enabled by default in the Java VM. For example, it enables Hostname Verification, disables the legacy SSL-2.0-compatible Client Hello, and disable the Nagle algorithm. Its implementation is configurable exposing the possibility to express the allowed SSL protocols, the allowed cipher suites, and the location of the Trust Store and the Key Store files.

Method Summary

Methods

Modifier and Type	Method and Description
void	deleteTrustCertificate(String alias) Deletes the X509 certificate with the specified Common Name (cn) from the currently configured trust store.
SSLSocketFactory	getSSLSocketFactory() Returns an SSLSocketFactory based on the current configuration of the SslManagerService and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello. If the SslManagerService configuration contains a path to a custom Trust store, then it will be used.
SSLSocketFactory	getSSLSocketFactory(String keyAlias) Returns an SSLSocketFactory based on the current configuration of the SslManagerService and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello. If the SslManagerService configuration contains a path to a custom Trust store, then it will be used.
SSLSocketFactory	getSSLSocketFactory(String protocol, String cipherSuites, String trustStorePath, String keyStorePath, char[] keyStorePassword, String keyAlias) Returns an SSLSocketFactory based on the specified parameters and applying best practices like Hostname Verification (enabled by default) and disables the legacy SSL-2.0-compatible Client Hello.
SSLSocketFactory	getSSLSocketFactory(String protocol, String cipherSuites, String trustStorePath, String keyStorePath, char[] keyStorePassword, String keyAlias, boolean hostnameVerification) Returns an SSLSocketFactory based on the specified parameters and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello.
X509Certificate[]	getTrustCertificates() Returns the X509 Certificates installed in the currently configured trust store.
void	installPrivateKey(String alias, PrivateKey privateKey, char[] password, Certificate[] publicCerts) Installs a private key and the correspondent public certificate chains in the configured key store with the defined alias.
void	installTrustCertificate(String alias, X509Certificate x509crt) Installs the specified X509 certificate in the currently configured trust store.

Method Detail

getSSLSocketFactory

SSLSocketFactory getSSLSocketFactory()
                                     throws GeneralSecurityException,
                                            IOException

Returns an SSLSocketFactory based on the current configuration of the SslManagerService and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello.
If the SslManagerService configuration contains a path to a custom Trust store, then it will be used. If not, the Java VM default Trust Store will be used.
If the SslManagerService configuration contains a path to a custom Key store, then it will be used. If not, no Key store will be specified..

Returns:

the SSLSocketFactory

Throws:

GeneralSecurityException

IOException

getSSLSocketFactory

SSLSocketFactory getSSLSocketFactory(String keyAlias)
                                     throws GeneralSecurityException,
                                            IOException

Returns an SSLSocketFactory based on the current configuration of the SslManagerService and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello.
If the SslManagerService configuration contains a path to a custom Trust store, then it will be used. If not, the Java VM default Trust Store will be used.
If the SslManagerService configuration contains a path to a custom Key store, and such store contains a KeyEntry with the alias "keyAlias" then a KeyStore with the only such KeyEntry will be used. If no custom store is configured or it does not contain the "keyAlias" specified, no Key store will be specified..

Parameters:

keyAlias - alias of the entry in the KeyStore to be used for the returned SSLSocketFactory

Returns:

the SSLSocketFactory

Throws:

GeneralSecurityException

IOException

getSSLSocketFactory

SSLSocketFactory getSSLSocketFactory(String protocol,
                                   String cipherSuites,
                                   String trustStorePath,
                                   String keyStorePath,
                                   char[] keyStorePassword,
                                   String keyAlias)
                                     throws GeneralSecurityException,
                                            IOException

Returns an SSLSocketFactory based on the specified parameters and applying best practices like Hostname Verification (enabled by default) and disables the legacy SSL-2.0-compatible Client Hello.

Parameters:

protocol - the protocol to use to initialize the SSLContext - e.g. TLSv1.2

cipherSuites - allowed cipher suites for the returned SSLSocketFactory

trustStorePath - Location of the Java keystore file containing the collection of CA certificates trusted by this application process (trust store). Key store type is expected to be JKS.

keyStorePath - Location of the Java keystore file containing an application process's own certificate and private key. Key store type is expected to be JKS.

keyStorePassword - Password to access the private key from the keystore file.

keyAlias - alias of the entry in the KeyStore to be used for the returned SSLSocketFactory

Returns:

the SSLSocketFactory

Throws:

GeneralSecurityException

IOException

getSSLSocketFactory

SSLSocketFactory getSSLSocketFactory(String protocol,
                                   String cipherSuites,
                                   String trustStorePath,
                                   String keyStorePath,
                                   char[] keyStorePassword,
                                   String keyAlias,
                                   boolean hostnameVerification)
                                     throws GeneralSecurityException,
                                            IOException

Returns an SSLSocketFactory based on the specified parameters and applying best practices like Hostname Verification and disables the legacy SSL-2.0-compatible Client Hello.

Parameters:

protocol - the protocol to use to initialize the SSLContext - e.g. TLSv1.2

cipherSuites - allowed cipher suites for the returned SSLSocketFactory

trustStorePath - Location of the Java keystore file containing the collection of CA certificates trusted by this application process (trust store). Key store type is expected to be JKS.

keyStorePath - Location of the Java keystore file containing an application process's own certificate and private key. Key store type is expected to be JKS.

keyStorePassword - Password to access the private key from the keystore file.

keyAlias - alias of the entry in the KeyStore to be used for the returned SSLSocketFactory

hostnameVerification - enable server Hostname Verification

Returns:

the SSLSocketFactory

Throws:

GeneralSecurityException

IOException

getTrustCertificates

X509Certificate[] getTrustCertificates()
                                       throws GeneralSecurityException,
                                              IOException

Returns the X509 Certificates installed in the currently configured trust store. If the SslManagerService configuration contains a path to a custom trust store, then the returned certificates are the ones installed in such store. Otherwise the default Java VM trust store will be listed.

Returns:

the X509Certificates

Throws:

GeneralSecurityException

IOException

installTrustCertificate

void installTrustCertificate(String alias,
                           X509Certificate x509crt)
                             throws GeneralSecurityException,
                                    IOException

Installs the specified X509 certificate in the currently configured trust store. If the SslManagerService configuration contains a path to a custom trust store, then the certificate will be installed in such store. Otherwise the certificate will be installed in the default Java VM trust store.

Parameters:

x509crt - certificate to be installed

Throws:

GeneralSecurityException

IOException

deleteTrustCertificate

void deleteTrustCertificate(String alias)
                            throws GeneralSecurityException,
                                   IOException

Deletes the X509 certificate with the specified Common Name (cn) from the currently configured trust store. If the SslManagerService configuration contains a path to a custom trust store, then the certificate will be deleted from such store. Otherwise the certificate will be deleted from the default Java VM trust store.

Parameters:

cn -

Throws:

GeneralSecurityException

IOException

installPrivateKey

void installPrivateKey(String alias,
                     PrivateKey privateKey,
                     char[] password,
                     Certificate[] publicCerts)
                       throws GeneralSecurityException,
                              IOException

Installs a private key and the correspondent public certificate chains in the configured key store with the defined alias.

Parameters:

alias - that is a string that will be used to identify the certificates in the key store

privateKey - that represents PrivateKey object

password - that represents the password used to encode the keys in the key store

publicCerts - that represents an array of Certificate objects that contain the public certificate chain

Throws:

GeneralSecurityException

IOException