/usr/share/doc/python-m2crypto/howto.ssl.html is in python-m2crypto 0.21.1-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | <HTML
><HEAD
><TITLE
>HOWTO: Programming SSL in Python with M2Crypto</TITLE
>
</HEAD>
<BODY
CLASS="ARTICLE"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
>
<DIV
CLASS="TITLEPAGE"
><H1
CLASS="TITLE"
><A
NAME="AEN2"
>HOWTO: Programming SSL in Python with M2Crypto</A
></H1
>
<P>
Ng Pheng Siong (ngps@netmemetic.com) and Heikki Toivonen (heikki@osafoundation.org)
</P
><P
CLASS="COPYRIGHT"
>Copyright © 2001, 2002 by Ng Pheng Siong.</P
>
<P
CLASS="COPYRIGHT"
>Portions Copyright © 2006 by Open Source Applications Foundation.</P
>
</DIV>
<DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="INTRODUCTION"
>Introduction</A
></H1
><P
><A
HREF="http://chandlerproject.org/Projects/MeTooCrypto"
TARGET="_top"
>M2Crypto</A
>
is a <A
HREF="http://www.python.org"
TARGET="_top"
>Python</A
>
interface to <A
HREF="http://www.openssl.org"
TARGET="_top"
>OpenSSL</A
>. It makes
available to the Python programmer SSL functionality to implement clients
and servers, S/MIME v2, RSA, DSA, DH, symmetric ciphers, message digests and
HMACs.
</P
><P
>This document demonstrates programming HTTPS with M2Crypto.
</P
></DIV
>
<DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="history"
>A bit of history</A
></H1
>
<p> 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.
</p>
<p>
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.
</p>
<p>
Subsequently, M2Crypto.httpslib grew a compatible (but not identical)
class HTTPSConnection.
</p>
<p>
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.
</p>
<p> Within the implementations, Python's
<tt>HTTPSConnection</tt> employs a
<tt>FakeSocket</tt> object, which collects all input from
the SSL connection before returning it to the application as a
<tt>StringIO</tt> buffer, whereas M2Crypto's
<tt>HTTPSConnection</tt> uses a buffering
<tt>M2Crypto.BIO.IOBuffer</tt> object that works over the
underlying M2Crypto.SSL.Connection directly. </p>
<p>Since then M2Crypto has gained a Twisted wrapper that allows securing
Twisted SSL connections with M2Crypto.</p>
</DIV
>
<DIV CLASS="SECT1" id="secure" name="secure">
<H1 CLASS="SECT1">Secure SSL</H1>
<p>It is recommended that you read the book Network Security with OpenSSL by John Viega, Matt Messier and Pravir Chandra,
ISBN 059600270X.</p>
<p>Using M2Crypto does not automatically make an SSL connection secure. There are various steps that need to be made
before we can make that claim. Let's see how a simple client can establish a secure connection:</p>
<pre>
ctx = SSL.Context()
ctx.set_verify(SSL.verify_peer | SSL.verify_fail_if_no_peer_cert, depth=9)
if ctx.load_verify_locations('ca.pem') != 1: raise Exception('No CA certs')
s = SSL.Connection(ctx)
s.connect(server_address)
# Normal protocol (for example HTTP) commands follow
</pre>
<p>The first line creates an SSL context. The defaults allow any SSL version (except SSL version 2 which has known
weaknesses) and sets the allowed ciphers to secure ones.</p>
<p>The second line tells M2Crypto to perform certificate validation. The flags shown above are typical for clients,
and requires the server to send a certificate. The depth parameter tells how long certificate chains are allowed -
9 is pretty common default, although probably too long in practice.</p>
<p>The third line loads the allowed root (certificate authority or CA) certificates.
Most Linux distributions come with CA certificates in suitable format. You
could also download the <a href="http://mxr.mozilla.org/seamonkey/source//security/nss/lib/ckfw/builtins/certdata.txt?raw=1">certdata.txt</a>
file from the <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>
project and convert it
with the little M2Crypto utility script <a href="http://svn.osafoundation.org/m2crypto/trunk/demo/x509/certdata2pem.py">demo/x509/certdata2pem.py</a>.</p>
<p>The fourth line creates an SSL connection object with the secure context.</p>
<p>The fifth line connects to the server. During this time we perform the last security step: just after connection, but before
exchanging any data, we compare the commonName (or subjectAltName DNS field) field in the certificate the server returned to the
server address we tried to connect to. This happens automatically with SSL.Connection and the Twisted wrapper class, and anything
that uses those. In all other cases you must do the check manually. It is recommended you call the SSL.Checker to do the actual check.</p>
<p>SSL servers are different in that they typically do not require the client to send a certificate, so there is usually no certificate
checking. Also, it is typically useless to perform host name checking.</p>
</DIV>
<DIV CLASS="SECT1">
<H1 CLASS="SECT1">Code Samples</H1>
<p>The best samples of how to use the various SSL objects are in the tests directory, and the test_ssl.py file specifically.
There are additional samples in the demo directory, but they are not quaranteed to be up to date.</p>
<p>NOTE: The tests and demos
may not be secure as is. Use the information above on how to make them secure.</p>
</DIV>
<DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SSLDUMP"
>ssldump</A
></H1
>
<P>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.
</P>
<P>
If linked with OpenSSL, ssldump can display certificates in decoded form
and decrypt traffic (provided that it has the appropriate keying
material)."
</P>
<P>ssldump is written by Eric Rescorla.
</P>
</DIV
>
</BODY>
</HTML>
|