Registry / http-networking / requests-pkcs12

requests-pkcs12

JSON →
library1.27pypypi✓ verified 25d ago

The requests-pkcs12 library extends the popular Python `requests` library to add native support for client-side PKCS#12 (often .p12 or .pfx) certificates. It provides a clean implementation by creating a custom `TransportAdapter` and `SSLContext`, avoiding monkey patching or the use of unencrypted temporary files. Currently at version 1.27, it serves as a robust transitional solution until `requests` incorporates direct PKCS#12 support. The project appears to be actively maintained, with frequent updates.

pip install requests-pkcs12
INSTALL
IMPORT
SIG · REQUESTS-PKCS12
R
requests-pkcs12
http-networkingpythonv1.27
Install
3.0s avg
Import
602ms
Disk
37MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.27 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.622s · 38.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.0s · import 0.582s · 39MB
37MB installed
● package 37MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

get
from requests_pkcs12 import get
For simple, one-off GET requests using PKCS#12.
post
from requests_pkcs12 import post
For simple, one-off POST requests using PKCS#12.
Pkcs12Adapter
from requests_pkcs12 import Pkcs12Adapter
For integrating PKCS#12 support into a requests.Session.
Session
from requests import Session
Needed when using Pkcs12Adapter with requests sessions.

This quickstart demonstrates how to perform both one-off and session-based HTTP requests using a PKCS#12 client certificate. It requires a `.p12` file and its corresponding password. For security, these values are retrieved from environment variables, or fall back to placeholders for demonstration. Remember to replace `PKCS12_FILENAME`, `PKCS12_PASSWORD`, and `TARGET_URL` with your actual certificate path, password, and the secure endpoint you wish to access.

import os from requests import Session from requests_pkcs12 import Pkcs12Adapter, get # --- Example 1: Simple one-off request --- # Requires a client certificate file (e.g., clientcert.p12) and its password. # Ensure 'pkcs12_filename' points to a valid .p12 file # and 'pkcs12_password' is correct for testing. PKCS12_FILENAME = os.environ.get('PKCS12_FILENAME', 'clientcert.p12') # Placeholder PKCS12_PASSWORD = os.environ.get('PKCS12_PASSWORD', 'your_pkcs12_password') # Placeholder TARGET_URL = os.environ.get('TARGET_URL', 'https://example.com/secure_endpoint') # Placeholder try: print(f"\nAttempting one-off GET to {TARGET_URL}...") r = get( TARGET_URL, pkcs12_filename=PKCS12_FILENAME, pkcs12_password=PKCS12_PASSWORD, verify=True # Always verify server certificates in production! ) r.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx) print(f"One-off GET successful! Status: {r.status_code}") # print(r.text) except Exception as e: print(f"One-off GET failed: {e}") # --- Example 2: Using with a requests Session (recommended for multiple requests) --- try: print(f"\nAttempting session-based GET to {TARGET_URL}...") with Session() as s: s.mount( 'https://', Pkcs12Adapter( pkcs12_filename=PKCS12_FILENAME, pkcs12_password=PKCS12_PASSWORD ) ) # The 'verify' parameter can be set on the session or per request. # It is crucial for verifying the server's identity. r_session = s.get(TARGET_URL, verify=True) r_session.raise_for_status() print(f"Session-based GET successful! Status: {r_session.status_code}") # print(r_session.text) except Exception as e: print(f"Session-based GET failed: {e}") # Note: For actual testing, replace 'clientcert.p12' and 'your_pkcs12_password' # with a real PKCS#12 file path and its password. You might need a dummy # server that requires client certificate authentication for full testing.
Debug
Known issues
gotchaDo not combine `pkcs12_filename` or `pkcs12_data` arguments with the standard `requests` `cert` parameter. The `Pkcs12Adapter` handles both certificate and key internally; using `cert` simultaneously can lead to conflicts or incorrect behavior.
fix
Only use `pkcs12_filename` and `pkcs12_password` (or `pkcs12_data` and `pkcs12_password`) provided by `requests-pkcs12`. Continue to use the `verify` parameter for server-side certificate verification.
affects: All versions
gotchaWhile `requests-pkcs12` handles client certificate authentication, proper server-side certificate verification (via the `verify` parameter) is still crucial. Failing to set `verify=True` (or providing a CA bundle) can leave your application vulnerable to Man-in-the-Middle attacks.
fix
Always use `verify=True` and ensure your system's CA certificates are up-to-date, or provide a path to a trusted CA bundle if connecting to non-standard CAs.
affects: All versions
deprecatedThe `requests-pkcs12` library is explicitly stated as a 'transitional solution' by its authors. Future versions of the main `requests` library might eventually incorporate native PKCS#12 support, potentially deprecating the need for this external library.
fix
Keep an eye on the official `requests` library roadmap and changelogs for native PKCS#12 support. Migrating to built-in functionality would be recommended if it becomes available.
affects: All versions
gotcha`requests-pkcs12` depends on `cryptography`, which has evolving Python version support. For instance, `cryptography` versions 44.0.0+ (released November 2024) deprecated Python 3.7 support. Ensure your Python environment meets `cryptography`'s and `requests-pkcs12`'s minimum requirements.
fix
Upgrade your Python version to 3.8 or newer. Check the `cryptography` changelog for specific version compatibility details. `requests-pkcs12` itself requires `>=3.7`.
affects: Users on Python < 3.8 with cryptography >= 44.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests_pkcs12'
The `requests-pkcs12` library has not been installed in your Python environment.
fix
Run `pip install requests-pkcs12` to install the library.
ValueError: Could not decrypt PFX; perhaps bad password?
The password provided for the PKCS#12 certificate file is incorrect, or the .p12/.pfx file is corrupted or not a valid PKCS#12 format.
fix
Verify that the PKCS#12 file's password is correct and that the file itself is valid. If testing, ensure no extra characters or incorrect encoding.
FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/certificate.p12'
The specified path to the PKCS#12 certificate file (`.p12` or `.pfx`) is incorrect, the file does not exist at that location, or the Python process lacks read permissions.
fix
Ensure the file path is correct, the file exists at the specified location, and your application has sufficient read permissions for the file.
requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:XXXX)
This often indicates a problem with the server's SSL certificate (e.g., self-signed, untrusted CA), or the server is rejecting the client certificate provided by the PKCS#12 file.
fix
If the server's certificate is untrusted, either set `verify=False` (for development, not recommended for production) or configure a trusted CA bundle. If the issue is client certificate rejection, ensure the server is configured to accept the PKCS#12 client certificate you are providing.
Upgrade
Version history
1.27latest on PyPI · released Sep 7, 2025
Audit
Dependencies
cryptographyrequiredRequired for parsing PKCS#12 files and creating SSL contexts.
requestsrequiredThe core HTTP library that requests-pkcs12 extends.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
requests-pkcs12 — pip install requests-pkcs12 · libregistry