review comments

Document/0x05g-Testing-Network-Communication.md

@@ -88,9 +88,17 @@ The default configuration for apps targeting Android 6.0 (API level 23) and lowe
 </base-config>
 ```
 
-#### Certificate Pinning
+### Certificate Pinning
 
-The Network Security Configuration can also be used to pin [declarative certificates](https://developer.android.com/training/articles/security-config.html#CertificatePinning "Certificate Pinning using Network Security Configuration") to specific domains. This is done by providing a `<pin-set>` in the Network Security Configuration, which is a set of digests (hashes) of the public key (`SubjectPublicKeyInfo`) of the corresponding X.509 certificate.
+Certificate pinning is a critical security mechanism employed in Android applications to safeguard against man-in-the-middle (MITM) attacks by ensuring that the app communicates exclusively with servers possessing predefined cryptographic credentials.
+
+While effective when implemented correctly, insecure implementations potentially enable attackers to read and modify all communication. See @MASWE-0047 for details on impact, modes of introduction and mitigations.
+
+Various approaches exist, depending on the API level of your app, and on the used libraries. In the following, the most common ones are briefly highlighted.
+
+#### Pinning via Network Security Configuration (API 24+)
+
+The Network Security Configuration can also be used to pin [declarative certificates](https://developer.android.com/training/articles/security-config.html#CertificatePinning) to specific domains. This is done by providing a `<pin-set>` in the Network Security Configuration, which is a set of digests (hashes) of the public key (`SubjectPublicKeyInfo`) of the corresponding X.509 certificate.
 
 When attempting to establish a connection to a remote endpoint, the system will:
 
@@ -129,14 +137,11 @@ If at least one of the pinned digests matches, the certificate chain will be con
     If your application uses low level networking APIs or SDKs like Flutter, the Network Security Configuration might not be used by default. In these cases, you will need to enable certificate pinning specifically for the technology used.
     For example, applications based on Cordova do not support Certificate Pinning natively, so the plugin [PhoneGap SSL Certificate Checker](https://github.com/EddyVerbruggen/SSLCertificateChecker-PhoneGap-Plugin) can be used.
 
-### Certificate pinning without Android Network Security Configuration
+### Certificate Pinning using the OkHttp Library
 
-If your application targets an Android version lower than Android 7.0 Nougat (SDK version 24), the Android Security Configuration is not available, and you need to implement certificate pinning manually.
+The OkHttp library is widely used for certificate pinning in Android due to its built-in `CertificatePinner` class, which enables developers to pin public key hashes or certificate signatures. This provides robust protection against MITM attacks.
 
-!!! warning "Implementing Certificate Pinning Manually"
-    Implementing certificate pinning manually has a high risk of adding functionality to your application that makes the app even less secure. If you are adding this manually take extreme care of implementing this correctly.
-
-Applications that use third-party networking libraries may utilize the libraries' certificate pinning functionality. For example, [okhttp](https://square.github.io/okhttp/features/https/#certificate-pinning-kt-java) can be set up with the `CertificatePinner` as follows:
+For example, [CertificatePinner](https://square.github.io/okhttp/features/https/#certificate-pinning-kt-java) can be set up as follows:
 
 ```java
 val client = OkHttpClient.Builder()
@@ -147,6 +152,19 @@ val client = OkHttpClient.Builder()
       .build()
 ```
 
+### Custom Certificate Pinning
+
+Certificate pinning can be implemented manually by overriding `TrustManager` or `HostnameVerifier` in [`HttpsURLConnection`](https://developer.android.com/reference/java/net/HttpURLConnection). This approach is highly error-prone, as it often involves directly inspecting server-sent certificates via `getPeerCertificates()`, which returns unvalidated chains that [attackers can manipulate](https://www.blackduck.com/blog/ineffective-certificate-pinning-implementations.html).
+
+!!! warning "Implementing Certificate Pinning Manually"
+    Implementing certificate pinning manually has a high risk of adding functionality to your application that makes the app even less secure. If you are adding this manually, take extreme care of implementing this correctly.
+
+### Vulnerable Third-Party Libraries
+
+Third-party libraries like older versions of the Secure-HTTP Cordova plugin or misconfigured PhoneGap plugins historically introduced vulnerabilities by [mishandling certificate chains](https://www.blackduck.com/blog/ineffective-certificate-pinning-implementations.html). These libraries often exposed non-default configuration options that, when enabled, allowed attackers to bypass pinning by injecting untrusted certificates into the chain.
+
+Developers must audit third-party libraries for adherence to chain-validation best practices and prefer those leveraging the Android Keystore system for pinning.
+
 ### Security Provider
 
 Android relies on a [security provider](https://developer.android.com/training/articles/security-gms-provider.html "Update your security provider to protect against SSL exploits") to provide SSL/TLS-based connections. The problem with this kind of security provider (one example is [OpenSSL](https://www.openssl.org/news/vulnerabilities.html "OpenSSL Vulnerabilities")), which comes with the device, is that it often has bugs and/or vulnerabilities.

tests-beta/android/MASVS-NETWORK/MASTG-TEST-0242.md

@@ -1,5 +1,5 @@
 ---
-title: Missing Certificate Pinning in Network Traffic 
+title: Missing Certificate Pinning in Network Traffic
 platform: network
 id: MASTG-TEST-0x242
 type: [static]