Reference Manual: ACL

From RFID Guardian

Contents 1 Introduction 2 Operation 3 Grammar 4 Tag 5 Tag set 6 Reader 7 Role 8 Context 9 Rule

Introduction

An ACL (Access Control List) is used to control the Guardian's mode of operation.

Normally, the ACL is controlled from the UI/ACL. See there for more details.

The ACL consists of several files, grouped into a directory:

• a .tags file that defines tags and/or sets of tags (default: example.tags);
• an optional .context file that defines contexts (default: example.context);
• a .readers file that defines readers and their roles (default: example.readers);
• a .acl file that defines rules (default: example.acl);
• an optional .requests file that defines queries to test the ACL.

These definitions are read by the ACL parser in the order specified above.

Operation

For operating an ACL, the Guardian program have selected an ACL (e.g. by specifying an ACL directory via the UI UI/ACL).

Then, each time an RFID query comes in, the ACL is invoked. It bases its decision on:

• the roles that the current reader can assume; the current reader either is the reader in whose field we are, that has authenticated itself most recently, or is set via the UI
• the current context, either derived from the environment (e.g. if the reader at home has authenticated most recently, the context would be 'home'), or set via the UI
• the type of query
• rules that apply

Grammar

The ACL is specified in a small language that defines rules in terms of roles, contexts, tag sets, and queries. The language is parsed via LLgen, an LL(1) parser generator. The grammar of the language is outlined in the sections below. It uses the following notation conventions:

( ) ? * + OR	meta-symbols for the language:
	( ) : grouping
	? : repeat 0 or 1 times;
	* : repeat 0 or more times;
	+ : repeat 1 or more times;
	OR : alternatives
x	a reserved word or keyword
x	a terminal symbol
x	a nonterminal symbol, i.e. another rule in the grammar

All definitions follow the rule "define before use". The grammar is layout-free.

Tag

A tag in the ACL defines a single RFID tag.

The header of the tag structure contains the RFID protocol type (currently, T15693 or T14443) and an optional name, used to identify and use the tag in other parts of the ACL.

The definition of a tag has as fields: the tag UID; and optional security information, like secret keys (kill, sleep, or wakeup keys) or even certificates. Key information may consist of a key type and a filename that contains the key; see the example in the reader section.

A tag has the following definition:

tag protocol name ? {

( ( ( tagid = tag_UID )

OR ( key = key_info )

OR ( wakekey = key_info )

OR ( sleepkey = key_info ) ) ; ) *

};

key_info ::= { ( ( ( type = crypto-algorithm )

OR ( store = filename )

OR ( password = passwd ) ) , ) * };

An example of a tag:

tag T15693 Passport {

tagid = 0xE0123456;

};

In this example we've got an 15693 tag named 'Passport'. Its tag UID is '0xE0123456'.

Tag set

Tags can be grouped into tag sets, to express common use in ACL rules.

The header of a tag set structure contains an '@tag' keyword, a protocol identifier, and a (non-optional) name.

The structure includes tags by referencing previously defined tags by name, by giving inline definitions of tags, or by including other tag sets.

A tag set has the following definition:

@tag protocol name { ( ( tag OR $tag_name OR @tag_set_name) , ) * };

An example of a tag set:

@tag T15693 MY_TAGS {

$Passport,

tag T15693 { tagid = 0xe007000012d716c0; },

};

In this example we created a tag set named 'MY_TAGS' of type 'T15693'. The tag set contains the 'Passport' tag and a new, unnamed tag.

Reader

A reader in the ACL defines a single RFID reader.

The header of the reader structure contains a name to identify and use the reader in other parts of the ACL.

The body of a reader's definition contains information on that reader's keys. Key information consists of the type of the key and the key store, i.e. the name of the file that contains the certificate or shared secret.

A reader has the following definition:

reader name {

( key = { key_info * }; ) *

};

An example of a reader:

reader SCHIPHOL {

key = { type = rsa_public; store = "schiphol-public.pem"; };

};

In this example we've got a reader named 'SCHIPHOL'. It's using a key of type 'rsa_public' which is stored in 'schiphol-public.pem'.

Role

Roles are used to group readers that share common capabilities. ACL rules do not even have a concept of readers; they work on roles only.

One role can contain several readers. An example of this is grouping all the readers at your own home into a single role and naming it 'HOME_READERS'. You can now use the 'HOME_READERS' role in a rule to, for example, allow all the readers in the role access to your tags.

A single reader may assume several different roles.

A role can be a superset of other roles. This is expressed by the clause '@role_name'.

A role has the following definition:

role name { ( ( reader_name OR @role_name ) , ) * };

An example of a role:

role FRIENDLY_READERS {

SCHIPHOL,

@HOME_READERS,

};

In this example, a role 'FRIENDLY_READERS' is defined that is assumed by the reader SCHIPHOL and by all readers that assume the role 'HOME_READERS'.

Context

Defining a context in the ACL is a way to control when rules are and when they're not applied.

An example of this is defining a 'home' context and let your home reader only access your tags when you are in the context of your home.

A context has the following definition:

context name ;

An example of this is

context home;

Rule

Rules define when and in which situation we deny or allow external readers to access our tags.

A rule returns a verdict, and it consists of clauses for roles, contexts, incoming queries, and tags to which the query matches. Another type of rule clause defines at which time interfering action should be undertaken in the reception/response cycle: either during the tags' response, or during the remainder of the external reader's request.

The header of the rule definition contains the protocol used for communication (P15693 or P14443_A, while P14443_B is reserved) and the verdict (ACCEPT or DENY).

A rule has the following definition:

rule protocol verdict {

( role_clause OR context_clause OR query_clause OR tags_clause OR interfere_clause ) *

};

role_clause ::= role = role_name ;

context_clause ::= ( ( context = context_name ) OR ( context = { ( context_name , ) + } ) ) ;

query_clause ::= query = {

( ( command = command ; )

OR ( flags = flags_expression ; )

OR ( ... other query fields ... ; ) ) *

} ;

tags_clause ::= ( ( tags = tag_uid ; )

OR ( tags = $tag_name )

OR ( tags = @tag_set ) ) ;

interfere_clause ::= interfere = ( REQUEST OR RESPONSE ) ;

All types of rule clause are optional, but there can be at most one of each type. For role, tags, context and query, the default value is *, meaning 'all' or 'any'. The default value for interfere is 'RESPONSE'.

Rules are presented in increasing strongness. A typical usage is to make a general rule (e.g. allow everything) and follow that with rules that deny access to selected tags. These rules can again be followed by rules that allow access only to selected roles or in specific contexts, etc.

An example of a rule:

rule P15693 ACCEPT {

role = *;

tags = *;

command = *;

context = *;

};

In this example we allow all traffic cause we don't want to interfere with most of the RFID traffic. Remark that this is equivalent to a rule with no clauses at all.

We don't want all readers to have full access to our tags. So we follow this with a rule that blocks all access to the tags in the tag set 'MY_TAGS':

rule P15693 DENY {

role = *;

tags = @MY_TAGS;

command = *;

context = *;

};

If we're in an environment we trust, the readers that can prove they belong to the role 'LEGAL_READER' are allowed access to 'MY_TAGS':

rule P15693 ACCEPT {

role = LEGAL_READER;

tags = @MY_TAGS;

command = *;

context = trusted;

};