# Installing the Zyte CA certificate

On some operating systems or web browsers, using Zyte services like [Zyte
API](../zyte-api/get-started.md#zyte-api) may require installing the Zyte CA certificate.

You can tell that is your case when every attempt to use a given Zyte service
results in an error about SSL certificate verification.

To install the Zyte CA certificate, [get it](#ca-file) and follow the
instructions below for your operating system or web browser.

## Get the Zyte CA certificate

Download the certificate from [here](https://docs.zyte.com/_static/zyte-ca.crt).

## Operating systems

### Windows 10

1. Press the `Win key + R` hotkey and input `mmc` in Run to open the Microsoft Management Console window.
2. Click `File` and select `Add/Remove Snap-ins`.
3. In the opened window select `Certificates` and press the `Add >` button.
4. In the Certificates Snap-in window select `Computer account > Local Account`, and press the `Finish` button to close the window.
5. Press the `OK` button in the Add or Remove Snap-in window.
6. Back in the Microsoft Management Console window, select `Certificates` under Console Root and  right-click `Trusted Root Certification Authorities`.
7. From the context menu select `All Tasks > Import` to open the Certificate Import Wizard window from which you can add the [Zyte CA certificate](#ca-file).

More details can be found [here](https://windowsreport.com/install-windows-10-root-certificates/).

### macOS

1. Open Keychain Access window (`Launchpad > Other > Keychain Access`).
2. Select `System` tab under Keychains, drag and drop the downloaded
   certificate file (or select File > `Import Items...` and navigate to
   the file).
3. Enter the administrator password to modify the keychain.
4. Double-click the `Crawlera CA` certificate entry, expand Trust, next
   to When using this certificate: select `Always Trust`.
5. Close the window and enter the administrator password again to update
   the settings.

> [!NOTE]
> These steps configure SSL for system tools and web browsers. Python on
> macOS does not read from the system Keychain by default; if you are
> using Python, see [Python](#ca-python) instead.

### Linux

1. Install the downloaded [Zyte CA certificate](#ca-file) file:
   ```bash
   sudo cp zyte-ca.crt /usr/local/share/ca-certificates/zyte-ca.crt
   ```
2. Update stored Certificate Authority files:
   ```bash
   sudo update-ca-certificates
   ```

## Web browsers

### Firefox

1. Open Preferences, visit Privacy & Security tab, scroll down to the Certificates section, click View Certificates… button to open Certificate Manager.
2. Under Authorities tab click Import… button, navigate to the certificate file.
3. In the opened window (You have been asked to trust a new Certificate Authority (CA)) check the first option Trust this CA to identify websites and click the OK button to finish importing the certificate.
4. Click the OK button to save settings and exit Certificate Manager.

### Chrome

1. Click the triple-dot icon in the top right corner and choose `Settings`.
2. Scroll to the `Privacy and security` section and click on `Security`.
3. Scroll down to find and click `Manage Certificates`.
4. The next steps will depend on the operating system. In the case of macOS, the previous action will open the `Keychain Access`, see [macOS](#ca-macos) above. In the case of Windows, the Certificates application should appear, select `Trusted Root Certification Authorities` tab, click `Import...` button, navigate to the certificate file, verify the import was successful and the installed certificate is displayed under Trusted Root Certification Authorities tab, close the Certificates window.

## Tech stacks

### Node.js

Point the `NODE_EXTRA_CA_CERTS` environment variable to the [Zyte CA
certificate](#ca-file).

### Python

To use [requests](https://requests.readthedocs.io/en/latest/), build a [CA bundle](#ca-bundle) and point the
`REQUESTS_CA_BUNDLE` environment variable to it.

> [!NOTE]
> On macOS, Python installed from [python.org](https://www.python.org/downloads/mac-osx/) does not read from the
> system Keychain. If Python SSL is not working at all, first run the
> certificate installer included with the Python installation:
> 
> ```bash
> open /Applications/Python\ 3.x/Install\ Certificates.command
> ```
> 
> Replace `3.x` with your installed Python version (e.g. `3.12`).
> This step only applies to python.org installations; Homebrew, pyenv,
> and conda installations do not require it.

## Alternative files

### CA bundle

Sometimes you cannot specify an *extra* certificate, like the Zyte CA
certificate, and instead you must specify a CA certificate *bundle* that
*includes* the Zyte CA certificate.

To generate such a CA certificate bundle:

1. Get a generic CA certificate bundle in PEM format, e.g. [curl’s](https://curl.se/ca/cacert.pem).
2. Append the contents of the [Zyte CA certificate](#ca-file) to the end
   of the generic CA certificate bundle file.

You can then use the resulting file as a CA certificate bundle that supports
Zyte domains.

### PKCS#12

In case of requiring a certificate with PKCS#12 format, you can generate it with the following OpenSSL command:

```bash
openssl pkcs12 -export -nokeys -password pass: -in zyte-ca.crt -out zyte-ca.p12
```