v0.10.1 release preparation (#1578)

adecaro · web-flow · commit 29ba95b7c898 · 2026-04-22T13:15:25.000+02:00
Signed-off-by: Angelo De Caro &lt;adc@zurich.ibm.com&gt;
diff --git a/docs/driverapi.md b/docs/driverapi.md
@@ -99,6 +99,121 @@ A `TokenRequest` is the primary structure submitted to the ledger. It consists o
 - **Auditing**: A dedicated section for auditor signatures and their identities.
 - **Metadata**: (Sent via transient data) Contains cleartext information required by participants and auditors to process the transaction.
 
+## Protocol Versions and Signature Security
+
+The Token SDK supports multiple protocol versions for token request signatures, providing a migration path for security improvements while maintaining backward compatibility.
+
+**Supported Protocol Versions**:
+- **Protocol V1**: Original implementation (legacy)
+- **Protocol V2**: Enhanced security implementation (recommended)
+
+### Protocol V1 (Legacy)
+
+**Implementation**: [`token/driver/request.go:marshalToMessageToSignV1`](../token/driver/request.go)
+
+**Signature Message Construction**:
+```
+SignatureMessage = ASN.1(TokenRequest) || Anchor
+```
+
+**Characteristics**:
+- Simple concatenation of ASN.1-encoded request and anchor
+- No delimiter or length prefix between components
+- Maintained for backward compatibility with existing deployments
+
+**Security Limitations**:
+- **Boundary Ambiguity**: Lack of delimiter creates potential for hash collision attacks
+- **No Input Validation**: Anchor parameter not validated for size or content
+- **Binary Data in Logs**: Error messages may expose sensitive data
+
+**Status**: ⚠️ **DEPRECATED** - Use Protocol V2 for new deployments
+
+### Protocol V2 (Recommended)
+
+**Implementation**: [`token/driver/request.go:marshalToMessageToSignV2`](../token/driver/request.go)
+
+**Signature Message Construction**:
+```go
+type SignatureMessage struct {
+    Request []byte  // ASN.1-encoded TokenRequest
+    Anchor  []byte  // Transaction anchor/ID
+}
+SignatureMessage = ASN.1(SignatureMessage)
+```
+
+**Security Improvements**:
+
+1. **Structured Format**: Uses ASN.1 structure with explicit field boundaries
+    - Prevents boundary ambiguity attacks
+    - Ensures unique mapping from (Request, Anchor) to signature message
+    - Maintains ASN.1 consistency throughout the protocol
+
+2. **Input Validation with Typed Errors**:
+    - Anchor must be non-empty (`ErrAnchorEmpty`)
+    - Anchor size limited to `MaxAnchorSize` (128 bytes) to prevent DoS (`ErrAnchorTooLarge`)
+    - Unsupported versions rejected with `ErrUnsupportedVersion`
+    - Validation occurs before signature generation
+
+3. **Secure Error Handling**:
+    - Binary data hex-encoded in error messages
+    - Prevents sensitive data exposure in logs
+    - Compatible with log aggregation systems
+
+4. **Comprehensive Documentation**:
+    - Security properties clearly documented
+    - Migration guidance provided
+    - Attack scenarios explained
+
+**Security Properties**:
+- **Collision Resistance**: Different (Request, Anchor) pairs always produce different signature messages
+- **Deterministic**: Same input always produces same output
+- **Tamper-Evident**: Any modification to Request or Anchor changes the signature message
+- **DoS Protection**: Input validation prevents resource exhaustion attacks
+
+### Migration Guide
+
+**For New Deployments**:
+- Use Protocol V2 by default
+- Configure validators to require minimum version 2
+- Benefit from enhanced security properties
+
+**For Existing Deployments**:
+
+1. **Phase 1: Deploy V2 Support**
+   ```go
+   // Deploy code supporting both V1 and V2
+   // V1 requests continue to work
+   // V2 requests are accepted
+   ```
+
+2. **Phase 2: Monitor Usage**
+   ```go
+   // V1 usage triggers deprecation warnings
+   // Monitor logs for V1 activity
+   // Plan migration timeline
+   ```
+
+3. **Phase 3: Migrate Applications**
+   ```go
+   // Update applications to use V2
+   // Test thoroughly in staging
+   // Roll out gradually
+   ```
+
+4. **Phase 4: Enforce V2**
+   ```go
+   // Configure validators with minimum version 2
+   // V1 requests rejected
+   // V1 support maintained for historical validation
+   ```
+
+**Backward Compatibility**:
+- V1 requests continue to validate correctly
+- Historical transactions remain valid
+- Regression tests ensure V1 compatibility
+- No breaking changes to existing deployments
+
+
 ## Drivers
 
 The Token SDK comes equipped with two reference drivers:
diff --git a/docs/drivers/dlogwogh.md b/docs/drivers/dlogwogh.md
@@ -1520,163 +1520,6 @@ The security of ZKAT-DLOG (NOGH) relies on:
 - Cache attacks (memory access patterns)
 - Power analysis (where applicable)
 
-
-### 12.8 Protocol Versions and Signature Security
-
-#### 12.8.1 Protocol Version Overview
-
-The Token SDK supports multiple protocol versions for token request signatures, providing a migration path for security improvements while maintaining backward compatibility.
-
-**Supported Protocol Versions**:
-- **Protocol V1**: Original implementation (legacy)
-- **Protocol V2**: Enhanced security implementation (recommended)
-
-#### 12.8.2 Protocol V1 (Legacy)
-
-**Implementation**: [`token/driver/request.go:marshalToMessageToSignV1`](../../token/driver/request.go)
-
-**Signature Message Construction**:
-```
-SignatureMessage = ASN.1(TokenRequest) || Anchor
-```
-
-**Characteristics**:
-- Simple concatenation of ASN.1-encoded request and anchor
-- No delimiter or length prefix between components
-- Maintained for backward compatibility with existing deployments
-
-**Security Limitations**:
-- **Boundary Ambiguity**: Lack of delimiter creates potential for hash collision attacks
-- **No Input Validation**: Anchor parameter not validated for size or content
-- **Binary Data in Logs**: Error messages may expose sensitive data
-
-**Status**: ⚠️ **DEPRECATED** - Use Protocol V2 for new deployments
-
-#### 12.8.3 Protocol V2 (Recommended)
-
-**Implementation**: [`token/driver/request.go:marshalToMessageToSignV2`](../../token/driver/request.go)
-
-**Signature Message Construction**:
-```go
-type SignatureMessage struct {
-    Request []byte  // ASN.1-encoded TokenRequest
-    Anchor  []byte  // Transaction anchor/ID
-}
-SignatureMessage = ASN.1(SignatureMessage)
-```
-
-**Security Improvements**:
-
-1. **Structured Format**: Uses ASN.1 structure with explicit field boundaries
-   - Prevents boundary ambiguity attacks
-   - Ensures unique mapping from (Request, Anchor) to signature message
-   - Maintains ASN.1 consistency throughout the protocol
-
-2. **Input Validation with Typed Errors**:
-   - Anchor must be non-empty (`ErrAnchorEmpty`)
-   - Anchor size limited to `MaxAnchorSize` (128 bytes) to prevent DoS (`ErrAnchorTooLarge`)
-   - Unsupported versions rejected with `ErrUnsupportedVersion`
-   - Validation occurs before signature generation
-
-3. **Secure Error Handling**:
-   - Binary data hex-encoded in error messages
-   - Prevents sensitive data exposure in logs
-   - Compatible with log aggregation systems
-
-4. **Comprehensive Documentation**:
-   - Security properties clearly documented
-   - Migration guidance provided
-   - Attack scenarios explained
-
-**Security Properties**:
-- **Collision Resistance**: Different (Request, Anchor) pairs always produce different signature messages
-- **Deterministic**: Same input always produces same output
-- **Tamper-Evident**: Any modification to Request or Anchor changes the signature message
-- **DoS Protection**: Input validation prevents resource exhaustion attacks
-
-#### 12.8.4 Migration Guide
-
-**For New Deployments**:
-- Use Protocol V2 by default
-- Configure validators to require minimum version 2
-- Benefit from enhanced security properties
-
-**For Existing Deployments**:
-
-1. **Phase 1: Deploy V2 Support**
-   ```go
-   // Deploy code supporting both V1 and V2
-   // V1 requests continue to work
-   // V2 requests are accepted
-   ```
-
-2. **Phase 2: Monitor Usage**
-   ```go
-   // V1 usage triggers deprecation warnings
-   // Monitor logs for V1 activity
-   // Plan migration timeline
-   ```
-
-3. **Phase 3: Migrate Applications**
-   ```go
-   // Update applications to use V2
-   // Test thoroughly in staging
-   // Roll out gradually
-   ```
-
-4. **Phase 4: Enforce V2**
-   ```go
-   // Configure validators with minimum version 2
-   // V1 requests rejected
-   // V1 support maintained for historical validation
-   ```
-
-**Backward Compatibility**:
-- V1 requests continue to validate correctly
-- Historical transactions remain valid
-- Regression tests ensure V1 compatibility
-- No breaking changes to existing deployments
-
-#### 12.8.5 Version Detection
-
-The protocol version is determined by the `TokenRequest` structure:
-
-```go
-func (r *TokenRequest) getVersion() int {
-    // Currently defaults to V1 for backward compatibility
-    // Future: May be determined by request structure or explicit field
-    return ProtocolV1
-}
-```
-
-**Future Enhancements**:
-- Explicit version field in `TokenRequest`
-- Automatic version negotiation
-- Per-network version policies
-
-#### 12.8.6 Security Recommendations
-
-**For Network Operators**:
-1. Deploy V2 support as soon as possible
-2. Monitor V1 usage via deprecation warnings
-3. Plan migration timeline based on network activity
-4. Set minimum version to V2 after migration complete
-5. Keep V1 support for historical transaction validation
-
-**For Application Developers**:
-1. Use V2 for all new token requests
-2. Test V2 implementation thoroughly
-3. Handle version-specific errors appropriately
-4. Document version requirements clearly
-
-**For Auditors**:
-1. Verify protocol version in audit logs
-2. Flag V1 usage in compliance reports
-3. Ensure V2 adoption in security assessments
-4. Validate signature message construction
-
----
-
 ## 13. Implementation Details
 
 ### 13.1 Error Handling
diff --git a/docs/evolution_summary.md b/docs/evolution_summary.md
