Documentation
¶
Overview ¶
Experimental: This package is EXPERIMENTAL and may change or be removed at any time Package keysplit provides key splitting functionality for TDF (Trusted Data Format) encryption.
This package extracts the key splitting logic from the main SDK granter functionality, providing a clean API for:
- Analyzing policy attributes and their associated KAS (Key Access Server) grants
- Creating cryptographic key splits based on attribute rules (allOf, anyOf, hierarchy)
- Building Key Access Objects (KAOs) that can be embedded in TDF manifests
The package implements XOR-based secret sharing for key splitting, where the original Data Encryption Key (DEK) can be reconstructed by XORing all the split keys together.
Attribute Resolution Hierarchy ¶
The package respects the attribute grant hierarchy:
- Value-level grants (most specific)
- Definition-level grants
- Namespace-level grants (least specific)
Attribute Rules ¶
Different attribute rule types determine how splits are created:
- allOf: Each value gets its own split (all must be satisfied)
- anyOf: All values share the same split (any can satisfy)
- hierarchy: Ordered evaluation with precedence
Basic Usage ¶
splitter := keysplit.NewXORSplitter(
keysplit.WithDefaultKAS("https://kas.example.com"),
)
// Generate splits from policy attributes and DEK
result, err := splitter.GenerateSplits(ctx, policyValues, dek)
if err != nil {
return err
}
// Build Key Access Objects for TDF manifest
kaos, err := splitter.BuildKeyAccessObjects(result, policyBytes, metadata)
if err != nil {
return err
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Base input validation errors ErrNoAttributes = errors.New("no attributes provided") ErrInvalidDEK = errors.New("invalid DEK: must be 32 bytes") ErrEmptyDEK = errors.New("DEK cannot be empty") // Attribute resolution errors ErrInvalidAttributeFQN = errors.New("invalid attribute FQN") ErrMissingDefinition = errors.New("attribute missing definition") ErrNoKASFound = errors.New("no KAS found for attribute") ErrMissingGrants = errors.New("attribute missing grants") ErrInvalidRule = errors.New("invalid attribute rule type") // KAS and key errors ErrInvalidPublicKey = errors.New("invalid KAS public key") ErrMissingKID = errors.New("KAS key missing key identifier") ErrMissingPEM = errors.New("KAS key missing PEM data") ErrUnsupportedAlg = errors.New("unsupported key algorithm") ErrInvalidKASURL = errors.New("invalid KAS URL") // Split generation errors ErrSplitGeneration = errors.New("failed to generate key split") ErrInvalidSplitID = errors.New("invalid split ID") ErrNoSplitsGenerated = errors.New("no splits generated") ErrSplitCountMismatch = errors.New("split count mismatch") // KAO building errors ErrKAOBuild = errors.New("failed to build key access object") ErrEncryptionFailed = errors.New("failed to encrypt key") ErrPolicyBinding = errors.New("failed to create policy binding") ErrMetadataEncrypt = errors.New("failed to encrypt metadata") // Configuration errors ErrNoDefaultKAS = errors.New("no default KAS configured") ErrInvalidConfig = errors.New("invalid configuration") )
Functions ¶
This section is empty.
Types ¶
type AttributeClause ¶
type AttributeClause struct {
// Definition is the attribute definition
Definition *policy.Attribute
// Values are all values for this attribute
Values []*policy.Value
// Rule specifies how values should be combined (allOf, anyOf, hierarchy)
Rule policy.AttributeRuleTypeEnum
}
AttributeClause groups attribute values by their definition and rule
func (*AttributeClause) String ¶
func (c *AttributeClause) String() string
String returns a human-readable representation of an attribute clause
type AttributeGrant ¶
type AttributeGrant struct {
// Level indicates where this grant was found in the hierarchy
Level GrantLevel
// Attribute is the attribute definition this grant applies to
Attribute *policy.Attribute
// KASGrants contains the resolved KAS server information
KASGrants []KASGrant
}
AttributeGrant represents KAS grants resolved for a specific attribute
type BooleanExpression ¶
type BooleanExpression struct {
// Clauses contains all attribute clauses (ANDed together)
Clauses []AttributeClause
}
BooleanExpression represents the complete attribute policy as clauses
func (*BooleanExpression) String ¶
func (e *BooleanExpression) String() string
String returns a human-readable representation of the boolean expression
type GrantLevel ¶
type GrantLevel int
GrantLevel indicates where a KAS grant is defined in the attribute hierarchy
const ( // ValueLevel indicates grants defined on the attribute value (most specific) ValueLevel GrantLevel = iota // DefinitionLevel indicates grants defined on the attribute definition DefinitionLevel // NamespaceLevel indicates grants defined on the attribute namespace (least specific) NamespaceLevel )
func (GrantLevel) String ¶
func (gl GrantLevel) String() string
type KASGrant ¶
type KASGrant struct {
// URL of the KAS server
URL string
// PublicKey contains the key information
PublicKey *policy.SimpleKasPublicKey
}
KASGrant represents a single KAS server grant with its public key
type KASPublicKey ¶
type KASPublicKey struct {
// URL of the KAS server
URL string
// KID is the key identifier
KID string
// PEM is the public key in PEM format
PEM string
// Algorithm specifies the key algorithm (e.g., "rsa", "ec")
Algorithm string
}
KASPublicKey contains public key information extracted from policy
type Split ¶
type Split struct {
// ID is a unique identifier for this split (empty if only one split)
ID string
// Data contains the actual split key bytes
Data []byte
// KASURLs lists all KAS servers that can decrypt this split
KASURLs []string
}
Split represents a single cryptographic key split with its KAS assignments
type SplitAssignment ¶
type SplitAssignment struct {
// SplitID is the unique identifier for this split
SplitID string
// KASURLs lists all KAS servers for this split
KASURLs []string
// Keys maps KAS URLs to their public key information
Keys map[string]*policy.SimpleKasPublicKey
}
SplitAssignment maps a split ID to its KAS assignments and keys
type SplitResult ¶
type SplitResult struct {
// Splits contains all the generated key splits
Splits []Split
// KASPublicKeys maps KAS URLs to their public key information
KASPublicKeys map[string]KASPublicKey
}
SplitResult contains all splits and their associated KAS public keys
type Splitter ¶
type Splitter interface {
// GenerateSplits analyzes attributes and creates key splits from a DEK
GenerateSplits(ctx context.Context, attrs []*policy.Value, dek []byte) (*SplitResult, error)
}
Splitter defines the interface for key splitting implementations
type SplitterOption ¶
type SplitterOption func(*splitterConfig)
SplitterOption configures the splitter behavior
func WithDefaultKAS ¶
func WithDefaultKAS(kas *policy.SimpleKasKey) SplitterOption
WithDefaultKAS sets the default KAS with complete key information
type XORSplitter ¶
type XORSplitter struct {
// contains filtered or unexported fields
}
XORSplitter implements XOR-based secret sharing for key splitting
func NewXORSplitter ¶
func NewXORSplitter(opts ...SplitterOption) *XORSplitter
NewXORSplitter creates a new XOR-based key splitter
func (*XORSplitter) GenerateSplits ¶
func (x *XORSplitter) GenerateSplits(_ context.Context, attrs []*policy.Value, dek []byte) (*SplitResult, error)
GenerateSplits implements the main key splitting workflow
Source Files