DEX Platform client requirements

Implementation overview

1. If a valid client certificate is unavailable, the 1E Client generates a Certificate Signing Request (CSR) containing all the relevant information identifying the device. This includes the machine FQDN, the GUID and several certificate extensions unique to the 1E Client.

2. The CSR is signed using an RSA key pair and the associated private key is stored locally in the machine store.

3. The signed CSR is sent to the Platform certificate provisioning service which validates the request, processes the CSR and sends back a BASE64 encoded certificate.

4. The request is authenticated using an authorization header in form of a signed-JWT.

5. A shared secret between the Platform and the 1E Client called the Provisioning Key is employed for JWT signing.

6. The returned certificate is associated with the locally stored private key and pushed to the machine certificate store.

   The custom certificate store created by 1E Client can be used for certificate look-up and provisioning. Refer to DedicatedClientCertificateStore.

   This certificate is then used for the mutual TLS handshake to establish a secure communication channel between the 1E Client and the platform.

How certificate management works

In addition to generating CSRs, the 1E Client is responsible for managing of all the certificates and private keys provisioned by it, including the following activities:

1. Check if the device already has a valid 1E provisioned client certificate in the certificate store. If not, the provisioning process starts.

   • Windows and macOS: we count through all the certificates in the certificate store checking for valid certificates.

   • Linux: We only check for the presence of a client certificate file named Tachyon.pfx file in the SSL certificate directory and none of the following checks are carried out.

   A certificate is marked as valid on Windows and macOS if it passes the following checks.

   • Certificate contains the custom 1E OID extensions

   • Certificate has not expired

   • Certificate will not have expired closer than a configurable threshold

   • Certificate contains the Client Authentication EKU extension

   • Certificate subject covers the machine FQDN

   • Certificate has a usable private key

2. Provision a new client certificate from the cloud service if required. This request is only generated if a client certificate has not been requested in the last 24 hours (this is the default), this setting is configurable.

3. Perform housekeeping activities every 1E Client start-up on the provisioned items, including cleaning up:

   • Expired certificates

   • Certificates without a usable private key

   • Orphaned (no associated private key) certificates

   • Orphaned private keys (no associated certificate)

   • Certificates whose provisioning key hash OID (1.2.5.1.4.1.61249.4) value does not match the currently stored provisioning key’s hash

   • On Linux, we also clean up the provisioned certificate whose subject does not cover the current machine FQDN

4. Periodically check when running whether a new client certificate request is needed, if the one that is in use nears expiry. This happens, by default, every 8 hours on a background thread and can be controlled using this configuration setting:

   ClientCertificateProvisioning.AutoRenewalCheckHours

Configuration

For settings that control the behavior of the platform provisioning service refer to 1E Client settings. The certificate provisioning feature is enabled by default.

Provisioning Key installation using a command-line

The provisioning key is a shared secret between the Platform provisioning service and the 1E Client used to generate a signed JWT using the HS256 algorithm. To use the Platform provisioning service a valid key must be stored in the client's persistent storage as follows.

During install

• Windows: Pass the plain text provisioning key copied from the platform to MSIEXEC.

  Copy

  msiexec /i 1E.Client-x64.msi ^
    SWITCH=<SWITCH_URL> ^
    BACKGROUNDCHANNELURL=<BGC_URL> ^
    PROVISIONINGKEY=<VALID_PROVISIONING_KEY> ^
    /qn ^
    /l*vx 1EClient-install.log
  

• macOS: Pass the plain text provisioning key copied from the platform to the install.sh script bundled in the published .dmg file. This will store the provisioning key directly in persistent storage.

  Copy

  sudo sh install.sh \
    SWITCH=<SWITCH_URL> \
    BACKGROUNDCHANNELURL=<BGC_URL> \
    PROVISIONINGKEY=<VALID_PROVISIONING_KEY>

• Linux: The plain-text provisioning key copied from the platform to the installer command line. Make sure the parameter is all upper-case as PROVISIONINGKEY otherwise the installer will not be able to recognize the plain-text value. This must remain identical as the platform. This will store the provisioning key directly in persistent storage.

  For openSUSE / Red Hat EL / SUSE:

  Copy

  sudo \
    SWITCH=<SWITCH_URL> \
    BACKGROUNDCHANNELURL=<BGC_URL> \
    PROVISIONINGKEY=<VALID_PROVISIONING_KEY> \
    rpm -i 1e.client-RHEL_9_x64_v24.11.0.39.rpm
  

  For Ubuntu:

  Copy

  sudo \
    SWITCH=<SWITCH_URL> \
    BACKGROUNDCHANNELURL=<BGC_URL> \
    PROVISIONINGKEY=<VALID_PROVISIONING_KEY> \
    dpkg -i 1e.client-Ubuntu_18.04_x64_v24.11.0.39.deb
  

  On Linux, you need to place the cacert.pem file (root CA certificate for the Platform) in the certificate directory before starting the 1E Client. This file is necessary for authenticating the certificate signing request’s response and for platform connectivity once a client certificate is acquired. The root CA certificate can be obtained from TeamViewer DEX Support and includes the public certificates from the Platform Switch and Background Channel.

Post install

You can set the provisioning key as a post installation step, this is important when you revoke a key.

• Windows: Using an administrative console.

  Copy

  cd "C:\Program Files\1E\Client" 
  .\1E.Client.exe -ProvisioningKey=<VALID_PROVISIONING_KEY>

