Markus/lib-privatebin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
v0.1.8.4
lib-privatebin/README.md

16 KiB
Raw Permalink Blame History

PrivateBin API Library

A C++ library for interacting with PrivateBin servers via the JSON API v1.3.

Features

  • Text Paste Creation: Create encrypted text pastes with multiple formats
  • File Upload: Upload files as encrypted pastes
  • Paste Retrieval: Retrieve and decrypt pastes
  • Paste Deletion: Delete pastes with deletion tokens
  • End-to-End Encryption: Client-side encryption with AES-256-GCM
  • Cross-Platform: Support for Windows and Linux
  • Complete API: Implementation of all PrivateBin v1.3 API functions
  • Automated Builds: Platform-specific build scripts for easy compilation
  • Text Formatting: Support for plaintext, syntax highlighting, and markdown

Text Formatting Support

The library supports multiple text formats as defined in the PrivateBin API v1.3:

Available Formats

  • plaintext - Plain text (default format)
  • syntaxhighlighting - Syntax highlighting for code snippets
  • markdown - Markdown formatting for rich text

Format Usage

#include "libprivatebin.h"

// Plain text format
create_paste(server, content, password, expiration, "plaintext", 0, 0, &url, &token);

// Syntax highlighting for code
create_paste(server, code_content, password, expiration, "syntaxhighlighting", 0, 0, &url, &token);

// Markdown formatting
create_paste(server, markdown_content, password, expiration, "markdown", 0, 0, &url, &token);

File Upload Functionality

The library includes an upload_file function that allows you to securely upload files to PrivateBin servers:

int upload_file(const char* server_url, const char* file_path,
                const char* password, const char* expiration,
                int burn_after_reading, int open_discussion,
                char** paste_url, char** delete_token);

File Upload Parameters

  • server_url: The URL of the PrivateBin server
  • file_path: The path to the file to upload
  • password: Optional password for the paste (can be NULL)
  • expiration: Expiration time ("5min", "10min", "1hour", "1day", "1week", "1month", "1year", "never")
  • burn_after_reading: 1 for "burn after reading", 0 for "keep"
  • open_discussion: 1 for allow discussion, 0 for disable discussion
  • paste_url: Output parameter for the URL of the created paste
  • delete_token: Output parameter for the deletion token

File Upload Features

  • Binary Files: Support for all file types
  • Size Limitation: Maximum file size 100MB
  • Secure Encryption: Same cryptography as text pastes
  • Compression: Automatic zlib compression before encryption
  • Metadata: File name, size, and type are added to metadata
  • Key Derivation: PBKDF2-HMAC-SHA256 with 100,000 iterations

How File Upload Works

  1. File Reading: The file is read in binary mode
  2. Size Check: Maximum file size is limited to 100MB
  3. Encryption:
    • Generation of a random 32-byte key
    • File compression with zlib
    • Encryption with AES-256-GCM
    • Key derivation with PBKDF2-HMAC-SHA256 (100,000 iterations)
  4. Metadata: File name, size, and type are added to metadata
  5. Upload: Encrypted data is sent to the PrivateBin server
  6. URL Generation: The URL is created with the Base58-encoded key

Build Scripts

The project includes several build scripts in the scripts/ directory for different platforms and use cases.

Windows Build Scripts

Windows Build (Recommended)

File: scripts/build_windows.bat
Requirements: Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg, Git

# Run from project root
scripts\build_windows.bat

This script:

  • Automatically detects and initializes the Visual Studio environment
  • Bootstraps vcpkg if not present
  • Configures CMake with the Visual Studio 2022 generator and vcpkg toolchain
  • Builds the project in Release configuration using MSVC

Linux Build Scripts

Automated Build Script

File: scripts/build.sh
Requirements: CMake, C++17 compiler, system packages

# Make executable and run from project root
chmod +x scripts/build.sh
./scripts/build.sh

This script:

  • Automatically detects and installs required dependencies
  • Configures CMake with Unix Makefiles
  • Builds the project in Release configuration

Manual Linux Build (Recommended)

Requirements: CMake 3.10+, GCC/Clang with C++17 support, system packages

# Install dependencies (Fedora/RHEL/CentOS)
sudo dnf install cmake gcc-c++ libcurl-devel cryptopp-devel json-devel

# Install dependencies (Ubuntu/Debian)
sudo apt install cmake g++ libcurl4-openssl-dev libcrypto++-dev nlohmann-json3-dev

# Build the project
mkdir build
cd build
cmake ..
make -j$(nproc)

# Run tests
ctest --verbose

# Run example
./example/example

Linux Dependencies:

  • libcurl-devel - HTTP client library
  • cryptopp-devel - Cryptographic library
  • json-devel - JSON parsing library
  • cmake - Build system
  • gcc-c++ - C++17 compiler

macOS Build Script

File: scripts/build.sh
Requirements: CMake, C++17 compiler, Homebrew packages

# Install dependencies via Homebrew
brew install cmake cryptopp nlohmann-json curl

# Make executable and run from project root
chmod +x scripts/build.sh
./scripts/build.sh

