add SSL class submitted by Tino Lange

Doc/lib/libimaplib.tex

@@ -9,16 +9,18 @@
 % Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
 % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
 % Revised by ESR, January 2000.
+% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 
 
 \indexii{IMAP4}{protocol}
+\indexii{IMAP4_SSL}{protocol}
 
-This module defines a class, \class{IMAP4}, which encapsulates a
-connection to an IMAP4 server and implements a large subset of the
+This module defines two classes, \class{IMAP4} and \class{IMAP4_SSL}, which encapsulate a
+connection to an IMAP4 server and implement a large subset of the
 IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
 compatible with IMAP4 (\rfc{1730}) servers, but note that the
 \samp{STATUS} command is not supported in IMAP4.
 
-A single class is provided by the \module{imaplib} module:
+Two classes are provided by the \module{imaplib} module, \class{IMAP4} is the base class:
 
 \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
 This class implements the actual IMAP4 protocol.  The connection is
@@ -48,6 +50,17 @@ sub-class of \exception{IMAP4.error}.  Some other client now has write permissio
 and the mailbox will need to be re-opened to re-obtain write permission.
 \end{excdesc}
 
+There's also a subclass for secure connections:
+
+\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, keyfile\optional{, certfile}}}}}
+This is a subclass derived from \class{IMAP4} that connects over an SSL encrypted socket 
+(to use this class you need a socket module that was compiled with SSL support).
+If \var{host} is not specified, \code{''} (the local host) is used.
+If \var{port} is omitted, the standard IMAP4-over-SSL port (993) is used.
+\var{keyfile} and \var{certfile} are also optional - they can contain a PEM formatted
+private key and certificate chain file for the SSL connection. 
+\end{classdesc}
+
 The following utility functions are defined:
 
 \begin{funcdesc}{Internaldate2tuple}{datestr}
@@ -311,6 +324,13 @@ msgnums = M.search(None, '(FROM "LDJ")')
 \end{methoddesc}
 
 
+Instances of \class{IMAP4_SSL} have just one additional method:
+
+\begin{methoddesc}{ssl}{}
+  Returns SSLObject instance used for the secure connection with the server.
+\end{methoddesc}
+
+
 The following attributes are defined on instances of \class{IMAP4}:
 
 

Lib/imaplib.py

@@ -15,8 +15,9 @@ Public functions:       Internaldate2tuple
 # Authentication code contributed by Donn Cave <donn@u.washington.edu> June 1998.
 # String method conversion by ESR, February 2001.
 # GET/SETACL contributed by Anthony Baxter <anthony@interlink.com.au> April 2001.
+# IMAP4_SSL contributed by Tino Lange <Tino.Lange@isg.de> March 2002.
 
-__version__ = "2.50"
+__version__ = "2.51"
 
 import binascii, re, socket, time, random, sys
 
@@ -982,6 +983,78 @@ class IMAP4:
 
 
 
+class IMAP4_SSL(IMAP4):
+
+    """IMAP4 client class over SSL connection
+
+    Instantiate with: IMAP4_SSL([, host[, port[, keyfile[, certfile]]]])
+
+            host - host's name (default: localhost);
+            port - port number (default: standard IMAP4 SSL port).
+            keyfile - PEM formatted file that contains your private key (default: None);
+            certfile - PEM formatted certificate chain file (default: None);
+
+    for more documentation see the docstring of the parent class IMAP4.
+    """
+
+
+    def __init__(self, host = '', port = IMAP4_SSL_PORT, keyfile = None, certfile = None):
+        self.keyfile = keyfile
+        self.certfile = certfile
+        IMAP4.__init__(self, host, port)
+
+
+    def open(self, host, port):
+        """Setup connection to remote server on "host:port".
+        This connection will be used by the routines:
+            read, readline, send, shutdown.
+        """
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.sock.connect((self.host, self.port))
+        self.sslobj = socket.ssl(self.sock,self.keyfile, self.certfile) 
+
+
+    def read(self, size):
+        """Read 'size' bytes from remote."""
+        return self.sslobj.read(size)
+
+
+    def readline(self):
+        """Read line from remote."""
+        line = ""
+        while 1:
+            char = self.sslobj.read(1)
+            line += char
+            if char == "\n": return line
+
+
+    def send(self, data):
+        """Send data to remote."""
+        self.sslobj.write(data)
+
+
+    def shutdown(self):
+        """Close I/O established in "open"."""
+        self.sock.close()
+
+
+    def socket(self):
+        """Return socket instance used to connect to IMAP4 server.
+
+        socket = <instance>.socket()
+        """
+        return self.sock
+
+
+    def ssl(self):
+        """Return SSLObject instance used to communicate with the IMAP4 server.
+
+        ssl = <instance>.socket.ssl()
+        """
+        return self.sslobj
+
+
+
 class _Authenticator:
 
     """Private class to provide en/decoding