546 lines
16 KiB
Markdown
546 lines
16 KiB
Markdown
# 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](https://github.com/PrivateBin/PrivateBin/wiki/API):
|
|
|
|
### Available Formats
|
|
|
|
- **`plaintext`** - Plain text (default format)
|
|
- **`syntaxhighlighting`** - Syntax highlighting for code snippets
|
|
- **`markdown`** - Markdown formatting for rich text
|
|
|
|
### Format Usage
|
|
|
|
```c
|
|
#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:
|
|
|
|
```c
|
|
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
|
|
|
|
```cmd
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```cmd
|
|
# Requires: Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg, Git
|
|
scripts\build_windows.bat
|
|
```
|
|
|
|
#### Linux - Automated Build via scripts/build.sh
|
|
```bash
|
|
# Requires: CMake, C++17 compiler, system packages
|
|
chmod +x scripts/build.sh
|
|
./scripts/build.sh
|
|
```
|
|
|
|
#### Linux - Manual Build (Recommended)
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
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](https://github.com/PrivateBin/PrivateBin/wiki/API):
|
|
|
|
#### Available Formats
|
|
|
|
- **`plaintext`** - Plain text (default)
|
|
- **`syntaxhighlighting`** - Syntax highlighting for code
|
|
- **`markdown`** - Markdown formatting
|
|
|
|
#### Basic Example
|
|
|
|
```c
|
|
#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
|
|
|
|
```c
|
|
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
|
|
|
|
```c
|
|
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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```cmd
|
|
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:
|
|
|
|
```cmd
|
|
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
|
|
```
|
|
|
|
3) 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`.
|
|
|
|
```cmd
|
|
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](https://github.com/PrivateBin/PrivateBin/wiki/API):
|
|
|
|
- **`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](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 |