{"id":2294,"library":"sspilib","title":"SSPI API Bindings for Python","description":"sspilib is a Python library that provides bindings for the Windows Security Support Provider Interface (SSPI) API. It offers both a high-level and a low-level interface to facilitate SSPI integration in other Python libraries. The library currently supports Python 3.9+ and ships as pre-compiled wheels for various platforms, including experimental support for non-Windows systems via `sspi-rs`, a Rust implementation.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/jborean93/sspilib","tags":["Windows","SSPI","authentication","security","bindings","kerberos","ntlm"],"install":[{"cmd":"pip install sspilib","lang":"bash","label":"Install sspilib"}],"dependencies":[],"imports":[{"note":"Main high-level API entry point.","symbol":"sspilib","correct":"import sspilib"},{"note":"Low-level SSPI function bindings, often more verbose.","symbol":"sspilib.raw","correct":"from sspilib import raw"},{"note":"Used for defining user credentials for security contexts.","symbol":"UserCredential","correct":"from sspilib import UserCredential"},{"note":"Used to initiate a client-side SSPI security context.","symbol":"ClientSecurityContext","correct":"from sspilib import ClientSecurityContext"},{"note":"Custom error class for SSPI-specific errors, compatible on non-Windows hosts.","symbol":"WindowsError","correct":"from sspilib import WindowsError"}],"quickstart":{"code":"import sspilib\nimport os\n\ntry:\n    # Get credentials and SPN from environment variables for a runnable example\n    # In a real application, retrieve these securely.\n    username = os.environ.get(\"SSPI_USERNAME\", \"user@DOMAIN.COM\")\n    password = os.environ.get(\"SSPI_PASSWORD\", \"your_secure_password\")\n    spn = os.environ.get(\"SSPI_SPN\", \"HOST/targetserver.domain.com\")\n\n    if not all([username, password, spn]):\n        print(\"Please set SSPI_USERNAME, SSPI_PASSWORD, and SSPI_SPN environment variables for a real test.\")\n        print(\"Proceeding with placeholders, which will likely fail on actual SSPI operations.\")\n\n    print(f\"Attempting to establish client security context for {username} to {spn}\")\n\n    # Define user credentials\n    cred = sspilib.UserCredential(username, password)\n    \n    # Initialize a client-side security context\n    # The credential argument is now mandatory and the first positional argument since v0.2.0\n    ctx = sspilib.ClientSecurityContext(cred, spn)\n\n    # Generate the first token (Client's initial negotiate message)\n    client_token = ctx.initialize_security_context()\n\n    if client_token:\n        print(f\"Generated initial client token (first leg of handshake): {client_token.hex()}\")\n        print(\"This token would typically be sent to the server for processing.\")\n        print(\"A full SSPI handshake involves multiple token exchanges between client and server.\")\n        # In a real scenario, you would send client_token to the server and receive a server_token.\n        # Then you would call ctx.initialize_security_context(server_token) again.\n    else:\n        print(\"No initial client token generated (context might be complete or error occurred).\")\n\n    if ctx.complete:\n        print(\"Security context reports as complete (may indicate successful single-leg auth or simulated completion).\")\n    else:\n        print(\"Security context not yet complete (requires further server interaction).\")\n\nexcept sspilib.WindowsError as e:\n    print(f\"SSPI Error: {e.strerror} (Error Code: {e.errno})\")\n    print(\"Ensure you are running on Windows or have sspi-rs correctly set up for non-Windows.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `credential` is always provided as the first argument when creating `ClientSecurityContext` or `ServerSecurityContext` instances.","message":"The constructor arguments for `sspilib.ClientSecurityContext` and `sspilib.ServerSecurityContext` changed. The `credential` argument became non-optional and was moved to the first positional argument.","severity":"breaking","affected_versions":"0.2.0+"},{"fix":"Upgrade your Python environment to version 3.9 or later.","message":"Python 3.8 support was dropped. The library now requires Python 3.9 or newer.","severity":"breaking","affected_versions":"0.3.0+"},{"fix":"For production non-Windows use cases, consider `python-gssapi`. If using `sspilib` on non-Windows, thoroughly test your authentication flows.","message":"Non-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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement appropriate synchronization mechanisms (e.g., locks) when using `sspilib` objects or functions in a multi-threaded context, especially with a free-threading interpreter.","message":"While `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.","severity":"gotcha","affected_versions":"All versions with Free-Threading support"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}