From 0e85f07781f8eab9670e06cee32b38657e3b62ce Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Thu, 24 May 2012 14:51:46 -0400 Subject: Combine action and details parameters This also removes the ability to change detail parameters which is actually a good thing. If we later need a way to change the authentication message, we can always add something like polkit.addAuthenticationMessageRule() so the user can register a function returning a string. Signed-off-by: David Zeuthen --- docs/man/polkit.xml | 379 ++++++++++++++++++++++++++++------------------------ 1 file changed, 204 insertions(+), 175 deletions(-) (limited to 'docs') diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml index de4bb4a..9718541 100644 --- a/docs/man/polkit.xml +++ b/docs/man/polkit.xml @@ -484,120 +484,196 @@ System Context | | programming language and interface with polkitd through the global polkit object (of type Polkit). - The following methods are available: - - - - void addRule - string function(action, subject, details) {...} - - - - - - - void addAdminRule - string[] function(action, subject, details) {...} - - - - - - - void log - string message - - - - - - - string spawn - string[] argv - - + + The <type>Polkit</type> type - - The addRule() method is used for adding a - function that may be called whenever an authorization check for - action, subject - and details is performed. Functions are - called in the order they have been added until one of the - functions returns a value. Hence, to add an authorization rule - that is processed before other rules, put it in a file in - /etc/polkit-1/rules.d - with a name that sorts before other rules files, for example - 00-early-checks.rules. Each function should - return one of the values "no", - "yes", "auth_self", - "auth_self_keep", - "auth_admin", - "auth_admin_keep" as defined above. If the - function returns null, - undefined or does not return a value at - all, the next function is tried. - + + The following methods are available on the polkit object: + - - The addAdminRule() method is used for - adding a function may be called whenever administrator - authentication is required. The function is used to specify what - identies may be used for administrator authentication for the - authorization check identified by action, - subject and - details. Functions added are called in - the order they have been added until one of the functions - returns a value. Each function should return an array of strings - where each string is of the form - "unix-group:<group>", - "unix-netgroup:<netgroup>" or - "unix-user:<user>". If the function - returns null, - undefined or does not return a value at - all, the next function is tried. - + + + + void addRule + string function(action, subject) {...} + + - - There is no guarantee that a function registered with - addRule() or - addAdminRule() is ever called - for example - an early rules file could register a function that always return - a value, hence ensuring that functions added later are never - called. - + + + + void addAdminRule + string[] function(action, subject) {...} + + - - If user-provided code takes a long time to execute an exception - will be thrown which normally results in the function being - terminated (the current limit is 15 seconds). This is used to - catch runaway scripts. - + + + + void log + string message + + - - The log() method writes the given - message to the system logger. Log entries - are emitted using the LOG_AUTHPRIV flag - meaning that the log entries usually ends up in the file - /var/log/secure. The - log() method is usually only used when - debugging rules. - + + + + string spawn + string[] argv + + - - The spawn() method spawns an external - helper identified by the argument vector - argv and waits for it to terminate. If an - error occurs or the helper doesn't exit normally with exit code - 0, an exception is thrown. If the helper does not exit within 10 - seconds it is killed. Otherwise, the program's - standard output is returned as a string. - The spawn() method should be used sparingly - as helpers may take a very long or indeterminate amount of time - to complete and no other authorization check can be handled - while the helper is running. - + + The addRule() method is used for adding a + function that may be called whenever an authorization check for + action and subject + is performed. Functions are + called in the order they have been added until one of the + functions returns a value. Hence, to add an authorization rule + that is processed before other rules, put it in a file in + /etc/polkit-1/rules.d + with a name that sorts before other rules files, for example + 00-early-checks.rules. Each function should + return one of the values "no", + "yes", "auth_self", + "auth_self_keep", + "auth_admin", + "auth_admin_keep" as defined above. If the + function returns null, + undefined or does not return a value at + all, the next function is tried. + + + + The addAdminRule() method is used for + adding a function may be called whenever administrator + authentication is required. The function is used to specify what + identies may be used for administrator authentication for the + authorization check identified by action + and subject. Functions added are called in + the order they have been added until one of the functions + returns a value. Each function should return an array of strings + where each string is of the form + "unix-group:<group>", + "unix-netgroup:<netgroup>" or + "unix-user:<user>". If the function + returns null, + undefined or does not return a value at + all, the next function is tried. + + + + There is no guarantee that a function registered with + addRule() or + addAdminRule() is ever called - for example + an early rules file could register a function that always return + a value, hence ensuring that functions added later are never + called. + + + + If user-provided code takes a long time to execute an exception + will be thrown which normally results in the function being + terminated (the current limit is 15 seconds). This is used to + catch runaway scripts. + + + + The spawn() method spawns an external + helper identified by the argument vector + argv and waits for it to terminate. If an + error occurs or the helper doesn't exit normally with exit code + 0, an exception is thrown. If the helper does not exit within 10 + seconds it is killed. Otherwise, the program's + standard output is returned as a string. + The spawn() method should be used sparingly + as helpers may take a very long or indeterminate amount of time + to complete and no other authorization check can be handled + while the helper is running. + + + + The log() method writes the given + message to the system logger prefixed + with the JavaScript filename and line number. Log entries are + emitted using the LOG_AUTHPRIV flag meaning + that the log entries usually ends up in the file + /var/log/secure. The + log() method is usually only used when + debugging rules. The Action and + Subject types has suitable + toString() methods defined for easy + logging, for example, + + + + will produce the following when the user runs 'pkexec bash -i' from a shelll: + + + + + + + The <type>Action</type> type + + + The action parameter passed to user + functions is an object with information about the action + being checked. It is of type Action and has + the following attribute: + + + + + string id + + + The action identifier, for example + org.freedesktop.policykit.exec. + + + + + + + The following methods are available on the Action type: + + + + + + string lookup + string key + + + + + The lookup() method is used to lookup the + polkit variables passed from the mechanism. For example, the + pkexec1 + mechanism sets the variable program + which can be obtained in Javascript using the expression + action.lookup("program"). If there is + no value for the given key, + then undefined is returned. + + + Consult the documentation for each mechanism for what + variables are available for each action. + + The <type>Subject</type> type @@ -700,52 +776,6 @@ System Context | | isInNetGroup() can be used to check if the subject is in a given netgroup. - - - - - The <type>Details</type> type - - - The details parameter passed to user - functions is an object with more information about the action - being checked. It is of type Details and has - details being set by the mechanism as attributes. For example, - the pkexec1 - mechanism sets the variable program - which can be obtained in Javascript using the expression - details["program"]. Consult the - documentation for each mechanism for what variables are - available for each action. - - - - The details also has the following - well-known attributes: - - - - polkit.message - - - The message to show in the authentication dialog (only - used if authentication is needed). Its initial value is - taken from the action declaration (the message element in the .policy file) but the value - can be overridden by the mechanism setting this key in - the details passed when doing the - CheckAuthorization() - call. - - - - - - Note that a rule can set the - polkit.message attribute to change the - message shown in the authentication dialog. - @@ -757,8 +787,8 @@ System Context | | users: wheel group: Forbid users in group children to change - hostname configuration (that is, any action starting with - org.freedesktop.hostname1.) and allow - anyone else to do it after authenticating as themselves: + hostname configuration (that is, any action with an identifier + starting with org.freedesktop.hostname1.) + and allow anyone else to do it after authenticating as + themselves: - The following example showcases two things + The following example shows how the authorization decision + can depend on variables passed by the + pkexec1 + mechanism: - - how the authorization decision can depend on variables passed by the mechanism - how to override the message shown in the authentication dialog -