tessl/pypi-gssapi

Python GSSAPI wrapper providing both low-level C-style and high-level Pythonic interfaces for Kerberos and other authentication mechanisms

—

Pending

Overview

Eval results

Files

Low-Level Raw API

Name: tessl/pypi-gssapi
Author: tessl

The raw GSSAPI API provides direct C-style bindings that closely follow RFC 2744 specifications. These functions offer fine-grained control over GSSAPI operations and access to all available extensions.

Capabilities

Core Modules Overview

The raw API is organized into modules that correspond to different aspects of GSSAPI functionality.

import gssapi.raw

# All functions can be imported directly from gssapi.raw
from gssapi.raw import acquire_cred, init_sec_context, wrap, unwrap

Names Module (gssapi.raw.names)

Direct name manipulation functions following RFC 2744.

def import_name(name_buffer, name_type=None):
    """
    Import a name from a buffer.
    
    Parameters:
    - name_buffer: bytes, name in external format
    - name_type: OID, name type (default: hostbased_service)
    
    Returns:
    Name: Imported name object
    """

def display_name(name, name_type=False):
    """
    Display a name in human-readable form.
    
    Parameters:
    - name: Name object
    - name_type: bool, whether to return name type
    
    Returns:
    DisplayNameResult: name (bytes), name_type (OID or None)
    """

def compare_name(name1, name2):
    """
    Compare two names for equality.
    
    Parameters:
    - name1: Name object
    - name2: Name object
    
    Returns:
    bool: True if names are equal
    """

def canonicalize_name(input_name, mech_type):
    """
    Canonicalize a name for a mechanism.
    
    Parameters:
    - input_name: Name object
    - mech_type: OID, mechanism type
    
    Returns:
    Name: Canonicalized name
    """

def export_name(name):
    """
    Export a name to a token.
    
    Parameters:
    - name: Name object
    
    Returns:
    bytes: Exported name token
    """

def duplicate_name(name):
    """
    Duplicate a name.
    
    Parameters:
    - name: Name object
    
    Returns:
    Name: Duplicated name
    """

Credentials Module (gssapi.raw.creds)

Credential management functions with direct control over all parameters.

def acquire_cred(desired_name=None, lifetime=None, desired_mechs=None, cred_usage=None, store=None):
    """
    Acquire credentials.
    
    Parameters:
    - desired_name: Name, principal name (None for default)
    - lifetime: int, desired lifetime in seconds (None for default)
    - desired_mechs: iterable of OID, desired mechanisms (None for default)
    - cred_usage: str, 'initiate', 'accept', or 'both' (None for both)
    - store: dict, credential store parameters
    
    Returns:
    AcquireCredResult: creds, mechs, lifetime
    """

def add_cred(input_creds, desired_name, mech, cred_usage, init_lifetime=None, accept_lifetime=None, store=None):
    """
    Add credentials to existing credential set.
    
    Parameters:
    - input_creds: Creds, existing credentials
    - desired_name: Name, principal name
    - mech: OID, mechanism
    - cred_usage: str, 'initiate', 'accept', or 'both'
    - init_lifetime: int, initiate lifetime in seconds
    - accept_lifetime: int, accept lifetime in seconds
    - store: dict, credential store parameters
    
    Returns:
    AddCredResult: creds, mechs, init_lifetime, accept_lifetime
    """

def inquire_cred(creds, name=True, lifetime=True, cred_usage=True, mechs=True):
    """
    Inquire about credentials.
    
    Parameters:
    - creds: Creds object
    - name: bool, include name information
    - lifetime: bool, include lifetime information
    - cred_usage: bool, include usage information
    - mechs: bool, include mechanism information
    
    Returns:
    InquireCredResult: name, lifetime, usage, mechs
    """

def inquire_cred_by_mech(creds, mech, name=True, init_lifetime=True, accept_lifetime=True, usage=True):
    """
    Inquire about credentials for specific mechanism.
    
    Parameters:
    - creds: Creds object
    - mech: OID, mechanism to query
    - name: bool, include name information
    - init_lifetime: bool, include initiate lifetime
    - accept_lifetime: bool, include accept lifetime
    - usage: bool, include usage information
    
    Returns:
    InquireCredByMechResult: name, init_lifetime, accept_lifetime, usage
    """

Security Contexts Module (gssapi.raw.sec_contexts)

