From a1a80cb63b129e37843c5569603d6327e84c85d5 Mon Sep 17 00:00:00 2001
From: Tim Perry <pimterry@gmail.com>
Date: Fri, 2 Feb 2024 17:56:25 +0100
Subject: [PATCH] Update the comments documenting our new iOS TLS override hook

---
 config.js               | 11 +++++++++++
 ios/ios-tls-override.js | 31 ++++++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/config.js b/config.js
index b9d0c66..6b48343 100644
--- a/config.js
+++ b/config.js
@@ -87,6 +87,12 @@ for (let i = 0; i < BASE64_CHARS.length; i++) {
     BASE64_LOOKUP[BASE64_CHARS.charCodeAt(i)] = i;
 }
 
+
+/**
+ * Take a base64 string, and return the raw bytes
+ * @param {string} input
+ * @returns Uint8Array
+ */
 function decodeBase64(input) {
     // Calculate the length of the output buffer based on padding:
     let outputLength = Math.floor((input.length * 3) / 4);
@@ -115,6 +121,11 @@ function decodeBase64(input) {
     return output;
 }
 
+/**
+ * Take a single-certificate PEM string, and return the raw DER bytes
+ * @param {string} input
+ * @returns Uint8Array
+ */
 function pemToDer(input) {
     const pemLines = input.split('\n');
     if (
diff --git a/ios/ios-tls-override.js b/ios/ios-tls-override.js
index c9b7a80..31baaba 100644
--- a/ios/ios-tls-override.js
+++ b/ios/ios-tls-override.js
@@ -1,6 +1,31 @@
-// Since iOS 11 (2017) Apple has used BoringSSL internally to handle all TLS. This code
-// hooks low-level BoringSSL calls, to override all custom certificate validation options complete.
-// This is a good intro: https://nabla-c0d3.github.io/blog/2019/05/18/ssl-kill-switch-for-ios12/
+/**************************************************************************************************
+ *
+ * Once we have captured traffic (once it's being sent to our proxy port) the next step is
+ * to ensure any clients using TLS (HTTPS) trust our CA certificate, to allow us to intercept
+ * encrypted connections successfully.
+ *
+ * This script does this, by defining overrides to hook BoringSSL on iOS 11+, so that normal
+ * certificate validation is skipped, and instead any TLS connection using our trusted CA is
+ * always trusted. In general use this disables both normal & certificate-pinned TLS/HTTPS
+ * validation, so that all connections which use your CA should always succeed.
+ *
+ * This does not completely disable TLS validation, but it does significantly relax it - it's
+ * intended for use with the other scripts in this repo that ensure all traffic is routed directly
+ * to your MitM proxy (generally on your local network). You probably don't want to use this for
+ * any sensitive traffic sent over public/untrusted networks - it is difficult to intercept, and
+ * any attacker would need a copy of the CA certifcate you're using, but by its nature as a messy
+ * hook around TLS internals it's probably not 100% secure.
+ *
+ * Since iOS 11 (2017) Apple has used BoringSSL internally to handle all TLS. This code
+ * hooks low-level BoringSSL calls, to override all custom certificate validation completely.
+ * https://nabla-c0d3.github.io/blog/2019/05/18/ssl-kill-switch-for-ios12/ to the general concept,
+ * but this
+ *
+ * Source available at https://github.com/httptoolkit/frida-interception-and-unpinning/
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * SPDX-FileCopyrightText: Tim Perry <tim@httptoolkit.com>
+ *
+ *************************************************************************************************/
 
 try {
     Module.ensureInitialized("libboringssl.dylib");