Compiler-free Python crypto library backed by the OS, supporting CPython and PyPy
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci Try caching homebrew on CircleCI Sep 4, 2018
dev
docs Fix docs typos Feb 24, 2018
oscrypto Fix compatibility with Python 3.7 Sep 1, 2018
requires
tests Use a local server for FTP testing Sep 3, 2018
.gitignore
.travis.yml
LICENSE Update copyright year Sep 4, 2018
appveyor.yml
changelog.md Version 0.19.1 Dec 14, 2017
codecov.json
readme.md Update readme section on deps task Apr 18, 2018
run.py Revamp CI integration Feb 1, 2017
setup.py
tox.ini Revamp CI integration Feb 1, 2017

readme.md

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 and pypy.

Travis CI AppVeyor CircleCI Codecov 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:

  • Windows XP or newer
  • OS X 10.7 or newer
    • Uses:
    • Tested on:
      • OS X 10.7
      • OS X 10.8
      • OS X 10.9
      • OS X 10.10
      • OS X 10.11
      • OS X 10.11 with OpenSSL 1.1.0
      • macOS 10.12
      • macOS 10.13 with LibreSSL 2.2.7
  • Linux or BSD
    • Uses one of:
    • Tested on:
      • Arch Linux with OpenSSL 1.0.2
      • OpenBSD 5.7 with LibreSSL
      • Ubuntu 10.04 with OpenSSL 0.9.8
      • Ubuntu 12.04 with OpenSSL 1.0.1
      • Ubuntu 15.04 with OpenSSL 1.0.1
      • Ubuntu 16.04 with OpenSSL 1.0.2 on Raspberry Pi 3 (armhf)

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.

  • TLSv1.x socket wrappers
    • Certificate verification performed by OS trust roots
    • Custom CA certificate support
    • SNI support (except Windows XP)
    • Session reuse via IDs/tickets
    • Modern cipher suites (RC4, DES, anon and NULL ciphers disabled)
    • Weak DH parameters and certificate signatures rejected
    • SSLv3 disabled by default, SSLv2 unimplemented
    • CRL/OCSP revocation checks consistenty disabled
  • Exporting OS trust roots
    • PEM-formatted CA certs from the OS for OpenSSL-based code
  • Encryption/decryption
    • AES (128, 192, 256), CBC mode, PKCS7 padding
    • AES (128, 192, 256), CBC mode, no padding
    • TripleDES 3-key, CBC mode, PKCS5 padding
    • TripleDes 2-key, CBC mode, PKCS5 padding
    • DES, CBC mode, PKCS5 padding
    • RC2 (40-128), CBC mode, PKCS5 padding
    • RC4 (40-128)
    • RSA PKCSv1.5
    • RSA OAEP (SHA1 only)
  • Generating public/private key pairs
    • RSA (1024, 2048, 3072, 4096 bit)
    • DSA (1024 bit on all platforms - 2048, 3072 bit with OpenSSL 1.x or Windows 8)
    • EC (secp256r1, secp384r1, secp521r1 curves)
  • Generating DH parameters
  • Signing and verification
    • RSA PKCSv1.5
    • RSA PSS
    • DSA
    • EC
  • Loading and normalizing DER and PEM formatted keys
    • RSA public and private keys
    • DSA public and private keys
    • EC public and private keys
    • X.509 Certificates
    • PKCS#12 archives (.pfx/.p12)
  • Key derivation
    • PBKDF2
    • PBKDF1
    • PKCS#12 KDF
  • Random byte generation

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:

  • No compiler needed, ever. No need to pre-compile shared libraries. Just distribute the Python source files, any way you want.
  • Uses the operating system's crypto library - does not require OpenSSL on Windows or OS X.
  • Relies on the operating system for security patching. You don't need to rebuild all of your apps every time there is a new TLS vulnerability.
  • Intentionally limited in scope to crypto primitives. Other libraries built upon it deal with certificate path validation, creating certificates and CSRs, constructing CMS structures.
  • Built on top of a fast, pure-Python ASN.1 parser, asn1crypto.
  • TLS functionality uses the operating system's trust list/CA certs and is pre-configured with sane defaults
  • Public APIs are simple and use strict type checks to avoid errors

Some downsides include:

  • Does not currently implement:
    • standalone DH key exchange
    • various encryption modes such as GCM, CCM, CTR, CFB, OFB, ECB
    • key wrapping
    • CMAC
    • HKDF
  • Non-TLS functionality is architected for dealing with data that fits in memory and is available all at once
  • Developed by a single developer

Related Crypto Libraries

oscrypto is part of the modularcrypto family of Python packages:

Current Release

0.19.1 - changelog

Dependencies

  • asn1crypto
  • Python 2.6, 2.7, 3.2, 3.3, 3.4, 3.5, 3.6, pypy

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

Testing

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

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

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

python run.py use_openssl=/path/to/libcrypto.dylib,/path/to/libssl.dylib 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:

  • Making a git tag in semver format

  • Running the command:

    python run.py release

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 avaiable 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