SSL Certificates (Install Charles Root Certificate )

SSL Certificates

Charles generates its own certificates for sites, which it signs using a Charles Root Certificate, which is uniquely generated for your installation of Charles (as of v3.10). You will see a warning in your browser, or other application, when it receives that certificate because the Charles Root Certificate is not in your list of trusted root certificates. See SSL Proxying.

You can choose to permanently trust each site's certificate as you encounter it, in which case you do not need to trust the Charles Root Certificate. If you would like to automatically trust every certificate issued by Charles, continue with these instructions.

The following instructions are for different browsers and applications to help you trust your Charles Root Certificate so you no longer see certificate warnings.

Note that the Charles Root Certificate approach changed with version 3.10 of Charles, so if you have already followed this procedure for an older version of Charles you will need to do it again.

Windows / Internet Explorer

In Charles go to the Help menu and choose "SSL Proxying > Install Charles Root Certificate". A window will appear warning you that the CA Root certificate is not trusted.

Click the "Install Certificate" button to launch the Certificate Import Wizard. The certificate must be imported into the "Trusted Root Certification Authorities" certificate store, so override the automatic certificate store selection.

Complete the wizard and your Charles Root Certificate is now installed. You may need to restart IE before the installation takes affect.

Mozilla Firefox

First ensure that Firefox is connected to Charles. You should see browsing from Firefox being recorded in Charles.

Visit https://chls.pro/ssl in Firefox. You will be presented with a certificate import dialog. Tick the option "Trust this CA to identify websites" and complete the import.

macOS

In Charles go to the Help menu and choose "SSL Proxying > Install Charles Root Certificate". Keychain Access will open. Find the "Charles Proxy..." entry, and double-click to get info on it. Expand the "Trust" section, and beside "When using this certificate" change it from "Use System Defaults" to "Always Trust". Then close the certificate info window, and you will be prompted for your Administrator password to update the system trust settings.

You may need to quit and reopen Safari to see the change.

iOS devices

• Set your iOS device to use Charles as its HTTP proxy in the Settings app > Wifi settings.
• Open Safari and browse to https://chls.pro/ssl. Safari will prompt you to install the SSL certificate.
• If you are on iOS 10.3 or later, open the Settings.app and navigate to General > About > Certificate Trust Settings, and find the Charles Proxy certificate, and switch it on to enable full trust for it (More information about this change in iOS 10).
• Now you should be able to access SSL websites with Charles using SSL Proxying.

Charles supports App Transport Security (ATS) as of the 3.11.4 release.

iOS Simulators

Quit your iOS Simulator. Launch Charles and go to the Help menu. Choose the "SSL Proxying > Install Charles Root Certificate in iOS Simulators" item. This will install your Charles Root Certificate into all of your iOS Simulators. Now when you start the iOS Simulator, you should be able to access SSL websites with Charles using SSL Proxying.

tvOS

In order to change the proxy settings on tvOS you must use Apple Configurator 2 from the App Store.

• Create a New Profile
• Add a Global HTTP Proxy payload
  • Proxy Type: Manual
  • Fill in the proxy server and port to point to Charles on your desktop machine. No username or password is required.
• Add the Charles Root Certificate in a Certificates payload:
  • In Charles, from the Help > SSL Proxying menu choose Save Charles Charles Root Certificate, choosing the .cer format from the filetype dropdown.
  • In Apple Configurator 2, add a Certificates payload using that file.

Deploy the configuration profile onto your Apple TV.

Then go into Settings > General > About > Certificates and enable trust for the Charles Proxy certificate.

Android

As of Android N, you need to add configuration to your app in order to have it trust the SSL certificates generated by Charles SSL Proxying. This means that you can only use SSL Proxying with apps that you control.

In order to configure your app to trust Charles, you need to add a Network Security Configuration File to your app. This file can override the system default, enabling your app to trust user installed CA certificates (e.g. the Charles Root Certificate). You can specify that this only applies in debug builds of your application, so that production builds use the default trust profile.

Add a file res/xml/network_security_config.xml to your app:

<network-security-config> 
  <debug-overrides> 
    <trust-anchors> 
      <!-- Trust user added CAs while debuggable only -->
      <certificates src="user" /> 
    </trust-anchors> 
  </debug-overrides> 
</network-security-config>

Then add a reference to this file in your app's manifest, as follows:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config" ... >
        ...
    </application>
</manifest>

Google Chrome

On macOS, please follow the instructions for macOS above. These instructions only apply on Windows.

In Charles go to the Help menu and choose "SSL Proxying > Save Charles Root Certificate". Save the root certificate as a Binary Certificate (.cer) to your desktop, or somewhere where you can easily access it in the next step.

In Chrome, open the Settings. At the bottom of the settings page, click "Advanced" to open the advanced section, then click the "Manage certificates…" button.

Go to the "Trusted Root Certification Authorities" tab and click "Import…".

Find the certificate file you saved from Charles in the previous step, then click Next and Finish, leaving the default options, until you complete the import. Chrome will now always trust certificates signed by Charles.

After importing you can delete the certificate file that you saved.

Java Applications

You can add your Charles Root Certificate to your root certificate trust store in Java, then all Java applications will trust the certificates that Charles issues. Note that you may need to do this each time you upgrade your Java installation.

In Charles go to the Help menu and choose "SSL Proxying > Save Charles Root Certificate". Save the root certificate as a Base 64 encoded certificate (.pem) to your desktop, or somewhere where you can easily access it in the next step.

Now find the cacerts file, it should be in your $JAVA_HOME/jre/lib/security/cacerts, where $JAVA_HOME is your java home directory for the JVM you’re using.

On Linux, $JAVA_HOME will probably be set already. On macOS, if it isn't set, try running /usr/libexec/java_home to get the location of your JVM.

Then type (substituting for $JAVA_HOME and the appropriate path to the certificate):

sudo keytool -import -alias charles -file ~/Desktop/charles-ssl-proxying-certificate.pem -keystore JAVA_HOME/jre/lib/security/cacerts -storepass changeit

(changeit is the default password on the cacerts file)

On Windows you may need to run the above from a command prompt as Administrator, and remove the "sudo" at the start of the line.

Then try:

keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

If you have multiple Java installations you may need to work out which ones you’re using to run your application and do this on the appropriate one. Or do it on all of your Java installations.

On macOS the Java Plugin has its cacerts file at /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/lib/security. You should add the Charles root certificate to that cacerts file if you want applets running in your browser to trust Charles.

Python

Python's requests module will fail with an error when you try to use it with SSL Proxying in Charles:

 requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate
 verify failed (_ssl.c:590)

You can configure requests to trust your Charles Root Certificate. First save your certificate as a .pem file using the Help > SSL Proxying > Save Charles Root Certificate menu. Then configure your Session as follows:

from requests import Session

session = Session()
session.verify = "charles-ssl-proxying-certificate.pem"

Thank you to Felipe Ferri for providing this example code.