1pop3(n)                     Tcl POP3 Client Library                    pop3(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       pop3 - Tcl client for POP3 email protocol
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require pop3  ?1.10?
14
15       ::pop3::open  ?-msex  0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmd‐
16       prefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username
17       password ?port?
18
19       ::pop3::config chan
20
21       ::pop3::status chan
22
23       ::pop3::last chan
24
25       ::pop3::retrieve chan startIndex ?endIndex?
26
27       ::pop3::delete chan startIndex ?endIndex?
28
29       ::pop3::list chan ?msg?
30
31       ::pop3::top chan msg n
32
33       ::pop3::uidl chan ?msg?
34
35       ::pop3::capa chan
36
37       ::pop3::close chan
38
39______________________________________________________________________________
40

DESCRIPTION

42       The pop3 package provides a simple Tcl-only client library for the POP3
43       email  protocol  as  specified   in   RFC   1939   [http://www.rfc-edi
44       tor.org/rfc/rfc1939.txt].  It works by opening the standard POP3 socket
45       on the server, transmitting the username and password, then providing a
46       Tcl  API  to  access the POP3 protocol commands.  All server errors are
47       returned as Tcl errors (thrown) which must be caught with the Tcl catch
48       command.
49

TLS SECURITY CONSIDERATIONS

51       This package uses the TLS package to handle the security for https urls
52       and other socket connections.
53
54       Policy decisions like the set of protocols to support and what  ciphers
55       to  use  are  not the responsibility of TLS, nor of this package itself
56       however.  Such decisions are the responsibility of  whichever  applica‐
57       tion  is  using  the  package,  and are likely influenced by the set of
58       servers the application will talk to as well.
59
60       For example, in light of the recent POODLE  attack  [http://googleonli
61       nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
62       ssl-30.html] discovered by Google many servers will disable support for
63       the  SSLv3  protocol.  To handle this change the applications using TLS
64       must be patched, and not this package, nor TLS itself.   Such  a  patch
65       may  be as simple as generally activating tls1 support, as shown in the
66       example below.
67
68
69                  package require tls
70                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
71
72                  ... your own application code ...
73
74

API

76       ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow?  ?-socketcmd  cmd‐
77       prefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username
78       password ?port?
79              Open a socket connection to the server specified by host, trans‐
80              mit  the  username  and  password  as  login  information to the
81              server.  The default port number is 110, which can be overridden
82              using the optional port argument.  The return value is a channel
83              used by all of the other ::pop3 functions.
84
85              The command recognizes three options
86
87              -msex boolean
88                     Setting this option tells the package that the server  we
89                     are  talking  to is an MS Exchange server (which has some
90                     oddities we have to work around). The default is False.
91
92              -retr-mode retr|list|slow
93                     The retrieval mode determines how  exactly  messages  are
94                     read  from the server.  The allowed values are retr, list
95                     and slow.  The default is retr. See ::pop3::retrieve  for
96                     more information.
97
98              -socketcmd cmdprefix
99                     This  option  allows  the  user to overide the use of the
100                     builtin socket command with any  API-compatible  command.
101                     The  envisioned  main use is the securing of the new con‐
102                     nection via SSL, through the specification of the command
103                     tls::socket.  This  command  is  specially  recognized as
104                     well, changing the default port of the connection to 995.
105
106              -stls boolean
107                     Setting this option tells the package to secure the  con‐
108                     nection  using  SSL  or  TLS. It performs STARTTLS as de‐
109                     scribed in IETF RFC 2595, it first opens a normal,  unen‐
110                     crypted  connection  and then negotiates a SSLv3 or TLSv1
111                     connection. If the connection cannot be secured, the con‐
112                     nection will be closed and an error will be returned
113
114              -tls-callback stls-callback-command
115                     This  option allows the user to overide the tls::callback
116                     used during the -stls SSL/TLS handshake. See the TLS man‐
117                     ual for details on how to implement this callback.
118
119       ::pop3::config chan
120              Returns  the  configuration of the pop3 connection identified by
121              the channel handle chan as a serialized array.
122
123       ::pop3::status chan
124              Query the server for the status of the mail spool.   The  status
125              is  returned as a list containing two elements, the first is the
126              number of email messages on the server and  the  second  is  the
127              size (in octets, 8 bit blocks) of the entire mail spool.
128
129       ::pop3::last chan
130              Query the server for the last email message read from the spool.
131              This value includes all messages read from all clients  connect‐
132              ing  to the login account.  This command may not be supported by
133              the email server, in which case the server may return  0  or  an
134              error.
135
136       ::pop3::retrieve chan startIndex ?endIndex?
137              Retrieve  a  range of messages from the server.  If the endIndex
138              is not specified, only one message will be retrieved.   The  re‐
139              turn  value is a list containing each message as a separate ele‐
140              ment.  See the startIndex and endIndex descriptions below.
141
142              The retrieval mode determines how exactly messages are read from
143              the server. The mode retr assumes that the RETR command delivers
144              the size of the message as part of the command status  and  uses
145              this to read the message efficiently. In mode list RETR does not
146              deliver the size, but the LIST command does and we use  this  to
147              retrieve the message size before the actual retrieval, which can
148              then be done efficiently. In the last mode, slow, the system  is
149              unable to obtain the size of the message to retrieve in any man‐
150              ner and falls back to reading the message from the  server  line
151              by line.
152
153              It  should also be noted that the system checks upon the config‐
154              ured mode and falls back to the slower modes if  the  above  as‐
155              sumptions are not true.
156
157       ::pop3::delete chan startIndex ?endIndex?
158              Delete  a range of messages from the server.  If the endIndex is
159              not specified, only one message will be deleted.  Note, the  in‐
160              dices  are not reordered on the server, so if you delete message
161              1, then the first message in the queue is message 2 (message in‐
162              dex  1 is no longer valid).  See the startIndex and endIndex de‐
163              scriptions below.
164
165              startIndex
166                     The startIndex may be an  index  of  a  specific  message
167                     starting  with the index 1, or it have any of the follow‐
168                     ing values:
169
170                     start  This is a logical value for the first  message  in
171                            the spool, equivalent to the value 1.
172
173                     next   The message immediately following the last message
174                            read, see ::pop3::last.
175
176                     end    The most recent message in the spool (the  end  of
177                            the  spool).   This is useful to retrieve only the
178                            most recent message.
179
180              endIndex
181                     The endIndex is an optional parameter and defaults to the
182                     value "-1", which indicates to only retrieve the one mes‐
183                     sage specified by startIndex.  If specified, it may be an
184                     index  of a specific message starting with the index "1",
185                     or it may have any of the following values:
186
187                     last   The message is the last message  read  by  a  POP3
188                            client, see ::pop3::last.
189
190                     end    The  most  recent message in the spool (the end of
191                            the spool).
192
193       ::pop3::list chan ?msg?
194              Returns the scan listing of the mailbox.  If  parameter  msg  is
195              given, then the listing only for that message is returned.
196
197       ::pop3::top chan msg n
198              Optional  POP3  command,  not  all  servers  may  support  this.
199              ::pop3::top retrieves headers of a message, specified by parame‐
200              ter msg, and number of n lines from the message body.
201
202       ::pop3::uidl chan ?msg?
203              Optional  POP3  command,  not  all  servers  may  support  this.
204              ::pop3::uidl returns the uid listing of the mailbox. If the  pa‐
205              rameter msg is specified, then the listing only for that message
206              is returned.
207
208       ::pop3::capa chan
209              Optional  POP3  command,  not  all  servers  may  support  this.
210              ::pop3::capa  returns  a list of the capabilities of the server.
211              TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical  capabilities.
212              See IETF RFC 2449.
213
214       ::pop3::close chan
215              Gracefully  close  the connect after sending a POP3 QUIT command
216              down the socket.
217

SECURE MAIL TRANSFER

219       A pop3 connection can be secured with SSL/TLS by requiring the  package
220       TLS  and then using either the option -socketcmd or the option -stls of
221       the command pop3::open.  The  first  method,  option  -socketcmd,  will
222       force  the  use of the tls::socket command when opening the connection.
223       This is suitable for POP3 servers which expect  SSL  connections  only.
224       These will generally be listening on port 995.
225
226
227                package require tls
228                tls::init -cafile /path/to/ca/cert -keyfile ...
229
230                # Create secured pop3 channel
231                pop3::open -socketcmd tls::socket \
232                   $thehost $theuser $thepassword
233
234                ...
235
236       The second method, option -stls, will connect to the standard POP3 port
237       and then perform an STARTTLS handshake. This will only  work  for  POP3
238       servers  which  have this capability. The package will confirm that the
239       server supports STARTTLS and the handshake was performed correctly  be‐
240       fore proceeding with authentication.
241
242
243                package require tls
244                tls::init -cafile /path/to/ca/cert -keyfile ...
245
246                # Create secured pop3 channel
247                pop3::open -stls 1 \
248                   $thehost $theuser $thepassword
249
250                ...
251
252

BUGS, IDEAS, FEEDBACK

254       This  document,  and the package it describes, will undoubtedly contain
255       bugs and other problems.  Please report such in the  category  pop3  of
256       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
257       also report any ideas for enhancements you may have for either  package
258       and/or documentation.
259
260       When proposing code changes, please provide unified diffs, i.e the out‐
261       put of diff -u.
262
263       Note further that  attachments  are  strongly  preferred  over  inlined
264       patches.  Attachments  can  be  made  by  going to the Edit form of the
265       ticket immediately after its creation, and  then  using  the  left-most
266       button in the secondary navigation bar.
267

KEYWORDS

269       email, mail, pop, pop3, rfc 1939, secure, ssl, tls
270

CATEGORY

272       Networking
273
274
275
276tcllib                               1.10                              pop3(n)
Impressum