This script:

  • Bootstraps vcpkg if not present
  • Configures CMake with Unix Makefiles
  • Builds the project in Release configuration

Installation

Dependencies

  • CMake 3.10+
  • C++17 compatible compiler
  • Windows: Crypto++ and nlohmann/json (via vcpkg)
  • Linux: libcurl, cryptopp, and nlohmann-json (via system packages)
  • macOS: libcurl, cryptopp, and nlohmann/json (via Homebrew)

Compilation

Windows - Build via scripts/build_windows.bat

# Requires: Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg, Git
scripts\build_windows.bat

Linux - Automated Build via scripts/build.sh

# Requires: CMake, C++17 compiler, system packages
chmod +x scripts/build.sh
./scripts/build.sh

Linux - Manual Build (Recommended)

# Install dependencies (Fedora/RHEL/CentOS)
sudo dnf install cmake gcc-c++ libcurl-devel cryptopp-devel json-devel

# Install dependencies (Ubuntu/Debian)
sudo apt install cmake g++ libcurl4-openssl-dev libcrypto++-dev nlohmann-json3-dev

# Build the project
mkdir build
cd build
cmake ..
make -j$(nproc)

# Run tests and examples
ctest --verbose
./example/example

macOS - Build via scripts/build.sh

# Install dependencies via Homebrew
brew install cmake cryptopp nlohmann-json curl

# Requires: CMake, C++17 compiler, Homebrew packages
chmod +x scripts/build.sh
./scripts/build.sh

Manual Build (All Platforms)

mkdir build
cd build
cmake ..
cmake --build . --config Release

Note: The manual build method requires you to have all dependencies properly configured. For most users, the platform-specific build scripts are recommended.

Linux Compatibility: The project has been tested and successfully builds on Fedora Linux with system packages. It automatically detects the platform and uses appropriate dependency resolution methods (vcpkg for Windows, system packages for Linux/macOS).

Usage

Text Paste with Formatting

The library supports multiple text formats as defined in the PrivateBin API v1.3:

Available Formats

  • plaintext - Plain text (default)
  • syntaxhighlighting - Syntax highlighting for code
  • markdown - Markdown formatting

Basic Example

#include "libprivatebin.h"

char* paste_url = nullptr;
char* delete_token = nullptr;

int result = create_paste(
    "https://privatebin.net",
    "Hello, World!",
    NULL,           // no password
    "1day",         // expiration
    "plaintext",    // format
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Paste created: %s\n", paste_url);
    free_string(paste_url);
    free_string(delete_token);
}

Syntax Highlighting Example

const char* code_content = R"(
#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}
)";

int result = create_paste(
    "https://privatebin.net",
    code_content,
    NULL,                    // no password
    "1week",                 // expiration
    "syntaxhighlighting",    // syntax highlighting format
    0,                       // don't burn after reading
    0                        // no discussion
);

Markdown Example

const char* markdown_content = R"(
# Header

This is **bold** and *italic* text.

## Code Block
```cpp
int x = 42;
std::cout << x << std::endl;

This is a blockquote. )";

int result = create_paste( "https://privatebin.net", markdown_content, NULL, // no password "1month", // expiration "markdown", // markdown format 0, // don't burn after reading 0 // no discussion );


### File Upload

```c
char* paste_url = nullptr;
char* delete_token = nullptr;

int result = upload_file(
    "https://privatebin.net",
    "/path/to/file.txt",
    "mypassword",   // optional password
    "1week",        // expiration
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Successfully uploaded!\n");
    printf("URL: %s\n", paste_url);
    printf("Delete Token: %s\n", delete_token);
    
    // Free memory
    free_string(paste_url);
    free_string(delete_token);
}

Examples

The library contains a comprehensive example program that demonstrates both text paste and file upload functionality:

Running the Example

# Run basic example (tests all text formats)
./example

# Upload a file
./example --upload https://privatebin.net test.txt

# Upload with password and expiration
./example --upload https://privatebin.net test.txt mypassword 1week

# Upload with all options
./example --upload https://privatebin.net test.txt mypassword 1day 1 0

The basic example now demonstrates:

  • Plaintext format - Simple text pastes
  • Syntax highlighting format - Code with syntax highlighting
  • Markdown format - Rich text formatting
  • Interactive format selection - Shows available options

Example Output

The example program demonstrates:

  • Creating text pastes
  • Retrieving paste content
  • Deleting pastes
  • File upload with various options
  • Error handling for all operations

Testing

This project ships with both unit-style tests (no network required) and optional integration tests against a live PrivateBin server.

Prerequisites

  • CMake 3.10+
  • A C++17 compiler
  • Dependencies (Windows via vcpkg; Linux/macOS via system packages as documented above)

Build and run tests (MSVC on Windows)

REM From project root
scripts\build_windows.bat

REM Run tests
ctest -C Release --test-dir build --output-on-failure

Build and run tests with clang-cl + LLVM coverage (Windows)

