This document defines policy markup for Device APIs. It is similar to the XACML 2.0 standard, but different.

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:

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 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:

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:

Decision

If determined, the result of a rule or policy or policy set is a decision, either “not applicable” or any one of the effectspermit”, “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:

The OR operator is evaluated as follows:

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.

URI-Scheme Modifier Function

If the input is a string bag, first it is converted to a URI bag by interpreting each string as a URI. Any string that does not have the form of a URI is removed from the bag.

Each URI in the bag is converted to a string by taking the URI’s scheme component.

Thus the result type is either the empty bag or string bag.

URI-Authority Modifier Function

If the input is a string bag, first it is converted to a URI bag by interpreting each string as a URI. Any string that does not have the form of a URI is removed from the bag.

Each URI in the bag is converted to a string by taking the URI’s scheme and authority components. If the URI does not have an authority component, it is removed from the bag.

Thus the result type is either the empty bag or string bag.

URI-Scheme-Authority Modifier Function

If the input is a string bag, first it is converted to a URI bag by interpreting each string as a URI. Any string that does not have the form of a URI is removed from the bag.

Each URI in the bag is converted to a string by taking the URI’s scheme and authority components. If the URI does not have an authority component, it is removed from the bag.

Thus the result type is either the empty bag or string bag.

URI-Host Modifier Function

If the input is a string bag, first it is converted to a URI bag by interpreting each string as a URI. Any string that does not have the form of a URI is removed from the bag.

Each URI in the bag is converted to a string by taking the URI’s scheme and authority components. If the URI does not have an authority component, it is removed from the bag.

Thus the result type is either the empty bag or string bag.

URI-Path Modifier Function

If the input is a string bag, first it is converted to a URI bag by interpreting each string as a URI. Any string that does not have the form of a URI is removed from the bag.

Each URI in the bag is converted to a string by taking the URI’s scheme and authority components. If the URI does not have an authority component, it is removed from the bag.

Thus the result type is either the empty bag or string bag.

Combining Algorithm

The policy-combining algorithm for a policy set determines how child policies and policy sets are combined.

The rule-combining algorithm for a policy determines how child rules are combined.

The algorithms are described in the following subsections. The term “child” is used to mean the child rules in the policy when applying the policy’s rule-combining algorithm, or the child policies and policy sets in the policy set when applying the policy set’s policy-combining algorithm.

Deny-Overrides Combining Algorithm

The Deny-Overrides Combining Algorithm is usable as a policy-combining algorithm and as a rule-combining algorithm.

The overall result of a query is evaluated as follows:

  • if any child evaluates to "deny", then the overall result is "deny";
  • otherwise, if any child is undetermined, then the overall result is undetermined;
  • otherwise, if any child evaluates to "prompt-oneshot", then the overall result is "prompt-oneshot";
  • otherwise, if any child evaluates to "prompt-session", then the overall result is "prompt-session";
  • otherwise, if any child evaluates to "prompt-blanket", then the overall result is "prompt-blanket";
  • otherwise, if any child evaluates to "permit", then the overall result is "permit";
  • otherwise, the overall result is "inapplicable".

Permit-Overrides Combining Algorithm

The Permit-Overrides Combining Algorithm is usable as a policy-combining algorithm and as a rule-combining algorithm. The overall result of a query is evaluated as follows:

  • if any child evaluates to "permit", then the overall result is "permit";
  • otherwise, if any child is undetermined, then the overall result is undetermined;
  • otherwise, if any child evaluates to "prompt-blanket", then the overall result is "prompt-blanket";
  • otherwise, if any child evaluates to "prompt-session", then the overall result is "prompt-session";
  • otherwise, if any child evaluates to "prompt-oneshot", then the overall result is "prompt-oneshot";
  • otherwise, if any child evaluates to "deny", then the overall result is "deny";
  • otherwise, the overall result is "inapplicable".

First-Applicable Rule Combining Algorithm

The First-Applicable Rule Combining Algorithm is usable as a rule-combining algorithm.

The overall result of a query is evaluated by processing the children in written order as follows:

  • if the current child is determined and does not evaluate to "inapplicable", the overall result is the result of the current child;
  • otherwise, if the current child is undetermined, the overall result is undetermined;
  • otherwise, if the current child is determined and has value "inapplicable", continue processing at the next child. If already processing the final child, the overall result is "inapplicable".

