Tutorial: ACL
From RFID Wiki
Contents |
[edit] Introduction
An ACL (Access Control List) is used to control the Guardian's mode of operation.
Normally, the ACL is controlled from the Tree:_UI#UI_Implementation:_ACL UI. 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.
All definitions follow the rule "define before use". The grammar of the definitions is layout-free. Clauses within a definition (or within another clause) can generally be given in any order.
[edit] Operation
For operating an ACL, the Guardian program must select an ACL (e.g. by specifying an ACL directory via the UI Tree:_UI#UI_Implementation:_ACL).
Then, if 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
[edit] Tag
A tag in the ACL defines a single RFID tag.
The header of the tag structure contains the type type (for example T15693) 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 paragraph on keys in the reader section.
A tag has the following structure:
| tag protocol name { |
| tagid = tag_UID; |
| key = key_info; |
| wakekey = key_info; |
| sleepkey = key_info; |
| }; |
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'.
[edit] 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 structure:
| @tag protocol name { |
| tag OR |
| $tag_name OR |
| @tag_set_name , * |
| }; |
An example of a tag set:
| @tag T15693 MY_TAGS{ |
| $Passport, |
| tag P15693 { 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.
[edit] 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 structure:
| reader name { |
| key = { key_information ; * }; * |
| }; |
An example of a reader:
| reader SCHIPHOL { |
| key = { type = rsa_public; store = "schiphol-public.pem"; }; |
| }; |
In this example we've got a reader named 'SCHPHOL'. It's using a key of type 'rsa_public' which is stored in 'schiphol-public.pem'.
[edit] 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 structure:
| 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'.
[edit] 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 structure:
| context name ; |
An example of this is
| context home; |
[edit] 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 (for example P15693) and the verdict ('ACCEPT or 'DENY').
A rule has the following structure:
| rule protocol verdict { |
| role = role_name ; |
| tags = tag_uid; |
| OR |
| tags = $tag_name; |
| OR |
| tags = @tag_set; |
| context = context_name; |
| OR |
| context = { context_name1, |
| context_name2, |
| ..., |
| }; |
| query = { |
| command = command; |
| flags = flags_expression; |
| ... other query fields ... ; |
| }; |
| interfere = REQUEST; |
| OR |
| interfere = RESPONSE; |
| }; |
All types of rule clause are optional. 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; |
| }; |
