Registry / auth-security / scramp

scramp

JSON →
library1.4.17pypypi✓ verified 24d ago

scramp is a pure-Python implementation of the SCRAM (Salted Challenge Response Authentication Mechanism) authentication protocol. It supports various SCRAM mechanisms including SCRAM-SHA-1, SCRAM-SHA-256, SCRAM-SHA-512, SCRAM-SHA3-512, and their channel-binding ('-PLUS') variants. The library is currently at version 1.4.8 (as of January 6, 2026) and maintains an active development status with moderate release cadence.

pip install scramp
INSTALL
IMPORT
SIG · SCRAMP
S
scramp
auth-securitypythonv1.4.17
Install
1.6s avg
Import
171ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.17 · 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.176s · 18.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.166s · 19MB
17MB installed
● package 17MB
Code
Verified usage

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

ScramClient
from scramp import ScramClient
ScramMechanism
from scramp import ScramMechanism

This quickstart demonstrates a basic SCRAM authentication flow between a client and a server. The server initializes a `ScramMechanism` with the user's password to generate and store authentication information. The client then initiates the exchange using `ScramClient`, sending messages back and forth with the server until authentication is complete. The password for the server-side setup is retrieved from an environment variable `SCRAMP_TEST_PASSWORD` for security best practices.

import os from scramp import ScramClient, ScramMechanism # --- Server Side Setup --- username = "user@example.com" password = os.environ.get('SCRAMP_TEST_PASSWORD', 'test_password') # In a real app, load from secure config # Server mechanism (stores user's SCRAM data derived from password) # In a real application, auth_info would be retrieved from a database for the given username. server_mechanism = ScramMechanism(password=password) server_auth_info = server_mechanism.make_auth_info(password) # Derived data to store/retrieve for user print("Server: Initialized SCRAM mechanism and derived auth info.") # --- Client Side Exchange --- client = ScramClient( mechanisms=['SCRAM-SHA-256'], # Client offers preferred mechanisms username=username, password=password ) print(f"Client: Initialized SCRAM client for user '{username}'.") # 1. Client sends initial message client_first_message = client.build_client_first_message() print(f"Client: Sending client-first-message: {client_first_message}") # 2. Server receives client-first-message and builds server-first-message # In a real server, 'server_auth_info' would be loaded from a DB based on 'username' server_first_message = server_mechanism.build_server_first_message( client_first_message, server_auth_info ) print(f"Server: Sending server-first-message: {server_first_message}") # 3. Client receives server-first-message and builds client-final-message client_final_message = client.build_client_final_message(server_first_message) print(f"Client: Sending client-final-message: {client_final_message}") # 4. Server receives client-final-message and authenticates server_final_message = server_mechanism.build_server_final_message( client_final_message, server_auth_info ) if server_mechanism.authenticated: print("Server: Client authenticated successfully!") print(f"Server: Sending server-final-message: {server_final_message}") else: print("Server: Authentication failed.") # 5. Client receives server-final-message (for verification and channel binding) try: client.verify_server_final_message(server_final_message) print("Client: Server final message verified (authentication successful from client perspective).") except ValueError as e: print(f"Client: Server final message verification failed: {e}")
Debug
Known issues
breakingVersion 1.2.0 introduced backward-incompatible changes to the server-side API. This update modified how authentication information is handled to enable storing derived user data (e.g., in a database) and integrate with third-party hashing libraries like `passlib`.
fix
Review server-side implementations (e.g., `make_auth_info`, `build_server_first_message`) and adapt to the updated API, especially if custom authentication databases or hashing functions are used.
affects: >=1.2.0
gotcha`ScramClient` selects the most secure mechanism from a provided list. To use channel-binding (`-PLUS`) variants, the `channel_binding` parameter (a tuple of name and data) must be explicitly provided during `ScramClient` initialization. If `channel_binding` is `None`, `-PLUS` mechanisms will be filtered out.
fix
When initializing `ScramClient`, pass `channel_binding=('tls-server-end-point', your_tls_data)` or similar if channel binding is desired for stronger security.
affects: All versions
gotchaThe package name `scramp` is easily confused with other Python libraries or projects (e.g., `scamp` for music, `SCAMP`/`pyscamp` for matrix profiles, `SCaMP` for metagenomics, `SCRAP` for RNA-seq, Scamp5d vision system). Ensure you are installing and importing `scramp` specifically for SCRAM protocol implementation.
fix
Always verify the PyPI project description and source URL to confirm you are using `scramp` for SCRAM authentication, not a similarly named library with different functionality.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scramp'
The 'scramp' library is not installed in the current Python environment.
fix
pip install scramp
TypeError: a bytes-like object is required, not 'str'
A Python string (`str`) was provided to a 'scramp' function or method that expects a byte string (`bytes`), often for sensitive data like passwords or salts.
fix
Encode the string to bytes, typically using `.encode('utf-8')`. Example: `client.set_password('mysecret'.encode('utf-8'))`
scramp.exceptions.ScrampError: Authentication failed
The SCRAM authentication exchange failed due to incorrect credentials (username, password), invalid proofs, or a violation of the authentication protocol steps.
fix
Verify the provided username, password, salt, and iteration count (N). Ensure both client and server are correctly following the SCRAM message exchange sequence and data integrity.
ValueError: Auth mechanism 'SCRAM-SHA-128' not supported by server
The client attempted to negotiate an authentication mechanism (e.g., 'SCRAM-SHA-128') that the 'scramp' server instance was not configured to support or did not advertise as available.
fix
Ensure that the client requests a mechanism that is present in the server's list of supported mechanisms, or configure the server to include the desired mechanism in its `mechanisms` parameter during instantiation.
Upgrade
Version history
1.4.17latest on PyPI · released Aug 7, 2026
Audit
Dependencies
passliboptionalOften used for flexible server-side password hashing (e.g., PBKDF2). Not a strict runtime dependency for basic operation, but enables advanced server-side customization.
Agent activity
19 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
scramp — pip install scramp · libregistry