Files

elpatron 90d9a23dd2 Initial commit: PrivateBin API C++ DLL implementation

2025-08-28 09:15:47 +02:00

8.3 KiB

Raw Blame History

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

HTTP Client Layer: Responsible for all network communication with PrivateBin servers
Crypto Module: Handles all encryption/decryption operations using AES-GCM
JSON Parser: Manages serialization and deserialization of API requests/responses
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

{
  "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

[
  [
    "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:

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
Data Preparation:
- Create paste_data JSON structure
- Compress with zlib if enabled
Key Derivation:
- Generate 8-byte random salt
- Apply PBKDF2-HMAC-SHA256 with 100,000 iterations
- Derive 256-bit key
Encryption:
- Generate 16-byte random IV
- Encrypt with AES-GCM
- Generate 128-bit authentication tag
URL Generation:
- Encode paste_key with Base58
- Construct URL: server_url + paste_id + "#" + encoded_key

5.2 Decryption Process

Key Extraction:
- Extract Base58-encoded key from URL fragment
- Decode to 32-byte paste key
Data Retrieval:
- Fetch paste data from server
- Extract metadata and ciphertext
Decryption:
- Derive key using PBKDF2
- Decrypt with AES-GCM
- Verify authentication tag
Data Decompression:
- Decompress with zlib if needed
- Parse JSON structure

6. Implementation Details

6.1 Dependencies

The library will depend on the following components:

HTTP Client:
- Windows: WinHTTP or WinINet
- Linux: libcurl
- Cross-platform alternative: cpp-httplib
Cryptography:
- Crypto++ or Botan for AES-GCM encryption
- Custom or existing implementation for PBKDF2
- zlib for compression
JSON Processing:
- nlohmann/json or rapidjson
Base58 Encoding:
- Custom implementation or existing library

6.2 Public API Interface

// 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:

# 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

// 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

Encryption Algorithm: AES-256-GCM
Key Derivation: PBKDF2-HMAC-SHA256 with 100,000 iterations
Random Number Generation: Use platform-specific secure random generators
Key Storage: Keys are never stored; they exist only in memory during operations

8.2 Data Protection

All encryption/decryption happens client-side
No plaintext data is sent over the network
Sensitive data in memory is cleared after use
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

8.3 KiB Raw Blame History