pop3(3tcl)
NAME
pop3 - Tcl client for POP3 email protocol
SYNOPSIS
package require Tcl 8.4 package require pop3 ?1.9? ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username password ?port? ::pop3::config chan ::pop3::status chan ::pop3::last chan ::pop3::retrieve chan startIndex ?endIndex? ::pop3::delete chan startIndex ?endIndex? ::pop3::list chan ?msg? ::pop3::top chan msg n ::pop3::uidl chan ?msg? ::pop3::capa chan ::pop3::close chan ______________________________________________________________________________
DESCRIPTION
The pop3 package provides a simple Tcl-only client library for the POP3 email protocol as specified in RFC 1939 [http://www.rfc- editor.org/rfc/rfc1939.txt]. It works by opening the standard POP3 socket on the server, transmitting the username and password, then providing a Tcl API to access the POP3 protocol commands. All server errors are returned as Tcl errors (thrown) which must be caught with the Tcl catch command.
TLS SECURITY CONSIDERATIONS
This package uses the TLS package to handle the security for https urls
and other socket connections.
Policy decisions like the set of protocols to support and what ciphers
to use are not the responsibility of TLS, nor of this package itself
however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set
of servers the application will talk to as well.
For example, in light of the recent POODLE attack
[http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-
exploiting-ssl-30.html] discovered by Google many servers will disable
support for the SSLv3 protocol. To handle this change the applications
using TLS must be patched, and not this package, nor TLS itself. Such
a patch may be as simple as generally activating tls1 support, as shown
in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
API
::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd
cmdprefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host
username password ?port?
Open a socket connection to the server specified by host,
transmit the username and password as login information to the
server. The default port number is 110, which can be overridden
using the optional port argument. The return value is a channel
used by all of the other ::pop3 functions.
The command recognizes three options
-msex boolean
Setting this option tells the package that the server we
are talking to is an MS Exchange server (which has some
oddities we have to work around). The default is False.
-retr-mode retr|list|slow
The retrieval mode determines how exactly messages are
read from the server. The allowed values are retr, list
and slow. The default is retr. See ::pop3::retrieve for
more information.
-socketcmd cmdprefix
This option allows the user to overide the use of the
builtin socket command with any API-compatible command.
The envisioned main use is the securing of the new
connection via SSL, through the specification of the
command tls::socket. This command is specially recognized
as well, changing the default port of the connection to
995.
-stls boolean
Setting this option tells the package to secure the
connection using SSL or TLS. It performs STARTTLS as
described in IETF RFC 2595, it first opens a normal,
unencrypted connection and then negotiates a SSLv3 or
TLSv1 connection. If the connection cannot be secured,
the connection will be closed and an error will be
returned
-tls-callback stls-callback-command
This option allows the user to overide the tls::callback
used during the -stls SSL/TLS handshake. See the TLS
manual for details on how to implement this callback.
::pop3::config chan
Returns the configuration of the pop3 connection identified by
the channel handle chan as a serialized array.
::pop3::status chan
Query the server for the status of the mail spool. The status
is returned as a list containing two elements, the first is the
number of email messages on the server and the second is the
size (in octets, 8 bit blocks) of the entire mail spool.
::pop3::last chan
Query the server for the last email message read from the spool.
This value includes all messages read from all clients
connecting to the login account. This command may not be
supported by the email server, in which case the server may
return 0 or an error.
::pop3::retrieve chan startIndex ?endIndex?
Retrieve a range of messages from the server. If the endIndex
is not specified, only one message will be retrieved. The
return value is a list containing each message as a separate
element. See the startIndex and endIndex descriptions below.
The retrieval mode determines how exactly messages are read from
the server. The mode retr assumes that the RETR command delivers
the size of the message as part of the command status and uses
this to read the message efficiently. In mode list RETR does not
deliver the size, but the LIST command does and we use this to
retrieve the message size before the actual retrieval, which can
then be done efficiently. In the last mode, slow, the system is
unable to obtain the size of the message to retrieve in any
manner and falls back to reading the message from the server
line by line.
It should also be noted that the system checks upon the
configured mode and falls back to the slower modes if the above
assumptions are not true.
::pop3::delete chan startIndex ?endIndex?
Delete a range of messages from the server. If the endIndex is
not specified, only one message will be deleted. Note, the
indices are not reordered on the server, so if you delete
message 1, then the first message in the queue is message 2
(message index 1 is no longer valid). See the startIndex and
endIndex descriptions below.
startIndex
The startIndex may be an index of a specific message
starting with the index 1, or it have any of the
following values:
start This is a logical value for the first message in
the spool, equivalent to the value 1.
next The message immediately following the last message
read, see ::pop3::last.
end The most recent message in the spool (the end of
the spool). This is useful to retrieve only the
most recent message.
endIndex
The endIndex is an optional parameter and defaults to the
value "-1", which indicates to only retrieve the one
message specified by startIndex. If specified, it may be
an index of a specific message starting with the index
"1", or it may have any of the following values:
last The message is the last message read by a POP3
client, see ::pop3::last.
end The most recent message in the spool (the end of
the spool).
::pop3::list chan ?msg?
Returns the scan listing of the mailbox. If parameter msg is
given, then the listing only for that message is returned.
::pop3::top chan msg n
Optional POP3 command, not all servers may support this.
::pop3::top retrieves headers of a message, specified by
parameter msg, and number of n lines from the message body.
::pop3::uidl chan ?msg?
Optional POP3 command, not all servers may support this.
::pop3::uidl returns the uid listing of the mailbox. If the
parameter msg is specified, then the listing only for that
message is returned.
::pop3::capa chan
Optional POP3 command, not all servers may support this.
::pop3::capa returns a list of the capabilities of the server.
TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities.
See IETF RFC 2449.
::pop3::close chan
Gracefully close the connect after sending a POP3 QUIT command
down the socket.
SECURE MAIL TRANSFER
A pop3 connection can be secured with SSL/TLS by requiring the package
TLS and then using either the option -socketcmd or the option -stls of
the command pop3::open. The first method, option -socketcmd, will
force the use of the tls::socket command when opening the connection.
This is suitable for POP3 servers which expect SSL connections only.
These will generally be listening on port 995.
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -socketcmd tls::socket \\
$thehost $theuser $thepassword
...
The second method, option -stls, will connect to the standard POP3 port
and then perform an STARTTLS handshake. This will only work for POP3
servers which have this capability. The package will confirm that the
server supports STARTTLS and the handshake was performed correctly
before proceeding with authentication.
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -stls 1 \\
$thehost $theuser $thepassword
...
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category pop3 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.
KEYWORDS
email, mail, pop, pop3, rfc 1939, secure, ssl, tls
CATEGORY
Networking
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
