Skip to content

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.

Sign up for GitHub

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

Jump to bottom
Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

feat(sdk): custom assertion provider #2687

wants to merge 10 commits into from

Conversation

pflynn-virtru
Copy link
Member

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

Proposed Changes

Checklist

  • I have added or updated unit tests
  • I have added or updated integration tests (if appropriate)
  • I have added or updated documentation

Testing Instructions

@pflynn-virtru
feat(sdk): add custom assertion provider interfaces for external signing
5842fe2 
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
@github-actions github-actions bot added comp:sdk A software development kit, including library, for client applications and inter-service communicati comp:examples size/xl labels Sep 4, 2025
@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Sep 4, 2025

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 169.826476ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 96.310574ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 345.257234ms
Throughput 289.64 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 36.942498007s
Average Latency 367.265958ms
Throughput 135.35 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 25.777301652s
Average Latency 257.070745ms
Throughput 193.97 requests/second

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Sep 5, 2025

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 184.171883ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 96.676921ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 347.09613ms
Throughput 288.10 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 36.589224949s
Average Latency 363.7831ms
Throughput 136.65 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 25.609274398s
Average Latency 255.299414ms
Throughput 195.24 requests/second

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Sep 5, 2025

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 181.710987ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 102.207188ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 355.455849ms
Throughput 281.33 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 38.242845277s
Average Latency 380.34329ms
Throughput 130.74 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 26.248033022s
Average Latency 261.388463ms
Throughput 190.49 requests/second

@pflynn-virtru pflynn-virtru marked this pull request as ready for review September 5, 2025 17:29
@pflynn-virtru pflynn-virtru requested review from a team as code owners September 5, 2025 17:29
@github-actions GitHub Actions
Copy link
Contributor

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 166.974401ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 86.580955ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 348.725865ms
Throughput 286.76 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 36.678728922s
Average Latency 365.05833ms
Throughput 136.32 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 25.299112154s
Average Latency 252.187565ms
Throughput 197.64 requests/second

@pflynn-virtru
feat(examples): improve assertion provider setup in decrypt command
7d5f435 
Enhance `--magic-word` handling with a more robust assertion provider setup, including default validation using `NoopAssertionValidationProvider` and state-aware `MagicWordAssertionProvider`.
@github-actions GitHub Actions
Copy link
Contributor

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 168.187219ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 107.203728ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 356.702927ms
Throughput 280.35 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 37.777895113s
Average Latency 375.988804ms
Throughput 132.35 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 26.129911958s
Average Latency 260.095998ms
Throughput 191.35 requests/second

@pflynn-virtru
refactor(examples, sdk): simplify assertion provider setup in decrypt…
15e708b 
… 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.
@pflynn-virtru
refactor(sdk): remove new assertion_binding.go implementation
a67f4cd 
Streamline SDK by removing unused `assertion_binding.go`, including obsolete legacy binding logic and functions for TDF assertion handling.
@github-actions GitHub Actions
Copy link
Contributor

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 172.742883ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 97.878579ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 354.388525ms
Throughput 282.18 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 37.270893901s
Average Latency 370.606763ms
Throughput 134.15 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 25.701914861s
Average Latency 255.525215ms
Throughput 194.54 requests/second

@github-actions GitHub Actions
Copy link
Contributor

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 178.572034ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 97.796969ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 354.655887ms
Throughput 281.96 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 36.924851193s
Average Latency 366.87036ms
Throughput 135.41 requests/second

NANOTDF Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 25.58324034s
Average Latency 255.073549ms
Throughput 195.44 requests/second

@pflynn-virtru
refactor(sdk, examples): replace default signing providers with publi…
37807d6 
…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.
@pflynn-virtru
refactor(sdk): enhance assertion handling and validation flow
4092840 
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.
@pflynn-virtru
refactor(sdk, examples): replace payload key mechanism with public ke…
5b64102 
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
comp:examples comp:sdk A software development kit, including library, for client applications and inter-service communicati size/xl
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@pflynn-virtru