PyKerberos

https://github.com/02strich/pykerberos
Admin
PyKerberos is a high-level Python wrapper for Kerberos (GSSAPI) operations that simplifies client...
Tokens:37,306
Snippets:221
Trust Score:8.8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example usage of authGSSClientResponse

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Example showing how to obtain the base64-encoded token after initializing a context and performing a step. The returned token is intended for the Authorization header.

```python
rc, ctx = kerberos.authGSSClientInit("http@example.com")
kerberos.authGSSClientStep(ctx, "")
token = kerberos.authGSSClientResponse(ctx)  # base64 string for the Authorization header
```

--------------------------------

### Channel bindings with initiator and acceptor addresses

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/channel-bindings.md

Example showing how to specify initiator and acceptor addresses when creating channel bindings.

```python
import kerberos, socket

cb = kerberos.channelBindings(
    initiator_addrtype=kerberos.GSS_C_AF_INET,
    initiator_address=socket.inet_aton("192.0.2.10"),
    acceptor_addrtype=kerberos.GSS_C_AF_INET,
    acceptor_address=socket.inet_aton("192.0.2.20"),
    application_data=b"tls-server-endpoint:" + digest,
)

```

--------------------------------

### Python example using getServerPrincipalDetails

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Example usage of getServerPrincipalDetails, including error handling for kerberos.KrbError. It prints the service principal or an error message with the error code.

```python
import kerberos

try:
    principal = kerberos.getServerPrincipalDetails("http", "example.com")
except kerberos.KrbError as e:
    msg, code = e.args[0]
    print("Lookup failed: %s (%s)" % (msg, code))
else:
    print("Service principal:", principal)
```

--------------------------------

### Basic authGSSClientInit example

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Basic initialization of a GSSAPI client context with a service principal. The function returns a tuple (rc, ctx) where rc is 1 on success.

```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
print("Init result:", rc)  # 1

```

--------------------------------

### Python example for authGSSClientWrapIov

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-extensions.md

Python example showing how to use authGSSClientWrapIov to wrap a plaintext message. It initializes the context, performs the handshake, wraps the data, and retrieves the response.

```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... handshake ...
rc, pad_len = kerberos.authGSSClientWrapIov(ctx, plaintext_b64)
wrapped = kerberos.authGSSClientResponse(ctx)
print("result=%d padding=%d" % (rc, pad_len))
```

--------------------------------

### Example usage of authGSSServerResponse

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example showing how to call authGSSServerResponse after authGSSServerStep returns AUTH_GSS_CONTINUE, to obtain the server token to send to the client.

```python
rc = kerberos.authGSSServerStep(sctx, token)
if rc == kerberos.AUTH_GSS_CONTINUE:
    server_token = kerberos.authGSSServerResponse(sctx)  # send to client
```

--------------------------------

### Server-side authentication step example

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example of using authGSSServerStep to process a client token during GSSAPI authentication. It initializes the server context, processes the client's challenge, and if continuation is required, generates a response to send back to the client.

```python
import kerberos

rc, sctx = kerberos.authGSSServerInit("http@example.com")
rc = kerberos.authGSSServerStep(sctx, client_token_b64)
if rc == kerberos.AUTH_GSS_CONTINUE:
    reply = kerberos.authGSSServerResponse(sctx)  # send back to client
```

--------------------------------

### Basic checkPassword example

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Example of calling checkPassword with basic verification, catching BasicAuthError and printing the error message and code.

```python
import kerberos

try:
    ok = kerberos.checkPassword("jdoe", "s3cret", "http/example.com", "EXAMPLE.COM")
except kerberos.BasicAuthError as e:
    message, code = e.args  # e.g. ("Client not found in Kerberos database", -1765328377)
    print("Authentication failed: %s (error %d)" % (message, code))
else:
    print("Authenticated:", ok)
```

--------------------------------

### Full round-trip example with authGSSWinRMEncryptMessage and authGSSWinRMDecryptMessage

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-extensions.md

Demonstrates the complete encryption and decryption cycle: initializes a context, encrypts a body, then decrypts it and asserts the result matches the original. The handshake step is omitted for brevity.

```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... handshake ...
body = b"<Envelope>...</Envelope>"
enc, hdr = kerberos.authGSSWinRMEncryptMessage(ctx, body)
dec = kerberos.authGSSWinRMDecryptMessage(ctx, enc, hdr)
assert dec == body
```

--------------------------------

### authGSSClientInit with principal, flags, and SPNEGO

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Initialization with an explicit client principal, delegation flags, and the SPNEGO mechanism. The example shows how to catch kerberos.GSSError and extract the major and minor status codes.

```python
import kerberos

flags = kerberos.GSS_C_DELEG_FLAG | kerberos.GSS_C_MUTUAL_FLAG | kerberos.GSS_C_SEQUENCE_FLAG
try:
    rc, ctx = kerberos.authGSSClientInit(
        "http@example.com",
        principal="jdoe@EXAMPLE.COM",
        gssflags=flags,
        mech_oid=kerberos.GSS_MECH_OID_SPNEGO,
    )
except kerberos.GSSError as e:
    (maj_msg, maj_code), (min_msg, min_code) = e.args
    print("GSS error: %s (%d) / %s (%d)" % (maj_msg, maj_code, min_msg, min_code))

```

