6.1.6 Trust Evaluation Hooks

Monotone makes heavy use of certs to provide descriptive information about revisions. In many projects, not all developers should have the same privileges, or be trusted for the same purposes (indeed, some signers might be automated robots, with very specific purposes).

These hooks allow the user to configure which signers will be trusted to make which kinds of assertions using certs. Monotone uses these certs when selecting available revisions for commands such as update.

Each user, or even each workspace, can have their own implementation of these hooks, and thus a different filtered view of valid revisions, according to their own preferences and purposes.

See Quality Assurance.

get_revision_cert_trust (signers, id, name, val)

Returns true if you trust the assertion name=value on a given revision id, given a valid signature from all the keys in signers; false otherwise. signers is a table containing a key_identity for all signatures on this cert, the other three parameters are strings.

The default definition of this hook returns true.

The default definition corresponds to a form of trust where every key which is defined in your database is trusted. This is a weak trust setting. A possible example of a stronger trust function (along with a utility function for computing the intersection of tables) is the following:

function intersection(a,b)
   local s={}
   local t={}
   for k,v in pairs(a) do s[v.name] = 1 end
   for k,v in pairs(b) do if s[v] ~= nil then table.insert(t,v) end end
   return t
end

function get_revision_cert_trust(signers, id, name, val)
   local trusted_signers = { "bob@happyplace.example.com",
                             "friend@trustedplace.example.com",
                             "myself@home.example.com" }
   local t = intersection(signers, trusted_signers)

   if t == nil then return false end

   if    (name ~= "branch" and table.getn(t) >= 1)
      or (name == "branch" and table.getn(t) >= 2)
   then
      return true
   else
      return false
   end
end

In this example, any revision certificate is trusted if it is signed by at least one of three “trusted” keys, unless it is an branch certificate, in which case it must be signed by two or more trusted keys. This is one way of requiring that the revision has been approved by an extra “reviewer” who used the approve command.

accept_testresult_change (old_results, new_results)

Called by mtn update.

This hook is used by the update algorithm to determine whether a change in test results between update source and update target is acceptable. The hook is called with two tables, each of which maps a signing key hash (as 20 raw bytes) – representing a particular testsuite – to a boolean value indicating whether or not the test run was successful (calculated from the testresult cert). The function should return true if you consider an update from the version carrying the old_results to the version carrying the new_results to be acceptable.

The default definition of this hook returns true if _MTN/wanted-testresults does not exist. Otherwise, the file should contain a list of signing key hex-encoded hashes in lowercase (40 characters). The hook returns false if a listed signing key hash is present in both old_results and new_results, with the value true in old_results and false in new_results; otherwise it returns true.