Markus/lib-privatebin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

Build: successful library and example compilation; merge file upload into unified example program; update CMakeLists.txt

Browse Source
This commit is contained in:
mbusc
2025-08-28 19:51:25 +02:00
parent 0b4b5244f1
commit 5528096614
12 changed files with 570 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
README.md
View File

@ -1,301 +1,221 @@
# PrivateBin API C++ DLL
# PrivateBin API Library
A cross-platform C++ library for interacting with PrivateBin servers.
## Overview
This library provides a simple 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.
A C++ library for interacting with PrivateBin servers via the JSON API v1.3.
## Features
- Create new pastes with optional expiration, formatting, and security settings
- Retrieve existing pastes by ID
- Delete pastes using the deletion token
- Cross-platform compatibility (Windows and Linux)
- Support for PrivateBin API versions 1.3 and later
- **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
## Development & Build
## File Upload Functionality
### Prerequisites
The library includes an `upload_file` function that allows you to securely upload files to PrivateBin servers:
- CMake 3.10+
- C++17-capable compiler (MSVC 2022 or GCC/Clang)
- Git
- vcpkg (automatically bootstrapped by the Makefile)
```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
## Installation
### Dependencies
- cryptopp (Crypto++)
- nlohmann-json
- Windows: WinHTTP (SDK)
- Linux: libcurl (used automatically via vcpkg)
- CMake 3.10+
- C++17 compatible compiler
- Crypto++ (via vcpkg)
- nlohmann/json (via vcpkg)
### Quick start with Makefile (Windows & Linux)
1) Install dependencies, configure, and build:
```
make
```
2) Build and run the example:
```
make example
```
The Makefile does:
- clone and bootstrap vcpkg
- install packages from `vcpkg.json`
- configure CMake with the vcpkg toolchain
- build the library and the example
### Manual with CMake
```
# clone and bootstrap vcpkg
git clone https://github.com/microsoft/vcpkg.git "$HOME/vcpkg"
"$HOME/vcpkg/bootstrap-vcpkg.sh" # Linux/macOS
# Windows (PowerShell):
# powershell -NoProfile -ExecutionPolicy Bypass -Command "& '$env:USERPROFILE\vcpkg\bootstrap-vcpkg.bat'"
# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake"
# Build
cmake --build build --config Release
# Example
cmake -S example -B example/build -DCMAKE_BUILD_TYPE=Release
cmake --build example/build --config Release
```
### Linux (WSL/Ubuntu) – Quick start
Prerequisites (Ubuntu/Debian):
### Compilation
```bash
sudo apt-get update -y && sudo apt-get install -y \
build-essential cmake git pkg-config libcurl4-openssl-dev \
curl zip unzip tar ninja-build ca-certificates
mkdir build
cd build
cmake ..
cmake --build . --config Release
```
Bootstrap vcpkg (once):
```bash
git clone https://github.com/microsoft/vcpkg.git "$HOME/vcpkg"
"$HOME/vcpkg/bootstrap-vcpkg.sh" -disableMetrics
```
Build (library, tests, example):
```bash
export VCPKG_ROOT="$HOME/vcpkg"
cmake -S . -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build build --config Release
```
Or simply use the helper script:
```bash
bash ./build.sh
```
Run the example:
```bash
./build/example/example
```
Run tests:
```bash
ctest --test-dir build --output-on-failure
```
Artifacts:
- Library: `build/libprivatebinapi.so`
- Example binary: `build/example/example`
Notes:
- vcpkg dependencies (`cryptopp`, `nlohmann-json`) are installed automatically during CMake configure when the toolchain file is provided.
- On Linux the example links directly against the in-tree target `privatebinapi`. On Windows it additionally copies the DLL next to the example executable after build.
- PrivateBin delete operation is performed via HTTP POST (per API), not HTTP DELETE.
### Windows (PowerShell) – Build via build_thinkpad.bat
For systems with Visual Studio 2022 Build Tools (C++ workload) and vcpkg in the user profile, there is a robust build script:
```
cd C:\Users\mbusc\source\repos\lib-privatebin
./build_thinkpad.bat
```
Notes:
- Requires Visual Studio 2022 Build Tools with C++ tools and the Windows 11 SDK. If `VsDevCmd.bat` is found, the script automatically initializes the MSVC environment.
- vcpkg is bootstrapped if needed; missing dependencies (`cryptopp`, `nlohmann-json`) are installed.
- If vcpkg requires a baseline, the script sets it automatically.
Edition/Path notes:
- If you use another VS edition (e.g., Professional/Enterprise), adjust the paths in `build_thinkpad.bat`:
- `C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\VsDevCmd.bat`
- `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat`
- Alternatively, you can use `vswhere.exe` to discover the installation path:
```powershell
& 'C:\Program Files\Microsoft Visual Studio\Installer\vswhere.exe' -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath
```
## Usage
### API Functions
### Simple Text Paste
```cpp
// Create a new paste
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);
// Retrieve a paste
int get_paste(const char* server_url, const char* paste_id,
const char* key, char** content);
// Delete a paste
int delete_paste(const char* server_url, const char* paste_id,
const char* delete_token);
// Free memory allocated by the API functions
void free_string(char* str);
```
### Example
```cpp
```c
#include "privatebinapi.h"
#include <iostream>
int main() {
char* paste_url = nullptr;
char* delete_token = nullptr;
int result = create_paste(
"https://privatebin.net",
"Hello, PrivateBin!",
nullptr, // No password
"1hour", // Expire in 1 hour
"plaintext", // Plain text format
0, // Don't burn after reading
0, // No discussion
&paste_url,
&delete_token
);
if (result == 0) {
std::cout << "Paste created: " << paste_url << std::endl;
std::cout << "Delete token: " << delete_token << std::endl;
// Free allocated memory
free_string(paste_url);
free_string(delete_token);
} else {
std::cout << "Failed to create paste: " << result << std::endl;
}
return 0;
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);
}
```
## Error Codes
### File Upload
- 0: Success
- 1: Network error
- 2: Encryption/decryption error
- 3: Invalid input
- 4: Server error
- 5: JSON parsing error
```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 (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
This project is licensed under the MIT License - see the LICENSE file for details.
See [LICENSE](LICENSE) for details.
## Troubleshooting
## Changelog
- vcpkg requires a baseline / "this vcpkg instance requires a manifest with a specified baseline"
- Run in the repo root to add an initial builtin baseline to `vcpkg.json`:
```powershell
$env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
& "$env:VCPKG_ROOT\vcpkg.exe" x-update-baseline --add-initial-baseline
```
- Then configure/build again.
### 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
- Visual Studio instance not found / "could not find specified instance of Visual Studio"
- Ensure VS 2022 Build Tools or Community with C++ tools and Windows 11 SDK are installed.
- Use the Developer Command Prompt (VsDevCmd):
```powershell
cmd /c "call `"C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\Common7\\Tools\\VsDevCmd.bat`" -arch=x64 && build.bat"
```
- Or delete the build folder to clear stale CMake cache and reconfigure:
```powershell
Remove-Item -Recurse -Force build
```
- `vswhere.exe` not found
- Add the VS Installer directory to PATH for the current session:
```powershell
$env:PATH = 'C:\\Program Files\\Microsoft Visual Studio\\Installer;' + $env:PATH
```
- Or install/download `vswhere` from Microsoft and place it under the Installer folder.
- `cryptoppConfig.cmake` / `cryptopp-config.cmake` not found during CMake configure
- Make sure CMake uses vcpkg's toolchain file and that the ports are installed for the active triplet:
```powershell
$env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
& "$env:VCPKG_ROOT\vcpkg.exe" install cryptopp nlohmann-json --triplet x64-windows
```
- PowerShell line continuation issues / parser errors
- Prefer single-line commands in PowerShell (avoid backticks if unsure). The README uses single-line examples for reliability.
## LLVM/clang-cl Coverage (Windows)
Requirements:
- clang/clang-cl toolchain installed
- LLVM tools on PATH (`llvm-profdata`, `llvm-cov`)
Configure with coverage:
```powershell
cmd /c "call ""C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat"" -arch=x64 && cmake -S . -B build-llvm -G "Ninja" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang-cl -DENABLE_LLVM_COVERAGE=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=""%USERPROFILE%\vcpkg\scripts\buildsystems\vcpkg.cmake"" && cmake --build build-llvm --config Release"
```
Run coverage target (executes tests, merges profiles, generates HTML report):
```powershell
cmd /c "call ""C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat"" -arch=x64 && cmake --build build-llvm --target coverage_llvm --config Release && start build-llvm\coverage\html\index.html"
```
Notes:
- If Ninja is not available, you can use the VS generator, but Ninja is recommended for clang.
- You can override `LLVM_PROFDATA` and `LLVM_COV` cache variables to absolute tool paths if needed.
### Windows – Quick start (vcpkg + VS 2022)
Build and package using the helper script:
```powershell
$env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
if (-not (Test-Path $env:VCPKG_ROOT)) { git clone https://github.com/microsoft/vcpkg $env:VCPKG_ROOT; & "$env:VCPKG_ROOT\bootstrap-vcpkg.bat" }
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows.ps1
```
Artifacts:
- DLL/LIB in `build\Release` and packaged zip at `dist\lib-privatebin-v0.1.1.3-windows-x64.zip`
- Example: `build\example\Release\example.exe` (also included in the zip if present)
Notes:
- Ensure Visual Studio 2022 Build Tools (C++ workload) and Windows 11 SDK are installed.
- The example links against the in-tree library target. The script copies DLL/LIB/PDB (if available), headers, README, and LICENSE into the package.
### 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