Attaching and Initialising the Interface

## 6.3 Attaching and Initialising the Interface

- A Note on Security

To use the interface, the Tcl program needs to be attached to the ECLiPSe program. The attach request is initiated on the ECLiPSe side, by calling the predicate remote_connect/3 2 from ECLiPSe. The Tcl program is then attached to the ECLiPSe program by executing the procedure ec_remote_init from Tcl. If no error occurs, then the connection is established and the interface is set up.
In more detail, the ECLiPSe predicate remote_connect/3 establishes a socket listening for the connection from the Tcl side. It prints out, on the stream `log_output`, the hostname and the port number that the Tcl side should connect to:

    [eclipse 1]: remote_connect(Host/Port, Control, _InitGoal).
    Socket created at address chicken.icparc.ic.ac.uk/25909

On the Tcl side, ec_remote_init is called with the hostname and port number given by remote_connect/3:

    ec_remote_init chicken.icparc.ic.ac.uk 25909

ec_remote_init host port ?init_command? ?pass? ?format?
  Initialise the remote Tcl interface on the Tcl side. A corresponding remote_connect/3 must have been started on the ECLiPSe side, which specifies the hostname (host) and port number (port) to connect to. The optional init_command is an is a Tcl command that will be invoked at the end of the attachment, before control is handed over to the ECLiPSe side (see section 6.7 for more details). pass and format are optional arguments for a simple security check: they specify an ECLiPSe term that will be matched against a corresponding term (using ==/2) on the ECLiPSe side before the connection is allow to proceed (pass will be sent to the ECLiPSe side in EXDR format3; the default is an empty string, which is what remote_connect_setup/3 expects).

If successful, some initial links are established between the two sides, such as the control connection and the connection to allow rpc goals to be sent from the Tcl to the ECLiPSe side. After the attachment, optional user-defined initialisations are performed on both sides (via the InitGoal argument on the ECLiPSe side, and the init_command on the Tcl side), and the two sides can then interact. Initially, the control is given to the Tcl side, and remote_connect/3 returns only when control is handed over to the ECLiPSe side.
As part of the attachment process, the ECLiPSe name of the control connection is passed to the Tcl side. This can be accessed by the user using the command:

ec_control_name
  returns the ECLiPSe name of the control connection. An error is raised if this procedure is called before an attachment to ECLiPSe is made.

Unimplemented functionality error will be raised if the Tcl or ECLiPSe side are incompatible with each other. This can happen if one side is outdated, e.g. if the remote Tcl interface used and the ECLiPSe being connected to are not from the same version of ECLiPSe. In this case, it is best to update both sides to the latest version of ECLiPSe.

### 6.3.1 A Note on Security

Once a Tcl side is attached to an ECLiPSe, the Tcl side can execute ECLiPSe goals on the ECLiPSe side via the ec_rpc mechanism. This may be a security concern as this gives the Tcl side as much access to the resources on the ECLiPSe side as the ECLiPSe process itself, even though the Tcl side can potentially be anywhere reachable from the ECLiPSe side via TCP. However, the connection must be initiated from the ECLiPSe side, and the attachment process must follow a protocol in order for a successful attachment. Nevertheless, if a third party somehow knew which Address to connect to, and follows the protocol, it can `steal' the connection to ECLiPSe. No authentication is performed by the simple `remote_connect_setup/3`, but remote_connect_accept/6 does allow a simple authentication where it can require the Tcl side to send an ECLiPSe term that matches the one specified in calling the predicate. This is done before the Tcl side is given the ability to run rpc goals on the ECLiPSe side.
It is also possible to limit the remote connection to the same machine as the ECLiPSe process by specifying `localhost' as the host name in the Host/Port address of `remote_connect/3`. The Tcl side must also use `localhost' for the Host name in its client connection.
Each peer queue is created by creating a new server socket on the ECLiPSe side and then accepting a client connection from the Tcl side. The accept command is told where the client connection is from, and the client host is checked against the client's host from the attachment, to ensure that the same host has been connected. If not, the ECLiPSe side will reject the particular connection. At this point, the security has probably been compromised, and the two side should disconnect.
Note also that by default, none of the information sent through the queues between the remote side and the ECLiPSe side is encrypted. If the programmer requires these communication channels to be secure, then such encryptions need to be provided by the programmer.