ntlm.h 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  1. // Copyright 2017 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. // Based on [MS-NLMP]: NT LAN Manager (NTLM) Authentication Protocol
  5. // Specification version 28.0 [1]. Additional NTLM reference [2].
  6. //
  7. // [1] https://msdn.microsoft.com/en-us/library/cc236621.aspx
  8. // [2] http://davenport.sourceforge.net/ntlm.html
  9. #ifndef NET_NTLM_NTLM_H_
  10. #define NET_NTLM_NTLM_H_
  11. #include <stddef.h>
  12. #include <stdint.h>
  13. #include <memory>
  14. #include <string>
  15. #include <vector>
  16. #include "base/containers/span.h"
  17. #include "base/strings/string_piece.h"
  18. #include "net/base/net_export.h"
  19. #include "net/ntlm/ntlm_constants.h"
  20. namespace net::ntlm {
  21. // Maps the bits in the NTLM Hash into 3 DES keys. The DES keys each have 56
  22. // bits stored in the 7 most significant bits of 8 bytes. The least
  23. // significant bit is undefined and will subsequently be set with odd parity
  24. // prior to use.
  25. NET_EXPORT_PRIVATE void Create3DesKeysFromNtlmHash(
  26. base::span<const uint8_t, kNtlmHashLen> ntlm_hash,
  27. base::span<uint8_t, 24> keys);
  28. // Generates the NTLMv1 Hash and writes the |kNtlmHashLen| byte result to
  29. // |hash|. Defined by NTOWFv1() in [MS-NLMP] Section 3.3.1.
  30. NET_EXPORT_PRIVATE void GenerateNtlmHashV1(
  31. const std::u16string& password,
  32. base::span<uint8_t, kNtlmHashLen> hash);
  33. // Generates the |kResponseLenV1| byte NTLMv1 response field according to the
  34. // DESL(K, V) function in [MS-NLMP] Section 6.
  35. NET_EXPORT_PRIVATE void GenerateResponseDesl(
  36. base::span<const uint8_t, kNtlmHashLen> hash,
  37. base::span<const uint8_t, kChallengeLen> challenge,
  38. base::span<uint8_t, kResponseLenV1> response);
  39. // Generates the NTLM Response field for NTLMv1 without extended session
  40. // security. Defined by ComputeResponse() in [MS-NLMP] Section 3.3.1 for the
  41. // case where NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY is not set.
  42. NET_EXPORT_PRIVATE void GenerateNtlmResponseV1(
  43. const std::u16string& password,
  44. base::span<const uint8_t, kChallengeLen> server_challenge,
  45. base::span<uint8_t, kResponseLenV1> ntlm_response);
  46. // Generates both the LM Response and NTLM Response fields for NTLMv1 based
  47. // on the users password and the servers challenge. Both the LM and NTLM
  48. // Response are the result of |GenerateNtlmResponseV1|.
  49. //
  50. // NOTE: This should not be used. The default flags always include session
  51. // security. Session security can however be disabled in NTLMv1 by omitting
  52. // NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY from the flag set used to
  53. // initialize |NtlmClient|.
  54. //
  55. // The default flags include this flag and the client will not be
  56. // downgraded by the server.
  57. NET_EXPORT_PRIVATE void GenerateResponsesV1(
  58. const std::u16string& password,
  59. base::span<const uint8_t, kChallengeLen> server_challenge,
  60. base::span<uint8_t, kResponseLenV1> lm_response,
  61. base::span<uint8_t, kResponseLenV1> ntlm_response);
  62. // The LM Response in V1 with extended session security is 8 bytes of the
  63. // |client_challenge| then 16 bytes of zero. This is the value
  64. // LmChallengeResponse in ComputeResponse() when
  65. // NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY is set. See [MS-NLMP] Section
  66. // 3.3.1.
  67. NET_EXPORT_PRIVATE void GenerateLMResponseV1WithSessionSecurity(
  68. base::span<const uint8_t, kChallengeLen> client_challenge,
  69. base::span<uint8_t, kResponseLenV1> lm_response);
  70. // The |session_hash| is MD5(CONCAT(server_challenge, client_challenge)).
  71. // It is used instead of just |server_challenge| in NTLMv1 when
  72. // NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY is set. See [MS-NLMP] Section
  73. // 3.3.1.
  74. NET_EXPORT_PRIVATE void GenerateSessionHashV1WithSessionSecurity(
  75. base::span<const uint8_t, kChallengeLen> server_challenge,
  76. base::span<const uint8_t, kChallengeLen> client_challenge,
  77. base::span<uint8_t, kNtlmHashLen> session_hash);
  78. // Generates the NTLM Response for NTLMv1 with session security.
  79. // Defined by ComputeResponse() in [MS-NLMP] Section 3.3.1 for the
  80. // case where NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY is set.
  81. NET_EXPORT_PRIVATE void GenerateNtlmResponseV1WithSessionSecurity(
  82. const std::u16string& password,
  83. base::span<const uint8_t, kChallengeLen> server_challenge,
  84. base::span<const uint8_t, kChallengeLen> client_challenge,
  85. base::span<uint8_t, kResponseLenV1> ntlm_response);
  86. // Generates the responses for V1 with extended session security.
  87. // This is also known as NTLM2 (which is not the same as NTLMv2).
  88. // |lm_response| is the result of |GenerateLMResponseV1WithSessionSecurity| and
  89. // |ntlm_response| is the result of |GenerateNtlmResponseV1WithSessionSecurity|.
  90. // See [MS-NLMP] Section 3.3.1.
  91. NET_EXPORT_PRIVATE void GenerateResponsesV1WithSessionSecurity(
  92. const std::u16string& password,
  93. base::span<const uint8_t, kChallengeLen> server_challenge,
  94. base::span<const uint8_t, kChallengeLen> client_challenge,
  95. base::span<uint8_t, kResponseLenV1> lm_response,
  96. base::span<uint8_t, kResponseLenV1> ntlm_response);
  97. // Generates the NTLMv2 Hash and writes it into |v2_hash|.
  98. NET_EXPORT_PRIVATE void GenerateNtlmHashV2(
  99. const std::u16string& domain,
  100. const std::u16string& username,
  101. const std::u16string& password,
  102. base::span<uint8_t, kNtlmHashLen> v2_hash);
  103. // In this implementation the Proof Input is the first 28 bytes of what
  104. // [MS-NLMP] section 3.3.2 calls "temp". "temp" is part of the input to
  105. // generate the NTLMv2 proof. "temp" is composed of a fixed 28 byte prefix
  106. // (the Proof Input), then the variable length updated target info that is
  107. // sent in the authenticate message, then followed by 4 zero bytes. See
  108. // [MS-NLMP] Section 2.2.2.7.
  109. //
  110. // |timestamp| contains a 64 bit Windows timestamp defined as the number of
  111. // 100 nanosecond ticks since midnight Jan 01, 1601 (UTC).
  112. //
  113. // The format of the returned |proof_input| is;
  114. //
  115. // [0-1] - 0x0101 (Version)
  116. // [2-7] - 0x000000000000 (Reserved - all zero)
  117. // [8-15] - |timestamp| (Timestamp)
  118. // [16-23] - |client_challenge| (Client challenge)
  119. // [24-27] - 0x00000000 (Reserved - all zero)
  120. NET_EXPORT_PRIVATE std::vector<uint8_t> GenerateProofInputV2(
  121. uint64_t timestamp,
  122. base::span<const uint8_t, kChallengeLen> client_challenge);
  123. // The NTLMv2 Proof is part of the NTLMv2 Response. See NTProofStr in [MS-NLMP]
  124. // Section 3.3.2.
  125. //
  126. // The NTLMv2 Proof is defined as;
  127. // v2_proof = HMAC_MD5(
  128. // v2_hash,
  129. // CONCAT(server_challenge, v2_input, target_info, 0x00000000))
  130. NET_EXPORT_PRIVATE void GenerateNtlmProofV2(
  131. base::span<const uint8_t, kNtlmHashLen> v2_hash,
  132. base::span<const uint8_t, kChallengeLen> server_challenge,
  133. base::span<const uint8_t, kProofInputLenV2> v2_input,
  134. base::span<const uint8_t> target_info,
  135. base::span<uint8_t, kNtlmProofLenV2> v2_proof);
  136. // The session base key is used to generate the Message Integrity Check (MIC).
  137. // See [MS-NLMP] Section 3.3.2.
  138. //
  139. // It is defined as;
  140. // session_key = HMAC_MD5(v2_hash, v2_proof)
  141. NET_EXPORT_PRIVATE void GenerateSessionBaseKeyV2(
  142. base::span<const uint8_t, kNtlmHashLen> v2_hash,
  143. base::span<const uint8_t, kNtlmProofLenV2> v2_proof,
  144. base::span<uint8_t, kSessionKeyLenV2> session_key);
  145. // The channel bindings hash is an MD5 hash of a data structure containing
  146. // a hash of the server's certificate.
  147. //
  148. // The |channel_bindings| string is supplied out of band (usually from a web
  149. // browser) and is a (21+sizeof(hash)) byte ASCII string, where 'hash' is
  150. // usually a SHA-256 of the servers certificate, but may be another hash
  151. // algorithm. The format as defined by RFC 5929 Section 4 is shown below;
  152. //
  153. // [0-20] - "tls-server-end-point:" (Literal string)
  154. // [21-(20+sizeof(hash)] - HASH(server_certificate) (Certificate hash)
  155. //
  156. // The |channel_bindings| string is then combined into a data structure called
  157. // gss_channel_bindings_struct (on Windows SEC_CHANNEL_BINDINGS) and MD5 hashed
  158. // according to the rules in RFC 4121 Section 4.1.1.2. When simplified this
  159. // results in the input to the hash (aka "ClientChannelBindingsUnhashed")
  160. // being defined as follows;
  161. //
  162. // [0-15] - 16 zero bytes (Collapsed fields)
  163. // [16-19] - |strlen(channel_bindings)| (Length=0x00000035)
  164. // [20-72] - |channel_bindings| (Channel bindings)
  165. //
  166. // See also RFC 5056 and [MS-NLMP] Section 3.1.5.1.2.
  167. //
  168. // The channel bindings hash is then defined as;
  169. // channel_bindings_hash = MD5(ClientChannelBindingsUnhashed)
  170. NET_EXPORT_PRIVATE void GenerateChannelBindingHashV2(
  171. const std::string& channel_bindings,
  172. base::span<uint8_t, kNtlmHashLen> channel_bindings_hash);
  173. // The Message Integrity Check (MIC) is a hash calculated over all three
  174. // messages in the NTLM protocol. The MIC field in the authenticate message
  175. // is set to all zeros when calculating the hash. See [MS-NLMP] Section
  176. // 3.1.5.1.2.
  177. //
  178. // In this implementation NTLMSSP_NEGOTIATE_KEY_EXCH never negotiated and
  179. // the MIC for this case is defined as below. If NTLMSSP_NEGOTIATE_KEY_EXCH
  180. // was negotiated, an alternate key is used. See [MS-NLMP] SEction 3.1.5.1.2
  181. // for additional details.
  182. //
  183. // mic = HMAC_MD5(
  184. // session_base_key,
  185. // CONCAT(negotiate_msg, challenge_msg, authenticate_msg))
  186. //
  187. // |session_key| must contain |kSessionKeyLenV2| bytes.
  188. // |mic| must contain |kMicLenV2| bytes.
  189. NET_EXPORT_PRIVATE void GenerateMicV2(
  190. base::span<const uint8_t, kSessionKeyLenV2> session_key,
  191. base::span<const uint8_t> negotiate_msg,
  192. base::span<const uint8_t> challenge_msg,
  193. base::span<const uint8_t> authenticate_msg,
  194. base::span<uint8_t, kMicLenV2> mic);
  195. // Updates the target info sent by the server, and generates the clients
  196. // response target info.
  197. NET_EXPORT_PRIVATE std::vector<uint8_t> GenerateUpdatedTargetInfo(
  198. bool is_mic_enabled,
  199. bool is_epa_enabled,
  200. const std::string& channel_bindings,
  201. const std::string& spn,
  202. const std::vector<AvPair>& av_pairs,
  203. uint64_t* server_timestamp);
  204. } // namespace net::ntlm
  205. #endif // NET_NTLM_NTLM_H_