1transfer::connect(n)       Data transfer facilities       transfer::connect(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transfer::connect - Connection setup
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit  ?1.0?
14
15       package require transfer::connect  ?0.2?
16
17       transfer::connect objectName ?options...?
18
19       objectName method ?arg arg ...?
20
21       objectName destroy
22
23       objectName connect command
24
25______________________________________________________________________________
26

DESCRIPTION

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
35       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

API

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
54              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
59   OBJECT COMMAND
60       All objects created by the ::transfer::connect command have the follow‐
61       ing general form:
62
63       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
68   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
78       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
84              The  detailed  behaviour of the method depends on the configured
85              mode.
86
87              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
91              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
100                     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
104                     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
115   OPTIONS
116       Connection objects support the set of options listed below.
117
118       -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
122              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
126              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
133       -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
138       -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
145       -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
150              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
155              See also section Secure connections.
156
157       -encoding encodingname
158
159       -eofchar eofspec
160
161       -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

SECURE CONNECTIONS

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
172
173                  # Load and initialize tls
174                  package require tls
175                  tls::init -cafile /path/to/ca/cert -keyfile ...
176
177                  # Create a connector with secure socket setup,
178                  transfer::connect C -socketcmd tls::socket ...
179                  ...
180
181

TLS SECURITY CONSIDERATIONS

183       This package uses the TLS package to handle the security for https urls
184       and other socket connections.
185
186       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
192       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
200
201                  package require tls
202                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
203
204                  ... your own application code ...
205
206

BUGS, IDEAS, FEEDBACK

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
214       When proposing code changes, please provide unified diffs, i.e the out‐
215       put of diff -u.
216
217       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

KEYWORDS

223       active, channel, connection, passive, secure, ssl, tls, transfer
224

CATEGORY

226       Transfer module
227
229       Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
230
231
232
233
234tcllib                                0.2                 transfer::connect(n)
Impressum