-
Couldn't load subscription status.
- Fork 24
feat(sdk): custom assertion provider #2687
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
pflynn-virtru
wants to merge
54
commits into
main
Choose a base branch
from
feature/assertion-provider
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implement pluggable assertion signing and validation providers to enable integration with external signing mechanisms like HSMs, smart cards (CAC/PIV), and cloud KMS services. ## What's New ### Core Interfaces - Add `AssertionSigningProvider` interface for custom signing implementations - Add `AssertionValidationProvider` interface for custom validation logic - Maintain full backward compatibility with existing DEK-based assertions ### Built-in Providers - `DefaultSigningProvider/DefaultValidationProvider`: Existing DEK-based behavior - `X509SigningProvider/X509ValidationProvider`: X.509 certificate support with x5c headers - `PKCS11Provider`: Template for hardware token integration ### SDK Integration - Add `WithAssertionSigningProvider()` option for TDF creation - Add `WithReaderAssertionValidationProvider()` option for TDF reading - Automatically fall back to default providers when none specified ### Examples - Add comprehensive assertion CLI commands (sign, verify, list) - Support reading assertions from TDF files - Add `--x509-verify` flag to decrypt command for X.509 validation ## Technical Details The implementation follows a provider pattern that allows developers to: 1. Supply custom signing logic while maintaining SDK compatibility 2. Integrate with hardware security modules and smart cards 3. Use X.509 certificates for identity-based assertions 4. Maintain complete backward compatibility with existing code All providers use the standard SDK assertion binding (`assertionHash` and `assertionSig` claims) ensuring full interoperability between tools. ## Testing - Added provider interface tests with mock implementations - Added X.509 provider tests with self-signed certificates - Verified interoperability with otdfctl-created TDFs - Tested backward compatibility with existing assertions
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Enhance `--magic-word` handling with a more robust assertion provider setup, including default validation using `NoopAssertionValidationProvider` and state-aware `MagicWordAssertionProvider`.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
… command Streamline assertion provider integration: - Remove unnecessary comments and redundant field (`AssertionProvider`) in `MagicWordAssertionProvider`. - Adjust `WithAssertionProviderFactory` to use a pointer for consistency. - Update regex in `decrypt.go` for precise assertion matching.
Streamline SDK by removing unused `assertion_binding.go`, including obsolete legacy binding logic and functions for TDF assertion handling.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
…c key signing providers Transition to `PublicKeySigningProvider`, replacing `DefaultSigningProvider` for consistent key-based signing. Introduce `SystemMetadataAssertionProvider` for system metadata handling. Refine assertion provider mechanism in SDK and CLI examples.
Introduce `Verify` method in `Assertion` to validate binding signatures. Update `AssertionProvider` and `Reader` interfaces to support enhanced validation mechanisms. Replace obsolete aggregate hash logic with root signature for assertion binding. Simplify and extend implementation for better clarity and modularity.
…y-based assertions Transition `PayloadKeyProvider` to `PublicKeySigningProvider` for key-based assertions. Introduce `KeyAssertionProvider` for improved assertion setup. Update related interfaces and examples to use RSA keys for signing and validation. Streamline CLI commands for flexible assertion provider setup.
…ertionRegistry` Introduce `AssertionRegistry` as a replacement for `AssertionProviderFactory`, streamlining assertion management. Update SDK and examples to use assertion builders and validators. Replace provider terminology with builder-focused nomenclature for consistency. Modify TDF assertion setup and CLI examples for improved clarity and usability.
…igning Transition from `SignWithProvider` to `Sign` for improved assertion signing. Simplify and streamline signature generation using direct key-based mechanisms. Update related assertion handling and verification methods to align with new design.
3 tasks
…lidation Streamline assertion handling by replacing `KeyAssertionProvider` with `KeyAssertionBuilder` and `KeyAssertionValidator`. Remove obsolete signing and validation providers for clarity. Update CLI and examples to support private key-based validation registry setup. Refine TDF assertion validation flow for improved security and modularity.
…thAssertionRegistryReader` Update SDK and examples to align with updated nomenclature. Replace references to `WithAssertionProviderFactory` with `WithAssertionRegistryReader` for consistency. Adjust decrypt command and related SDK logic to reflect this change.
|
I think we should remove the |
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
…tion Include `statementValue` during `KeyAssertionBinder` setup to simplify public key statement handling. Refactor related tests and examples to use the updated constructor, improving clarity and consistency.
Eliminate `slog` logging throughout assertion-related methods and components for a leaner implementation. Simplify legacy v1 format handling by removing unnecessary logging and unused variables. Update context handling for enhanced clarity and maintainability.
…ication Improve assertion structure by adding HMAC-based cryptographic binding that combines manifest root signature and assertion content. Update verification logic to validate binding signature and assertion hash for enhanced security and consistency. Refactor example for improved clarity and extensibility.
…dation refinements Update ADR to include schema registration, refinements in binder/validator usage, enhanced fail-secure validation, and interoperability details for assertion bindings. Simplify examples and improve implementation guidance for clarity.
…rtion usage Simplify description for encryption/decryption examples with enhanced clarity. Refine assertion examples to highlight efficient operations and implementation details. Update security guidance and configuration options for better readability.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
Refactor `SystemMetadataAssertionProvider` to standardize V1 schema handling for cross-SDK compatibility and remove legacy V2 schema support. Introduce `DEKAssertionValidator` to enable fallback validation for DEK-signed assertions. Update security checks to enforce cryptographic bindings and enhance tampering detection. Adjust tests and documentation to reflect these changes.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
…ompatibility Streamline assertion signature computation by introducing reusable methods `ComputeAggregateHash` and `ComputeAssertionSignature`. Refactor `DEKAssertionValidator`, `KeyAssertionBinder`, and `SystemMetadataAssertionProvider` to adopt standardized signature handling, ensuring cross-SDK interoperability and tampering detection. Update tests and examples to reflect new behavior and schema handling refinements.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
…gnature handling Refactor assertion components to incorporate `ShouldUseHexEncoding` for encoding format detection directly from the manifest. Simplify constructors for `KeyAssertionBinder`, `DEKAssertionValidator`, and `SystemMetadataAssertionProvider` by removing redundant `useHex` and `aggregateHash` parameters. Update tests, examples, and validation logic for improved clarity, consistency, and tampering protection.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
…nifest processing Unified assertion signature computation by introducing `VerifyAssertionSignatureFormat` helper. Refactored `DEKAssertionValidator`, `SystemMetadataAssertionProvider`, and related test helpers to eliminate redundant logic and use standardized manifest processing. Enhanced tampering detection and cross-SDK compatibility with updated encoding format handling.
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Standard Benchmark Metrics Skipped or FailedBulk Benchmark Results
TDF3 Benchmark Results:
NANOTDF Benchmark Results:
|
pflynn-virtru
commented
Oct 23, 2025
| RunE: encrypt, | ||
| Args: cobra.MinimumNArgs(1), | ||
| } | ||
| encryptCmd.Flags().StringSliceVarP(&dataAttributes, "data-attributes", "a", []string{"https://example.com/attr/attr1/value/value1"}, "space separated list of data attributes") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
revert
Adds diagrams for assertions --------- Signed-off-by: Scott Hamrick <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
comp:examples
comp:sdk
A software development kit, including library, for client applications and inter-service communicati
docs
Documentation
size/xl
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposed Changes
This pull request introduces comprehensive documentation and architectural decisions to support custom assertion providers in the OpenTDF SDK. The changes focus on enabling integration with hardware-backed and cloud-based key management systems, improving troubleshooting for assertion-related errors, and ensuring extensibility and security across SDKs.
Custom Assertion Provider Architecture:
adr/decisions/2025-10-16-custom-assertion-providers.md) detailing the adoption of the Binder/Validator pattern for assertion signing and validation, supporting hardware security modules, smart cards, and cloud KMS integration.AssertionBinderandAssertionValidatorinterfaces, with schema-based dispatch and registration methods for extensible provider integration.PermissiveMode,FailFast,StrictMode) and DEK fallback logic for robust assertion validation and forward compatibility.Troubleshooting and Developer Guidance:
docs/Assertions-Troubleshooting.md) covering common errors with key loading, assertion validation, TDF creation, and decryption, along with solutions and debugging tips.These changes ensure the SDK remains secure, extensible, and developer-friendly while supporting advanced cryptographic integrations.
Checklist
Testing Instructions