--------------------------------

### Example usage of authGSSServerTargetName

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example showing how to retrieve the client-targeted name after server authentication. Requires authGSSServerInit("") to avoid supplying server credentials, otherwise the target name remains NULL.

```python
rc, sctx = kerberos.authGSSServerInit("")   # no own creds
kerberos.authGSSServerStep(sctx, token)
print("Client targeted:", kerberos.authGSSServerTargetName(sctx))
```

--------------------------------

### Example usage of authGSSServerUserName

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example showing how to call authGSSServerUserName after authGSSServerStep returns AUTH_GSS_COMPLETE, to print the authenticated client's username.

```python
rc = kerberos.authGSSServerStep(sctx, token)
if rc == kerberos.AUTH_GSS_COMPLETE:
    print("Authenticated client:", kerberos.authGSSServerUserName(sctx))
```

--------------------------------

### Example usage of authGSSServerClean

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example showing how to call authGSSServerClean after server authentication. Returns 1 (AUTH_GSS_COMPLETE) as a no-op.

```python
rc, sctx = kerberos.authGSSServerInit("http@example.com")
# ... accept authentication ...
kerberos.authGSSServerClean(sctx)  # returns 1
```

--------------------------------

### Channel bindings example using TLS and RFC5929

Source: https://github.com/02strich/pykerberos/blob/master/README.txt

This code snippet shows how to compute channel bindings application data from a server certificate using SHA-256 and base64 decoding, then pass it to kerberos.authGSSClientInit and kerberos.authGSSClientStep. It is based on RFC5929 and uses the 'tls-server-end-point' type. The example is simplified and assumes a socket object is obtained somehow.

```python
import hashlib

    def get_channel_bindings_application_data(socket):
        # This is a highly simplified example, there are other use cases
        # where you might need to use different hash types or get a socket
        # object somehow.
        server_certificate = socket.getpeercert(True)
        certificate_hash = hashlib.sha256(server_certificate).hexdigest().upper()
        certificate_digest = base64.b16decode(certificate_hash)
        application_data = b'tls-server-end-point:%s' % certificate_digest

        return application_data

    def main():
        # Code to setup a socket with the server
        # A lot of code to setup the handshake and start the auth process
        socket = getsocketsomehow()

        # Connect to the host and start the auth process

        # Build the channel bindings object
        application_data = get_channel_bindings_application_data(socket)
        channel_bindings = kerberos.channelBindings(application_data=application_data)

        # More work to get responses from the server

        result, context = kerberos.authGSSClientInit(kerb_spn, gssflags=gssflags, principal=principal)

        # Pass through the channel_bindings object as created in the kerberos.channelBindings method
        result = kerberos.authGSSClientStep(context, neg_resp_value, channel_bindings=channel_bindings)

        # Repeat as necessary
```

--------------------------------

### RFC 5929 TLS server endpoint channel bindings example

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/channel-bindings.md

Example showing how to create channel bindings from a TLS socket's server certificate and pass them to authGSSClientStep.

```python
import base64, hashlib, kerberos

def tls_server_endpoint_bindings(socket):
    """RFC 5929 channel bindings from a TLS socket's server certificate."""
    server_certificate = socket.getpeercert(True)
    certificate_hash = hashlib.sha256(server_certificate).hexdigest().upper()
    certificate_digest = base64.b16decode(certificate_hash)
    application_data = b"tls-server-endpoint:%s" % certificate_digest
    return kerberos.channelBindings(application_data=application_data)

cb = tls_server_endpoint_bindings(sock)
rc, ctx = kerberos.authGSSClientInit(kerb_spn)
rc = kerberos.authGSSClientStep(ctx, server_challenge, channel_bindings=cb)

```

--------------------------------

### Example usage of authGSSClientResponseConf

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Example showing how to check whether the last unwrapped message was encrypted. It requires a completed handshake and an unwrap call before checking the confidentiality flag.

```python
rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... complete handshake, then unwrap a protected message ...
kerberos.authGSSClientUnwrap(ctx, server_data)
if kerberos.authGSSClientResponseConf(ctx):
    print("Message was encrypted (confidentiality on)")
```

--------------------------------

### changePassword usage example with error handling

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Shows how to call changePassword with a realm-qualified user name and capture the PwdChangeError. The exception's args contain a message and error code; on success, it prints 'Password changed'.

```python
import kerberos

try:
    kerberos.changePassword("jdoe@EXAMPLE.COM", "oldpass", "newpass")
except kerberos.PwdChangeError as e:
    msg, code = e.args
    print("Password change failed: %s (%d)" % (msg, code))
else:
    print("Password changed")

```

--------------------------------

### checkPassword with verify=False and explicit realm

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Example of calling checkPassword with KDC verification disabled and an explicit realm in the user name, showing that default_realm is unused.

