Kerberos 5 Test Environment (k5test)

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'kadmin.local'

  cause k5test could not find a required Kerberos executable (e.g., `kadmin.local`, `kinit`, `krb5kdc`) on the system's PATH. This typically means the Kerberos utilities are not installed.
  fix Install the necessary Kerberos client and server packages for your operating system (e.g., `krb5-kdc`, `krb5-admin-server` on Debian/Ubuntu; `krb5-server`, `krb5-workstation` on RHEL/CentOS).

• ImportError: cannot import name 'K5Context' from 'k5test'

  cause The `K5Context` class was not found during import. This usually indicates a typo in the import statement or that the `k5test` package is not correctly installed.
  fix Ensure `k5test` is installed (`pip install k5test`) and use the correct import statement: `from k5test import K5Context`.

• subprocess.CalledProcessError: Command '['kinit', 'testuser']' returned non-zero exit status 1.

  cause A Kerberos command executed by k5test (or by your test code via subprocess) failed. This could be due to incorrect environment variables, permissions, or conflicts with existing Kerberos configurations.
  fix Review the stderr output of the `CalledProcessError` for more specific Kerberos error messages. Ensure that no system-wide Kerberos environment variables (e.g., `KRB5_CONFIG`, `KRB5CCNAME`) are unintentionally interfering with the temporary environment set up by `K5Context`. Try setting `KRB5_TRACE=/dev/stderr` in the subprocess environment to get more verbose Kerberos debugging output.

Warnings

• gotcha k5test relies on external Kerberos binaries. It does not provide the Kerberos 5 KDC or client executables itself. Users must have the necessary Kerberos server and client packages (e.g., `krb5-kdc`, `krb5-admin-server`, `krb5-user`) installed on their system for k5test to function.
  Fix: Install the appropriate Kerberos packages for your operating system (e.g., `sudo apt install krb5-kdc krb5-admin-server krb5-user` on Debian/Ubuntu or `sudo dnf install krb5-server krb5-workstation` on RHEL/Fedora).
• gotcha Prior to v0.10.2, k5test relied on the system's `which(1)` command for locating Kerberos binaries. If `which` was not installed or if binaries like `kadmin.local` were in non-standard paths, k5test might fail to find them.
  Fix: Upgrade to k5test v0.10.2 or newer, which uses `shutil.which()` for more robust executable discovery. If upgrading is not an option, ensure `which(1)` is installed and Kerberos binaries are in standard PATH locations.
• breaking Version 0.10.0 introduced support for Heimdal Kerberos, which was not available in earlier versions. While the default remains MIT Kerberos, users who explicitly require Heimdal or are migrating from systems where Heimdal was implicitly used might need to update their K5Context instantiation.
  Fix: If Heimdal Kerberos support is desired, explicitly specify `kdc_type='heimdal'` when creating the context: `K5Context(kdc_type='heimdal')`. The default is `kdc_type='mit'`.

Install

• pip install k5test Install stable version

Imports

• K5Context

  from k5test import K5Context

Quickstart

This quickstart demonstrates how to set up a temporary Kerberos 5 environment using `k5test.K5Context`. It initializes a KDC, provides a credential cache and keytab, and configures `krb5.conf`. The example then uses `subprocess` to run `kinit` to authenticate 'testuser' and `kadmin.local` to list principals, showcasing how to interact with the managed Kerberos services within your tests. Note that system Kerberos binaries must be installed.

import subprocess
from k5test import K5Context
import os

def run_k5test_example():
    # K5Context creates a temporary Kerberos environment.
    # It provides paths to a credential cache (ccache) and keytab,
    # and sets up a krb5.conf to point to its KDC.
    try:
        with K5Context() as c:
            print(f"Kerberos context created. KDC Port: {c.kdc_port}")
            print(f"Credential Cache: {c.ccache}")
            print(f"Keytab: {c.keytab}")

            # Example: Authenticate as 'testuser' using the generated ccache
            # kinit requires the KRB5CCNAME environment variable to be set.
            kinit_env = os.environ.copy()
            kinit_env['KRB5CCNAME'] = c.ccache
            # k5test often manages KRB5_CONFIG and other Kerberos env vars internally
            # within the context manager, or provides an 'env' dict for subprocesses.
            # For kinit, we usually only need to override KRB5CCNAME.

            print("\nRunning kinit...")
            subprocess.run(['kinit', 'testuser'], env=kinit_env, check=True, capture_output=True)
            print("kinit successful for testuser.")

            # Example: List principals using kadmin.local
            # kadmin.local might need more environment variables set by K5Context
            # to locate its configuration and daemons. Use c.env.
            print("\nListing principals via kadmin.local...")
            kadmin_output = subprocess.check_output(['kadmin.local', '-q', 'list_principals'], env=c.env, text=True)
            print(kadmin_output)

            # Your test code that uses Kerberos can go here
            print("\nKerberos environment is ready for testing.")

    except FileNotFoundError as e:
        print(f"Error: Kerberos binary not found. Please ensure krb5-kdc and krb5-admin-server are installed. {e}")
    except subprocess.CalledProcessError as e:
        print(f"Error during Kerberos command execution: {e}")
        print(f"Stderr: {e.stderr.decode()}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    run_k5test_example()