First-Matching-Target Policy Combining Algorithm

The First-Matching-Target Policy Combining Algorithm is usable as a policy-combining algorithm.

The overall result of a query is evaluated by processing the children in written order as follows:

  • if the current child has a target that matches the overall result is the result of the current child;
  • otherwise, continue processing at the next child. If already processing the final child, the overall result is "inapplicable".

Effect

The effect of a rule is one of the following:

Permit

This effect allows requested access without user interaction.

Deny

This effect denies requested access without user interaction.

Prompt-x

The prompt-oneshot, prompt-session and prompt-blanket effects allow requested access after explicit confirmation by the user. The implementation MUST prompt the user before allowing access.

The implementation MUST only provide the user the option to grant permission up to the maximum allowed by the effect, ie:

  • prompt-oneshot: "deny always", "deny this time", "allow this time";
  • prompt-session: prompt-oneshot options plus "deny for this session", "allow for this session";
  • prompt-blanket: prompt-session options plus "allow always".

The implementation MUST provide a means to respond with any available option that is applicable in the context in which the prompt is displayed.

Any default action MUST be at least as restrictive as "deny this time".

If the user has the option of deferring a response indefinitely and the user does not respond explicitly, the requested access MUST NOT be allowed.

For a widget, a session lasts while the application is still running and the terminal has not been switched off or placed in standby mode.

For a website, another visit to the same page in the same Browser tab or window is part of the same session.

Query

A query represents a specific instance of a security policy being evaluated in order to make an access control decision relating to an attempted operation by a web application.

A query is characterised by the collection of subject attributes associated with the web application instance, the collection of resource attributes associated with the attempted operation, and the collection of environment attributes associated with the circumstances of the attempt. The determinedness of each of these attributes is in accordance with the execution phase of the attempt.

A query is evaluated against a policy-set, resulting in a decision in accordance with the evaluation rules defined in this specification.

Security Policy Document Format

This section defines a method for representing a Security Policy (e.g. for interchange or device management purposes).

Schema

The <signed-policy> Element

The root element of a signed policy document is a <signed-policy>>.

<signed-policy> contains, in any order, exactly one <signature> element and one or more elements each of which is either <policy-set> or <policy>;.

The <signature> Element

The <signature> element, as a child of <signed-policy>, specifies the detached digital signature of the signed policy document as defined in XML Digital Signature [[!XMLDSIG-CORE2]], with the following additional constraints:

  • the <signature> element MUST contain one or more valid <Reference> elements;
  • the URL attribute of each <Reference> element MUST contain a reference to a <policy>; or <policy-set> element that is a sibling of the <signature> element in the same Signed Policy Document;
  • the <Reference> element MUST NOT have any <Transform> elements;
  • the widget user agent MUST treat the <signed-policy> as invalid if it has a child <policy>; or <policy-set> element for which there is no <Reference> element.

Processing of the signature is specified in section (*** change ref ***).

The <policy-set> Element

The root element of a policy document is either a <policy-set> or a <policy>;. <policy-set> has two possible attributes:

  • combine, which MUST take a value of "deny-overrides", "permit-overrides" or "first-matching-target". The attribute is optional; if it is omitted, the default value is "deny-overrides";
  • id, whose value is a textual identifier for the <policy-set>.

<policy-set> contains an optional <target>;, then zero or more <policy>; and/or <policy-set> elements.

The <rule> Element

<rule> has one possible attribute, effect, which must take a value of "permit", "prompt-blanket", "prompt-session", "prompt-oneshot" or "deny". The attribute is optional; if it is omitted, the default value is "permit".

<rule> contains an optional <condition>.

The <target> Element

<target> contains one or more <subject> elements.

The <subject> Element

<subject> contains one or more <subject-match> elements.

The <condition> Element

<condition> has one possible attribute, combine, which must take a value of "and" or "or". The attribute is optional; if it is omitted, the default value is "and".

<condition> contains one or more elements, each of which is one of <condition>, <subject-match>, <resource-match> or <environment-match>.

The <subject-match>, <resource-match>, <environment-match> Elements

<subject-match> represents a condition on a single subject attribute to be matched in a target or condition. <resource-match> represents a condition on a single resource attribute to be matched in a condition. <environment-match> represents a condition on a single environment attribute to be matched in a condition.