```python
import kerberos

# Realm is taken from the user string ("@EXAMPLE.COM"), so default_realm is unused;
# KDC verification of the service ticket is turned off.
if kerberos.checkPassword("jdoe@EXAMPLE.COM", "s3cret", "http/example.com", "ANY.REALM", verify=False):
    print("Credentials valid")
```

--------------------------------

### Error handling for empty challenge

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Example of catching the KrbError raised when authGSSServerStep is called with an empty challenge string. The error message is printed to show the expected failure condition.

```python
try:
    kerberos.authGSSServerStep(sctx, "")
except kerberos.KrbError as e:
    print(e.args[0])  # "No challenge parameter in request from client"
```

--------------------------------

### C wrapper signature for authGSSWinRMDecryptMessage

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-extensions.md

Shows the C function signature and the start of its argument parsing, which expects three objects: the context, encrypted data, and header. The ellipsis indicates omitted implementation details.

```c
/* src/kerberos.c:651 — wrapper */
static PyObject* authGSSWinRMDecryptMessage(PyObject* self, PyObject* args) {
    ...
    if (! PyArg_ParseTuple(args, "OOO", &pystate, &pyenc_data, &pyheader)) {
```

--------------------------------

### Build PyKerberos with setup.py

Source: https://github.com/02strich/pykerberos/blob/master/README.txt

Run this command in the package directory to build the extension module.

```bash
python setup.py build
```

--------------------------------

### Initialize server context with empty service string

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Accepts any service by passing an empty string as the service parameter. This relies on the default acceptor credentials and does not acquire its own credentials.

```python
rc, sctx = kerberos.authGSSServerInit("")  # empty service string
```

--------------------------------

### kerberos.authGSSServerInit(service)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Initializes a server-side GSSAPI context. Returns a context handle.

```APIDOC
## authGSSServerInit(service)

### Description
Initializes a server-side GSSAPI context. Returns a context handle.

### Method
Function call

### Endpoint
`kerberos.authGSSServerInit(service)`

### Parameters
- **service** (string) - Required - The service principal name.

### Returns
- **context** - A GSSAPI context handle.

### Exceptions
- **GSSError** - Raised on initialization failure.

### Example
```python
import kerberos
context = kerberos.authGSSServerInit('HTTP@example.com')
```
```

--------------------------------

### Sample macOS Kerberos configuration (config/edu.mit.Kerberos)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/configuration.md

Sample configuration file in the macOS Kerberos preferences format, referenced by the README. It sets the default realm to EXAMPLE.COM, disables DNS fallback, and specifies DES encryption types for ticket and TGS. It also defines the KDC for the realm and maps domain names to the realm.

```ini
[libdefaults]
    default_realm = EXAMPLE.COM
    dns_fallback = NO
    default_tkt_enctypes = des-cbc-crc
    default_tgs_enctypes = des-cbc-crc

[realms]
	EXAMPLE.COM = {
		kdc = kdc.example.com
	}

[domain_realm]
	.example.com = EXAMPLE.COM
	example.com = EXAMPLE.COM
```

--------------------------------

### kerberos.authGSSClientInit(service, principal=None, gssflags=10, mech_oid=None)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Initializes a client-side GSSAPI context. Returns a context handle for subsequent operations.

```APIDOC
## authGSSClientInit(service, principal=None, gssflags=10, mech_oid=None)

### Description
Initializes a client-side GSSAPI context. Returns a context handle for subsequent operations.

### Method
Function call

### Endpoint
`kerberos.authGSSClientInit(service, principal=None, gssflags=10, mech_oid=None)`

### Parameters
- **service** (string) - Required - The service principal name.
- **principal** (string) - Optional - The client principal name.
- **gssflags** (int) - Optional - GSSAPI flags (default 10).
- **mech_oid** (string) - Optional - Mechanism OID.

### Returns
- **context** - A GSSAPI context handle.

### Exceptions
- **GSSError** - Raised on GSSAPI initialization failure.

### Example
```python
import kerberos
context = kerberos.authGSSClientInit('HTTP@example.com')
```
```

--------------------------------

### Run PyKerberos test.py with command line arguments

Source: https://github.com/02strich/pykerberos/blob/master/README.txt

Run the test script with user id, password, and service principal. The service principal defaults to 'http@host.example.com'.

```bash
python test.py -u userid -p password -s service
```

--------------------------------

### Initialize server context with service principal

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Initializes a GSSAPI server context with a service principal in the format type@fqdn (e.g., imap@mail.example.com). Returns a tuple (rc, sctx) where rc is 1 on success (AUTH_GSS_COMPLETE) and sctx is the server context capsule.

```python
import kerberos

rc, sctx = kerberos.authGSSServerInit("http@example.com")
print("Server init:", rc)  # 1
```

--------------------------------

### C signature of authGSSWinRMEncryptMessage

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-extensions.md

Shows the C wrapper function signature and the start of argument parsing with the 'et' format, which forces a UTF-8 copy of the input message.

