Files
API-WINDNAS/env/lib/python3.12/site-packages/spnego/_context.py

841 lines
34 KiB
Python
Raw Normal View History

# 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