Ssl-certificate
Introduction
The use of SSL certificates allows for a secure connection over the HTTPS protocol between participants when working with software. This guide describes how to configure the components of the SmartPlayer platform to work with SSL certificates.
- When purchasing a cloud server - no configuration is required. Everything is set up and working.
- When purchasing a local server - certificates will need to be issued and the SmartPlayer platform will need to be configured. This case will be discussed further in the guide.
Certification Authorities
There are 2 types of certification authorities:
- Certificates issued by widely accepted public certification authorities - These are certificates issued by public companies (such as GlobalSign, Comodo, etc.). The issuance of a certificate signed by such a certification authority is a paid service.
- Self-signed certificates - These are certificates issued by a private (personal) certification authority. A private certification authority in a company is usually maintained by the IT department. Certificates issued by such an authority can be used for various purposes, they are free and can be created independently. Large companies sometimes create their own private certification authority infrastructure and issue certificates signed by it.
Types of Certificates
Theory on types of certificates. The simplified classification of SSL includes the following options:
- Extended Validation Certificate: ExtendedSSL (EV SSL). This is the latest and possibly the most significant development in SSL technology since its introduction. This solution complies with standardized extended validation guidelines. New high-security browsers such as Microsoft Internet Explorer 7+, Opera 9.5+, Firefox 3+, Google Chrome, Apple Safari 3.2+, and iPhone Safari 3.0+ recognize ExtendedSSL certificates as extended validation (EV) certificates. This is relevant for clients who want to declare the highest level of authentication.
- Organization Validated Certificate: OrganizationSSL (OV SSL). GlobalSign has been issuing organization validated certificates for 15 years. Information about companies applying for an OrganizationSSL certificate is thoroughly verified before the certificate is issued.
- Domain Validated Certificate: DomainSSL (DV SSL). DomainSSL certificates are fully supported and recognized by browsers, just like OrganizationSSL certificates, but they have one advantage — they are issued almost instantly and without the need to send company documents for verification. This makes DomainSSL an ideal offer for an organization that needs to obtain an SSL certificate urgently, without additional costs and without the effort of sending company documents for verification.
Certificate Chains
Issuing a certificate implies not just one certificate file, but a chain of certificates that need to be obtained:
- Root SSL Certificate, CA Certificate — This is an electronic document that certification authorities use to sign SSL certificates upon issuance. The root certificate, often called a trusted root certificate, is at the heart of the trust model that supports SSL/TLS.
Each browser contains a root store. Some browsers operate independently, while others use a third-party certificate store. The root certificate store is a set of preloaded root certificates that are on the device. The root certificate is invaluable because browsers automatically trust a certificate signed with a trusted root certificate. Trusted roots belong to Certification Authorities (e.g., Comodo, Thawte, Geotrust, GlobalSign, Symantec, etc.) - organizations that verify and issue SSL certificates.
- Intermediate Certificate - Certification Authorities (CAs) do not issue end-user SSL certificates directly from their Root Certificate. This would be risky because, in the case of improper issuance or an error, the Root Certificate would be revoked, and every issued certificate that was signed using that Root Certificate would immediately become "Untrusted".
Therefore, to protect themselves, CAs usually issue what is called an "Intermediate Certificate". The Certification Authority signs the Intermediate Certificate with its private key, which makes it "Trusted". The CA then uses the private key of the Intermediate Certificate to sign end-user SSL certificates. This process can be repeated several times, where an intermediate root signs another intermediate link, and then the CA uses this to sign the certificate.
- SSL Certificate - A unique certificate issued for the domain name of a web application.
Certificate Issuance
Depending on which certification authority will be used, the issuance process differs.
- "Certificates issued by widely accepted public certification authorities" - You can find any site on the internet (for example, reg.ru / firstssl.ru and countless others) that deals with the issuance of certificates from the required certification authority (for example, GlobalSign). Each site has a personal account/instructions on how to issue certificates.
- "Self-signed certificates" - Contact your company's IT department.
| Recommendation | Reason for recommendation |
|---|---|
| Buy certificates issued by a "commonly accepted public certification authority"
Reason for recommendation: The SmartPlayer platform is cross-platform, meaning client applications work on all operating systems (AndroidOS/WebOS/TizenOS/Windows/Linux/Raspberry Pi, etc.). This means that all operating systems must trust the certification authority that issued the certificates by default. Even if the current project only uses Android OS, it doesn't mean that the procurement department won't buy devices on TizenOS in a year. Use a certification authority trusted by the maximum number of device manufacturers. | |
| Buy certificates from GlobalSign
Reason for recommendation: A global certification authority trusted by all device manufacturers worldwide. The widest coverage of devices from manufacturers. SmartPlayer uses a certificate from this certification authority. For example, Samsung/LG - South Korea, BrightSign - UK, Android OS - countless different manufacturers, and they all trust GlobalSign. | |
| Do not use private certification authorities
Reason for recommendation: No device trusts private certification authorities. To launch https, you will need to add the certificate to the device's certificate store manually. And if there are more than 50 devices in the project? This already becomes a lot of routine manual work. The SmartPlayer platform does not yet support the loading of user certificates through the SmartPlayer personal account. This will be improved in the future, but there will not be a universal solution for all operating systems. There are manufacturer restrictions, for example, TizenOS does not provide an API for loading certificates as of May 30, 2024. Do not take unnecessary risks, use certificates from public certification authorities.
| |
| Which type of certificate to choose? | Reason for recommendation: Use DomainSSL (DV SSL). It is the cheapest and quickest to issue for ensuring work over the https protocol. |
Configuring the SmartPlayer Platform
To ensure the correct operation of the "https" protocol using SSL certificate(s), the following platform components need to be configured:
- The server application and the SmartPlayer personal account
- SmartPlayer client applications
By this point, you should have three certificates and a private key:
- Root SSL certificate, CA certificate (for example, in this guide we will call it: rootCA.crt)
- Intermediate certificate (for example, in this guide we will call it: intermediateCA.crt)
- SSL certificate (for example, in this guide we will call it: server-sp.crt)
- SSL private key (for example, in this guide we will call it: server-sp.key)
Configuring the SmartPlayer Server Application (and Personal Account)
Create a certificate chain from the "intermediate certificate" and the "SSL certificate" by combining them into one file. There are different ways to do this:
- Open any text editor and paste the content of the "intermediate certificate" file first, then paste the content of the "SSL certificate" file without any spaces from the next line. Save the resulting text document with the *.crt extension.
- When working in Linux, simply execute the command:
cat intermediateCA.crt server-sp.crt > server-sp-chain.crt
As a result, we have the file server-sp-chain.crt, which contains both certificates. If you open the file in a special certificate management program (https://keystore-explorer.org/), you will see the following hierarchical structure.
- Upload the certificate chain (server-sp-chain.crt) and the private key (server-sp.key) to the server using any convenient method. Commonly used programs for this include:
- WinScp - https://winscp.net/eng/
- FileZilla - https://filezilla-project.org/
- Sftp / scp - usually come with the operating system
- Find the path (if you don't know it) where the SmartPlayer platform is installed on the server, by default it is "/home/smartplayer/smartplayer"
- Move the files server-sp-chain.crt and server-sp.key to the certificate folder, by default this is "/home/smartplayer/smartplayer/nginx/ssl". By default, in the nginx configuration provided by SmartPlayer, the file names are: ssl.crt (certificate chain) and ssl_private.key (private key). Use these names for your files to avoid rewriting the nginx web server configuration files.
- Check the nginx configuration to ensure the files are accessible to the web server, by running the command:
docker exec -it smartplayer_web_1 shinside the containernginx -t. The output should be:
- Reload the nginx configuration by running the command:
docker exec -it smartplayer_web_1 shinside the containernginx -s reload - The installation of the certificate on the SmartPlayer server application is now complete. To verify, open the URL of the personal account or server application in the browser. If you used certificates issued by a "common public certification authority," you will immediately see a secure connection (green lock to the left of the address). If you used "self-signed certificates," you will see an insecure connection in the browser, as it does not trust the certificate.
Configuring SmartPlayer Client Applications
- If you used a certificate issued by a "public certification authority" from GlobalSign, adding certificates to the end devices is not necessary, and the HTTPS connection between the client application and the server application should immediately open. The client application will display a registration code upon first access.
- If you issued a certificate from a private certification authority, you need to add the rootCA.crt to the device's certificate store. Each operating system handles this differently; instructions can be found on the Internet. After adding the certificate, restart the device, and the HTTPS connection should open.
Separate instructions for operating systems on how to add custom certificates:
- Installing_Certificates_for_Android_OS
- TizenOS - does not support the installation of certificates issued by a private certification authority. You need to use certification authorities from the list
SSSP#Поддержка_HTTPS_(сертификаты)
Troubleshooting
Trust anchor for certification path not found
| Operating System | Cause of Error | Error Fix |
|---|---|---|
| Android OS | The device does not trust the certification authority that issued the certificate installed on the SmartPlayer server application | Add the root certificate of the certification authority to the user certificates on the device. General instructions Installing_Certificates_for_Android_OS. A device reboot may be required after installation, depending on the device firmware. |
| Android OS | The device does not trust the certification authority that issued the certificate installed on the SmartPlayer server application, but the certificate is installed in the device's certificate store | Update the client application to version v1.70.2 or higher |
Connection error ${server address} {"type":"TransportError", "description":{"isTrusted"}}
| Operating system | Cause of Error | Error Fix |
|---|---|---|
| WebOS | The device does not trust the certification authority that issued the certificate installed on the SmartPlayer server application | Add the root certificate of the certification authority to the user certificates on the device in the WebOS system menu. A device reboot may be required after installation, depending on the device firmware. |
| TizenOS | The device does not trust the certification authority that issued the certificate installed on the SmartPlayer server application | It is not possible to add the root certificate of the certification authority to the user certificates on the device. Issue the certificate with a certification authority that the device trusts by default. Use the certification authorities from the list SSSP#Support_HTTPS_(certificates). |
| BrightSignOS | The device does not trust the certification authority that issued the certificate installed on the SmartPlayer server application. | nstructions on how to import the root certificate into the device (not tested by us) can be found at: https://support.brightsign.biz/hc/en-us/articles/360024205233-How-do-I-display-a-webpage-that-requires-a-client-certificate. Access via VPN/Proxy, as it is not accessible from a Russian IP. |
Bad line при проверки конфигурации nginx
This error occurs when the certificate chain is created incorrectly, at the junction of certificates. Open the certificate chain file in any text editor (sublim/atom/editor/notepad++, etc.) and make a line break at the beginning of the next certificate. Incorrect
Correct
Test in the SmartPlayer Testing Infrastructure
SmartPlayer offers a testing environment where you can test the interaction between the SmartPlayer server application and client application over HTTPS with certificates issued by a private certification authority.
- Server application: https://self-certificate-api.smartplayer.org/
- Personal area: https://self-certificate.smartplayer.org/
When opening the URL in the browser, there will be a certificate error. The browser on your computer does not trust the private certification authority issued by SmartPlayer.
To make the browser trust the certificate signed by a private certification authority, add the root certificate to the browser's user certificate store. Each browser has its own section for this, but most often these settings can be found in the security section.
Download and add the certificate https://instructions.hb.ru-msk.vkcs.cloud/rootCA_sp_2024.crt
Added certificate to browser storage
Added certificate to browser storage
Restart the page
Server application
Personal area
Now it is clear that the browser trusts our certificate signed by the private certification authority. If you need to test any client application, request a build on the server https://self-certificate-api.smartplayer.org/ for testing from the company's manager.
Certificate Issuance by SmartPlayer Employees
SmartPlayer can issue a certificate for a project, but this requires the participation of the domain administrator for which the certificate will be issued. To start the certificate issuance process, you need to obtain the domain name for which the certificate needs to be issued (for example, api.smartplayer.org/cms.smartplayer.org).
| Step name | Description of actions | Responsible | |||
|---|---|---|---|---|---|
| Buy a GlobalSign certificate on the reg.ru website | Purchase a DomainSSL level certificate | SmartPlayer employee | |||
| Sending TXT record | A SmartPlayer employee will send the TXT record that needs to be added for the domain | SmartPlayer employee
- |
Adding a TXT record for the domain | Add the TXT record for the domain | Domain administrator (organization employee) |
| Creating a certificate chain | A certificate chain is created for installation on the server application | SmartPlayer employee | |||
| Sending the archive (root certificate, certificate chain, private key) | Sending the archive with certificate data | SmartPlayer employee |
- The cost of the service is approximately 3000 rubles (includes the purchase of the certificate). Post-payment. The cost may vary, please check with the sales department.
- The certificate will be valid for one year from the date of issuance.
If the server application and the personal account use the same domain, one certificate is sufficient. If different domains are used, two certificates need to be purchased.
Example of a single domain for the personal account and server application:
- https://develop.smartplayer.org - server application
- https://develop.smartplayer.org/cms/ - personal account
Example of two domains for the personal account and server application:
- https://api.smartplayer.org - серверное приложение
- https://cms.smartplayer.org - личный кабинет
This does not affect the operation of the applications in any way; you can choose any option for hosting the platform.
