com.ls.lars.server
Class AgentPlatformSecurity

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--com.ls.lars.communication.CommunicationTemplate
              |
              +--com.ls.lars.server.AgentTemplate
                    |
                    +--com.ls.lars.server.AgentSynchronization
                          |
                          +--com.ls.lars.server.AgentPlatformSecurity
All Implemented Interfaces:
ICommunication, IToLars, Runnable, Serializable

public final class AgentPlatformSecurity
extends AgentSynchronization

The lars platform synchronization process allows the inter-connection of lars platforms in order to enable cross-platform messaging. Lars platforms can be configured to 'know' remote platforms and to connect to them at runtime.
For instance, 141.168.1.1-lars1 could be configured to connect to 141.168.1.1-lars3, which enables the agents on both platforms to inter-communicate with each other.

Platform synchronization also can establish connections dynamically: a lars platform, which connects to a remote platform, gets automatically informed on other platforms that are currently connected to that remote platform. This information process depends on the kind of connection type that exist between the various platforms.

There are 3 kinds of connection types:

Example: The platform1 is connected to platform2a using a 'hidden' connection, and to platform2b using a 'public' connection. Now, platform3 opens a 'private' connection to platform1. In this case, platform3 will be informed on the connection parameters of platform2b, which enables it to connect to the platform directly. The platform3 will not get the connection parameters of platform2a, as this platform is 'hidden' by platform1.

This agent takes care what information is being sent to a connecting platform. The information always contains the connection parameters of the local platform, additional connection parameters being sent are depending on the connection type as explained above.

In addition this agent manages the security settings regarding the client-to-lars- and inter-lars-communication. The agent provides possibilities to define trusted and untrustedparties - on the basis of the following settings (to be configured within the config file):

You can define the security of your local lars platform to a very fine-grained level. For instance, you could specify that all agents coming from platform1 are not allowed to connect, but the agents AgentX and AgentY of the very same platform.

Please note:
By default your local lars platform is absolutely locked.
This means no agent may connect from outside to your lars platform This behavior forces you to think about security and to configure at least a minimum set of trusted agents, platforms or IP addresses.