• macOS:

  Copy

  cd "Applications/1E Client.app/Contents/MacOS"
  sudo ./1E\ Client -ProvisioningKey=<VALID_PROVISIONING_KEY>

• Linux:

  Copy

  cd /usr/sbin
  sudo ./1E.Client -ProvisioningKey=<VALID_PROVISIONING_KEY>

1E features require a PKI and certificates on client devices and servers. Please see below for client requirements, and Certificate requirements for server requirements. You need to have a PKI in your environment with at least one Issuing CA.

1E requires each Issuing CA has:

• A Certificate Revocation List (CRL) Distribution Point (CDP) that uses HTTP/S.

• This HTTP/S CDP information is included in certificates issued to 1E Server and client devices.

If you have an existing PKI and have just added a new CDP to support HTTP/S then you will need to re-issue certificates to your servers and devices.

• 1E deliberately does not work with self-signed certificates for security reasons. Therefore, 1E client or Server cannot be installed on the same server as a Root CA, because its certificate is self-signed.

• 1E uses TLSv1.2. If your PKI is using SHA512, then ensure that your environment has relevant updates applied, as described in SHA512 is disabled in Windows when you use TLS 1.2.

• If you want 1E to manage legacy OS that Microsoft no longer supports, there may be issues with encrypted certificates described in Common client requirements.

Client Certificates

If you have configured 1E Server to require client certificates, each device requires a certificate with the following properties, so the Platform client can be authenticated by the 1E Switch. Refer to Certificate requirements.

• All 1E Client certificate requests get routed to a special .client.platformURL, for example acme.client.uk.cloud.1e.com.

• The 1E Client has a setting which skips the local trust chain check during the client certificate selection process. Previously, client certificates needed to be trusted locally to be viable for presentation to the Switch. The default setting is true: SkipLocalTrustCheckForClientCertificates

• The 1E Client requires that the client certificate it presents to the platform has both the Signature and Encryption request handling options. These options are the defaults if provisioning using a Computer Certificate template from a Microsoft Windows Certificate Authority. If you are using a custom template, or an alternative certificate authority, you should confirm that both these options are enabled.

  

Client certificate properties:

• Issued by a trusted Certificate Authority (CA):

  • The certificate for the Root CA in the Certification Path must exist in the Trusted Root CA store of the client.

  • If the issuing CA is not the Root CA then the certificate for the issuing CA and any intermediate CA in the Certification Path must exist in the Intermediate CA store of the client.

  • If either of these CA certificates is different from those used by the 1E Web Server, they will need to be exported and imported on the 1E Web Server.

  • Most organizations have automated distribution of these CA certificates to clients and servers, using Group Policy for example.

• Enhanced Key Usage - has at least Client Authentication.

• Key Usage - has at least Digital Signature and Key encipherment.

• Private key - for workgroup and non-Windows devices, the private key must be exportable.

• Revocation information is included - references at least one CRL Distribution point that uses HTTP.

  • Has a Subject Name of type Common Name (CN=<computername>) or Subject Alternative Name (DNS Name=<computername>) where <computername> depends on the type of device:

  • On domain-joined Windows PCs this must be the computername FQDN of the computer, for example W701.ACME.LOCAL

  • On workgroup Windows PCs and non-Windows devices, this must be the computername of the computer - as returned by the hostname command, for example on Windows PC this could be W701, and on a Mac this could be MAC01.local.

  1E clients and Switches use OpenSSL and its validation process to verify certificates.

Certificate storage requirements by OS type:

• Windows devices: The certificate is stored in the Windows Local Computer personal certificates store.

• Non-Windows devices - except for the Mac: The client does not use proprietary certificate stores. Instead, the client requires the certificate to exist as a .pfx file in the client installation folder structure, refer to Client certificates in Deploying 1E Client on Linux.

• MacOS: You have a choice of storing the client certificate in the macOS Key Store or using the .pfx file approach required by other non-Windows devices, refer to Certificate files in Deploying 1E Client on macOS.

Considerations when requesting your certificate:

• The certificate can be used only on the server it was intended, that has the correct computername FQDN and DNS Alias FQDN.

• It is not possible to use the Create Certificate Request method in IIS Manager Server Certificates, because it does not support all the above requirements.

• If you have a Microsoft CA, and a suitable Web Server template has been issued and enabled in the Directory Enrollment Policy, then it is possible to Request New Certificate in the Certificates (Local Computer) mmc snap-in and use the Certificate Enrollment wizard.

• Many organizations have their own process for submitting a Certificate Signing Request (CSR). Ensure all the above requirements are specified. Security administrators sometimes have difficulty providing a certificate with one or more Subject Alternative Names (SAN), and it helps to explain these are type DNS.

Anonymous Client Certificates

• Are available on all supported platforms (Windows, macOS and Linux) when ClientCertificateSelection is set to anonymous

• Provide greater flexibility to you when you deploy client authentication certificates, because you can instruct the 1E Client to select any valid and locally-trusted client certificate, ignoring FQDN matches

To enable this feature, set the ClientCertificateSelection configuration setting to anonymous. The trusted anonymous certificates are marked as viable, but client certificates which pass FQDN checks are still prioritised while attempting a Switch connection.

If the 1E Client presents an anonymous client certificate, this will be visible in the 1E Portal device pillar as shown.