Connecting a certificate
Overview
Certificates are used to establish secure connections. In a test system a certificate may be needed to connect to the web softphone system from a browser.
There are several cases:
-
The master domain matches a public DNS name, and the DNS server binds it to the platform server address.
-
The name of one of the system working domains is bound by the DNS server to the platform server address.
-
The master domain matches a public DNS name, but the DNS server does not bind it to the platform server address.
-
The names of all platform logical domains, starting from the master server, are local.
Main configuration options for cases 1 and 2:
-
Automatic certificate issuance using the ACME service via LetsEncrypt servers.
-
Manual certificate issuance or taking a ready certificate and connecting it to the system via the configuration. The certificate will need to be renewed when it expires.
Requests to the server must be made using public domain names that are bound by the DNS server to the platform and for which the certificate is issued/loaded/configured.
Situation 3 is configured the same way as situation 4, although it may be configured by loading an existing certificate and connecting it to the system via the configuration.
Situation 4 can be configured by issuing a self-signed certificate for the master domain name and connecting it to the system via the configuration. On the local DNS or in the hosts file of client machines, the platform server IP address must be associated with the master domain name. And in browsers the name will have to be added to security exceptions.
| Two weeks before the current certificate expires, system health monitoring starts signaling. |
Certificate application procedure
-
First an attempt is made to apply the certificate by SNI.
-
If unsuccessful, the certificate specified in the configuration in the 'certdir' parameter of the role (microservice instance) serving this request — ws or sg — is applied.
-
Last, if the 'certdir' parameter is not set or set incorrectly in the configuration, the default certificate supplied with the platform is applied.
SNI
If a domain matching the SNI name is found in the platform domain tree and the 'certificate_pem' parameter is set in it, its value is applied.
If the 'certificate_pem' parameter is not set in the domain found by SNI, a search is performed in the parent domain, and so on up to the master domain.
If the 'certificate_pem' parameter is not set anywhere in parent domains up to the master domain, the certificate search by SNI stops.
If no domain matching the SNI name is found in the platform domain tree, all parent names relative to the received SNI name are checked in turn. The master domain is always checked last. As above, if the 'certificate_pem' parameter is set in any of the domains found in the platform domain tree, its value is applied. Otherwise the certificate search by SNI stops.
Configuration methods
1. ACME LetsEncrypt
Prerequisites:
-
The domain tree contains a domain whose name is known to public DNS servers and is bound to the public IP address of the current platform instance server or to the public IP address of the local router.
-
The server has internet access.
-
A request from the internet by domain name to port 80 over http is not blocked by routers and firewalls and is routed to the platform server.
-
The addressed server contains the WS microservice listening on port 80 (or another port if the router performs port substitution).
In a suitable domain, set the acme_account_email option in the settings and enable the acme_enabled option.
After some time the certificate_pem option will contain the PEM content of the generated certificate. The header will contain several special fields indicating automatic issuance.
Subsequently, when accessed by the domain name, the platform will use the current domain certificate.
The certificate is issued for 3 months, and the system starts automatic renewal after 2 months.
| Certificate issuance is provided by the mware microservice, so information about the renewal process and possible failures is placed in its log journal. |
2. Uploading a ready certificate to disk and connecting via configuration
-
Form server.key and server.crt files from the available certificates.
-
Place them on disk where they will be safe and secure. For example, the syncroot/common/cert directory (inside the container it is /var/lib/era_files/syncroot/common/cert; on the host depending on the paths chosen at installation, by default /opt/era/syncroot/common/cert). It is inaccessible from the API and automatically synchronized between all platform servers, which makes it possible to copy it to one server and use it on any server of the system.
-
Make sure the configuration file has an alias in the aliases section pointing to the folder you use inside the container. For example, for the path suggested in item 2:
{ "alias": "default_certdir", "value": "/var/lib/era_files/syncroot/common/cert" } -
Set for all WS and SG microservice instances the configuration option for using the certificate from the config, pointing to the alias created earlier. For example:
"certdir": "alias://paths/default_certdir"
-
Activate the modified configuration.
| A certificate loaded into the domain in the certificate_pem field takes priority over a certificate set via the configuration when accessing the server through this domain name. |
3. Uploading a ready certificate to the domain
A combined content must be formed: First the key, then the certificate, then the certificate chain (if present). In the domain whose name matches the certificate domain name, insert the certificate content into the certificate_pem option.
Example content:
date=2023-11-29 -----BEGIN RSA PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCczvGDUx8MMwnj v+CUjlyDRZ9pbI7veOTWgq/mj+f+aw6zHyjERIGv7x9lFTF/zoPSUxf4CxHiPjid ... N7oVoQ2dzIe9rjkLPrwKf+o3QfMnsotrE773dc67om2ynrY2fJIoa5TzVEtcB6A0 2+XrTNfre/PEPz3+uL2WCVja -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIIE6zCCA9OgAwIBAgISBPPhdaDZBu7SUParH1/Pb1QqMA0GCSqGSIb3DQEBCwUA MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD ... SKDVqkLi0yhp3LpS0OYRMrQddVtxS4tqInxGSt0CvIK5xeOB3abY5ShW0JYYUARz YR7I9fkBPg4p+b9KxrfG -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIFFjCCAv6gAwIBAgIRAJErCErPDBinU/bWLiWnX1owDQYJKoZIhvcNAQELBQAw TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh ... MldlTTKB3zhThV1+XWYp6rjd5JW1zbVWEkLNxE7GJThEUG3szgBVGP7pSWTUTsqX nLRbwHOoq7hHwg== -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIFYDCCBEigAwIBAgIQQAF3ITfU6UK47naqPGQKtzANBgkqhkiG9w0BAQsFADA/ MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT ... he8Y4IWS6wY7bCkjCWDcRQJMEhg76fsO3txE+FiYruq9RUWhiF1myv4Q6W+CyBFC Dfvp7OOGAN6dEOM4+qR9sdjoSYKEBpsr6GtPAQw4dy753ec5 -----END CERTIFICATE-----
Before each section the header may or may not contain meta-information, for example:
Bag Attributes
localKeyID: 01 00 00 00
1.3.6.1.4.1.311.17.3.20: 9E D3 D5 AE 59 ED 75 B8 B7 87 6D 7F 60 46 23 F4 01 BA E7 AA
friendlyName: [IIS] era, (any host) @ 2021.4.6 21:29:54
subject=/CN=incoplax.com
issuer=/C=US/O=Let's Encrypt/CN=R3
If you have several files, for example domain.key, domain.crt, ca.pem, then to form the required value they must be concatenated in the following order: first the private key (key), then the certificate itself, then the certificate chain (ca).
If automatic issuance was performed previously, after manual modification it will stop for the specific domain because the header will lack the automatic issuance marker.
| A certificate loaded into the domain in the certificate_pem field takes priority over a certificate set via the configuration when accessing the server through this domain name. Even if it is incorrect or expired. |
|
When accessing the server by domain name, if this domain exists among platform domains and the domain has no certificate set in the certificate_pem field, a search is performed in the parent domain up to the master. If a certificate is found set in certificate_pem in any parent domain, it is applied. If no parent domain has a certificate set in the certificate_pem field, the certificate from the configuration is applied. Therefore, if you plan to access child domains by their names in URLs, you should:
|
4. Issuing a self-signed certificate for a local domain name
Command to issue a certificate using the openssl utility:
openssl req -newkey rsa:2048 -nodes -keyout server.key -x509 -days 1095 -out server.crt
During command execution the target domain name must be entered. Mainly this is the master domain name.
As a result of the command, server.key and server.crt files appear.
If they are planned to be loaded to disk, their names must be exactly server.key, server.crt, since the configuration sets only the directory where these files are placed.
If they are planned to be installed in the domain parameter certificate_pem, a combined body must be formed: first the server.key content, then the server.crt content.
|
When using a local name, its binding to the server IP address must be ensured on client machines:
|
| When using a self-signed certificate, the domain name must be added to security exceptions in browsers. |
Root certificates
Certificates are signed with keys of trusted centers. Root certificates reside in the client system and are used to validate the entire signature chain of the server certificate when establishing a secure connection.
When the platform acts as a secure connection client, it also validates the chain for trust. In some cases, when connecting to internal services, it may be necessary to add the server certificate or a trusted root certificate of an internal certificate authority to the system. Without this the secure connection will not be established.
By default the platform container contains root certificates of well-known centers. (/etc/ssl/certs).
Additional root certificates can be loaded in the standard way into the container directory (of each server for a multi-server system):
/usr/local/share/ca-certificates
and run the command
update-ca-certificates
Public root certificates reside in system directories depending on the Linux builds used. The Debian-based platform container loads public root certificates from the file "/etc/ssl/certs/ca-certificates.crt". This is exactly where certificates are added after running the "update-ca-certificates" command.
After the platform or a specific node is restarted, the added certificates are applied.
They can be applied without a restart by executing the API method: RELOAD /rest/v1/master/logicalroles/all/cacerts.
Another way is to place trusted certificates in the directory synchronized between servers :SYNC/common/cacerts.
First, this directory is available on the host of each server as a container volume.
Second, this directory is synchronized between all platform servers, so it is enough to change its content on any one server.
The composition of root certificates in the :SYNC/common/cacerts folder can be managed, among other ways, with the master domain REST API: /rest/v1/fs/targets/cacerts.
After changing the composition, either execute the API method (RELOAD /rest/v1/master/logicalroles/all/cacerts) or restart the required nodes or the whole system.
In some services trusted certificates are connected directly where used — oauth providers, telephony providers, LDAPS, sber-salute ASR/TTS services. Each of these entities can explicitly contain a trusted certificate chain for validating a specific service without the need to add trusted certificates to disk in the shared platform directory.