eGenix.com: eGenix.com pyOpenSSL Distribution - Python OpenSSL Interface (original) (raw)

The eGenix.com pyOpenSSL Distribution is an easy-to-install version of the pyOpenSSL Python interface to the open-source OpenSSL library. Complete with with source, OpenSSL libraries, CA bundles and binaries for Windows, Linux, Mac OS X and FreeBSD.

Version: 0.13.16

Introduction

The eGenix.com pyOpenSSL Distribution includes everything you need to get started with OpenSSL in Python.

It comes with an easy-to-use installer that includes the most recent OpenSSL library versions in pre-compiled form, as well as the most recent certificate authority (CA) root bundles.

pyOpenSSL

pyOpenSSLis an open-source Python add-on that allows writing SSL-aware networking applications as as certificate management tools. It uses the OpenSSL library as performant and robust SSL engine.

Our eGenix.com pyOpenSSL distribution is based on the last pyOpenSSL release 0.13 which was still using a custom OpenSSL Python wrapper written in C. Newer versions of pyOpenSSL have switched to a cffi based approach which requires additional support libraries and is slower.

Please note that we sometimes add additional functionality to the pyOpenSSL package, which is only available in our distribution. See the documentation and change log for details.

OpenSSL

OpenSSL is an open-source implementation of the SSL protocol.

Due to security breaches in OS-level OpenSSL library distributions (e.g. the Debian OpenSSL "fix") and the general problem of old OpenSSL libraries on systems, we have chosen to integrate the most current versions of the OpenSSL libraries directly with the package - on Windows and all supported Unix platforms, as well as Mac OS X.

The current version of OpenSSL shipped with the eGenix.com pyOpenSSL Distribution is:

OpenSSL 1.0.2j

In previous releases, we also added the OpenSSL version number to the package version. Since causes very long version numbers, we have dropped the OpenSSL version starting with 0.13.5 and will only increase the main version number from now on. In the future, we plan to switch to a new version scheme that is compatible with our normal version number scheme for products.

To avoid patent issues, we have excluded the following algorithms from OpenSSL via its config options: IDEA, MDC2 and RC5. We also removed the Kerberos5 support, since it's not needed for SSL-based communication, and SSLv2 support, since this protocol has been broken for years and should no longer be in use. To help mitigate the CRIME attack, we have also disabled TLS compression support in our library builds. This may result in problems with other libraries which link against these APIs. pyOpenSSL itself does not use them.

Certificate Authority Certificates (CA Bundles)

In addition to OpenSSL library binaries, we always include the most recent certificate authority (CA) certificate bundles derived from the from Mozilla Firefox browser code base as CRT file with the distribution and also include a helper moduleOpenSSL.ca_bundle to easily access these embedded CA certificate lists for verification purposes.

The CA bundles are updated with each new release of the eGenix pyOpenSSL distribution, but we also make them available as separate download.

Features

Easy-to-use interface.
Easy Installation.
All Inclusive.
Comes with built-in root certificate authority (CA) certificate bundles which are compatible with Firefox
No External Dependencies: does not need or rely on system OpenSSL libraries.
Stable, robust and portable.
Supports Python 2.4 - 2.7.
Available for Windows, Linux, FreeBSD and Mac OS X with both 32- and 64-bit support.
Free: to use and redistribute.
Open-Source

System Requirements

The binary packages we provide for the various platforms include the pyOpenSSL modules as well as the OpenSSL libraries inside the OpenSSL Python package, so there's no need to download and install OpenSSL libraries separately.

When using Python 2.5 or later, there are no additional requirements. Python 2.4 on Windows also works out of the box with the installers we provide.

If you are using Python 2.4 on Unix, you additionally need the current eGenix.com mx Base Distributioninstalled (>= version 3.1.0), since this is needed to be able to load the shared OpenSSL libraries directly from the package directory.

Due to a bug in Python 2.7.9 which results in the ctypes module not compiling on FreeBSD, you may need the current eGenix.com mx Base Distributioninstalled on that platform as well.

Compiling From Source

If you want to build the distribution from source, e.g. to include/exclude patented algorithms, you will need a compiled version of the OpenSSL Toolkit together with header files. We used the following config options for the version included in the distribution:

./config shared no-idea no-mdc2 no-rc5 no-krb5 no-comp no-ssl2

After setting the SSL environment variable to the location of your OpenSSL installation and adjusting the version number of the distribution, you can then compile and install the distribution using:

python setup.py install

See the egenix_pyopenssl.py source code for details.

The source distribution includes pre-compiled versions of the OpenSSL libs and header files for Windows - compiled with VC7.1 for Python 2.4 and 2.5 and VC9 for Python 2.6 and 2.7. Please see the openssl-win32/ and openssl-win64/ directories for details and the scripts we used to build those binaries.

License

The eGenix.com pyOpenSSL Distribution itself is made available under the terms & conditions of our eGenix.com Public License Agreement 1.1.0 which is an Open Source license based on the CNRI Python license.

