Files
API-WINDNAS/env/lib/python3.12/site-packages/smbprotocol/dfs.py

457 lines
15 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)
from __future__ import annotations
import time
from collections import OrderedDict, namedtuple
from typing import Iterator
from smbprotocol.structure import (
BytesField,
EnumField,
FlagField,
IntField,
ListField,
Structure,
TextField,
)
DFSTarget = namedtuple("DFSTarget", ["target_path", "set_boundary"])
"""A TargetEntry element in the TargetList ReferralCache.
Contains the DFS target details for a referral request. This object is defined in [MS-DFSC] under
`ReferralCache TargetList`_.
Attributes:
target_path (str): The NetworkPath value in the referral entry.
set_boundary (bool): Whether the TARGET_SET_BOUNDARY flag was set in the referral entry.
.. _ReferralCache TargetList:
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/0f9ef683-b497-47d0-8c2c-e56e34fde2e3
"""
class DomainEntry:
"""A DomainCache entry.
A processed domain and DC referral request.
Args:
referral: The DFSReferralResponse entry for a domain referral request to cache.
Attributes:
domain_list (List[str]): A list of known domain controller hostnames for the domain.
"""
def __init__(self, referral: DFSReferralEntryV3):
self.domain_list = []
self._referral = referral
self._start_time: float = time.time()
self._domain_hint_idx: int | None = None
@property
def domain_name(self) -> str:
"""The domain DFS path."""
return self._referral.dfs_path
@property
def dc_hint(self) -> str:
"""The last known good domain hostname in domain_list."""
return self.domain_list[self._domain_hint_idx]
@dc_hint.setter
def dc_hint(self, value: str) -> None:
for idx, target in enumerate(self.domain_list):
if target == value:
self._domain_hint_idx = idx
break
else:
raise ValueError("The specific domain hint does not exist in this domain cache entry")
@property
def is_expired(self) -> bool:
"""Whether the hint has expired or not."""
return ((time.time() - self._start_time) - self._referral["time_to_live"].get_value()) >= 0
@property
def is_valid(self) -> bool:
"""Whether the domain entry has had a DC referral response or not."""
return self._domain_hint_idx is not None and not self.is_expired
def process_dc_referral(self, referral: DFSReferralResponse) -> None:
if self._domain_hint_idx is None:
self._domain_hint_idx = 0
for dc_entry in referral["referral_entries"].get_value():
for dc_hostname in dc_entry.network_address:
if dc_hostname not in self.domain_list:
self.domain_list.append(dc_hostname)
class ReferralEntry:
"""A ReferralCache entry.
A parsed referral response that is cached by the client for future connection requests.
Args:
referral: The DFSReferralResponse to cache.
"""
def __init__(self, referral: DFSReferralResponse):
referrals = referral["referral_entries"].get_value()
self._referral_header_flags = referral["referral_header_flags"]
self._referrals: list[DFSReferralEntryV1 | DFSReferralEntryV2 | DFSReferralEntryV3] = referrals
self._start_time: float = time.time()
self._target_hint_idx: int = 0
@property
def dfs_path(self) -> str:
return self._referrals[self._target_hint_idx].dfs_path
@property
def is_root(self) -> bool:
return self._referrals[self._target_hint_idx]["server_type"].has_flag(DFSServerTypes.ROOT_TARGETS)
@property
def is_link(self) -> bool:
return not self.is_root
# @property
# def is_interlink(self) -> bool:
# return False
@property
def is_expired(self) -> bool:
referral = self._referrals[self._target_hint_idx]
return ((time.time() - self._start_time) - referral["time_to_live"].get_value()) >= 0
@property
def target_failback(self) -> bool:
return self._referral_header_flags.has_flag(DFSReferralHeaderFlags.TARGET_FAIL_BACK)
@property
def target_hint(self) -> DFSTarget:
return self.target_list[self._target_hint_idx]
@target_hint.setter
def target_hint(self, value: DFSTarget) -> None:
for idx, target in enumerate(self.target_list):
if target == value:
self._target_hint_idx = idx
break
else:
raise ValueError("The specific target hint does not exist in this referral entry")
@property
def target_list(self) -> list[DFSTarget]:
return [
DFSTarget(
target_path=e.network_address,
set_boundary=e["referral_entry_flags"].has_flag(DFSReferralEntryFlags.TARGET_SET_BOUNDARY),
)
for e in self._referrals
]
def __iter__(self) -> Iterator[DFSTarget]:
"""Iterates through the target_list with a priority being the hinted value."""
yield self.target_list[self._target_hint_idx]
for idx, target in enumerate(self.target_list):
if idx == self._target_hint_idx:
continue
yield target
class DFSReferralRequestFlags:
"""
[MS-DFSC] 2.2.3 REQ_GET_DFS_REFERRAL_EX
RequestFlags
"""
SITE_NAME = 0x00000001
class DFSReferralHeaderFlags:
"""
[MS-DFSC] 2.2.4 RESP_GET_DFS_REFERRAL
ReferralHeaderFlags
"""
REFERRAL_SERVERS = 0x00000001
STORAGE_SERVERS = 0x00000002
TARGET_FAIL_BACK = 0x00000004
class DFSServerTypes:
"""
[MS-DFSC] 2.2.5.1 DFS_REFERRAL_V1
ServerType
"""
NON_ROOT_TARGETS = 0x0000
ROOT_TARGETS = 0x0001
class DFSReferralEntryFlags:
"""
[MS-DFSC] 2.2.5.3 DFS_REFERRAL_V3 & 2.2.5.4 DFS_REFERRAL_V4
ReferralEntryFlags
"""
NAME_LIST_REFERRAL = 0x0002
TARGET_SET_BOUNDARY = 0x0004
class DFSReferralRequest(Structure):
"""
[MS-DFSC] 2.2.2 REQ_GET_DFS_REFERRAL
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/663c9b38-41b8-4faa-b6f6-a4576b4cea62
"""
def __init__(self):
self.fields = OrderedDict(
[
("max_referral_level", IntField(size=2, default=4)),
("request_file_name", TextField(null_terminated=True)),
]
)
super().__init__()
class DFSReferralRequestEx(Structure):
"""
[MS-DFSC] 2.2.3 REQ_GET_DFS_REFERRAL_EX
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/575ad372-46a7-4ed6-80e5-f87768fad9a0
"""
def __init__(self):
self.fields = OrderedDict(
[
("max_referral_level", IntField(size=2, default=4)),
("request_flags", FlagField(size=2, flag_type=DFSReferralRequestFlags)),
(
"request_data_length",
IntField(
size=4,
default=lambda s: 4
+ s["request_file_name_length"].get_value()
+ s["site_name_length"].get_value(),
),
),
(
"request_file_name_length",
IntField(
size=2,
default=lambda s: len(s["request_file_name"]),
),
),
(
"request_file_name",
TextField(
null_terminated=True,
size=lambda s: s["request_file_name_length"].get_value(),
),
),
(
"site_name_length",
IntField(
size=2,
default=lambda s: len(s["site_name"]),
),
),
(
"site_name",
TextField(
null_terminated=True,
size=lambda s: s["site_name_length"].get_value(),
),
),
]
)
super().__init__()
class DFSReferralResponse(Structure):
"""
[MS-DFSC] 2.2.4 RESP_GET_DFS_REFERRAL
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/bd1a7a9d-dfee-4dc6-ba37-bfeb329a7bfa
"""
def __init__(self):
self.fields = OrderedDict(
[
("path_consumed", IntField(size=2)),
("number_of_referrals", IntField(size=2)),
("referral_header_flags", FlagField(size=4, flag_type=DFSReferralHeaderFlags)),
(
"referral_entries",
ListField(
list_count=lambda s: s["number_of_referrals"].get_value(),
unpack_func=lambda s, b: self._create_dfs_referral_entry(b),
),
),
("string_buffer", BytesField()),
]
)
super().__init__()
def _create_dfs_referral_entry(self, data):
results = []
for _ in range(self.fields["number_of_referrals"].get_value()):
b_version = data[:1]
if b_version == b"\x01":
referral_entry = DFSReferralEntryV1()
elif b_version == b"\x02":
referral_entry = DFSReferralEntryV2()
else:
referral_entry = DFSReferralEntryV3()
data = referral_entry.unpack(data)
results.append(referral_entry)
# Now process the string_buffer values. Do it in reverse order as the offset value needs to be calculated based
# on the entry size(s) that come after that entry.
entry_offset = 0
for referral_entry in reversed(results):
entry_offset += referral_entry["size"].get_value()
referral_entry.process_string_buffer(data, entry_offset)
return results
class DFSReferralEntryV1(Structure):
"""
[MS-DFSC] 2.2.5.1 DFS_REFERRAL_V1
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/2f7570f9-cafe-442b-ae9e-3ff119cae7d8
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=1)),
("size", IntField(size=2)),
("server_type", EnumField(size=2, enum_type=DFSServerTypes)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags)),
("share_name", TextField(null_terminated=True)),
]
)
super().__init__()
@property
def network_address(self):
return self["share_name"].get_value()
def process_string_buffer(self, buffer, entry_offset):
# The V1 entry does not use a string buffer so this is a no-op.
pass
class DFSReferralEntryV2(Structure):
"""
[MS-DFSC] 2.2.5.2 DFS_REFERRAL_V2
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/3b6ed482-0ca4-4af1-9fd0-254d137c7af4
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=2)),
("size", IntField(size=2)),
("server_type", FlagField(size=2, flag_type=DFSServerTypes)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags)),
("proximity", IntField(size=4)),
("time_to_live", IntField(size=4)),
("dfs_path_offset", IntField(size=2)),
("dfs_alternate_path_offset", IntField(size=2)),
("network_address_offset", IntField(size=2)),
]
)
self.dfs_path = None
self.dfs_alternate_path = None
self.network_address = None
super().__init__()
def process_string_buffer(self, buffer, entry_offset):
buffer_fields = ["dfs_path", "dfs_alternate_path", "network_address"]
for field_name in buffer_fields:
field_offset = self[f"{field_name}_offset"].get_value()
if field_offset == 0:
continue
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[field_offset - entry_offset :])
setattr(self, field_name, field.get_value())
class DFSReferralEntryV3(Structure):
"""
[MS-DFSC] 2.2.5.3 DFS_REFERRAL_V3
This is also the same as V4 just with the addition of more referral_entry_flags and version_number being 4.
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/50a739cf-8211-4b17-9990-63696d37028d
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=3)),
("size", IntField(size=2)),
("server_type", FlagField(size=2, flag_type=DFSServerTypes, flag_strict=False)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags, flag_strict=False)),
("time_to_live", IntField(size=4)),
# The follow fields depend on the ReferralEntryFlags, the actual field names are when the entry is not a
# NameListReferral.
("dfs_path_offset", IntField(size=2)), # SpecialNameOffset
("dfs_alternate_path_offset", IntField(size=2)), # NumberOfExpandedNames
("network_address_offset", IntField(size=2)), # ExpandedNameOffset
("service_site_guid", BytesField(size=lambda s: s["size"].get_value() - 18)), # Padding
]
)
self.dfs_path = None
self.dfs_alternate_path = None
self.network_address = None
super().__init__()
def process_string_buffer(self, buffer, entry_offset):
is_name_list = self["referral_entry_flags"].has_flag(DFSReferralEntryFlags.NAME_LIST_REFERRAL)
buffer_fields = ["dfs_path", "network_address"]
if not is_name_list:
buffer_fields.insert(1, "dfs_alternate_path")
for field_name in buffer_fields:
field_offset = self[f"{field_name}_offset"].get_value()
if field_offset == 0:
continue
string_offset = field_offset - entry_offset
if is_name_list and field_name == "network_address":
value = []
for _ in range(self["dfs_alternate_path_offset"].get_value()):
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[string_offset:])
value.append(field.get_value())
string_offset += len(field)
else:
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[string_offset:])
value = field.get_value()
setattr(self, field_name, value)