Introduction

History

pyOpenSSL was originally created by Martin Sjögren because the SSL support in the standard library in Python 2.1 (the contemporary version of Python when the pyOpenSSL project was begun) was severely limited. Other OpenSSL wrappers for Python at the time were also limited, though in different ways.

Later it was maintained by Jean-Paul Calderone who among other things managed to make pyOpenSSL a pure Python project which the current maintainers are very grateful for.

Over the time the standard library’s ssl module improved, never reaching the completeness of pyOpenSSL’s API coverage. Despite PEP 466 many useful features remain Python 3-only and pyOpenSSL remains the only alternative for full-featured TLS code across all noteworthy Python versions from 2.7 through 3.5 and PyPy.

Development

pyOpenSSL is collaboratively developed by the Python Cryptography Authority (PyCA) that also maintains the low-level bindings called cryptography.

Current maintainer and release manager is Hynek Schlawack.

Contributing

First of all, thank you for your interest in contributing to pyOpenSSL! This project has no company backing its development therefore we’re dependent on help by the community.

Filing bug reports

Bug reports are very welcome. Please file them on the GitHub issue tracker. Good bug reports come with extensive descriptions of the error and how to reproduce it. Reporters are strongly encouraged to include an short, self contained, correct example.

Patches

All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, pyca/pyopenssl. These pull requests should satisfy the following properties:

Code

  • The pull request should focus on one particular improvement to pyOpenSSL. Create different pull requests for unrelated features or bugfixes.

  • Code should follow PEP 8, especially in the “do what code around you does” sense. Follow OpenSSL naming for callables whenever possible is preferred.

  • Pull requests that introduce code must test all new behavior they introduce as well as for previously untested or poorly tested behavior that they touch.

  • Pull requests are not allowed to break existing tests. We usually don’t comment on pull requests that are breaking the CI because we consider them work in progress. Please note that not having 100% code coverage for the code you wrote/touched also causes our CI to fail.

Documentation

When introducing new functionality, please remember to write documentation.

  • New functions and methods should have a docstring describing what they do, what parameters they takes, what types those parameters are, and what they return.

    def dump_publickey(type, pkey):
        """
        Dump a public key to a buffer.
    
        :param type: The file type (one of :data:`FILETYPE_PEM` or
            :data:`FILETYPE_ASN1`).
        :param PKey pkey: The PKey to dump.
    
        :return: The buffer with the dumped key in it.
        :rtype: bytes
        """
    

    Don’t forget to add an .. auto(function|class|method):: statement to the relevant API document found in doc/api/ to actually add your function to the Sphinx documentation.

  • Do not use :py: prefixes when cross-linking (Python is default). Do not use the generic :data: or :obj:. Instead use more specific types like :class:, :func: or :meth: if applicable.

  • Pull requests that introduce features or fix bugs should note those changes in the CHANGELOG.rst file. Please add new entries to the top of the current Changes section followed by a line linking to the relevant pull request:

    - Added ``OpenSSL.crypto.some_func()`` to do something awesome.
      [`#1 <https://github.com/pyca/pyopenssl/pull/1>`_]
    
  • Use semantic newlines in reStructuredText files (files ending in .rst).

Review

Finally, pull requests must be reviewed before merging. This process mirrors the cryptography code review process. Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged.

Pull requests are merged by members of PyCA. They should, of course, keep all the requirements detailed in this document as well as the pyca/cryptography merge requirements in mind.

The final responsibility for the reviewing of merged code lies with the person merging it. Since pyOpenSSL is a sensitive project from a security perspective, reviewers are strongly encouraged to take this review and merge process very seriously.

Finding Help

If you need any help with the contribution process, you’ll find us hanging out at #cryptography-dev on Freenode IRC. You can also ask questions on our mailing list.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Security

If you feel that you found a security-relevant bug that you would prefer to discuss in private, please send us a GPG-encrypted e-mail.

The maintainer can be reached at hs@ox.cx and his GPG key ID is 0xAE2536227F69F181 (Fingerprint: C2A0 4F86 ACE2 8ADC F817  DBB7 AE25 3622 7F69 F181). Feel free to cross-check this information with Keybase.