Install System Root Certificate

This API is used to install a system-level root certificate on your Android device, with compatibility across all Android versions.

You might be confused about the difference between the root certificate mentioned here and FIRERPA’s encryption certificate. The FIRERPA encryption certificate is used to encrypt communication traffic between FIRERPA and you, whereas the root certificate referred to here is a system-trusted root certificate built into the Android operating system. This certificate is used for encrypting and decrypting HTTPS and related traffic within the system. If you are familiar with packet capturing (or “interception”), this root certificate is exactly the one used in such scenarios. You can use the API described in this chapter together with the “Set Proxy” API to perform man-in-the-middle (MITM) packet capture. Alternatively, you may choose to use our pre-packaged script startmitm.py. Here, we are only introducing the underlying functionality.

Prerequisites

Ensure that you have obtained the certificate from tools like Fiddler or mitmproxy. For mitmproxy, you should use the certificate file named mitmproxy-ca-cert.pem. For Fiddler, the certificate is typically in .crt format; you can export this file directly from Fiddler and provide its file path as the parameter—there is no need to worry about filename conversions. To avoid unnecessary time consumption, we recommend using mitmproxy. If you are using tools like Charles, we cannot guarantee a smooth setup process, as their configurations tend to be more complex and may require deeper understanding of various certificate types to correctly configure HTTPS interception. If you must use Charles, we suggest configuring it to use SOCKS5 as the proxy protocol.

Installing the Root Certificate

Once you have the path to your prepared certificate file, you can use the following API to install the mitmproxy root certificate. Once installed, it will persist permanently on the device and does not need to be reinstalled.

d.install_ca_certificate(cert_path)

Uninstalling the Root Certificate

You can call the following code to remove a custom root certificate previously installed on the device. We do not recommend frequently installing and uninstalling certificates. Unless necessary, there is no need to invoke this API.

d.uninstall_ca_certificate(cert_path)

A complete example is shown below (we assume the device instance d has already been initialized):

import os

# Construct the path to mitmproxy-ca-cert.pem
HOME = os.path.expanduser("~")
cert_path = os.path.join(HOME, ".mitmproxy", "mitmproxy-ca-cert.pem")
# Use the following line to install the certificate (using mitmproxy as an example)
d.install_ca_certificate(cert_path)

# Use the following line to uninstall the certificate
d.uninstall_ca_certificate(cert_path)

This certificate installation and removal API is universal—you can use it to install any certificate required by applications, including those from Fiddler or Charles, simply by providing the correct file path. If your goal is packet capture, refer to the Set Proxy section afterward to configure the proxy settings to point to the listening address of your MITM tool.