Feature: Implement HTTPS-Only Communication with Certificate Pinning (NF.S21) #113

New issue

Closed

opened 2025-10-16 16:59:02 +00:00 by rwachters · 0 comments

rwachters commented

2025-10-16 16:59:02 +00:00

(Migrated from github.com)

Executive Summary

This issue details the implementation plan for enabling HTTPS-only communication between the client and server, as specified in user story NF.S21 - Secure Communication with Server. The revised approach leverages a CustomTrustManager for certificate pinning on the client, eliminating the need for server-side certificate distribution and enhancing security.

User Story

NF.S21 - Secure Communication with Server: As a user, I want all communication between my client and the server to be encrypted using HTTPS, so that my data is secure and protected from eavesdropping.

Current State

Server: HTTP-only on port 8080 (localhost)
Client: Connects via HTTP to http://localhost:8080
SSL/TLS: Not implemented
Certificate Management: Not implemented

Required Changes Overview

The implementation requires changes across server, client (app), and common modules, spanning approximately 13-18 files with new files to be created and existing files to be modified.

Implementation Plan (Phases)

Phase 1: Server SSL/TLS Infrastructure (Estimated: 3-4 days)

This phase focuses on configuring the server to serve content over HTTPS and managing server certificates.

Task 1.1: Create the SslConfig data class (server/src/main/kotlin/eu/torvian/chatbot/server/domain/config/SslConfig.kt).
Task 1.2: Adapt CertificateService and DefaultCertificateService from temp/ files, updating package names.
Task 1.3: Implement CertificateManager interface and DefaultCertificateManager implementation.
Task 1.4: Update ServerControlServiceImpl:
- Modify constructor to inject CertificateManager.
- Add loadKeystore helper method.
- Update startSuspend to generate self-signed certificates if sslConfig.generateSelfSigned is true and no keystore exists.
- Restructure createEmbeddedServer to use the configure lambda for sslConnector setup.
Task 1.5: Add Bouncy Castle dependencies to server/build.gradle.kts.
Task 1.6: Update Koin modules (configModule, serviceModule, mainModule) for SslConfig, CertificateService, CertificateManager, and ServerControlServiceImpl injection.
Task 1.7: Update ServerConfig and ServerMain to include SslConfig and use HTTPS defaults.
Task 1.8: Create server-side tests for certificate generation, parsing, and HTTPS functionality (CertificateServiceTest, CertificateManagerTest, ServerHttpsTest).

Phase 2: Client SSL/TLS Configuration (Estimated: 3-4 days)

This phase focuses on configuring the client's HTTP client to use HTTPS and implement certificate pinning.

Task 2.1: Create CertificateStorage interface and platform-specific implementations (FileSystemCertificateStorage, AndroidCertificateStorage, BrowserCertificateStorage).
Task 2.2: Implement CustomTrustManager for Desktop and Android platforms. This manager will handle certificate pinning by verifying the server certificate obtained during the TLS handshake against a stored certificate.
Task 2.3: Update createHttpClient to configure SSL/TLS, injecting CertificateStorage and using CustomTrustManager for JVM/Android.
Task 2.4: Update client serverUrl in AppMain.kt, MainActivity.kt, and WASM AppMain.kt to use https://localhost:8443 (or appropriate platform-specific HTTPS URL).
Task 2.5: Add Koin bindings for CertificateStorage in desktopModule, androidModule, and wasmJsModule.
Task 2.6: Create client-side tests for certificate storage (CertificateStorageTest).

Phase 3: Certificate Verification UI (Estimated: 2-3 days)

This phase focuses on providing a user interface for handling self-signed or changed certificates.

Task 3.1: Create CertificateWarningDialog composable to display certificate details (fingerprint, issuer, validity) and allow the user to accept or reject the certificate.
Task 3.2: Integrate the CertificateWarningDialog into the client's connection flow, triggered by the CustomTrustManager on first connection to a server with a self-signed certificate, or if a pinned certificate changes.
Task 3.3: Implement logic to store accepted certificates via CertificateStorage and handle rejections.

Phase 4: Testing and Documentation (Estimated: 2-3 days)

