Install & Compatibility
Where this runs
tested against v0.6.0 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.082s · 53MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sspilib
✓ import sspilib
Main high-level API entry point.
sspilib.raw
✓ from sspilib import raw
Low-level SSPI function bindings, often more verbose.
UserCredential
✓ from sspilib import UserCredential
Used for defining user credentials for security contexts.
ClientSecurityContext
✓ from sspilib import ClientSecurityContext
Used to initiate a client-side SSPI security context.
WindowsError
✓ from sspilib import WindowsError
Custom error class for SSPI-specific errors, compatible on non-Windows hosts.
This quickstart demonstrates the initiation of a client-side SSPI security context using `sspilib.UserCredential` and `sspilib.ClientSecurityContext`. It generates the initial authentication token that would be sent to a server. For a complete SSPI handshake, the server would process this token and return its own, which the client would then process, and so on. Credentials and the Service Principal Name (SPN) are retrieved from environment variables for demonstration purposes.
import sspilib
import os
try:
# Get credentials and SPN from environment variables for a runnable example
# In a real application, retrieve these securely.
username = os.environ.get("SSPI_USERNAME", "user@DOMAIN.COM")
password = os.environ.get("SSPI_PASSWORD", "your_secure_password")
spn = os.environ.get("SSPI_SPN", "HOST/targetserver.domain.com")
if not all([username, password, spn]):
print("Please set SSPI_USERNAME, SSPI_PASSWORD, and SSPI_SPN environment variables for a real test.")
print("Proceeding with placeholders, which will likely fail on actual SSPI operations.")
print(f"Attempting to establish client security context for {username} to {spn}")
# Define user credentials
cred = sspilib.UserCredential(username, password)
# Initialize a client-side security context
# The credential argument is now mandatory and the first positional argument since v0.2.0
ctx = sspilib.ClientSecurityContext(cred, spn)
# Generate the first token (Client's initial negotiate message)
client_token = ctx.initialize_security_context()
if client_token:
print(f"Generated initial client token (first leg of handshake): {client_token.hex()}")
print("This token would typically be sent to the server for processing.")
print("A full SSPI handshake involves multiple token exchanges between client and server.")
# In a real scenario, you would send client_token to the server and receive a server_token.
# Then you would call ctx.initialize_security_context(server_token) again.
else:
print("No initial client token generated (context might be complete or error occurred).")
if ctx.complete:
print("Security context reports as complete (may indicate successful single-leg auth or simulated completion).")
else:
print("Security context not yet complete (requires further server interaction).")
except sspilib.WindowsError as e:
print(f"SSPI Error: {e.strerror} (Error Code: {e.errno})")
print("Ensure you are running on Windows or have sspi-rs correctly set up for non-Windows.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe constructor arguments for `sspilib.ClientSecurityContext` and `sspilib.ServerSecurityContext` changed. The `credential` argument became non-optional and was moved to the first positional argument.fixEnsure `credential` is always provided as the first argument when creating `ClientSecurityContext` or `ServerSecurityContext` instances.
affects: 0.2.0+
breakingPython 3.8 support was dropped. The library now requires Python 3.9 or newer.fixUpgrade your Python environment to version 3.9 or later.
affects: 0.3.0+
gotchaNon-Windows support for sspilib is experimental and relies on the `sspi-rs` Rust library. Compatibility with actual Windows SSPI is not 100%, and its use on non-Windows platforms is at your own risk. It is recommended to use a library that wraps GSSAPI (e.g., `python-gssapi`) for more robust cross-platform authentication.fixFor production non-Windows use cases, consider `python-gssapi`. If using `sspilib` on non-Windows, thoroughly test your authentication flows.
affects: All versions
gotchaWhile `sspilib` supports Python Free-Threading (PEP 779), it is not designed to be thread-safe out of the box. Limited testing has been performed in free-threading environments.fixImplement appropriate synchronization mechanisms (e.g., locks) when using `sspilib` objects or functions in a multi-threaded context, especially with a free-threading interpreter.
affects: All versions with Free-Threading support
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sspilib'
The sspilib package is not installed in the current Python environment or is not accessible on the PYTHONPATH.
fixRun `pip install sspilib` to install the library.
ERROR: Could not build wheels for sspilib
On non-Windows systems (Linux/macOS), sspilib requires the Rust toolchain (rustc and cargo) to build its `sspi-rs-ffi` backend, which might be missing.
fixInstall Rust and Cargo using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` before running `pip install sspilib`.
ImportError: cannot import name 'high_level' from 'sspilib'
The sspilib library exposes its high-level API directly as `sspi` and its low-level API as `low_level` at the top-level module, not as a module named `high_level`.
fixImport the high-level API using `from sspilib import sspi` or the low-level API using `from sspilib import low_level`.
Upgrade
Version history
0.6.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
No dependency data recorded yet.