Customizing HTTPS on REST API

The BigFix root server is configured to use HTTPS by default when it gets installed and creates its own certificate during the installation. If you want to replace it, you need to configure HTTPS manually.

First steps

If you have a trusted SSL security certificate and key from a certificate authority, you can configure the BigFix root server to use this certificate and key to enable trusted connections. You can also use a self-signed certificate.

When you have a trusted SSL certificate, copy the .pvk (if you have one) and the .pem files on the computer running the BigFix root server.

In the following sections, we show ways to implement these macro-steps:

  • Specify that you are using a secure communication.
  • Specify where the SSL certificate and private key files are located.
  • Restart the relevant services.

After you have completed the configurations described in the following sections, the connections from the Rest API and the BigFix Console use this trusted certificate.

Customizing HTTPS using the BigFix Console

  1. From the BigFix console select the Computers tab.
  2. Select the computer running Rest API (usually the server) and Edit Computer Settings from the Edit menu.
  3. Look for _BESRelay_HTTPServer_UseSSLFlag setting. If it exists, do not create a second one, but edit its value to 1 to enable HTTPS. If it does not exist, add it:

  4. If you combined the private key file with the certificate file, skip this step and set only the _BESRelay_HTTPServer_SSLCertificateFilePath.

    Look for _BESRelay_HTTPServer_SSLPrivateKeyFilePath setting. If it exists, do not create a second one, but edit its value to the full path name of the private key (.pvk file which contains the private key for the server). The private key must not have a password. If this setting does not exist, add it.

  5. Look for _BESRelay_HTTPServer_SSLCertificateFilePath setting. If it exists, do not create a second one, but edit its value to the full path name of the .pem file which might contain both the certificate and private key for the server, or only the certificate. If this setting does not exist, add it:

    Ensure that the .pem file is in standard OpenSSL PKCS7 .pem file format.

    The certificate is supplied by the server to connecting clients and they present a dialog to the user containing information from the certificate. If the certificate meets all of the trust requirements of the connecting client, then the client connects without any interventions by the user. If the certificate does not meet the trust requirements of the client, then the user will be prompted with a dialog asking them if it is OK to proceed with the connection, and giving them access to information about the certificate. A trusted certificate is signed by a trusted authority (such as Verisign), contains the correct host name, and is not expired.

  6. To require TLS 1.3, look for _BESRelay_HTTPServer_RequireTLS13 If it exists, do not create a second one, but edit its value to 1 .
    Note: The REST API component always uses the higher and most secure version available of TLS when communicating with the BigFix server, (regardless of local settings or settings of the masthead).
  7. Restart the BES Root Server service:
    • On Windows, open Services, select BES Root Server and on the Action menu, click Restart.
    • On Linux run from the prompt: systemctl restart besserver

      Up to BigFix Version 11.0.1, for backward compatibility reasons, you can also run the command:

      /etc/init.d/besserver restart
  8. To restore the connection between the BES Root Server and Web Reports, from Web Reports edit the datasource settings for the datasource whose certificate was modified as follows:
    1. Select Administration > Datasource Settings > Edit.
    2. Enter the password in the appropriate field and submit the form to exchange the certificate and accept the request warning.
Note: These settings are stored in the registry under the key HKLM/Software/WoW6432Node/BigFix/EnterpriseClient/Settings/Client

Customizing HTTPS manually

If you have a trusted SSL security and a key from a certificate authority (.pem file), you can configure the computer running REST API (usually the server) to customize trusted connections.

On Windows systems

To customize HTTPS manually on Windows systems, complete the following steps:

  1. Run regedit and locate HKEY_LOCAL_MACHINE\Software\Wow6432Node\BigFix\EnterpriseClient\Settings\Client

    You need to add or modify subkeys for the HTTPS flag, and for the location of the SSL certificate.

  2. Create a subkey of Client called _BESRelay_HTTPServer_UseSSLFlag (if it does not exist yet). Add a string value (reg_sz) called "value" to the key and set it to 1 to enable HTTPS.
  3. Important: If you combined the private key file with the certificate file, move to step 4.

    Create a subkey of Client called _BESRelay_HTTPServer_SSLPrivateKeyFilePath (if it does not exist yet). Add a string value (reg_sz) called "value" to the key and set it to the full path name of the private key (.pvk file which contains the private key for the server).
  4. Create a subkey of Client called _BESRelay_HTTPServer_SSLCertificateFilePath (if it does not exist yet). Add a string value (reg_sz) called "value" to the key and set it to the full path name of the SSL certificate (cert.pem).
  5. To require TLS 1.3: Create a subkey of Client called _BESRelay_HTTPServer_RequireTLS13 (if it does not exist yet). Add a string value (reg_sz) called "value" to the key and set it to 1 to enable TLS 1.3.

  6. Restart the BES Root Server service.
  7. To restore the connection between the BES Root Server and Web Reports, from Web Reports edit the datasource settings for the datasource whose certificate was modified as follows:
    1. Select Administration > Datasource Settings > Edit.
    2. Enter the password in the appropriate field and submit the form to exchange the certificate and accept the request warning.

On Linux systems

To customize HTTPS manually on Linux systems, complete the following steps:

Save the files cert.pem and pvtkey.pvk (if you have it) in a protected area of the file system, where it can be accessed by the BigFix besserver process, for example, /etc/opt/BESServer/.

Edit the /var/opt/BESServer/besserver.config file, by adding the following entries.

Important: If you combined the private key file with the certificate file, skip these settings.
[Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_SSLPrivateKeyFilePath]
value = /etc/opt/BESServer/pvtkey.pvk
[Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_SSLCertificateFilePath]
value = /etc/opt/BESServer/cert.pem
To enable HTTPS:
[Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_UseSSLFlag]
value = 1
To require TLS 1.3:
[Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_RequireTLS13]
value = 1

Stop and restart the BigFix root server.

To restore the connection between the BES Root Server and Web Reports:

From Web Reports, edit the datasource settings for the datasource whose certificate was modified as follows:
  1. Select Administration > Datasource Settings > Edit.
  2. Enter the password in the appropriate field and submit the form to exchange the certificate and accept the request warning.