Customizing HTTPS on REST API

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.

After you have completed the configuration, connections from the REST API and console use this trusted certificate.

Complete the steps to accomplish the following tasks:

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

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 TLS12, look for _BESRelay_HTTPServer_RequireTLS12. If it exists, do not create a second one, but edit its value to 1 .
    Note: The REST API component always uses TLS 1.2 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: service besserver restart or /etc/init.d/besserver restart.
Note: These settings are stored in the registry under the key HKLM/Software/WoW6432Node/BigFix/EnterpriseClient/Settings/Client

Customizing HTTPS manually on Windows systems

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.

After you have completed the configuration, connections from the Rest API and console use this trusted certificate. 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 (it might already exist).
  3. Create a string value (reg_sz) for the key _BESRelay_HTTPServer_UseSSLFlag called value and set it to 1 to enable HTTPS.
  4. Important: If you combined the private key file with the certificate file, move to step 6.

    Create a subkey of Client called _BESRelay_HTTPServer_SSLPrivateKeyFilePath (it might already exist).
  5. Create a string value (reg_sz) for the key _BESRelay_HTTPServer_SSLPrivateKeyFilePath called value and set it to the full path name of the private key (.pvk file which contains the private key for the server).
  6. Create a subkey of Client called _BESRelay_HTTPServer_SSLCertificateFilePath (it might already exist).
  7. Create a string value (reg_sz) for the key _BESRelay_HTTPServer_SSLCertificateFilePath called value and set it to the full path name of the SSL certificate (cert.pem).
  8. To require TLS 1.2:

    Create a subkey of Client called _BESRelay_HTTPServer_RequireTLS12 (it might already exist).
  9. Create a string value (reg_sz) for the key _BESRelay_HTTPServer_RequireTLS12 called value and set it to 1 to enable TLS 1.2.
  10. Restart the BES Root Server service.

Customizing HTTPS manually on Linux systems

If you have a trusted SSL security certificate and key from a certificate authority (.pem file), you can configure the BigFix root server to use this certificate and key to enable trusted connections. After you have completed the configuration, connections from the REST API and console use this trusted certificate.

This procedure describes how you can configure the BigFix root server on Linux systems to use a certificate to enable trusted connections through the REST API and BigFix Console.

  1. Save the files cert.pem and pvtkey.pvk in a protected area of the file system, where it can be accessed by the BigFix besserver process, for example, /etc/opt/BESServer/
  2. Edit the /var/opt/BESServer/besserver.config file, by adding the following entries:
    [Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_UseSSLFlag]
    value = 1
    
    Important: If you combined the private key file with the certificate file, skip this setting
    [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 require TLS 1.2:
    [Software\BigFix\EnterpriseClient\Settings\Client\_BESRelay_HTTPServer_RequireTLS12]
    value = 1
  3. Stop and restart the BigFix root server.