GitHub - Mineru98/client-side-cryptography
Key Points
- 1This project introduces a secure web application that implements a fully automated JSON encryption and decryption system, ensuring transparent, end-to-end secure communication between client and server.
- 2It leverages AES-256-GCM encryption, utilizing a Go-based WebAssembly module for client-side processing and Express.js middleware for automatic server-side handling, with specific API routes configured for mandatory encryption.
- 3The system aims to provide robust security for sensitive data exchanges, such as user authentication and CRUD operations, while offering a developer-friendly experience by abstracting the underlying cryptographic processes, and is easily deployable via Docker.
This paper describes a web security system designed to provide fully automated bidirectional encryption and decryption for JSON data transmitted between a client (browser) and a server (Express.js). The core methodology revolves around transparently encrypting and decrypting JSON payloads using AES-256-GCM, leveraging WebAssembly for high-performance client-side cryptographic operations, and server-side middleware for automated processing.
System Architecture and Data Flow:
The system comprises a "Client Layer" and a "Server Layer" communicating via "Network Communication."
- Client-Side Encryption Flow:
- A client-side browser initiates a request with a plaintext JSON object.
- This JSON data is routed through
crypto-utils.js, a JavaScript utility layer that orchestrates the encryption process. crypto-utils.jsoffloads the actual cryptographic operations to a WebAssembly (Wasm) module. This Wasm module is compiled from a Go encryption engine, enabling high-performance, near-native execution of cryptographic primitives within the browser's sandbox.- The Go encryption engine within the Wasm module performs AES-256-GCM encryption on the JSON data. The output is an encrypted, Base64-encoded string.
- This encrypted JSON data, typically in a wrapped format (e.g., as part of a
POSTbody), is then sent over the network.
- Server-Side Decryption and Processing Flow:
- Upon receiving an encrypted request, the Express.js server intercepts it.
- A dedicated "automatic encryption middleware" within the Express.js application processes the incoming data.
- This middleware invokes a server-side
crypto.jsmodule (written in Node.js) to decrypt the Base64-encoded encrypted JSON. - The
crypto.jsmodule performs AES-256-GCM decryption, restoring the original plaintext JSON data. - The decrypted JSON data is then passed to the server's business logic for processing.
- Server-Side Encryption and Client-Side Decryption Flow (Response):
- After the business logic processes the request and generates a plaintext JSON response, this response is returned to the automatic encryption middleware.
- The middleware, again using the
crypto.jsmodule, encrypts the response JSON using AES-256-GCM, producing another Base64-encoded encrypted string. - This encrypted response is sent back over the network to the client.
- On the client side, the encrypted response is received by the
crypto-utils.jslayer. - Similar to the request flow,
crypto-utils.jsutilizes the WebAssembly crypto module (Go engine) to decrypt the incoming data. - The WebAssembly module performs AES-256-GCM decryption, restoring the original plaintext JSON response, which is then made available to the client-side application (e.g., for UI rendering or further processing).
Technical Details and Security Specifications:
The cryptographic operations adhere to the following specifications:
- Algorithm: AES-256-GCM.
- Key Size: 256 bits (32 bytes).
- Initialization Vector (IV) Size: 96 bits (12 bytes).
- Authentication Tag Size: 128 bits (16 bytes).
- Encoding: Base64 for encrypted data transmission.
The system implements path-based security, where all endpoints under /api/secure/* are automatically encrypted and decrypted, while other paths can opt for selective encryption. This provides flexibility while ensuring sensitive data always benefits from end-to-end encryption. Key management is handled via environment variables for the encryption key, and production environments are strongly recommended to use HTTPS for transport layer security. The design emphasizes transparency for developers, allowing them to work with plaintext JSON objects while the underlying communication remains encrypted.