221 lines
6.3 KiB
Markdown
221 lines
6.3 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
|
|
- **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:
|
|
|
|
```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
|
|
|
|
- CMake 3.10+
|
|
- C++17 compatible compiler
|
|
- Crypto++ (via vcpkg)
|
|
- nlohmann/json (via vcpkg)
|
|
|
|
### Compilation
|
|
|
|
```bash
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
cmake --build . --config Release
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Simple Text Paste
|
|
|
|
```c
|
|
#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
|
|
|
|
```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
|
|
|
|
See [LICENSE](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 |