Debian Codegraph @

src/spnego/_negotiate.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 base64
5 import logging
6 import struct
7 import typing
8
9 import spnego
10 from spnego._context import (
11 IOV,
12 ContextProxy,
13 ContextReq,
14 GSSMech,
15 IOVUnwrapResult,
16 IOVWrapResult,
17 SecPkgContextSizes,
18 UnwrapResult,
19 WinRMWrapResult,
20 WrapResult,
21 )
22 from spnego._credential import Credential, unify_credentials
23 from spnego._gss import GSSAPIProxy
24 from spnego._spnego import (
25 NegState,
26 NegTokenInit,
27 NegTokenResp,
28 pack_mech_type_list,
29 unpack_token,
30 )
31 from spnego._sspi import SSPIProxy
32 from spnego.channel_bindings import GssChannelBindings
33 from spnego.exceptions import (
34 BadMechanismError,
35 InvalidTokenError,
36 NegotiateOptions,
37 NoContextError,
38 )
39
40 log = logging.getLogger(__name__)
41
42
43 class NegotiateProxy(ContextProxy):
44 """A context wrapper for a Python managed SPNEGO context.
45
46 This is a context that can be used on Linux to generate SPNEGO tokens based on the raw Kerberos or NTLM tokens
47 generated by gssapi or our Python NTLM provider This is used as a fallback if gssapi is not available or cannot
48 generate SPNEGO tokens.
49 """
50
51 def __init__(
52 self,
53 username: typing.Optional[typing.Union[str, Credential, typing.List[Credential]]] = None,
54 password: typing.Optional[str] = None,
55 hostname: typing.Optional[str] = None,
56 service: typing.Optional[str] = None,
57 channel_bindings: typing.Optional[GssChannelBindings] = None,
58 context_req: ContextReq = ContextReq.default,
59 usage: str = "initiate",
60 protocol: str = "negotiate",
61 options: NegotiateOptions = NegotiateOptions.none,
62 **kwargs: typing.Any,
63 ) -> None:
64 credentials = unify_credentials(username, password)
65 super(NegotiateProxy, self).__init__(
66 credentials, hostname, service, channel_bindings, context_req, usage, protocol, options
67 )
68
69 self._credentials = credentials
70 self._complete = False
71 self._available_contexts: typing.Optional[typing.Dict[GSSMech, ContextProxy]] = kwargs.get(
72 "_negotiate_contexts", None
73 )
74 self._context_list: typing.Dict[GSSMech, typing.Tuple[ContextProxy, typing.Optional[bytes]]] = {}
75 self.__chosen_mech: typing.Optional[GSSMech] = None
76 self._mech_list: typing.List[str] = []
77
78 self._init_sent = False
79 self._mech_sent = False
80 self._mic_sent = False
81 self._mic_recv = False
82 # DCE will always send a MIC token, even for Kerberos.
83 self._mic_required = bool(self.context_req & ContextReq.dce_style)
84
85 @classmethod
86 def available_protocols(cls, options: typing.Optional[NegotiateOptions] = None) -> typing.List[str]:
87 # We always support Negotiate and NTLM as we have our builtin NTLM backend and only support kerberos if gssapi
88 # is present.
89 protocols = ["ntlm", "negotiate"]
90
91 # Make sure we add Kerberos first as the order is important.
92 if "kerberos" in GSSAPIProxy.available_protocols(
93 options=options
94 ) or "kerberos" in SSPIProxy.available_protocols(options=options):
95 protocols.insert(0, "kerberos")
96
97 return protocols
98
99 @classmethod
100 def iov_available(cls) -> bool:
101 # If SSPI is available then IOV is available, otherwise it's dependent on whether GSSAPI exposes the functions.
102 if SSPIProxy.available_protocols() == []:
103 return GSSAPIProxy.iov_available()
104 else:
105 return True
106
107 @property
108 def client_principal(self) -> typing.Optional[str]:
109 return self._context.client_principal if self._context_list else None
110
111 @property
112 def complete(self) -> bool:
113 return self._complete
114
115 @property
116 def context_attr(self) -> ContextReq:
117 return self._context.context_attr if self._context_list else ContextReq.none
118
119 @property
120 def negotiated_protocol(self) -> typing.Optional[str]:
121 return self._context.negotiated_protocol if self._context_list else None
122
123 @property
124 def session_key(self) -> bytes:
125 return self._context.session_key if self._context_list else b""
126
127 def new_context(self) -> "NegotiateProxy":
128 return NegotiateProxy(
129 hostname=self._hostname,
130 service=self._service,
131 channel_bindings=self.channel_bindings,
132 context_req=self.context_req,
133 usage=self.usage,
134 protocol=self.protocol,
135 options=self.options,
136 _negotiate_contexts={m: c[0].new_context() for m, c in self._context_list.items()},
137 )
138
139 def step(
140 self,
141 in_token: typing.Optional[bytes] = None,
142 *,
143 channel_bindings: typing.Optional[GssChannelBindings] = None,
144 ) -> typing.Optional[bytes]:
145 log.debug("SPNEGO step input: %s", base64.b64encode(in_token or b"").decode())
146
147 # Step 1. Process SPNEGO mechs.
148 mech_token_in, mech_list_mic, is_spnego = self._step_spnego_input(
149 in_token=in_token,
150 channel_bindings=channel_bindings,
151 )
152
153 mech_token_out = None
154 if mech_token_in or self.usage == "initiate":
155 # Step 2. Process the inner context tokens.
156 mech_token_out = self._step_spnego_token(in_token=mech_token_in, channel_bindings=channel_bindings)
157
158 out_token: typing.Optional[bytes] = None
159 if is_spnego:
160 # Step 3. Process / generate the mechListMIC.
161 out_mic = self._step_spnego_mic(in_mic=mech_list_mic)
162
163 # Step 4. Generate the output SPNEGO token.
164 out_token = self._step_spnego_output(out_token=mech_token_out, out_mic=out_mic)
165
166 else:
167 out_token = mech_token_out
168 self._complete = self._context.complete
169
170 if self.complete:
171 # Remove the leftover contexts if there are still others remaining.
172 self._context_list = {self._chosen_mech: (self._context, None)}
173
174 log.debug("SPNEGO step output: %s" % base64.b64encode(out_token or b"").decode())
175
176 return out_token
177
178 def _step_spnego_input(
179 self,
180 in_token: typing.Optional[bytes] = None,
181 channel_bindings: typing.Optional[GssChannelBindings] = None,
182 ) -> typing.Tuple[typing.Optional[bytes], typing.Optional[bytes], bool]:
183 mech_list_mic = None
184 token = None
185 is_spnego = True
186
187 if in_token:
188 try:
189 in_token = unpack_token(in_token)
190 except struct.error as e:
191 raise InvalidTokenError(base_error=e, context_msg=f"Failed to unpack input token {e!s}")
192
193 if isinstance(in_token, NegTokenInit):
194 mech_list_mic = in_token.mech_list_mic
195 token = in_token.mech_token
196
197 # This is the first token of the exchange, we should build our context list based on the mechs the
198 # opposite end supports.
199 mech_list = self._rebuild_context_list(
200 mech_types=in_token.mech_types,
201 channel_bindings=channel_bindings,
202 )
203
204 if self.usage == "initiate":
205 # If initiate processes a NegTokenInit2 token that's just used as a hint, use the actually
206 # supported mechs as the true mech list.
207 self._mech_list = mech_list
208
209 else:
210 # If accept processes a NegTokenInit token we treat that as an actual init is sent so it does not
211 # send it's own and uses the initiate mech list as the true mech list.
212 self._init_sent = True
213 self._mech_list = in_token.mech_types
214
215 # If the preferred initiator token does not match the preferred acceptor token then the acceptor
216 # must send the request-mic negState.
217 preferred_mech = self._preferred_mech_list()[0]
218 if preferred_mech.value != in_token.mech_types[0]:
219 self._mic_required = True
220
221 elif isinstance(in_token, NegTokenResp):
222 mech_list_mic = in_token.mech_list_mic
223 token = in_token.response_token
224
225 # https://github.com/jborean93/smbprotocol/issues/137
226 # Some really old SPNEGO implementations have mechListMIC with the same value as responseToken. This is
227 # a bug but needs to be handled by blanking out the mechListMIC.
228 if token and mech_list_mic == token:
229 mech_list_mic = None
230
231 # If we have received the supported_mech then we don't need to send our own.
232 if in_token.supported_mech:
233 self.__chosen_mech = GSSMech.from_oid(in_token.supported_mech)
234 self._mech_sent = True
235
236 # Raise exception if we are rejected and have no error info (mechToken) that will give us more info.
237 if in_token.neg_state == NegState.reject and not token:
238 raise InvalidTokenError(context_msg="Received SPNEGO rejection with no token error message")
239
240 if in_token.neg_state == NegState.request_mic:
241 self._mic_required = True
242 elif in_token.neg_state == NegState.accept_complete:
243 self._complete = True
244
245 else:
246 # This usually indicates the token is a raw NTLM or Kerberos token, return as is.
247 is_spnego = False
248 token = in_token
249
250 self.__chosen_mech = GSSMech.ntlm if token and token.startswith(b"NTLMSSP\x00") else GSSMech.kerberos
251
252 if not self._context_list:
253 self._rebuild_context_list(
254 mech_types=[self.__chosen_mech.value],
255 channel_bindings=channel_bindings,
256 )
257
258 else:
259 self._mech_list = self._rebuild_context_list(
260 channel_bindings=channel_bindings,
261 )
262
263 return token, mech_list_mic, is_spnego
264
265 def _step_spnego_token(
266 self,
267 in_token: typing.Optional[bytes] = None,
268 *,
269 channel_bindings: typing.Optional[GssChannelBindings] = None,
270 ) -> typing.Optional[bytes]:
271 chosen_mech = self._chosen_mech
272 context, generated_token = self._context_list[chosen_mech]
273
274 out_token: typing.Optional[bytes] = None
275 if not context.complete:
276 # When usage == 'initiate', the context_list may contain a pre-cached token which we use instead.
277
278 if generated_token:
279 out_token = generated_token
280 self._context_list[chosen_mech] = (context, None) # Clear the value as it's no longer required.
281
282 else:
283 out_token = context.step(in_token=in_token, channel_bindings=channel_bindings)
284
285 # NTLM has a special case where we need to tell it it's ok to generate the MIC and also determine if
286 # it actually did set the MIC as that controls the mechListMIC for the SPNEGO token.
287 if self._requires_mech_list_mic:
288 self._mic_required = True
289
290 return out_token
291
292 def _step_spnego_mic(self, in_mic: typing.Optional[bytes] = None) -> typing.Optional[bytes]:
293 if in_mic:
294 self.verify(pack_mech_type_list(self._mech_list), in_mic)
295 self._reset_ntlm_crypto_state(outgoing=False)
296
297 self._mic_required = True # If we received a mechListMIC we need to send one back.
298 self._mic_recv = True
299
300 if self._mic_sent:
301 self._complete = True
302
303 if self._context.complete and self._mic_required and not self._mic_sent:
304 out_mic = self.sign(pack_mech_type_list(self._mech_list))
305 self._reset_ntlm_crypto_state()
306
307 self._mic_sent = True
308
309 return out_mic
310
311 return None
312
313 def _step_spnego_output(
314 self,
315 out_token: typing.Optional[bytes] = None,
316 out_mic: typing.Optional[bytes] = None,
317 ) -> typing.Optional[bytes]:
318 final_token: typing.Optional[bytes] = None
319
320 if not self._init_sent:
321 self._init_sent = True
322
323 init_kwargs: typing.Dict[str, typing.Any] = {
324 "mech_token": out_token,
325 "mech_list_mic": out_mic,
326 }
327 if self.usage == "accept":
328 init_kwargs["hint_name"] = b"not_defined_in_RFC4178@please_ignore"
329
330 final_token = NegTokenInit(self._mech_list, **init_kwargs).pack()
331
332 elif not self.complete:
333 state = NegState.accept_incomplete
334
335 # As per RFC 4178 - 4.2.2: supportedMech should only be present in the first reply from the target.
336 # Also 'negState: request-mic' MUST only be in the first reply from the target if it is needed.
337 # https://tools.ietf.org/html/rfc4178#section-4.2.2
338 supported_mech = None
339 if not self._mech_sent:
340 supported_mech = self._chosen_mech.value
341 if self._mic_required:
342 state = NegState.request_mic
343
344 self._mech_sent = True
345
346 if self._context.complete and (not self._mic_required or (self._mic_sent and self._mic_recv)):
347 state = NegState.accept_complete
348 self._complete = True
349
350 final_token = NegTokenResp(
351 neg_state=state, supported_mech=supported_mech, response_token=out_token, mech_list_mic=out_mic
352 ).pack()
353
354 return final_token
355
356 def query_message_sizes(self) -> SecPkgContextSizes:
357 if not self.complete:
358 raise NoContextError(context_msg="Cannot get message sizes until context has been established")
359
360 return self._context.query_message_sizes()
361
362 def wrap(self, data: bytes, encrypt: bool = True, qop: typing.Optional[int] = None) -> WrapResult:
363 return self._context.wrap(data, encrypt=encrypt, qop=qop)
364
365 def wrap_iov(
366 self,
367 iov: typing.Iterable[IOV],
368 encrypt: bool = True,
369 qop: typing.Optional[int] = None,
370 ) -> IOVWrapResult:
371 return self._context.wrap_iov(iov, encrypt=encrypt, qop=qop)
372
373 def wrap_winrm(self, data: bytes) -> WinRMWrapResult:
374 return self._context.wrap_winrm(data)
375
376 def unwrap(self, data: bytes) -> UnwrapResult:
377 return self._context.unwrap(data)
378
379 def unwrap_iov(
380 self,
381 iov: typing.Iterable[IOV],
382 ) -> IOVUnwrapResult:
383 return self._context.unwrap_iov(iov)
384
385 def unwrap_winrm(self, header: bytes, data: bytes) -> bytes:
386 return self._context.unwrap_winrm(header, data)
387
388 def sign(self, data: bytes, qop: typing.Optional[int] = None) -> bytes:
389 return self._context.sign(data, qop=qop)
390
391 def verify(self, data: bytes, mic: bytes) -> int:
392 return self._context.verify(data, mic)
393
394 @property
395 def _context(self) -> ContextProxy:
396 return self._context_list[self._chosen_mech][0]
397
398 @property
399 def _chosen_mech(self) -> GSSMech:
400 if self.__chosen_mech:
401 return self.__chosen_mech
402
403 return next(iter(self._context_list))
404
405 @property
406 def _context_attr_map(self) -> typing.List[typing.Tuple[ContextReq, int]]:
407 return [] # SPNEGO layer uses the generic commands, the underlying context has it's own specific map.
408
409 @property
410 def _requires_mech_list_mic(self) -> bool:
411 return self._context._requires_mech_list_mic
412
413 def _preferred_mech_list(self) -> typing.List[GSSMech]:
414 """Get a list of mechs that can be used in priority order (highest to lowest)."""
415 available_protocols = [p for p in self.available_protocols(self.options) if p != "negotiate"]
416 return [getattr(GSSMech, p) for p in available_protocols]
417
418 def _rebuild_context_list(
419 self,
420 mech_types: typing.Optional[typing.List[str]] = None,
421 channel_bindings: typing.Optional[GssChannelBindings] = None,
422 ) -> typing.List[str]:
423 """Builds a new context list that are available to the client."""
424 available_contexts = self._available_contexts or {}
425 last_err = None
426
427 if not available_contexts:
428 context_kwargs: typing.Dict[str, typing.Any] = {
429 "hostname": self._hostname,
430 "service": self._service,
431 "channel_bindings": self.channel_bindings,
432 "context_req": self.context_req,
433 }
434 all_protocols = self._preferred_mech_list()
435
436 for mech in all_protocols:
437 if mech_types and mech.value not in mech_types:
438 continue
439
440 protocol = mech.name
441 try:
442 log.debug(f"Attempting to create {protocol} context when building SPNEGO mech list")
443
444 # Cannot use SSPI's NTLM as we need to reset the crypto state which SSPI does not expose.
445 options = self.options & ~NegotiateOptions.use_negotiate
446 if protocol == "ntlm" and "ntlm" in SSPIProxy.available_protocols(options=options):
447 options |= NegotiateOptions.use_ntlm
448
449 if self.usage == "accept":
450 context = spnego.server(protocol=protocol, options=options, **context_kwargs)
451 else:
452 context = spnego.client(self._credentials, protocol=protocol, options=options, **context_kwargs)
453
454 context._is_wrapped = True
455 available_contexts[mech] = context
456 except Exception as e:
457 last_err = e
458 log.debug("Failed to create context for SPNEGO protocol %s: %s", protocol, str(e))
459 continue
460
461 self._context_list = {}
462 mech_list = []
463 for mech, context in available_contexts.items():
464 try:
465 first_token = context.step(channel_bindings=channel_bindings) if self.usage == "initiate" else None
466 except Exception as e:
467 last_err = e
468 log.debug("Failed to create first token for SPNEGO protocol %s: %s", mech.name, str(e))
469 continue
470
471 self._context_list[mech] = (context, first_token)
472 mech_list.append(mech.value)
473
474 if not mech_list:
475 raise BadMechanismError(context_msg="Unable to negotiate common mechanism", base_error=last_err)
476
477 return mech_list
478
479 def _reset_ntlm_crypto_state(self, outgoing: bool = True) -> None:
480 self._context._reset_ntlm_crypto_state(outgoing=outgoing)