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

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

Installation

Dependencies

• CMake 3.10+
• C++17 compatible compiler
• Crypto++ (via vcpkg)
• nlohmann/json (via vcpkg)

Compilation

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

Usage

Simple Text Paste

#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);
}

File Upload

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 (creates a text paste)
./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

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
• upload_file() - Uploads a file
• get_paste() - Retrieves a paste
• delete_paste() - Deletes a paste
• free_string() - Frees memory

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