Direct security context establishment and management.

def init_sec_context(creds, context=None, target_name=None, mech=None, req_flags=None, time_req=None, channel_bindings=None, input_token=None):
    """
    Initialize security context (initiator side).
    
    Parameters:
    - creds: Creds, initiator credentials
    - context: SecurityContext, existing context (None for new)
    - target_name: Name, target principal
    - mech: OID, desired mechanism
    - req_flags: RequirementFlag, requested context features
    - time_req: int, requested context lifetime
    - channel_bindings: ChannelBindings, channel binding data
    - input_token: bytes, input token from acceptor
    
    Returns:
    InitSecContextResult: context, mech, flags, token, lifetime, more_steps
    """

def accept_sec_context(creds, context=None, input_token=None, channel_bindings=None):
    """
    Accept security context (acceptor side).
    
    Parameters:
    - creds: Creds, acceptor credentials
    - context: SecurityContext, existing context (None for new)
    - input_token: bytes, input token from initiator
    - channel_bindings: ChannelBindings, channel binding data
    
    Returns:
    AcceptSecContextResult: context, initiator_name, mech, token, flags, lifetime, delegated_creds, more_steps
    """

def inquire_context(context, initiator_name=True, target_name=True, lifetime=True, mech=True, flags=True, locally_init=True, complete=True):
    """
    Inquire about context information.
    
    Parameters:
    - context: SecurityContext object
    - initiator_name: bool, include initiator name
    - target_name: bool, include target name  
    - lifetime: bool, include remaining lifetime
    - mech: bool, include mechanism
    - flags: bool, include context flags
    - locally_init: bool, include local initiation status
    - complete: bool, include completion status
    
    Returns:
    InquireContextResult: requested information fields
    """

def delete_sec_context(context):
    """
    Delete security context and free resources.
    
    Parameters:
    - context: SecurityContext object
    
    Returns:
    bytes or None: Final context token if available
    """

def export_sec_context(context):
    """
    Export security context to a token.
    
    Parameters:
    - context: SecurityContext object
    
    Returns:
    bytes: Exported context token
    """

def import_sec_context(token):
    """
    Import security context from a token.
    
    Parameters:
    - token: bytes, exported context token
    
    Returns:
    SecurityContext: Imported context
    """

Message Protection Module (gssapi.raw.message)

Message wrapping, unwrapping, and MIC operations.

def wrap(context, message, encrypt=None):
    """
    Wrap (protect) a message.
    
    Parameters:
    - context: SecurityContext object
    - message: bytes, message to protect
    - encrypt: bool, whether to encrypt (None for context default)
    
    Returns:
    WrapResult: message (bytes), encrypted (bool)
    """

def unwrap(context, message):
    """
    Unwrap (unprotect) a message.
    
    Parameters:
    - context: SecurityContext object
    - message: bytes, protected message
    
    Returns:
    UnwrapResult: message (bytes), encrypted (bool), qop (int)
    """

def get_mic(context, message):
    """
    Generate Message Integrity Code.
    
    Parameters:
    - context: SecurityContext object
    - message: bytes, message to sign
    
    Returns:
    bytes: MIC token
    """

def verify_mic(context, message, mic):
    """
    Verify Message Integrity Code.
    
    Parameters:
    - context: SecurityContext object
    - message: bytes, original message
    - mic: bytes, MIC token
    
    Returns:
    int: Quality of protection used
    """

Miscellaneous Functions (gssapi.raw.misc)

Utility functions for mechanism inquiry and general GSSAPI operations.

def indicate_mechs():
    """
    Get available GSSAPI mechanisms.
    
    Returns:
    set: Available mechanism OIDs
    """

def inquire_names_for_mech(mech):
    """
    Get supported name types for a mechanism.
    
    Parameters:
    - mech: OID, mechanism to query
    
    Returns:
    set: Supported name type OIDs
    """

def inquire_mechs_for_name(name):
    """
    Get mechanisms that support a name type.
    
    Parameters:
    - name: Name object or OID
    
    Returns:
    set: Supporting mechanism OIDs
    """

Types and Enumerations (gssapi.raw.types)

GSSAPI type definitions and enumerations.

from gssapi.raw.types import NameType, RequirementFlag, AddressType, MechType, IntEnumFlagSet