Task 4.1: Write comprehensive unit and integration tests for all new and modified components.
Task 4.2: Conduct end-to-end testing of HTTPS communication, certificate pinning, and the certificate warning dialog.
Task 4.3: Document server configuration, client setup, and deployment instructions.
Task 4.4: Update the project README with HTTPS setup instructions.

Key Components and Files

Server

New:
- SslConfig.kt (server/src/main/kotlin/eu/torvian/chatbot/server/domain/config/SslConfig)
- CertificateManager.kt (server/src/main/kotlin/eu/torvian/chatbot/server/service/security/CertificateManager)
- DefaultCertificateManager.kt (server/src/main/kotlin/eu/torvian/chatbot/server/service/security/DefaultCertificateManager)
- CertificateServiceTest.kt (server/src/test/kotlin/eu/torvian/chatbot/server/service/security/CertificateServiceTest.kt)
- CertificateManagerTest.kt (server/src/test/kotlin/eu/torvian/chatbot/server/service/security/CertificateManagerTest.kt)
- ServerHttpsTest.kt (server/src/test/kotlin/eu/torvian/chatbot/server/ktor/ServerHttpsTest.kt)
Modified:
- ServerConfig.kt
- ServerMain.kt
- ServerControlServiceImpl.kt
- chatBotServerModule.kt
- configModule.kt
- serviceModule.kt
- build.gradle.kts

Client

New:
- CertificateStorage.kt (app/src/commonMain/kotlin/eu/torvian/chatbot/app/service/security/CertificateStorage.kt)
- FileSystemCertificateStorage.kt (app/src/desktopMain/kotlin/eu/torvian/chatbot/app/service/security/FileSystemCertificateStorage.kt)
- CustomTrustManager.kt (Desktop) (app/src/desktopMain/kotlin/eu/torvian/chatbot/app/service/security/CustomTrustManager.kt)
- AndroidCertificateStorage.kt (app/src/androidMain/kotlin/eu/torvian/chatbot/app/service/security/AndroidCertificateStorage.kt)
- CustomTrustManager.kt (Android) (app/src/androidMain/kotlin/eu/torvian/chatbot/app/service/security/CustomTrustManager.kt)
- BrowserCertificateStorage.kt (app/src/wasmJsMain/kotlin/eu/torvian/chatbot/app/service/security/BrowserCertificateStorage.kt)
- CertificateWarningDialog.kt (app/src/commonMain/kotlin/eu/torvian/chatbot/app/compose/dialogs/CertificateWarningDialog.kt)
- CertificateStorageTest.kt (app/src/desktopTest/kotlin/eu/torvian/chatbot/app/service/security/CertificateStorageTest.kt)
Modified:
- createHttpClient.kt
- appModule.kt
- AppMain.kt (desktop)
- desktopModule.kt
- MainActivity.kt (android)
- androidModule.kt
- AppMain.kt (wasm)

Configuration Management

