public class JSSEHelper
extends java.lang.Object
This class is for components and applications to utilize the SSL configuration framework for selecting SSL configurations and turning them into SSL objects such as SSLContext, Properties, URLStreamHandlers, and SocketFactories.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CONNECTION_INFO_CERT_MAPPING_HOST
Property used in the connection information Map to define the host
which is being connected to for dynamic selection of the certificate
map.
|
static java.lang.String |
CONNECTION_INFO_DIRECTION
Variable used for the connection information to determine SSLContext
validation rules.
|
static java.lang.String |
CONNECTION_INFO_ENDPOINT_NAME
Property used in the connection information Map to define the endpoint
for dynamic and group selection.
|
static java.lang.String |
CONNECTION_INFO_IS_WEB_CONTAINER_INBOUND
Property used to determine if the connection is a Web Container
inbound connection.
|
static java.lang.String |
CONNECTION_INFO_REMOTE_HOST
Property used in the connection information Map to define the remote
host which is being connected to for dynamic selection.
|
static java.lang.String |
CONNECTION_INFO_REMOTE_PORT
Property used in the connection information Map to define the remote
port which is being connected to for dynamic selection.
|
static java.lang.String |
DIRECTION_INBOUND
Variable used when the direction of the SSLContext is inbound.
|
static java.lang.String |
DIRECTION_OUTBOUND
Variable used when the direction of the SSLContext is outbound.
|
static java.lang.String |
DIRECTION_UNKNOWN
Variable used when the direction of the SSLContext is not currently known.
|
static java.lang.String |
ENDPOINT_ADMIN_IPC
EndPoint name when using IPC protocol from the IPC connector for outbound connections.
|
static java.lang.String |
ENDPOINT_ADMIN_SOAP
EndPoint name when using SOAP protocol from the SOAP connector for outbound connections.
|
static java.lang.String |
ENDPOINT_BUS_CLIENT
EndPoint name when using BUS_CLIENT protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_BUS_TO_BUS
EndPoint name when using ENDPOINT_BUS_TO_BUS protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_BUS_TO_WEBSPHERE_MQ
EndPoint name when using ENDPOINT_BUS_TO_WEBSPHERE_MQ protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_CLIENT_TO_WEBSPHERE_MQ
EndPoint name when using ENDPOINT_CLIENT_TO_WEBSPHERE_MQ protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_HTTP
EndPoint name when using HTTP protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_IIOP
EndPoint name when using IIOP protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_JMS
EndPoint name when using JMS protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_LDAP
EndPoint name when using LDAP (JNDI) protocol for outbound connections.
|
static java.lang.String |
ENDPOINT_SIP
EndPoint name when using SIP protocol for outbound connections.
|
Constructor and Description |
---|
JSSEHelper()
Constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
deregisterSSLConfigChangeListener(SSLConfigChangeListener listener)
This method removes the specific SSLConfigChangeListener from the list of
active listeners.
|
boolean |
doesSSLConfigExist(java.lang.String sslAliasName)
This method checks to ensure the SSL configuration name is known.
|
java.util.Map<java.lang.String,java.lang.Object> |
getInboundConnectionInfo()
This method is used to obtain information about the connection on the
thread of execution.
|
static JSSEHelper |
getInstance()
This method returns an instance of the JSSEHelper class.
|
java.util.Map<java.lang.String,java.lang.Object> |
getOutboundConnectionInfo()
This method is used to obtain information about the connection on the
thread of execution.
|
java.util.Properties |
getProperties(java.lang.String sslAliasName)
This method returns the SSL properties given a specific SSL configuration
alias.
|
java.util.Properties |
getProperties(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method returns the effective SSL properties object for use by an SSL
application or component.
|
java.util.Properties |
getProperties(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener,
boolean tryDefault)
Like
getProperties(String, Map, SSLConfigChangeListener) ,
except failing over to the default configuration is a choice. |
javax.net.ssl.SSLContext |
getSSLContext(java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
java.util.Properties props)
This method creates an SSLContext given a specific direction ("inbound" or
"outbound") and the SSL properties needed to create the SSLContext.
|
javax.net.ssl.SSLContext |
getSSLContext(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method creates an SSLContext for use by an SSL application or component.
|
javax.net.ssl.SSLContext |
getSSLContext(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener,
boolean tryDefault)
Like
getSSLContext(String, Map, SSLConfigChangeListener) ,
failing over to the default configuration is a choice. |
java.util.Properties |
getSSLPropertiesOnThread()
This method allows the retrieving of SSL properties on the thread of execution.
|
javax.net.ssl.SSLServerSocketFactory |
getSSLServerSocketFactory(java.util.Properties props)
This method creates an SSLServerSocketFactory given the SSL configuration
properties specified.
|
javax.net.ssl.SSLServerSocketFactory |
getSSLServerSocketFactory(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method creates an SSLSocketFactory for use by an SSL application or
component.
|
javax.net.ssl.SSLSocketFactory |
getSSLSocketFactory(java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
java.util.Properties props)
This method creates an SSLContext based on the SSL properties specified.
|
javax.net.ssl.SSLSocketFactory |
getSSLSocketFactory(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method creates an SSLSocketFactory for use by an SSL application or
component.
|
java.net.URLStreamHandler |
getURLStreamHandler(java.util.Properties props)
This method creates a URLStreamHandler specific SSL properties.
|
java.net.URLStreamHandler |
getURLStreamHandler(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method creates a URLStreamHandler for use by an SSL application or component.
|
void |
registerSSLConfigChangeListener(java.lang.String sslAliasName,
java.util.Map<java.lang.String,java.lang.Object> connectionInfo,
SSLConfigChangeListener listener)
This method registers an SSLConfigChangeListener for the specific SSL
configuration chosen based upon the parameters passed in using the
precedence logic described in the JavaDoc for the getSSLContext API.
|
void |
reinitializeClientDefaultSSLProperties()
This method causes a reinitialization of the SSL properties that are
located in default locations for sas.client.props, soap.client.props
or ssl.client.props.
|
void |
setInboundConnectionInfo(java.util.Map<java.lang.String,java.lang.Object> connectionInfo)
This method sets information about the connection on the thread
of execution.
|
void |
setOutboundConnectionInfo(java.util.Map<java.lang.String,java.lang.Object> connectionInfo)
This method sets information about the connection on the thread
of execution.
|
void |
setSSLPropertiesOnThread(java.util.Properties props)
This method allows the setting of SSL properties on the thread of execution.
|
void |
validateSSLProperties(java.util.Properties props)
This method attempts to create an SSLContext using the properties provided.
|
public static final java.lang.String DIRECTION_INBOUND
Variable used when the direction of the SSLContext is inbound. This is associated to receiving requests or server-side sockets, etc. This helps with validation of the required SSL attributes.
public static final java.lang.String DIRECTION_OUTBOUND
Variable used when the direction of the SSLContext is outbound. This is associated to sending requests or client-side sockets, etc. This helps with validation of the required SSL attributes.
public static final java.lang.String DIRECTION_UNKNOWN
Variable used when the direction of the SSLContext is not currently known. This will require that a TrustStore and KeyStore are both specified.
public static final java.lang.String ENDPOINT_IIOP
EndPoint name when using IIOP protocol for outbound connections.
public static final java.lang.String ENDPOINT_HTTP
EndPoint name when using HTTP protocol for outbound connections.
public static final java.lang.String ENDPOINT_SIP
EndPoint name when using SIP protocol for outbound connections.
public static final java.lang.String ENDPOINT_JMS
EndPoint name when using JMS protocol for outbound connections.
public static final java.lang.String ENDPOINT_BUS_CLIENT
EndPoint name when using BUS_CLIENT protocol for outbound connections.
public static final java.lang.String ENDPOINT_BUS_TO_WEBSPHERE_MQ
EndPoint name when using ENDPOINT_BUS_TO_WEBSPHERE_MQ protocol for outbound connections.
public static final java.lang.String ENDPOINT_BUS_TO_BUS
EndPoint name when using ENDPOINT_BUS_TO_BUS protocol for outbound connections.
public static final java.lang.String ENDPOINT_CLIENT_TO_WEBSPHERE_MQ
EndPoint name when using ENDPOINT_CLIENT_TO_WEBSPHERE_MQ protocol for outbound connections.
public static final java.lang.String ENDPOINT_LDAP
EndPoint name when using LDAP (JNDI) protocol for outbound connections.
public static final java.lang.String ENDPOINT_ADMIN_SOAP
EndPoint name when using SOAP protocol from the SOAP connector for outbound connections.
public static final java.lang.String ENDPOINT_ADMIN_IPC
EndPoint name when using IPC protocol from the IPC connector for outbound connections.
public static final java.lang.String CONNECTION_INFO_DIRECTION
Variable used for the connection information to determine SSLContext validation rules.
public static final java.lang.String CONNECTION_INFO_ENDPOINT_NAME
Property used in the connection information Map to define the endpoint for dynamic and group selection.
public static final java.lang.String CONNECTION_INFO_REMOTE_HOST
Property used in the connection information Map to define the remote host which is being connected to for dynamic selection. The host can be in the DNS or IP formats. It is preferred to be in the DNS format. The format should match the com.ibm.ssl.dynamicSelectionInfo property information in order for a match to occur.
public static final java.lang.String CONNECTION_INFO_REMOTE_PORT
Property used in the connection information Map to define the remote port which is being connected to for dynamic selection. The port should be the exact port being connected to so an accurate dynamic selection can be made.
public static final java.lang.String CONNECTION_INFO_CERT_MAPPING_HOST
Property used in the connection information Map to define the host which is being connected to for dynamic selection of the certificate map. The host should be in the IP format.
public static final java.lang.String CONNECTION_INFO_IS_WEB_CONTAINER_INBOUND
Property used to determine if the connection is a Web Container inbound connection.
public static JSSEHelper getInstance()
This method returns an instance of the JSSEHelper class. This is the proper way to get a reference of this API class.
public void setSSLPropertiesOnThread(java.util.Properties props)
This method allows the setting of SSL properties on the thread of execution. This has the highest precedence in terms of selection rules. When the SSL runtime finds SSL properties on the thread, this should be used before anything else in the selection process.
It's important to clear the thread after use, especially where thread pools are used. It is not cleared up automatically. Pass in "null" to this API to clear it.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "setSSLConfig" to be granted.
props
- public java.util.Properties getSSLPropertiesOnThread()
This method allows the retrieving of SSL properties on the thread of execution. This can be used for verification purposes or to communicate SSL properties among components running on the same thread.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
public java.util.Properties getProperties(java.lang.String sslAliasName) throws SSLException
This method returns the SSL properties given a specific SSL configuration alias.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- SSLException
public javax.net.ssl.SSLContext getSSLContext(java.util.Map<java.lang.String,java.lang.Object> connectionInfo, java.util.Properties props) throws SSLException
This method creates an SSLContext given a specific direction ("inbound" or "outbound") and the SSL properties needed to create the SSLContext. The properties can be retrieved from the SSL configuration using the getProperties API in this class.
connectionInfo
- - contains information about the connection direction, host, port, etc.props
- - the SSL propertiesSSLException
public java.net.URLStreamHandler getURLStreamHandler(java.util.Properties props) throws SSLException
This method creates a URLStreamHandler specific SSL properties. The URLStreamHandler is used for outbound URL connections.
props
- - the SSL properties (connectionInfo derived from URL)SSLException
public javax.net.ssl.SSLServerSocketFactory getSSLServerSocketFactory(java.util.Properties props) throws SSLException
This method creates an SSLServerSocketFactory given the SSL configuration properties specified. The properties can be retrieved from the SSL configuration using the getProperties API in this class.
props
- SSLException
public javax.net.ssl.SSLSocketFactory getSSLSocketFactory(java.util.Map<java.lang.String,java.lang.Object> connectionInfo, java.util.Properties props) throws SSLException
This method creates an SSLContext based on the SSL properties specified. The properties can be retrieved from the SSL configuration using the getProperties API in this class. The connectionInfo can be used by a custom TrustManager for further trust evaluation.
connectionInfo
- - contains information about the connection
direction, endpoint, host, port, etc.props
- - the SSL properties that will be used.SSLException
public javax.net.ssl.SSLContext getSSLContext(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method creates an SSLContext for use by an SSL application or component. Precedence logic will determine which parameters are used for creating the SSLContext. The selection precendence rules are:
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- - Used in direct selection. The alias name of a
specific SSL configuration (optional). You can pass in "null" here.connectionInfo
- - Used in dynamic selection and by custom TrustManagers. This refers
to the remote connection information. The current properties known
by the runtime include:
Example OUTBOUND case (endpoint refers more to protocol used since
outbound names are not well-known):
com.ibm.ssl.remoteHost="hostname.ibm.com"
com.ibm.ssl.remotePort="9809"
com.ibm.ssl.direction="outbound"
com.ibm.ssl.endPointName="IIOP"
Example INBOUND case (endpoint name matches serverindex endpoint):
com.ibm.ssl.direction="inbound"
com.ibm.ssl.endPointName="CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS"
listener
- - This is used to notify the
caller of this API that the SSL configuration changed in the runtime.
It's up to the caller to decide if they want to call this API again
to get the new SSLContext for the configuration. Passing in NULL
indicates no notification is desired. See the
com.ibm.websphere.ssl.SSLConfigChangeListener interface for more
information.SSLException
public javax.net.ssl.SSLContext getSSLContext(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener, boolean tryDefault) throws SSLException, SSLConfigurationNotAvailableException
getSSLContext(String, Map, SSLConfigChangeListener)
,
failing over to the default configuration is a choice.sslAliasName
- connectionInfo
- listener
- tryDefault
- if the specified alias is not available, true
indicates the default configuration should be tried.SSLException
SSLConfigurationNotAvailableException
public java.net.URLStreamHandler getURLStreamHandler(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method creates a URLStreamHandler for use by an SSL application or component. Precedence logic will determine which parameters are used for creating the URLStreamHandler. See the JavaDoc for getSSLContext with the same parameters for more info on the behavior of this API.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- connectionInfo
- listener
- SSLException
public javax.net.ssl.SSLSocketFactory getSSLSocketFactory(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method creates an SSLSocketFactory for use by an SSL application or component. Precedence logic will determine which parameters are used for creating the SSLSocketFactory. See the JavaDoc for getSSLContext with the same parameters for more info on the behavior of this API.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- connectionInfo
- listener
- SSLException
public javax.net.ssl.SSLServerSocketFactory getSSLServerSocketFactory(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method creates an SSLSocketFactory for use by an SSL application or component. Precedence logic will determine which parameters are used for creating the SSLSocketFactory. See the JavaDoc for getSSLContext with the same parameters for more info on the behavior of this API.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- connectionInfo
- listener
- SSLException
public java.util.Properties getProperties(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method returns the effective SSL properties object for use by an SSL application or component. Precedence logic will determine which parameters are used for creating the Properties. See the JavaDoc for getSSLContext with the same parameters for more info on the behavior of this API. If the SSLConfigChangeListener is non null, it must be deregistered by deregisterSSLConfigChangeListener when it is no longer needed.
When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getSSLConfig" to be granted.
sslAliasName
- connectionInfo
- listener
- SSLException
public java.util.Properties getProperties(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener, boolean tryDefault) throws SSLException
getProperties(String, Map, SSLConfigChangeListener)
,
except failing over to the default configuration is a choice.sslAliasName
- connectionInfo
- listener
- tryDefault
- if the specified alias is not available, true
indicates the default configuration should be tried.SSLException
public void registerSSLConfigChangeListener(java.lang.String sslAliasName, java.util.Map<java.lang.String,java.lang.Object> connectionInfo, SSLConfigChangeListener listener) throws SSLException
This method registers an SSLConfigChangeListener for the specific SSL configuration chosen based upon the parameters passed in using the precedence logic described in the JavaDoc for the getSSLContext API. The SSLConfigChangeListener must be deregistered by deregisterSSLConfigChangeListener when it is no longer needed.
sslAliasName
- connectionInfo
- listener
- SSLException
public void deregisterSSLConfigChangeListener(SSLConfigChangeListener listener) throws SSLException
This method removes the specific SSLConfigChangeListener from the list of active listeners.
listener
- SSLException
public boolean doesSSLConfigExist(java.lang.String sslAliasName)
This method checks to ensure the SSL configuration name is known.
sslAliasName
- public void reinitializeClientDefaultSSLProperties()
This method causes a reinitialization of the SSL properties that are located in default locations for sas.client.props, soap.client.props or ssl.client.props. Additional SSL configurations can be specified in the ssl.client.props.
public void validateSSLProperties(java.util.Properties props) throws SSLException
This method attempts to create an SSLContext using the properties provided. It is assumed the API is called on the node where the KeyStore information specified in the properties resides.
props
- SSLException
public java.util.Map<java.lang.String,java.lang.Object> getInboundConnectionInfo()
This method is used to obtain information about the connection on the thread of execution. This connection information can then be used from Custom Key and Trust Managers.
public void setInboundConnectionInfo(java.util.Map<java.lang.String,java.lang.Object> connectionInfo)
This method sets information about the connection on the thread of execution. This connection information can then be used from Custom Key and Trust Managers. This method is invoked prior to an SSL handshake.
It's important to clear the thread after use, especially where thread pools are used. It is not cleared up automatically. Pass in "null" to this API to clear it.
connectionInfo
- - Used in dynamic selection and by
custom KeyManagers. This refers to the inbound connection
information. For certificate mapping usage these
properties need to be provided, for example:
com.ibm.ssl.certMappingHost="hostname.ibm.com"
com.ibm.ssl.isWebContainerInbound= new Boolean(true);public java.util.Map<java.lang.String,java.lang.Object> getOutboundConnectionInfo()
This method is used to obtain information about the connection on the thread of execution. This connection information can then be used to set the connection information prior to creating and SSL socket.
public void setOutboundConnectionInfo(java.util.Map<java.lang.String,java.lang.Object> connectionInfo)
This method sets information about the connection on the thread of execution. This method is invoked prior to creating an SSL socket.
It's important to clear the thread after use, especially where thread pools are used. It is not cleared up automatically. Pass in "null" to this API to clear it.
connectionInfo
-