path: root/doc/howto.https.docbook

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY m2-blurb SYSTEM "m2_blurb.docbook">
]>

<article>
    <articleinfo>
    <title>HOWTO: Programming HTTPS in Python with M2Crypto</title>

    <author>
      <firstname>Pheng Siong</firstname>
      <surname>Ng</surname>
      <affiliation>
        <address><email>ngps@netmemetic.com</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>2001</year>
      <year>2002</year>
      <holder>Ng Pheng Siong.</holder>
    </copyright>

    <revhistory>
      <revision>
      <revnumber>$Revision: 1.1 $</revnumber>
      <date>$Date: 2003/06/22 16:41:18 $</date>
      </revision>
    </revhistory>
    </articleinfo>

    <sect1 id="introduction">
    <title>Introduction</title>
    &m2-blurb;

    <para>This document demonstrates programming HTTPS clients and servers
    with M2Crypto.
    </para>
    </sect1>

    <sect1 id="https"> 
    <title>Programming HTTPS</title> 
    <para>HTTPS - HTTP over SSL/TLS 
    <citation>RFC XXXX</citation> - provides a XXX
    </para> 

    <para>Python has had good HTTP support for several years now. M2Crypto's
    HTTPS functionality mostly adopts the interfaces in Python's HTTP modules.
    </para>

    <para>In this HOWTO, we shall begin with writing HTTPS clients. Now, to
    test the HTTPS clients we write, we need a HTTPS server; conversely, to
    test our HTTPS servers, we need a HTTPS client. ;-) </para>

    <para> All the programs we write in this HOWTO are found in
    &lt;m2crypto&gt;/demo/https.howto/. Additionally, a number of programs from
    &lt;m2crypto&gt;/demo/ssl are also copied into this directory; their names are
    prefixed by "orig". These "orig" programs shall be our known-working HTTPS
    clients and servers.  </para> </sect1>

    <sect1 id="ssldump"> 
    <title>ssldump</title> 

    <para>ssldump "is an SSLv3/TLS network protocol analyser. It identifies
    TCP connections on the chosen network interface and attempts to interpret
    them as SSLv3/TLS traffic. When it identifies SSLv3/TLS traffic, it
    decodes the records and displays them in a textual form to stdout. If
    provided with the appropriate keying material, it will also decrypt the
    connections and display the application data traffic.  
    </para>
    
    <para>
    If linked with OpenSSL, ssldump can display certificates in decoded form
    and decrypt traffic (provided that it has the appropriate keying
    material)."
    </para>

    <para>ssldump is written by Eric Rescorla.
    </para>
    </sect1>

    <sect1 id="orig-https-srv.py">
    <title>orig_https_srv.py</title>
    <para>orig_https_srv.py is an enhanced version of SimpleHTTPServer that
    features the following: </para>

    <itemizedlist mark=opencircle>
    <listitem>
    <para>Works over HTTPS.
    </para>
    </listitem>

    <listitem>
    <para>Uses one thread per connection.
    </para>
    </listitem>

    <listitem>
    <para>Generates directory listings.
    </para>
    </listitem>

    <listitem>
    <para>Displays SSL handshaking and SSL session info.
    </para>
    </listitem>

    <listitem>
    <para>Performs SSL renegotiation when a magic URL is requested.
    </para>
    </listitem>
    </itemizedlist>

    <para>Invoke orig_https_srv.py thusly:
    </para>

    <screen>
    <userinput>
$ python orig_https_srv.py
    </userinput>
    </screen>

    <para>By default, orig_https_srv.py serves HTTPS on port 9443.
    </para>
    </sect1>

    <sect1 id="history"> 
    <title>A bit of history</title> 
    <para> M2Crypto was created during the time of Python 1.5, which features
    a module httplib providing client-side HTTP functionality. M2Crypto sports
    a httpslib based on httplib.
    </para>

    <para>
    Beginning with version 2.0, Python's socket module provided
    (rudimentary) SSL support. Also in the same version, httplib was
    enhanced with class HTTPConnection, which is more sophisticated than
    the old class HTTP, and HTTPSConnection, which does HTTPS.
    </para>

    <para>
    Subsequently, M2Crypto.httpslib grew a compatible (but not identical)
    class HTTPSConnection. 
    </para>
    
    <para>
    The primary interface difference between the two HTTPSConnection
    classes is that M2Crypto's version accepts an M2Crypto.SSL.Context
    instance as a parameter, whereas Python 2.x's SSL support does not
    permit Pythonic control of the SSL context.
    </para>

    <para> Within the implementations, Python's
    <classname>HTTPSConnection</classname> employs a
    <classname>FakeSocket</classname> object, which collects all input from
    the SSL connection before returning it to the application as a
    <classname>StringIO</classname> buffer, whereas M2Crypto's
    <classname>HTTPSConnection</classname> uses a buffering
    <classname>M2Crypto.BIO.IOBuffer</classname> object that works over the
    underlying M2Crypto.SSL.Connection directly.  </para> </sect1>

    <sect1 id="simple-get"> 
    <title>A simple HTTPS GET client using M2Crypto.httpslib</title> 

    <para> Let us now look at possibly the simplest HTTPS client we will ever
    write.
    </para>
    </sect1>

    <sect1 id="simple-post"> 
    <title>A simple HTTPS-POST client</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="threaded-cli"> 
    <title>A multi-threaded HTTPS client</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="async-cli"> 
    <title>An asynchronous HTTPS client</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="session-reuse"> 
    <title>Re-using SSL session </title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="threaded-reuse-cli"> 
    <title>A multi-threaded session-reusing client</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="async-reuse-cli"> 
    <title>An asynchronous session-reusing client</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="verify-server-cert"> 
    <title>Verifying server certificate</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="using-client-cert"> 
    <title>Using client certificate</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="simple-https-server"> 
    <title>SimpleHTTPSServer</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="medusa-https-server"> 
    <title>A Medusa-based HTTPS server</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="verify-client-cert"> 
    <title>Client certificate-based authentication</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="control-session-reuse"> 
    <title>Controlling session reuse</title> 
    <para>XXX
    </para>
    </sect1>

    <sect1 id="id-kludge">
    <title></title>
    <para>
    <literal>$Id: howto.https.docbook,v 1.1 2003/06/22 16:41:18 ngps Exp $</literal>
    </para>
    </sect1>
</article>