Files

378 lines
15 KiB
Python

# Copyright: (c) 2020, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import enum
import typing
GSSError: typing.Type[Exception]
try:
from gssapi.raw import GSSError # type: ignore
except ImportError as e:
GSSError = Exception
WinError: typing.Type[Exception]
try:
WinError = WindowsError # type: ignore
except NameError:
WinError = Exception
class NativeError(Exception):
"""Stub for a native error that can be used to generate a SpnegoError from a known platform native code."""
def __init__(self, msg: str, **kwargs: typing.Any) -> None:
self.msg = msg
for key in ["maj_code", "winerror"]:
if key in kwargs:
setattr(self, key, kwargs[key])
class NegotiateOptions(enum.IntFlag):
"""Flags that the caller can use to control the negotiation behaviour.
A list of features as bit flags that the caller can specify when creating the security context. These flags can
be used on both Windows or Linux but are a no-op on Windows as it should always have the same features available.
On Linux the features it can implement depend on a wide range of factors like the system libraries/headers that
are installed, what GSSAPI implementation is present, and what Python libraries are available.
This is a pretty advanced feature and is mostly a way to control the kerberos to ntlm fallback behaviour on Linux.
The `use_*` options when combined with `protocol='credssp'` control the underlying auth proxy provider that is used
in the CredSSP authentication process and not the parent context proxy the user interacts with.
These are the currently implemented feature flags:
use_sspi:
Ensures the context proxy used is :class:`spnego._sspi.SSPIProxy`.
use_gssapi:
Ensures the context proxy used is :class:`spnego._gss.GSSAPIProxy`.
use_negotiate:
Ensures the context proxy used is :class:`spnego._negotiate.NegotiateProxy`.
use_ntlm:
Ensures the context proxy used is :class:`spnego._ntlm.NTLMProxy`.
negotiate_kerberos:
Will make sure that Kerberos is at least available to try for authentication when using the `negotiate`
protocol. If Kerberos cannot be used due to the Python gssapi library not being installed then it will raise a
:class:`spnego.exceptions.FeatureMissingError`. If Kerberos was available but it cannot get a credential or
create a context then it will just fallback to NTLM auth. If you wish to only use Kerberos with no NTLM
fallback, set `protocol='kerberos'` when creating the security context.
session_key:
Ensure that the authenticated context will be able to return the session key that was negotiated between the
client and the server. Older versions of `gss-ntlmssp`_ do not expose the functions required to retrieve this
info so when this feature flag is set then the NTLM fallback process will use a builtin NTLM process and not
`gss-ntlmssp`_ if the latter is too old to retrieve the session key. Cannot be used in combination with
`protocol='credssp'` as CredSSP does not provide a session key.
wrapping_iov:
The GSSAPI IOV methods are extensions to the Kerberos spec and not implemented or exposed on all platforms,
macOS is a popular example. If the caller requires the wrap_iov and unwrap_iov methods this will ensure it
fails fast before the auth has been set up. Unfortunately there is no fallback for this as if the headers
aren't present for GSSAPI then we can't do anything to fix that. This won't fail if `negotiate` was used and
NTLM was the chosen protocol as that happens post negotiation.
wrapping_winrm:
To created a wrapped WinRM message the IOV extensions are required when using Kerberos auth. Setting this flag
will skip Kerberos when `protocol='negotiate'` if the IOV headers aren't present and just fallback to NTLM.
.. _gss-ntlmssp:
https://github.com/gssapi/gss-ntlmssp
"""
none = 0x00000000
# Force a specific provider
use_sspi = 0x00000001
use_gssapi = 0x00000002
use_negotiate = 0x00000004
use_ntlm = 0x00000008
negotiate_kerberos = 0x00000010
session_key = 0x00000020
wrapping_iov = 0x00000040
wrapping_winrm = 0x00000080
class FeatureMissingError(Exception):
@property
def feature_id(self) -> NegotiateOptions:
return self.args[0]
@property
def message(self) -> str:
msg = {
NegotiateOptions.negotiate_kerberos: "The Python gssapi library is not installed so Kerberos cannot be "
"negotiated.",
NegotiateOptions.wrapping_iov: "The system is missing the GSSAPI IOV extension headers or CredSSP is "
"being requested, cannot utilize wrap_iov and unwrap_iov",
NegotiateOptions.wrapping_winrm: "The system is missing the GSSAPI IOV extension headers required for "
"WinRM encryption with Kerberos.",
NegotiateOptions.session_key: "The protocol selected does not support getting the session key.",
}.get(self.feature_id, "Unknown option flag: %d" % self.feature_id)
return msg
def __str__(self) -> str:
return self.message
class ErrorCode(enum.IntEnum):
"""Common error codes for SPNEGO operations.
Mostly a copy of the `GSS major error codes`_ with the names made more pythonic. Not all codes have a corresponding
SpnegoError class as they are reserved for the codes that apply to both GSSAPI and SSPI.
.. _GSS major error codes:
https://docs.oracle.com/cd/E19683-01/816-1331/reference-4/index.html
"""
bad_mech = 1 # BadMechanismError
bad_name = 2 # BadNameError
# bad_nametype = 3 # No equivalent in SSPI, shouldn't happen in our code as well.
bad_bindings = 4 # BadBindings
# bad_status = 5 # Only used in gss_display_status which we don't care about.
bad_mic = 6 # BadMICError
no_cred = 7 # NoCredentialError
no_context = 8 # NoContextError
invalid_token = 9 # InvalidTokenError
invalid_credential = 10 # InvalidCredentialError
credentials_expired = 11 # CredentialsExpiredError
context_expired = 12 # ContextExpiredError
failure = 13 # This is a generic error with the error coming from the minor code, uses SpnegoError directly.
bad_qop = 14 # UnsupportedQop
# unauthorized = 15 # Shouldn't happen in our code, we don't do any authorization functions.
unavailable = 16 # OperationNotAvailableError
# duplicate_element = 17 # Shouldn't happen in our code.
# name_not_mn = 18 # Shouldn't happen in our code.
# Implementation is inspired by the python-gssapi project https://github.com/pythongssapi/python-gssapi.
# https://github.com/pythongssapi/python-gssapi/blob/826c02de1c1885896924bf342c60087f369c6b1a/gssapi/raw/misc.pyx#L180
class _SpnegoErrorRegistry(type):
__registry: typing.Dict[int, typing.Type] = {}
__gssapi_map: typing.Dict[int, int] = {}
__sspi_map: typing.Dict[int, int] = {}
def __init__(
cls,
*args: typing.Any,
**kwargs: typing.Any,
) -> None:
# Load up the registry with the instantiated class so we can look it up when creating a SpnegoError.
error_code = getattr(cls, "ERROR_CODE", None)
if error_code is not None and error_code not in cls.__registry:
cls.__registry[error_code] = cls
# Map the system error codes to the common spnego error code.
for system_attr, mapping in [("_GSSAPI_CODE", cls.__gssapi_map), ("_SSPI_CODE", cls.__sspi_map)]:
codes = getattr(cls, system_attr, None)
if codes is None:
continue
if not isinstance(codes, (list, tuple)):
codes = [codes]
for c in codes:
mapping[c] = error_code or 0
def __call__(
cls,
error_code: typing.Optional[int] = None,
base_error: typing.Optional[Exception] = None,
*args: typing.Any,
**kwargs: typing.Any,
) -> "_SpnegoErrorRegistry":
error_code = error_code if error_code is not None else getattr(cls, "ERROR_CODE", None)
if error_code is None:
if not base_error:
raise ValueError("%s requires either an error_code or base_error" % cls.__name__)
# GSSError
maj_code = getattr(base_error, "maj_code", None)
# WindowsError
winerror = getattr(base_error, "winerror", None)
if maj_code is not None:
error_code = cls.__gssapi_map.get(maj_code, None)
elif winerror is not None:
error_code = cls.__sspi_map.get(winerror, None)
else:
raise ValueError(
"base_error of type '%s' is not supported, must be a gssapi.exceptions.GSSError or "
"WindowsError" % type(base_error).__name__
)
new_cls = cls.__registry.get(error_code or 0, cls)
return super(_SpnegoErrorRegistry, new_cls).__call__(
error_code, # type: ignore[arg-type] # I cannot understand this, seems to be bug?
base_error,
*args,
**kwargs,
)
class SpnegoError(Exception, metaclass=_SpnegoErrorRegistry):
"""Common error for SPNEGO exception.
Creates an common error record for SPNEGO errors raised by pyspnego. This error record can wrap system level error
records raised by GSSAPI or SSPI and wrap them into a common error record across the various platforms. While this
reflects the GSSAPI major codes that can be raised, it is up to the GSSAPI platform to conform to those error
codes. Some platforms like MIT krb5 always report `GSS_S_FAILURE` and use the minor code to report the actual
error message.
Args:
error_code: The ErrorCode for the error, this must be set if base_error is not set.
base_error: The system level error from SSPI or GSSAPI, this must be set if error_code is not set.
context_msg: Optional message to provide more context around the error.
Attributes:
base_error (Optional[Union[GSSError, WinError]]): The system level error if one was provided.
"""
# Classes the subclass this type need to provide the following class attribute:
#
# ERROR_CODE = common ErrorCode value for the exception
# _BASE_MESSAGE = common string that explains the error code in the absence of the system error message.
#
# The following attributes are used to map specific system error codes to the common ErrorCode error.
# _GSSAPI_CODE = The GSSAPI major_code from GSSError to map to the common error code
# _SSPI_CODE = The winerror value from an WindowsError to map to the common error code
def __init__(
self,
error_code: typing.Optional[typing.Union[int, ErrorCode]] = None,
base_error: typing.Optional[Exception] = None,
context_msg: typing.Optional[str] = None,
) -> None:
self.base_error = base_error
self._error_code = error_code
self._context_message = context_msg
super(SpnegoError, self).__init__(self.message)
@property
def nt_status(self) -> int:
"""The Windows NT Status code that represents this error."""
codes = getattr(self, "_SSPI_CODE", self._error_code) or 0xFFFFFFFF
return codes[0] if isinstance(codes, (list, tuple)) else codes
@property
def message(self) -> str:
error_code = self._error_code if self._error_code is not None else 0xFFFFFFFF
if self.base_error:
base_message = str(self.base_error)
else:
base_message = getattr(self, "_BASE_MESSAGE", "Unknown error code")
msg = "SpnegoError (%d): %s" % (error_code, base_message)
if self._context_message:
msg += ", Context: %s" % self._context_message
return msg
class BadMechanismError(SpnegoError):
ERROR_CODE = ErrorCode.bad_mech
_BASE_MESSAGE = "An unsupported mechanism was requested"
_GSSAPI_CODE = 65536 # GSS_S_BAD_MECH
_SSPI_CODE = -2146893051 # SEC_E_SECPKG_NOT_FOUND
class BadNameError(SpnegoError):
ERROR_CODE = ErrorCode.bad_name
_BASE_MESSAGE = "An invalid name was supplied"
_GSSAPI_CODE = 1310722 # GSS_S_BAD_NAME
_SSPI_CODE = -2146893053 # SEC_E_TARGET_UNKNOWN
class BadBindingsError(SpnegoError):
ERROR_CODE = ErrorCode.bad_bindings
_BASE_MESSAGE = "Invalid channel bindings"
_GSSAPI_CODE = 262144 # GSS_BAD_BINDINGS
_SSPI_CODE = -2146892986 # SEC_E_BAD_BINDINGS
class BadMICError(SpnegoError):
ERROR_CODE = ErrorCode.bad_mic
_BASE_MESSAGE = "A token had an invalid Message Integrity Check (MIC)"
_GSSAPI_CODE = 3932166 # GSS_BAD_MIC
_SSPI_CODE = -2146893041 # SEC_E_MESSAGE_ALTERED
class NoCredentialError(SpnegoError):
ERROR_CODE = ErrorCode.no_cred
_BASE_MESSAGE = "No credentials were supplied, or the credentials were unavailable or inaccessible"
_GSSAPI_CODE = 458752 # GSS_NO_CRED
_SSPI_CODE = -2146893042 # SEC_E_NO_CREDENTIALS
class NoContextError(SpnegoError):
ERROR_CODE = ErrorCode.no_context
_BASE_MESSAGE = "No context has been established, or invalid handled passed in"
_GSSAPI_CODE = 524288 # GSS_S_NO_CONTEXT
_SSPI_CODE = -2146893055 # SEC_E_INVALID_HANDLE
class InvalidTokenError(SpnegoError):
ERROR_CODE = ErrorCode.invalid_token
_BASE_MESSAGE = "A token was invalid, or the logon was denied"
_GSSAPI_CODE = 589824 # GSS_S_DEFECTIVE_TOKEN
_SSPI_CODE = [-2146893044, -2146893048] # SEC_E_LOGON_DENIED, SEC_E_INVALID_TOKEN
class InvalidCredentialError(SpnegoError):
ERROR_CODE = ErrorCode.invalid_credential
_BASE_MESSAGE = "A credential was invalid"
_GSSAPI_CODE = 655360 # GSS_S_DEFECTIVE_CREDENTIAL
_SSPI_CODE = -1073741715 # STATUS_LOGON_FAILURE
class CredentialsExpiredError(SpnegoError):
ERROR_CODE = ErrorCode.credentials_expired
_BASE_MESSAGE = "The referenced credentials have expired"
_GSSAPI_CODE = 720896 # * GSS_S_CREDENTIALS_EXPIRED
_SSPI_CODE = -1073741711 # STATUS_PASSWORD_EXPIRED
class ContextExpiredError(SpnegoError):
ERROR_CODE = ErrorCode.context_expired
_BASE_MESSAGE = "Security context has expired"
_GSSAPI_CODE = 786432 # GSS_S_CONTEXT_EXPIRED
_SSPI_CODE = -2146893033 # SEC_E_CONTEXT_EXPIRED
class UnsupportedQop(SpnegoError):
ERROR_CODE = ErrorCode.bad_qop
_BASE_MESSAGE = "The quality-of-protection requested could not be provided"
_GSSAPI_CODE = 917504 # GSS_S_BAD_QOP
_SSPI_CODE = -2146893046 # SEC_E_QOP_NOT_SUPPORTED
class OperationNotAvailableError(SpnegoError):
ERROR_CODE = ErrorCode.unavailable
_BASE_MESSAGE = "Operation not supported or available"
_GSSAPI_CODE = 1048576 # GSS_S_UNAVAILABLE
_SSPI_CODE = -2146893054 # SEC_E_UNSUPPORTED_FUNCTION