SSL certificates

Starting with v18 Leia, Kodi verifies the certificates of peers in SSL-secured connections. This is very important for security, but might lead to some troubles connecting to HTTPS and FTPS servers depending on your setup.

For connections to publicly available third-party servers no problems should be experienced because they use certificates issued by trusted certificate authorities (CAs) and are set up in a correct way (otherwise e.g. browers would not be able to access them, too). However, you have to be careful with servers that you set up on your own. See below for the details on how Kodi checks certificates and what steps you might have to take.

Scope

Certificate checking in the context of this Wiki page affects all outgoing SSL-secured connections made by Kodi (both core Kodi and Python add-ons) via the curl library. In practice, this means all HTTPS and FTPS protocol requests. The checking is performed by curl when connecting to a server. If the check fails, the connection will be terminated and the resource in question cannot be used.

Checks performed

Kodi will check that the certificate of the server

1. is trusted and that it
2. was issued for the server you wanted to connect to.

Trust

SSL forms trust by only allowing certificates issued by certificate authorities known to thoroughly check the claimed ownership of servers to pass. Lists of such trusted authorities are usually distributed with operating systems and browsers. If this check fails, you will get errors similar to ERROR: CCurlFile::FillBuffer - Failed: Peer certificate cannot be authenticated with given CA certificates(60) in your log and connections will fail. There are multiple ways to deal with this when the need arises that are detailed below. For technical details on the check, see CURLOPT_SSL_VERIFYPEER.

Server identity

Verifying the server name in the certificate against the host being connected to is always enabled and cannot be disabled. You have to be careful to ensure that the hostname you enter in Kodi (e.g. as part of an URL or in file source settings) matches the name on the certificate. Otherwise you will get errors similar to SSL: certificate subject name 'xy' does not match target host name 'real.host.name' in your log and connections will fail. For technical details on the check, see (via CURLOPT_SSL_VERIFYHOST.

Trusting your servers

Servers accessible via the internet

If your server is accessible via the internet, you can get a certificate from a trusted authority. Let's Encrypt is one example of such a certificate authority and issues certificates for free, but any major CA will work.

Servers not accessible via the internet

If your server is not accessible via the internet, you cannot get a certificate from a trusted authority, so you have to create a certificate yourself (called self-signed certificate). For instructions on how to do this, please refer to the manual of your server software. After that, you have to convince Kodi to trust that certificate.

Adding the certificate to the trust store

How Kodi determines what certificate authorities to trust depends on your platform.

Linux

The certificate store of the operating system (as compiled into the curl library used on the system) is used. The process of adding new certificates to that store depends on your distribution, so please refer to its documentation. For Ubuntu and similar, it is sufficient to copy your certificate (in DER format) to /usr/local/share/ca-certificates/ and then run sudo update-ca-certificates.

All other platforms

Kodi includes its own bundle of default trusted certificate authorities in the file system/certs/cacert.pem of the Kodi installation.

1. Copy the file to a new location
2. Add your certificate (in PEM format) to the end of the new file
3. Set the environment variable SSL_CERT_FILE to the location of that new file

This method is also usable on Linux if you do not want to change your system trust store.

Disabling the check

If for whatever reason you cannot get a self-signed certificate trusted, there is the explicitly discouraged option to disable the check altogether for network file sources. This way, you will lose most of the benefits of using SSL at all since man-in-the-middle (MITM) attacks are trivially possible, so be warned. To disable the check, add |verifypeer=false to the end of the URL or remote path of your source.