Encryption in manager api

Manager API

The manager api is used by the GUI for requesting files, giving listing of active sessions (CALLs/REGISTERs) or other stats. Since version of a sniffer 2024.02.2 and GUI 26.20, the voipmonitor introduces encryption for xchanges between manager and the GUI. The encryption is enabled by default.

Configuration

By default you don't need to configure anything, generating the key and use it by the GUI and sniffer is fully automated.

manager api bind options

configuration in voipmonitor.conf - by default the voipmonitor sniffer binds on 127.0.0.1:5029

managerip=127.0.0.1
managerport=5029

manager's encryption options

socketfile

The volunary option for openning the socketfile used for unencrypted requests/responses of the manager api at a time of start the sniffer service.

managersocket = /tmp/vm_manager_socket

disable encryption

disables the encryption completely (use for testing/debuging)

manager_enable_unencrypted = yes

the key options

By default the voipmonitor's sniffer and GUI loads the key from voipmonitor GUI's db. You can override this by define the keys options in /etc/voipmonitor.conf it accepts the base64 form of a key - you can generate by the GUI (Read bellow)

manager_aes_key
manager_aes_iv

and In the GUI's configuration.php

VPMANAGER_AES_KEY
VPMANAGER_AES_IV
VPMANAGER_AES_CIPHER (default is aes-128-cbc)

generating the key

You can ask GUI to generate the key and also store it to db for being used by the GUI and sniffer's xchanges enter the GUI's installation folder and ask run.php like

php run.php generate_aes_key

Other options of the run.php related to keys

generate_aes_key - generates the new key don't saves it
store_aes_key - generates and stores the key to db
delete_aes_key - remves the key from db

How to use the API - examples

In following examples will be introduced various ways on how to send manager command listcalls and receive the answer

with disabled encryption

echo listcalls | nc 127.0.0.1 5029

With encryption - by GUIs run.php

id_sensor based request

php php/run.php send_manager_cmd -s 2 -c listcalls

-s id_sensor: 2
-c command: listcalls

IP:port based request

php php/run.php send_manager_cmd -h s4.voipmonitor.org -p 5029 -a -c listcalls
-h host: 10.0.0.1
-p port: 5029
-a enables encryption
-c command: listcalls

using sniffers socketfile

You can use unencrypted request by sending to a socket file

define socketfile in voipmonitor.conf

Define the option in /etc/voipmonitor.conf, the socket file will be created at a time of the service start, when undefined you can ask new socketfile with a manager request.

managersocket = /tmp/vm_manager_socket

enable socketfile in a runtime

Send request to an api to open manager_socket file:

echo 'manager_file start /tmp/vm_manager_socket' | nc 127.0.0.1 5029

==== use the socket file You can use the scocket file with pure requests without encryption

echo listcalls | nc -U /tmp/vm_manager_socket

the socket file remove

You can ask kmanager api for remove of the file (the removing has not real usecase)

echo 'manager_file stop' | nc 127.0.0.1 5029

Manager command's task listcalls

use the SSH for accesing the socketfile from other host

ssh myGUIhost 'echo listcalls | nc -U /tmp/vm_manager_socket'