```c
/* src/kerberos.c:593 — wrapper; note "et" forces a UTF-8 copy of the input */
static PyObject* authGSSWinRMEncryptMessage(PyObject* self, PyObject* args) {
    ...
    if (! PyArg_ParseTuple(args, "Oet", &pystate, "UTF-8", &input)) {
```

--------------------------------

### authGSSClientInit(service, principal=None, gssflags=10, mech_oid=None)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Initializes a GSSAPI client context. This is the first step in the authentication lifecycle. It creates the context and returns a tuple with a result code and an opaque context capsule used by all other client functions.

```APIDOC
## authGSSClientInit(service, principal=None, gssflags=10, mech_oid=None)

### Description
Initializes a GSSAPI client context. This is the first step in the authentication lifecycle. It creates the context and returns a tuple with a result code and an opaque context capsule used by all other client functions.

### Method
Function call

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **service** (str) - Required - Service principal in the form `type@fqdn` (e.g. `imap@mail.example.com`). If it contains a `/` it is imported with `GSS_C_NO_OID`; otherwise `gss_krb5_nt_service_name` is used.
- **principal** (str or None) - Optional - Client principal `user@realm`. When set, acquires credentials with `gss_acquire_cred` / `GSS_C_INITIATE`; when `None`/empty, the default credential cache is used.
- **gssflags** (int) - Optional - GSS flags bitmask (see `GSS_C_*_FLAG` constants). Default is `GSS_C_MUTUAL_FLAG | GSS_C_SEQUENCE_FLAG` (= 10). Example: `GSS_C_DELEG_FLAG|GSS_C_MUTUAL_FLAG|GSS_C_SEQUENCE_FLAG` allows forwarding credentials to the remote host.
- **mech_oid** (capsule or None) - Optional - GSS mechanism OID. `None` = `GSS_C_NO_OID`. Possible values: `kerberos.GSS_MECH_OID_KRB5`, `kerberos.GSS_MECH_OID_SPNEGO`.

### Request Example
```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
print("Init result:", rc)  # 1
```

### Response
#### Success Response (200)
- **result code** (int) - `AUTH_GSS_COMPLETE` = 1 on success; failures raise instead.
- **context** (capsule) - Opaque context capsule to pass to all other client functions.

#### Response Example
```python
(1, <capsule object>)
```

### Error Handling
- **kerberos.GSSError** - Raised when `gss_import_name` / `gss_acquire_cred` / `gss_release_name` fails.
- **TypeError** - Raised when `mech_oid` is not a capsule (message `"Invalid type for mech_oid"`) or the capsule contains a `NULL` pointer (message `"Invalid value for mech_oid"`).
```

--------------------------------

### C wrapper signature for authGSSServerStep

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

C function signature for the internal wrapper that parses arguments and calls the underlying GSSAPI logic. The body is omitted in the source, showing only the signature and the start of the function.

```c
/* src/kerberos.c:501 — wrapper */
static PyObject *authGSSServerStep(PyObject *self, PyObject *args) {
    ...
    if (!PyArg_ParseTuple(args, "Os", &pystate, &challenge)) {
```

--------------------------------

### C wrapper signature for authGSSServerInit

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

C wrapper function signature for authGSSServerInit, showing the function takes a PyObject self and args, and parses a single string argument 'service'. The ellipsis indicates omitted implementation details.

```c
/* src/kerberos.c:476 — wrapper */
static PyObject *authGSSServerInit(PyObject *self, PyObject *args) {
    ...
    if (!PyArg_ParseTuple(args, "s", &service)) {
```

--------------------------------

### kerberos.authGSSClientStep(context, challenge, channel_bindings=None)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Processes one client-side GSSAPI step. Returns 1 on success, 0 on failure.

```APIDOC
## authGSSClientStep(context, challenge, channel_bindings=None)

### Description
Processes one client-side GSSAPI step. Returns 1 on success, 0 on failure.

### Method
Function call

### Endpoint
`kerberos.authGSSClientStep(context, challenge, channel_bindings=None)`

### Parameters
- **context** - Required - The GSSAPI context handle.
- **challenge** (string) - Required - The challenge data (base64 encoded).
- **channel_bindings** - Optional - Channel bindings capsule.

### Returns
- **int** - 1 on success, 0 on failure.

### Exceptions
- **GSSError** - Raised on GSSAPI step failure.

### Example
```python
import kerberos
result = kerberos.authGSSClientStep(context, challenge)
```
```

--------------------------------

### kerberos.authGSSServerStep(context, challenge)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Processes one server-side GSSAPI step. Returns 1 on success, 0 on failure.

```APIDOC
## authGSSServerStep(context, challenge)

### Description
Processes one server-side GSSAPI step. Returns 1 on success, 0 on failure.

### Method
Function call

### Endpoint
`kerberos.authGSSServerStep(context, challenge)`

### Parameters
- **context** - Required - The GSSAPI context handle.
- **challenge** (string) - Required - The challenge data (base64 encoded).

### Returns
- **int** - 1 on success, 0 on failure.

### Exceptions
- **GSSError** - Raised on step failure.

### Example
```python
import kerberos
result = kerberos.authGSSServerStep(context, challenge)
```
```

