docs: update future work sections and add encryption sigil details
This commit is contained in:
snider
parent
bdef246a87
commit
86f4e33b1a
4 changed files with 175 additions and 6 deletions
|
|
@ -344,7 +344,15 @@ Permutation seed: SHA256(entropy || "permutation")
|
|||
Mask seed: SHA256(entropy || "mask" || 0x0000000000000000)
|
||||
```
|
||||
|
||||
## 10. References
|
||||
## 10. Future Work
|
||||
|
||||
- [ ] Hardware-accelerated obfuscation implementations
|
||||
- [ ] Additional obfuscator algorithms (block-based, etc.)
|
||||
- [ ] Formal side-channel resistance analysis
|
||||
- [ ] Integration benchmarks with different AEAD ciphers
|
||||
- [ ] WASM compilation for browser environments
|
||||
|
||||
## 11. References
|
||||
|
||||
- [RFC 8439] ChaCha20 and Poly1305 for IETF Protocols
|
||||
- [RFC 7539] ChaCha20 and Poly1305 for IETF Protocols (obsoleted by 8439)
|
||||
|
|
|
|||
|
|
@ -332,7 +332,18 @@ This section defines conventions for magic number allocation:
|
|||
| `\x00\x00\x00\x00` | Reserved (null) |
|
||||
| `\xFF\xFF\xFF\xFF` | Reserved (test/invalid) |
|
||||
|
||||
### 8.2 Allocation Guidelines
|
||||
### 8.2 Registered Magic Numbers
|
||||
|
||||
The following magic numbers are registered for specific applications:
|
||||
|
||||
| Magic | Application | Description |
|
||||
|-------|-------------|-------------|
|
||||
| `SMSG` | Borg | Encrypted message/media container |
|
||||
| `STIM` | Borg | Encrypted TIM container bundle |
|
||||
| `STMF` | Borg | Secure To-Me Form (encrypted form data) |
|
||||
| `TRIX` | Borg | Encrypted DataNode archive |
|
||||
|
||||
### 8.3 Allocation Guidelines
|
||||
|
||||
Applications SHOULD:
|
||||
|
||||
|
|
@ -381,7 +392,15 @@ Future versions may define:
|
|||
- Media type registration (e.g., `application/x-trix`)
|
||||
- Magic number registry
|
||||
|
||||
## 11. References
|
||||
## 11. Future Work
|
||||
|
||||
- [ ] Media type registration (`application/x-trix`, `application/x-smsg`, etc.)
|
||||
- [ ] Formal magic number registry with registration process
|
||||
- [ ] Streaming encoding/decoding for large payloads
|
||||
- [ ] Header compression for bandwidth-constrained environments
|
||||
- [ ] Sub-container nesting specification (Trix within Trix)
|
||||
|
||||
## 12. References
|
||||
|
||||
- [RFC 8259] The JavaScript Object Notation (JSON) Data Interchange Format
|
||||
- [RFC 2119] Key words for use in RFCs to Indicate Requirement Levels
|
||||
|
|
|
|||
|
|
@ -251,7 +251,46 @@ Pretty-prints JSON data with indentation.
|
|||
| In | Indent JSON (2 spaces) |
|
||||
| Out | Passthrough |
|
||||
|
||||
### 5.5 Hash Sigils
|
||||
### 5.5 Encryption Sigils
|
||||
|
||||
Encryption sigils provide authenticated encryption using AEAD ciphers.
|
||||
|
||||
#### 5.5.1 ChaCha20-Poly1305 Sigil
|
||||
|
||||
Encrypts data using XChaCha20-Poly1305 authenticated encryption.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Name | `chacha20poly1305` |
|
||||
| Category | Reversible |
|
||||
| Key size | 32 bytes |
|
||||
| Nonce size | 24 bytes (XChaCha variant) |
|
||||
| Tag size | 16 bytes |
|
||||
| In | Encrypt (generates nonce, prepends to output) |
|
||||
| Out | Decrypt (extracts nonce from input prefix) |
|
||||
|
||||
**Critical Implementation Detail**: The nonce is embedded IN the ciphertext output, not transmitted separately:
|
||||
|
||||
```
|
||||
In(plaintext) -> [24-byte nonce][ciphertext][16-byte tag]
|
||||
Out(ciphertext_with_nonce) -> plaintext
|
||||
```
|
||||
|
||||
**Construction**:
|
||||
|
||||
```go
|
||||
sigil, err := NewChaChaPolySigil(key) // key must be 32 bytes
|
||||
ciphertext, err := sigil.In(plaintext)
|
||||
plaintext, err := sigil.Out(ciphertext)
|
||||
```
|
||||
|
||||
**Security Properties**:
|
||||
- Authenticated: Poly1305 MAC prevents tampering
|
||||
- Confidential: ChaCha20 stream cipher
|
||||
- Nonce uniqueness: Random 24-byte nonce per encryption
|
||||
- No nonce management required by caller
|
||||
|
||||
### 5.6 Hash Sigils
|
||||
|
||||
Hash sigils compute cryptographic digests. They are irreversible.
|
||||
|
||||
|
|
@ -433,13 +472,23 @@ When combining compression and encryption sigils:
|
|||
- Comparison operations should be constant-time where security-relevant
|
||||
- Hash comparisons should use constant-time comparison functions
|
||||
|
||||
## 10. References
|
||||
## 10. Future Work
|
||||
|
||||
- [ ] AES-GCM encryption sigil for environments requiring AES
|
||||
- [ ] Zstd compression sigil with configurable compression levels
|
||||
- [ ] Streaming sigil interface for large data processing
|
||||
- [ ] Sigil metadata interface for reporting transformation properties
|
||||
- [ ] WebAssembly compilation for browser-based sigil operations
|
||||
- [ ] Hardware acceleration detection and utilization
|
||||
|
||||
## 11. References
|
||||
|
||||
- [RFC 4648] The Base16, Base32, and Base64 Data Encodings
|
||||
- [RFC 1952] GZIP file format specification
|
||||
- [RFC 8259] The JavaScript Object Notation (JSON) Data Interchange Format
|
||||
- [FIPS 180-4] Secure Hash Standard
|
||||
- [FIPS 202] SHA-3 Standard
|
||||
- [RFC 8439] ChaCha20 and Poly1305 for IETF Protocols
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -451,8 +500,10 @@ When combining compression and encryption sigils:
|
|||
| `hex` | Encoding | Yes | Hexadecimal |
|
||||
| `base64` | Encoding | Yes | RFC 4648 |
|
||||
| `gzip` | Compression | Yes | RFC 1952 |
|
||||
| `zstd` | Compression | Yes | Zstandard |
|
||||
| `json` | Formatting | Partial | Compacts JSON |
|
||||
| `json-indent` | Formatting | Partial | Pretty-prints JSON |
|
||||
| `chacha20poly1305` | Encryption | Yes | XChaCha20-Poly1305 AEAD |
|
||||
| `md4` | Hash | No | 128-bit |
|
||||
| `md5` | Hash | No | 128-bit |
|
||||
| `sha1` | Hash | No | 160-bit |
|
||||
|
|
|
|||
|
|
@ -180,6 +180,7 @@ function Verify(input: string, expectedHash: string) -> bool:
|
|||
| Deduplication | Good | Identify identical content |
|
||||
| File integrity | Moderate | Use with checksum comparison |
|
||||
| Non-critical checksums | Good | Simple verification |
|
||||
| Rolling key derivation | Good | Time-based key rotation (see 6.3) |
|
||||
|
||||
### 6.2 Not Recommended Uses
|
||||
|
||||
|
|
@ -190,6 +191,54 @@ function Verify(input: string, expectedHash: string) -> bool:
|
|||
| Digital signatures | Use proper signature schemes |
|
||||
| Security-critical integrity | Use HMAC-SHA256 |
|
||||
|
||||
### 6.3 Rolling Key Derivation Pattern
|
||||
|
||||
LTHN is well-suited for deriving time-based rolling keys for streaming media or time-limited access control. The pattern combines a time period with user credentials:
|
||||
|
||||
```
|
||||
streamKey = SHA256(LTHN(period + ":" + license + ":" + fingerprint))
|
||||
```
|
||||
|
||||
#### 6.3.1 Cadence Formats
|
||||
|
||||
| Cadence | Period Format | Example | Window |
|
||||
|---------|---------------|---------|--------|
|
||||
| daily | YYYY-MM-DD | "2026-01-13" | 24 hours |
|
||||
| 12h | YYYY-MM-DD-AM/PM | "2026-01-13-AM" | 12 hours |
|
||||
| 6h | YYYY-MM-DD-HH | "2026-01-13-00" | 6 hours (00, 06, 12, 18) |
|
||||
| 1h | YYYY-MM-DD-HH | "2026-01-13-15" | 1 hour |
|
||||
|
||||
#### 6.3.2 Rolling Window Implementation
|
||||
|
||||
For graceful key transitions, implementations should support a rolling window:
|
||||
|
||||
```
|
||||
function GetRollingPeriods(cadence: string) -> (current: string, next: string):
|
||||
now = currentTime()
|
||||
current = formatPeriod(now, cadence)
|
||||
next = formatPeriod(now + periodDuration(cadence), cadence)
|
||||
return (current, next)
|
||||
```
|
||||
|
||||
Content encrypted with rolling keys includes wrapped CEKs (Content Encryption Keys) for both current and next periods, allowing decryption during period transitions.
|
||||
|
||||
#### 6.3.3 CEK Wrapping
|
||||
|
||||
```
|
||||
// Wrap CEK for distribution
|
||||
For each period in [current, next]:
|
||||
streamKey = SHA256(LTHN(period + ":" + license + ":" + fingerprint))
|
||||
wrappedCEK = ChaCha20Poly1305_Encrypt(CEK, streamKey)
|
||||
store (period, wrappedCEK) in header
|
||||
|
||||
// Unwrap CEK for playback
|
||||
For each (period, wrappedCEK) in header:
|
||||
streamKey = SHA256(LTHN(period + ":" + license + ":" + fingerprint))
|
||||
CEK = ChaCha20Poly1305_Decrypt(wrappedCEK, streamKey)
|
||||
if success: return CEK
|
||||
return error("no valid key for current period")
|
||||
```
|
||||
|
||||
## 7. Security Considerations
|
||||
|
||||
### 7.1 Not a Password Hash
|
||||
|
|
@ -282,10 +331,52 @@ Conforming implementations SHOULD:
|
|||
|
||||
Note: Key map only matches exact character codes, not normalized equivalents.
|
||||
|
||||
## 10. References
|
||||
## 10. API Reference
|
||||
|
||||
### 10.1 Go API
|
||||
|
||||
```go
|
||||
import "github.com/Snider/Enchantrix/pkg/crypt"
|
||||
|
||||
// Create crypt service
|
||||
svc := crypt.NewService()
|
||||
|
||||
// Hash with LTHN
|
||||
hash := svc.Hash(crypt.LTHN, "input string")
|
||||
|
||||
// Available hash types
|
||||
crypt.LTHN // LTHN quasi-salted hash
|
||||
crypt.SHA256 // Standard SHA-256
|
||||
crypt.SHA512 // Standard SHA-512
|
||||
// ... other standard algorithms
|
||||
```
|
||||
|
||||
### 10.2 Direct Usage
|
||||
|
||||
```go
|
||||
import "github.com/Snider/Enchantrix/pkg/crypt/std/lthn"
|
||||
|
||||
// Direct LTHN hash
|
||||
hash := lthn.Hash("input string")
|
||||
|
||||
// Verify hash
|
||||
valid := lthn.Verify("input string", expectedHash)
|
||||
```
|
||||
|
||||
## 11. Future Work
|
||||
|
||||
- [ ] Custom key map configuration via API
|
||||
- [ ] WASM compilation for browser-based LTHN operations
|
||||
- [ ] Alternative underlying hash functions (SHA-3, BLAKE3)
|
||||
- [ ] Configurable salt derivation strategies
|
||||
- [ ] Performance optimization for high-throughput scenarios
|
||||
- [ ] Formal security analysis of rolling key pattern
|
||||
|
||||
## 12. References
|
||||
|
||||
- [FIPS 180-4] Secure Hash Standard (SHA-256)
|
||||
- [RFC 4648] The Base16, Base32, and Base64 Data Encodings
|
||||
- [RFC 8439] ChaCha20 and Poly1305 for IETF Protocols
|
||||
- [Wikipedia: Leet] History and conventions of leet speak character substitution
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue