# insanum/ecies architecture

> Architecture diagram of the GitHub repository insanum/ecies, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/insanum/ecies
- Repository: https://github.com/insanum/ecies

## Overview

##### Main Components
a. Receiver Component:
- Loads an EC key from a DER file (created via the provided make cert command).
- Sends its public key and curve information to the Transmitter.
b. Transmitter Component:
- Generates a new ephemeral EC key on the same curve.
- Computes the shared symmetric key using the Diffie-Hellman primitive.
- Encrypts the plaintext using AES-GCM with the shared key.
- Sends the ephemeral public key, initialization vector (IV), tag, and ciphertext to the Receiver.
c. Cryptographic Operations:
- Utilizes two core external libraries: OpenSSL and WolfSSL.
- Uses AES-GCM for encryption/authentication.
d. Data Flow Elements:
- EC Key generation/loading.
- Public key exchange.
- Shared secret computation.
- Encryption and decryption processes.

##### Relationships and Interactions
- Finally, illustrate the Receiver using the received ephemeral public key to derive the shared symmetric key and decrypt the ciphertext.

##### Architectural Patterns
- This project follows a typical secure communication flow where key exchange (using ECC/Diffie-Hellman) is followed by symmetric encryption (AES-GCM).
- That there are dual implementations (OpenSSL vs. WolfSSL) which are essentially “plug and play” alternatives chosen at build time via a Makefile.
- That the proof-of-concept purposely simplifies the standard ECIES by omitting a KDF and HMAC and substituting them with AES-GCM.

##### Relevant Technologies
- C Programming language for core implementation.
- Cryptographic libraries: OpenSSL and WolfSSL.
- AES-GCM for symmetric encryption.
- ECC for public/private key operations.
- The Makefile for build automation and configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% OpenSSL Implementation Subgraph
    subgraph "OpenSSL Implementation"
        R_OS["Receiver – EC Key Loader & Decryptor (OpenSSL)"]:::receiver
        T_OS["Transmitter – Ephemeral Key Generator, Shared Key & Encryptor (OpenSSL)"]:::transmitter
        R_OS -->|"sends_PublicKey+Curve"| T_OS
        T_OS -->|"returns_EphemeralPublicKey+IV+tag+ciphertext"| R_OS
    end

    %% WolfSSL Implementation Subgraph
    subgraph "WolfSSL Implementation"
        R_WS["Receiver – EC Key Loader & Decryptor (WolfSSL)"]:::receiver
        T_WS["Transmitter – Ephemeral Key Generator, Shared Key & Encryptor (WolfSSL)"]:::transmitter
        R_WS -->|"sends_PublicKey+Curve"| T_WS
        T_WS -->|"returns_EphemeralPublicKey+IV+tag+ciphertext"| R_WS
    end

    %% Supporting Components Subgraph
    subgraph "Supporting Components"
        OS_Crypto["OpenSSL Crypto Operations (AES-GCM & ECC)"]:::crypto
        WS_Crypto["WolfSSL Crypto Operations (AES-GCM & ECC)"]:::crypto
        MF["Makefile (Build Automation)"]:::build
        FD["Flow Diagram"]:::doc
        FC["Flow Config"]:::doc
        RD["README.md (Project Documentation)"]:::doc
    end

    %% Link cryptographic operations with implementations
    R_OS --- OS_Crypto
    T_OS --- OS_Crypto
    R_WS --- WS_Crypto
    T_WS --- WS_Crypto

    %% Link build automation to implementations (symbolic dependency)
    MF --- R_OS
    MF --- T_OS
    MF --- R_WS
    MF --- T_WS

    %% Link documentation nodes (non-functional pointers)
    FD --- FC
    FD --- RD

    %% Click Events for Receiver and Transmitter in OpenSSL
    click R_OS "https://github.com/insanum/ecies/blob/master/ecies_openssl.c"
    click T_OS "https://github.com/insanum/ecies/blob/master/ecies_openssl.c"

    %% Click Events for Receiver and Transmitter in WolfSSL
    click R_WS "https://github.com/insanum/ecies/blob/master/ecies_wolfssl.c"
    click T_WS "https://github.com/insanum/ecies/blob/master/ecies_wolfssl.c"

    %% Click Events for Cryptographic Operations
    click OS_Crypto "https://github.com/insanum/ecies/blob/master/ecies_openssl.c"
    click WS_Crypto "https://github.com/insanum/ecies/blob/master/ecies_wolfssl.c"

    %% Click Events for Data Flow Documentation, Build, and README
    click FD "https://github.com/insanum/ecies/blob/master/flow/ecies_flow.mmd"
    click FC "https://github.com/insanum/ecies/blob/master/flow/ecies_flow.cfg"
    click MF "https://github.com/insanum/ecies/tree/master/Makefile"
    click RD "https://github.com/insanum/ecies/blob/master/README.md"

    %% Styles
    classDef receiver fill:#f8c291,stroke:#333,stroke-width:2px,color:#000;
    classDef transmitter fill:#82ccdd,stroke:#333,stroke-width:2px,color:#000;
    classDef crypto fill:#badc58,stroke:#333,stroke-width:2px,color:#000;
    classDef build fill:#ffbe76,stroke:#333,stroke-width:2px,color:#000;
    classDef doc fill:#f6e58d,stroke:#333,stroke-width:2px,color:#000;
```
