SSPI API Bindings for Python

Warnings

• breaking The constructor arguments for `sspilib.ClientSecurityContext` and `sspilib.ServerSecurityContext` changed. The `credential` argument became non-optional and was moved to the first positional argument.
  Fix: Ensure `credential` is always provided as the first argument when creating `ClientSecurityContext` or `ServerSecurityContext` instances.
• breaking Python 3.8 support was dropped. The library now requires Python 3.9 or newer.
  Fix: Upgrade your Python environment to version 3.9 or later.
• gotcha 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.
  Fix: For production non-Windows use cases, consider `python-gssapi`. If using `sspilib` on non-Windows, thoroughly test your authentication flows.
• gotcha 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.
  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.

Install

• pip install sspilib Install sspilib

Imports

• 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.

Quickstart

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}")