Port MASTG-TEST-0022 (by @guardsquare)

[titze]

Thank you for submitting a Pull Request to the OWASP MASTG. Please make sure that:

• Your contribution is written in the 2nd person (e.g. you)
• Your contribution is written in an active present form for as much as possible.
• You have made sure that the reference section is up to date (e.g. please add sources you have used, make sure that the references to MITRE/MASVS/etc. are up to date)
• Your contribution has proper formatted markdown and/or code
• Any references to website have been formatted as [TEXT](URL “NAME”)
• You verified/tested the effectiveness of your contribution (e.g.: is the code really an effective remediation? Please verify it works!)

If your PR is related to an issue. Please end your PR test with the following line:
This PR closes #2958.

Couple of notes:

• I did not move the original dynamic analysis, as I believe this does not really test if pinning is performed, or would give much information (e.g., for which domains). happy to discuss
• The old test also had in its headline "Testing Custom Certificate Stores". This is not really there anymore now. The Network configuration does not allow this, and I am not sure there is even a good reason to do this at all. The MASWE-047 is also about pinning only

[sushi2k]

Added comment to NSC config

[sushi2k]

Thank you for the new test cases and the PR @titze! Please check the suggestions below.

[sushi2k]

I think we can remove this section.

Android versions lower than 7.0 are around 1.6% of users and declining, see https://apilevels.com/.

@cpholguera didn't we agree on a minimum version of the Android Level and we said we only support Android 7.0 onwards in the MASTG? I couldn't find the statement in the MASTG.

[titze]

For Android 7.0 I agree.

But what about other communication libraries like okhttp? I think it would be valuable to read about those, and that you can configure this differently for them, wdyt?

[cpholguera]

I agree we should keep the mention. Maybe this wasn't clear due to how the section is currently structured: it's a subsection of "### Android Network Security Configuration"

I think we should have a dedicated section: "### Certificate Pinning"

And have subsections for each method.

[cpholguera]

I asked perplexity to draft one for us, it's nice because it also includes one method we don't have here yet: TrustManager, and more.

