Port MASTG-TEST-0022: Testing Custom Certificate Stores and Certificate Pinning (android) (by @guardsquare)

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 more details.
+
+Various approaches exist, depending on the API level of the 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 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:
 
@@ -105,7 +113,7 @@ If at least one of the pinned digests matches, the certificate chain will be con
 <?xml version="1.0" encoding="utf-8"?>
 <network-security-config>
     <domain-config>
-        Use certificate pinning for OWASP website access including sub domains
+        <!-- Use certificate pinning for OWASP website access including sub domains -->
         <domain includeSubdomains="true">owasp.org</domain>
         <pin-set expiration="2018/8/10">
             <!-- Hash of the public key (SubjectPublicKeyInfo of the X.509 certificate) of
@@ -119,6 +127,48 @@ If at least one of the pinned digests matches, the certificate chain will be con
 </network-security-config>
 ```
 
+!!! note "Backup Pin"
+    When implementing Certificate Pinning you should always include a backup pin to ensure that the app's connectivity is unaffected, in case you need update the certificate. A backup pin could be the intermediate certificate of the CA.
+
+!!! note "Expiration dates"
+    If you [set an expiration date](https://developer.android.com/privacy-and-security/security-config#CertificatePinning), make sure to update your application in time. Otherwise pinning will **not** be performed at all after the configured date.
+
+!!! warning "Technologies not using Network Security Configuration"
+    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 using the OkHttp Library
+
+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.
+
+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()
+      .certificatePinner(
+          CertificatePinner.Builder()
+              .add("publicobject.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")
+              .build())
+      .build()
+```
+
+### Certificate Pinning using TrustKit
+
+For Android versions prior to API 24, the [TrustKit library](https://github.com/datatheorem/TrustKit-Android) offers a backward-compatible solution. TrustKit validates pins against the cleaned certificate chain. However, improper configuration — such as enabling non-default options like CA pinning — can reintroduce [vulnerabilities akin to custom implementations](https://www.blackduck.com/blog/ineffective-certificate-pinning-implementations.html).
+
+### 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 [be manipulated by attackers](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-0240.md

@@ -0,0 +1,38 @@
+---
+title: Missing Certificate Pinning in Code
+platform: android
+id: MASTG-TEST-0240
+type: [static]
+weakness: MASWE-0047
+---
+
+## Overview
+
+Apps can configure certificate pinning using the [Network Security Configuration]("../../../Document/0x05g-Testing-Network-Communication.md#certificate-pinning"). For each domain, one or multiple digests can be pinned.
+
+Certificate pinning can also be done manually in the code. Depending on the used technologies, this can be done for example by:
+
+- Pinning a certificate with a custom `TrustManager`,
+- configuring the used third party networking libraries to pin certificates,
+- use plugins to achieve certificate pinning for hybrid apps.
+
+Chapter [Certificate pinning without Android Network Security Configuration]("../../../Document/0x05g-Testing-Network-Communication.md#certificate-pinning-without-android-network-security-configuration") explains in more detail how this can be achieved in the app.
+
+The goal of this test is to check if any certificate pinning exists.
+
+!!! note "Limitations"
+    Since there are many different ways to achieve certificate pinning in the code, checking statically if the application performs pinning might not reveal all such locations. To make sure certificates are pinned for all relevant connections, additional dynamic analysis can be performed.
+
+## Steps
+
+1. Reverse engineer the app (@MASTG-TECH-0017).
+2. Inspect the AndroidManifest.xml, and check if a `networkSecurityConfig` is set in the `<application>` tag. If yes, inspect the referenced file, and all domains which have a pinned certificate.
+3. Run a static analysis tool such as @MASTG-TOOL-0011 or @MASTG-TOOL-0018 on the code and look for APIs or configurations performing certificate pinning (see above). Extract all domains for which the certificates are pinned.
+
+## Observation
+
+The output should contain a list of domains which enable certificate pinning.
+
+## Evaluation
+
+The test case fails if any relevant domain does not enable certificate pinning.

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

@@ -0,0 +1,26 @@
+---
+title: Expired Certificate Pins
+platform: android
+id: MASTG-TEST-0241
+type: [static]
+weakness: MASWE-0047
+---
+
+## Overview
+
+Apps can configure expiration dates for pinned certificates in the [Network Security Configuration]("../../../Document/0x05g-Testing-Network-Communication.md#certificate-pinning"). After the expiration date, the pin is no longer used and all installed CAs for that domain are trusted.
+
+The goal of this test is to check if any expiration date is in the past.
+
+## Steps
+
+1. Reverse engineer the app (@MASTG-TECH-0017).
+2. Inspect the AndroidManifest.xml, and check if a `networkSecurityConfig` is set in the `<application>` tag. If yes, inspect the referenced file, and extract the expiration dates for every domain.
+
+## Observation
+
+The output should contain a list of expiration dates for pinned certificates.
+
+## Evaluation
+
+The test case fails if any expiration date is in the past.

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

@@ -0,0 +1,29 @@
+---
+title: Missing Certificate Pinning in Network Traffic
+platform: network
+id: MASTG-TEST-0x242
+type: [static]
+weakness: MASWE-0047
+---
+
+## Overview
+
+There are various ways how certificate pinning can be done for an application.
+
+Since statically finding all of the locations where certificate pinning is performed might not be feasible, this test case uses dynamic analysis to observe all connections the app makes.
+
+The goal of this test case is to dynamically check if the connection to a server can be intercepted using a [Man-in-the-Middle attack]("../../../Document/0x04f-Testing-Network-Communication.md#mitm-attack). If this is possible, it means that the certificate is not pinned correctly or not pinned at all.
+
+## Steps
+
+1. Set up an intercepting proxy, for example @MASTG-TOOL-0077 or @MASTG-TOOL-0097.
+2. Install the application on a device connected to that proxy, and intercept the communication.
+3. Extract all domains which were intercepted.
+
+## Observation
+
+The output should contain a list domains, for which the interception was successful.
+
+## Evaluation
+
+The test case fails if any relevant domain was intercepted.

tests/android/MASVS-NETWORK/MASTG-TEST-0022.md

@@ -7,6 +7,9 @@ platform: android
 title: Testing Custom Certificate Stores and Certificate Pinning
 masvs_v1_levels:
 - L2
+status: deprecated
+covered_by: [MASTG-TEST-0x22-1,MASTG-TEST-0x22-2,MASTG-TEST-0x22-3]
+deprecation_note: New version available in MASTG V2
 ---
 
 ## Overview