If you want code coverage reports using LLVM tools:

  1. Install LLVM (contains llvm-profdata and llvm-cov)

    • winget install LLVM.LLVM or use the official installer (ensure tools are in PATH)

  2. Configure a separate clang-cl build with coverage enabled:

cmake -S . -B build-clang -G "Visual Studio 17 2022" -A x64 -T ClangCL ^
  -DCMAKE_TOOLCHAIN_FILE="%USERPROFILE%\vcpkg\scripts\buildsystems\vcpkg.cmake" ^
  -DVCPKG_TARGET_TRIPLET=x64-windows ^
  -DENABLE_LLVM_COVERAGE=ON ^
  -DLLVM_PROFDATA="C:/Program Files/LLVM/bin/llvm-profdata.exe" ^
  -DLLVM_COV="C:/Program Files/LLVM/bin/llvm-cov.exe"

cmake --build build-clang --config Release --target coverage_llvm
  1. Coverage outputs
    • Text report is printed in the build log
    • HTML report is written to build-clang/coverage/html/

Notes:

  • The coverage target runs the tests and then generates reports. It requires clang/clang-cl; MSVC alone is not supported for LLVM coverage instrumentation.
  • On Windows | must be escaped in regex arguments; the CMake configuration already handles this.

Integration tests against a live server

By default the integration test is disabled. Enable it by setting an environment variable before running the tests. The default server used is https://privatebin.medisoftware.org.

REM Enable integration test and optionally override the server URL
set PRIVATEBIN_IT=1
set PRIVATEBIN_SERVER=https://privatebin.medisoftware.org/

ctest -C Release --test-dir build --output-on-failure

What it does:

  • Creates a paste (three text formats: plaintext, syntax highlighting, markdown)
  • Retrieves the paste and validates content
  • Deletes the paste
  • Uploads a small file and performs the same roundtrip

Safety & disclaimers:

  • The referenced server is intended for testing and may be rate-limited or reset without notice. See its homepage for details: https://privatebin.medisoftware.org
  • Do not upload sensitive data to public test instances.

API Reference

Functions

  • create_paste() - Creates a text paste with optional formatting
  • upload_file() - Uploads a file
  • get_paste() - Retrieves a paste
  • delete_paste() - Deletes a paste
  • free_string() - Frees memory

Format Support

The create_paste() function supports the following formats as defined in the PrivateBin API v1.3:

  • plaintext - Default format for simple text
  • syntaxhighlighting - Syntax highlighting for code snippets
  • markdown - Markdown formatting for rich text

Error Codes

  • 0 - Success
  • 1 - Network error
  • 2 - Cryptographic error
  • 3 - Invalid input (e.g., file not found or too large)
  • 4 - Server error
  • 5 - JSON parsing error

Security

  • Client-Side Encryption: All data is encrypted before upload
  • AES-256-GCM: Modern encryption with authentication
  • PBKDF2: Secure key derivation with 100,000 iterations
  • Random Keys: Each paste receives a unique key
  • No Server Logs: Server cannot read encrypted data
  • File Compression: Automatic zlib compression before encryption
  • Binary Support: All file types are treated as encrypted binary data

Limitations

  • File Size: Maximum file size is 100MB
  • File Type: All file types are treated as binary data
  • Server Compatibility: Works with PrivateBin v1.3+ servers
  • Format: Files are always treated as "plaintext" (even if they are binary data)

Error Handling

The library returns detailed error codes and logs errors to the console. Common errors:

  • File not found: Check the file path
  • File too large: Reduce file size or split it up
  • Network error: Check server URL and internet connection
  • Server error: The server might be temporarily unavailable

License

See LICENSE for details.

Changelog

v0.1.1.6 (2025-08-28)

  • NEW: Full Linux compatibility with system packages
  • NEW: Automatic platform detection (Windows: vcpkg, Linux: system packages)
  • IMPROVED: Enhanced Linux build documentation and instructions
  • IMPROVED: Better dependency management for cross-platform builds
  • FIXED: CMakeLists.txt now works on both Windows and Linux without manual configuration

v0.1.1.5 (2025-08-28)

  • NEW: Enhanced text format support (plaintext, syntax highlighting, markdown)
  • NEW: Comprehensive format testing in examples and integration tests
  • IMPROVED: Better API documentation with format examples
  • IMPROVED: Enhanced test coverage for all supported formats

v0.1.1.4 (2025-08-28)

  • NEW: Automated release creation script (scripts/create_release.ps1)
  • NEW: Build scripts moved to scripts/ directory for better organization
  • IMPROVED: Enhanced build documentation with platform-specific instructions
  • IMPROVED: Better project structure and organization

v0.1.1.1 (2025-08-28)

  • NEW: Combined example program with both text and file upload functionality
  • IMPROVED: Unified command-line interface for examples
  • IMPROVED: Better error handling and user experience

v0.1.1 (2025-08-28)

  • NEW: File upload functionality added
  • NEW: upload_file() function implemented
  • NEW: Comprehensive example program
  • NEW: Extended documentation for file upload
  • IMPROVED: Better error handling
  • IMPROVED: Cross-platform compatibility