1transfer::connect(n) Data transfer facilities transfer::connect(n)
2______________________________________________________________________________
6
8 transfer::connect - Connection setup
9
11 package require Tcl 8.4
12 package require snit ?1.0?
14 package require transfer::connect ?0.2?
16 transfer::connect objectName ?options...?
18 objectName method ?arg arg ...?
20 objectName destroy
22 objectName connect command
24______________________________________________________________________________
26
28 This package provides objects holding enough information to enable them
29 to either actively connect to a counterpart, or to passively wait for a
30 connection from said counterpart. I.e. any object created by this
31 packages is always in one of two complementary modes, called active
32 (the object initiates the connection) and passive (the object receives
33 the connection).
34 Of the two objects in a connecting pair one has to be configured for
36 active mode, and the other then has to be configured for passive mode.
37 This establishes which of the two partners connects to whom (the active
38 to the other), or, who is waiting on whom (the passive on the other).
39 Note that this is completely independent of the direction of any data
40 transmission using the connection after it has been established. An
41 active object can, after establishing the connection, either transmit
42 or receive data. Equivalently the passive object can do the same after
43 the waiting for its partner has ended.
44
46 PACKAGE COMMANDS
47 transfer::connect objectName ?options...?
48 This command creates a new connection object with an associated
49 Tcl command whose name is objectName. This object command is
50 explained in full detail in the sections Object command and
51 Object methods. The set of supported options is explained in
52 section Options.
53 The object command will be created under the current namespace
55 if the objectName is not fully qualified, and in the specified
56 namespace otherwise. The fully qualified name of the object
57 command is returned as the result of the command.
58 OBJECT COMMAND
60 All objects created by the ::transfer::connect command have the follow‐
61 ing general form:
62 objectName method ?arg arg ...?
64 The method method and its arg'uments determine the exact behav‐
65 ior of the command. See section Object methods for the detailed
66 specifications.
67 OBJECT METHODS
69 objectName destroy
70 This method destroys the object. This is safe to do for an
71 active object when a connection has been started, as the comple‐
72 tion callback is synchronous. For a passive object currently
73 waiting for its partner to establish the connection however this
74 is not safe and will cause errors later on, when the connection
75 setup completes and tries to access the now missing data struc‐
76 tures of the destroyed object.
77 objectName connect command
79 This method starts the connection setup per the configuration of
80 the object. When the connection is established the callback com‐
81 mand will be invoked with one additional argument, the channel
82 handle of the socket over which data can be transfered.
83 The detailed behaviour of the method depends on the configured
85 mode.
86 active The connection setup is done synchronously. The object
88 waits until the connection is established. The method
89 returns the empty string as its result.
90 passive
92 The connection setup is done asynchronously. The method
93 returns immediately after a listening socket has been set
94 up. The connection will be established in the background.
95 The method returns the port number of the listening
96 socket, for use by the caller. One important use is the
97 transfer of this information to the counterpart so that
98 it knows where it has to connect to.
99 This is necessary as the object might have been config‐
101 ured for port 0, allowing the operating system to choose
102 the actual port it will listen on.
103 The listening port is closed immediately when the connec‐
105 tion was established by the partner, to keep the time
106 interval small within which a third party can connect to
107 the port too. Even so it is recommended to use addi‐
108 tional measures in the protocol outside of the connect
109 and transfer object to ensure that a connection is not
110 used with an unidentified/unauthorized partner One possi‐
111 bility for this is the use of SSL/TLS. See the option
112 -socketcmd and section Secure connections for information
113 on how to do this.
114 OPTIONS
116 Connection objects support the set of options listed below.
117 -mode mode
119 This option specifies the mode the object is in. It is optional
120 and defaults to active mode. The two possible modes are:
121 active In this mode the two options -host and -port are relevant
123 and specify the host and TCP port the object has to con‐
124 nect to. The host is given by either name or IP address.
125 passive
127 In this mode the option -host has no relevance and is
128 ignored should it be configured. The only option the
129 object needs is -port, and it specifies the TCP port on
130 which the listening socket is opened to await the connec‐
131 tion from the partner.
132 -host hostname-or-ipaddr
134 This option specifies the host to connect to in active mode,
135 either by name or ip-address. An object configured for passive
136 mode ignores this option.
137 -port int
139 For active mode this option specifies the port the object is
140 expected to connect to. For passive mode however it is the port
141 where the object creates the listening socket waiting for a con‐
142 nection. It defaults to 0, which allows the OS to choose the
143 actual port to listen on.
144 -socketcmd command
146 This option allows the user to specify which command to use to
147 open a socket. The default is to use the builtin ::socket. Any
148 compatible with that command is allowed.
149 The envisioned main use is the specfication of tls::socket. I.e.
151 this option allows the creation of secure transfer channels,
152 without making this package explicitly dependent on the tls
153 package.
154 See also section Secure connections.
156 -encoding encodingname
158 -eofchar eofspec
160 -translation transspec
162 These options are the same as are recognized by the builtin com‐
163 mand fconfigure. They provide the configuration to be set for
164 the channel between the two partners after it has been estab‐
165 lished, but before the callback is invoked (See method connect).
166
168 One way to secure connections made by objects of this package is to
169 require the package tls and then configure the option -socketcmd to
170 force the use of command tls::socket to open the socket.
171 # Load and initialize tls
174 package require tls
175 tls::init -cafile /path/to/ca/cert -keyfile ...
176 # Create a connector with secure socket setup,
178 transfer::connect C -socketcmd tls::socket ...
179 ...
180
183 This package uses the TLS package to handle the security for https urls
184 and other socket connections.
185 Policy decisions like the set of protocols to support and what ciphers
187 to use are not the responsibility of TLS, nor of this package itself
188 however. Such decisions are the responsibility of whichever applica‐
189 tion is using the package, and are likely influenced by the set of
190 servers the application will talk to as well.
191 For example, in light of the recent POODLE attack [http://googleonli‐
193 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
194 ssl-30.html] discovered by Google many servers will disable support for
195 the SSLv3 protocol. To handle this change the applications using TLS
196 must be patched, and not this package, nor TLS itself. Such a patch
197 may be as simple as generally activating tls1 support, as shown in the
198 example below.
199 package require tls
202 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
203 ... your own application code ...
205
208 This document, and the package it describes, will undoubtedly contain
209 bugs and other problems. Please report such in the category transfer
210 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
211 also report any ideas for enhancements you may have for either package
212 and/or documentation.
213 When proposing code changes, please provide unified diffs, i.e the out‐
215 put of diff -u.
216 Note further that attachments are strongly preferred over inlined
218 patches. Attachments can be made by going to the Edit form of the
219 ticket immediately after its creation, and then using the left-most
220 button in the secondary navigation bar.
221
223 active, channel, connection, passive, secure, ssl, tls, transfer
224
226 Transfer module
227
229 Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
230tcllib 0.2 transfer::connect(n)