Policy Markup for Device APIs

Introduction

The Devices API policy framework [[!DAP-POLICY-FRAMEWORK]] outlines the role and use of policy in the context of Device APIs. This document defines a policy markup similar to XACML 2.0 [[!XACML20]], but different.

Values and Types

Each value in an expression is conceptually a bag of potentially multiple simple values. The bag can be empty, containing no simple values. In practice almost every value encountered in the model is either an empty bag or a bag containing a single simple value. When a bag contains one or more simple values, all the simple values have the same type, one of:

String
IRI

Each modifier function defines its result type, and how the function’s effect depends on the type of the input.

Each matching function defines how it depends on the type of its input.

Where a modifier function or matching function does not specify how it treats an input of a particular type, it implicitly converts the value to a bag of strings before performing its operation.

When evaluating an access control query at a given application Execution Phase, an expression may have undetermined value if one or more of the attributes on which it depends has undetermined value at that execution phase.

For each modifier function and matching function, its result for a given set of inputs is determined if and only if all of its inputs are determined.

The syntax used for encoding a certificate fingerprint in DAP Security Policy documents is the SDP syntax defined in [[!RFC4572]] without the "fingerprint" scheme, as follows:

dapfingerprint = hash-func SP fingerprint
hash-func      = "sha-1" / "sha-224" / "sha-256" /
	         "sha-384" / "sha-512" /
                 "md5" / "md2" / token 
                 ; Additional hash functions can only come 
                 ; from updates to [[!RFC3279]]
fingerprint    = 2UHEX *(":" 2UHEX) 
                 ; Each byte in upper-case hex, separated
                 ; by colons. 
UHEX           = DIGIT / %x41-46 ; A-F uppercase

Attribute Match

An attribute match is a statement about one attribute whose truth can be evaluated, that is it evaluates to true or false (or undetermined). An attribute match is a subject match, resource match or environment match, depending on whether the attribute being matched is a subject, resource or environment attribute.

An attribute match is an expression with a boolean result whose form is limited to one of the following:

matchfunc(modifierfunc(attr), value)
matchfunc(attr, value)

Matchfunc is the matching function, a function with a boolean result and two non-boolean inputs. Its result is undetermined if either input is undetermined.

In the first case, modifierfunc is a function with a non-boolean result and a single non-boolean input. The result of modifierfunc is undetermined if its input is undetermined.

In the second case, there is no modifierfunc.

The value to match (matchfunc’s second input) is a sequence of literal text and other attribute references implicitly combined using string concatenation. Thus its type is bag containing a single string, unless there is any reference to an attribute resolving to an empty bag, in which case it is an empty bag. Any reference to a non-string attribute is converted to string bag first. Any reference to an attribute whose value is a bag containing two or more values causes the whole match value to be undefined. Any reference to an undetermined attribute causes the whole value to match to be undetermined.

For a subject attribute match, only a single literal string is allowed, with no attribute references.

If the attribute does not exist, then it has the empty bag value.

Subject Match

A subject specification consists of a conjunctive sequence of subject matches. A specification is evaluated as follows:

is determined and has value TRUE if each of the subject matches has value TRUE
otherwise, is undetermined if any or the subject matches is undetermined
otherwise is determined and has value FALSE.

A subject match is an attribute match where the attribute being matched is a subject attribute, and the match value is a literal string and does not contain any attribute references.

Target

The target of a policy or policy set identifies the set of subjects to which the policy or policy set applies.

The target consists of a disjunctive sequence of subject specifications. A target specification is evaluated as follows:

has value TRUE if at least one of the subject specifications has value TRUE
otherwise has value FALSE
A policy or policy-set that has no target explicitly specified is treated as having a target that evaluates unconditionally to TRUE.

Decision

If determined, the result of a rule or policy or policy set is a decision, either “not applicable” or any one of the effects “permit”, “prompt-blanket”, “prompt-session”, “prompt-oneshot” or “deny”.

The result of a rule or policy or policy set may be undetermined under conditions specified for each below.

Rule

A rule consists of a condition and an effect.

The result of a rule is determined if and only if its condition has determined value.

Condition

The condition of a rule specifies extra criteria that need to be matched before the rule becomes applicable.

The condition consists of one or more attribute matches, combined with AND and OR operators into an arbitrarily nested tree.

The AND operator is evaluated as follows:

is determined and has value “no match” if any input is “no match”
otherwise is undetermined if any input is undetermined
otherwise is determined and has value “match”

The OR operator is evaluated as follows:

is determined and has value “match” if any input is “match”
otherwise is undetermined if any input is undetermined
otherwise is determined and has value “no match”

Policy

A policy has a target, and a list of zero or more rules combined using a rule-combining algorithm. Where a directive attribute query finds more than one applicable directive attribute set, the first one is used.

A policy optionally has a textual description.

A policy optionally has an id. If an implementation provides a means to provision a security policy fragment to replace an existing one, this id can be used to identify the policy or policy set to replace. No management of ids is mandated, therefore it is recommended that a standardised textual representation of a UUID should be used as the id.

The result of a policy is determined if and only if its combining rule has determined value.

Policy Set

The overall security framework is a policy set.

A policy-set is a target with a list of zero or more policies and policy sets combined using a policy-combining algorithm. Where a directive attribute query finds more than one applicable directive attribute set, the first one is used.

A policy set optionally has an id. If an implementation provides a means to provision a security policy fragment to replace an existing one, this id can be used to identify the policy or policy set to replace. No management of ids is mandated, therefore it is recommended that a standardised textual representation of a UUID should be used as the id.

The result of a policy is determined if and only if its combining rule has determined value.

Policy Document

Where the implementation supports deployment of a fragment of policy to add to the existing security policy framework or to replace a part of it, the policy document is the unit of addition or replacement. A policy document can be either a policy or a policy-set.

Signed Policy Document

Where the implementation supports deployment of policy fragments as above, the signed policy documentx is the cryptographically signed unit of deployment. It contains one or more policy documents as well as a single signature.

Matching Function

The matching function used in an attribute match is one of the following.

String Equality Matching Function

True if and only if some string from one input string bag is byte-for-byte equal to some string from the other input string bag. Thus an empty bag is not equal to anything, not even another empty bag. An input of type other than empty bag or string bag is converted to string bag first.

Globbing Matching Function

True if and only if, for some string in the first input string bag, the entire string matches the glob pattern in some string in the second input string bag. If either input is the empty bag, the result is false. An input of type other than empty bag or string bag is converted to string bag first.

A glob pattern is as described in [[!SUS3]] section 2.13 Pattern Matching Notation but excluding 2.13.3 Patterns Used for Filename Expansion.

Using this function with a glob pattern of “*” (a single asterisk) is a convenient way to test whether the first input is not an empty bag.

Regular Expression Matching Function

True if and only if, for some string in the first input string bag, some part of the string matches the regular expression pattern in some string in the second input string bag. If either input is the empty bag, the result is false. An input of type other than empty bag or string bag is converted to string bag first.

This uses the definition of regular expressions in ECMAScript 3rd edition [[!ECMA-262]].

Modifier Function

The modifier function optionally specified in each attribute in a target or condition is one of the following.