SSL certificates

From Official Kodi Wiki
Jump to navigation Jump to search

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 web browsers would not be able to access them). However, you have to be careful with servers that you manage yourself; see below for the details on how Kodi checks certificates and what steps you might have to take.

1 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 check is performed by curl when initially connecting to a server. If the check fails, the connection will be terminated and the resource in question cannot be used.

2 Checks performed

Kodi will check that the certificate of the server

  1. is trusted, and
  2. that it was explicitly issued (by domain name or IP address) for the server you wanted to connect to.

2.1 Trust

SSL trust is conferred by only allowing certificates issued by Certificate Authorities known to thoroughly check the claimed ownership of servers prior to issuance. 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.

2.2 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.

3 Trusting your servers

3.1 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, notable for the fact that it issues such certificates for free (the trade-off being that they must be renewed every 89 days, compared to most other CAs which issue certificates that are valid for at least a year), but any major CA will work.

3.2 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 (known as a 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.

3.2.1 Adding certificates to the trust store

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

3.2.1.1 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

.

3.2.1.2 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.

3.2.2 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, since man-in-the-middle (MITM) attacks are trivially possible. You have been warned. To disable the check, add |verifypeer=false to the end of the URL or remote path of your source.