327 lines
8.3 KiB
Markdown
327 lines
8.3 KiB
Markdown
# PrivateBin API C++ DLL Design Document
|
|
|
|
## 1. Overview
|
|
|
|
This document describes the design of a cross-platform C++ DLL that implements the PrivateBin API. The DLL will provide functions to interact with PrivateBin servers, allowing applications to create, retrieve, and delete pastes programmatically. The library will be compatible with both Windows and Linux platforms.
|
|
|
|
### 1.1 Purpose
|
|
|
|
The purpose of this library is to provide a simple, cross-platform C++ interface for interacting with PrivateBin services. PrivateBin is a minimalist, open-source online pastebin where the server has zero knowledge of stored data. All data is encrypted and decrypted in the browser using 256-bit AES encryption.
|
|
|
|
### 1.2 Scope
|
|
|
|
The library will implement the following functionality:
|
|
- Creating new pastes with optional expiration, formatting, and security settings
|
|
- Retrieving existing pastes by ID
|
|
- Deleting pastes using the deletion token
|
|
- Cross-platform compatibility (Windows and Linux)
|
|
- Support for PrivateBin API versions 1.3 and later
|
|
|
|
## 2. Architecture
|
|
|
|
### 2.1 System Overview
|
|
|
|
```
|
|
+---------------------+
|
|
| Application |
|
|
+----------+----------+
|
|
|
|
|
+----------v----------+
|
|
| PrivateBin C++ DLL |
|
|
| |
|
|
| +----------------+ |
|
|
| | HTTP Client | |
|
|
| +----------------+ |
|
|
| +----------------+ |
|
|
| | Crypto Module | |
|
|
| +----------------+ |
|
|
| +----------------+ |
|
|
| | JSON Parser | |
|
|
| +----------------+ |
|
|
+----------+----------+
|
|
|
|
|
+----------v----------+
|
|
| PrivateBin Server |
|
|
+---------------------+
|
|
```
|
|
|
|
### 2.2 Component Description
|
|
|
|
1. **HTTP Client Layer**: Responsible for all network communication with PrivateBin servers
|
|
2. **Crypto Module**: Handles all encryption/decryption operations using AES-GCM
|
|
3. **JSON Parser**: Manages serialization and deserialization of API requests/responses
|
|
4. **API Interface**: Provides the public interface for library users
|
|
|
|
### 2.3 Cross-Platform Considerations
|
|
|
|
To ensure compatibility across Windows and Linux:
|
|
- Use standard C++ libraries where possible
|
|
- Abstract platform-specific functionality behind common interfaces
|
|
- Use CMake as the build system for cross-platform compilation
|
|
- Handle character encoding differences between platforms
|
|
|
|
## 3. API Endpoints Reference
|
|
|
|
### 3.1 Request/Response Schema
|
|
|
|
The PrivateBin API uses JSON for communication. All requests must include the header `X-Requested-With: JSONHttpRequest`.
|
|
|
|
#### 3.1.1 Retrieve Paste
|
|
- **Method**: GET
|
|
- **Endpoint**: `/[pasteID]`
|
|
- **Request Data**: None
|
|
- **Response**: paste.jsonld
|
|
|
|
#### 3.1.2 Create Paste
|
|
- **Method**: POST
|
|
- **Endpoint**: `/`
|
|
- **Request Data**: paste.jsonld (without pasteID)
|
|
- **Response**: `{"status": 0, "id": "[pasteID]", "url": "[serverAddress?pasteID]", "deletetoken": "[deleteToken]"}`
|
|
|
|
#### 3.1.3 Delete Paste
|
|
- **Method**: DELETE/POST
|
|
- **Endpoint**: `/`
|
|
- **Request Data**: `{"pasteid": "[pasteID]", "deletetoken": "[deletetoken]}`
|
|
- **Response**: `{"status":0, "id": "[pasteID]"}`
|
|
|
|
#### 3.1.4 Error Response
|
|
- **Response**: `{"status":1, "message": "[errormessage]"}`
|
|
|
|
### 3.2 Authentication Requirements
|
|
|
|
No authentication is required for basic paste operations. All encryption/decryption happens client-side. The deletion token is required for deleting pastes.
|
|
|
|
## 4. Data Models
|
|
|
|
### 4.1 Paste Data Structure
|
|
|
|
```json
|
|
{
|
|
"v": 2,
|
|
"adata": [...],
|
|
"ct": "base64(cipher_text)",
|
|
"meta": {
|
|
"expire": "5min",
|
|
"created": 1234567890,
|
|
"time_to_live": 300,
|
|
"icon": "data:image/png;base64,..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 Paste Metadata Structure
|
|
|
|
```json
|
|
[
|
|
[
|
|
"base64(cipher_iv)",
|
|
"base64(kdf_salt)",
|
|
100000,
|
|
256,
|
|
128,
|
|
"aes",
|
|
"gcm",
|
|
"zlib"
|
|
],
|
|
"plaintext",
|
|
0,
|
|
0
|
|
]
|
|
```
|
|
|
|
## 5. Business Logic Layer
|
|
|
|
### 5.1 Encryption Process
|
|
|
|
The encryption process follows these steps:
|
|
|
|
1. **Key Generation**:
|
|
- Generate a random 32-byte paste key
|
|
- If password provided: paste_passphrase = paste_key + paste_password
|
|
- If no password: paste_passphrase = paste_key
|
|
|
|
2. **Data Preparation**:
|
|
- Create paste_data JSON structure
|
|
- Compress with zlib if enabled
|
|
|
|
3. **Key Derivation**:
|
|
- Generate 8-byte random salt
|
|
- Apply PBKDF2-HMAC-SHA256 with 100,000 iterations
|
|
- Derive 256-bit key
|
|
|
|
4. **Encryption**:
|
|
- Generate 16-byte random IV
|
|
- Encrypt with AES-GCM
|
|
- Generate 128-bit authentication tag
|
|
|
|
5. **URL Generation**:
|
|
- Encode paste_key with Base58
|
|
- Construct URL: `server_url + paste_id + "#" + encoded_key`
|
|
|
|
### 5.2 Decryption Process
|
|
|
|
1. **Key Extraction**:
|
|
- Extract Base58-encoded key from URL fragment
|
|
- Decode to 32-byte paste key
|
|
|
|
2. **Data Retrieval**:
|
|
- Fetch paste data from server
|
|
- Extract metadata and ciphertext
|
|
|
|
3. **Decryption**:
|
|
- Derive key using PBKDF2
|
|
- Decrypt with AES-GCM
|
|
- Verify authentication tag
|
|
|
|
4. **Data Decompression**:
|
|
- Decompress with zlib if needed
|
|
- Parse JSON structure
|
|
|
|
## 6. Implementation Details
|
|
|
|
### 6.1 Dependencies
|
|
|
|
The library will depend on the following components:
|
|
|
|
1. **HTTP Client**:
|
|
- Windows: WinHTTP or WinINet
|
|
- Linux: libcurl
|
|
- Cross-platform alternative: cpp-httplib
|
|
|
|
2. **Cryptography**:
|
|
- Crypto++ or Botan for AES-GCM encryption
|
|
- Custom or existing implementation for PBKDF2
|
|
- zlib for compression
|
|
|
|
3. **JSON Processing**:
|
|
- nlohmann/json or rapidjson
|
|
|
|
4. **Base58 Encoding**:
|
|
- Custom implementation or existing library
|
|
|
|
### 6.2 Public API Interface
|
|
|
|
```cpp
|
|
// Core API functions
|
|
int create_paste(const char* server_url, const char* content,
|
|
const char* password, const char* expiration,
|
|
const char* format, int burn_after_reading,
|
|
int open_discussion, char** paste_url,
|
|
char** delete_token);
|
|
|
|
int get_paste(const char* server_url, const char* paste_id,
|
|
const char* key, char** content);
|
|
|
|
int delete_paste(const char* server_url, const char* paste_id,
|
|
const char* delete_token);
|
|
```
|
|
|
|
### 6.3 Error Handling
|
|
|
|
The library will use error codes to indicate the result of operations:
|
|
- 0: Success
|
|
- 1: Network error
|
|
- 2: Encryption/decryption error
|
|
- 3: Invalid input
|
|
- 4: Server error
|
|
- 5: JSON parsing error
|
|
|
|
## 7. Cross-Platform Implementation
|
|
|
|
### 7.1 Build System
|
|
|
|
Using CMake for cross-platform builds:
|
|
|
|
```cmake
|
|
# CMakeLists.txt
|
|
cmake_minimum_required(VERSION 3.10)
|
|
project(PrivateBinAPI)
|
|
|
|
set(CMAKE_CXX_STANDARD 17)
|
|
|
|
# Platform-specific configurations
|
|
if(WIN32)
|
|
# Windows-specific settings
|
|
add_definitions(-DWINDOWS)
|
|
elseif(UNIX)
|
|
# Linux-specific settings
|
|
add_definitions(-DLINUX)
|
|
endif()
|
|
|
|
# Add library sources
|
|
add_library(privatebinapi SHARED
|
|
src/privatebinapi.cpp
|
|
src/http_client.cpp
|
|
src/crypto.cpp
|
|
src/json_parser.cpp
|
|
)
|
|
|
|
# Link dependencies
|
|
target_link_libraries(privatebinapi ${DEPENDENCIES})
|
|
```
|
|
|
|
### 7.2 Platform Abstraction
|
|
|
|
```cpp
|
|
// http_client.h
|
|
#ifdef WINDOWS
|
|
#include <windows.h>
|
|
#include <winhttp.h>
|
|
#elif LINUX
|
|
#include <curl/curl.h>
|
|
#endif
|
|
|
|
class HttpClient {
|
|
public:
|
|
bool get(const std::string& url, std::string& response);
|
|
bool post(const std::string& url, const std::string& data,
|
|
std::string& response);
|
|
bool put(const std::string& url, const std::string& data,
|
|
std::string& response);
|
|
bool delete_req(const std::string& url, const std::string& data,
|
|
std::string& response);
|
|
};
|
|
```
|
|
|
|
## 8. Security Considerations
|
|
|
|
### 8.1 Cryptographic Requirements
|
|
|
|
1. **Encryption Algorithm**: AES-256-GCM
|
|
2. **Key Derivation**: PBKDF2-HMAC-SHA256 with 100,000 iterations
|
|
3. **Random Number Generation**: Use platform-specific secure random generators
|
|
4. **Key Storage**: Keys are never stored; they exist only in memory during operations
|
|
|
|
### 8.2 Data Protection
|
|
|
|
1. All encryption/decryption happens client-side
|
|
2. No plaintext data is sent over the network
|
|
3. Sensitive data in memory is cleared after use
|
|
4. Secure string handling to prevent memory dumps
|
|
|
|
## 9. Testing Strategy
|
|
|
|
### 9.1 Unit Testing
|
|
|
|
Unit tests will cover:
|
|
- Encryption/decryption functions
|
|
- Base58 encoding/decoding
|
|
- JSON serialization/deserialization
|
|
- HTTP client functionality
|
|
- Error handling
|
|
|
|
### 9.2 Integration Testing
|
|
|
|
Integration tests will verify:
|
|
- End-to-end paste creation and retrieval
|
|
- Cross-platform compatibility
|
|
- Error scenarios and edge cases
|
|
- Performance benchmarks
|
|
|
|
### 9.3 Test Framework
|
|
|
|
- Google Test for unit testing
|
|
- Mock HTTP servers for integration testing
|
|
- Cross-platform test execution
|
|
|