2 Using pre-shared keys

    Overview

    • non-secret PSK identity string,

    PSK identity string is a non-empty UTF-8 string. For example, “PSK ID 001 Zabbix agentd”. It is a unique name by which this specific PSK is referred to by Zabbix components. Do not put sensitive information in PSK identity string - it is transmitted over the network unencrypted.

    PSK value is a hard to guess string of hexadecimal digits, for example, “e560cb0d918d26d31b4f642181f5f570ad89a390931102e5391d08327ba434e9”.

    Size limits

    There are size limits for PSK identity and value in Zabbix, in some cases a crypto library can have lower limit:

    Zabbix frontend allows configuring up to 128-character long PSK identity string and 2048-bit long PSK regardless of crypto libraries used.
    If some Zabbix components support lower limits, it is the user’s responsibility to configure PSK identity and value with allowed length for these components.
    Exceeding length limits results in communication failures between Zabbix components.

    Before Zabbix server connects to agent using PSK, the server looks up the PSK identity and PSK value configured for that agent in database (actually in configuration cache). Upon receiving a connection the agent uses PSK identity and PSK value from its configuration file. If both parties have the same PSK identity string and PSK value the connection may succeed.

    Each PSK identity must be paired with only one value. It is the user’s responsibility to ensure that there are no two PSKs with the same identity string but different values. Failing to do so may lead to unpredictable disruptions of communication between Zabbix components using PSKs with this PSK identity string.

    Generating PSK

    For example, a 256-bit (32 bytes) PSK can be generated using the following commands:

    • with OpenSSL:
    • with GnuTLS:
    2.          Generating a random key for user 'psk_identity'
    3.          Key stored to database.psk
    5.          psk_identity:9b8eafedfaae00cece62e85d5f4792c7d9c9bcc851b23216a1d300311cc4f7cb

    Note that “psktool” above generates a database file with a PSK identity and its associated PSK. Zabbix expects just a PSK in the PSK file, so the identity string and colon (‘:’) should be removed from the file.

    Configuring PSK for server-agent communication (example)

    Set access rights to PSK file - it must be readable only by Zabbix user.

    Edit TLS parameters in agent configuration file zabbix_agentd.conf, for example, set:

    1. TLSConnect=psk
    2.        TLSAccept=psk
    3.        TLSPSKFile=/home/zabbix/zabbix_agentd.psk
    4.        TLSPSKIdentity=PSK 001

    The agent will connect to server (active checks) and accept from server and only connections using PSK. PSK identity will be “PSK 001”.

    Restart the agent. Now you can test the connection using zabbix_get, for example:

    (To minimize downtime see how to change connection type in Connection encryption management).

    Configure PSK encryption for this agent in Zabbix frontend:

    • Go to: Configuration → Hosts

    Example:

    When configuration cache is synchronized with database the new connections will use PSK. Check server and agent logfiles for error messages.

    Configuring PSK for server - active proxy communication (example)

    On the proxy, write the PSK value into a file, for example, /home/zabbix/zabbix_proxy.psk. The file must contain PSK in the first text string, for example:

    1. e560cb0d918d26d31b4f642181f5f570ad89a390931102e5391d08327ba434e9

    Set access rights to PSK file - it must be readable only by Zabbix user.

    Edit TLS parameters in proxy configuration file zabbix_proxy.conf, for example, set:

    The proxy will connect to server using PSK. PSK identity will be “PSK 002”.

    (To minimize downtime see how to change connection type in Connection encryption management).

    Configure PSK for this proxy in Zabbix frontend. Go to Administration→Proxies, select the proxy, go to “Encryption” tab. In “Connections from proxy” mark PSK. Paste into “PSK identity” field “PSK 002” and “e560cb0d918d26d31b4f642181f5f570ad89a390931102e5391d08327ba434e9” into “PSK” field. Click “Update”.

    Restart proxy. It will start using PSK-based encrypted connections to server. Check server and proxy logfiles for error messages.