Tcl Library Source Code

Documentation
Login
EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

pop3 - Tcl client for POP3 email protocol

Table Of Contents

SYNOPSIS

package require Tcl 8.5 9
package require pop3 ?1.11?

::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. 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 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

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. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

KEYWORDS

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

CATEGORY

Networking