--------------------------------

### authGSSServerInit(service)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Initializes the server-side GSSAPI context. This function creates a server context capsule that is used in subsequent authentication steps. It accepts a service principal string and returns a tuple containing a result code and the context.

```APIDOC
## authGSSServerInit(service)

### Description
Initializes the server-side GSSAPI context. This function creates a server context capsule that is used in subsequent authentication steps. It accepts a service principal string and returns a tuple containing a result code and the context.

### Method
Function call

### Endpoint
`authGSSServerInit(service)`

### Parameters
- **service** (str) - Required - Service principal `type@fqdn` (e.g. `imap@mail.example.com`). May be an empty string, meaning the server does not acquire its own credentials and accepts based on the default acceptor credentials.

### Return Type
Tuple `(int, context)`: result code (`AUTH_GSS_COMPLETE` = 1 on success; failures raise) and an opaque server context capsule.

### Throws
- `kerberos.GSSError` - If `gss_import_name` fails or `gss_acquire_cred` with `GSS_C_ACCEPT` fails.

### Request Example
```python
import kerberos

rc, sctx = kerberos.authGSSServerInit("http@example.com")
print("Server init:", rc)  # 1
```

Accept any service (no local credentials — relies on the default acceptor credential):

```python
rc, sctx = kerberos.authGSSServerInit("")  # empty service string
```

### Response
#### Success Response
- **rc** (int) - Result code, `AUTH_GSS_COMPLETE` (1) on success.
- **sctx** (context) - Opaque server context capsule.

#### Response Example
```python
(1, <capsule object "...">)
```
```

--------------------------------

### kerberos.authGSSServerResponse(context)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Returns the base64-encoded server response from the last GSSAPI step.

```APIDOC
## authGSSServerResponse(context)

### Description
Returns the base64-encoded server response from the last GSSAPI step.

### Method
Function call

### Endpoint
`kerberos.authGSSServerResponse(context)`

### Parameters
- **context** - Required - The GSSAPI context handle.

### Returns
- **string** - Base64-encoded response.

### Example
```python
import kerberos
response = kerberos.authGSSServerResponse(context)
```
```

--------------------------------

### kerberos.authGSSClientUnwrapIov(context, challenge)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Performs IOV-mode unwrap on the given challenge data.

```APIDOC
## authGSSClientUnwrapIov(context, challenge)

### Description
Performs IOV-mode unwrap on the given challenge data.

### Method
Function call

### Endpoint
`kerberos.authGSSClientUnwrapIov(context, challenge)`

### Parameters
- **context** - Required - The GSSAPI context handle.
- **challenge** (string) - Required - The data to unwrap.

### Returns
- **string** - The unwrapped data.

### Exceptions
- **GSSError** - Raised on unwrap failure.

### Example
```python
import kerberos
unwrapped = kerberos.authGSSClientUnwrapIov(context, challenge)
```
```

--------------------------------

### authGSSClientStep signatures (C wrapper and Python stub)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Shows the C wrapper signature and the Python stub signature for authGSSClientStep. The C keyword for the first argument is "state", while the Python stub names it "context". The C wrapper accepts an optional channel_bindings argument.

```c
/* src/kerberos.c:236 — wrapper; kwlist = {"state", "challenge", "channel_bindings"} */
static PyObject *authGSSClientStep(PyObject *self, PyObject *args, PyObject* keywds) {
    ...
    if (! PyArg_ParseTupleAndKeywords(args, keywds, "Os|O", kwlist, &pystate, &challenge, &pychan_bindings)) {
```

```python
# pysrc/kerberos.py:133 — documented signature (stub names first arg "context";
# the C keyword name is "state")
def authGSSClientStep(context, challenge, **kwargs):
```

--------------------------------

### getServerPrincipalDetails(service, hostname)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Retrieves the service principal (e.g., http/example.com@EXAMPLE.COM) for the given service type and hostname by looking up the default keytab. Returns a string or raises kerberos.KrbError on failure.

```APIDOC
## getServerPrincipalDetails(service, hostname)

### Description
Retrieves the service principal (e.g., `http/example.com@EXAMPLE.COM`) for the given service type and hostname by looking up the default keytab. Returns a string or raises `kerberos.KrbError` on failure.

### Signature
```python
def getServerPrincipalDetails(service, hostname):
```

### Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `service` | str | yes | — | Kerberos service type for the server (e.g. `http`). |
| `hostname` | str | yes | — | Hostname of the server (e.g. `example.com`). |

### Return Type
`str` — the service principal (e.g. `http/example.com@EXAMPLE.COM`) for which the keytab contains an entry matching the prefix `service/hostname@`. Looked up by enumerating the default keytab (`krb5_kt_default`, `src/kerberosgss.c:62`) and string-comparing unparsed principal names against the generated prefix (`src/kerberosgss.c:53-95`). The returned string is a fresh `malloc` copy freed after conversion to a Python str (`src/kerberos.c:104-109`).

### Throws
| Error type | Condition |
|---|---|
| `kerberos.KrbError` | `krb5_init_context`, `krb5_kt_default`, `krb5_kt_start_seq_get`, or `krb5_unparse_name` fails — `args == ((message, code),)` |
| `kerberos.KrbError` | no keytab entry matches — `args == (("Principal not found in keytab", -1),)` (`src/kerberosgss.c:92-94`) |

### Examples
```python
import kerberos

