Welcome to the Firewall Support Project

The firewall support project provides the following capabilities:

· Sending and receiving Cougaar messages over the HTTP protocol.

· Sending and receiving Cougaar messages over the HTTPS protocol.

· Integrating HTTPS with the Cougaar PKI (separate Cougaar project required).

The HTTP and HTTPS protocol make it easier to deploy Cougaar agents across enclave boundaries. In addition, the HTTPS protocol protects the confidentiality, integrity and authenticity of inter-agent connections.

1 HTTP message transport 1

1.1 HTTP protocol configuration. 2

1.2 Example node XML configuration file. 3

2 HTTPS message transport 3

2.1 HTTPS configuration. 4

2.2 Example node XML configuration file: 5

3 Cougaar Public Key Infrastructure. 5

4 Future plans. 6

1 HTTP message transport

The HTTP message transport protocol provides the following capabilities:

• Every agent listens for incoming messages through a servlet installed on the tomcat web server.
• Messages are sent through the HTTP POST protocol.
• Cougaar messages can cross firewalls with a standard configuration.

Figure 1: HTTP message transport protocol

In order use HTTP(S) exclusively as the message transport, the naming server must be configured to not bootstrap using RMI. The naming server bootstraps using RMI if the following is true:

• org.cougaar.core.name.server parameter(s) values are configured using the standard format:

NAME=HOST:PORT or NAME=AGENT@HOST:PORT.

For example, org.cougaar.core.name.server=NodeX@myhost:8888

• the alpreg.ini file exists, defining a host and port for the naming server:

[ Registry ]

address=myhost

alias=NodeX

port=8888

When using the HTTP transport, the naming server configuration will need to be defined in two parts; the first part is an alias and the second part is the MTS address. An alias is defined by

org.cougaar.name.server=NodeX@ or, if there are multiple WPs, with the usual "WP-NUMBER" pattern: org.cougaar.name.server.WP-9=NodeX@. An alias is a WP cache (local bind) entry indicating that there's a WP on NodeX. However, the alias by itself just tells the WP cache that there's a WP on NodeX, but the MTS will lack the HTTP address for NodeX. To add the HTTP address for NodeX, specify the following parameter: org.cougaar.name.server.NodeX=-HTTP:http://myhost:8080/$NodeX/httpmts. The alias and MTS address must be configured for every node.

Please note:

• The HTTP message transport protocol should not be confused with web-based traffic for the end-user. The HTTP message transport protocol is a mechanism to exchange Cougaar messages between agents in a machine-readable format. The format is not readable by an end-user. On the other hand, web-based traffic is generally HTML data sent over the HTTP protocol.
• The HTTP message transport protocol is integrated with the message transport service. It can be used in conjunction or in replacement of the RMI message transport protocol.

• Special care must be taken when specifying an agent name in the configuration. '$' will need to be escaped with a backslash on the shell (e.g., \$\Agent). In ruby you need to do one more level of escaping the '\' (e.g., \\$\\Agent).
• HTTP is enabled by default.

1.1 HTTP protocol configuration

The naming server configuration parameters for HTTP is set by the $CIP/csmart/configs/rules/security/naming/nameserver-http.rule file when using ACME.

Parameter	Description	Example
org.cougaar.name.server	Parameter used to specify WP aliases and MTS addresses.	Alias: NODE@ MTS address: -HTTP:http://myhost:8080/$NodeX/httpmts

The HTTP MTS LinkProtocol is set by the $CIP/csmart/configs/rules/security/mts/http_mts.rule file when using ACME.

Component	InsertionPoint	Priority
org.cougaar.core.security.mts.HTTPLinkProtocol	Node.AgentManager.Agent.MessageTransport.Component	COMPONENT

Please note:

• In addition to configuring a node with the HTTPLinkProtocol, the LoopbackLinkProtocol (org.cougaar.mts.base.LoopbackLinkProtocol) must also be added (using the same insertionpoint and priority as the HTTPLinkProtocol) for intra-node messages.

1.2 Example node XML configuration file

<?xml version='1.0'?>

<society name='society-for-NodeX'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:noNamespaceSchemaLocation='http://www.cougaar.org/2003/society.xsd'>

<host name='myhost'>

<node name='NodeX'>

<vm_parameter>

-Dorg.cougaar.name.server =NodeX@

</vm_parameter>

<vm_parameter>

-Dorg.cougaar.name.server .NodeX=-HTTP:http://myhost:8080/\$\NodeX/httpmts

</vm_parameter>

…

<component

name='org.cougaar.core.security.mts.HTTPLinkProtocol()'

class='org.cougaar.core.security.mts.HTTPLinkProtocol '

priority='COMPONENT'

insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'>

</component>

…

2 HTTPS message transport

The HTTP over SSL (HTTPS) message transport protocol provides the following capabilities:

• Every agent listens for incoming messages through a servlet installed on the tomcat web server.
• Messages are sent through the HTTPS POST protocol.
• Cougaar messages can cross firewalls with a standard configuration.
• All HTTP traffic used for the Cougaar Message Transport service is encrypted and authenticated using SSL.
• Both ends of the connection are authenticated using the Cougaar PKI. Certificate chains are verified against valid trusted certificate authorities.
• Both the client and server must provide the certificate of the node during the SSL handshake.
• The HTTPS mechanism is controlled by the security policy.

Figure 2: HTTPS message transport protocol

When using the HTTPS transport, the naming server configuration will need to be defined in two parts; the first part is an alias and the second part is the MTS address. An alias is defined by

org.cougaar.name.server=NodeX@ or, if there are multiple WPs, with the usual "WP-NUMBER" pattern: org.cougaar.name.server.WP-9=NodeX@. An alias is a WP cache (local bind) entry indicating that there's a WP on NodeX. However, the alias by itself just tells the WP cache that there's a WP on NodeX, but the MTS will lack the HTTPS address for NodeX. To add the HTTPS address for NodeX, specify the following parameter: org.cougaar.name.server.NodeX=-HTTPS:https://myhost:8090/$NodeX/httpmts. The alias and MTS address must be configured for every node.

Please note:

• Special care must be taken when specifying an agent name in the configuration. '$' will need to be escaped with a backslash on the shell (e.g., \$\Agent). In ruby you need to do one more level of escaping the '\' (e.g., \\$\\Agent).
• To enable HTTPS, tomcat server must have a server certificate installed and https is enabled (see section section 9.5 Servlet Server Install Guide of the Cougaar Developers’ Guide http://cougaar.org/docman/view.php/17/133/CDG_11_2_Final.pdf).

2.1 HTTPS configuration

The naming server configuration parameters for HTTPS is set by the $CIP/csmart/configs/rules/security/naming/nameserver-http.rule when using ACME.

Parameter	Description	Example
org.cougaar.name.server	Parameter used to specify WP aliases and MTS addresses.	Alias: NODE@ MTS address: -HTTPS:https://myhost:8090/$NodeX/httpmts

The HTTPS MTS LinkProtocol is set by the $CIP/csmart/configs/rules/security/mts/https_mts.rule file when using ACME.

Component	InsertionPoint	Priority
org.cougaar.core.security.mts.HTTPSLinkProtocol	Node.AgentManager.Agent.MessageTransport.Component	COMPONENT

Please note:

· In addition to configuring a node with the HTTPSLinkProtocol, the LoopbackLinkProtocol (org.cougaar.mts.base.LoopbackLinkProtocol) must also be added (using the same insertionpoint and priority as the HTTPSLinkProtocol) for intra-node messages.

2.2 Example node XML configuration file:

<?xml version='1.0'?>

<society name='society-for-NodeX'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:noNamespaceSchemaLocation='http://www.cougaar.org/2003/society.xsd'>

<host name='myhost'>

<node name='NodeX'>

<vm_parameter>

-Dorg.cougaar.name.server =NodeX@

</vm_parameter>

<vm_parameter>

-Dorg.cougaar.name.server .NodeX=-HTTPS:https://myhost:8090/\$\NodeX/httpmts

</vm_parameter>

…

<component

name='org.cougaar.core.security.mts.HTTPSLinkProtocol()'

class='org.cougaar.core.security.mts.HTTPSLinkProtocol '

priority='COMPONENT'

insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'>

</component>

…

3 Cougaar Public Key Infrastructure

The fwsupport project provides components to enable the HTTPS protocol as a transport mechanism. HTTPS can be enabled as a standalone component or along with other security services (which are provided in separate projects).

When installed as a standalone project, the user must configure each Tomcat server with a keystore containing cryptographic keys. When installed with the Cougaar PKI services, the HTTPS protocol is integrated with the Cougaar PKI.

The Cougaar PKI is used to protect the authenticity, integrity and confidentiality of Cougaar messages. First, the Cougaar security services provide mechanisms to encrypt, sign, and verify the signature of Cougaar messages. Second, the security services provides mechanisms to establish secure stream-oriented connections that can be used to exchange Cougaar messages in a secure manner. This mechanism is also used to protect the content of web traffic between a user and Cougaar agents.

Agents are authenticated using X.509 certificates. Users may be authenticated with X.509 certificates and/or user names and passwords.

4 Future plans

• A future version of the firewall support project will allow agents to be deployed across firewalls that have Network Address Translation enabled.