Communication

Any combination of X.509 certificates can be used to secure and authenticate communication between the Snow Inventory Agent and the Snow Inventory endpoint, that is, a Snow Extender or a Snow Inventory Server.

Endpoint certificates

If the endpoint certificate has been issued by a trusted root certificate authority (CA), the only required configurations on the agent side are to configure the agent to use the HTTPS or HTTP URI scheme and, for the Linux agent, to specify the path to the root certificate, as described in Communication using TLS.

Self-signed or self-issued certificates

If the endpoint uses a self-signed certificate for TLS, it is best practice to ensure that the root CA for the self-signed certificate is present and available to the agent so that certificate verification can be performed. For the Linux agent, the path to the root certificate must be specified, as described in Communication using TLS.

If no trusted root CA is present on the client machine, and therefore no certificate verification can be performed, you must disable the validation check. This is however insecure and strongly discouraged.

To disable the validation check, set http.ssl_verify in the agent configuration file to false:

<SystemSettings>
    <Setting key="http.ssl_verify" value="false" />
</SystemSettings>

Client certificates

Snow Inventory Agent supports the use of client certificates when establishing a connection with a Snow Inventory endpoint.

note

The endpoint must be a Snow Inventory Server. The Snow Extender does not support client certificates.

A common practice is to distribute the client certificate alongside the agent as part of the update package. The agent is then configured to look for a certificate.pfx file that contains the client certificate for client authentication and use that, provided it has the correct password.

To configure the use of client certificates, use the ClientCertificate element in the agent configuration file:

EXAMPLE

<Server>
    <Endpoint>
      <ClientCertificate>
          <FileName>certificate.pfx</FileName>
          <Password>encryptedpassword</Password>
      </ClientCertificate>
    </Endpoint>
</Server>

The password must be stored encrypted in the agent configuration file. For information on how to encrypt passwords, see Password encryption.

If the endpoint is used with a client certificate and the password does not match, an error is generated in the snowagent.log file. If several endpoints have been configured, the agent will randomly select another one from the list and continue trying to negotiate a connection.

note

Specify one client certificate per endpoint. You can add multiple entries for the same endpoint with different client certificates.

Public key pinning

Public key pinning prevents man-in-the-middle attacks from occurring on the communication link between the agent and the Snow Inventory endpoint. It is recommended to enable the public key pinning feature by default to ensure security of data in transit and fully mitigate potential man-in-the-middle attacks.

During initial communication establishment between an agent and an endpoint, the agent checks whether the encoded hash key of the endpoint matches the expected key, stored as a hash value in the agent configuration file. If the values match, communication is established. Otherwise, communication is dropped.

To enable public key pinning, you must extract the public key from the endpoint’s certificate and hash and encode it using SHA 256 and Base64, and then add the encoded key to the agent configuration file, as described in the steps below. In the commands, replace DNS_OF_YOUR_SERVER with the DNS of your inventory server.

1. Open a communication link with the endpoint and extract the certificate:

   openssl s_client -servername DNS_OF_YOUR_SERVER -connect DNS_OF_YOUR_SERVER:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > DNS_OF_YOUR_SERVER.pem

   note

   For Windows, use NUL instead of /dev/null.

   Instead of using sed -n to extract the certificate, you can copy the certificate from the command output and paste it into a file. The lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- must be included.

2. Extract the public key from the endpoint certificate file you created in the previous step:

   openssl x509 -in DNS_OF_YOUR_SERVER.pem -pubkey -noout > DNS_OF_YOUR_SERVER.pubkey.pem

3. Convert the public key from pem to der format:

   openssl asn1parse -noout -inform pem -in DNS_OF_YOUR_SERVER.pubkey.pem -out DNS_OF_YOUR_SERVER.pubkey.der

4. SHA 256 hash and base-64 encode the key:

   openssl dgst -sha256 -binary DNS_OF_YOUR_SERVER.pubkey.der | openssl base64

5. Add the encoded key, preceded by sha256//, to snowagent.config:

   <Server>
       <Endpoint>
          <ServerPublicKeyHash>sha256//<---encoded key ---></ServerPublicKeyHash>
       </Endpoint>
   </Server>

Communication using TLS

To use Transport Layer Security (TLS) for the communication between the Snow Inventory Agent and the Snow Inventory endpoint, the below requirements must be met.

TLS versions supported by the agents are listed in Security considerations in Snow Inventory. From a security point of view, using the latest stable version is always advisable.

Agent	Description
Windows	The root certificate (.cer) must be installed in the Trusted Root Certification Authorities of the computer to be inventoried.
Unix	The certificate file (.cer) must be placed in the /opt/snow/ directory of the computer to be inventoried. Note: If the connection between the agent and the Snow Inventory endpoint fails, see Troubleshooting TLS connection failures for Unix for possible reasons and solutions.
Linux	Since the location of the certificate file differs between Linux distributions, the agent must be told where to find it via the setting key http.ssl_capath in the agent configuration file. Example: <SystemSettings> <Setting key="http.ssl_capath" value="/etc/ssl/certs/mycert.pem" /> </SystemSettings>
macOS	By default, the agent collects the certificate file from Keychain. If you want to provide your own certificate file, specify it using the setting key http.ssl_capath in the agent configuration file, see the example above.

Troubleshooting TLS connection failures for Unix

If any of the following error messages are shown in the Unix agent log, follow the instructions to enable the connection between the agent and the Snow Inventory endpoint.

• Error message: RSA premaster secret error

  The components local_policy.jar and US_export_policy.jar must be updated in Java.

• Error message: ERROR; Posting to server;;; Couldn't connect to server: https://<inventory_URL>:443: Exception caught: A system call received a parameter that is not valid. (Read failed)

  The Snow Inventory endpoint requires a newer version of TLS than is enabled by default in your Java version. To enable the use of the required TLS version, carry out one of the following options:

  • Option 1: Force the connection with the supported TLS version. At the command prompt, enter:

    -Djdk.tls.client.protocols=TLSv[x.y] [agent scan command] -Djdk.tls.client.protocols=TLSv[x.y] [agent send command], where TLSv[x.y] is the required TLS version.

  • Option 2: Override the default protocol. At the command prompt, enter:

    -Dcom.ibm.jsse2.overrideDefaultTLS=true [agent scan command] -Dcom.ibm.jsse2.overrideDefaultTLS=true [agent send command]

    EXAMPLE

    Option 1:

    java -Djdk.tls.client.protocols=TLSv1.2 -jar /opt/snow/snowagent.jar -w /opt/snow scan >/dev/null 2>&1 ; java -Djdk.tls.client.protocols=TLSv1.2 -jar /opt/snow/snowagent.jar -w /opt/snow send >/dev/null 2>&1

    Option 2:

    java -Dcom.ibm.jsse2.overrideDefaultTLS=true -jar /opt/snow/snowagent.jar -w /opt/snow scan >/dev/null 2>&1 ; java -Dcom.ibm.jsse2.overrideDefaultTLS=true -jar /opt/snow/snowagent.jar -w /opt/snow send >/dev/null 2>&1

    note

    In most systems the minimum required TLS version is 1.2. It was made the default protocol in IBM Java 7 with Service Refresh 5, fix pack 15 and in IBM Java 8 with Service Refresh 8, fix pack 15.