The element has up to three (XML) attributes:

  • (mandatory) attr: the name of the subject, resource or environment (respectively) attribute to check. The attribute name is optionally followed by one of the suffixes ".scheme", ".authority", ".scheme-authority", ".host" or ".path", causing the equivalently named URI modifier function to be applied to the attribute value before matching.
  • (optional) match: the literal text to match. If this attribute is omitted, then the contents of the element are used instead.
  • (optional) func: the match function to use. If it is present, it must be one of "equal", "glob" or "regexp". If func is omitted, then the default is "glob".

The contents of a <subject-match>, <resource-match> or <environment-match> element represent the value to match, only if the match attribute is absent. If the match attribute is present, then the element contents are ignored. For a <subject-match>, the contents are PCDATA. For the others, the contents can be any combination of PCDATA, <subject-attr>, <resource-attr> and <environment-attr> elements, giving the literal text to match after expanding any attributes.

The <subject-attr>, <resource-attr>, <environment-attr> Elements

Each of these elements represents the value of a subject, resource or environment attribute respectively.

The element has one (XML) attribute, attr, giving the name of the attribute to expand. It has no contents.

Attribute Definitions

Subject Attribute Definitions

The identity of a subject is in one of the following classes. The class determines which attributes are available; other attributes have the undefined value.

Widget Subject Attribute Definitions

Widget Subject Attributes Table
Attribute Type Value
class string This has the value "widget" if and only if the subject is a widget.
install-uri URI The URI that the widget resource was originally retrieved from before installation, if known, otherwise the empty bag.
id URI The identity of the widget. For a W3C widget specification [[!WIDGETS]] compliant widget resource, this is the value of the id attribute of the widget element in the widget configuration document converted from IRI to URI based on RFC3987 [[!IRI]]. In this case, it is a URI that uniquely identifies the widget. Empty bag if there is no id attribute.
version string Version of the widget resource. For a W3C widget specification compliant widget resource, this is the version attribute of the widget element in the widget configuration document. Empty bag if there is no version attribute.
distributor-key-cn string The common name of the end entity certificate for the applicable widget resource distributor signature. Empty bag if none.
distributor-key-fingerprint string The fingerprint of the end-entity certificate for the applicable widget resource distributor signature. Empty bag if none.
distributor-key-root-cn string The common name of the root certificate for the applicable widget resource distributor signature. Empty bag if none.
distributor-key-root-fingerprint string The fingerprint of the root certificate for the applicable widget resource distributor signature.Empty bag if none.
author-key-cn string The common name of the end entity certificate for the widget resource author signature. Empty bag if none.
author-key-fingerprint string The fingerprint of the end entity certificate for the widget resource author signature in SDP syntax. Empty bag if none.
author-key-root-cn string The common name of the root certificate for the widget resource author signature. Empty bag if none.
author-key-root-fingerprint string The fingerprint of the root certificate for the widget resource author signature. Empty bag if none.
widget-attr:name The value of the named attribute of the widget element whose type and value are set up in the widget configuration document for use in the security framework. Empty bag if no such named attribute is defined.

Web Site Subject Attribute Definitions

Website Subject Attributes Table
Attribute Type Value Meaning
class string "website" Has the value "website" if and only if the subject is of this class.
sign-schema string "" (empty string) Not signed.
sign-schema string "tls" The page was fetched using HTTPS and the browser has verified that the site certificate’s Common Name matches the host that the page was fetched from, and it has already applied its own policies regarding whether the root certificate is in an acceptable trust domain.
sign-schema string "tls-ev" As "tls", and, additionally, the site certificate has an extended validation field and the browser’s internal policy allows that information to be passed to the security framework.
uri URI The URI used to access the document that embeds or refers to the JavaScript code, corresponding to the window.location property of the browsing context. In the case of that a feature is accessed from a child browsing context (for example from within a <iframe> within some outer document), this attribute provides the location of the child context.
uri-top URI The URI used to access the website that embeds or refers to the JavaScript code, corresponding to the top.window property of the browsing context. In the case that the feature is accessed from a child browsing context (for example from within an <iframe>), this attribute provides the location of the top-level browsing context. If the current browsing context is a child of a widget top-level browsing context, this attribute contains an IRI with the widget: scheme that corresponds to the top-level containing document from the widget resource.
key-root-cn string The common name of the root certificate chained to by the site certificate. Empty bag if none.
key-root-fingerprint string The fingerprint of the root certificate chained to by the site certificate. Empty bag if none.

