mitm.xml 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228
  1. <PAGE>
  2. <INCLUDE file="inc/header.tmpl" />
  3. <VAR match="VAR_SEL_CONTRIBUTE" replace="selected" />
  4. <VAR match="VAR_SEL_CONTRIB_MITM" replace="selected" />
  5. <PARSE file="menu1.xml" />
  6. <PARSE file="menu2-contribute.xml" />
  7. <INCLUDE file="inc/content.tmpl" />
  8. <h1>Observing VPN clients</h1>
  9. <p>Most of the VPN <a href="protocols.html">protocols supported by
  10. OpenConnect</a> are proprietary, undocumented, and in many cases
  11. overly-complex, perhaps intentionally obfuscated.</p>
  12. <p>In order to add support for <a
  13. href="contribute.html#new-protocols">new protocols</a>, and sometimes
  14. even to improve or update support for existing ones, it is often
  15. necessary to observe existing clients and servers in order to
  16. understand how they work.</p>
  17. <h2>Observing TLS/SSL connections</h2>
  18. <p>Modern VPN protocols almost always support a UDP-based transport
  19. for tunneled packets, e.g. DTLS for the Cisco AnyConnect protocol, or
  20. ESP for the GlobalProtect protocol. This is because <a
  21. href="http://sites.inka.de/~W1011/devel/tcp-tcp.html">TCP over TCP is
  22. very suboptimal</a> in terms of performance. However, most VPN
  23. protocols also support TLS/SSL for connection initiation and as a
  24. fallback, due to its universal availability even in highly filtered or
  25. firewalled network environments. <b>It is typically more
  26. straightforward and productive to start out by observing the TLS/SSL
  27. side of a new VPN protocol, and saving the UDP-based transport for
  28. later</b> (See <a
  29. href="http://lists.infradead.org/pipermail/openconnect-devel/2016-October/004015.html">this
  30. discussion thread</a> from the <a href="mail.html">mailing list</a>
  31. during the initial work on the <a
  32. href="globalprotect.html">GlobalProtect protocol</a>.)</p>
  33. <p>The content of a TLS/SSL connection is end-to-end encrypted and
  34. authenticated, and the session keys are normally kept only in memory
  35. by the applications using these connections. Therefore, special
  36. techniques are needed to decrypt traffic and observe the plaintext
  37. bytes-on-the-wire of any TLS-based communications protocol.</p>
  38. <p>There are more-or-less 3 possible techniques for decrypting
  39. TLS-based communications and observing the plaintext. The first two
  40. shown here are quite simply, but not universally usable; the
  41. third is more complex but should be applicable to any TLS-based
  42. VPN protocol.</p>
  43. <h3>(1) Using SSLKEYLOGFILE</h3>
  44. <p>If your VPN client is based on a standard TLS library and does not
  45. disable this mechanism, it is likely the most straightforward way to
  46. decrypt TLS traffic.</p>
  47. <p>Most <a
  48. href="https://en.wikipedia.org/wiki/Comparison_of_TLS_implementations">TLS
  49. libraries</a> (including OpenSSL, GnuTLS, and LibNSS) support an
  50. environment variable called <tt>SSLKEYLOGFILE</tt>, which will cause
  51. applications using those libraries to write "premaster secrets" for
  52. their TLS/DTLS sessions to a file. This makes it straightforward to
  53. automatically decrypt the traffic using the Wireshark network protocol
  54. analyzer. Basically, you should run the VPN client that you're
  55. observing with this environment variable set, run Wireshark on the
  56. same computer, and configure Wireshark to use the resulting log file;
  57. see <a href="https://wiki.wireshark.org/TLS#tls-decryption">Wireshark's
  58. TLS decryption documentation for details.</a></p>
  59. <p>Note that some proprietary VPN clients disable the
  60. <tt>SSLKEYLOGFILE</tt> mechanism to prevent decryption of their
  61. traffic, but many developers overlook this especially in early
  62. releases of their client software.</p>
  63. <h3>(2) Using server's RSA private key</h3>
  64. <p>If you have access to the RSA private key of a VPN <i>server</i>
  65. supporting the protocol you're observing (likely because you
  66. administer such a VPN), and can use RSA key exchange, then you can
  67. provide this RSA private key to Wireshark and automatically decrypt
  68. TLS traffic to and from <i>this server</i> using Wireshark; again, see
  69. <a href="https://wiki.wireshark.org/TLS#tls-decryption">Wireshark's
  70. TLS decryption documentation for details and limitations.</a></p>
  71. <p>This works because the RSA key exchange supported by TLS (re)uses
  72. the server's private key for encryption of the ephemeral session keys,
  73. unlike Diffie-Helman or Elliptic Curve Diffie-Helman exchanges which
  74. do not. (<a href="https://security.stackexchange.com/a/35521">More
  75. detailed explanation on StackExchange.</a>)</p>
  76. <p>This lack of <a href="https://en.wikipedia.org/wiki/Forward_secrecy">forward
  77. secrecy</a> of session keys is indeed why RSA key exchange has been
  78. deprecated in TLS 1.2 and <a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#Key_exchange_or_key_agreement">removed
  79. in TLS 1.3</a>. However, most VPN servers and clients continue to
  80. support TLS 1.2 or older with RSA key exchange for backwards
  81. compatibility, so this is still a viable option for decrypting traffic
  82. as of 2022.</p>
  83. <h3>(3) MITM</h3>
  84. <p>If you cannot use either of the above mechanisms, then you will
  85. need to use the <a
  86. href="https://en.wikipedia.org/wiki/Man-in-the-middle_attack">MITM
  87. technique</a> to decrypt traffic to/from the VPN client you are
  88. observing.</p>
  89. <p>The basic idea is to convince the two peers of the TLS connection
  90. (VPN client and server) that they are communicating directly with each
  91. other via an end-to-end encrypted TLS session, when in fact each of
  92. them is in fact communicating with an intermediary (the
  93. "man-in-the-middle"). The intermediary creates two <i>separate</i>
  94. TLS sessions: one between the real client and the intermediary, and
  95. one between the intermediary and the real server. The intermediary can
  96. inspect and modify traffic before relaying it between the the peers,
  97. who continue to believe that they are communicating directly with each
  98. other.</p>
  99. <p>In order to MITM-capture the traffic from a typical proprietary VPN
  100. client:</p>
  101. <ol>
  102. <li>Use <a href="https://mitmproxy.org">mitmproxy</a>, running on
  103. Linux. (There are other similar tools available, but the rest of
  104. this document will assume you are running <tt>mitmproxy</tt> on
  105. Linux.)</li>
  106. <li>Set up a virtual machine and install the required operating and
  107. VPN client. (It is possible to do this using a physical system as
  108. well, but this will make transparent routing more complex.) We
  109. recommend:
  110. <ul>
  111. <li>Linux host OS with <a href="https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine">KVM/QEMU</a>
  112. as a hypervisor</li>
  113. <li>Guest/VM configured for <a href="https://en.wikibooks.org/wiki/QEMU/Networking#User_mode_networking">user
  114. mode networking</a></li>
  115. <li>Assuming the guest is running Microsoft Windows as its OS, install <a href="https://access.redhat.com/articles/2488201">RedHat's
  116. paravirtualized I/O drivers</a> to improve performance.</li>
  117. </ul></li>
  118. <li><p>Run <tt>mitmproxy</tt> on the host system, and route traffic
  119. from the VM through it <i>transparently</i>, that is without setting
  120. an explicit proxy. (See <a href="#antimitm">below</a>, for why an explicit proxy is unlikely to work.)</p>
  121. <p>With KVM/QEMU and user-mode networking, this
  122. consists of setting the guest system's IPv4 gateway to
  123. <tt>10.0.2.2</tt> and setting up <tt>iptables</tt> rules on the
  124. Linux host to redirect traffic. (Described in more detail in
  125. <a href="https://docs.mitmproxy.org/stable/howto-transparent-vms">mitmproxy's
  126. guide to transparently proxying virtual machines</a>).</p></li>
  127. <li><p><b>Browse to the URL <a
  128. href="https://mitm.it">https://mitm.it</a> on the VM</b>; this is a
  129. special domain intercepted by <tt>mitmproxy</tt> itself.</p><p>The
  130. web page shown will help you verify that (a) the VM's traffic is
  131. really passing through MITMproxy and (b) the VM's operating system
  132. trusts <tt>mitmproxy</tt>'s certificates.</p></li>
  133. <li>Run the VPN client on the VM, and capture and study its traffic
  134. using <tt>mitmproxy</tt> (or <tt>mitmdump</tt>) on the host.</li>
  135. <li><p>The client and/or server may employ various mechanisms to detect
  136. MITM and shut down the MITM'ed connection. <b>Trick,
  137. bludgeon, or confuse the client and server into ignoring this</b>;
  138. see <a href="#antimitm">below</a> for specific examples.</p><p>This usually works by
  139. sending a copy or hash/fingerprint of the server's TLS certificate
  140. as part of the in-band protocol data, and checking for differences
  141. from the certificate exchanged in the TLS handshake. </p></li>
  142. <li>Repeat these steps iteratively to understand how the VPN
  143. client's interaction with the VPN server works.</li>
  144. </ol>
  145. <h3 id="antimitm">Defeating anti-MITM measures</h3>
  146. <p>Many proprietary VPN clients will ignore <i>explicit</i> system/browser
  147. proxy settings and attempt to establish direct connections to VPN servers,
  148. which is why explicit proxy setups often will not work, and transparent
  149. proxying is required.</p>
  150. <p>In cases where your VPN client/server detect MITM'ed connections
  151. and stop communicating (6), it's typically necessary to write a script
  152. which will detect and rewrite in-band protocol data containing the
  153. server's TLS certificate (or a hash/fingerprint of it). This requires
  154. a recent version of <tt>mitmproxy</tt> containing <a
  155. href="https://github.com/mitmproxy/mitmproxy/pull/1935">pull request
  156. #1935</a> which was contributed by OpenConnect developers for this
  157. purpose.</p>
  158. <p>An example of such a script may be useful:
  159. <a href="https://gitlab.com/dlenski/pangp-hacks/-/blob/master/gp_ssl_log.py">gp_ssl_log.py</a>.
  160. This script works with <tt>mitmproxy</tt> or <tt>mitmdump</tt> to modify
  161. traffic to/from with a GlobalProtect server; specifically it <a
  162. href="https://gitlab.com/dlenski/pangp-hacks/-/blob/master/gp_ssl_log.py#L63-68">mangles
  163. the <tt>&lt;root-ca&gt;</tt> XML tag</a> sent by GlobalProtect portal
  164. servers, which GlobalProtect's official client software uses to verify
  165. that certificates of servers it connects to. It can be used with
  166. <tt>mitmdump</tt> as follows:</p>
  167. <pre>
  168. ./mitmdump -vvv --tcp $YOUR_GP_SERVER_IP -s /path/to/gp_ssl_log.py --ssl-version-server all --insecure
  169. </pre>
  170. <h2>Documenting VPN protocols</h2>
  171. <p>Sometimes it's most satisfying and productive to simply start
  172. coding up support for a new protocol or feature in OpenConnect
  173. itself. However, if you don't understand the structure of the
  174. OpenConnect codebase well, this may make it difficult to explain and
  175. discuss the code with more experienced developers.</p>
  176. <p>Often it is very useful to take a step back and explain how the VPN
  177. protocol works in more human-readable terms before implementing it in
  178. OpenConnect's codebase. Preparing a document that intersperses prose
  179. explanations with captured traffic can aid in communication. See
  180. <a href="https://github.com/dlenski/openconnect/blob/master/PAN_GlobalProtect_protocol_doc.md">PAN_GlobalProtect_protocol_doc.md</a>,
  181. (prepared during the implementation of the GlobalProtect protocol in
  182. OpenConnect, and subsequently updated) for a complete example.</p>
  183. <h2>Ask for help</h2>
  184. <p>Ask on the <a href="mail.html">mailing list</a> for help with new
  185. protocol implementations, or show us your code via Merge Requests
  186. on GitLab.</p>
  187. <INCLUDE file="inc/footer.tmpl" />
  188. </PAGE>