Modules | |
| Rules Processing | |
| typedef char * | rules_domain |
| Rules Domains are UTF-8 representations of a Fully Qualified Domain Name. More... | |
| typedef uint8_t | rules_type[16] |
| Rules Types are 128-bit "well-known service
identities". More... | |
| typedef uint8_t * | rules_typeref |
| A reference to the 16-byte array of a rules_type. | |
| typedef char * | rules_name |
| Rules Names represent instances of a Rules Type. More... | |
| typedef char const * | rules_varray_ptr[26] |
Rules Variables form a set of 26 variables named a through z that never have value NULL but may be empty when their length is 0. They generally point back into a Rule or to a constant string and have a pointer and length. Do not assume a NUL terminator. More... | |
| typedef unsigned | rules_varray_len[26] |
| The corresponding lengths for rules_varray_ptr. | |
| typedef uint32_t | rules_flags |
| Flags in a bit mask. More... | |
| typedef char const * | rules_trigger |
| Triggers reference a ^trigger name. More... | |
| #define | RULES_VARINDEX(c) (c - 'a') |
| Map a lowercase letter c to a Rules Variable in the variable array indexes. More... | |
| #define | RULES_FLAG(c) ( 1 << (c - 'A') ) |
| Map an uppercase letter to a Rules Flag. More... | |
Detailed Description
Rules define a number of types. Several of them will also occur in higher layers, such as Access Control. These higher layers are less abstract and generally add a new type which either wraps or aliases these forms.
Macro Definition Documentation
◆ RULES_FLAG
| #define RULES_FLAG | ( | c | ) | ( 1 << (c - 'A') ) |
Map an uppercase letter to a Rules Flag.
Use bit 0 for 'A', bit 1 for 'B' and so on. Only capital letters are mapped, and the caller should be certain not to map anything else to a Rules Flag.
This definition is the same as ACCESS_RIGHT().
◆ RULES_VARINDEX
| #define RULES_VARINDEX | ( | c | ) | (c - 'a') |
Map a lowercase letter c to a Rules Variable in the variable array indexes.
Only capital letters are mapped, and the caller should be certain not to map anything else to a Rules Variable.
This definition is not also exported by Access Control.
Typedef Documentation
◆ rules_domain
| typedef char* rules_domain |
Rules Domains are UTF-8 representations of a Fully Qualified Domain Name.
These names have no initial or trailing dots, they have at least one inner dot and they have been mapped from the DNS wire format Punycode for international names to UTF-8. The wire form was a valid DNS name.
Note the value of this mapping: Code should have only one form to deal with, and Punycode is both specific to one protocol and confusing. It also cannot be processed like any other internationalised code. So we choose an internal form that maps to a standard form.
See A2ID_BUFSIZE for a discussion of the size that a domain in this form can take. This is normally supported as part of the a2id_t and a2sel_t definitions in ARPA2 software.
The NULL value is invalid as an Rules Domain. This means that software can use it to indicate absense of a domain in places where it accepts optional parameters.
This definition is the same as for access_domain.
◆ rules_flags
| typedef uint32_t rules_flags |
Flags in a bit mask.
Rules may set flags named A through Z in short FLAGS words. Encode A in bit 0 through Z in bit 25 of a 32-bit unsigned integer.
This definition is the same as access_rights.
◆ rules_name
| typedef char* rules_name |
Rules Names represent instances of a Rules Type.
Where the Rules Type is "well-known", it is instantiated by an rules_domain and this Rules Name. The general Rules Name format is a UTF-8 string with a NUL terminator, but its format is defined by the Rules Type.
The purpose of the Rules Name is to allow generic software to fill it, perhaps with user-supplied templates or regular expressions taking content from an application's context. This allows the generation of an Rules Name even in applications that are not aware of the semantics of an Rules Type. As an example, a generic web server may take elements from the path and/or query paramters and use those in a string templated that is printed into an environment variable to be supplied to some software for Rules Control.
The value NULL is not a proper rules_name. Depending on the definition for the given rules_type, an empty string may be a valid form. Note that this means that NULL can be used to indicate absense of an Rules Name in places where software can optionally handle Rules Names.
This definition is the same as for access_name.
◆ rules_trigger
| typedef char const* rules_trigger |
Triggers reference a ^trigger name.
When a Rule contains a ^trigger word, the rules_trigger points after the '^' at the trigger itself. Note that it is a word, so it ends in either a space or in the NUL character that terminates every Rule. Upcalls provide the length of the remaining trigger word.
This definition is not also exported by Access Control.
◆ rules_type
| typedef uint8_t rules_type[16] |
Rules Types are 128-bit "well-known service identities".
We write an Rules Type in UUID form, but code that prepares for taking it up use the canonical form of 16 bytes of which the UUID shows the per-byte hex form with a couple of dashes. These 16 bytes are used in message digests.
The Rules Type serves as a "well-known identifier" for a class of uses. For instance, we might have one for the idea of "file storage" that could span many application areas but be the same across vendors and protocols and software suites. Or we might have one for "git access", regardless of the method being SSH, HTTPS, local file system or other.
Rules Types need further refinment to properly localise them. First of all, the rules_domain has to be distinguished, so policy rights assigned in one domain cannot pass over to another domain. Furthermore, every Rules Types defines a UTF-8 string format for an rules_name that can distinguish instances within the well-known class below the domain. In the Git example, the Rules Name could be a name for a repository.
The all-zero value is not a valid rules_type. This means that zeroing an rules_type will not cause presumptious use of a valid rules_type.
This definition is the same as for access_type.
◆ rules_varray_ptr
| typedef char const* rules_varray_ptr[26] |
Rules Variables form a set of 26 variables named a through z that never have value NULL but may be empty when their length is 0. They generally point back into a Rule or to a constant string and have a pointer and length. Do not assume a NUL terminator.
Rules Variables are emptied at the start of a Rule, also within a Ruleset. Other than that, as long as they are not set to a new value, the values are kept until the end of a Rule, and is still available when its terminating NUL causes an upcall. The underlying memory disappears as soon as the underlying memory is given up, which must be assumed at the end of processing a Ruleset.
The corresponding lenghts are in rules_varray_len.
This definition is not also exported by Access Control.