try:
    principal = kerberos.getServerPrincipalDetails("http", "example.com")
except kerberos.KrbError as e:
    msg, code = e.args[0]
    print("Lookup failed: %s (%s)" % (msg, code))
else:
    print("Service principal:", principal)
```
```

--------------------------------

### Python signature for authGSSServerInit

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-server.md

Documented Python signature for authGSSServerInit, taking a single service parameter. This is the public API for initializing the server context.

```python
# pysrc/kerberos.py:188 — documented signature
def authGSSServerInit(service):
```

--------------------------------

### channelBindings(initiator_addrtype=0, initiator_address=None, acceptor_addrtype=0, acceptor_address=None, application_data=None)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/channel-bindings.md

Creates a gss_channel_bindings_struct capsule for use with authGSSClientStep. All parameters are optional keyword arguments.

```APIDOC
## channelBindings(initiator_addrtype=0, initiator_address=None, acceptor_addrtype=0, acceptor_address=None, application_data=None)

### Description
Creates a channel bindings structure for GSSAPI authentication, used to bind the authentication to a specific data channel (e.g., TLS session). The returned capsule is passed to `authGSSClientStep` via its `channel_bindings` keyword.

### Method
Function call

### Endpoint
`channelBindings` (Python function)

### Parameters
All parameters are optional keyword arguments.

- **initiator_addrtype** (int) - Optional - Address type of the initiator (see `GSS_C_AF_*` constants, e.g., `GSS_C_AF_INET` = 2). Default: `GSS_C_AF_UNSPEC` (0).
- **initiator_address** (bytes/str) - Optional - Address of the initiator. Default: `None` (empty buffer).
- **acceptor_addrtype** (int) - Optional - Address type of the acceptor. Default: `GSS_C_AF_UNSPEC` (0).
- **acceptor_address** (bytes/str) - Optional - Address of the acceptor. Default: `None` (empty buffer).
- **application_data** (bytes/str) - Optional - Application data; for TLS this is typically `b"tls-server-endpoint:" + <certificate digest>` per RFC 5929. Default: `None` (empty buffer).

### Return Type
An opaque capsule wrapping a `struct gss_channel_bindings_struct` pointer. The capsule owns the copied byte buffers and the struct itself.

### Throws
- **TypeError** - Argument parsing failure, e.g., wrong types for address data.

### Examples
```python
import base64, hashlib, kerberos

def tls_server_endpoint_bindings(socket):
    """RFC 5929 channel bindings from a TLS socket's server certificate."""
    server_certificate = socket.getpeercert(True)
    certificate_hash = hashlib.sha256(server_certificate).hexdigest().upper()
    certificate_digest = base64.b16decode(certificate_hash)
    application_data = b"tls-server-endpoint:%s" % certificate_digest
    return kerberos.channelBindings(application_data=application_data)

cb = tls_server_endpoint_bindings(sock)
rc, ctx = kerberos.authGSSClientInit(kerb_spn)
rc = kerberos.authGSSClientStep(ctx, server_challenge, channel_bindings=cb)
```

With initiator and acceptor addresses:

```python
import kerberos, socket

cb = kerberos.channelBindings(
    initiator_addrtype=kerberos.GSS_C_AF_INET,
    initiator_address=socket.inet_aton("192.0.2.10"),
    acceptor_addrtype=kerberos.GSS_C_AF_INET,
    acceptor_address=socket.inet_aton("192.0.2.20"),
    application_data=b"tls-server-endpoint:" + digest,
)
```
```

--------------------------------

### authGSSClientClean(ctx)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Compatibility no-op. The context frees itself when garbage-collected, so this function does nothing but is provided for compatibility.

```APIDOC
## authGSSClientClean(ctx)

### Description
Compatibility no-op. The context frees itself when garbage-collected, so this function does nothing but is provided for compatibility.

### Method
Function call

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **ctx** (capsule) - Required - The context capsule returned by `authGSSClientInit`.

### Request Example
```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... complete authentication ...
kerberos.authGSSClientClean(ctx)
```

### Response
#### Success Response (200)
No return value.

#### Response Example
```python
None
```

### Error Handling
No errors are raised.
```

--------------------------------

### kerberos.authGSSClientResponse(context)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Returns the base64-encoded client response from the last GSSAPI step.

```APIDOC
## authGSSClientResponse(context)

### Description
Returns the base64-encoded client response from the last GSSAPI step.

### Method
Function call

### Endpoint
`kerberos.authGSSClientResponse(context)`

### Parameters
- **context** - Required - The GSSAPI context handle.

### Returns
- **string** - Base64-encoded response.

### Example
```python
import kerberos
response = kerberos.authGSSClientResponse(context)
```
```

--------------------------------

### C wrapper signature for channelBindings

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/channel-bindings.md

C implementation of the channelBindings wrapper, showing the keyword argument parsing with format '|iet#iet#et#'.

```c
/* src/kerberos.c:195 — wrapper; kwlist = {"initiator_addrtype", "initiator_address",
 *                                        "acceptor_addrtype", "acceptor_address",
 *                                        "application_data"} */
static PyObject *channelBindings(PyObject *self, PyObject *args, PyObject* keywds) {
    int initiator_addrtype = GSS_C_AF_UNSPEC;
    int acceptor_addrtype = GSS_C_AF_UNSPEC;
    const char *encoding = NULL;
    ...
    if (!PyArg_ParseTupleAndKeywords(args, keywds, "|iet#iet#et#", kwlist,
            &initiator_addrtype, &encoding, &initiator_address, &initiator_length,
            &acceptor_addrtype, &encoding, &acceptor_address, &acceptor_length,
            &encoding, &application_data, &application_length)) {

```

--------------------------------

### Import kerberos module

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Import the kerberos module. The module is a single top-level compiled extension, not a package, so this is the only import path.

```python
import kerberos
```

--------------------------------

### kerberos.authGSSClientUnwrap(context, challenge)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Performs client-side GSSAPI unwrap on the given challenge data.

```APIDOC
## authGSSClientUnwrap(context, challenge)

### Description
Performs client-side GSSAPI unwrap on the given challenge data.

### Method
Function call

### Endpoint
`kerberos.authGSSClientUnwrap(context, challenge)`

### Parameters
- **context** - Required - The GSSAPI context handle.
- **challenge** (string) - Required - The data to unwrap (base64 encoded).

### Returns
- **string** - The unwrapped data.

### Exceptions
- **GSSError** - Raised on unwrap failure.

### Example
```python
import kerberos
unwrapped = kerberos.authGSSClientUnwrap(context, challenge)
```
```

--------------------------------

### kerberos.channelBindings(**kwargs)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Builds a gss_channel_bindings_struct capsule for use in GSSAPI operations.

```APIDOC
## channelBindings(**kwargs)

### Description
Builds a gss_channel_bindings_struct capsule for use in GSSAPI operations.

### Method
Function call

### Endpoint
`kerberos.channelBindings(**kwargs)`

### Parameters
- **kwargs** - Optional - Channel binding parameters.

### Returns
- **capsule** - A channel bindings capsule.

### Example
```python
import kerberos
bindings = kerberos.channelBindings()
```
```

--------------------------------

### Multi-step GSS negotiation loop with authGSSClientStep

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Multi-step negotiation loop using authGSSClientStep. The first challenge is empty (""). The loop continues while rc equals AUTH_GSS_CONTINUE (0); on completion, the context's username is populated.

```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
challenge = ""  # first token is empty
while rc == kerberos.AUTH_GSS_CONTINUE:
    rc = kerberos.authGSSClientStep(ctx, challenge)
    challenge = kerberos.authGSSClientResponse(ctx)  # send this to the server
    # ... exchange `challenge` over the wire, receive the server's next token ...
```

--------------------------------

### checkPassword(user, pswd, service, default_realm, verify=True)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/basic-auth.md

Authenticates a user with a password against a Kerberos service. Returns True on success, raises BasicAuthError on failure.

```APIDOC
## checkPassword(user, pswd, service, default_realm, verify=True)

### Description
Authenticates a user with a password against a Kerberos service. Returns True on success, raises BasicAuthError on failure.

### Method
Function call

### Endpoint
`kerberos.checkPassword(user, pswd, service, default_realm, verify=True)`

### Parameters
- **user** (str) - Required - Kerberos user name. A realm may be included by appending `@` plus the realm to the user id; otherwise the `default_realm` is appended.
- **pswd** (str) - Required - Password for the user.
- **service** (str) - Required - Kerberos service to check access for, of the form `sss/xx.yy.zz`, e.g. `http/example.com`.
- **default_realm** (str) - Required - Realm used when the user string contains no `@`; Kerberos realms are normally uppercase (e.g. `EXAMPLE.COM`).
- **verify** (bool) - Optional - Default: True - Flag for KDC verification (`krb5_verify_init_creds`) of the service ticket.

### Return Type
`bool` — `True` if authentication succeeds, `False` otherwise. Note: on every failure path the wrapper raises `BasicAuthError` instead of returning `False`.

### Throws
- `kerberos.BasicAuthError` - If `krb5_init_context` fails - args == (("Cannot initialize Kerberos5 context", code),)
- `kerberos.BasicAuthError` - If `krb5_parse_name` fails for service or user, `krb5_unparse_name` fails, `krb5_get_init_creds_password` fails, or `krb5_verify_init_creds` fails - args == (message, code)

### Examples
Basic verification:

```python
import kerberos

try:
    ok = kerberos.checkPassword("jdoe", "s3cret", "http/example.com", "EXAMPLE.COM")
except kerberos.BasicAuthError as e:
    message, code = e.args  # e.g. ("Client not found in Kerberos database", -1765328377)
    print("Authentication failed: %s (error %d)" % (message, code))
