SSL certificates - Revision history

RogueScholar: added Category:Advanced topics using HotCat

2022-03-19T21:05:47Z

added Category:Advanced topics using HotCat

← Older revision		Revision as of 21:05, 19 March 2022
Line 41:		Line 41:
	==== Disabling the check ====		==== 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 <code>\|verifypeer=false</code> to the end of the URL or remote path of your source.		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 <code>\|verifypeer=false</code> to the end of the URL or remote path of your source.

			[[Category:Advanced topics]]

RogueScholar: Fix dead-end page, remove redundant information and fix typos

2021-09-23T01:27:06Z

Fix dead-end page, remove redundant information and fix typos

← Older revision		Revision as of 01:27, 23 September 2021
Line 1:		Line 1:
	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.		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 [[FTP\|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.		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.

	== Scope ==		== 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.		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 [[w:CURL\|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.

	== Checks performed ==		== Checks performed ==
	Kodi will check that the certificate of the server		Kodi will check that the certificate of the server
	# is trusted and that it		# is trusted, and
	# was issued for the server you wanted to connect to.		# that it was explicitly issued (by domain name or IP address) for the server you wanted to connect to.

	=== Trust ===		=== 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 <code>ERROR: CCurlFile::FillBuffer - Failed: Peer certificate cannot be authenticated with given CA certificates(60)</code> 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 [https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html CURLOPT_SSL_VERIFYPEER].		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 <code>ERROR: CCurlFile::FillBuffer - Failed: Peer certificate cannot be authenticated with given CA certificates(60)</code> 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 [https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html CURLOPT_SSL_VERIFYPEER].

	=== Server identity ===		=== 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 <code>SSL: certificate subject name 'xy' does not match target host name 'real.host.name'</code> in your log and connections will fail~~. For technical details on the check, see (via [https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html CURLOPT_SSL_VERIFYHOST]~~.		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 <code>SSL: certificate subject name 'xy' does not match target host name 'real.host.name'</code> in your log, and connections will fail.

	== Trusting your servers ==		== Trusting your servers ==

	=== Servers accessible via the internet ===		=== Servers accessible via the internet ===
			If your server is accessible via the internet, you can get a certificate from a trusted authority. [https://letsencrypt.org/ 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.

	If your server is accessible via the internet, you can get a certificate from a trusted authority. [https://letsencrypt.org/ 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 (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.
	=== 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 ====~~

			==== Adding certificates to the trust store ====
	How Kodi determines what certificate authorities to trust depends on your platform.		How Kodi determines what certificate authorities to trust depends on your platform.

	===== Linux =====		===== 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 [[w:X.690\|DER format]]) to <code>/usr/local/share/ca-certificates/</code> and then run <syntaxhighlight lang="sh">sudo update-ca-certificates</syntaxhighlight>.
	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 <code>/usr/local/share/ca-certificates/</code> and then run <~~code~~>sudo update-ca-certificates</~~code~~>.

	===== All other platforms =====		===== All other platforms =====

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

	# Copy the file to a new location		# Copy the file to a new location
	# Add your certificate (in PEM format) to the end of the new file		# Add your certificate (in [[w:Privacy-Enhanced Mail\|PEM format]]) to the end of the new file
	# Set the environment variable <code>SSL_CERT_FILE</code> to the location of that new file		# Set the environment variable <code>SSL_CERT_FILE</code> to the location of that new file

Line 46:		Line 40:

	==== Disabling the check ====		==== 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 <code>\|verifypeer=false</code> to the end of the URL or remote path of your source.
	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 <code>\|verifypeer=false</code> to the end of the URL or remote path of your source.

Yol at 09:16, 27 May 2018

2018-05-27T09:16:29Z

← Older revision		Revision as of 09:16, 27 May 2018
Line 33:		Line 33:
	===== Linux =====		===== 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 ~~PEM~~ format) to <code>/usr/local/share/ca-certificates/</code> and then run <code>sudo update-ca-certificates</code>.		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 <code>/usr/local/share/ca-certificates/</code> and then run <code>sudo update-ca-certificates</code>.

	===== All other platforms =====		===== All other platforms =====

Yol: Created page with "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..."

2018-05-27T09:14:40Z

Created page with "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..."

New page

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
# is trusted and that it
# 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 <code>ERROR: CCurlFile::FillBuffer - Failed: Peer certificate cannot be authenticated with given CA certificates(60)</code> 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 [https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html 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 <code>SSL: certificate subject name 'xy' does not match target host name 'real.host.name'</code> in your log and connections will fail. For technical details on the check, see (via [https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html 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. [https://letsencrypt.org/ 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 PEM format) to <code>/usr/local/share/ca-certificates/</code> and then run <code>sudo update-ca-certificates</code>.

===== All other platforms =====

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

# Copy the file to a new location
# Add your certificate (in PEM format) to the end of the new file
# Set the environment variable <code>SSL_CERT_FILE</code> 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 <code>|verifypeer=false</code> to the end of the URL or remote path of your source.