class NameType:
    hostbased_service: OID
    user_name: OID
    machine_uid_name: OID
    string_uid_name: OID
    anonymous: OID
    export: OID
    composite_export: OID

class RequirementFlag(IntEnumFlagSet):
    mutual_authentication: int
    replay_detection: int
    sequence_detection: int
    confidentiality: int
    integrity: int
    anonymous: int
    protection_ready: int
    transfer_ready: int
    deleg_policy_flag: int
    delegate_to_peer: int

class AddressType:
    unspecified: int
    hostbased: int
    ip: int
    directional: int

class MechType:
    kerberos: OID
    spnego: OID

OID Handling (gssapi.raw.oids)

Object Identifier manipulation and well-known OID constants.

class OID:
    """Object Identifier representation."""
    
    def __init__(self, cpy=None, elements=None):
        """
        Create OID from copy or elements.
        
        Parameters:
        - cpy: OID, existing OID to copy
        - elements: bytes, DER-encoded OID elements
        """
    
    @property
    def dotted_form(self):
        """Get dotted decimal string representation."""
    
    def __str__(self):
        """String representation of OID."""
    
    def __eq__(self, other):
        """Compare OIDs for equality."""

Channel Bindings (gssapi.raw.chan_bindings)

Channel binding data structures for binding authentication to secure channels.

class ChannelBindings:
    """Channel binding information."""
    
    def __init__(self, initiator_address_type=None, initiator_address=None, 
                 acceptor_address_type=None, acceptor_address=None, 
                 application_data=None):
        """
        Create channel bindings.
        
        Parameters:
        - initiator_address_type: AddressType, initiator address type
        - initiator_address: bytes, initiator address
        - acceptor_address_type: AddressType, acceptor address type
        - acceptor_address: bytes, acceptor address
        - application_data: bytes, application-specific data
        """

Exception Handling (gssapi.raw.exceptions)

GSSAPI error handling with specific exception classes for each major error code.

class GSSError(Exception):
    """Base GSSAPI error class with major and minor error codes."""
    
    def __init__(self, maj_stat, min_stat):
        """
        Parameters:
        - maj_stat: int, major status code
        - min_stat: int, minor status code
        """
    
    @property
    def maj_stat(self):
        """Major status code."""
    
    @property
    def min_stat(self):
        """Minor status code."""

# Specific exception classes
class BadMechanismError(GSSError): pass
class BadNameError(GSSError): pass
class BadNameTypeError(GSSError): pass
class BadStatusError(GSSError): pass
class BadSigError(GSSError): pass
class CredentialsExpiredError(GSSError): pass
class DefectiveCredentialError(GSSError): pass
class DefectiveTokenError(GSSError): pass
class FailureError(GSSError): pass
class NoContextError(GSSError): pass
class NoCredentialsError(GSSError): pass
class BadQoPError(GSSError): pass
class UnauthorizedError(GSSError): pass
class UnavailableError(GSSError): pass
class DuplicateElementError(GSSError): pass
class NameNotMNError(GSSError): pass

Usage Examples

Low-Level Authentication

import gssapi.raw as gssapi

# Acquire credentials
cred_result = gssapi.acquire_cred(
    desired_name=gssapi.import_name(b'service@hostname.example.com'),
    cred_usage='initiate'
)
creds = cred_result.creds

# Initialize context
target_name = gssapi.import_name(b'target@hostname.example.com')
init_result = gssapi.init_sec_context(
    creds=creds,
    target_name=target_name,
    req_flags=gssapi.RequirementFlag.mutual_authentication
)

context = init_result.context
token = init_result.token

Low-Level Message Protection

import gssapi.raw as gssapi

# Wrap message
message = b"Secret data"
wrap_result = gssapi.wrap(context, message, encrypt=True)
protected_message = wrap_result.message

# Unwrap message
unwrap_result = gssapi.unwrap(context, protected_message)
original_message = unwrap_result.message
was_encrypted = unwrap_result.encrypted

Error Handling

import gssapi.raw as gssapi

try:
    creds = gssapi.acquire_cred()
except gssapi.NoCredentialsError:
    print("No credentials available")
except gssapi.CredentialsExpiredError:
    print("Credentials have expired")
except gssapi.GSSError as e:
    print(f"GSSAPI error: {e.maj_stat}, {e.min_stat}")

Install with Tessl CLI