@titze could you use this as reference to rework this section? (Carefully review and rewrite as needed since this is fully AI generated; the markdown header levels also don't match). Recommendations shouldn't be here, consider reviewing the corresponding MASWE and creating a new MASTG-BEST-xxxx to capture them and link from the tests.

---

Certificate Pinning

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[1][3]. While effective when implemented correctly, variations in implementation methodologies can introduce vulnerabilities, particularly when developers misuse platform-specific APIs or third-party libraries[2][4]. Below is an analysis of common implementation approaches, their security implications, and recommendations for robust deployment.

Implementation Methods for Certificate Pinning in Android

Network Security Configuration (API 24+)

Introduced in Android Nougat (API 24), the network security configuration file (network_security_config.xml) provides a declarative method for certificate pinning without requiring extensive custom code[3]. Developers specify public key hashes (pins) for trusted domains directly in XML, allowing the Android operating system to validate server certificates during the TLS handshake. This method is inherently secure because it leverages the OS’s certificate validation routines, ensuring that only the cleaned certificate chain—free of attacker-injected certificates—is evaluated against the pins[3]. For example, pins derived from a server’s public key remain valid even if the certificate is reissued with the same key, reducing maintenance overhead[3].

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[1][3]. When configured correctly—by pinning to intermediate or root certificates rather than leaf certificates—OkHttp provides robust protection against MITM attacks. However, insecure implementations arise when developers hardcode leaf certificate hashes, which become invalid upon certificate rotation, necessitating frequent app updates[3]. Additionally, older versions of OkHttp were vulnerable to chain-cleaning flaws if they relied on getPeerCertificates(), which returns server-sent certificates rather than the validated chain[2]. Upgrading to the latest OkHttp version and pinning to public keys mitigates these risks[2].

TrustKit for Backward Compatibility

For Android versions prior to API 24, the TrustKit library offers a backward-compatible solution by integrating certificate pinning into the app’s network layer[3]. TrustKit validates pins against the cleaned certificate chain and supports report-uri functionality to notify developers of pin validation failures. However, improper configuration—such as enabling non-default options like CA pinning—can reintroduce vulnerabilities akin to custom implementations[2]. For instance, the PhoneGap SSL Certificate Checker plugin’s CA-pinning feature was found to be bypassable until patched[2].

Custom Implementations Using HttpsURLConnection

Developers occasionally implement certificate pinning manually by overriding TrustManager or HostnameVerifier in HttpsURLConnection[1][2]. 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[2]. For example, an attacker could present a malicious certificate chain containing a trusted root CA, causing the app to mistakenly validate a rogue leaf certificate[2]. Secure custom implementations require reconstructing the OS-validated certificate chain, a complex process prone to implementation errors[2].

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[2]. 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[2].

Recommendations for Secure Certificate Pinning

1. Prefer Network Security Configuration: For apps targeting API 24+, use the built-in network_security_config.xml to delegate pinning to the OS, minimizing human error[3].
2. Update Libraries Regularly: Ensure OkHttp, TrustKit, and other third-party libraries are updated to versions that validate cleaned certificate chains[2][3].
3. Avoid Leaf Certificate Pinning: Pin to public keys of intermediate or root CAs to accommodate certificate rotations without app updates[3].
4. Deprecate Custom Implementations: Refactor legacy code using HttpsURLConnection or TrustManager to use vetted libraries or the network security config[2].
5. Monitor for Pinning Failures: Implement report-uri endpoints or logging mechanisms to detect and respond to pin validation failures, indicative of ongoing attacks[3].

By adhering to these practices, developers can mitigate risks associated with outdated or insecure pinning implementations while maintaining compatibility across Android versions[4].

Citations

[1] What is Certificate Pinning? - Zimperium https://www.zimperium.com/glossary/certificate-pinning/
[2] Ineffective Certificate Pinning Implementations | Black Duck Blog https://www.blackduck.com/blog/ineffective-certificate-pinning-implementations.html
[3] Blog: Securing HTTPS with Certificate Pinning on Android - Approov https://approov.io/blog/securing-https-with-certificate-pinning-on-android
[4] modern alternatives to outdated certificate pinning practices https://blog.cloudflare.com/why-certificate-pinning-is-outdated/
[5] Mobile Development and Security: Certificate Pinning on Android https://nglogic.com/cert-pinning-android/
[6] 3 Ways How To Implement Certificate Pinning on Android - Netguru https://www.netguru.com/blog/android-certificate-pinning
[7] Certificate Pinning — Does It Help App Security? – PreEmptive https://www.preemptive.com/blog/what-is-certificate-pinning-app-security/
[8] Enhancing Security in Android Applications with SSL Pinning https://www.droidcon.com/2024/07/11/enhancing-security-in-android-applications-with-ssl-pinning/
[9] Defeating Android Certificate Pinning with Frida - HTTP Toolkit https://httptoolkit.com/blog/frida-certificate-pinning/
[10] Higher risk of no certificate pinning on mobile apps vs web apps? https://security.stackexchange.com/questions/226062/higher-risk-of-no-certificate-pinning-on-mobile-apps-vs-web-apps
[11] Android SSL certificate pinning to prevent Man-in-the-middle attack https://blog.ostorlab.co/android-ssl-pinning.html
[12] What is the best way to implement SSL Pinning? : r/androiddev https://www.reddit.com/r/androiddev/comments/uuie96/what_is_the_best_way_to_implement_ssl_pinning/
[13] Certificate Pinning - What it Is, its Benefits, and Drawbacks https://www.sapphire.net/blogs-press-releases/certificate-pinning/
[14] TLS Certificate Security for Android | Guardsquare https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps
[15] The problem with certificate pinning | SSLs.com Blog https://www.ssls.com/blog/the-problem-with-certificate-pinning/
[16] Security with network protocols - Android Developers https://developer.android.com/privacy-and-security/security-ssl
[17] Certificate Pinning: Challenges and Viable Alternatives - SecureW2 https://www.securew2.com/blog/everything-you-need-to-know-about-certificate-pinning
[18] Unpacking Android Security: Part 3 — Insecure Communication https://proandroiddev.com/unpacking-android-security-part-3-insecure-communication-d5e833166040
[19] Security with network protocols - Android Developers https://developer.android.com/privacy-and-security/security-ssl
[20] Certificate Pinning, Public-Key Pinning oder CA Pinning? https://www.cologne-intelligence.de/blog/pinning-in-android-apps
[21] Secure Android Apps with TLS/SSL Pinning - ProAndroidDev https://proandroiddev.com/secure-android-apps-with-tls-ssl-pinning-c087fc7ef828

[titze]

I added / merged most of this into the existing doc, and cleaned it up a bit.
I did not add any recommendations, since those are already captured in https://mas.owasp.org/MASWE/MASVS-NETWORK/MASWE-0047/#mitigations.

[sushi2k]

Suggested change

There are various ways how [certificate pinning]("../../../Document/0x05g-Testing-Network-Communication.md#certificate-pinning-without-android-network-security-configuration") can be done for an application.

If we remove it in the document, let's also remove the reference here.

[titze]

I think the text itself does make sense, but if the link is gone, it makes sense to remove that.

[sushi2k]

Suggested change

	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 the certificate is not pinned correctly or at all.
	The goal of this test case is to dynamically check if the connection to a server can be intercepted using a [Machine-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.

[titze]

@sushi2k I disagree with the "Machine-in-the-Middle". Technically correct, but "man-in-the-middle" is a very common and known term.

[cpholguera]

Hi @titze there's a problem with the PR, it now affects 240 files. Could you please recheck/fix the merging of the main branch so that only your changes are showing?

[titze]

Fixed. I messed up the rebase on master...

[cpholguera]

No problem, thanks so much for the fix!