ARPA2 Common Libraries  2.3.1
Functions
Collaboration diagram for Database Key derivation and Privacy Control:

Functions

bool rules_dbkey_domain (rules_dbkey domkey, const uint8_t *opt_dbkey, int dbkeylen, const char *xsdomain)
 Derive the Domain Key for a given domain name and optional Database Secret. More...
 
bool rules_dbkey_service (rules_dbkey svckey, const uint8_t *domkey, unsigned domkeylen, const uint8_t xstype[16])
 Derive the Service Key for a given Access Type, using a Domain Key as a start. More...
 
bool rules_dbkey_selector (rules_dbkey reqkey, const uint8_t *svckey, unsigned svckeylen, const char *xsname, const a2sel_t *selector)
 Derive the Request Key for a given Access Name and Selector, using a Domain Key as a start. Note that this functionality may be wrapped inside an iterator like rules_dbiterate() More...
 
bool rules_dbkey_parse (rules_dbkey outkey, const char *hexkey, int hexkeylen)
 Parse a Database Key from hexidecimal notation. More...
 

Detailed Description

The keys used to lookup information in the RuleDB are formed in a number of steps. Each of these steps reduce the ability of the holder of a key to access information from the RuleDB.

Current protection is agains treating the RuleDB as an oracle for keys, which would allow stolen databases to yield sensitive data that identifies users. In a future release, encrypted values will also shield the technical data contained therein from prying eyes.

Note that the keys are derived from a message digest, and even if that process uses a secure hash, it still works on rather limited entropy. The result is that guessing becomes feasible, both for the key and (future:encrypted) value. The use of a Database Secret in the first stage avoids that, by inserting actual entropy, known only to the database manager, in the top of the key derivation chain:

  1. Database Secret is a code that is known only to the owner of the RuleDB
  2. Domain Key may be known to the administrator of a domain name
  3. Service Key may be distributed to administrators of services of a given Access Type and is specific to a domain name being serviced
  4. Request Key is derived for a specific request
Note
None of this is obligatory; it is mostly very helpful to structure commercial hosting operations and implement privacy laws and assumed by default in ARPA2 Access Control, Groups and anything else built on these Rules and the RuleDB.

Function Documentation

◆ rules_dbkey_domain()

bool rules_dbkey_domain ( rules_dbkey  domkey,
const uint8_t *  opt_dbkey,
int  dbkeylen,
const char *  xsdomain 
)

Derive the Domain Key for a given domain name and optional Database Secret.

First phase of key preparation,

  • [Database Secret], Domain being accessed --> "Domain Key" to be followed by
  • Access Type --> "Service Key"
  • Access Name, Selector (which walks up) --> "Request Key"

This function may precede rules_dbkey_service().

This phase is usually performed in a restricted area, and protects the Database Secret from being shared between domains. It does this by hashing the key along with the domain and returning the result as a next-level key.

Parameters
[out]domkeyThe Domain Key derived herein
[in]opt_dbkeyOptional Database Secret key bytes, set to NULL for none
[in]dkkeylenThe length of opt_dbkey if not NULL
[in]xsdomainThe Access Domain as a NUL-terminated UTF-8 string
Returns
true on success, false with errno set on failure
Note
Any byte sequence works as the Database Secret. If it is not provided then anyone can compute the Domain Key, Service Key and Request Key with only the knowledge of the other public inputs. Such a party can start looking up data in your database. Using a Database Secret constrains the leakage of sensitive data to only the are derived from any derived key; this may help you to implement privacy policies. Domain Keys can query all information underneath a domain name; Service Keys can query all information underneath a domain's service (Access Type). Request Keys can only query information for a given request.
The xsdomain is the domain name after mapping to Unicode; it must not use Punycode, the wire format for Internationalised DNS.

◆ rules_dbkey_parse()

bool rules_dbkey_parse ( rules_dbkey  outkey,
const char *  hexkey,
int  hexkeylen 
)

Parse a Database Key from hexidecimal notation.

Many applications of the Rules DB call for explicitly provided key material, for instance in an environment variable. These forms are generally hexadecimal, and they must be parsed.

This is a standard utility function for doing just that. The output can be used as the rules_dbkey input to other functions accessing the Rules DB.

The hexkeylen must be twice the length of the outkey size in bytes. (This is added as a protection against possible future changes in the byte size of database keys.) When hexkeylen is set to 0, a NUL-terminated string will be assumed.

Parameters
[out]outkeyThe rules_dbkey structure to fill
[in]hexkeyA sequence of hexadecimal characters
[in]hexkeylenThe number of hexadecimal characters
Returns
true on success, false with errno set on failure

◆ rules_dbkey_selector()

bool rules_dbkey_selector ( rules_dbkey  reqkey,
const uint8_t *  svckey,
unsigned  svckeylen,
const char *  xsname,
const a2sel_t selector 
)

Derive the Request Key for a given Access Name and Selector, using a Domain Key as a start. Note that this functionality may be wrapped inside an iterator like rules_dbiterate()

After the key preparation in phase 1+2,

  • [Database Secret], Domain being accessed --> "Domain Key"
  • Access Type --> "Service Key" we turn to the final phase of key derivation,
  • Access Name, Selector (which walks up) --> "Request Key"

This function may follow after rules_dbkey_service().

This is intended to derive database lookup keys that can be used as parameters to rules_dbget() and rules_dbset().

The form of the Access Name is determined by the Access Type, but generally takes the shape of an UTF-8 string. The Selector is provided in parsed and normalised form in a data structure from a2sel_parse().

This process is sometimes broken into pieces, where the digest is cloned after writing the svckey bytes and xsname message; this is helpful for efficient iteration over various selector values. This is not done here, but it is supported by digesting the selector last.

Parameters
[out]reqkeyThe Request Key derived herein
[in]svckeyThe previously derived Service Key
[in]svckeylenThe length of svckey
[in]xsnameThe Access Name input
[in]selectorThe Selector to lookup for
Returns
true on success, false with errno set on failure

◆ rules_dbkey_service()

bool rules_dbkey_service ( rules_dbkey  svckey,
const uint8_t *  domkey,
unsigned  domkeylen,
const uint8_t  xstype[16] 
)

Derive the Service Key for a given Access Type, using a Domain Key as a start.

After the key preparation in phase 1,

  • [Database Secret], Domain being accessed --> "Domain Key" we turn to the second phase of key preparation,
  • Access Type --> "Service Key" to be followed by
  • Access Name, Selector (which walks up) --> "Request Key"

This function may follow after rules_dbkey_domain() and may precede by rules_dbkey_selector().

This is intended to derive purpose-specific keys that can be distributed to service providers. They will share access data with other providers offering the same access type, which is somewhat unavoidable, but they will not be able to see the access control lists for other access types.

Parameters
[out]svckeyThe Service Key derived herein
[in]domkeyThe previously derived Domain Key
[in]domkeylenThe length of svckey
[in]xstypeThe Access Type input
Returns
true on success, false with errno set on failure