com.sap.security.core.server.https
Class SecureConnectionFactory

java.lang.Object
  |
  +--com.sap.security.core.server.https.SecureConnectionFactory

All Implemented Interfaces:

SocketFactory

public class SecureConnectionFactory

extends Object

implements SocketFactory

This factory class should be used within SAP J2EE Server to create HttpsUrlConnection and SSLSocket instances based on given security credentials (key stores).

The advantage of this factory is that it hides from application developers SSL-library specific handling and takes care for such features as verifiying of certificate chains, session caching, naming checks, etc. Some configuration can be done using Utils class.

Inside this factory IAIK iSaSiLk is used as SSL implementation and w3c-http extended by IAIK for HTTP/HTTPS, but application developers are dealing only with standard java classes: Keystore, HttpUrlConnection and Socket.

If an application developer is interested in extended HTTP features like WebDAV, etc. we want to mention that there is an addition library available within the J2EE Server which uses this factory for SSL Socket creation but another paradigma for HTTP Connections.

The SecureConnectionFactory is initialized with 2 Keystores: Trusted Store, which contains the root certificates belonging to trusted Certificated Authorities, and an optional Credentials Keystore, containing one or several pairs of private-key with corresponding certificates, which are to be used for SSL with mutual authentication.
After initialisation the factory provides two kinds of methods:

• createURLConnection(String url, ...) or
  createURLConnection(String protocol, String host, int port, String file, ...)

  which supports https (and experimentally http based on W3C implementation) as protocols and returns an instance of HttpURLConnection.

• createSocket (String host, int port, ...)

  which returns an instance of Socket.

Different SSL and HTTP settings can be configured either on the factory to apply to all created connections or by using the Utils class to be connection specific.

Proxy Settings
For connecting via a proxy the host name and port number of the proxy have to be set as System properties using "https.proxyHost" and "https.proxyPort".

It is possible to specify a list of hosts for which the library should not use a proxy. This can be done using the "https.nonProxyHosts" property. The value of this property is a '|' separated list of host names. The '*' as wildcard character is allowed as first character of a name in the list.

Proxy authentication can be done by setting System properties "https.proxyUser" and "https.proxyPassword" or using the methods Utils.setProxyAuthentication.

To achive that the createSocket method establishes a connection over proxy see example at createSocket(String, int, Socket) or use the method createSocket(String, int).

Because SecureConnectionFactory also supports HTTP protocol if the method createURLConnection is called with a "http"-URL, proxy settings for HTTP connections should be set separately. This can be done by setting the System property proxySet to "true" and the System properties proxyHost, and proxyPort.

SSL with client authentication
During the SSL handshake a server sends a list of certificate authorities, which are accepted by the server for authenticating the client with client certificates. Based on this list and all of the KeyEntries contained in the provided Credentials Keystore, the client decides, which credentials to use for authentication. If this decision is undefined, or if an application has to restrict the choice of available credentials an array of aliases can be additionaly specified. An empty array of aliases will prevent client authentication. To allow all available credentials use null as value for aliase or methods without such parameter.

SSL session caching
Each instance os SecureConnectionFactory provides independent cache of SSL sessions. This avoids session collisions from different applications within the same running Java VM.

SSL Naming Check
SSL Naming Check offers a way to compare host name with the name server certificate was issued for. The name from server certificate is dermined from ALL common name component of subject's distinguidshed name, all SubjectAltName and NetscapeSSLServerName extensions. See HostnameVerifier and DefaultHostnameVerifier for details about compearing the name components.

Logging
All classes are using standard Logging API provided by SAP J2EE Server.
The debugging messages from underlying IAIK library are redirected to location com.sap.security.core.server.https.IAIK under severity level DEBUG.

Copyright (c) 2003 SAP AG.

Field Summary

boolean

_isIAIKavailable

Constructor Summary

SecureConnectionFactory(Certificate[] trustedcerts, Object[] keyandcerts)
This constructor is provided because of some special needs of WEBSERVICES Project.

SecureConnectionFactory(KeyStore keystore)
Creates a new factory based on given credentials.

SecureConnectionFactory(KeyStore truststore, KeyStore keystore)
Creates a new factory based on given credentials.

SecureConnectionFactory(KeyStore truststore, Object truststoreCreds, KeyStore keystore, Object keystoreCreds)
Creates a new connection factory based on given credentials.

SecureConnectionFactory(String trustview, String keyview)
Constructor to use within SAP J2EE Server.

Method Summary

