attributes

README

Attributes

ABAC systems rely on "attributes", and Virtru itself chooses to represent attributes as canonical URIs for convenience's sake, but the word "attribute" by itself is too generic for implementation use.

To avoid confusion this codebase uses the following terms for the following "parts" of an attribute:

Assuming an example attribute in the following URI form: https://derp.com/attr/Blob/value/Green ->

• Attribute Namespace = https://derp.com
• Attribute Name = Blob
• Attribute Canonical Name = Attribute Namespace + Attribute Name = https://derp.com/attr/Blob
• Attribute Value = Green
• Attribute Instance = Attribute Namespace + Attribute Name + Attribute Specific value = https://derp.com/attr/Blob/value/Green
• Attribute Definition = Metadata (rule type: allof/anyof/hierarchy, etc, allowed values) associated with a specific Attribute Canonical Name

Attribute Instances are basically just Attribute Definitions, but taken with a specific Attribute Value.

Every Attribute Instance necessarily has a corresponding Attribute Definition. Multiple Attribute Instances may share the same Attribute Definition.

Example

If an Attribute Definition for the Canonical Name https://derp.com/attr/Blob defined the following allowed Attribute Values: [Green, Red, Blue, Purple] for that Canonical Name:

then there would be 4 possible unique Attribute Instances for that single Attribute Definition:

https://derp.com/attr/Blob/value/Green https://derp.com/attr/Blob/value/Red https://derp.com/attr/Blob/value/Blue https://derp.com/attr/Blob/value/Purple

1. These Attribute Instances all share the same Canonical Name
2. These Attribute Instances all share the same Attribute Definition
3. These Attribute Instances may be mapped to either data or entities in an ABAC system

Struct representations

• AttributeDefinition
• AttributeInstance

Documentation

Index

• func ClusterByAuthority[attrCluster Clusterable](attrs []attrCluster) map[string][]attrCluster
• func ClusterByCanonicalName[attrCluster Clusterable](attrs []attrCluster) map[string][]attrCluster
• type AttributeDefinition
  • func (attrdef AttributeDefinition) GetAuthority() string
  • func (attrdef AttributeDefinition) GetCanonicalName() string
• type AttributeInstance
  • func ParseInstanceFromParts(namespace, name, value string) (AttributeInstance, error)
  • func ParseInstanceFromURI(attributeURI string) (AttributeInstance, error)
  • func (attrdef AttributeInstance) GetAuthority() string
  • func (attr AttributeInstance) GetCanonicalName() string
  • func (attr AttributeInstance) String() string
• type Clusterable

Functions

func ClusterByAuthority

func ClusterByAuthority[attrCluster Clusterable](attrs []attrCluster) map[string][]attrCluster

ClusterByAuthority takes a slice of Clusterables, and returns them as a map, where the map is keyed by each unique Authorities (e.g. 'https://myauthority.org') found in the slice of Clusterables

func ClusterByCanonicalName

func ClusterByCanonicalName[attrCluster Clusterable](attrs []attrCluster) map[string][]attrCluster

ClusterByCanonicalName takes a slice of Clusterables (AttributeInstance OR AttributeDefinition), and returns them as a map, where the map is keyed by each unique CanonicalName (e.g. Authority+Name, 'https://myauthority.org/attr/<name>') found in the slice of Clusterables

Types

type AttributeDefinition

type AttributeDefinition struct {
	Authority string `json:"authority"`
	Name      string `json:"name"`
	Rule      string `json:"rule"`
	State     string `json:"state,omitempty"`
	//'order' contains all the valid values an Instance of this Definition may
	//have. If the `rule` is == hierarchy, then the ordering of these values implies
	//their hierarchical position.
	Order   []string           `json:"order"`
	GroupBy *AttributeInstance `json:"group_by,omitempty"`
}

AttributeDefinition describes metadata about the attribute - it's name, it's authority, it's rule, it's valid values, etc.

Instances, not Definitions, are compared for access decisions.

An AttributeDefinition is not "an attribute" and cannot be used for access decisions, it simply described how a given AttributeInstance should be compared.

Every Instance has a parent Definition, but not every Definition has an Instance.

func (AttributeDefinition) GetAuthority

func (attrdef AttributeDefinition) GetAuthority() string

Returns the authority of this AttributeDefinition:

<scheme>://<hostname>

func (AttributeDefinition) GetCanonicalName

func (attrdef AttributeDefinition) GetCanonicalName() string

Returns the canonical URI representation of this AttributeDefinition:

<scheme>://<hostname>/attr/<name>

type AttributeInstance

type AttributeInstance struct {
	Authority string `json:"authority"`
	Name      string `json:"name"`
	Value     string `json:"value"`
}

AttributeInstance is created by selecting the Authority, Name and a specific Value from an AttributeDefinition.

An AttributeInstance is a single, unique attribute, with a single value.

Applied to an entity, the AttributeInstance becomes an entity attribute. Applied to data, the AttributeInstance becomes a data attribute.

When making an access decisions, these two kinds of AttributeInstances are compared with each other.

Example AttributeInstance: https://derp.com/attr/Blob/value/Green ->

Authority = https://derp.com
Name = Blob
CanonicalName = Authority + Name https://derp.com/attr/Blob
Value = Green

func ParseInstanceFromParts

func ParseInstanceFromParts(namespace, name, value string) (AttributeInstance, error)

Accepts attribute namespace, name and value strings, and returns an AttributeInstance

func ParseInstanceFromURI

func ParseInstanceFromURI(attributeURI string) (AttributeInstance, error)

Accepts a valid attribute instance URI (authority + name + value in the canonical format 'https://example.org/attr/MyAttrName/value/MyAttrValue') and returns an AttributeInstance.

Strings that are not valid URLs will result in a parsing failure, and return an error.

func (AttributeInstance) GetAuthority

func (attrdef AttributeInstance) GetAuthority() string

func (AttributeInstance) GetCanonicalName

func (attr AttributeInstance) GetCanonicalName() string

For cases where just the canonical name of this AttributeInstance is required (e.g. <authority>/attr/<name> - the authority and name, but not the value):

<authority>/attr/<name>

func (AttributeInstance) String

func (attr AttributeInstance) String() string

Implement the standard "stringify" interface and return a string in the canonical AttributeInstance format of

<authority>/attr/<name>/value/<value>

type Clusterable

type Clusterable interface {
	// Type constraint (generics)
	// Both AttributeDefinitions and AttributeInstances are clusterable
	AttributeInstance | AttributeDefinition

	// Returns the canonical URI representation of this clusterable thing, in the format
	//  <scheme>://<hostname>/attr/<name>
	GetCanonicalName() string
	// Returns the authority of this clusterable thing, in the format
	//  <scheme>://<hostname>
	GetAuthority() string
}

Clusterable is an interface that either AttributeInstances or AttributeDefinitions can implement, to support easily "clustering" or grouping a slice of either by their shared CanonicalName or Authority.