cryptography

The cryptography library maintains a strong API stability policy for all documented APIs and behaviors.

What is guaranteed:

• Public APIs will not be removed or renamed without providing a compatibility alias.
• The behavior of existing APIs will not change.

What is NOT guaranteed:

• Internal object details like dir(obj) or obj.__dict__ may change when new features are added.
• Objects are not guaranteed to be pickleable; pickled objects from one version may not be loadable in future versions.
• Sub-classing is not supported unless explicitly documented; behavior regarding sub-classes is not guaranteed to be stable.
• Development versions are not covered by this policy.

Security Exception: To resolve security issues or harden the library against attacks, the stability policy may be violated.

To improve performance and memory safety, pyca/cryptography is actively migrating its functionality from OpenSSL to Rust.

Key migration benefits include:

• Performance: Moving X.509 certificate parsing to Rust resulted in a 10x performance improvement over OpenSSL 3. Moving public key parsing to Rust improved end-to-end X.509 path validation by 60%.
• Memory Safety: By using Rust for parsing and X.509 operations, the library avoids several OpenSSL-related CVEs and leverages Rust's memory safety guarantees.

Currently, the library uses a hybrid approach: pure-Rust for parsing and X.509 operations, and OpenSSL for providing core cryptographic algorithms.

Supported Versions

cryptography provides security support for the main branch and the most recent release.

OpenSSL Updates

cryptography statically links OpenSSL in binary distributions for Windows, macOS, and Linux. To avoid shipping insecure software, cryptography will release a new version whenever OpenSSL releases a security or bug fix. It is strongly recommended to upgrade to the latest version as soon as a new release is announced.

The cryptography library is organized into two distinct layers:

1. Recipes Layer: High-level, safe cryptographic recipes (e.g., fernet, x509) that require little to no configuration. These are recommended for most use cases to avoid common cryptographic errors.
2. Hazmat (Hazardous Materials) Layer: Low-level cryptographic primitives located in the cryptography.hazmat package. These require in-depth knowledge of cryptographic concepts and can be dangerous if used incorrectly. Documentation for these primitives will always include a warning admonition.

The cryptography library provides several Message Authentication Code (MAC) algorithms to ensure data integrity and authenticity.

Recommendation: It is strongly recommended to use HMAC for most use cases unless you have a specific requirement for another algorithm.

Supported MAC algorithms include:

• hmac (Recommended)
• cmac
• poly1305

The cryptography_vectors package includes example test files for FIPS 186-2 ECDSA validation. These files are structured as follows:

• .rsp files: These are response files formatted specifically for CAVS (Cryptographic Algorithm Validation Service) validation.
• SigGen.txt: This file contains values for ECDSA signature generation. To calculate the signature components r and s according to the X9.62 standard, you will need the additional values provided in this file:
  • d: The private key.
  • k: The random value used in calculating the signature (r, s) (refer to ANS X9.62).

The cryptography_vectors package provides two types of CCM (Counter with CBC-MAC) example files for testing:

1. Response files (.rsp): These contain properly formatted CAVS (Cryptographic Algorithm Validation Suite) response files.
2. DVPT text files (DVPT{128/192/256}.txt): These contain the same values as the corresponding .rsp files but include additional diagnostic information. For failed test cases, the reason for failure is provided in parentheses following the result (e.g., Result = Fail (2 - CT changed)). Note that this extra information is not part of a standard CAVS response format.

When writing C bindings, follow these style requirements:

• Parameters: Do not name parameters in function signatures (e.g., long f(long);), unless they are inside a struct.
• No Arguments: Always include void if a function takes no arguments (e.g., long f(void);).
• Line Wrapping: Wrap lines at 80 characters.
• Spacing: Include a space after commas between parameters.
• Comments: Use C-style /* */ comments; do not use C++-style //.
• Constants: Do not use #define for values. Instead, assign them to appropriate types using static const (e.g., static const int SOME_VALUE;).

A Rust toolchain is only required during the build phase of cryptography. It is not required to use the library at runtime.

For Docker deployments, use a multi-stage Dockerfile. Install the Rust toolchain in the build stage to compile the package, then copy only the necessary artifacts to the final runtime image. This keeps the runtime image lightweight and secure by excluding the Rust compiler and build tools.

Key derivation functions (KDFs) derive bytes suitable for cryptographic operations from passwords or other data sources using a pseudo-random function (PRF).

Common use cases include:

• Cryptographic key derivation: Deriving a key suitable for use as input to an encryption algorithm (often called key stretching). Examples include using PBKDF2HMAC or HKDF.
• Password storage: Using computationally intensive algorithms that are demanding on both computational and memory resources to make brute-force attacks difficult.