# 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