# # # patch "monotone.texi" # from [e791cde3620d4ed4489952d28398a28970bc18df] # to [dfb9842a37aae294ae22c54fdb893e4952ec2be6] # ============================================================ --- monotone.texi e791cde3620d4ed4489952d28398a28970bc18df +++ monotone.texi dfb9842a37aae294ae22c54fdb893e4952ec2be6 @@ -9654,6 +9654,33 @@ @section Hooks This section documents the existing hook functions and their default definitions. address@hidden Common Data Types + +Some hooks take arguments which are more complex than a simple string or number. +Where multiple hooks take the same kind of argument, we generally try to make +them take that kind of argument in the same format. + address@hidden @code address@hidden key_identity + +When a key is created, it is given a meaningful name. Because this is chosen by +the key creator and may be unreliable, trust hooks need to be able to look at +the key hash as well. This may be inconvenient, so a local alias is also provided. +This alias is obtained from an other hook, which can provide reliable easy-to-use +names based on the key hash (or however else you want). + address@hidden address@hidden address@hidden + id = "key hash/fingerprint, in hex", + given_name = "name given when creating the key", + name = "local alias of the key" address@hidden address@hidden group address@hidden smallexample + address@hidden ftable + @subsection Event Notifications and Triggers There are a number of hooks that are called when noteworthy events @@ -9681,8 +9708,7 @@ @subsection Event Notifications and Trig commit-notification systems such as mailing lists or news services. It should not perform any security-critical operations. address@hidden note_netsync_start (@var{session_id}, @var{my_role}, @var{sync_type}, address@hidden, @var{remote_keyname}, @var{includes}, @var{excludes}) address@hidden note_netsync_start (@var{session_id}, @var{my_role}, @var{sync_type}, @var{remote_host}, @var{remote_key}, @var{includes}, @var{excludes}) Called by monotone before any other of the netsync notification hooks are called. The @var{session_id} helps keep track of the current netsync @@ -9707,11 +9733,10 @@ @subsection Event Notifications and Trig it was told to connect to; at the server, this will use the numerical IP address the connection was received from. address@hidden @var{remote_keyname} address@hidden @var{remote_key} -The name of the key being used by the other end of the connection. This may be -set to "-unknown-" at the server if the key used by the client is not present -at the server. +The identity of the key being used by the other end of the connection. The fields may +be empty at the server if the key used by the client is not present at the server. @item @var{includes} and @var{excludes} @@ -9726,7 +9751,7 @@ @subsection Event Notifications and Trig by @command{mtn automate get_revision @var{new_id}}. @var{certs} is a Lua table containing one subtable for each cert attached to the revision @var{new_id}. These subtables have fields named "key", "name", and -"value", containing the signing key for the cert, the name of the cert, +"value", containing the identity of the signing key for the cert, the name of the cert, and the value of the cert. There is no default definition for this hook. @var{session_id} is used together with @code{note_netsync_start} and @code{note_netsync_end}. If you're not interested in that type of @@ -9738,41 +9763,39 @@ @subsection Event Notifications and Trig netsync. The arguments are the same as for @var{note_netsync_revision_received}. address@hidden note_netsync_cert_received (@var{rev_id}, @var{key}, @var{name}, @var{value}, @var{session_id}) address@hidden note_netsync_cert_received (@var{rev_id}, @var{key_identity}, @var{name}, @var{value}, @var{session_id}) Called by monotone after a cert is received through netsync, if the revision that the cert is attached to was not also received in the same netsync operation. @var{rev_id} is the revision id that the cert is attached to, address@hidden is the key that the cert is signed with, @var{name} is the name address@hidden is the key that the cert is signed with, @var{name} is the name of the cert, and @var{value} is the cert value. There is no default definition for this hook. @var{session_id} is used together with @code{note_netsync_start} and @code{note_netsync_end}. If you're not interested in that type of tracking, you can ignore that variable entirely. address@hidden note_netsync_cert_sent (@var{rev_id}, @var{key}, @var{name}, @var{value}, @var{session_id}) address@hidden note_netsync_cert_sent (@var{rev_id}, @var{key_identity}, @var{name}, @var{value}, @var{session_id}) Called by monotone after a cert is sent through netsync, if the revision that the cert is attached to was not also sent in the same netsync operation. The arguments are the same as for @var{note_netsync_cert_received}. address@hidden note_netsync_pubkey_received (@var{keyname}, @var{session_id}) address@hidden note_netsync_pubkey_received (@var{key_identity}, @var{session_id}) -Called by monotone after a pubkey is received through netsync. @var{keyname} -is the name of the key received. There is no default definition for this hook. +Called by monotone after a pubkey is received through netsync. @var{key_identity} +is the identity of the key received. There is no default definition for this hook. @var{session_id} is used together with @code{note_netsync_start} and @code{note_netsync_end}. If you're not interested in that type of tracking, you can ignore that variable entirely. address@hidden note_netsync_pubkey_sent (@var{keyname}, @var{session_id}) address@hidden note_netsync_pubkey_sent (@var{key_identity}, @var{session_id}) Called by monotone after a pubkey is sent through netsync. The arguments are the same as for @var{note_netsync_pubkey_received}. address@hidden note_netsync_end (@var{session_id}, @var{status}, address@hidden, @var{bytes_out}, @var{certs_in}, @var{certs_out}, address@hidden, @var{revs_out}, @var{keys_in}, @var{keys_out}) address@hidden note_netsync_end (@var{session_id}, @var{status}, @var{bytes_in}, @var{bytes_out}, @var{certs_in}, @var{certs_out}, @var{revs_in}, @var{revs_out}, @var{keys_in}, @var{keys_out}) Called by monotone after all other the netsync notification hooks have been called. This hook would usually be used for post-netsync purposes, @@ -9909,21 +9932,19 @@ @subsection User Defaults @end group @end smallexample address@hidden get_passphrase (@var{keypair_id}) address@hidden get_passphrase (@var{key_identity}) Returns a string which is the passphrase used to encrypt the private -half of @var{keypair_id} in your database, using the @sc{arc4} symmetric -cipher. @var{keypair_id} is a Lua string containing the label that you -used when you created your key --- something like address@hidden"nicole@@example.com"}. This hook has no default definition. If +half of @var{key_identity} in your key store, using the @sc{TripleDES} symmetric +cipher. This hook has no default definition. If this hook is not defined or returns false, monotone will prompt you for a passphrase each time it needs to use a private key. address@hidden get_author (@var{branchname}, @var{keypair_id}) address@hidden get_author (@var{branchname}, @var{keyidentity}) Returns a string which is used as a value for automatically generated @code{author} certificates when you commit changes to address@hidden with the keypair identity @var{keypair_id}. Generally address@hidden with the keypair identity @var{key_identity}. Generally this hook remains undefined, and monotone selects your signing key name for the author certificate. You can use this hook to override that choice, if you like. @@ -9932,7 +9953,7 @@ @subsection User Defaults definitions might be: @smallexample @group -function get_author(branchname, keypair_id) +function get_author(branchname, key_identity) -- Key pair identity ignored. local user = os.getenv("USER") local host = os.getenv("HOSTNAME") @@ -9943,12 +9964,12 @@ @subsection User Defaults @end smallexample @smallexample @group -function get_author(branchname, keypair_id) +function get_author(branchname, key_identity) -- Branch name ignored. - if (keypair_id == "joe@@example.com") then + if (key_identity.given_name == "joe@@example.com") then return "Joe Random " end - return keypair_id + return key_identity end @end group @end smallexample @@ -10044,9 +10065,9 @@ @subsection Netsync Permission Hooks changed. @ftable @code address@hidden get_netsync_read_permitted (@var{branch}, @var{identity}) address@hidden get_netsync_read_permitted (@var{branch}, @var{key_identity}) -Returns @code{true} if a peer authenticated as key @var{identity} +Returns @code{true} if a peer authenticated as key @var{key_identity} should be allowed to read from your database certs, revisions, manifests, and files associated with @var{branch}; otherwise @code{false}. The default definition of this hook reads a file @file{read-permissions} in @@ -10082,18 +10103,11 @@ @subsection Netsync Permission Hooks If a client connects anonymously, this hook will be called with a address@hidden of @code{nil}. address@hidden of @code{nil}. -Note that the @var{identity} value is a key ID (such as address@hidden@@pobox.com}'') but will correspond to a @emph{unique} -key fingerprint (hash) in your database. Monotone will not permit two -keys in your database to have the same ID. Make sure you confirm the -key fingerprints of each key in your database, as key ID strings are -``convenience names'', not security tokens. address@hidden get_netsync_write_permitted (@var{key_identity}) address@hidden get_netsync_write_permitted (@var{identity}) - -Returns @code{true} if a peer authenticated as key @var{identity} should +Returns @code{true} if a peer authenticated as key @var{key_identity} should be allowed to write into your database certs, revisions, manifests, and files; otherwise @code{false}. The default definition of this hook reads a file @file{write-permissions} in the configuration directory which contains a list @@ -10101,16 +10115,9 @@ @subsection Netsync Permission Hooks @code{*} means to allow access to anyone whose public key we already have. If a client connects anonymously, it will be unconditionally denied -write access; this hook will @emph{not} be called with a @var{identity} +write access; this hook will @emph{not} be called with a @var{key_identity} of @code{nil}. -Note that the @var{identity} value is a key ID (such as address@hidden@@pobox.com}'') but will correspond to a @emph{unique} -key fingerprint (hash) in your database. Monotone will not permit two -keys in your database to have the same ID. Make sure you confirm the -key fingerprints of each key in your database, as key ID strings are -``convenience names'', not security tokens. - Note also that, unlike the equivalent read permission hook, the write permission hook does not take a @var{branch} name as an argument. There is presently no way to selectively grant write access to different @@ -10289,7 +10296,7 @@ @subsection Trust Evaluation Hooks Returns whether or not you @emph{trust} the assertion @address@hidden on a given revision @var{id}, given a valid signature from all the keys in @var{signers}. The @var{signers} -parameter is a table containing all the key names which signed this +parameter is a table containing all the key identities which signed this cert, the other three parameters are strings. The default definition of this hook simply returns @code{true}, which @@ -10304,7 +10311,7 @@ @subsection Trust Evaluation Hooks function intersection(a,b) local address@hidden@} local address@hidden@} - for k,v in pairs(a) do s[v] = 1 end + 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