In simple words, you are free to use the software without paying fees or royalties as long as you give proper attribution and keep the license document together with the software. Please see the license document for details and consult a lawyer if you have legal questions.

The eGenix.com pyOpenSSL Distribution includes these third-party products:

pyOpenSSL which is licensed under the Apache License Version 2.0
OpenSSL which is licensed under the OpenSSL Toolkit License
zlib which is licensed under the zlib License (if at all, zlib is only included in pre-built OpenSSL binaries)

Please see our eGenix.com Third-Party License Guide 2.0 for details or check the source code distribution which comes with all licenses and disclaimers.

Documentation

The following documentation is available for eGenix pyOpenSSL:

eGenix pyOpenSSL Distribution Documentation

The manual includes pointers to the OpenSSL, the pyOpenSSL API documentation, as well as the eGenix additions to pyOpenSSL and notes relevant to using the package in applications. All APIs live in the top-level OpenSSL Python package.

Download

We provide downloads for the following platforms.

Please note:

First, please identify which Python version you have installed and whether you need a UCS2 or UCS4 build (see below for how this can be done). We have setup the default selections below to what you normally need for the platform's default Python installations.
If you are using Python 2.4 on Unix, you also need to install the current eGenix.com mx Base Distribution (>= version 3.1.0). This is not needed for Python 2.5 or later versions.
Since the eGenix.com pyOpenSSL Distribution contains cryptographic code, you will be asked to confirm to comply to the German and EU export regulations (which are based on of the Wassenaar Arrangement). Please make sure that downloading and using cryptography is legal in your country.
After successful download, please head on to the installation instructions below.

Windows (x86 - 32-bit):

Windows (x64 - 64-bit):

Linux (i686 - 32-bit):

Linux (x86_64 - 64-bit):

Mac OS X 10.4 and 10.5 (PPC + Intel x86 - Universal Binaries):

Mac OS X 10.6 and later (Intel x64):

FreeBSD (i386 - 32-bit):

FreeBSD (amd64 - 64-bit):

Source Code:

Easy Install / Setuptools / pip / zc.buildout:

If you want to use easy_install / setuptools / pip for installation, you can also use our egg builds of the packages. Please see the egg installation instructions below for details.

Other Platforms:

If you need distribution archives for platforms not mentioned here, please contact support@egenix.com for details. It is very likely that we can find a way to help you.

Python Unicode Version (UCS2 vs. UCS4)

On Unix it is important to know whether you need to download a distribution for a narrow Unicode build of Python (UCS2) or a wide version (UCS4).

Most Unixes ship with wide Python builds these days (including RedHat and SuSE). In order to make sure, please run the following command which will tell you what kind of Python installation you have:

python -c "import sys;print(sys.maxunicode<66000)and'UCS2'or'UCS4'"

If you get errors such as "unresolved symbol PyUnicodeUCS2_AsEncodedString" when trying to load an extension from the distribution, you have likely installed an archive for a wrong Unicode version.

Included Root CA Certificate Bundles

If you just want to upgrade one of the included CA bundle files OpenSSL/ca-bundle*.crt, you can also download the files directly:

Installation

The eGenix pyOpenSSL Distribution can be installed using multiple way. This section goes into detail regarding the various possible approaches.

Web Installer

The web installer is available for download on the product's Python Package Index (PyPI) page. Installation tools will automatically pick up this installer when used without any extra options or URLs.

The web installer will then determine the installation platform, select the right binary download package and install the corresponding prebuilt archive for you. If the web installer fails to find a suitable binary, please try one of the other methods explained below and report the problem to our support team.

Note that when using Python 2.4 on Unix, you will also need to install the eGenix.com mx Base Distribution before proceeding with the following steps as explained in the download section.

Examples:

setuptools' easy_install:

easy_install egenix-pyopenssl

pip installer:

pip install egenix-pyopenssl

zc.buildout configuration manager:

builout.cfg:
eggs += egenix-pyopenssl

Download and unzip the installer from PyPI and run:

cd egenix-pyopenssl-0.13.16
python setup.py install

Confirmation of Export Regulations

IMPORTANT NOTICE:
Since the eGenix.com pyOpenSSL Distribution contains cryptographic code, you will need to comply to the German and EU export regulations for such code (which are based on of the Wassenaar Arrangement). Please make sure that downloading and using cryptography is legal in your country.

The web installer will ask you to confirm that you have read, understood and agree to comply to the terms outlined on our crypto download page prior to starting the download of the prebuilt archive for your installation platform (which are hosted on our servers in Germany). The installer package itself does not contain any cryptography code, so export regulations do not apply to the download from PyPI (which is hosted in the US and elsewhere).

This confirmation normally requires entering "ok" at the command line. Since this doesn't work well in e.g. testing environments, we have added to additional possibilities to pass this confirmation to the web installer:

via a --crypto-confirm command line switch, which you can pass to python setup.py install, e.g.

