Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       pop3 - Tcl client for POP3 email protocol

SYNOPSIS

       package require Tcl  8.5

       package require pop3  ?1.10?

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

       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