diff options
Diffstat (limited to 'doc/howto.https.docbook')
| -rw-r--r-- | doc/howto.https.docbook | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/doc/howto.https.docbook b/doc/howto.https.docbook new file mode 100644 index 0000000..c097e0c --- /dev/null +++ b/doc/howto.https.docbook @@ -0,0 +1,248 @@ +<!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 + <m2crypto>/demo/https.howto/. Additionally, a number of programs from + <m2crypto>/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> + |