Debian Codegraph @

src/spnego/_ntlm_raw/security.py

raw
1 # Copyright: (c) 2020, Jordan Borean (@jborean93) <[email protected]>
2 # MIT License (see LICENSE or https://opensource.org/licenses/MIT)
3
4 import struct
5 import typing
6
7 from spnego._ntlm_raw.crypto import RC4Handle, crc32, hmac_md5, rc4
8 from spnego._ntlm_raw.messages import NegotiateFlags
9 from spnego.exceptions import OperationNotAvailableError
10
11
12 def seal(
13 flags: int,
14 handle: RC4Handle,
15 signing_key: bytes,
16 seq_num: int,
17 b_data: bytes,
18 *,
19 to_sign: typing.Optional[bytes] = None,
20 ) -> typing.Tuple[bytes, bytes]:
21 """Create a sealed NTLM message.
22
23 Creates a sealed NTLM message as documented at `NTLM Message Confidentiality`_.
24
25 Args:
26 flags: The negotiated flags between the initiator and acceptor.
27 handle: The RC4 handle for the negotiated context.
28 signing_key: The key used to sign the message.
29 seq_num: The sequence number for the message.
30 b_data: The data/message bytes to seal.
31
32 Returns:
33 Tuple[bytes, bytes]: The sealed message bytes and the message signature.
34
35 .. _NTLM Message Confidentiality:
36 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/115f9c7d-bc30-4262-ae96-254555c14ea6
37 """
38 seal_msg = rc4(handle, b_data)
39 signature = sign(flags, handle, signing_key, seq_num, to_sign if to_sign else b_data)
40 return seal_msg, signature
41
42
43 def sign(
44 flags: int,
45 handle: RC4Handle,
46 signing_key: bytes,
47 seq_num: int,
48 b_data: bytes,
49 ) -> bytes:
50 """Create a NTLM signature.
51
52 Creates a NTLM signature as documented at `NTLM Message Integrity`_ and appends it to the end of the message.
53
54 Args:
55 flags: The negotiated flags between the initiator and acceptor.
56 handle: The RC4 handle for the negotiated context.
57 signing_key: The key used to sign the message.
58 seq_num: The sequence number for the signature.
59 b_data: The data/message bytes to sign.
60
61 Returns:
62 bytes: The data with the signature appended.
63
64 .. _NTLM Message Integrity:
65 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/131b0062-7958-460e-bca5-c7a9f9086652
66 """
67 if flags & NegotiateFlags.sign == 0:
68 if flags & NegotiateFlags.always_sign == 0:
69 raise OperationNotAvailableError(context_msg="Signing without integrity.")
70
71 # This is the behaviour seen with SSPI when signing data with NTLMSSP_NEGOTIATE_ALWAYS_SIGN.
72 return b"\x01" + b"\x00" * 15
73
74 elif flags & NegotiateFlags.extended_session_security:
75 return _mac_with_ess(flags, handle, signing_key, seq_num, b_data)
76
77 else:
78 return _mac_without_ess(handle, seq_num, b_data)
79
80
81 def _mac_without_ess(
82 handle: RC4Handle,
83 seq_num: int,
84 b_data: bytes,
85 ) -> bytes:
86 """NTLM MAC without Extended Session Security
87
88 Generates the NTLM signature when Extended Session Security has not been negotiated. The structure of the signature
89 is documented at `NTLM signature without ESS`_.
90
91 The algorithm as documented by `MAC without ESS`_ is::
92
93 Define MAC(Handle, SigningKey, SeqNum, Message) as
94 Set NTLMSSP_MESSAGE_SIGNATURE.Version to 0x00000001
95 Set NTLMSSP_MESSAGE_SIGNATURE.Checksum to CRC32(Message)
96 Set NTLMSSP_MESSAGE_SIGNATURE.RandomPad RC4(Handle, RandomPad)
97 Set NTLMSSP_MESSAGE_SIGNATURE.Checksum to RC4(Handle, NTLMSSP_MESSAGE_SIGNATURE.Checksum)
98 Set NTLMSSP_MESSAGE_SIGNATURE.SeqNum to RC4(Handle, 0x00000000)
99
100 If (connection oriented)
101 Set NTLMSSP_MESSAGE_SIGNATURE.SeqNum to NTLMSSP_MESSAGE_SIGNATURE.SeqNum XOR SeqNum
102 Set SeqNum to SeqNum + 1
103
104 Else
105 Set NTLMSSP_MESSAGE_SIGNATURE.SeqNum to NTLMSSP_MESSAGE_SIGNATURE.SeqNum XOR (app supplied SeqNum)
106
107 Endif
108
109 Set NTLMSSP_MESSAGE_SIGNATURE.RandomPad to 0
110
111 EndDefine
112
113 Args:
114 handle: The RC4 handle for the negotiated context.
115 seq_num: The sequence number for the signature.
116 b_data: The data/message bytes to sign.
117
118 Returns:
119 bytes: The NTLM signature.
120
121 .. _NTLM signature without ESS:
122 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/83fbd0e7-8ab0-4873-8cbe-795249b46b8a
123
124 .. _MAC without ESS:
125 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/0b1fb6a6-7224-4d5b-af35-fdd45c0791e5
126 """
127 checksum = crc32(b_data)
128 rc4(handle, b"\x00\x00\x00\x00") # NTLMSSP_MESSAGE_SIGNATURE.RandomPad RC4(Handle, RandomPad)
129 checksum = rc4(handle, checksum)
130
131 temp_seq_num = struct.unpack("<I", rc4(handle, b"\x00\x00\x00\x00"))[0]
132 b_seq_num = struct.pack("<I", temp_seq_num ^ seq_num)
133
134 return b"\x01\x00\x00\x00" + b"\x00\x00\x00\x00" + checksum + b_seq_num
135
136
137 def _mac_with_ess(flags: int, handle: RC4Handle, signing_key: bytes, seq_num: int, b_data: bytes) -> bytes:
138 """NTLM MAC with Extended Session Security
139
140 Generates the NTLM signature when Extended Session Security has been negotiated. The structure of the signature is
141 documented at `NTLM signature with ESS`_.
142
143 The algorithm as documented by `MAC with ESS`_ is::
144
145 Define MAC(Handle, SigningKey, SeqNum, Message) as
146 Set NTLMSSP_MESSAGE_SIGNATURE.Version to 0x00000001
147 Set NTLMSSP_MESSAGE_SIGNATURE.Checksum to HMAC_MD5(SigningKey, ConcatenationOf(SeqNum, Message))[0..7]
148 Set NTLMSSP_MESSAGE_SIGNATURE.SeqNum to SeqNum
149 Set SeqNum to SeqNum + 1
150 EndDefine
151
152 # When NegotiateFlags.key_exch
153
154 Define MAC(Handle, SigningKey, SeqNum, Message) as
155 Set NTLMSSP_MESSAGE_SIGNATURE.Version to 0x00000001
156 Set NTLMSSP_MESSAGE_SIGNATURE.Checksum to RC4(Handle,
157 HMAC_MD5(SigningKey, ConcatenationOf(SeqNum, Message))[0..7])
158 Set NTLMSSP_MESSAGE_SIGNATURE.SeqNum to SeqNum
159 Set SeqNum to SeqNum + 1
160 EndDefine
161
162 Args:
163 flags: The negotiated flags between the initiator and acceptor.
164 handle: The RC4 handle for the negotiated context.
165 signing_key: The key used to sign the message.
166 seq_num: The sequence number for the signature.
167 b_data: The data/message bytes to sign.
168
169 Returns:
170 bytes: The NTLM with ESS signature.
171
172 .. _NTLM signature with ESS:
173 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/2c3b4689-d6f1-4dc6-85c9-0bf01ea34d9f
174
175 .. _MAC with ESS:
176 https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/a92716d5-d164-4960-9e15-300f4eef44a8
177 """
178 b_seq_num = struct.pack("<I", seq_num)
179
180 checksum = hmac_md5(signing_key, b_seq_num + b_data)[:8]
181 if flags & NegotiateFlags.key_exch:
182 checksum = handle.update(checksum)
183
184 return b"\x01\x00\x00\x00" + checksum + b_seq_num