Home

Awesome

oscrypto

A compilation-free, always up-to-date encryption library for Python that works on Windows, OS X, Linux and BSD. Supports the following versions of Python: 2.6, 2.7, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10 and pypy.

GitHub Actions CI CircleCI PyPI

Supported Operating Systems

The library integrates with the encryption library that is part of the operating system. This means that a compiler is never needed, and OS security updates take care of patching vulnerabilities. Supported operating systems include:

OS X 10.6 will not be supported due to a lack of available cryptographic primitives and due to lack of vendor support.

Features

Currently the following features are implemented. Many of these should only be used for integration with existing/legacy systems. If you don't know which you should, or should not use, please see Learning.

The feature set was largely driven by the technologies used related to generating and validating X.509 certificates. The various CBC encryption schemes and KDFs are used to load encrypted private keys, and the various RSA padding schemes are part of X.509 signatures.

For modern cryptography not tied to an existing system, please see the Modern Cryptography section of the docs.

Please note that this library does not include modern block modes such as CTR and GCM due to lack of support from both OS X and OpenSSL 0.9.8.

Why Another Python Crypto Library?

In short, the existing cryptography libraries for Python didn't fit the needs of a couple of projects I was working on. Primarily these are applications distributed to end-users who aren't programmers, that need to handle TLS and various technologies related to X.509 certificates.

If your system is not tied to AES, TLS, X.509, or related technologies, you probably want more modern cryptography.

Depending on your needs, the cryptography package may be a good (or better) fit.

Some things that make oscrypto unique:

Some downsides include:

Related Crypto Libraries

oscrypto is part of the modularcrypto family of Python packages:

Current Release

1.3.0 - changelog

Dependencies

¹ On Linux, ctypes.util.find_library() is used to located OpenSSL. Alpine Linux does not have an appropriate install by default for find_library() to work properly. Instead, oscrypto.use_openssl() must be called with the path to the OpenSSL shared libraries.

Installation

pip install oscrypto

License

oscrypto is licensed under the terms of the MIT license. See the LICENSE file for the exact license text.

Documentation

oscrypto documentation

Continuous Integration

Various combinations of platforms and versions of Python are tested via:

Testing

Tests are written using unittest and require no third-party packages.

Depending on what type of source is available for the package, the following commands can be used to run the test suite.

Git Repository

When working within a Git working copy, or an archive of the Git repository, the full test suite is run via:

python run.py tests

To run only some tests, pass a regular expression as a parameter to tests.

python run.py tests aes

To run tests multiple times, in order to catch edge-case bugs, pass an integer to tests. If combined with a regular expression for filtering, pass the repeat count after the regular expression.

python run.py tests 20
python run.py tests aes 20

Backend Options

To run tests using a custom build of OpenSSL, or to use OpenSSL on Windows or Mac, add use_openssl after run.py, like:

python run.py use_openssl=/path/to/libcrypto.so,/path/to/libssl.so tests

To run tests forcing the use of ctypes, even if cffi is installed, add use_ctypes after run.py:

python run.py use_ctypes=true tests

To run tests using the legacy Windows crypto functions on Windows 7+, add use_winlegacy after run.py:

python run.py use_winlegacy=true tests

Internet Tests

To skip tests that require an internet connection, add skip_internet after run.py:

python run.py skip_internet=true tests

PyPi Source Distribution

When working within an extracted source distribution (aka .tar.gz) from PyPi, the full test suite is run via:

python setup.py test

Test Options

The following env vars can control aspects of running tests:

Force OpenSSL Shared Library Paths

Setting the env var OSCRYPTO_USE_OPENSSL to a string in the form:

/path/to/libcrypto.so,/path/to/libssl.so

will force use of specific OpenSSL shared libraries.

This also works on Mac and Windows to force use of OpenSSL instead of using native crypto libraries.

Force Use of ctypes

By default, oscrypto will use the cffi module for FFI if it is installed.

To use the slightly slower, but more widely-tested, ctypes FFI layer, set the env var OSCRYPTO_USE_CTYPES=true.

Force Use of Legacy Windows Crypto APIs

On Windows 7 and newer, oscrypto will use the CNG backend by default.

To force use of the older CryptoAPI, set the env var OSCRYPTO_USE_WINLEGACY=true.

Skip Tests Requiring an Internet Connection

Some of the TLS tests require an active internet connection to ensure that various "bad" server certificates are rejected.

To skip tests requiring an internet connection, set the env var OSCRYPTO_SKIP_INTERNET_TESTS=true.

Package

When the package has been installed via pip (or another method), the package oscrypto_tests may be installed and invoked to run the full test suite:

pip install oscrypto_tests
python -m oscrypto_tests

Development

To install the package used for linting, execute:

pip install --user -r requires/lint

The following command will run the linter:

python run.py lint

Support for code coverage can be installed via:

pip install --user -r requires/coverage

Coverage is measured by running:

python run.py coverage

To install the packages requires to generate the API documentation, run:

pip install --user -r requires/api_docs

The documentation can then be generated by running:

python run.py api_docs

To install the necessary packages for releasing a new version on PyPI, run:

pip install --user -r requires/release

Releases are created by:

Existing releases can be found at https://pypi.python.org/pypi/oscrypto.

CI Tasks

A task named deps exists to download and stage all necessary testing dependencies. On posix platforms, curl is used for downloads and on Windows PowerShell with Net.WebClient is used. This configuration sidesteps issues related to getting pip to work properly and messing with site-packages for the version of Python being used.

The ci task runs lint (if flake8 is available for the version of Python) and coverage (or tests if coverage is not available for the version of Python). If the current directory is a clean git working copy, the coverage data is submitted to codecov.io.

python run.py deps
python run.py ci