Socket	createSocket(InetAddress inetAddr, int port) Creates (ssl)socket based on local credentials.
Socket	createSocket(InetAddress inetAddr, int port, InetAddress clientAddr, int cport) Creates (ssl)socket based on local credentials.
Socket	createSocket(InetAddress inetAddr, int port, InetAddress clientAddr, int cport, String[] aliases) Creates (ssl)socket based on local credentials.
Socket	createSocket(InetAddress inetAddr, int port, String[] aliases) Creates (ssl)socket based on local credentials.
Socket	createSocket(String host, int port) Creates (ssl)socket based on local credentials. This method establishes a connection using proxy setting specified in System properties.
Socket	createSocket(String host, int port, InetAddress clientAddr, int cport) Creates (ssl)socket based on local credentials.
Socket	createSocket(String host, int port, InetAddress clientAddr, int cport, String[] aliases) Creates (ssl)socket based on local credentials.
Socket	createSocket(String host, int port, Socket socket) Creates (ssl)socket based on local credentials. This constructor should be used when tunneling SSL through a proxy.
Socket	createSocket(String host, int port, Socket socket, String[] aliases) Creates (ssl)socket based on local credentials. This constructor should be used when tunneling SSL through a proxy.
Socket	createSocket(String host, int port, String[] aliases) Creates (ssl)socket based on local credentials. This method establishes a connection using proxy setting specified in System properties.
HttpURLConnection	createURLConnection(String url) Creates HttpUrlConnection based on local credentials.
HttpURLConnection	createURLConnection(String url, String keyalias) Creates HttpUrlConnection based on local credentials.
HttpURLConnection	createURLConnection(String url, String[] keyaliases) Creates HttpUrlConnection based on local credentials.
HttpURLConnection	createURLConnection(String protocol, String host, int port, String file) Creates an a HttpURLConnection based on protocol, host, port and file.
HttpURLConnection	createURLConnection(String protocol, String host, int port, String file, String keyalias) Creates HttpUrlConnection based on local credentials.
HttpURLConnection	createURLConnection(String protocol, String host, int port, String file, String[] keyaliases) Creates HttpUrlConnection based on local credentials.
String	getConnectionHeader() Returns the value of the "Connection"- header used by the factory.
static SecureConnectionFactory	getDefault() Creates a default instance of SecureConnectionFactory.
protected void	initFactory(Certificate[] trustedcerts, Object[] keyandcerts)
protected void	initFactory(KeyStore truststore, Object truststoreCreds, KeyStore keystore, Object keystoreCreds)
void	setConnectionHeader(String arg) Sets the value of the "Connection" - header used by the factory.
void	setDefaultSSLContext(Object context) Allows a customizing of SSLClientContext used be the factory.
void	setHostnameVerifier(HostnameVerifier ver) Sets the hostname verifier. If the default verifier doesn't meet the requirements a customised verifier can be used, e.g. factory.setHostnameVerifier(new HostnameVerifier (){ public boolean verify (String urlHostname, String certHostname ) { // compare the strings on your way return ...; } });
void	setIgnoreServerCertificate(boolean arg) Acitivates/deactivates verification of server certificate.
void	setSSLDebugStream(OutputStream out) Replicates the debugging outputs to specified output stream. (e.g.
void	setUseProxyForSocketConnection(boolean arg) Defines whether the createSocket(String, int) and createSocket(String, int, String[]) methods should determine proxy setting using System properties.

Methods inherited from class java.lang.Object

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

Field Detail

_isIAIKavailable

public boolean _isIAIKavailable

Constructor Detail

SecureConnectionFactory

public SecureConnectionFactory(KeyStore keystore)

Creates a new factory based on given credentials. The keystore is used to look up for trusted certificates AND client credentials.

NOTE: To avoid that the keystore used to look up for client credentials use SecureConnectionFactory(KeyStore, KeyStore) with null as second parameter.

ATTENTION: If a trusted certificate store is not specified (null) all SSL connections will fail on server authentication. This behaivior can be temporary changed using the setIgnoreServerCertificate(boolean) method. But it's not recomended to use this method, because it contradicts with SSL principles.

Parameters:

keystore - a keystore with trusted certificates for server authentication and KeyAndCertificate pairs for client authentication

SecureConnectionFactory

public SecureConnectionFactory(KeyStore truststore,
                               KeyStore keystore)

Creates a new factory based on given credentials.

ATTENTION: If a trusted certificate store is not specified (null) all SSL connections will fail on server authentication. This behaivior can be temporary changed using the setIgnoreServerCertificate(boolean) method. But it's not recomended to use this method, because it contradicts with SSL principles.

Parameters:

truststore - a keystore with trusted certificates for server authentication

keystore - a keystore used for client authentication

SecureConnectionFactory

public SecureConnectionFactory(KeyStore truststore,
                               Object truststoreCreds,
                               KeyStore keystore,
                               Object keystoreCreds)

Creates a new connection factory based on given credentials.

ATTENTION: If a trusted certificate store is not specified (null) all SSL connections will fail on server authentication. This behaivior can be temporary changed using the setIgnoreServerCertificate(boolean) method. But it's not recomended to use this method, because it contradicts with SSL principles.

Parameters:

truststore - a keystore with trusted certificates for server authentication

truststoreCreds - is ignored now

keystore - a keystore used for client authentication

keystoreCrds - is either ignored or if it is an instance of char[] used as described in KeyStore.getKey(java.lang.String, char[])

SecureConnectionFactory

public SecureConnectionFactory(String trustview,
                               String keyview)

Constructor to use within SAP J2EE Server.

The trust and keystores will be accessed over JNDI by the name of the view.
Code based permissions are granted automatically. User based permissions are always required and can be granted with e.g. using run-as identity in deployment descriptor or administrativly.

Parameters:

trustview - the name of the view containing trusted certificates

keyview - the name of the view containing client certificates. It can be identical with trustview.

SecureConnectionFactory

public SecureConnectionFactory(Certificate[] trustedcerts,
                               Object[] keyandcerts)

This constructor is provided because of some special needs of WEBSERVICES Project.

Method Detail

getDefault

public static SecureConnectionFactory getDefault()

Creates a default instance of SecureConnectionFactory. The factory is always initialized with trusted store only, so client authentication is not possible.

The keystore view "TrustedCAs" is used as trusted store.

initFactory

protected void initFactory(KeyStore truststore,
                           Object truststoreCreds,
                           KeyStore keystore,
                           Object keystoreCreds)

initFactory

protected void initFactory(Certificate[] trustedcerts,
                           Object[] keyandcerts)

setDefaultSSLContext

public void setDefaultSSLContext(Object context)

Allows a customizing of SSLClientContext used be the factory. If such context is set externally, the context based on local credentials is ignored.

Parameters:

context - should be an instance of iaik.security.ssl.SSLClientContext and contain a nessesory settings for SSL connections.

setSSLDebugStream

public void setSSLDebugStream(OutputStream out)

Replicates the debugging outputs to specified output stream. (e.g. System.out) for each connection created by the factory.

Parameters:

out - OuputStram to write to.

setIgnoreServerCertificate

public void setIgnoreServerCertificate(boolean arg)

Acitivates/deactivates verification of server certificate.

Calling this method with true will deactivate server authentication (including naming check) for all connection created with this factory instance.
It's not recomended to use this method in productiv systems, because it contradicts with SSL principles.

setHostnameVerifier

public void setHostnameVerifier(HostnameVerifier ver)

Sets the hostname verifier.
If the default verifier doesn't meet the requirements a customised verifier can be used, e.g.

    	factory.setHostnameVerifier(new HostnameVerifier (){
    		public boolean verify (String urlHostname, String certHostname ) {
    			// compare the strings on your way
    			return ...;
    		}
    	});	     
  

Parameters:

ver - instance od HostnameVerifier

setUseProxyForSocketConnection

public void setUseProxyForSocketConnection(boolean arg)

Defines whether the createSocket(String, int) and createSocket(String, int, String[]) methods should determine proxy setting using System properties. Default it's set to true.

createURLConnection

public HttpURLConnection createURLConnection(String protocol,
                                             String host,
                                             int port,
                                             String file)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates an a HttpURLConnection based on protocol, host, port and file.

Parameters:

protocol - http and https are supported

host - the host name of the target server

port - the port number on the target server

file - the filename on the target server (e.g. /myapp/index.html)

Returns:

HttpURLConnection

Throws:

MalformedURLException - if it was not possible to create a valid URL from input data

IOException - if an I/O exception occurs

KeyStoreException - if exception occurs during access to the keystore

createURLConnection

public HttpURLConnection createURLConnection(String protocol,
                                             String host,
                                             int port,
                                             String file,
                                             String keyalias)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates HttpUrlConnection based on local credentials.

Parameters:

protocol -

host -

port -

file -

keyalias -

Returns:

Throws:

MalformedURLException -

IOException -

KeyStoreException -

createURLConnection

public HttpURLConnection createURLConnection(String protocol,
                                             String host,
                                             int port,
                                             String file,
                                             String[] keyaliases)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates HttpUrlConnection based on local credentials.

Parameters:

protocol -

host -

port -

file -

keyaliases -

Returns:

Throws:

MalformedURLException -

IOException -

KeyStoreException -

createURLConnection

public HttpURLConnection createURLConnection(String url)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates HttpUrlConnection based on local credentials.

Parameters:

url -

Returns:

Throws:

MalformedURLException -

IOException -

KeyStoreException -

createURLConnection

public HttpURLConnection createURLConnection(String url,
                                             String keyalias)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates HttpUrlConnection based on local credentials.

Parameters:

url -

keyalias -

Returns:

Throws:

MalformedURLException -

IOException -

KeyStoreException -

createURLConnection

public HttpURLConnection createURLConnection(String url,
                                             String[] keyaliases)
                                      throws MalformedURLException,
                                             IOException,
                                             KeyStoreException

Creates HttpUrlConnection based on local credentials.

Parameters:

url -

Returns:

HttpURLConnection

Throws:

MalformedURLException -

IOException -

KeyStoreException -

createSocket

public Socket createSocket(InetAddress inetAddr,
                           int port)
                    throws IOException

Creates (ssl)socket based on local credentials.

Parameters:

inetAddr -

port -

Returns:

Throws:

IOException -

createSocket

public Socket createSocket(InetAddress inetAddr,
                           int port,
                           String[] aliases)
                    throws IOException

Creates (ssl)socket based on local credentials.

Parameters:

inetAddr -

port -

aliases -

Returns:

Throws:

IOException -

createSocket

public Socket createSocket(String host,
                           int port,
                           InetAddress clientAddr,
                           int cport)
                    throws IOException

Creates (ssl)socket based on local credentials.

Parameters:

host -

port -

clientAddr -

cport -

Returns:

Throws:

IOException -

createSocket

public Socket createSocket(String host,
                           int port,
                           InetAddress clientAddr,
                           int cport,
                           String[] aliases)
                    throws IOException

Creates (ssl)socket based on local credentials.

Parameters:

host -

port -

clientAddr -

cport -

aliases -

Returns:

Throws:

IOException -

createSocket

public Socket createSocket(String host,
                           int port)
                    throws IOException

Creates (ssl)socket based on local credentials.

This method establishes a connection using proxy setting specified in System properties. If such behaivior is not wished this can be changed using setUseProxyForSocketConnection.

Specified by:

createSocket in interface SocketFactory

createSocket

public Socket createSocket(String host,
                           int port,
                           String[] aliases)
                    throws IOException

Creates (ssl)socket based on local credentials.

This method establishes a connection using proxy setting specified in System properties. If such behaivior is not wished this can be changed using setUseProxyForSocketConnection.

createSocket

public Socket createSocket(InetAddress inetAddr,
                           int port,
                           InetAddress clientAddr,
                           int cport)
                    throws IOException

Creates (ssl)socket based on local credentials.

createSocket

public Socket createSocket(InetAddress inetAddr,
                           int port,
                           InetAddress clientAddr,
                           int cport,
                           String[] aliases)
                    throws IOException

Creates (ssl)socket based on local credentials.

createSocket

public Socket createSocket(String host,
                           int port,
                           Socket socket)
                    throws IOException

Creates (ssl)socket based on local credentials.

This constructor should be used when tunneling SSL through a proxy. The host and port information are needed for session caching.
Example:

	 Socket proxySocket = Utils.getProxySocket ( host,_port, proxyuser,proxypwd);
	 Socket socket = factory.createSocket(_host,_port, proxySocket);
  

Specified by:

createSocket in interface SocketFactory

createSocket

public Socket createSocket(String host,
                           int port,
                           Socket socket,
                           String[] aliases)
                    throws IOException

Creates (ssl)socket based on local credentials.

This constructor should be used when tunneling SSL through a proxy. The host and port information are needed for session caching.
Example:

	 Socket proxySocket = Utils.getProxySocket ( host,_port, proxyuser,proxypwd);
	 Socket socket = factory.createSocket(_host,_port, proxySocket);
  

setConnectionHeader

public void setConnectionHeader(String arg)

Sets the value of the "Connection" - header used by the factory.

Because the HTTP library employs persistent connections that are possibly used for multiple HTTPS requests, this can be a security risk, if two logical instances with different personalisation are connecting to the same host one after another. To prevent this, connections created by the factory, are not persistent by default. For application where such threats are not critical, but using of persistent connections is desirable, this behaivor can be changed by calling this method with parameter "keep-alive".

Parameters:

arg - value of "Connection" -header (i.e. close or keep-alive)

getConnectionHeader

public String getConnectionHeader()

Returns the value of the "Connection"- header used by the factory.