Estructura inicial funcional con documentación en el README.md de la FastAPI
This commit is contained in:
840
env/lib/python3.12/site-packages/spnego/_context.py
vendored
Normal file
840
env/lib/python3.12/site-packages/spnego/_context.py
vendored
Normal file
@@ -0,0 +1,840 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user