Certificate Connection

Overview

Certificates are used to establish secure connections. In a test system, the certificate may be needed to connect to the web softphone system from a browser.

There are several cases:

  1. The master domain matches the public DNS name, and the DNS server associates it with the platform server address.

  2. The name of one of the system’s working domains is associated by the DNS server with the address of the platform server.

  3. The master domain matches the public DNS name, but the DNS server does not associate it with the platform server address.

  4. The names of all logical domains in the platform, starting with the master server, are local.

The main options for setting up cases 1 and 2:

  • Automatic certificate issuance using ACME service via servers LetsEncrypt.

  • Issuing a certificate manually or taking a ready-made certificate and connecting it to the system via configuration. The certificate will need to be renewed when it expires.

In this case, calls to the server must be made by public domain names, which are associated by the DNS server with the platform and for which a certificate is issued/loaded/configured.

Situation 3 is configured in the same way as situation 4, although it is possible to configure by loading an existing certificate and connecting it to the system through configuration.

Situation 4 can be configured by issuing a self-signed certificate for the domain name of the master domain and connecting it to the system through configuration. In this case on the local DNS or in the hosts file of client machines it is necessary to link the IP-address of the platform server with the name of the master domain. And in browsers you will have to add the name to security exceptions.

Two weeks before the current certificate expires, system_state monitoring will start signaling.

Procedure for application of certificates

  1. First, an attempt is made to apply the certificate by SNI.

  2. On failure, the certificate specified in the configuration in the 'certdir' parameter of the role (microservice instance) that serves this request is applied - ws or sg.

  3. Lastly, if the 'certdir' parameter is not set or incorrectly set 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’s 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, the 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 the parent domains up to the master domain, then the SNI certificate lookup stops.

If no domain matching the SNI name is found in the platform’s domain tree, all parent names are checked in turn with respect to the obtained SNI name. The master domain is checked last in any case. As above, if any of the domains found in the platform’s domain tree have the 'certificate_pem' parameter set, then its value is applied. Otherwise the certificate search by SNI is stopped.

Customization methods

1. ACME LetsEncrypt

Prerequisites:

  • In the domain tree, there is a domain whose name is known to public DNS servers and is associated with the public IP address of the server of the current platform instance, or the public IP address of the local router.

  • The server has access to the internet.

  • Access from the Internet by domain name to port 80 via http is not blocked by routers and firewalls and is routed to the platform server.

  • The addressed server contains a WS microservice that listens on port 80 (or other if the router performs port spoofing).

In the matching domain, you need to set acme_account_email and enable the option in the settings acme_enabled.

After a while, the PEM content of the generated certificate will appear in the certificate_pem option. There will be a few special fields in the header indicating that the certificate was automatically issued.

In the future, when accessing by domain name, the platform will use the certificate of the current domain.

The certificate is issued for a period of 3 months and the system starts to automatically renew it after 2 months.

Certificate issuance is provided by the mware microservice, and therefore information about the update process and possible failures is placed in its log.

2. Downloading a ready certificate to disk and connection via configuration

  1. Generate server.key files from the existing certificates and server.crt.

  2. Place them on disk in a location 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, in the host depending on the paths selected during installation, the default is /opt/era/syncroot/common/cert). It is not available from the API, and is automatically synchronized between all servers of the platform, which makes it possible to copy it to one server and use it on any server of the system.

  3. Make sure that the configuration file has an appropriate alias in the aliases section that points to the folder you are using within the container. For example, for the path suggested in step 2:

    {
  "alias": "default_certdir",
  "value": "/var/lib/era_files/syncroot/common/cert"
}

  4. Set all instances of microservices WS and SG to the configuration option to use a certificate from the config pointing to the alias created earlier. For example:

      "certdir": "alias://paths/default_certdir"

  5. Activate the modified configuration.

A certificate loaded into the domain in the certificate_pem field takes precedence over a certificate installed through configuration when accessing the server through that domain name.

3. Uploading a ready certificate to the domain

The merged content needs to be generated: First the key, then the certificate, then the certificate chain (if any). In the domain whose name matches the domain name of the certificate, you should paste the contents of the certificate into the option certificate_pem.

Sample 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-----

The heading before each section may or may not contain meta-information, such as:

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=era-platform.ru
issuer=/C=US/O=Let's Encrypt/CN=R3

If you have several files, for example domain.key, domain.crt, ca.pem, then to generate the required value, you need to chain them in the following order: first the private key, then the certificate itself, and then the certificate chain (ca).

If an automatic checkout was previously performed, it will cease for a particular domain after a manual change on the grounds that there is no automatic checkout indication in the header.

The certificate loaded into the domain in the certificate_pem field takes precedence over a certificate installed through configuration when accessing the server through that domain name. Even if it is incorrect or expired.

If the server is accessed by domain name, if this domain exists among the platform domains and there is no certificate installed in the domain in the certificate_pem field, it is searched in the parent domain up to the master.

If an installed certificate_pem certificate is found anywhere in the parent domains, it is applied.

If none of the parent domains has a certificate set in the certificate_pem field, then the certificate from the configuration is applied.

Therefore, if you plan to refer to child domains by their names in the URL, you should:

  • or install custom certificates for each of these domains;

  • or in the parent domain add support for all such child domains in the field acme_subdomains;

  • or use a wildcard certificate that covers all such child domains and upload it to the master domain or one of the root domains;

  • or use a wildcard certificate that covers all such child domains, and use it via a configuration setting.

4. Issuance of self-signed certificate for local domain name

Command to issue a certificate using the utility openssl:

openssl req -newkey rsa:2048 -nodes -keyout server.key -x509 -days 1095 -out server.crt

The command execution will require you to enter the target domain name. This is mostly the name of the master domain.

The command results in the files server.key and server.crt

If it is planned to load them to disk, their names should be exactly the following: server.key, server.crt, because the configuration only sets the directory where these files are located.

If you plan to set them in the domain parameter certificate_pem, you should form a merged body: first the contents of server.key, then the contents of the server.crt.

When using a local name, you must ensure that it is associated with the server IP address on client machines:

  • or through a file hosts (linux: /etc/hosts, windows: windows/system32/drivers/etc/hosts),

  • or through a local DNS server.
When using a self-signed certificate, you must add the domain name to security exceptions in browsers.
  • Personalization
  • Increase font size
  • Decrease font size