Resource Attribute Definitions

The resource is identified by one or more of the following attributes:

Widget Resource Attributes Table
Attribute Type Value Comment
api-feature (*** ref: ****) URI The IRI identifier of the requested Feature converted to URI as per RFC3987 [[!IRI]]. This uses the same naming scheme as in a widget’s feature element. Determined for all applicable application execution phases.
device-cap string Device capability being accessed, if any. Empty bag if none See Appendix A (*** change this ref ***). Determined for all applicable application Execution Phases.
param:name See comment The value of parameter name. The specification of each Device Capabilities lists the parameters associated with that Device Capability and the type and semantics of each. Empty bag if the parameter is not defined. Determined in the invoke execution phase. Undetermined in all other execution phases.
The following resource attributes give information on the source of the implementation of the API Feature.
feature-install-uri URI The URI that the API implementation was originally retrieved from before installation, if known, otherwise the empty bag. Determined for all applicable application execution phases.
feature-key-cn string The common name of the end entity certificate for the signature associated with the Feature implementation. Empty bag if none. Determined for all applicable application execution phases.
feature-key-root-cn string The common name of the root certificate for the signature associated with the Feature implementation. Empty bag if none Determined for all applicable application execution phases.
feature-key-root-fingerprint string The fingerprint of the root certificate of the signature associated with the Feature implementation. Empty bag if none. Determined for all applicable application execution phases.

Context Attribute Definitions

Context Attributes Table
Attribute Type Value Comment
roaming string "national", "international", or empty string Determined in the following execution phases:
  • widget-instantiate
  • website-bind
  • invoke
Undetermined in the following execution phases:
  • widget-install
bearer-type string The type of the current network bearer over which a network request will be served, either by request of the application or by default (per the current serving network or the one over which the request will be served, if multiple networks are available). A comma-separated list of one or more of the bearer types given as examples in W3C DCO [[DCONTOLOGY]]. Determined in the following execution phases:
  • widget-instantiate
  • website-bind
  • invoke
Undetermined in the following execution phases:
  • widget-install

Examples

Example Policies to mitigate Abuse Use Cases

This section outlines some example policies that could be used to deal with abuses of device APIs.

Defending against premium rate abuse

The example assumes that a number of mechanisms have already been defeated in the security chain – the application is trusted and is on the device. If the user (or the policy provider) has stated that they don’t want to call premium rate numbers in the UK:

<target>
  <subject>
    <subject-match attr="author-key-root-fingerprint" 
        match="sha256 ******** root fingerprint of author ****" /> 
    <-- to identify the Identified domain, the same would
	  apply for the Unidentified domain-->
</target>
<rule effect="one-shot">
  <condition>
    <resource-match attr="dev-cap" match="messaging.*.send"
		param:recipients="+4409*" func="glob"/> <-- to block UK premium rate numbers -->
  </condition>
</rule>
We could extend this to other countries if we are concerned that premium rate numbers would not only be from the host country. Here is an example of a policy fragment for blocking Spanish premium rate numbers that could be added, along with the condition combining operator (please note: there are probably more elegant ways of expressing this by using regular expressions):
<condition combine="or">
  <resource-match attr="dev-cap" match="messaging.*.send"
        param:recipients="+4409*" func="glob"/> <-- to block UK premium rate numbers -->
  <resource-match attr="dev-cap"
    match="messaging.*.send" param:recipients="+34806*" func="glob"/>
    <-- to block Spanish premium rate numbers -->
</condition>
    	

If the malicious widget is out in the wild already and has been identified, then we want to prevent it from installing and executing on devices, halting the spread of the malware in its early stages of distribution.

Clearly, if the widget is prevented from installing, then it cannot call a device API – these functions are shown as a belt and braces example:

<target>
  <subject>
    <subject-match attr="id" match="http://maliciouswidget1.example.org"/>
   </subject>
</target>
<rule effect="deny">
  <condition combine="or">
    <resource-match attr="widget-install" /> <resource-match
      attr="widget-instantiate" />
    <resource-match attr="api-feature" match="*"/>
    <resource-match attr="dev-cap" match="*" />
  </condition>
</rule>

Acknowledgements

The editors would like to extend special thanks to Nokia, OMTP BONDI, and PhoneGap for providing the foundation of the working group’s requirements discussion.