M2Crypto

M2Crypto is the most complete Python wrapper for OpenSSL featuring RSA, DSA, DH, HMACs, message digests, symmetric ciphers (including AES); SSL functionality to implement clients and servers; HTTPS extensions to Python's httplib, urllib, and xmlrpclib; unforgeable HMAC'ing AuthCookies for web session management; FTP/TLS client and server; S/MIME; ZServerSSL: A HTTPS server for Zope and ZSmime: An S/MIME messenger for Zope. M2Crypto can also be used to provide SSL for Twisted.

M2Crypto's unit tests cover over 80% of the Python code.

The original M2Crypto homepage is at http://sandbox.rulemaker.net/ngps/m2/. It hasn't been updated since M2Crypto 0.13.1 release.

Discuss M2Crypto on comp.lang.python newsgroup or python-list mailinglist. You can also get questions answered on stackoverflow.com (please tag questions with m2crypto tag). M2Crypto used to be discussed on the public python-crypto mailing list, but it is no longer the preferred forum. See http://listserv.surfnet.nl/archives/python-crypto.html for archives and subscription information.

M2Crypto was started and mostly developed by Ng Pheng Siong. The current maintainer is Heikki Toivonen (heikki@osafoundation.org). Heikki's blog contains updates on M2Crypto depevelopment. Patches gracefully accepted, but please file bugs and attach the patches as attachments to the bugs. See below for Bugzilla information.

OSAF is providing limited hosting to the M2Crypto project - see below for details.

Cryptography Export Notice

This software is subject to the U.S. Export Administration Regulations and other U.S. law, and may not be exported or re-exported to certain countries (currently Cuba, Iran, Libya, North Korea, Sudan and Syria) or to persons or entities prohibited from receiving U.S. exports (including Denied Parties, Specially Designated Nationals, and entities on the Bureau of Industry and Security Entity List or involved with missile technology or nuclear, chemical or biological weapons).

Donations

If you would like to offer monetary support, you can make a tax-deductible (in the United States) donation to Open Source Applications Foundation, which is providing hosting for M2Crypto.

Downloads

0.21.1:

• M2Crypto-0.21.1.tar.gz
• svn co http://svn.osafoundation.org/m2crypto/tags/0.21.1 m2crypto-0.21.1

Contributed Builds

These are provided by volunteers, untested by M2Crypto author. Feel free to add contributed build links. Please mention the configuration (platform, python version, openssl version, your name and preferably also your email address). You need to register on this wiki to be able to edit.

