Typing stubs for pyOpenSSL

Warnings

• breaking pyOpenSSL versions 24.2.1 and newer now include their own type annotations (a `py.typed` file). If you are using `pyOpenSSL>=24.2.1`, you should uninstall `types-pyopenssl` to prevent potential conflicts and ensure correct type checking behavior.
  Fix: If `pyOpenSSL>=24.2.1` is installed, run `pip uninstall types-pyopenssl`.
• gotcha As a stub-only package maintained in Typeshed, updates to `types-pyopenssl` might lag behind new releases of the main `pyOpenSSL` library. This can lead to 'stale' type annotations that don't cover the latest features or API changes in `pyOpenSSL`.
  Fix: Consider pinning `types-pyopenssl` to a specific version for stability, but be aware this might mean missing out on recent type improvements. Alternatively, check Typeshed's GitHub for the latest stub updates and contribute if you find missing annotations.
• gotcha The `types-pyopenssl` package is explicitly marked as 'partial' in Typeshed. This indicates that some parts of the `pyOpenSSL` API may not have complete or accurate type annotations, potentially leading to `Any` types or type checker errors in certain scenarios.
  Fix: If encountering missing or incorrect annotations, consult the `pyOpenSSL` runtime documentation. For long-term solutions, consider contributing improvements to the `pyOpenSSL` stubs in the Typeshed repository.
• gotcha Historically, stub packages from Typeshed, including `types-pyopenssl`, have sometimes had implicit or explicit dependencies on other stub packages (e.g., `types-cryptography`). If an upstream library (like `cryptography`) later includes its own `py.typed` file, this can cause conflicts or incorrect type resolution if both the upstream library's native stubs and the Typeshed stub package are present.
  Fix: Regularly review your project's `pip freeze` output and type checker logs for warnings about conflicting type providers. Remove redundant stub packages if the upstream library now provides its own `py.typed` file.

Install

• pip install types-pyopenssl Install types-pyopenssl

Imports

• Connection

  from OpenSSL.SSL import Connection

• X509

  from OpenSSL.crypto import X509

• PKey

  from OpenSSL.crypto import PKey

• Context

  from OpenSSL.SSL import Context

Quickstart

This quickstart demonstrates how to use `types-pyopenssl` by creating a self-signed certificate and private key, showcasing type annotations for common `pyOpenSSL` objects like `PKey` and `X509`. Type checkers would use these stubs to validate the types in such code.

from OpenSSL import crypto, SSL
from datetime import datetime, timedelta

def generate_self_signed_cert(
    common_name: str,
    country: str,
    state: str,
    city: str,
    organization: str,
    email: str,
    valid_days: int = 365,
) -> tuple[crypto.PKey, crypto.X509]:
    """
    Generates a self-signed certificate and private key objects with type hints.
    This demonstrates common pyOpenSSL types like PKey and X509.
    """
    # Generate a new key pair
    k = crypto.PKey()
    k.generate_key(crypto.TYPE_RSA, 2048)

    # Create a self-signed cert
    cert = crypto.X509()
    cert.get_subject().C = country
    cert.get_subject().ST = state
    cert.get_subject().L = city
    cert.get_subject().O = organization
    cert.get_subject().CN = common_name
    cert.get_subject().emailAddress = email
    cert.set_serial_number(1000)
    # Dates must be in UTC. Format 'YYYYMMDDHHMMSSZ'
    cert.gmtime_before = (datetime.utcnow() - timedelta(days=1)).strftime('%Y%m%d%H%M%SZ')
    cert.gmtime_after = (datetime.utcnow() + timedelta(days=valid_days)).strftime('%Y%m%d%H%M%SZ')
    cert.set_issuer(cert.get_subject())
    cert.set_pubkey(k)
    cert.sign(k, 'sha256')

    return k, cert

# Example usage with type-hinted variables
private_key: crypto.PKey
certificate: crypto.X509
private_key, certificate = generate_self_signed_cert(
    common_name="example.com",
    country="US",
    state="CA",
    city="San Francisco",
    organization="Example Org",
    email="admin@example.com"
)

print("Generated private key and certificate objects with type hints.")
print(f"Certificate subject CN: {certificate.get_subject().CN}")
print(f"Private key type: {private_key.type()}")