841 lines
34 KiB
Python
841 lines
34 KiB
Python
|
|
# Copyright: (c) 2020, Jordan Borean (@jborean93) <jborean93@gmail.com>
|
||
|
|
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
|
||
|
|
|
||
|
|
import abc
|
||
|
|
import dataclasses
|
||
|
|
import enum
|
||
|
|
import typing
|
||
|
|
import warnings
|
||
|
|
|
||
|
|
from spnego._credential import Credential
|
||
|
|
from spnego._text import to_text
|
||
|
|
from spnego.channel_bindings import GssChannelBindings
|
||
|
|
from spnego.exceptions import FeatureMissingError, NegotiateOptions, SpnegoError
|
||
|
|
from spnego.iov import BufferType, IOVBuffer, IOVResBuffer
|
||
|
|
|
||
|
|
F = typing.TypeVar("F", bound=typing.Callable[..., typing.Any])
|
||
|
|
NativeIOV = typing.TypeVar("NativeIOV", bound=typing.Any)
|
||
|
|
IOV = typing.Union[
|
||
|
|
IOVBuffer,
|
||
|
|
IOVResBuffer,
|
||
|
|
typing.Tuple[typing.Union[BufferType, int], typing.Union[bool, bytes, int]],
|
||
|
|
typing.Union[BufferType, int],
|
||
|
|
bytes,
|
||
|
|
]
|
||
|
|
|
||
|
|
|
||
|
|
def split_username(username: typing.Optional[str]) -> typing.Tuple[typing.Optional[str], typing.Optional[str]]:
|
||
|
|
"""Splits a username and returns the domain component.
|
||
|
|
|
||
|
|
Will split a username in the Netlogon form `DOMAIN\\username` and return the domain and user part as separate
|
||
|
|
strings. If the user does not contain the `DOMAIN\\` prefix or is in the `UPN` form then then user stays the same
|
||
|
|
and the domain is an empty string.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
username: The username to split
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
Tuple[Optional[str], Optional[str]]: The domain and username.
|
||
|
|
"""
|
||
|
|
if username is None:
|
||
|
|
return None, None
|
||
|
|
|
||
|
|
domain: typing.Optional[str]
|
||
|
|
if "\\" in username:
|
||
|
|
domain, username = username.split("\\", 1)
|
||
|
|
else:
|
||
|
|
domain = None
|
||
|
|
|
||
|
|
return to_text(domain, nonstring="passthru"), to_text(username, nonstring="passthru")
|
||
|
|
|
||
|
|
|
||
|
|
def wrap_system_error(error_type: typing.Type, context: typing.Optional[str] = None) -> typing.Callable[[F], F]:
|
||
|
|
"""Wraps a function that makes a native GSSAPI/SSPI syscall and convert native exceptions to a SpnegoError.
|
||
|
|
|
||
|
|
Wraps a function that can potentially raise a WindowsError or GSSError and converts it to the common SpnegoError
|
||
|
|
that is exposed by this library. This is to ensure the context proxy functions raise a common set of errors rather
|
||
|
|
than a specific error for the provider. The underlying error is preserved in the SpnegoError if the user wishes to
|
||
|
|
inspect that.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
error_type: The native error type that need to be wrapped.
|
||
|
|
context: An optional context message to add to the error if raised.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def decorator(func: F) -> F:
|
||
|
|
def wrapper(*args: typing.Any, **kwargs: typing.Any) -> F:
|
||
|
|
try:
|
||
|
|
return func(*args, **kwargs)
|
||
|
|
|
||
|
|
except error_type as native_err:
|
||
|
|
raise SpnegoError(base_error=native_err, context_msg=context) from native_err
|
||
|
|
|
||
|
|
return typing.cast(F, wrapper)
|
||
|
|
|
||
|
|
return decorator
|
||
|
|
|
||
|
|
|
||
|
|
class WrapResult(typing.NamedTuple):
|
||
|
|
"""Result of the `wrap()` function."""
|
||
|
|
|
||
|
|
data: bytes #: The bytes of the wrapped data.
|
||
|
|
encrypted: bool #: Whether the data was encrypted (True) or not (False).
|
||
|
|
|
||
|
|
|
||
|
|
class IOVWrapResult(typing.NamedTuple):
|
||
|
|
"""Result of the `wrap_iov()` function."""
|
||
|
|
|
||
|
|
buffers: typing.Tuple[IOVResBuffer, ...] #: The wrapped IOV buffers.
|
||
|
|
encrypted: bool #: Whether the buffer data was encrypted (True) or not (False).
|
||
|
|
|
||
|
|
|
||
|
|
class WinRMWrapResult(typing.NamedTuple):
|
||
|
|
"""Result of the `wrap_winrm()` function."""
|
||
|
|
|
||
|
|
header: bytes #: The header of the wrapped result.
|
||
|
|
data: bytes #: The wrapped data included any padding.
|
||
|
|
padding_length: int #: The length of the bytes added to the data for padding.
|
||
|
|
|
||
|
|
|
||
|
|
class UnwrapResult(typing.NamedTuple):
|
||
|
|
"""Result of the `unwrap()` function."""
|
||
|
|
|
||
|
|
data: bytes #: The bytes of the unwrapped data.
|
||
|
|
encrypted: bool #: Whether the input data was encrypted (True) or not (False)
|
||
|
|
qop: int #: The Quality of Protection used for the encrypted data.
|
||
|
|
|
||
|
|
|
||
|
|
class IOVUnwrapResult(typing.NamedTuple):
|
||
|
|
"""Result of the `unwrap_iov()` function."""
|
||
|
|
|
||
|
|
buffers: typing.Tuple[IOVResBuffer, ...] #: The unwrapped IOV buffers.
|
||
|
|
encrypted: bool #: Whether the input buffers were encrypted (True) or not (False)
|
||
|
|
qop: int #: The Quality of Protection used for the encrypted buffers.
|
||
|
|
|
||
|
|
|
||
|
|
@dataclasses.dataclass(frozen=True)
|
||
|
|
class SecPkgContextSizes:
|
||
|
|
"""Sizes of important structures used for messages.
|
||
|
|
|
||
|
|
This dataclass exposes the sizes of important structures used in message
|
||
|
|
support functions like wrap, wrap_iov, sign, etc. Use
|
||
|
|
:meth:`ContextReq.query_message_sizes` to retrieve this value for an
|
||
|
|
authenticated context.
|
||
|
|
|
||
|
|
Currently only ``header`` is exposed but other sizes may be added in the
|
||
|
|
future if needed.
|
||
|
|
|
||
|
|
Attributes:
|
||
|
|
header: The size of the header/signature of a wrapped token. This
|
||
|
|
corresponds to cbSecurityTrailer in SecPkgContext_Sizes in SSPI and
|
||
|
|
the size of the allocated GSS_IOV_BUFFER_TYPE_HEADER IOV buffer.
|
||
|
|
"""
|
||
|
|
|
||
|
|
header: int
|
||
|
|
|
||
|
|
|
||
|
|
class ContextReq(enum.IntFlag):
|
||
|
|
none = 0x00000000
|
||
|
|
|
||
|
|
# GSSAPI|SSPI flags
|
||
|
|
delegate = 0x00000001
|
||
|
|
mutual_auth = 0x00000002
|
||
|
|
replay_detect = 0x00000004
|
||
|
|
sequence_detect = 0x00000008
|
||
|
|
confidentiality = 0x00000010
|
||
|
|
integrity = 0x00000020
|
||
|
|
# anonymous = 0x00000040 # TODO: Add support for anonymous auth.
|
||
|
|
dce_style = 0x00001000
|
||
|
|
identify = 0x00002000
|
||
|
|
# Requires newer python-gssapi version to support https://github.com/pythongssapi/python-gssapi/pull/218
|
||
|
|
delegate_policy = 0x00080000
|
||
|
|
|
||
|
|
# Special flag that disables integrity/confidentiality on Kerberos/Negotiate
|
||
|
|
# This should not be set with integrity or confidentiality.
|
||
|
|
no_integrity = 0x10000000
|
||
|
|
|
||
|
|
# mutual_auth | replay_detect | sequence_detect | confidentiality | integrity
|
||
|
|
default = 0x00000002 | 0x00000004 | 0x00000008 | 0x00000010 | 0x00000020
|
||
|
|
|
||
|
|
|
||
|
|
class GSSMech(str, enum.Enum):
|
||
|
|
ntlm = "1.3.6.1.4.1.311.2.2.10"
|
||
|
|
spnego = "1.3.6.1.5.5.2"
|
||
|
|
|
||
|
|
# Kerberos has been put under several OIDs over time, we should only be using 'kerberos'.
|
||
|
|
kerberos = "1.2.840.113554.1.2.2" # The actual Kerberos OID, this should be the one used.
|
||
|
|
_ms_kerberos = "1.2.840.48018.1.2.2"
|
||
|
|
_kerberos_draft = "1.3.5.1.5.2"
|
||
|
|
_iakerb = "1.3.6.1.5.2"
|
||
|
|
|
||
|
|
# Not implemented.
|
||
|
|
kerberos_u2u = "1.2.840.113554.1.2.2.3"
|
||
|
|
negoex = "1.3.6.1.4.1.311.2.2.30"
|
||
|
|
|
||
|
|
@classmethod
|
||
|
|
def native_labels(cls) -> typing.Dict[str, str]:
|
||
|
|
return {
|
||
|
|
GSSMech.ntlm: "NTLM",
|
||
|
|
GSSMech.ntlm.value: "NTLM",
|
||
|
|
GSSMech.spnego: "SPNEGO",
|
||
|
|
GSSMech.spnego.value: "SPNEGO",
|
||
|
|
GSSMech.kerberos: "Kerberos",
|
||
|
|
GSSMech.kerberos.value: "Kerberos",
|
||
|
|
GSSMech._ms_kerberos: "MS Kerberos",
|
||
|
|
GSSMech._ms_kerberos.value: "MS Kerberos",
|
||
|
|
GSSMech._kerberos_draft: "Kerberos (draft)",
|
||
|
|
GSSMech._kerberos_draft.value: "Kerberos (draft)",
|
||
|
|
GSSMech._iakerb: "IAKerberos",
|
||
|
|
GSSMech._iakerb.value: "IAKerberos",
|
||
|
|
GSSMech.kerberos_u2u: "Kerberos User to User",
|
||
|
|
GSSMech.kerberos_u2u.value: "Kerberos User to User",
|
||
|
|
GSSMech.negoex: "NEGOEX",
|
||
|
|
GSSMech.negoex.value: "NEGOEX",
|
||
|
|
}
|
||
|
|
|
||
|
|
@property
|
||
|
|
def common_name(self) -> str:
|
||
|
|
if self.is_kerberos_oid:
|
||
|
|
return "kerberos"
|
||
|
|
|
||
|
|
return self.name
|
||
|
|
|
||
|
|
@property
|
||
|
|
def is_kerberos_oid(self) -> bool:
|
||
|
|
"""Determines if the mech is a Kerberos mech.
|
||
|
|
|
||
|
|
Kerberos has been known under serveral OIDs in the past. This tells the caller whether the OID is one of those
|
||
|
|
"known" OIDs.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bool: Whether the mech is a Kerberos mech (True) or not (False).
|
||
|
|
"""
|
||
|
|
return self in [GSSMech.kerberos, GSSMech._ms_kerberos, GSSMech._kerberos_draft, GSSMech._iakerb]
|
||
|
|
|
||
|
|
@staticmethod
|
||
|
|
def from_oid(oid: str) -> "GSSMech":
|
||
|
|
"""Converts an OID string to a GSSMech value.
|
||
|
|
|
||
|
|
Converts an OID string to a GSSMech value if it is known.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
oid: The OID as a string to convert from.
|
||
|
|
|
||
|
|
Raises:
|
||
|
|
ValueError: if the OID is not a known GSSMech.
|
||
|
|
"""
|
||
|
|
for mech in GSSMech:
|
||
|
|
if mech.value == oid:
|
||
|
|
return mech
|
||
|
|
else:
|
||
|
|
raise ValueError("'%s' is not a valid GSSMech OID" % oid)
|
||
|
|
|
||
|
|
|
||
|
|
class ContextProxy(metaclass=abc.ABCMeta):
|
||
|
|
"""Base class for a authentication context.
|
||
|
|
|
||
|
|
A base class the defined a common entry point for the various authentication context's that are used in this
|
||
|
|
library. For a new context to be added it must implement the abstract functions in this class and translate the
|
||
|
|
calls to what is required internally.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
credentials: A list of credentials to use for authentication.
|
||
|
|
hostname: The principal part of the SPN. This is required for Kerberos auth to build the SPN.
|
||
|
|
service: The service part of the SPN. This is required for Kerberos auth to build the SPN.
|
||
|
|
channel_bindings: The optional :class:`spnego.channel_bindings.GssChannelBindings` for the context.
|
||
|
|
context_req: The :class:`spnego.ContextReq` flags to use when setting up the context.
|
||
|
|
usage: The usage of the context, `initiate` for a client and `accept` for a server.
|
||
|
|
protocol: The protocol to authenticate with, can be `ntlm`, `kerberos`, or `negotiate`. Not all providers
|
||
|
|
support all three protocols as that is handled by :class:`SPNEGOContext`.
|
||
|
|
options: The :class:`spnego.NegotiateOptions` that define pyspnego specific options to control the negotiation.
|
||
|
|
|
||
|
|
Attributes:
|
||
|
|
usage (str): The usage of the context, `initiate` for a client and `accept` for a server.
|
||
|
|
protocol (str): The protocol to set the context up with; `ntlm`, `kerberos`, or `negotiate`.
|
||
|
|
spn (str): The service principal name of the service to connect to.
|
||
|
|
channel_bindings (spnego.channel_bindings.GssChannelBindings): Optional channel bindings to provide with the
|
||
|
|
context.
|
||
|
|
options (NegotiateOptions): The user specified negotiation options.
|
||
|
|
context_req (ContextReq): The context requirements flags as an int value specific to the context provider.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(
|
||
|
|
self,
|
||
|
|
credentials: typing.List[Credential],
|
||
|
|
hostname: typing.Optional[str],
|
||
|
|
service: typing.Optional[str],
|
||
|
|
channel_bindings: typing.Optional[GssChannelBindings],
|
||
|
|
context_req: ContextReq,
|
||
|
|
usage: str,
|
||
|
|
protocol: str,
|
||
|
|
options: NegotiateOptions,
|
||
|
|
) -> None:
|
||
|
|
self.usage = usage.lower()
|
||
|
|
if self.usage not in ["initiate", "accept"]:
|
||
|
|
raise ValueError("Invalid usage '%s', must be initiate or accept" % self.usage)
|
||
|
|
|
||
|
|
self.protocol = protocol.lower()
|
||
|
|
if self.protocol not in ["ntlm", "kerberos", "negotiate", "credssp"]:
|
||
|
|
raise ValueError("Invalid protocol '%s', must be ntlm, kerberos, negotiate, or credssp" % self.protocol)
|
||
|
|
|
||
|
|
if self.protocol not in self.available_protocols(options=options):
|
||
|
|
raise ValueError("Protocol %s is not available" % self.protocol)
|
||
|
|
|
||
|
|
self._hostname = hostname
|
||
|
|
self._service = service
|
||
|
|
self.spn = None
|
||
|
|
if service or hostname:
|
||
|
|
self.spn = to_text("%s/%s" % (service if service else "HOST", hostname or "unspecified"))
|
||
|
|
|
||
|
|
self.channel_bindings = channel_bindings
|
||
|
|
self.options = NegotiateOptions(options)
|
||
|
|
|
||
|
|
self.context_req = context_req # Generic context requirements.
|
||
|
|
self._context_req = 0 # Provider specific context requirements.
|
||
|
|
for generic, provider in self._context_attr_map:
|
||
|
|
if context_req & generic:
|
||
|
|
self._context_req |= provider
|
||
|
|
|
||
|
|
self._context_attr = 0 # Provider specific context attributes, set by self.step().
|
||
|
|
|
||
|
|
# Whether the context is wrapped inside another context - set by NegotiateProxy.
|
||
|
|
self._is_wrapped = False
|
||
|
|
|
||
|
|
if options & NegotiateOptions.wrapping_iov and not self.iov_available():
|
||
|
|
raise FeatureMissingError(NegotiateOptions.wrapping_iov)
|
||
|
|
|
||
|
|
@property
|
||
|
|
def username(self) -> None:
|
||
|
|
warnings.warn("username is deprecated", category=DeprecationWarning)
|
||
|
|
return None
|
||
|
|
|
||
|
|
@property
|
||
|
|
def password(self) -> None:
|
||
|
|
warnings.warn("password is deprecated", category=DeprecationWarning)
|
||
|
|
return None
|
||
|
|
|
||
|
|
@classmethod
|
||
|
|
def available_protocols(cls, options: typing.Optional[NegotiateOptions] = None) -> typing.List[str]:
|
||
|
|
"""A list of protocols that the provider can offer.
|
||
|
|
|
||
|
|
Returns a list of protocols the underlying provider can implement. Currently only kerberos, negotiate, or ntlm
|
||
|
|
is understood. The protocols that are available for each proxy context depend on the OS platform and what
|
||
|
|
libraries are installed. See each proxy's `available_protocols` function for more info.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
options: The context requirements of :class:`NegotiationOptions` that state what the client requires.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
List[str]: The list of protocols that the context can use.
|
||
|
|
"""
|
||
|
|
return ["kerberos", "negotiate", "ntlm"] # pragma: no cover
|
||
|
|
|
||
|
|
@classmethod
|
||
|
|
def iov_available(cls) -> bool:
|
||
|
|
"""Whether the context supports IOV wrapping and unwrapping.
|
||
|
|
|
||
|
|
Will return a bool that states whether the context supports IOV wrapping or unwrapping. The NTLM protocol on
|
||
|
|
Linux does not support IOV and some Linux gssapi implementations do not expose the extension headers for this
|
||
|
|
function. This gives the caller a sane way to determine whether it can use :meth:`wrap_iov` or
|
||
|
|
:meth:`unwrap_iov`.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bool: Whether the context provider supports IOV wrapping and unwrapping (True) or not (False).
|
||
|
|
"""
|
||
|
|
return True # pragma: no cover
|
||
|
|
|
||
|
|
@property
|
||
|
|
@abc.abstractmethod
|
||
|
|
def client_principal(self) -> typing.Optional[str]:
|
||
|
|
"""The principal that was used authenticated by the acceptor.
|
||
|
|
|
||
|
|
The name of the client principal that was used in the authentication context. This is `None` when
|
||
|
|
`usage='initiate'` or the context has not been completed. The format of the principal name is dependent on the
|
||
|
|
protocol and underlying library that was used to complete the authentication.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
Optional[str]: The client principal name.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@property
|
||
|
|
@abc.abstractmethod
|
||
|
|
def complete(self) -> bool:
|
||
|
|
"""Whether the context has completed the authentication process.
|
||
|
|
|
||
|
|
Will return a bool that states whether the authentication process has completed successfully.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bool: The authentication process is complete (True) or not (False).
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@property
|
||
|
|
def context_attr(self) -> ContextReq:
|
||
|
|
"""The context attributes that were negotiated.
|
||
|
|
|
||
|
|
This is the context attributes that were negotiated with the counterpart server. These attributes are only
|
||
|
|
valid once the context is fully established.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
ContextReq: The flags that were negotiated.
|
||
|
|
"""
|
||
|
|
attr = 0
|
||
|
|
for generic, provider in self._context_attr_map:
|
||
|
|
if self._context_attr & provider:
|
||
|
|
attr |= generic
|
||
|
|
|
||
|
|
return ContextReq(attr)
|
||
|
|
|
||
|
|
@property
|
||
|
|
@abc.abstractmethod
|
||
|
|
def negotiated_protocol(self) -> typing.Optional[str]:
|
||
|
|
"""The name of the negotiated protocol.
|
||
|
|
|
||
|
|
Once the authentication process has compeleted this will return the name of the negotiated context that was
|
||
|
|
used. For pure NTLM and Kerberos this will always be `ntlm` or `kerberos` respectively but for SPNEGO this can
|
||
|
|
be either of those two.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
Optional[str]: The protocol that was negotiated, can be `ntlm`, `kerberos`, or `negotiate. Will be `None`
|
||
|
|
for the acceptor until it receives the first token from the initiator. Once the context is establish
|
||
|
|
`negotiate` will change to either `ntlm` or `kerberos` to reflect the protocol that was used by SPNEGO.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@property
|
||
|
|
@abc.abstractmethod
|
||
|
|
def session_key(self) -> bytes:
|
||
|
|
"""The derived session key.
|
||
|
|
|
||
|
|
Once the authentication process is complete, this will return the derived session key. It is recommended to not
|
||
|
|
use this key for your own encryption processes and is only exposed because some libraries use this key in their
|
||
|
|
protocols.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bytes: The derived session key from the authenticated context.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def new_context(self) -> "ContextProxy":
|
||
|
|
"""Creates a new security context.
|
||
|
|
|
||
|
|
Creates a new security context based on the current credential and
|
||
|
|
options of the current context. This is useful when needing to set up a
|
||
|
|
new security context without having to retrieve the credentials again.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
ContextProxy: The new security context.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def query_message_sizes(self) -> SecPkgContextSizes:
|
||
|
|
"""Gets the important structure sizes for message functions.
|
||
|
|
|
||
|
|
Will get the important sizes for the various message functions used by
|
||
|
|
the current authentication context. This must only be called once the
|
||
|
|
context has been authenticated.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
SecPkgContextSizes: The sizes for the current context.
|
||
|
|
|
||
|
|
Raises:
|
||
|
|
NoContextError: The security context is not ready to be queried.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def step(
|
||
|
|
self,
|
||
|
|
in_token: typing.Optional[bytes] = None,
|
||
|
|
*,
|
||
|
|
channel_bindings: typing.Optional[GssChannelBindings] = None,
|
||
|
|
) -> typing.Optional[bytes]:
|
||
|
|
"""Performs a negotiation step.
|
||
|
|
|
||
|
|
This method performs a negotiation step and processes/generates a token. This token should be then sent to the
|
||
|
|
counterpart context to continue the authentication process.
|
||
|
|
|
||
|
|
This should not be called once :meth:`complete` is True as the security context is complete.
|
||
|
|
|
||
|
|
For the initiator this is equivalent to `gss_init_sec_context`_ for GSSAPI and `InitializeSecurityContext`_ for
|
||
|
|
SSPI.
|
||
|
|
|
||
|
|
For the acceptor this is equivalent to `gss_accept_sec_context`_ for GSSAPI and `AcceptSecurityContext`_ for
|
||
|
|
SSPI.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
in_token: The input token to process (or None to process no input token).
|
||
|
|
channel_bindings: Optional channel bindings ot use in this step. Will take priority over channel bindings
|
||
|
|
set in the context if both are specified.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
Optional[bytes]: The output token (or None if no output token is generated.
|
||
|
|
|
||
|
|
.. _gss_init_sec_context:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.19
|
||
|
|
|
||
|
|
.. _InitializeSecurityContext:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-initializesecuritycontextw
|
||
|
|
|
||
|
|
.. _gss_accept_sec_context:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.1
|
||
|
|
|
||
|
|
.. _AcceptSecurityContext:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-acceptsecuritycontext
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def wrap(self, data: bytes, encrypt: bool = True, qop: typing.Optional[int] = None) -> WrapResult:
|
||
|
|
"""Wrap a message, optionally with encryption.
|
||
|
|
|
||
|
|
This wraps a message, signing it and optionally encrypting it. The :meth:`unwrap` will unwrap a message.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_wrap`_ for GSSAPI and `EncryptMessage`_ for SSPI.
|
||
|
|
|
||
|
|
The SSPI function's `EncryptMessage`_ is called with the following buffers::
|
||
|
|
|
||
|
|
SecBufferDesc(SECBUFFER_VERSION, [
|
||
|
|
SecBuffer(SECBUFFER_TOKEN, sizes.cbSecurityTrailer, b""),
|
||
|
|
SecBuffer(SECBUFFER_DATA, len(data), data),
|
||
|
|
SecBuffer(SECBUFFER_PADDING, sizes.cbBlockSize, b""),
|
||
|
|
])
|
||
|
|
|
||
|
|
Args:
|
||
|
|
data: The data to wrap.
|
||
|
|
encrypt: Whether to encrypt the data (True) or just wrap it with a MIC (False).
|
||
|
|
qop: The desired Quality of Protection (or None to use the default).
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
WrapResult: The wrapped result which contains the wrapped message and whether it was encrypted or not.
|
||
|
|
|
||
|
|
.. _gss_wrap:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.33
|
||
|
|
|
||
|
|
.. _EncryptMessage:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/secauthn/encryptmessage--general
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def wrap_iov(
|
||
|
|
self,
|
||
|
|
iov: typing.Iterable[IOV],
|
||
|
|
encrypt: bool = True,
|
||
|
|
qop: typing.Optional[int] = None,
|
||
|
|
) -> IOVWrapResult:
|
||
|
|
"""Wrap/Encrypt an IOV buffer.
|
||
|
|
|
||
|
|
This method wraps/encrypts an IOV buffer. The IOV buffers control how the data is to be processed. Because
|
||
|
|
IOV wrapping is an extension to GSSAPI and not implemented for NTLM on Linux, this method may not always be
|
||
|
|
available to the caller. Check the :meth:`iov_available` property.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_wrap_iov`_ for GSSAPI and `EncryptMessage`_ for SSPI.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
iov: A list of :class:`spnego.iov.IOVBuffer` buffers to wrap.
|
||
|
|
encrypt: Whether to encrypt the message (True) or just wrap it with a MIC (False).
|
||
|
|
qop: The desired Quality of Protection (or None to use the default).
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
IOVWrapResult: The wrapped result which contains the wrapped IOVBuffer bytes and whether it was encrypted
|
||
|
|
or not.
|
||
|
|
|
||
|
|
.. _gss_wrap_iov:
|
||
|
|
http://k5wiki.kerberos.org/wiki/Projects/GSSAPI_DCE
|
||
|
|
|
||
|
|
.. _EncryptMessage:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/secauthn/encryptmessage--general
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def wrap_winrm(self, data: bytes) -> WinRMWrapResult:
|
||
|
|
"""Wrap/Encrypt data for use with WinRM.
|
||
|
|
|
||
|
|
This method wraps/encrypts bytes for use with WinRM message encryption.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
data: The data to wrap.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
WinRMWrapResult: The wrapped result for use with WinRM message encryption.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def unwrap(self, data: bytes) -> UnwrapResult:
|
||
|
|
"""Unwrap a message.
|
||
|
|
|
||
|
|
This unwraps a message created by :meth:`wrap`.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_unwrap`_ for GSSAPI and `DecryptMessage`_ for SSPI.
|
||
|
|
|
||
|
|
The SSPI function's `DecryptMessage`_ is called with the following buffers::
|
||
|
|
|
||
|
|
SecBufferDesc(SECBUFFER_VERSION, [
|
||
|
|
SecBuffer(SECBUFFER_STREAM, len(data), data),
|
||
|
|
SecBuffer(SECBUFFER_DATA, 0, b""),
|
||
|
|
])
|
||
|
|
|
||
|
|
Args:
|
||
|
|
data: The data to unwrap.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
UnwrapResult: The unwrapped message, whether it was encrypted, and the QoP used.
|
||
|
|
|
||
|
|
.. _gss_unwrap:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.31
|
||
|
|
|
||
|
|
.. _DecryptMessage:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/secauthn/decryptmessage--general
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def unwrap_iov(
|
||
|
|
self,
|
||
|
|
iov: typing.Iterable[IOV],
|
||
|
|
) -> IOVUnwrapResult:
|
||
|
|
"""Unwrap/Decrypt an IOV buffer.
|
||
|
|
|
||
|
|
This method unwraps/decrypts an IOV buffer. The IOV buffers control how the data is to be processed. Because
|
||
|
|
IOV wrapping is an extension to GSSAPI and not implemented for NTLM on Linux, this method may not always be
|
||
|
|
available to the caller. Check the :meth:`iov_available` property.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_unwrap_iov`_ for GSSAPI and `DecryptMessage`_ for SSPI.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
iov: A list of :class:`spnego.iov.IOVBuffer` buffers to unwrap.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
IOVUnwrapResult: The unwrapped buffer bytes, whether it was encrypted, and the QoP used.
|
||
|
|
|
||
|
|
.. _gss_unwrap_iov:
|
||
|
|
http://k5wiki.kerberos.org/wiki/Projects/GSSAPI_DCE
|
||
|
|
|
||
|
|
.. _DecryptMessage:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/secauthn/decryptmessage--general
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def unwrap_winrm(self, header: bytes, data: bytes) -> bytes:
|
||
|
|
"""Unwrap/Decrypt a WinRM message.
|
||
|
|
|
||
|
|
This method unwraps/decrypts a WinRM message. It handles the complexities of unwrapping the data and dealing
|
||
|
|
with the various system library calls.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
header: The header portion of the WinRM wrapped result.
|
||
|
|
data: The data portion of the WinRM wrapped result.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bytes: The unwrapped message.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def sign(self, data: bytes, qop: typing.Optional[int] = None) -> bytes:
|
||
|
|
"""Generates a signature/MIC for a message.
|
||
|
|
|
||
|
|
This method generates a MIC for the given data. This is unlike wrap which bundles the MIC and the message
|
||
|
|
together. The :meth:`verify` method can be used to verify a MIC.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_get_mic`_ for GSSAPI and `MakeSignature`_ for SSPI.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
data: The data to generate the MIC for.
|
||
|
|
qop: The desired Quality of Protection (or None to use the default).
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bytes: The MIC for the data requested.
|
||
|
|
|
||
|
|
.. _gss_get_mic:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.15
|
||
|
|
|
||
|
|
.. _MakeSignature:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-makesignature
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
@abc.abstractmethod
|
||
|
|
def verify(self, data: bytes, mic: bytes) -> int:
|
||
|
|
"""Verify the signature/MIC for a message.
|
||
|
|
|
||
|
|
Will verify that the given MIC matches the given data. If the MIC does not match the given data, an exception
|
||
|
|
will be raised. The :meth:`sign` method can be used to sign data.
|
||
|
|
|
||
|
|
This is the equivalent to `gss_verify_mic`_ for GSSAPI and `VerifySignature`_ for SSPI.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
data: The data to verify against the MIC.
|
||
|
|
mic: The MIC to verify against the data.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
int: The QoP (Quality of Protection) used.
|
||
|
|
|
||
|
|
.. _gss_verify_mic:
|
||
|
|
https://tools.ietf.org/html/rfc2744.html#section-5.32
|
||
|
|
|
||
|
|
.. _VerifySignature:
|
||
|
|
https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-verifysignature
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
# Internal properties/functions not for public use.
|
||
|
|
|
||
|
|
@property
|
||
|
|
@abc.abstractmethod
|
||
|
|
def _context_attr_map(self) -> typing.List[typing.Tuple[ContextReq, int]]:
|
||
|
|
"""Map the generic ContextReq into the provider specific flags.
|
||
|
|
|
||
|
|
Will return a list of tuples that give the provider specific flag value for the generic ContextReq that is
|
||
|
|
exposed to end users.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
List[Tuple[ContextReq, int], ...]: A list of tuples where tuple[0] is the ContextReq flag and tuple[1] is
|
||
|
|
the relevant provider specific flag for our common one.
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|
||
|
|
|
||
|
|
def get_extra_info(
|
||
|
|
self,
|
||
|
|
name: str,
|
||
|
|
default: typing.Any = None,
|
||
|
|
) -> typing.Any:
|
||
|
|
"""Return information about the security context.
|
||
|
|
|
||
|
|
Returns extra information about the security context that is not defined
|
||
|
|
as part of the standard :class:`ContextProxy` attributes or properties.
|
||
|
|
By default there is no context specific information and it's up to the
|
||
|
|
sub classes to implement their own.
|
||
|
|
|
||
|
|
These names can be queried for a CredSSP context.
|
||
|
|
|
||
|
|
client_credential:
|
||
|
|
Used on an `acceptor` CredSSP context and contains the delegated
|
||
|
|
credential sent by the client to the server. This is only
|
||
|
|
available once the context is complete otherwise the default
|
||
|
|
value is returned. The types returned can be
|
||
|
|
:class:`TSPasswordCreds`, :class:`TSSmartCardCreds`, or
|
||
|
|
:class:`TSRemoteGuardCreds`.
|
||
|
|
|
||
|
|
sslcontext:
|
||
|
|
The :class:`ssl.SSLContext` instance used for the CredSSP
|
||
|
|
context.
|
||
|
|
|
||
|
|
ssl_object:
|
||
|
|
The :class:`ssl.SSLObject` instance used for the CredSSP
|
||
|
|
context.
|
||
|
|
|
||
|
|
auth_stage - added in 0.5.0:
|
||
|
|
A string representing that sub authentication stage being
|
||
|
|
performed in the CredSSP authentication stepping. The value
|
||
|
|
here is meant to be a human friendly representation and not
|
||
|
|
something to be relied upon.
|
||
|
|
|
||
|
|
protocol_version - added in 0.5.0:
|
||
|
|
The CredSSP protocol version that was negotiated between the
|
||
|
|
initiator and acceptor. This is the minimum version number
|
||
|
|
offered by both parties once the Negotiate authentication stage
|
||
|
|
is complete.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
name: The name/id of the information to retrieve.
|
||
|
|
default: The default value to return if the information is not
|
||
|
|
available on the current context proxy.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
name: The name/id of the information to retrieve.
|
||
|
|
default: The default value to return if the information is not
|
||
|
|
available on the current context proxy.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
The information requested or the default value specified if the
|
||
|
|
information isn't found.
|
||
|
|
"""
|
||
|
|
return default
|
||
|
|
|
||
|
|
@property
|
||
|
|
def _requires_mech_list_mic(self) -> bool:
|
||
|
|
"""Determine if the SPNEGO mechListMIC is required for the sec context.
|
||
|
|
|
||
|
|
When Microsoft hosts deal with NTLM through SPNEGO it always wants the mechListMIC to be present when the NTLM
|
||
|
|
authentication message contains a MIC. This goes against RFC 4178 as a mechListMIC shouldn't be required if
|
||
|
|
NTLM was the preferred mech from the initiator but we can't do anything about that now. Because we exclusively
|
||
|
|
use SSPI on Windows hosts, which does all the work for us, this function only matter for Linux hosts when this
|
||
|
|
library manually creates the SPNEGO token.
|
||
|
|
|
||
|
|
The function performs 2 operations. When called before the NTLM authentication message has been created it
|
||
|
|
tells the gss-ntlmssp mech that it's ok to generate the MIC. When the authentication message has been created
|
||
|
|
it returns a bool stating whether the MIC was present in the auth message and subsequently whether we need to
|
||
|
|
include the mechListMIC in the SPNEGO token.
|
||
|
|
|
||
|
|
See `mech_required_mechlistMIC in MIT KRB5`_ for more information about how MIT KRB5 deals with this.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
bool: Whether the SPNEGO mechListMIC needs to be generated or not.
|
||
|
|
|
||
|
|
.. _mech_requires_mechlistMIC:
|
||
|
|
https://github.com/krb5/krb5/blob/b2fe66fed560ae28917a4acae6f6c0f020156353/src/lib/gssapi/spnego/spnego_mech.c#L493
|
||
|
|
"""
|
||
|
|
return False # pragma: no cover
|
||
|
|
|
||
|
|
def _build_iov_list(
|
||
|
|
self, iov: typing.Iterable[IOV], native_convert: typing.Callable[[IOVBuffer], NativeIOV]
|
||
|
|
) -> typing.List[NativeIOV]:
|
||
|
|
"""Creates a list of IOV buffers for the native provider needed."""
|
||
|
|
provider_iov: typing.List[NativeIOV] = []
|
||
|
|
|
||
|
|
for entry in iov:
|
||
|
|
data: typing.Optional[typing.Union[bytes, int, bool]]
|
||
|
|
if isinstance(entry, tuple):
|
||
|
|
if len(entry) != 2:
|
||
|
|
raise ValueError("IOV entry tuple must contain 2 values, the type and data, see IOVBuffer.")
|
||
|
|
|
||
|
|
if not isinstance(entry[0], int):
|
||
|
|
raise ValueError("IOV entry[0] must specify the BufferType as an int")
|
||
|
|
buffer_type = entry[0]
|
||
|
|
|
||
|
|
if entry[1] is not None and not isinstance(entry[1], (bytes, int, bool)):
|
||
|
|
raise ValueError(
|
||
|
|
"IOV entry[1] must specify the buffer bytes, length of the buffer, or whether "
|
||
|
|
"it is auto allocated."
|
||
|
|
)
|
||
|
|
data = entry[1] if entry[1] is not None else b""
|
||
|
|
|
||
|
|
elif isinstance(entry, int):
|
||
|
|
buffer_type = entry
|
||
|
|
data = None
|
||
|
|
|
||
|
|
elif isinstance(entry, bytes):
|
||
|
|
buffer_type = BufferType.data
|
||
|
|
data = entry
|
||
|
|
|
||
|
|
else:
|
||
|
|
raise ValueError("IOV entry must be a IOVBuffer tuple, int, or bytes")
|
||
|
|
|
||
|
|
iov_buffer = IOVBuffer(type=BufferType(buffer_type), data=data)
|
||
|
|
provider_iov.append(native_convert(iov_buffer))
|
||
|
|
|
||
|
|
return provider_iov
|
||
|
|
|
||
|
|
def _reset_ntlm_crypto_state(self, outgoing: bool = True) -> None:
|
||
|
|
"""Reset the NTLM crypto handles after signing/verifying the SPNEGO mechListMIC.
|
||
|
|
|
||
|
|
`MS-SPNG`_ documents that after signing or verifying the mechListMIC, the RC4 key state needs to be the same
|
||
|
|
for the mechListMIC and for the first message signed/sealed by the application. Because we use SSPI on Windows
|
||
|
|
hosts which does all the work for us this function only matters for Linux hosts.
|
||
|
|
|
||
|
|
Args:
|
||
|
|
outgoing: Whether to reset the outgoing or incoming RC4 key state.
|
||
|
|
|
||
|
|
.. _MS-SPNG:
|
||
|
|
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-spng/b87587b3-9d72-4027-8131-b76b5368115f
|
||
|
|
"""
|
||
|
|
pass # pragma: no cover
|