• M2Crypto-0.21.1-py2.7-macosx-10.7-intel.egg by John Randolph (compiled with OS X 10.7: i686-apple-darwin11-llvm-gcc-4.2, Python 2.7, swig 2.0.2, OpenSSL 0.9.7)
• M2Crypto-0.21.1-py2.5-macosx-10.5-i386.egg by John Randolph (compiled with setuptools, MacOSX 10.5, Python 2.5, OpenSSL 0.9.7).
• M2Crypto-0.21.1-py2.6-macosx-10.6-universal.egg by John Randolph (compiled with setuptools, MacOSX 10.6, Python 2.6, OpenSSL 0.9.8).
• M2Crypto-0.21.1.win32-py2.7.msi by Csaba Tóth (compiled with MSVC2008 32 bit against OpenSSL 1.0.0c), MSI Installer version.
• M2Crypto-0.21.1.win32-py2.6.exe by Flier Lu (compiled with Mingw 32bit against openssl-1.0.0d, Python 2.6), EXE Installer version.
• M2Crypto-0.20.2-py2.6-linux-x86_64.egg by Jerome Collette (compiled with GCC 4.4.5 against OpenSSL 0.9.8), 'bdist_egg' version.
• M2Crypto-0.20.2.win32-py2.7.exe by MaliciousWizard (compiled with MSVC2008 against OpenSSL 0.9.8o), 'bdist_wininst' version.
• M2Crypto-0.20.2-py2.7-win32.egg by MaliciousWizard (compiled with MSVC2008 against OpenSSL 0.9.8o), 'bdist_egg' version.
• M2Crypto-0.20.2.win32.zip by MaliciousWizard (compiled with MSVC2008 against OpenSSL 0.9.8o), 'bdist' version.
• M2Crypto-0.19.1.win32-py2.6.exe by KeLLey (compiled with MinGW(gcc-3.4.5) against OpenSSL 0.9.8k, dll's included(depend on MSVCR90.dll,zlib available))
• M2Crypto-0.19.1.win32-py2.5.exe by KeLLey (compiled with MinGW(gcc-3.4.5) against OpenSSL 0.9.8k, dll's included(depend on MSVCR71.dll,zlib available))
• M2Crypto-0.19.win32-py2.5.exe by Mikko Hiltunen (compiled with MinGW against OpenSSL 0.9.8i, dll:s included)
• M2Crypto-0.18.win32-py2.4.exe by Eli Golovinsky (includes OpenSSL 0.9.8e binaries)
• M2Crypto-0.18.2.win32-py2.5.exe by Mikko Hiltunen (compiled with MinGW against OpenSSL 0.9.8g, dll:s included)
• M2Crypto-0.18.2-py2.5-macosx-10.5-i386.egg by Florent Aide (MacosX^? 10.5 egg compiled against OpenSSL 0.9.7l using Xcode 3.0 toolbox. ie: GCC 4.0.1)

Requirements

0.21.1:

• Python 2.3 or newer
  • m2urllib2 requires Python 2.4 or newer
• OpenSSL 0.9.7 or newer
  • Some optional new features will require OpenSSL 0.9.8 or newer
• SWIG 1.3.28 or newer required for building
  • SWIG 1.3.30 or newer may be required with Python 2.5 or newer and Python 2.4 with Py_ssize_t patches

Documentation

Recommended reading for anyone using OpenSSL or any OpenSSL wrappers: "Network Security with OpenSSL" by John Viega, Matt Messier and Pravir Chandra, ISBN 059600270X.

SSL in Python 2.6 is a good overview of the status of SSL in Python 2.6 and later.

How to build M2Crypto on Windows by Eli Golovinsky

There are some old, minimal HOWTO documents in the doc/ directory:

• Creating your own CA with OpenSSL
• Programming S/MIME in Python with M2Crypto
• Programming SSL in Python with M2Crypto
• ZServerSSL HOWTO

Generated API Documentation

Unit tests and demo scripts are also useful learning tools. You can also easily generate API documentation for M2Crypto using Epydoc.

1. Install Epydoc 3.0.1 or later, setuptools and optionally Graphviz
2. cd M2Crypto source tree
3. python setup build test
4. epydoc --no-private --config=epydoc.conf

This will create api/ directory under doc/. Open the index.html file in your browser.

Epydoc takes a lot of optional arguments and options in the config file that you may wish to experiment with.

OpenSSL documentation can be used as well, you just have to figure out the actual OpenSSL APIs called.

Finally, here is a comparison of Python cryptography modules (PDF) which includes a nice feature list for M2Crypto.

Extras: Tools and Modules

The demo directory contains some hidden gems. For example, there is the certdata2pem.py script that can convert the certdata.txt file from the NSS project into PEM format, suitable for M2Crypto consumption. This is an easy way to get root certificates for programs using M2Crypto.

The socklib.py is a little hack for cases where you are using a 3rd party library which invokes Python's insecure socket.ssl. By importing socklib first and calling socklib.setSSLContextFactory, you can make the 3rd party library use the secure SSL from M2Crypto.

Subversion source repository

Anonymous access to the repository:

• svn co http://svn.osafoundation.org/m2crypto/trunk m2crypto

Subversion over SSH (with write access) to the repository:

• svn co svn+ssh://svn.osafoundation.org/svn/m2crypto/trunk m2crypto

Browse the Subversion repository

• http://svn.osafoundation.org/m2crypto/
• viewcv
• websvn (check the RSS feeds for changes)

Bugzilla database

Please note that OSAF's Bugzilla installation has several products, and M2Crypto is but one of them. Take that into account when you search for bugs and file new bugs.

List all open M2crypto bugs.

File an M2Crypto bug (advanced).

https://bugzilla.osafoundation.org/

Tinderbox

Continuous builds and tests are done with the help of Tinderbox2.

Contributing

If you have suggestions for new ideas, or have found bugs, or have implemented some features or fixed bugs, the way to interact is via Bugzilla. All code contributions should be patches against the svn trunk, and attached to appropriate bugs. All code changes should come with appropriate unit tests.

Roadmap for M2Crypto some-non-compatible-release

What kind of release would we get if backwards compatibility was not an issue? Maybe something like:

• All error conditions should raise an exception, no more need to check return values for error conditions.
• All M2Crypto exceptions should inherit from M2CryptoException.
• All OpenSSL errors should results in M2CryptoException-derived exception (currently some plain Exceptions)

Some major items that might be beyond the scope:

• Get rid of SWIG

Release Checklist

• Announce approximate release schedule on python-crypto mailinglist, leaving room for at least 4 one week betas before the final bits.
• Before first beta create branch; create beta and release tags from branch
• Run unit tests for bits about to be packaged
• Check out fresh source with svn export, create tar.gz tarball on homepage, update sections and links
• Upload release to cheeseshop.python.org with PGP signature
• Announce
  • beta
    • python-crypto
    • blog
  • release
    • python-crypto
    • freshmeat.net
    • blog
    • comp.lang.python and comp.lang.python.announce

Projects Using M2Crypto

Feel free to update!

Related Projects

• pyOpenSSL
• python-nss
• TLS Lite

FAQ

Code

Q: I get an error initializing SSL.Context:

Traceback (most recent call last):
  ...
  File ".../M2Crypto/SSL/Context.py", line 43, in __init__
    map()[long(self.ctx)] = self
ValueError: invalid literal for long(): _480e1008_p_SSL_CTX 

A: Your version of SWIG is too old. The minimum required is 1.3.28.

Q: I get a typedef error during build:

_lib.h:5: error: redefinition of typedef 'Py_ssize_t'

A: It has been reported this was a problem with SWIG 1.3.30rc1, but that it works in 1.3.30 and newer.

Q: M2Crypto crashes/does not work in my multi-threaded application.

A: You need to call M2Crypto.threading.init() to initialize threading mode before use, and cleanup() to end threading support.

Q: I have OpenSSL in non-standard location, how can I build M2Crypto?

A: build_ext takes --openssl option to specify openssl directory prefix. However, there have been some reports that this is not always enough, and you need to also explicitly specify --library-dirs and --include-dirs options. So the full build and install command would be something like: python setup.py build_ext --openssl=<openssl prefix> --library-dirs=<openssl prefix>/lib --include-dirs=<openssl prefix>/include build install.

Q: I still can't build on a Fedora Core -based system, any workarounds?

A: Use the fedora_setup.sh wrapper script: ./fedora_setup.sh [setup.py options]

General

Q: Why is OSAF providing limited hosting to M2Crypto?

A: M2Crypto did not have public source repository nor bug database, which made it hard to contribute to it and keep track of issues. M2crypto is an integral part of OSAF's Chandler application and we have made and will continue to make changes to it, but we did not want to fork M2Crypto. We believe everyone will benefit by working on and improving the same official version.

Q: Will you host M2Crypto permanently?

A: We'll provide hosting as long as needed and/or we are able to do so. If some other hosting arrangement makes sense, we can switch to that in the future.

Q: My project X does not have a public source archive or Bugzilla, can you provide hosting for it?

A: Short answer: no. We do not intend to become a project hosting facility. We made an exception with M2Crypto because we use it in Chandler and intend to make lots of changes. If your project is used in Chandler and we feel like we would need to modify it a lot, we could consider it. But even then we'd ask you to first see if you could use some public project hosting facility like SourceForge.

Q: How can I edit this page?

A: You need to register on this wiki to be able to edit.

• M2Crypto-0.20.2-py2.6-linux-x86_64.egg: (compiled with GCC 4.4.5 against OpenSSL 0.9.8), 'bdist_egg' version.

• M2Crypto-0.21.1.win32-py2.7.msi: Built with Python 2.7.1 32 bit, OpenSSL 1.0.0c, MSVC2008, MSI Installer version

• M2Crypto-0.21.1-py2.5-macosx-10.5-i386.egg: M2Crypto-0.21.1-py2.5-macosx-10.5-i386.egg

• M2Crypto-0.21.1.win32-py2.6.exe: compiled with Mingw 32bit against openssl-1.0.0d, Python 2.6

• openssl-1.0.0d-win32.zip: OpenSSL 1.0.0d compiled with VS2010 for Win32