pyOpenSSL Documentation

pyOpenSSL is a high-level Python wrapper around a subset of the OpenSSL library. Its core features include:

• SSL.Connection objects: These wrap the methods of Python's portable sockets.
• Python-written callbacks.
• Extensive error-handling mechanisms that mirror OpenSSL's native error codes.

The OpenSSL package provides a high-level Python interface to the functions available in the OpenSSL library. It is organized into two primary functional modules:

1. OpenSSL.crypto: Used for cryptographic operations (e.g., generating keys, handling certificates, hashing).
2. OpenSSL.ssl: Used for SSL/TLS communication, including managing SSL contexts and handling secure connections.

To use the library, you must have the OpenSSL module available in your Python environment.

import OpenSSL

The SSL.Connection class wraps a transport object to provide SSL/TLS capabilities. Instead of requiring a standard socket.socket object, SSL.Connection accepts any socket-like transport object.

Requirements for the transport object:

• Basic Requirement: The object must implement a fileno() method that returns a file descriptor valid at the C level (compatible with system read and write calls).
• For connect() or accept(): If you intend to use the .connect() or .accept() methods on the SSL.Connection instance, the underlying transport object must also implement these methods.

Method Delegation:

SSL.Connection uses a delegation pattern. If a method is called on the SSL.Connection object that is not defined within the SSL wrapper, the call is automatically passed through to the underlying transport object.

pyOpenSSL uses CalVer (Calendar Versioning) in the YY.MINOR.MICRO format.

Unlike Semantic Versioning (SemVer), the major version number represents the year of release and is not an indicator of breaking changes. You should check the changelog for information regarding breaking changes or deprecations.

To install the standard version of pyOpenSSL, use pip install pyopenssl.

$ pip install pyopenssl

To install pyOpenSSL in editable mode with testing dependencies for development purposes, navigate to the root directory of your checkout and run pip install -e .[test].

$ pip install -e .[test]

The Python Cryptographic Authority (pyca) strongly recommends using the pyca/cryptography library instead of pyOpenSSL whenever possible.

Guidance:

• If your use case is anything other than establishing a TLS connection, you should migrate to cryptography and remove pyOpenSSL from your dependencies.

pyOpenSSL maintains a strong backward compatibility policy. When breaking changes are necessary, the project follows a strict lifecycle:

1. Announcement: Breaking changes are first announced in the changelog.
2. Deprecation Period: The old behavior will continue to work but will raise a DeprecationWarning for one year.
3. Removal: The breaking change is finalized and the old behavior is removed, following a second announcement in the changelog.

Because of this policy, updating to newer versions is generally safe.

To install pyOpenSSL, use pip. It is recommended to install it within a virtual environment to avoid conflicts with system packages.

pip install pyOpenSSL

The OpenSSL.crypto module is pending deprecation. It is highly recommended to use pyca/cryptography instead, as it provides a more complete set of cryptographic primitives and a more powerful X509 API.

If you must interoperate between the two libraries, you can convert objects using the following methods on X509, CRL, and PKey objects:

• to_cryptography(): Converts an OpenSSL object to a cryptography object.
• from_cryptography(): Creates an OpenSSL object from a cryptography object.

An SSL.Session object represents a set of connection parameters that can be reused to speed up subsequent connections (session resumption).

Sessions are tied to the Context that created them. When using Connection.set_session(), pyOpenSSL ensures the session is only reused with a compatible Context to prevent security issues.