# High-Level Architecture ### I. Introduction and Architectural Principles The GetTrusted architecture is a zero-trust security framework designed to provide verifiable, hardware-rooted, and privacy-preserving identities for individuals and enterprises. The core principle is End-to-End Encryption (E2EE) and verifiable trust, moving all cryptographic operations to the device and relying on hardware security modules (HSMs) for key integrity. #### Core Principles | Principle | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **End-to-End Encryption (E2EE)** | All communications and data storage are encrypted from source to destination. The API server acts only as an unintelligent proxy and public key exchange mechanism. | | **Hardware Root of Trust** | Cryptographic identity is rooted in the device's HSM (Secure Enclave, StrongBox, TPM) to ensure private keys are never exposed and cannot be exfiltrated. Biometrics enabled on key access if required. | | **Verifiable Trust Graph** | All trust events, including identity creation, mutual trust exchanges, and key recovery, are logged immutably to a attestation log for audit and verification, leveraging Certificate Transparency (CT) principles. | | **Zero Credential Storage** | The API server never stores user passwords or private keys. Authentication is managed solely through hardware-attested, identity-signed JSON Web Tokens (JWTs). | ### II. System Components The architecture consists of three primary components working in concert to manage identity and data exchange. #### 1. GetTrusted Mobile Client (Client) The client application manages all key generation, cryptographic operations, and secure storage locally. It is responsible for: * Generating the **Master Identity CA** (self-signed, temporal). * Minting the primary **Device Key** and limited **Tertiary Device Keys**. * Creating a derived **Backup Key** (using a hash of fingerprint + passphrase) for secure data recovery, stored in the platform Keystore. * Generating authentication JWTs using the Device Key and attaching hardware attestation tokens. * Performing E2E encryption and decryption of all communicated data. #### 2. API Server (Proxy & Public Key Exchange) This server acts as a non-trustworthy intermediary for all network traffic. * **Role:** Public key discovery and WebSocket server. * **Function:** Stores public keys and facilitates the exchange of public keys between users who have an established relationship. * **Authentication:** Validates incoming JWTs, ensuring the token is properly signed by a registered, hardware-attested Device Key and contains valid identity information (Device ID, permissions, Master Identity ID). * **Data Integrity:** Stores temporary end to end encrypted data for routing but stores no private user credentials or expose any PII unencrypted. * **Enterprise Data**: All business get a unique key in KMS and unique Intermediary CA stored in KMS. Data is stored using business only keys, with support for bring your own KMS keys coming. #### 3. Attestation Server (Verifiable Trust Log) This specialized server provides an immutable, auditable log of trust events, functioning similarly to a Certificate Transparency log. This log functions only on hashes that are anonymous, unless you have a trusted contact which makes the log both policy and history. * **Technology:** Uses Merkle trees and cryptographic hashing to ensure the log cannot be tampered with. * **Recorded Events (Trust Events):** * Identity Creation (Master CA minting). * Device/Key Recovery. * Mutual Trust Exchange. * Verification Events. * Business CA Creation * Business and Employee Relationship * Delegation Events * Identity Additions like KYC (Real Human Attestation) * **Purpose:** Allows the ability verify the history and validity of a user's trust chain and to observe changes over time, establishing the "Trust Graph." ### III. Identity Hierarchy and Delegation (PKI Model) GetTrusted implements a dual-layered PKI model to manage human identity and business relationships, all rooted in X.509 certificates. #### 1. Personal Identity Chain (Self-Signed) | Identity Component | Function | Status | Rooted To | | ---------------------- | ------------------------------------------------------------------------------- | ----------------- | ------------------------------- | | **Master Identity CA** | Root of the personal identity. **Temporal** and destroyed after key delegation. | Self-Signed CA | - | | **Device Key** | Primary operational key. Used for signing, authentication, and encryption. | X.509 Certificate | Master Identity CA | | **Tertiary Key** | Optional keys with limited, specific permissions (e.g., IoT device access). | X.509 Certificate | Device Key, Master Identity CA. | #### 2. Enterprise and Network Chain (Global Root) | CA Level | Function | Signed By | | -------------------------------- | ----------------------------------------------- | ---------------------------- | | **GetTrusted Root CA** | Global trust anchor for the entire network. | Self-Signed (Offline) | | **GetTrusted Business CA** | Intermediary CA for managing business entities. | GetTrusted Root CA | | **Organization Intermediary CA** | Dedicated CA for each enterprise/organization. | GetTrustedBusiness CA | | **Employee Device Keys** | Keys for organizational members. | Organization Intermediary CA | #### 3. Dual-Signature Binding A critical feature is the explicit binding of personal and organizational identity. Certificates issued to an employee for use within an enterprise are **dual-signed** by both the **Organization Intermediary CA** and the **Human's Device Key**. This process explicitly ties the human's self-sovereign identity to their enterprise identity for purposes like network authorization and identity recovery. This also allows us to expose trust graph activity for the human to the business in an anonymous way. ### IV. Communication and Authentication Authentication relies on cryptographic proof-of-possession rather than shared secrets. * **Authentication Flow:** The Mobile Client generates a JWT containing identity claims (Device ID, permissions, Master Identity ID) and cryptographically signs the JWT using the **Device Private Key**. * **Attestation:** The JWT includes **Hardware Attestation Tokens** and **Key Attestations** provided by the device's HSM, proving that the Device Key is genuinely hardware-backed and operating on a trusted device state. * **Verification:** The API Server verifies the JWT signature against the registered **Device Public Key** and checks the validity of the attestation tokens, ensuring the request originates from a legitimate, registered, and hardware-verified entity. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gettrusted.app/architectural-foundations/high-level-architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.