go-i2p/go-i2cp
1
0
Fork 0
mirror of https://github.com/go-i2p/go-i2cp.git synced 2025-12-01 06:54:57 -05:00
Code Issues Packages Projects Releases Wiki Activity

fixup example dir

Browse Source
This commit is contained in:
eyedeekay
2025-11-22 14:29:46 -05:00
parent 6e426751d4
commit 41b106c496
6 changed files with 616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
examples/.gitignore vendored Normal file
View File

@@ -0,0 +1,6 @@
# Ignore compiled binaries in subdirectories
context-usage/context-usage
modern-crypto/modern-crypto
# Ignore test binaries
*.test

191
examples/README.md Normal file
View File

@@ -0,0 +1,191 @@
# go-i2cp Examples
This directory contains example programs demonstrating how to use the go-i2cp library.
## Available Examples
### 1. [Context Usage](context-usage/)
Demonstrates context-aware operations in go-i2cp, including:
- **Connection with Timeout**: Using `context.WithTimeout` to prevent hanging connections
- **Session Creation with Cancellation**: Manual cancellation using `context.WithCancel`
- **Graceful Shutdown**: Proper cleanup using the `Close()` method
- **Background Processing**: Running I/O loops with context support
**Features shown:**
- Context cancellation and timeout handling
- Proper error handling for context errors
- Graceful shutdown with cleanup
- Session lifecycle management
**Location:** `examples/context-usage/`
[📖 Full Documentation](context-usage/README.md)
### 2. [Modern Cryptography Demo](modern-crypto/)
Demonstrates the modern cryptographic algorithms supported by go-i2cp:
- **Ed25519 Digital Signatures**: Fast, secure signing and verification
- **X25519 Key Exchange**: ECDH for perfect forward secrecy
- **ChaCha20-Poly1305 Encryption**: Authenticated encryption with additional data
- **Stream Serialization**: I2CP protocol-compatible serialization
- **Legacy DSA Support**: Backward compatibility with older I2P versions
**Features shown:**
- Key pair generation for multiple algorithms
- Message signing and verification
- Diffie-Hellman key exchange
- Authenticated encryption/decryption
- Serialization and deserialization
- Integration with the Crypto struct
**Location:** `examples/modern-crypto/`
[📖 Full Documentation](modern-crypto/README.md)
## Running Examples
Each example is in its own subdirectory with a dedicated README.md:
```bash
# Context usage example
cd context-usage
go run context_usage.go
# Modern crypto example
cd modern-crypto
go run modern_crypto_demo.go
```
## Building Examples
Each example can be built independently:
```bash
# Build context usage
cd context-usage
go build
# Build modern crypto
cd modern-crypto
go build
```
## Common Usage Patterns
### Basic Client Connection
```go
import (
"context"
"time"
i2cp "github.com/go-i2p/go-i2cp"
)
func main() {
client := i2cp.NewClient(nil)
// Connect with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := client.Connect(ctx)
if err != nil {
// Handle error
}
defer client.Close()
// Use client...
}
```
### Session Creation
```go
session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
ctx := context.Background()
err := client.CreateSession(ctx, session)
if err != nil {
// Handle error
}
```
### Graceful Shutdown
```go
// Close will:
// - Destroy all sessions
// - Wait for pending operations (max 5 seconds)
// - Close TCP connection
err := client.Close()
if err != nil && err != i2cp.ErrClientClosed {
// Handle error
}
```
### Modern Cryptography
```go
crypto := i2cp.NewCrypto()
// Ed25519 signatures
kp, _ := crypto.Ed25519SignatureKeygen()
signature, _ := kp.Sign(message)
verified := kp.Verify(message, signature)
// X25519 key exchange
aliceKp, _ := crypto.X25519KeyExchangeKeygen()
bobKp, _ := crypto.X25519KeyExchangeKeygen()
sharedSecret, _ := aliceKp.GenerateSharedSecret(bobKp.PublicKey())
// ChaCha20-Poly1305 encryption
cipher, _ := crypto.ChaCha20Poly1305CipherKeygen()
ciphertext, _ := cipher.Encrypt(plaintext, additionalData)
decrypted, _ := cipher.Decrypt(ciphertext, additionalData)
```
## Requirements
- Go 1.18 or later
- Access to an I2P router (for actual connections)
- Default: `127.0.0.1:7654`
- Configure via `~/.i2cp.conf` or environment variables
## Notes
- Most examples will fail to fully connect without a running I2P router
- The examples demonstrate API usage even when not connected to a router
- Error handling is shown for demonstration purposes
- In production, add more robust error handling and logging
## Environment Configuration
Create `~/.i2cp.conf` to configure connection settings:
```ini
i2cp.tcp.host=127.0.0.1
i2cp.tcp.port=7654
i2cp.username=
i2cp.password=
i2cp.SSL=false
```
Or use environment variables:
```bash
export I2CP_HOME=/path/to/config
export GO_I2CP_CONF=/custom/config.conf
```
## Further Reading
- [I2CP Specification](https://geti2p.net/spec/i2cp)
- [go-i2cp Documentation](../README.md)
- [Implementation Plan](../PLAN.md)
## Contributing
Found an issue or want to add an example? Please submit a pull request or open an issue on GitHub.

92
examples/context-usage/README.md Normal file
View File

@@ -0,0 +1,92 @@
# Context Usage Example
This example demonstrates context-aware operations in the go-i2cp library.
## Features Demonstrated
- **Connection with Timeout**: Using `context.WithTimeout` to prevent hanging connections
- **Session Creation with Cancellation**: Manual cancellation using `context.WithCancel`
- **Graceful Shutdown**: Proper cleanup using the `Close()` method
- **Background Processing**: Running I/O loops with context support
## What You'll Learn
- How to use `context.Context` for timeouts and cancellation
- Proper error handling for context-related errors
- Graceful shutdown patterns with resource cleanup
- Session lifecycle management
- Background task management with context
## Running the Example
```bash
cd examples/context-usage
go run context_usage.go
```
## Building the Example
```bash
cd examples/context-usage
go build
./context-usage
```
## Example Output
The example will demonstrate four scenarios:
1. **Connection with Timeout** - Shows how to connect with a 10-second timeout
2. **Session with Cancellation** - Demonstrates manual cancellation after 5 seconds
3. **Graceful Shutdown** - Shows proper cleanup of multiple sessions
4. **Background Processing** - Demonstrates I/O processing with context
Note: Most scenarios will fail to fully execute without a running I2P router, but they demonstrate proper API usage and error handling.
## Code Highlights
### Connection with Timeout
```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := client.Connect(ctx)
// Context will automatically cancel after 10 seconds
```
### Graceful Shutdown
```go
// Close will:
// 1. Destroy all sessions
// 2. Wait for pending operations (max 5 seconds)
// 3. Close TCP connection
err := client.Close()
```
### Context Cancellation
```go
ctx, cancel := context.WithCancel(context.Background())
go func() {
time.Sleep(5 * time.Second)
cancel() // Cancel after 5 seconds
}()
err := client.CreateSession(ctx, session)
// Will fail with context cancelled error
```
## Requirements
- Go 1.18 or later
- Optional: I2P router running on `127.0.0.1:7654` for full functionality
## Related Examples
- [Modern Crypto Demo](../modern-crypto/) - Demonstrates cryptographic operations
- [Examples Overview](../) - All available examples
## Further Reading
- [Context Package Documentation](https://pkg.go.dev/context)
- [I2CP Specification](https://geti2p.net/spec/i2cp)
- [go-i2cp Main Documentation](../../README.md)

178
examples/context-usage/context_usage.go Normal file
View File

@@ -0,0 +1,178 @@
// Package main demonstrates context-aware operations in go-i2cp
//
// This example shows:
// - Using context.WithTimeout for connection timeout
// - Using context.WithCancel for manual cancellation
// - Graceful shutdown with Close()
// - Error handling for context cancellation
package main
import (
"context"
"fmt"
"log"
"time"
i2cp "github.com/go-i2p/go-i2cp"
)
func main() {
// Example 1: Connection with timeout
fmt.Println("=== Example 1: Connection with Timeout ===")
connectWithTimeout()
// Example 2: Session creation with cancellation
fmt.Println("\n=== Example 2: Session with Cancellation ===")
sessionWithCancellation()
// Example 3: Graceful shutdown
fmt.Println("\n=== Example 3: Graceful Shutdown ===")
gracefulShutdown()
// Example 4: Background processing with context
fmt.Println("\n=== Example 4: Background Processing ===")
backgroundProcessing()
}
// Example 1: Connect with a timeout to prevent hanging indefinitely
func connectWithTimeout() {
// Create client with nil callbacks (simplest case)
client := i2cp.NewClient(nil)
// Create a context with 10 second timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := client.Connect(ctx)
if err != nil {
log.Printf("Connect failed: %v", err)
return
}
defer client.Close()
fmt.Println("Connected successfully with timeout context")
}
// Example 2: Session creation with manual cancellation
func sessionWithCancellation() {
client := i2cp.NewClient(&i2cp.ClientCallBacks{})
// Create a cancellable context
ctx, cancel := context.WithCancel(context.Background())
// Simulate cancellation after 5 seconds
go func() {
time.Sleep(5 * time.Second)
log.Println("Cancelling session creation...")
cancel()
}()
err := client.Connect(ctx)
if err != nil {
log.Printf("Connect failed: %v", err)
return
}
defer client.Close()
// Create session with empty callbacks
session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
err = client.CreateSession(ctx, session)
if err != nil {
// This will likely fail due to cancellation
log.Printf("Session creation failed (expected): %v", err)
return
}
fmt.Println("Session created successfully")
}
// Example 3: Graceful shutdown with proper cleanup
func gracefulShutdown() {
client := i2cp.NewClient(&i2cp.ClientCallBacks{})
ctx := context.Background()
err := client.Connect(ctx)
if err != nil {
log.Printf("Connect failed: %v", err)
return
}
// Create multiple sessions
for i := 0; i < 3; i++ {
session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
err = client.CreateSession(ctx, session)
if err != nil {
log.Printf("Session %d creation failed: %v", i, err)
}
}
// Close will:
// 1. Destroy all sessions
// 2. Wait for pending operations (max 5 seconds)
// 3. Close TCP connection
fmt.Println("Starting graceful shutdown...")
err = client.Close()
if err != nil {
log.Printf("Close failed: %v", err)
} else {
fmt.Println("Shutdown completed successfully")
}
}
// Example 4: Background message processing with context
func backgroundProcessing() {
client := i2cp.NewClient(&i2cp.ClientCallBacks{})
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
err := client.Connect(ctx)
if err != nil {
log.Printf("Connect failed: %v", err)
return
}
defer client.Close()
// Create session with empty callbacks
session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
err = client.CreateSession(ctx, session)
if err != nil {
log.Printf("Session creation failed: %v", err)
return
}
// Process I/O in background with context cancellation support
go func() {
for {
err := client.ProcessIO(ctx)
if err != nil {
if err == i2cp.ErrClientClosed {
log.Println("Client closed, stopping I/O processing")
return
}
if err == context.Canceled || err == context.DeadlineExceeded {
log.Printf("Context cancelled: %v", err)
return
}
log.Printf("ProcessIO error: %v", err)
}
// Small delay to prevent busy loop
time.Sleep(100 * time.Millisecond)
// Check if context is done
select {
case <-ctx.Done():
log.Println("Context done, stopping processing")
return
default:
}
}
}()
// Simulate some work
time.Sleep(2 * time.Second)
fmt.Println("Background processing completed")
}

149
examples/modern-crypto/README.md Normal file
View File

@@ -0,0 +1,149 @@
# Modern Cryptography Demo
This example demonstrates the modern cryptographic algorithms supported by go-i2cp.
## Features Demonstrated
- **Ed25519 Digital Signatures**: Fast, secure signing and verification
- **X25519 Key Exchange**: ECDH for perfect forward secrecy
- **ChaCha20-Poly1305 Encryption**: Authenticated encryption with additional data (AEAD)
- **Stream Serialization**: I2CP protocol-compatible serialization
- **Legacy DSA Support**: Backward compatibility with older I2P versions
## What You'll Learn
- How to generate key pairs for multiple algorithms
- Message signing and signature verification
- Diffie-Hellman key exchange (ECDH)
- Authenticated encryption and decryption
- Serialization and deserialization of cryptographic keys
- Integration with the I2CP Crypto struct
## Running the Example
```bash
cd examples/modern-crypto
go run modern_crypto_demo.go
```
## Building the Example
```bash
cd examples/modern-crypto
go build
./modern-crypto
```
## Example Output
The demo will show:
```
=== I2CP Modern Cryptography Demo ===
✅ Crypto system initialized
🔑 Ed25519 Digital Signatures:
✅ Generated Ed25519 key pair
✅ Signed message (64 bytes signature)
✅ Signature verification successful
🔐 X25519 Key Exchange (ECDH):
✅ Generated Alice's X25519 key pair
✅ Generated Bob's X25519 key pair
✅ ECDH successful - shared secret established
🔒 ChaCha20-Poly1305 Authenticated Encryption:
✅ Created ChaCha20-Poly1305 cipher
✅ Encrypted message: 54 bytes → 70 bytes
✅ Decryption successful - message integrity verified
💾 Stream Serialization (I2CP compatibility):
✅ Ed25519 key pair serialized
✅ Ed25519 serialization/deserialization successful
🔄 Legacy DSA Support (preserved):
✅ Generated DSA key pair
✅ Legacy DSA functionality preserved
🎉 I2CP cryptography modernization complete!
```
## Code Highlights
### Ed25519 Signatures
```go
crypto := go_i2cp.NewCrypto()
kp, _ := crypto.Ed25519SignatureKeygen()
signature, _ := kp.Sign(message)
verified := kp.Verify(message, signature)
```
### X25519 Key Exchange
```go
aliceKp, _ := crypto.X25519KeyExchangeKeygen()
bobKp, _ := crypto.X25519KeyExchangeKeygen()
sharedSecret, _ := aliceKp.GenerateSharedSecret(bobKp.PublicKey())
```
### ChaCha20-Poly1305 Encryption
```go
cipher, _ := crypto.ChaCha20Poly1305CipherKeygen()
ciphertext, _ := cipher.Encrypt(plaintext, additionalData)
decrypted, _ := cipher.Decrypt(ciphertext, additionalData)
```
### Stream Serialization
```go
stream := go_i2cp.NewStream(make([]byte, 0, 1024))
kp.WriteToStream(stream)
kp2, _ := go_i2cp.Ed25519KeyPairFromStream(stream)
```
## Cryptographic Algorithms
### Ed25519
- **Type**: Digital signature algorithm
- **Security**: 128-bit security level
- **Key Size**: 32 bytes (public), 64 bytes (private)
- **Signature Size**: 64 bytes
- **Performance**: Very fast signing and verification
- **Use Case**: Message authentication, identity verification
### X25519
- **Type**: Elliptic curve Diffie-Hellman (ECDH)
- **Security**: 128-bit security level
- **Key Size**: 32 bytes (public and private)
- **Shared Secret**: 32 bytes
- **Performance**: Fast key exchange
- **Use Case**: Perfect forward secrecy, session key establishment
### ChaCha20-Poly1305
- **Type**: Authenticated encryption with additional data (AEAD)
- **Security**: 256-bit key, 128-bit authentication
- **Key Size**: 32 bytes
- **Nonce Size**: 12 bytes
- **Authentication Tag**: 16 bytes
- **Performance**: Very fast on modern CPUs
- **Use Case**: Secure message encryption, tunnel encryption
## Requirements
- Go 1.18 or later
- No I2P router required (this example works standalone)
## Related Examples
- [Context Usage](../context-usage/) - Demonstrates context-aware operations
- [Examples Overview](../) - All available examples
## Further Reading
- [Ed25519 Specification](https://ed25519.cr.yp.to/)
- [RFC 7748 - X25519](https://tools.ietf.org/html/rfc7748)
- [RFC 8439 - ChaCha20-Poly1305](https://tools.ietf.org/html/rfc8439)
- [I2CP Specification](https://geti2p.net/spec/i2cp)
- [go-i2cp Main Documentation](../../README.md)

0
examples/modern_crypto_demo.go → examples/modern-crypto/modern_crypto_demo.go
View File