uricrypt 0.1.0

Hierarchy-preserving deterministic URI encryption
Documentation

URICrypt

A Rust library for encrypting URIs while preserving their hierarchical structure and common prefixes.

Features

  • Prefix-Preserving Encryption: URIs with shared paths maintain identical encrypted prefixes, enabling efficient caching and storage
  • Deterministic Encryption: Same inputs always produce the same encrypted output
  • URL-Safe Output: Generates clean URLs without padding characters using base64 URL-safe encoding

Installation

Add this to your Cargo.toml:

[dependencies]
uricrypt = "0.1.0"

Usage

Basic Example

use uricrypt::{encrypt_uri, decrypt_uri};

fn main() {
    let uri = "https://example.com/api/v1/users";
    let secret_key = b"your-secret-key-min-32-bytes-recommended";
    let context = b"MyApp-v1.0";

    // Encrypt the URI
    let encrypted = encrypt_uri(uri, secret_key, context);
    println!("Encrypted: {}", encrypted);

    // Decrypt it back
    let decrypted = decrypt_uri(&encrypted, secret_key, context).unwrap();
    assert_eq!(uri, decrypted);
}

Prefix Preservation

URIs sharing common paths will have identical encrypted prefixes:

let key = b"secret-key";
let ctx = b"app-context";

let uri1 = "https://api.example.com/v1/users/123";
let uri2 = "https://api.example.com/v1/users/456";
let uri3 = "https://api.example.com/v2/posts";

let enc1 = encrypt_uri(uri1, key, ctx);
let enc2 = encrypt_uri(uri2, key, ctx);
let enc3 = encrypt_uri(uri3, key, ctx);

// enc1 and enc2 share the same prefix for "https://api.example.com/v1/users/"
// All three share the prefix for "https://api.example.com/"

API Reference

encrypt_uri

pub fn encrypt_uri(uri: &str, secret_key: &[u8], context: &[u8]) -> String

Encrypts a URI while preserving its hierarchical structure.

Parameters:

  • uri: The URI to encrypt (must contain "://")
  • secret_key: Secret key for encryption (use at least 32 bytes)
  • context: Additional context for domain separation (e.g., app version)

Returns: URL-safe base64 encoded encrypted URI

decrypt_uri

pub fn decrypt_uri(
    encrypted_base64: &str,
    secret_key: &[u8],
    context: &[u8],
) -> Result<String, String>

Decrypts a URI encrypted with encrypt_uri.

Parameters:

  • encrypted_base64: The encrypted URI as URL-safe base64
  • secret_key: Same secret key used for encryption
  • context: Same context used for encryption

Returns: Ok(String) with the original URI, or Err(String) if decryption fails

Security Considerations

  • Key Management: Use a cryptographically secure random key of at least 32 bytes
  • Context Binding: The context parameter provides domain separation - use it to bind encryption to specific applications or versions
  • Deterministic: This is deterministic encryption - identical URIs encrypted with the same key/context produce identical ciphertexts
  • Authentication: Each URI component includes a 16-byte authentication tag that prevents tampering
  • Algorithm: Uses TurboShake128 (SHA-3 family) for key derivation and stream generation

Use Cases

  • Privacy-Preserving Caching: Cache encrypted URLs while maintaining cache hierarchy
  • Log Anonymization: Store and analyze sensitive URLs in logs without exposing actual endpoints
  • Compliant Data Storage: Meet data residency requirements while maintaining URL structure