Secure Login (Civetweb, TLS-terminator) example

The Secure Login example demonstrates use of the Information Obscurity pattern. This example demonstrates the capability to transmit critical system information through an untrusted environment.

Example architecture

This example simulates the acquisition of remote access to an IoT device by sending user account credentials (user name and password) to this device. The untrusted environment within the IoT device is the web server that responds to requests from users. Practical experience has shown that this kind of web server is easy to detect and frequently attacked successfully because IoT devices do not have built-in tools for protection against intrusion and other attacks. Users also gain access to the IoT device through an untrusted network. Obviously, encryption algorithms must be used in these types of conditions to protect user account credentials from being compromised.

In terms of the architecture in these systems, the following objects can be distinguished:

• Data source: user's browser.
• Point of communication with the device: web server.
• Subsystem for processing information from the user: authentication subsystem.

To employ cryptographic protection, the following steps must be completed:

1. Configure interaction between the data source and the device over the HTTPS protocol. This helps prevent unauthorized surveillance of HTTP traffic and MITM (man-in-the-middle) attacks.
2. Generate a shared secret between the data source and the information processing subsystem.
3. Use this secret to encrypt information on the data source side and to decrypt the information on the information processing subsystem side. This helps prevent data within the device from being compromised (at the point of communication).

The Secure Login example includes the following components:

• Civetweb web server (untrusted component, WebServer program).
• User authentication subsystem (trusted component, AuthService program).
• TLS terminator (trusted component, TlsEntity program). This component supports the TLS (transport layer security) mechanism. Together with the web server, the TLS terminator supports the HTTPS protocol on the device side (the web server interacts with the browser through the TLS terminator).

The user authentication process occurs as follows:

1. Using their browser, the user opens the page at https://localhost:1106 (when running the example on QEMU) or at https://<Raspberry Pi IP address>:1106 (when running the example on Raspberry Pi 4 B). HTTP traffic between the browser and TLS terminator will be transmitted in encrypted form, but the web server will work only with unencrypted HTTP traffic.

   This example uses a self-signed certificate, so most up-to-date browsers will warn you that the connection is not secure. You need to agree to use this "insecure" connection, which will actually be encrypted despite the warning. In some browsers, you may encounter the message "TLS: Error performing handshake: -30592: errno = Success".

2. The Civetweb web server running in the WebServer program displays the index.html page containing an authentication prompt.
3. The user clicks the Log in button.
4. The WebServer program queries the AuthService program via IPC to get the page containing the user name and password input form.
5. The AuthService program performs the following actions:
   • Generates a private key and public settings, and calculates the public key based on the Diffie-Hellman algorithm.
   • Creates the auth.html page containing the user name and password input form (the page code contains the public settings and the public key).
   • Transfers the received page to the WebServer program via IPC.
6. The Civetweb web server running in the WebServer program displays the auth.html page containing the user name and password input form.
7. The user completes the form and clicks the Submit button (correct data for authentication is contained in the file secure_login/auth_service/src/authservice.cpp).
8. The auth.html page code executed by the browser performs the following actions:
   • Generates a private key and calculates the public key and shared secret key based on the Diffie-Hellman algorithm.
   • Encrypts the password by using the XOR operation with the shared secret key.
   • Transmits the user name, encrypted password and public key to the web server.
9. The WebServer program queries the AuthService program via IPC to get the page containing the authentication result by transmitting the user name, encrypted password and public key.
10. The AuthService program performs the following actions:
    • Calculates the shared secret key based on the Diffie-Hellman algorithm.
    • Decrypts the password by using the shared secret key.
    • Returns the result_err.html page or result_ok.html page depending on the authentication result.
11. The Civetweb web server running in the WebServer program displays the result_err.html page or the result_ok.html page.

This way, confidential data is transmitted only in encrypted form through the network and web server. In addition, all HTTP traffic is transmitted through the network in encrypted form. Data is transferred between components via IPC interactions controlled by the Kaspersky Security Module.

Unit testing using the GoogleTest framework

In addition to the Information Obscurity pattern, the Secure Login example demonstrates use of the GoogleTest framework to conduct unit testing of applications developed for KasperskyOS (this framework is provided in KasperskyOS Community Edition).

The source code of the tests is located at the following path:

/opt/KasperskyOS-Community-Edition-<version>/examples/secure_login/tests

These unit tests are designed for verification of certain CPP modules of the authentication subsystem and web server.

To start testing:

1. Go to the directory with the Secure Login example.
2. Delete the build directory containing the results of the previous build by running the following command:

   sudo rm -rf build/

3. Open the cross-build.sh script file in a text editor.
4. Add the -D RUN_TESTS="y" \ build flag to the script (for example, after the -D CMAKE_BUILD_TYPE:STRING=Release \ build flag).
5. Save the script file and then run the command:

   $ sudo ./cross-build.sh

Tests are conducted in the TestEntity program. The AuthService and WebServer programs are not started in this case. Therefore, the example cannot be used to demonstrate the Information Obscurity pattern when testing is being conducted.

After testing is finished, the results of the tests are displayed.

Example files

The code of the example and build scripts are available at the following path:

/opt/KasperskyOS-Community-Edition-<version>/examples/secure_login

Building and running example

To run an example on QEMU, go to the directory containing the example, build the example and run the following commands:

$ cd build/einit

# Before running the following command, be sure that the path to

# the directory with the qemu-system-aarch64 executable file is saved in

# the PATH environment variable. If it is not there,

# add it to the PATH variable.

$ qemu-system-aarch64 -m 2048 -machine vexpress-a15 -nographic -monitor none -net nic,macaddr=52:54:00:12:34:56 -net user,hostfwd=tcp::1106-:1106 -sd sdcard0.img -kernel kos-qemu-image

See also Building and running examples section.