| # SKUNKSLAB FEDERATED BRICK PROTOCOL |
|
|
| ## BRICK = Bound Repository Integrity & Cryptographic Kernel |
|
|
| **Version:** 1.0 |
| **Status:** Formal Specification |
| **Date:** 2026-08-12 |
|
|
| --- |
|
|
| ## Overview |
|
|
| BRICK is a federated repository integrity and identity sealing scheme that combines: |
| - **SHA3-256**: Deterministic content/tree hashing |
| - **AES-256-GCM**: Authenticated encryption for sealed manifests |
| - **SAML 2.0**: Federated identity binding and assertion |
|
|
| Each repository becomes a content-addressed "brick" that can be instantly validated or rejected by federation nodes via cryptographic verification. |
|
|
| --- |
|
|
| ## Core Architecture |
|
|
| ``` |
| Repository Tree |
| ↓ canonicalize |
| Manifest(repo_id, commit, paths, file_hashes, policy) |
| ↓ SHA3-256 |
| ROOT_HASH |
| ↓ AES-256-GCM encrypt |
| SEALED_BRICK |
| ↓ SAML bind |
| FEDERATED_BRICK_RECEIPT |
| ``` |
|
|
| --- |
|
|
| ## Cryptographic Primitives |
|
|
| ### 1. File-Level Hashing |
|
|
| ``` |
| H_file = SHA3-256(file_bytes) |
| ``` |
|
|
| For each file in the repository, compute its SHA3-256 digest. |
|
|
| ### 2. Repository Tree Hash |
|
|
| ``` |
| H_tree = SHA3-256( |
| repo_id || |
| commit_id || |
| sort(path_i || H_file_i) |
| ) |
| ``` |
|
|
| - Concatenate repository ID and commit ID |
| - Sort all (path, file_hash) pairs lexicographically |
| - Hash the canonical representation |
| |
| This ensures: |
| - ✓ Same content always produces same hash (deterministic) |
| - ✓ Any file change is instantly detectable |
| - ✓ Canonical ordering prevents collision attacks |
| |
| ### 3. BRICK Identifier |
| |
| ``` |
| BRICK_ID = SHA3-256( |
| "SKUNKSLAB-BRICK-v1" || |
| H_tree || |
| federation_id || |
| policy_id |
| ) |
| ``` |
| |
| - Include protocol version to prevent downgrade |
| - Include federation ID (separates federated domains) |
| - Include policy ID (encodes governance rules) |
| - This becomes the Authenticated Associated Data (AAD) for encryption |
|
|
| ### 4. Sealed Material via AES-256-GCM |
|
|
| ``` |
| K_repo = derive_key(master_secret, repo_id, federation_id) |
| nonce = random(96 bits) |
| |
| C, TAG = AES-256-GCM( |
| K_repo, |
| nonce, |
| manifest, |
| AAD = BRICK_ID || repo_id || federation_id |
| ) |
| ``` |
|
|
| - Derive encryption key from master secret (never use SAML material as key) |
| - Generate random nonce for each encryption |
| - Encrypt the full manifest (includes all metadata) |
| - Authentication tag ensures integrity and binds identity |
|
|
| ### 5. SAML Identity Binding |
|
|
| The SAML assertion provides: |
| - Federation issuer (which federation node issued this) |
| - Subject (who owns/authored the repository) |
| - Assertion ID (unique identifier within federation) |
| - Timestamp and signature |
|
|
| **Important:** SAML is NOT used as cryptographic key material. Instead: |
| - Derive AES key independently via secure key derivation (HKDF, Argon2, etc.) |
| - Bind SAML identity metadata into the AAD |
| - Verify SAML signature separately from AES-GCM tag |
|
|
| --- |
|
|
| ## BRICK Receipt Structure |
|
|
| ```json |
| { |
| "brick_id": "SHA3_DIGEST_HEX", |
| "repository_hash": "H_TREE_HEX", |
| "ciphertext_hash": "SHA3_256(C || TAG)_HEX", |
| "saml_issuer": "federation.example.com", |
| "saml_subject": "user@example.com", |
| "saml_assertion_id": "uuid", |
| "policy_id": "policy_v1", |
| "timestamp": "2026-08-12T11:03:00Z", |
| "nonce": "BASE64_ENCODED_NONCE", |
| "ciphertext": "BASE64_ENCODED_C", |
| "auth_tag": "BASE64_ENCODED_TAG" |
| } |
| ``` |
|
|
| --- |
|
|
| ## Verification Algorithm |
|
|
| Federation nodes verify a BRICK receipt as follows: |
|
|
| ### Step 1: Recompute H_tree |
| ``` |
| H_tree' = SHA3-256( |
| repo_id || |
| commit_id || |
| sort(path_i || H_file_i) |
| ) |
| |
| Assert H_tree' == receipt.repository_hash |
| ``` |
| |
| ### Step 2: Verify SAML Assertion |
| ``` |
| saml_cert = fetch_issuer_certificate(receipt.saml_issuer) |
| Assert verify_signature(receipt.saml_assertion, saml_cert) == TRUE |
| Assert receipt.saml_subject matches authorization policy |
| ``` |
| |
| ### Step 3: Recompute BRICK_ID |
| ``` |
| BRICK_ID' = SHA3-256( |
| "SKUNKSLAB-BRICK-v1" || |
| H_tree' || |
| receipt.federation_id || |
| receipt.policy_id |
| ) |
| |
| Assert BRICK_ID' == receipt.brick_id |
| ``` |
| |
| ### Step 4: Verify AES-GCM Authentication |
| ``` |
| K_repo' = derive_key(master_secret, repo_id, federation_id) |
| TAG' = AES-256-GCM-VERIFY( |
| K_repo', |
| receipt.nonce, |
| receipt.ciphertext, |
| AAD = receipt.brick_id || repo_id || federation_id |
| ) |
| |
| Assert TAG' == receipt.auth_tag |
| ``` |
| |
| ### Step 5: Decrypt and Validate Manifest |
| ``` |
| manifest = AES-256-GCM-DECRYPT( |
| K_repo', |
| receipt.nonce, |
| receipt.ciphertext, |
| receipt.auth_tag, |
| AAD = receipt.brick_id || repo_id || federation_id |
| ) |
| |
| Assert manifest.policy_id == receipt.policy_id |
| Assert manifest.federation_id == receipt.federation_id |
| ``` |
| |
| **If all steps pass:** BRICK is valid and can be accepted. |
| **If any step fails:** BRICK is invalid and must be rejected instantly. |
| |
| --- |
| |
| ## Federation Policy Binding |
| |
| Each BRICK includes a `policy_id` that encodes: |
| - Which federation nodes are allowed to hold this brick |
| - What operations are permitted (read, write, fork, merge) |
| - Governance rules (voting thresholds, audit requirements) |
| - Revocation mechanisms |
| |
| The policy is included in: |
| 1. The BRICK_ID computation (makes it part of the identity) |
| 2. The AES-GCM AAD (makes it authenticated) |
| 3. The SAML assertion (binds it to issuing authority) |
| |
| --- |
| |
| ## Security Properties |
| |
| ### Integrity |
| - ✓ SHA3-256 detects any single-bit change |
| - ✓ AES-GCM authentication tag prevents forgery |
| - ✓ SAML signature prevents issuer spoofing |
| |
| ### Authenticity |
| - ✓ SAML assertion binds to federated identity |
| - ✓ AES-GCM tag proves encryption wasn't tampered with |
| - ✓ Policy binding ensures only authorized federations accept |
| |
| ### Confidentiality |
| - ✓ AES-256-GCM protects manifest contents |
| - ✓ Nonce randomization prevents replay |
| - ✓ Key derivation prevents key reuse across repos |
| |
| ### Availability |
| - ✓ No key escrow (each repo has independent derived key) |
| - ✓ Stateless verification (no server required) |
| - ✓ Instant rejection (no expensive validation) |
| |
| --- |
| |
| ## Implementation Checklist |
| |
| - [ ] SHA3-256 hash computation (use libssl or libgcrypt) |
| - [ ] AES-256-GCM encryption/decryption with nonce handling |
| - [ ] HKDF key derivation from master secret |
| - [ ] SAML 2.0 assertion parsing and signature verification |
| - [ ] BRICK receipt JSON serialization |
| - [ ] Verification algorithm implementation |
| - [ ] Federation policy enforcement |
| - [ ] Test suite (positive + negative cases) |
| - [ ] Performance benchmarking |
| - [ ] Documentation and examples |
| |
| --- |
| |
| ## Example: BRICK Sealing a Repository |
| |
| ```rust |
| // Input: repository contents |
| let repo_id = "snapkitty/ledger-core"; |
| let commit_id = "a1b2c3d4"; |
| let files = vec![ |
| ("src/main.rs", "sha3_hash_here"), |
| ("src/lib.rs", "sha3_hash_there"), |
| ]; |
|
|
| // Step 1: Compute H_tree |
| let h_tree = sha3_256( |
| format!("{}||{}", repo_id, commit_id) + |
| &canonical_sort_and_concat(files) |
| ); |
|
|
| // Step 2: Compute BRICK_ID |
| let brick_id = sha3_256( |
| format!("SKUNKSLAB-BRICK-v1||{}||{}||policy_v1", h_tree, "fed.example.com") |
| ); |
| |
| // Step 3: Derive AES key |
| let k_repo = hkdf_derive(master_secret, repo_id, "fed.example.com"); |
| |
| // Step 4: Encrypt manifest |
| let (ciphertext, tag) = aes_256_gcm_encrypt( |
| k_repo, |
| random_nonce_96bits(), |
| manifest_json, |
| aad = format!("{}||{}||fed.example.com", brick_id, repo_id) |
| ); |
|
|
| // Step 5: Create BRICK receipt |
| let receipt = BrickReceipt { |
| brick_id, |
| repository_hash: h_tree, |
| ciphertext_hash: sha3_256(&format!("{}{}", ciphertext, tag)), |
| saml_issuer: "fed.example.com", |
| saml_subject: "alice@fed.example.com", |
| policy_id: "policy_v1", |
| timestamp: now(), |
| // ... other fields |
| }; |
| |
| // Return receipt (can be broadcast to federation) |
| receipt.to_json() |
| ``` |
| |
| --- |
| |
| ## References |
| |
| - **NIST FIPS 202**: SHA-3 Standard |
| - **NIST SP 800-38D**: GCM and GMAC Mode |
| - **OASIS SAML 2.0 Standard**: Assertions and Protocols |
| - **RFC 5869**: HMAC-based Extract-and-Expand Key Derivation Function (HKDF) |
| |
| --- |
| |
| ## Implementation status |
| |
| This document specifies a protocol design. The receipt examples and verification pseudocode are not a tested implementation. No end-to-end SAML, encryption, or repository-seal interoperability run is recorded here. Validate canonicalization, key management, replay handling, and each verification step before treating a receipt as evidence of repository integrity. |
| |
| See the [security guide](SECURITY.md) for the separate engine evidence and authorization mechanisms. |
| |