else:
    print("Authenticated:", ok)
```

With KDC verification disabled and an explicit realm in the user name:

```python
import kerberos

# Realm is taken from the user string ("@EXAMPLE.COM"), so default_realm is unused;
# KDC verification of the service ticket is turned off.
if kerberos.checkPassword("jdoe@EXAMPLE.COM", "s3cret", "http/example.com", "ANY.REALM", verify=False):
    print("Credentials valid")
```
```

--------------------------------

### authGSSClientStep(ctx, challenge)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

Exchanges challenges during the authentication handshake. This function should be called repeatedly while it returns `AUTH_GSS_CONTINUE (0)`, until it returns `AUTH_GSS_COMPLETE (1)`. It takes the context capsule from `authGSSClientInit` and the challenge data from the server.

```APIDOC
## authGSSClientStep(ctx, challenge)

### Description
Exchanges challenges during the authentication handshake. This function should be called repeatedly while it returns `AUTH_GSS_CONTINUE (0)`, until it returns `AUTH_GSS_COMPLETE (1)`. It takes the context capsule from `authGSSClientInit` and the challenge data from the server.

### Method
Function call

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **ctx** (capsule) - Required - The context capsule returned by `authGSSClientInit`.
- **challenge** (bytes) - Required - The challenge data received from the server.

### Request Example
```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... send initial response to server, receive challenge ...
rc = kerberos.authGSSClientStep(ctx, challenge)
```

### Response
#### Success Response (200)
- **result code** (int) - `AUTH_GSS_CONTINUE` (0) if more steps are needed, `AUTH_GSS_COMPLETE` (1) if authentication is complete.

#### Response Example
```python
0  # continue
1  # complete
```

### Error Handling
- **kerberos.GSSError** - Raised when the GSSAPI step fails.
```

--------------------------------

### kerberos.authGSSClientWrapIov(context, data, protect=1)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Performs IOV-mode wrap on the given data. Returns a tuple (result, pad_len).

```APIDOC
## authGSSClientWrapIov(context, data, protect=1)

### Description
Performs IOV-mode wrap on the given data. Returns a tuple (result, pad_len).

### Method
Function call

### Endpoint
`kerberos.authGSSClientWrapIov(context, data, protect=1)`

### Parameters
- **context** - Required - The GSSAPI context handle.
- **data** (string) - Required - The data to wrap.
- **protect** (int) - Optional - Whether to protect the data (default 1).

### Returns
- **tuple** - (result, pad_len) where result is the wrapped data and pad_len is the padding length.

### Exceptions
- **GSSError** - Raised on wrap failure.

### Example
```python
import kerberos
result, pad_len = kerberos.authGSSClientWrapIov(context, data)
```
```

--------------------------------

### Python usage of authGSSWinRMEncryptMessage

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-extensions.md

Demonstrates initializing a GSSAPI client context and calling authGSSWinRMEncryptMessage to encrypt a WinRM request body, returning the encrypted data and header for sending.

```python
import kerberos

rc, ctx = kerberos.authGSSClientInit("http@example.com")
# ... negotiate + wrap a WinRM request ...
enc_body, header = kerberos.authGSSWinRMEncryptMessage(ctx, b'<?xml version="1.0"?>...')
# send enc_body and header to the WinRM server
```

--------------------------------

### authGSSClientInit C wrapper signature

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/gssapi-client.md

C wrapper for authGSSClientInit, showing the function signature and the default gss_flags value. The wrapper parses arguments with PyArg_ParseTupleAndKeywords using the keyword list {"service", "principal", "gssflags", "mech_oid"}.

```c
/* src/kerberos.c:128 — wrapper; kwlist = {"service", "principal", "gssflags", "mech_oid"} */
static PyObject* authGSSClientInit(PyObject* self, PyObject* args, PyObject* keywds) {
    ...
    long int gss_flags = GSS_C_MUTUAL_FLAG | GSS_C_SEQUENCE_FLAG;
    if (!PyArg_ParseTupleAndKeywords(args, keywds, "s|zlO", kwlist, &service, &principal, &gss_flags, &pymech_oid)) {

```

--------------------------------

### Python documented signature for channelBindings

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/channel-bindings.md

Python signature of channelBindings as documented in pysrc/kerberos.py.

```python
# pysrc/kerberos.py:273 — documented signature
def channelBindings(**kwargs):

```

--------------------------------

### kerberos.authGSSServerClean(context)

Source: https://github.com/02strich/pykerberos/blob/master/_autodocs/api-reference/kerberos.md

Cleans up a server-side GSSAPI context. Always returns 1.

```APIDOC
## authGSSServerClean(context)

### Description
Cleans up a server-side GSSAPI context. Always returns 1.

### Method
Function call

### Endpoint
`kerberos.authGSSServerClean(context)`

### Parameters
- **context** - Required - The GSSAPI context handle.

### Returns
- **int** - Always 1.

### Example
```python
import kerberos
kerberos.authGSSServerClean(context)
```
```
Tokens:
Raw