python setup.py install --crypto-confirm
via setting an environment variable EGENIX_CRYPTO_CONFIRM to the value "ok", which is useful for installers such as pip and easy_install, which indirectly call the web installer, e.g.

export EGENIX_CRYPTO_CONFIRM=ok
pip install egenix-pyopenssl

Windows Installer

Installation using the Windows installers is straight forward: just double-click on the installer EXE or MSI file and follow the instructions.

Both installers register the distribution with the Windows software registry, so you can easily uninstall the distribution should you require to do so.

With the new MSI installer you also have the option to run the installer without the GUI or to integrate it into an automatic installation process. Please see the MSI installer documentation on the Python web-site for details.

To uninstall the distribution, please use the standard Windows software registry.

Prebuilt Distribution Installation

To reduce the number of binaries that we have to create for each release, we have adapted a new generic distribution format that works on all Python platforms: the Prebuilt Distribution Format.

Technically, this format is a standard Python distutils distribution, but with only the build/ directory and without the source tree.

System-wide Installation

In order to install such a distribution, please follow these instructions:

Download and unzip the archive into a temporary directory
Change into the distribution directory
Run the following command using the Python interpreter with which you intend to work (this could be the default one, or an application specific one depending on your needs):
sudo python setup.py install
On Windows and some other platforms that don't have sudo, please run the above without sudo as administrator or root.

The distribution will then be installed into the standard directory for Python extensions of your Python installation (usually the site-packages/ subdirectory of the Python standard library directory).

To uninstall, follow the same steps as above, but use the command uninstall instead:

sudo python setup.py uninstall

User Installation

You will need to be able to sudo on the target machine or know the root password for the above to work. If you don't have permission to install packages as root, you can still install the distribution into a local directory, e.g. ~/lib/python by using the following installation command:

python setup.py install --home=/home/user/

This will install the distribution into the directory /home/user/lib/python/. In order to have Python see this directory and make it useable for import, you have to adjust the PYTHONPATH environment variable to include this directory, e.g.

export PYTHONPATH=/home/user/lib/python

To see all the possible installation options, run the install script using the help options:

python setup.py install --help

To uninstall, follow the same steps as above, but use the command uninstall instead:

sudo python setup.py uninstall --home=/home/user/

Egg Distribution Installation

If you prefer to use easy_install or another egg-file based installer such as zc.buildout for your Python packages, you can also download the egg distributions we make available for the package and install those.

Automatic Download

The egg archives we provide are made available through two PyPI-style indexes which the egg tools setuptools/easy_install/pip/zc.buildout can access to automatically download and install the right egg archive.

By downloading the egg distributions for the eGenix.com pyOpenSSL Distribution you confirm that you have read, understood and agree to comply to the terms outlined on our crypto download page.

There are two indexes, one for Python UCS2 builds (these include Windows builds):

https://downloads.egenix.com/python/index/ucs2/

and one for Python UCS4 builds:

https://downloads.egenix.com/python/index/ucs4/

If you are using a Python UCS2 build, then you can install the egg archives using this command:

easy_install -i https://downloads.egenix.com/python/index/ucs2/
egenix-pyopenssl

For UCS4 builds, please use this command:

easy_install -i https://downloads.egenix.com/python/index/ucs4/
egenix-pyopenssl

The command line parameters for other tools such as pip are similar. Please consult their documentation for details.

Manual Installation

In order to install an egg distribution with easy_install, please follow these instructions:

Download the egg file into a temporary directory
Change into the temporary directory
Run the following command using the Python interpreter with which you intend to work (this could be the default one, or an application specific one depending on your needs):
sudo easy_install ./.egg
On Windows and some other platforms that don't have sudo, please run the above without sudo as administrator or root.

Please consult the easy_install documentation for details on how to uninstall egg files.

Source Code Installation

To install from source, please unzip the source archive and then run the following command in the distribution directory:

sudo python setup.py install

Please make sure that you are using the Python binary for which you want to install the distribution. The installer will then automatically choose the correct path for the installation.

If you don't have root permissions on the target machine, you can use the same approach as for the prebuilt distribution outlined above for a user installation in the /home/user/lib/python directory:

python setup.py install --home=/home/user/

Please remember to setup the PYTHONPATH to include the /home/user/lib/python directory:

export PYTHONPATH=/home/user/lib/python

Otherwise, Python won't see the new installation and thus won't be able to import it.

To uninstall, follow the same steps as above, but use the command uninstall instead of install.

Support

eGenix offers these support options:

Commercial Support

Professional level support for this product as well as all other eGenix products and Python itself is available directly from the developers at eGenix.com.

Consulting

eGenix.com offers professional consulting servicesfor all questions and tasks around this product, including customized modifications, help with integration and on-site problem solving. Please contact sales@egenix.com for details.

Free User Support

In order for our users to keep in touch and be able to help themselves, we have created the egenix-users user mailing list.

History & Changes

Please see the change log for details regarding changes to the distribution between releases.

Older versions of eGenix pyOpenSSL, which are still available:

Notices

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)