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 "privatebinapi.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

PowerShell Build (Recommended)

File: scripts/build_windows.ps1
Requirements: PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git

# Run from project root
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1

This script:

• Automatically bootstraps vcpkg if not present
• Configures CMake with Visual Studio 2022 generator
• Builds the project in Release configuration
• Creates a Windows distribution package with all artifacts

Command Line Build

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

# Run from project root
scripts\build_thinkpad.bat

This script:

• Automatically detects and initializes Visual Studio environment
• Handles vcpkg bootstrapping
• Configures CMake with proper toolchain
• Builds the project using MSVC compiler

Linux/macOS Build Script

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

# 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
• Crypto++ (via vcpkg)
• nlohmann/json (via vcpkg)

Compilation

Windows (PowerShell) - Build via scripts/build_windows.ps1

# Requires: PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1

Windows (Command Line) - Build via scripts/build_thinkpad.bat

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

Linux/macOS - Build via scripts/build.sh

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

Manual Build

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

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

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 "privatebinapi.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

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