to Class Specification
Incoming Messages: You can send messages requesting the following services from this agent. Input parameters you have to specify are listed with the messages and must be transmitted using a map.

      -----------------------------------------------------------------------
      agent_connected (internal use only!)
      -----------------------------------------------------------------------
      Function:    Notifies the current agent that a defined other agent is
                   available on the local platform.

      Parameters:  agent's name (String)
                   The string message containing the agent's name

      Responses:   none

      Note:        This message is for lars internal use only, thus it can
                   be sent only from the platform's AgentMessageRouter.
                   Any message from any other originator will be ignored.
      -----------------------------------------------------------------------
      set_trusted_agent (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds agent name(s) to the list of all trusted agents.

      Parameters: Map with key 'agent' and with a String or Collection
                  denoting the trusted agent name(s) as value(s).

      Responses:  none
      -----------------------------------------------------------------------
      set_untrusted_agent (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds agent name(s) to the list of all untrusted agents.

      Parameters: Map with key 'agent' and with a String or Collection
                  denoting the untrusted agent name(s) as value(s).

      Responses:  none
      -----------------------------------------------------------------------
      set_trusted_platform (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds platform name(s) to the list of all trusted platforms.

      Parameters: Map with key 'platform' and with a String or
                  Collection denoting the trusted platform name(s) as value(s).

      Responses:  none
      -----------------------------------------------------------------------
      set_untrusted_platform (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds platform name(s) to the list of all untrusted
                  platforms.

      Parameters: Map with key 'platform' and with a String or Collection
                  denoting the untrusted platform name(s) as value(s).

      Responses:  none
      -----------------------------------------------------------------------
      set_trusted_ip (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds IP address(es) to the list of all trusted IP addresses.

      Parameters: Map with key 'ipAddress' and with a String or
                  Collection denoting the trusted IP address(es) as value(s).

      Responses:  none
      -----------------------------------------------------------------------
      set_untrusted_ip (config file only!)
      -----------------------------------------------------------------------
      Function:   Adds IP address(es) to the list of all untrusted IP
                  addresses.

      Parameters: Map with key 'ipAddress' and with a String or
                  Collection denoting the untrusted IP address(es) as
                  value(s).

      Responses:  none
      -----------------------------------------------------------------------
      response_for_connection_parameters
      -----------------------------------------------------------------------
      Function:   This message is being sent from the local listener agents,
                  when being ask for their connectionParameters.

      Parameters: Map with key 'port' and with a String denoting the port the
                  sender of this message (a listener) is listening on.

      Responses:  none
      -----------------------------------------------------------------------
      register_platforms (internal use only!)
      -----------------------------------------------------------------------
      Function:   Registers the platforms given by this message to the local
                  lars platform.

      Parameters: List containing one or more
                  AgentSynchronization.LarsPlatformRepresentation entries.

      Responses:  none

      Note:       This message is used for the platform synchronization
                  process only, thus it can be sent only from this platform's
                  AgentSynchronizeSupervisor or
                  AgentSynchronizeConnectionHandler.
                  Messages being sent from any other originator will be
                  ignored.
      -----------------------------------------------------------------------
      unregister_platforms (internal use only!)
      -----------------------------------------------------------------------
      Function:   Unregisters the platforms given by this message to the local
                  lars platform.

      Parameters: List containing one or more
                  AgentSynchronization.LarsPlatformRepresentation entries.

      Responses:  none

      Note:       This message is used for the platform synchronization process
                  only, thus it can be sent only from this platform's
                  AgentSynchronizeSupervisor or
                  AgentSynchronizeConnectionHandler.
                  Messages being sent from any other originator will be
                  ignored.
      -----------------------------------------------------------------------
      inform_remote_platforms (internal use only!)
      -----------------------------------------------------------------------
      Function:   The message orders this agent to inform every platform as
                  given in this message's content on the connection settings
                  of every other connected platform - according on the type of
                  connection.

      Parameters: List containing one or more
                  AgentSynchronization.LarsPlatformRepresentation entries.

      Responses:  none

      Note:       This message is used for the platform synchronization
                  process only, thus it can be sent only from this platform's
                  AgentSynchronizeSupervisor or
                  AgentSynchronizeConnectionHandler.
                  Messages being sent from any other originator will be
                  ignored.
      -----------------------------------------------------------------------

 Note:
 When specifying trusted and untrusted agents, platforms and/or IP addresses,
 you can specifying the connectionType, the setting is thought for.

 If you specify a connectionType of:

 
 When you do not specify a connectionType, the default is '*'!

Version:
$Revision: 1.20 $
Author:
Last modified by $Author: OHittmeyer $
See Also:
Serialized Form

Inner classes inherited from class com.ls.lars.server.AgentSynchronization
AgentSynchronization.LarsPlatformRepresentation
 
Field Summary
protected static String HIDDEN_ACCESS
          Constant representing a string constant for access
protected static String PRIVATE_ACCESS
          Constant representing a string constant for access
protected static String PUBLIC_ACCESS
          Constant representing a string constant for access
protected  String revisionInformation
          revision information string, managed by our version control system.
 
Fields inherited from class com.ls.lars.server.AgentSynchronization
agentListener, agentPlatformSecurityName, agentSychronizeConnectionHandlerName, agentSychronizeSupervisorName, ATTEMPT_CONNECTIONS, CHECK_CONNECTIONS, initiallyKnownPlatforms, LISTENER_NAME, LISTENER_TYPE, ownPlatformIP, ownPlatformName, PLATFORM_ACCESS, PLATFORM_CONNECTION_TYPE, PLATFORM_IP, PLATFORM_NAME, PLATFORM_PORT, preferredProtocolOrder, refreshTime, refreshTimeIfUnconnectedPlatforms, SYNCHRONIZATION_INTERVALS
 
Fields inherited from class com.ls.lars.server.AgentTemplate
agentMaxPool, agentMessageRouterName, agentMinPool, defaultServiceAccessPermission, defaultServiceAccessPrivilege, dynamicObjectController, FULL_SERVICE_ACCESS, iXMLHandlerForConfigLoader, localPlatform, maxInvokeStackCounter, NO_SERVICE_ACCESS, RUN_LEVEL_ACTIONS_INITIALIZED, RUN_LEVEL_CONFIG_FILE_INTERPRETED, RUN_LEVEL_CONFIG_FILE_READ, RUN_LEVEL_EMBRYONIC, RUN_LEVEL_INTERPRET_METHODS_REGISTERED, RUN_LEVEL_POOL_INITIALIZED, RUN_LEVEL_RUNNING, RUN_LEVEL_STOPPED, RUN_LEVEL_TERMINATED
 
Fields inherited from class com.ls.lars.communication.CommunicationTemplate
agentName, homePlatform, iPKIHandler, logger, STATUS_CONNECTED, STATUS_NOT_CONNECTED
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Fields inherited from interface com.ls.lars.communication.ICommunication
AUTHENTICATION_PASSWORD, AUTHENTICATION_USER, COMPRESSION_AUTO_COMPRESSION, COMPRESSION_AUTO_COMPRESSION_START_SIZE, COMPRESSION_LEVEL, COMPRESSION_TYPE, COMPRESSION_ZIP_ENTRY_NAME, CONNECTION_TYPE, HOST_ID, HOST_IP, HOST_PORT, HTTP, J_SECURE_SOCKET, J_SOCKET, JMS, JMS_INITIAL_CONTEXT_FACTORY, JMS_JMSMESSENGER_APPLICATION_LOCATION, JMS_PROVIDER_URL, JMS_RECEIVING_QUEUE_NAME, JMS_SECURITY_CREDENTIALS, JMS_SECURITY_PRINCIPAL, JMS_SENDING_QUEUE_NAME, MAXIMUM_MESSAGE_LENGTH, PROTOCOL, RMI, SOCKET, TIMEOUT, USE_OUTBOX
 
Constructor Summary
AgentPlatformSecurity(String agentName, String homePlatform, List agentCfgFiles)
          Constructor with the agentName, its homePlatform and the name of the configuration file of the new agent
 
Method Summary
protected  void initializeMessages()
          Method which is called after the cfg-file has been read.
protected  boolean interpretAgentConnected(Message currentMessage)
          Is the reply from AgentMessageRouter, when AgentSocketListener, AgentRMIListener, etc. is known by the AgentMessageRouter.
protected  boolean interpretInformRemotePlatforms(Message currentMessage)
          Method, that decides according to the access parameter, which remote platform is to be informed and what information this remote platform gets.
protected  boolean interpretRegisterPlatforms(Message currentMessage)
          New platforms are registered and stored in allKnownPlatforms.
protected  boolean interpretResponseForConnectionParameters(Message currentMessage)
          Method is called by the AgentMessageRouter if one of the listeners (AgentSocketListener, AgentRMIListener, etc.) is known.
protected  boolean interpretSetTrustedAgent(Message currentMessage)
          Adds agent names to the list of trusted agents. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretSetTrustedIp(Message currentMessage)
          Adds IP addresses to the list of trusted IP addresses. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretSetTrustedPlatform(Message currentMessage)
          Adds platform names to the list of trusted platforms. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretSetUntrustedAgent(Message currentMessage)
          Adds agent names to the list of untrusted agents. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretSetUntrustedIp(Message currentMessage)
          Adds IP addresses to the list of untrusted IP addresses. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretSetUntrustedPlatform(Message currentMessage)
          Adds platform names to the list of untrusted platforms. Note: For security reasons this message is accepted only if coming directly from a config file!
protected  boolean interpretUnregisterPlatforms(Message currentMessage)
          Platforms are unregistered and deleted from allKnownPlatforms.
 
Methods inherited from class com.ls.lars.server.AgentSynchronization
addPlatformToVectorOfPlatforms, checkForEqualPlatformConnections, checkForEqualPlatforms, checkPlatformInVectorOfPlatforms, deletePlaformFromVectorOfPlatforms, interpretSetConstants, interpretSynchronizePlatforms, ownPlatform
 
Methods inherited from class com.ls.lars.server.AgentTemplate
executeLifeCycle, executeWhileRunning, getAgentRevisionInformation, getIPKIHandler, getOwnPublicKeyCertificate, getRevisionInformation, initializeAction, interpret, interpretAccessDenied, interpretCheckRegisteredServices, interpretCloseConnection, interpretDefineObject, interpretDeliveryFailed, interpretGetRevisionInformation, interpretInterpretationSuccessful, interpretLoadObject, interpretLogInbox, interpretMonitorLookup, interpretNotifiedAgent, interpretNotifyCanceled, interpretNotifyNotCanceled, interpretNotUnderstood, interpretPing, interpretRegisterService, interpretSendAsConfigured, interpretSetAccessPrivileges, interpretSetForeignPublicKeyCertificate, interpretSetLog, interpretSetOwnPublicKeyCertificate, interpretSetPkiEnvironment, interpretSetPkiMessages, interpretSetPrivateKey, interpretSetRunLevel, interpretSignatureNotValid, interpretStartupConstraint, loadConfigFile, performDefaultBehavior, reconnectAfterMigration, registerInterpretMethods, registerInterpretMethods, registerInterpretMethods, reInitializeAction, setAgentMessageRouterName, setIXMLHandler, setLocalPlatform, setPKIMessage, terminateAction, toString
 
Methods inherited from class com.ls.lars.communication.CommunicationTemplate
addConnectionParameter, checkSendSystemReply, connect, createReplyId, disconnect, disconnectForMigration, finalize, forwardMessage, forwardMessage, getAgentName, getConnectionParameters, getInboxSize, getLarsHost, getNumberOfProcessedMessages, getNumberOfProcessedMessagesPerMinute, getStartTime, isConnected, logInbox, receiveBlockedMessage, receiveBlockedMessage, run, sendMessage, sendSynchronousRequest, sendSynchronousRequest, setConnectionParameters, setLog, setMeantimeBetweenConnectionCheck, waitForConnection, waitForConnection
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, yield
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.ls.lars.communication.IToLars
start
 

Field Detail

revisionInformation

protected String revisionInformation
revision information string, managed by our version control system.

PUBLIC_ACCESS

protected static final String PUBLIC_ACCESS
Constant representing a string constant for access

PRIVATE_ACCESS

protected static final String PRIVATE_ACCESS
Constant representing a string constant for access

HIDDEN_ACCESS

protected static final String HIDDEN_ACCESS
Constant representing a string constant for access
Constructor Detail

AgentPlatformSecurity

public AgentPlatformSecurity(String agentName,
                             String homePlatform,
                             List agentCfgFiles)
Constructor with the agentName, its homePlatform and the name of the configuration file of the new agent
Parameters:
agentName - name of the agent
homePlatform - name of the lars platform (e.g 192.168.1.1-lars)
agentCfgFiles - name of the agent config file (e.g. AgentPlatformSecurity.cfg)
Method Detail

initializeMessages

protected void initializeMessages()
Method which is called after the cfg-file has been read. It will setup the AgentMessageRouter to notify when the listeners are runnging.
Overrides:
initializeMessages in class AgentSynchronization

interpretAgentConnected

protected boolean interpretAgentConnected(Message currentMessage)
Is the reply from AgentMessageRouter, when AgentSocketListener, AgentRMIListener, etc. is known by the AgentMessageRouter. Every time a listener is reported it is asked for the socket connection parameters or rmi connection parameters respectivly.
Overrides:
interpretAgentConnected in class AgentTemplate
Parameters:
currentMessage - Incomming Message.
Returns:
Result is true if everything was ok, false otherwise.

interpretSetTrustedAgent

protected boolean interpretSetTrustedAgent(Message currentMessage)
Adds agent names to the list of trusted agents.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_trusted_agent' message
Returns:
true, if successful; false else

interpretSetUntrustedAgent

protected boolean interpretSetUntrustedAgent(Message currentMessage)
Adds agent names to the list of untrusted agents.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_untrusted_agent' message
Returns:
true, if successful; false else

interpretSetTrustedPlatform

protected boolean interpretSetTrustedPlatform(Message currentMessage)
Adds platform names to the list of trusted platforms.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_trusted_platform' message
Returns:
true, if successful; false else

interpretSetUntrustedPlatform

protected boolean interpretSetUntrustedPlatform(Message currentMessage)
Adds platform names to the list of untrusted platforms.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_untrusted_platform' message
Returns:
true, if successful; false else

interpretSetTrustedIp

protected boolean interpretSetTrustedIp(Message currentMessage)
Adds IP addresses to the list of trusted IP addresses.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_trusted_ip' message
Returns:
true, if successful; false else

interpretSetUntrustedIp

protected boolean interpretSetUntrustedIp(Message currentMessage)
Adds IP addresses to the list of untrusted IP addresses.

Note: For security reasons this message is accepted only if coming directly from a config file!

Parameters:
currentMessage - a 'set_untrusted_ip' message
Returns:
true, if successful; false else

interpretResponseForConnectionParameters

protected boolean interpretResponseForConnectionParameters(Message currentMessage)
Method is called by the AgentMessageRouter if one of the listeners (AgentSocketListener, AgentRMIListener, etc.) is known. The message contains the connection parameters of the respective listener.
Parameters:
currentMessage - Incomming Message.
Returns:
Result is true if everything was ok, false otherwise.

interpretRegisterPlatforms

protected boolean interpretRegisterPlatforms(Message currentMessage)
New platforms are registered and stored in allKnownPlatforms.
Parameters:
currentMessage - Incomming Message.
Returns:
Result is true if everything was ok, false otherwise.

interpretUnregisterPlatforms

protected boolean interpretUnregisterPlatforms(Message currentMessage)
Platforms are unregistered and deleted from allKnownPlatforms.
Parameters:
currentMessage - the current 'unregister_platforms' message
Returns:
Result is true if everything was ok, false otherwise.

interpretInformRemotePlatforms

protected boolean interpretInformRemotePlatforms(Message currentMessage)
Method, that decides according to the access parameter, which remote platform is to be informed and what information this remote platform gets.
Parameters:
currentMessage - Incomming Message.
Returns:
Result is true if everything was ok, false otherwise.