Server: Recommend using environment variables or application.conf for SSL settings (e.g., server.ssl.enabled, server.ssl.port, server.ssl.keystore.path, server.ssl.keystore.password, server.ssl.keyAlias, server.ssl.keyPassword, server.ssl.generateSelfSigned).
Client: Update AppConfig to use HTTPS URLs (e.g., https://localhost:8443).

Security Considerations

Certificate Validation Modes: Support production (CA-signed), local network (self-signed with pinning), and development (user-accepted self-signed) scenarios.
Certificate Pinning Strategy: Store SHA-256 fingerprint on first connection (user acceptance), verify on subsequent connections, and warn users if the certificate changes.
Key Storage: Server private keys in encrypted JKS keystore; client certificates in platform-specific secure storage. Passwords loaded from environment variables.

Acceptance Criteria Mapping

All communication encrypted using HTTPS: Achieved by server SSL connector and client HTTPS URLs.
Server has valid SSL/TLS certificate: Handled by certificate generation/loading in CertificateManager.
Client verifies server certificate: Implemented via certificate pinning using CustomTrustManager.
Warning for self-signed certificates: Provided by CertificateWarningDialog on first connection or certificate change.
Certificate storage for future use: Managed by CertificateStorage implementations.

Estimated Effort

Total Estimated Effort: 10-14 days

## Executive Summary This issue details the implementation plan for enabling HTTPS-only communication between the client and server, as specified in user story **NF.S21 - Secure Communication with Server**. The revised approach leverages a `CustomTrustManager` for certificate pinning on the client, eliminating the need for server-side certificate distribution and enhancing security. ## User Story * **NF.S21 - Secure Communication with Server**: As a user, I want all communication between my client and the server to be encrypted using HTTPS, so that my data is secure and protected from eavesdropping. ## Current State * **Server**: HTTP-only on port 8080 (localhost) * **Client**: Connects via HTTP to `http://localhost:8080` * **SSL/TLS**: Not implemented * **Certificate Management**: Not implemented ## Required Changes Overview The implementation requires changes across **server**, **client (app)**, and **common** modules, spanning approximately **13-18 files** with new files to be created and existing files to be modified. ## Implementation Plan (Phases) ### Phase 1: Server SSL/TLS Infrastructure (Estimated: 3-4 days) This phase focuses on configuring the server to serve content over HTTPS and managing server certificates. * **Task 1.1**: Create the `SslConfig` data class (`server/src/main/kotlin/eu/torvian/chatbot/server/domain/config/SslConfig.kt`). * **Task 1.2**: Adapt `CertificateService` and `DefaultCertificateService` from `temp/` files, updating package names. * **Task 1.3**: Implement `CertificateManager` interface and `DefaultCertificateManager` implementation. * **Task 1.4**: Update `ServerControlServiceImpl`: * Modify constructor to inject `CertificateManager`. * Add `loadKeystore` helper method. * Update `startSuspend` to generate self-signed certificates if `sslConfig.generateSelfSigned` is true and no keystore exists. * Restructure `createEmbeddedServer` to use the `configure` lambda for `sslConnector` setup. * **Task 1.5**: Add Bouncy Castle dependencies to `server/build.gradle.kts`. * **Task 1.6**: Update Koin modules (`configModule`, `serviceModule`, `mainModule`) for `SslConfig`, `CertificateService`, `CertificateManager`, and `ServerControlServiceImpl` injection. * **Task 1.7**: Update `ServerConfig` and `ServerMain` to include `SslConfig` and use HTTPS defaults. * **Task 1.8**: Create server-side tests for certificate generation, parsing, and HTTPS functionality (`CertificateServiceTest`, `CertificateManagerTest`, `ServerHttpsTest`). ### Phase 2: Client SSL/TLS Configuration (Estimated: 3-4 days) This phase focuses on configuring the client's HTTP client to use HTTPS and implement certificate pinning. * **Task 2.1**: Create `CertificateStorage` interface and platform-specific implementations (`FileSystemCertificateStorage`, `AndroidCertificateStorage`, `BrowserCertificateStorage`). * **Task 2.2**: Implement `CustomTrustManager` for Desktop and Android platforms. This manager will handle certificate pinning by verifying the server certificate obtained during the TLS handshake against a stored certificate. * **Task 2.3**: Update `createHttpClient` to configure SSL/TLS, injecting `CertificateStorage` and using `CustomTrustManager` for JVM/Android. * **Task 2.4**: Update client `serverUrl` in `AppMain.kt`, `MainActivity.kt`, and WASM `AppMain.kt` to use `https://localhost:8443` (or appropriate platform-specific HTTPS URL). * **Task 2.5**: Add Koin bindings for `CertificateStorage` in `desktopModule`, `androidModule`, and `wasmJsModule`. * **Task 2.6**: Create client-side tests for certificate storage (`CertificateStorageTest`). ### Phase 3: Certificate Verification UI (Estimated: 2-3 days) This phase focuses on providing a user interface for handling self-signed or changed certificates. * **Task 3.1**: Create `CertificateWarningDialog` composable to display certificate details (fingerprint, issuer, validity) and allow the user to accept or reject the certificate. * **Task 3.2**: Integrate the `CertificateWarningDialog` into the client's connection flow, triggered by the `CustomTrustManager` on first connection to a server with a self-signed certificate, or if a pinned certificate changes. * **Task 3.3**: Implement logic to store accepted certificates via `CertificateStorage` and handle rejections. ### Phase 4: Testing and Documentation (Estimated: 2-3 days) * **Task 4.1**: Write comprehensive unit and integration tests for all new and modified components. * **Task 4.2**: Conduct end-to-end testing of HTTPS communication, certificate pinning, and the certificate warning dialog. * **Task 4.3**: Document server configuration, client setup, and deployment instructions. * **Task 4.4**: Update the project `README` with HTTPS setup instructions. ## Key Components and Files ### Server * **New**: * `SslConfig.kt` (`server/src/main/kotlin/eu/torvian/chatbot/server/domain/config/SslConfig`) * `CertificateManager.kt` (`server/src/main/kotlin/eu/torvian/chatbot/server/service/security/CertificateManager`) * `DefaultCertificateManager.kt` (`server/src/main/kotlin/eu/torvian/chatbot/server/service/security/DefaultCertificateManager`) * `CertificateServiceTest.kt` (`server/src/test/kotlin/eu/torvian/chatbot/server/service/security/CertificateServiceTest.kt`) * `CertificateManagerTest.kt` (`server/src/test/kotlin/eu/torvian/chatbot/server/service/security/CertificateManagerTest.kt`) * `ServerHttpsTest.kt` (`server/src/test/kotlin/eu/torvian/chatbot/server/ktor/ServerHttpsTest.kt`) * **Modified**: * `ServerConfig.kt` * `ServerMain.kt` * `ServerControlServiceImpl.kt` * `chatBotServerModule.kt` * `configModule.kt` * `serviceModule.kt` * `build.gradle.kts` ### Client * **New**: * `CertificateStorage.kt` (`app/src/commonMain/kotlin/eu/torvian/chatbot/app/service/security/CertificateStorage.kt`) * `FileSystemCertificateStorage.kt` (`app/src/desktopMain/kotlin/eu/torvian/chatbot/app/service/security/FileSystemCertificateStorage.kt`) * `CustomTrustManager.kt` (Desktop) (`app/src/desktopMain/kotlin/eu/torvian/chatbot/app/service/security/CustomTrustManager.kt`) * `AndroidCertificateStorage.kt` (`app/src/androidMain/kotlin/eu/torvian/chatbot/app/service/security/AndroidCertificateStorage.kt`) * `CustomTrustManager.kt` (Android) (`app/src/androidMain/kotlin/eu/torvian/chatbot/app/service/security/CustomTrustManager.kt`) * `BrowserCertificateStorage.kt` (`app/src/wasmJsMain/kotlin/eu/torvian/chatbot/app/service/security/BrowserCertificateStorage.kt`) * `CertificateWarningDialog.kt` (`app/src/commonMain/kotlin/eu/torvian/chatbot/app/compose/dialogs/CertificateWarningDialog.kt`) * `CertificateStorageTest.kt` (`app/src/desktopTest/kotlin/eu/torvian/chatbot/app/service/security/CertificateStorageTest.kt`) * **Modified**: * `createHttpClient.kt` * `appModule.kt` * `AppMain.kt` (desktop) * `desktopModule.kt` * `MainActivity.kt` (android) * `androidModule.kt` * `AppMain.kt` (wasm) ## Configuration Management * **Server**: Recommend using environment variables or `application.conf` for SSL settings (e.g., `server.ssl.enabled`, `server.ssl.port`, `server.ssl.keystore.path`, `server.ssl.keystore.password`, `server.ssl.keyAlias`, `server.ssl.keyPassword`, `server.ssl.generateSelfSigned`). * **Client**: Update `AppConfig` to use HTTPS URLs (e.g., `https://localhost:8443`). ## Security Considerations * **Certificate Validation Modes**: Support production (CA-signed), local network (self-signed with pinning), and development (user-accepted self-signed) scenarios. * **Certificate Pinning Strategy**: Store SHA-256 fingerprint on first connection (user acceptance), verify on subsequent connections, and warn users if the certificate changes. * **Key Storage**: Server private keys in encrypted JKS keystore; client certificates in platform-specific secure storage. Passwords loaded from environment variables. ## Acceptance Criteria Mapping * **All communication encrypted using HTTPS**: Achieved by server SSL connector and client HTTPS URLs. * **Server has valid SSL/TLS certificate**: Handled by certificate generation/loading in `CertificateManager`. * **Client verifies server certificate**: Implemented via certificate pinning using `CustomTrustManager`. * **Warning for self-signed certificates**: Provided by `CertificateWarningDialog` on first connection or certificate change. * **Certificate storage for future use**: Managed by `CertificateStorage` implementations. ## Estimated Effort **Total Estimated Effort: 10-14 days**