View source for 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'