Qore krb5 Module
================

The Qore krb5 module provides Kerberos 5 and GSSAPI primitives for Qore so
that Qore code and Qorus integration services can participate in enterprise
Kerberos-authenticated networks as first-class citizens, alongside native
Java and .NET services.

The binary module is named `krb5`; a small Qore-language helper module is
provided as `Krb5Util`.

The module provides:

- Kerberos realm, credential-cache, and keytab discovery
- Kerberos initial credential acquisition from passwords and keytabs, with
  noninteractive service use, KDC canonicalization, PAC requests, enctype
  restriction, and FAST armor credential caches
- Credential metadata and credential-cache store/list/enumerate operations
- Credential renewal and service-ticket acquisition from existing caches
- Credential lifecycle helpers for expiry and renewal-threshold checks
- In-memory credential caches and keytabs for tests and service setup
- Filesystem sandbox enforcement for file-backed credential caches and
  keytabs
- Kerberos principal parsing, enterprise (UPN) principal parsing, and
  structured introspection
- Explicit GSSAPI credentials imported from Kerberos credential caches or
  client keytabs, so GSSAPI code does not need to rely on process-global
  default credentials
- Initiator-side GSSAPI security contexts with configurable flags, lifetime,
  mechanism selection, and explicit target-name type selection
- Acceptor-side GSSAPI security contexts for service endpoints, including
  explicit service-keytab credentials and authenticated initiator-name
  reporting
- Delegated credential extraction from completed acceptor contexts
- GSSAPI channel bindings, including RFC 5929 `tls-server-end-point`
  application data for hardened SASL/GSSAPI deployments
- GSSAPI wrap, unwrap, and wrap-size-limit helpers for negotiated integrity
  and confidentiality layers
- GSSAPI MIC (Message Integrity Code) compute and verify for standalone
  integrity tokens used in SASL/GSSAPI integrity verification
- Credential cache collection discovery across all configured backends
- S4U2Self credential impersonation for GSS identity-forwarding flows, plus
  a low-level S4U2Proxy binding for caller-supplied Kerberos evidence tickets
- GSS-level impersonated client context helper for service-to-service S4U
  flows
- Keytab entry removal for key rotation workflows
- Keytab rotation helpers for highest-kvno discovery and old-entry cleanup
- Credential renewal workflow helper for long-running services
- Credential cache maintenance helpers for renewal and service-ticket
  prefetch workflows
- Kerberos environment validation with structured checks for deployment
  diagnostics
- a `Krb5Util` helper module with Qore-language Kerberos and SPNEGO utilities,
  including HTTP Negotiate client/server step helpers

Higher-level helper APIs should use `Logger::LoggerInterface` for diagnostics.
Logs must not include passwords, keys, raw tickets, raw GSS tokens, or
delegated credential material.

Building
--------

Requires Qore 2.0 or later and MIT Kerberos / GSSAPI development libraries.

  mkdir build && cd build
  cmake .. -DCMAKE_BUILD_TYPE=Release
  cmake --build .

To run the tests from the repository root:

  test/run-tests.sh

Using the module
----------------

Qore code that needs the binary API should use:

  %requires krb5

Qore code that needs helper functions such as
`Krb5Util::getHostBasedServicePrincipal()` should use:

  %requires Krb5Util

The helper module also includes SPNEGO helpers for HTTP Negotiate
integrations:

  string auth = Krb5Util::buildNegotiateAuthorizationHeader(gss_token_hex);
  string response_token = Krb5Util::extractNegotiateHeaderToken(
      "WWW-Authenticate: Negotiate ...");
  hash<Krb5Util::SpnegoResponseInfo> info =
      Krb5Util::parseNegotiateResponseHeader("Negotiate ...");

Client/server HTTP Negotiate exchanges can use header-level step helpers:

  hash<Krb5Util::NegotiateClientStepInfo> client_step =
      Krb5Util::buildNegotiateClientStep(initiator, www_authenticate_header);
  hash<Krb5Util::NegotiateServerStepInfo> server_step =
      Krb5Util::acceptNegotiateAuthorizationHeader(acceptor,
          client_step.authorization_header);

Credential metadata can be evaluated without exposing key or ticket material:

  hash<Krb5Util::CredentialLifecycleInfo> lifecycle =
      Krb5Util::getCredentialLifecycleInfo(creds.getInfo(), 300);
  if (lifecycle.should_renew) {
      # renew before expiry
  }

Keytab rotation code can inspect and remove old service keys without logging
key material:

  int highest = Krb5Util::getKeytabHighestKvno(keytab, service_principal);
  int removed = Krb5Util::removeOldKeytabEntries(keytab, service_principal,
      highest);

Long-running services can maintain a cache and prefetch service tickets:

  hash<Krb5Util::CredentialCacheMaintenanceOptions> maint_opts();
  maint_opts.renew_threshold_seconds = 300;
  maint_opts.service_principals = ("HTTP/backend.example.com@EXAMPLE.COM",);
  hash<Krb5Util::CredentialCacheMaintenanceResult> maint =
      Krb5Util::maintainCredentialCache(ctx, cache, maint_opts, logger);

Deployment checks can require a usable service keytab:

  hash<Krb5Util::KerberosEnvironmentValidationOptions> env_opts();
  env_opts.require_service_principal = True;
  hash<Krb5Util::KerberosEnvironmentInfo> env =
      Krb5Util::validateKerberosEnvironment(
          "HTTP/qorus.example.com@EXAMPLE.COM", logger, env_opts);

See the generated HTML documentation for the class reference, security model,
use cases, and runnable examples.

Questions
---------

Please direct questions to david@qore.org.