267 lines
8.0 KiB
Markdown
267 lines
8.0 KiB
Markdown
# NOSTR Core Library - Usage Guide
|
|
|
|
## Overview
|
|
|
|
The NOSTR Core Library (`libnostr_core`) is a self-contained, exportable C library for NOSTR protocol implementation. It requires **no external cryptographic dependencies** (no OpenSSL, no libwally) and can be easily integrated into other projects.
|
|
|
|
## Key Features
|
|
|
|
- **Self-Contained Crypto**: All cryptographic operations implemented from scratch
|
|
- **Zero External Dependencies**: Only requires standard C library, cJSON, and libwebsockets
|
|
- **Cross-Platform**: Builds on Linux, macOS, Windows (with appropriate toolchain)
|
|
- **NIP-06 Compliant**: Proper BIP39/BIP32 implementation for key derivation
|
|
- **Thread-Safe**: Core cryptographic functions are stateless and thread-safe
|
|
- **Easy Integration**: Simple C API with clear error handling
|
|
|
|
## File Structure for Export
|
|
|
|
### Core Library Files (Required)
|
|
```
|
|
libnostr_core/
|
|
├── nostr_core.h # Main public API header
|
|
├── nostr_core.c # Core implementation
|
|
├── nostr_crypto.h # Crypto implementation header
|
|
├── nostr_crypto.c # Self-contained crypto implementation
|
|
├── Makefile # Build configuration
|
|
└── cjson/ # JSON library (can be replaced with system cJSON)
|
|
├── cJSON.h
|
|
└── cJSON.c
|
|
```
|
|
|
|
### Optional Files
|
|
```
|
|
├── examples/ # Usage examples (helpful for integration)
|
|
├── LIBRARY_USAGE.md # This usage guide
|
|
├── SELF_CONTAINED_CRYPTO.md # Crypto implementation details
|
|
└── CROSS_PLATFORM_GUIDE.md # Platform-specific build notes
|
|
```
|
|
|
|
## Integration Methods
|
|
|
|
### Method 1: Static Library Integration
|
|
|
|
1. **Copy Required Files**:
|
|
```bash
|
|
cp nostr_core.h nostr_core.c nostr_crypto.h nostr_crypto.c /path/to/your/project/
|
|
cp -r cjson/ /path/to/your/project/
|
|
```
|
|
|
|
2. **Build Static Library**:
|
|
```bash
|
|
gcc -c -fPIC nostr_core.c nostr_crypto.c cjson/cJSON.c
|
|
ar rcs libnostr_core.a nostr_core.o nostr_crypto.o cJSON.o
|
|
```
|
|
|
|
3. **Link in Your Project**:
|
|
```bash
|
|
gcc your_project.c -L. -lnostr_core -lm -o your_project
|
|
```
|
|
|
|
### Method 2: Direct Source Integration
|
|
|
|
Simply include the source files directly in your project:
|
|
|
|
```c
|
|
// In your project
|
|
#include "nostr_core.h"
|
|
|
|
// Compile with:
|
|
// gcc your_project.c nostr_core.c nostr_crypto.c cjson/cJSON.c -lm
|
|
```
|
|
|
|
### Method 3: Shared Library Integration
|
|
|
|
1. **Build Shared Library**:
|
|
```bash
|
|
make libnostr_core.so
|
|
```
|
|
|
|
2. **Install System-Wide** (optional):
|
|
```bash
|
|
sudo cp libnostr_core.so /usr/local/lib/
|
|
sudo cp nostr_core.h /usr/local/include/
|
|
sudo ldconfig
|
|
```
|
|
|
|
3. **Use in Projects**:
|
|
```bash
|
|
gcc your_project.c -lnostr_core -lm
|
|
```
|
|
|
|
## Basic Usage Example
|
|
|
|
```c
|
|
#include "nostr_core.h"
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
|
|
int main() {
|
|
// Initialize the library
|
|
if (nostr_init() != NOSTR_SUCCESS) {
|
|
fprintf(stderr, "Failed to initialize NOSTR library\n");
|
|
return 1;
|
|
}
|
|
|
|
// Generate a keypair
|
|
unsigned char private_key[32];
|
|
unsigned char public_key[32];
|
|
|
|
if (nostr_generate_keypair(private_key, public_key) != NOSTR_SUCCESS) {
|
|
fprintf(stderr, "Failed to generate keypair\n");
|
|
nostr_cleanup();
|
|
return 1;
|
|
}
|
|
|
|
// Convert to hex and bech32
|
|
char private_hex[65], public_hex[65];
|
|
char nsec[100], npub[100];
|
|
|
|
nostr_bytes_to_hex(private_key, 32, private_hex);
|
|
nostr_bytes_to_hex(public_key, 32, public_hex);
|
|
nostr_key_to_bech32(private_key, "nsec", nsec);
|
|
nostr_key_to_bech32(public_key, "npub", npub);
|
|
|
|
printf("Private Key: %s\n", private_hex);
|
|
printf("Public Key: %s\n", public_hex);
|
|
printf("nsec: %s\n", nsec);
|
|
printf("npub: %s\n", npub);
|
|
|
|
// Create and sign an event
|
|
cJSON* event = nostr_create_text_event("Hello NOSTR!", private_key);
|
|
if (event) {
|
|
char* event_json = cJSON_Print(event);
|
|
printf("Signed Event: %s\n", event_json);
|
|
free(event_json);
|
|
cJSON_Delete(event);
|
|
}
|
|
|
|
// Cleanup
|
|
nostr_cleanup();
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
## Dependency Management
|
|
|
|
### Required Dependencies
|
|
- **Standard C Library**: malloc, string functions, file I/O
|
|
- **Math Library**: `-lm` (for cryptographic calculations)
|
|
- **cJSON**: JSON parsing (included, or use system version)
|
|
|
|
### Optional Dependencies
|
|
- **libwebsockets**: Only needed for relay communication functions
|
|
- **System cJSON**: Can replace bundled version
|
|
|
|
### Minimal Integration (Crypto Only)
|
|
If you only need key generation and signing:
|
|
|
|
```bash
|
|
# Build with minimal dependencies
|
|
gcc -DNOSTR_CRYPTO_ONLY your_project.c nostr_crypto.c -lm
|
|
```
|
|
|
|
## Cross-Platform Considerations
|
|
|
|
### Linux
|
|
- Works out of the box with GCC
|
|
- Install build-essential: `sudo apt install build-essential`
|
|
|
|
### macOS
|
|
- Works with Xcode command line tools
|
|
- May need: `xcode-select --install`
|
|
|
|
### Windows
|
|
- Use MinGW-w64 or MSYS2
|
|
- Or integrate with Visual Studio project
|
|
|
|
### Embedded Systems
|
|
- Library is designed to work on resource-constrained systems
|
|
- No heap allocations in core crypto functions
|
|
- Stack usage is predictable and bounded
|
|
|
|
## API Reference
|
|
|
|
### Initialization
|
|
```c
|
|
int nostr_init(void); // Initialize library
|
|
void nostr_cleanup(void); // Cleanup resources
|
|
const char* nostr_strerror(int error); // Get error string
|
|
```
|
|
|
|
### Key Generation
|
|
```c
|
|
int nostr_generate_keypair(unsigned char* private_key, unsigned char* public_key);
|
|
int nostr_generate_mnemonic_and_keys(char* mnemonic, size_t mnemonic_size,
|
|
int account, unsigned char* private_key,
|
|
unsigned char* public_key);
|
|
int nostr_derive_keys_from_mnemonic(const char* mnemonic, int account,
|
|
unsigned char* private_key, unsigned char* public_key);
|
|
```
|
|
|
|
### Event Creation
|
|
```c
|
|
cJSON* nostr_create_text_event(const char* content, const unsigned char* private_key);
|
|
cJSON* nostr_create_profile_event(const char* name, const char* about,
|
|
const unsigned char* private_key);
|
|
int nostr_sign_event(cJSON* event, const unsigned char* private_key);
|
|
```
|
|
|
|
### Utilities
|
|
```c
|
|
void nostr_bytes_to_hex(const unsigned char* bytes, size_t len, char* hex);
|
|
int nostr_hex_to_bytes(const char* hex, unsigned char* bytes, size_t len);
|
|
int nostr_key_to_bech32(const unsigned char* key, const char* hrp, char* output);
|
|
nostr_input_type_t nostr_detect_input_type(const char* input);
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All functions return standardized error codes:
|
|
|
|
- `NOSTR_SUCCESS` (0): Operation successful
|
|
- `NOSTR_ERROR_INVALID_INPUT` (-1): Invalid parameters
|
|
- `NOSTR_ERROR_CRYPTO_FAILED` (-2): Cryptographic operation failed
|
|
- `NOSTR_ERROR_MEMORY_FAILED` (-3): Memory allocation failed
|
|
- `NOSTR_ERROR_IO_FAILED` (-4): File I/O operation failed
|
|
- `NOSTR_ERROR_NETWORK_FAILED` (-5): Network operation failed
|
|
|
|
## Security Considerations
|
|
|
|
1. **Private Key Handling**: Always clear private keys from memory when done
|
|
2. **Random Number Generation**: Uses `/dev/urandom` on Unix systems
|
|
3. **Memory Safety**: All buffers are bounds-checked
|
|
4. **Constant-Time Operations**: Critical crypto operations are timing-attack resistant
|
|
|
|
## Testing Your Integration
|
|
|
|
Use the provided examples to verify your integration:
|
|
|
|
```bash
|
|
# Test key generation
|
|
./examples/simple_keygen
|
|
|
|
# Test mnemonic functionality
|
|
./examples/mnemonic_generation
|
|
|
|
# Test event creation
|
|
./examples/text_event
|
|
|
|
# Test all functionality
|
|
./examples/utility_functions
|
|
```
|
|
|
|
## Support and Documentation
|
|
|
|
- See `examples/` directory for comprehensive usage examples
|
|
- Check `SELF_CONTAINED_CRYPTO.md` for cryptographic implementation details
|
|
- Review `CROSS_PLATFORM_GUIDE.md` for platform-specific notes
|
|
- All functions are documented in `nostr_core.h`
|
|
|
|
## License
|
|
|
|
This library is designed to be freely integrable into other projects. Check the individual file headers for specific licensing information.
|
|
|
|
---
|
|
|
|
**Quick Start**: Copy `nostr_core.h`, `nostr_core.c`, `nostr_crypto.h`, `nostr_crypto.c`, and the `cjson/` folder to your project, then compile with `-lm`. That's it!
|