icing/monorepo
4
0
Fork 0
Code Pull Requests 3 Actions Packages Releases 1 Activity
ee27a82c0a
monorepo/docs/UserManual.md
STCB ee27a82c0a
All checks were successful
/ mirror (push) Successful in 4s
Details
/ deploy (push) Successful in 39s
Details
Partial Doc update for Greenlight (#65) 
Co-authored-by: STCB <stephane.corbiere@epitech.eu>
Reviewed-on: #65
Co-authored-by: STCB <21@stcb.cc>
Co-committed-by: STCB <21@stcb.cc>
2025-07-06 23:09:20 +00:00

14 KiB
Raw Blame History

User Manual for Icing Dialer

Introduction

The Icing Dialer is an open-source mobile application designed to enable end-to-end encrypted voice calls over GSM/LTE networks, ensuring privacy without reliance on the internet, servers, or third-party infrastructure. This manual provides comprehensive guidance for three audiences: average users, security experts, and developers. A final section outlines our manual testing policy to ensure the application's reliability and security.

  • Average User: Instructions for using the Icing Dialer as a transparent replacement for the default phone dialer.
  • Security Expert: Technical details of the Icing protocol, including cryptographic mechanisms and implementation.
  • Developer: In-depth explanation of the code architecture, Icing protocol library, and integration guidelines.
  • Manual Tests: Overview of the manual testing policy for validating the application and protocol.

Summary

Average User

The Icing Dialer is a privacy-focused mobile application that replaces your default phone dialer, providing secure, end-to-end encrypted voice calls over GSM/LTE networks. It is designed to be intuitive and indistinguishable from a standard dialer, ensuring seamless use for all users.

Key Features

  • Seamless Dialer Replacement: Functions as a full replacement for your phone’s default dialer, supporting standard call features and encrypted calls.
  • Cryptographic Key Pair Generation: Automatically generates an ED25519 key pair during setup for secure communications, stored securely using the Android Keystore.
  • Secure Contact Sharing: Adds and shares contacts via QR codes or VCF files, ensuring privacy.
  • Automatic Call Encryption: Encrypts calls with compatible Icing Dialer users using the Noise protocol, encoded into the analog audio signal via Codec2 and 4FSK modulation.
  • On-the-Fly Pairing: Detects other Icing Dialer users and offers encrypted pairing during calls (optional, under development).
  • Call Management: Includes call history, contact management, visual voicemail, and features like mute, speaker, and SIM selection.
  • Privacy Protection: Safeguards sensitive communications with secure voice authentication and encrypted voicemail.

Getting Started

  1. Installation: Install the Icing Dialer from a trusted source (e.g., a partnered AOSP fork or Magisk module for rooted Android devices).
  2. Setup: Upon first launch, the app generates an ED25519 key pair using the Android Keystore. Follow prompts to complete setup.
  3. Adding Contacts: Use the QR code or VCF import feature to securely add contacts. Scan a contact’s QR code or import a VCF file to establish a secure connection.
  4. Making Calls: Dial numbers using the full dialer interface (numbers, *, #). The app uses the Android Telephony API to detect compatible users and automatically encrypts calls when possible.
  5. Encrypted Calls: Calls to known contacts with public keys are automatically encrypted. A data rate and error indicator provide real-time feedback. Use the disable encryption button if needed.
  6. Call History and Contacts: Access call history with filters for missed, incoming, and outgoing calls. Tap a call to view details or open a contact modal. Manage contacts with search, favorites, and blocklist features.
  7. Visual Voicemail: Play, pause, or manage voicemails with quick links to call, text, block, or share numbers.
  8. Settings: Configure default SIM, manage public keys, and access the blocklist via the settings menu.

Troubleshooting

  • FAQs: Available on our Reddit and Telegram channels for common issues and setup guidance.
  • Feedback: Submit feedback via our anonymous CryptPad form for prompt issue resolution.

Example Scenarios

  • Secure Voicemail Access: Mathilda, 34, uses Icing to securely retrieve a PayPal authentication code from her voicemail, protected by her registered Icing public key.
  • Authenticated Calls: Jeff, 70, authenticates with his bank using encrypted DTMF transmission, ensuring secure and verified communication.
  • Private Communication: Elise, 42, a journalist, uses Icing to make discreet, encrypted calls despite unreliable or monitored networks.
  • Emergency Calls Abroad: Paul, 22, a developer, uses Icing to securely assist colleagues with a critical issue while abroad, relying only on voice calls.

Security Expert

The Icing Dialer is the reference implementation of the Icing protocol, an open, decentralized encryption protocol for telephony. This section details the cryptographic and technical foundations, focusing on security principles.

Icing Protocol Overview

The Icing protocol enables end-to-end encrypted voice calls over GSM/LTE networks by encoding cryptographic data into the analog audio signal. Key components include:

  • End-to-End Encryption: Utilizes the Noise protocol with XX (mutual authentication) and XK (known-key) handshake patterns for secure session establishment, using ED25519 key pairs.
  • Perfect Forward Secrecy: Ensures session keys are ephemeral and discarded after use, with future sessions salted using pseudo-random values derived from past calls.
  • Codec2 and 4FSK: Voice data is compressed using Codec2 and modulated with 4FSK (Four Frequency Shift Keying) for transmission over GSM/LTE.
  • Secure Contact Pairing: Uses QR codes or VCF files for secure key exchange, preventing man-in-the-middle attacks.
  • Encrypted DTMF: Supports secure transmission of DTMF signals for authentication scenarios.
  • Forward Error Correction (FEC): Detects up to 50% of transmission errors in Alpha 1, with plans for stronger FEC (>80% detection, 20% correction) in future iterations.
  • Decentralized Design: Operates without servers or third-party intermediaries, minimizing attack surfaces.
  • Voice Authentication: Implements cryptographic voice authentication to verify caller identity.

Security Implementation

  • Cryptographic Framework: Uses ED25519 key pairs for authentication and encryption, generated and stored securely via the Android Keystore. The Noise protocol ensures secure key exchange and session setup. AES-256 and ECC (P-256, ECDH) are employed for data encryption.
  • Analog Signal Encoding: Codec2 compresses voice data, and 4FSK modulates encrypted data into the analog audio signal, ensuring compatibility with GSM/LTE networks.
  • Threat Model: Protects against eavesdropping, interception, replay attacks, and unauthorized access. Includes replay protection mechanisms and assumes adversaries may control network infrastructure but not device endpoints.
  • Data Privacy: Minimizes data storage (only encrypted keys and minimal metadata), with no unencrypted call metadata stored. Sensitive data is encrypted at rest.
  • Current Status: Protocol Alpha 1, tested in DryBox, validates peer ping, ephemeral key management, handshakes, real-time encryption, stream compression, and 4FSK transmission. Alpha 2 will enhance FEC and on-the-fly key exchange.

Future Considerations

  • Develop a full RFC for the Icing protocol, documenting peer ping, handshakes, and FEC.
  • Optimize Codec2 and 4FSK for improved audio quality and transmission reliability.
  • Implement embedded silent data transmission (e.g., DTMF) and on-the-fly key exchange.
  • Enhance interoperability with existing standards (e.g., SIP, WebRTC).

Developer

The Icing Dialer and its protocol are open-source and extensible. This section explains the code architecture, Icing protocol library, and guidelines for integration into custom applications.

Code Architecture

The Icing Dialer is developed in two implementations:

  • Root-app: For rooted Android devices, deployed via a Magisk module (~85% complete for Alpha 1).
  • AOSP-app: Integrated into a custom AOSP fork for native support, pending partnerships with AOSP-based projects (e.g., GrapheneOS, LineageOS).

The application is written in Kotlin, leveraging the Android Telephony API for call management and a modular architecture:

  • UI Layer: A responsive, intuitive interface resembling a default phone dialer, with accessibility features, contact management, and call history.
  • Encryption Layer: Manages ED25519 key pair generation (via Android Keystore or RAM for export), Noise protocol handshakes (XX and XK), Codec2 compression, and 4FSK modulation.
  • Network Layer: Interfaces with GSM/LTE networks via the Android Telephony API to encode encrypted data into analog audio signals.

Icing Protocol Library

The Kotlin-based Icing protocol library (~75% complete for Alpha 1) enables third-party applications to implement the Icing protocol. Key components include:

  • KeyPairGenerator: Generates and manages ED25519 key pairs, supporting secure (Android Keystore) and insecure (RAM) generation, with export/import capabilities.
  • NoiseProtocolHandler: Implements XX and XK handshakes for secure session establishment, ensuring Perfect Forward Secrecy.
  • QRCodeHandler: Manages secure contact sharing via QR codes or VCF files.
  • AudioEncoder: Compresses voice with Codec2 and modulates encrypted data with 4FSK.
  • CallManager: Uses the Android Telephony API to detect peers, initiate calls, and handle DTMF transmission.
  • FECModule: Implements basic FEC for detecting 50% of transmission errors, with plans for enhanced detection and correction.

Integration Guide

  1. Include the Library: Add the Icing protocol library to your project (available upon Beta release).
  2. Initialize KeyPairGenerator: Generate an ED25519 key pair using Android Keystore for secure storage or RAM for exportable keys.
  3. Implement NoiseProtocolHandler: Configure XX or XK handshakes for authentication and session setup.
  4. Integrate QRCodeHandler: Enable contact sharing via QR codes or VCF files.
  5. Use AudioEncoder: Compress voice with Codec2 and modulate with 4FSK for GSM/LTE transmission.
  6. Leverage CallManager: Manage calls and DTMF via the Android Telephony API.
  7. Test with DryBox: Validate implementation using the Python-based DryBox environment for end-to-end call simulation.

Development Status

  • Protocol Alpha 1: Implemented in DryBox, supporting peer ping, ephemeral keys, handshakes, encryption, Codec2 compression, and 4FSK modulation.
  • Kotlin Library: 75% complete, with tasks remaining for Alpha 1 completion.
  • Root-app: 85% complete, with Magisk deployment in progress.
  • AOSP-app: In development, pending AOSP fork partnerships.

Developers can join our Reddit or Telegram communities for updates and to contribute to the open-source project.

Manual Tests

The Icing project employs a rigorous manual testing policy to ensure the reliability, security, and usability of the Icing Dialer and its protocol. This section outlines our testing approach, incorporating beta testing scenarios and evaluation criteria.

Testing Environment

  • DryBox: A Python-based environment simulating end-to-end encrypted calls over a controlled network, used to validate Protocol Alpha 1 and future iterations.
  • Root-app Testing: Conducted on rooted Android devices using Magisk modules.
  • AOSP-app Testing: Planned for custom AOSP forks, pending partnerships.

Manual Testing Policy

  • Usability Testing: Beta testers evaluate the dialer’s intuitiveness as a drop-in replacement, testing call initiation, contact management, and voicemail. Initial tests confirm usability without prior instructions.
  • Encryption Validation: Tests in DryBox verify end-to-end encryption using Noise protocol (XX/XK handshakes), ED25519 key pairs, Codec2, and 4FSK. Includes encrypted DTMF and FEC (50% error detection).
  • Contact Pairing: Tests QR code and VCF-based contact sharing for security and functionality.
  • Call Scenarios: Tests include clear calls (to non-Icing and Icing dialers), encrypted calls (to known and unknown contacts), and DTMF transmission.
  • Performance Testing: Ensures minimal latency, low bandwidth usage, and high audio quality (clarity, minimal distortion) via Codec2/4FSK.
  • Privacy Testing: Verifies encrypted storage of keys and minimal metadata, with no unencrypted call logs stored.
  • Integration Testing: Validates Android Telephony API integration, permissions (microphone, camera, contacts), and background operation.

Beta Testing Scenarios

  • Clear call from Icing Dialer to another dialer (e.g., Google, Apple).
  • Clear call between two Icing Dialers.
  • Clear call to a known contact (with public key) without Icing Dialer.
  • Encrypted call to a known contact with Icing Dialer.
  • Encrypted call to an unknown contact with Icing Dialer (optional, under development).
  • Create/edit/save contacts with/without public keys.
  • Share/import contacts via QR code/VCF.
  • Listen to voicemail and verify encryption.
  • Record and verify encrypted call integrity.
  • Change default SIM.

Evaluation Criteria

  • Security: Validates AES-256/ECC encryption, ED25519 key management, Perfect Forward Secrecy, replay protection, and end-to-end encryption integrity.
  • Performance: Measures call setup latency, bandwidth efficiency, and audio quality (clarity, consistency).
  • Usability: Ensures intuitive UI, seamless call handling, and robust error recovery.
  • Interoperability: Tests compatibility with GSM/LTE networks and potential future integration with SIP/WebRTC.
  • Privacy: Confirms encrypted data storage, minimal permissions, and no unencrypted metadata.
  • Maintainability: Reviews code quality, modularity, and documentation for the protocol and library.

Current Testing Status

  • Protocol Alpha 1: Validated in DryBox for encryption, handshakes, Codec2/4FSK, and FEC.
  • Root-app: 85% complete, undergoing usability, performance, and security testing.
  • Feedback Channels: Anonymous feedback via CryptPad and FAQs on Reddit/Telegram inform testing.

Future Testing Plans

  • Test Protocol Alpha 2 for enhanced FEC and on-the-fly key exchange.
  • Conduct AOSP-app testing with partnered forks.
  • Incorporate NPS/CSAT metrics from AMAs to assess user satisfaction.

Conclusion

The Icing Dialer and its protocol offer a pioneering approach to secure telephony, leveraging ED25519 key pairs, the Noise protocol, Codec2, 4FSK, and the Android Telephony API. This manual provides comprehensive guidance for users, security experts, and developers, supported by a robust testing policy. For further details or to contribute, visit our Reddit or Telegram communities.