Database Key derivation and Privacy Control

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]	domkey	The Domain Key derived herein
[in]	opt_dbkey	Optional Database Secret key bytes, set to NULL for none
[in]	dkkeylen	The length of opt_dbkey if not NULL
[in]	xsdomain	The 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]	outkey	The rules_dbkey structure to fill
[in]	hexkey	A sequence of hexadecimal characters
[in]	hexkeylen	The 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]	reqkey	The Request Key derived herein
[in]	svckey	The previously derived Service Key
[in]	svckeylen	The length of svckey
[in]	xsname	The Access Name input
[in]	selector	The 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]	svckey	The Service Key derived herein
[in]	domkey	The previously derived Domain Key
[in]	domkeylen	The length of svckey
[in]	xstype	The Access Type input

Returns

true on success, false with errno set on failure