org.freedesktop.PolicyKit1.Authority Interfaceorg.freedesktop.PolicyKit1.Authority InterfaceAuthority InterfaceMethods
Flags CheckAuthorizationFlags
Enumeration ImplicitAuthorization
ErrorDomain org.freedesktop.PolicyKit1.Error.*
Flags AuthorityFeatures
Structure Subject
Structure Identity
Structure ActionDescription
Structure AuthorizationResult
Structure TemporaryAuthorization
EnumerateActions (IN String locale,
OUT Array<ActionDescription> action_descriptions)
CheckAuthorization (IN Subject subject,
IN String action_id,
IN Dict<String,String> details,
IN CheckAuthorizationFlags flags,
IN String cancellation_id,
OUT AuthorizationResult result)
CancelCheckAuthorization (IN String cancellation_id)
RegisterAuthenticationAgent (IN Subject subject,
IN String locale,
IN String object_path)
RegisterAuthenticationAgentWithOptions (IN Subject subject,
IN String locale,
IN String object_path,
IN Dict<String,Variant> options)
UnregisterAuthenticationAgent (IN Subject subject,
IN String object_path)
AuthenticationAgentResponse (IN String cookie,
IN Identity identity)
AuthenticationAgentResponse2 (IN uint32 uid, IN String cookie,
IN Identity identity)
AuthenticationAgentResponse3 (IN String cookie,
IN Identity identity,
IN Subject subject)
EnumerateTemporaryAuthorizations (IN Subject subject,
OUT Array<TemporaryAuthorization> temporary_authorizations)
RevokeTemporaryAuthorizations (IN Subject subject)
RevokeTemporaryAuthorizationById (IN String id)
Signals
Changed ()
Properties
BackendName readable String
BackendVersion readable String
BackendFeatures readable AuthorityFeatures
Description
This D-Bus interface is implemented by the /org/freedesktop/PolicyKit1/Authority object on the well-known name org.freedesktop.PolicyKit1 on the system message bus.
EnumerationsThe CheckAuthorizationFlags Flags
{
None = 0x00000000,
AllowUserInteraction = 0x00000001,
AlwaysCheck = 0x00000002
}
Flags used in the CheckAuthorization() method.
None
No flags set.
AllowUserInteraction
If the Subject can obtain the authorization through authentication, and an authentication agent is available, then attempt to do so. Note, this means that the CheckAuthorization() method will block while the user is being asked to authenticate.
AlwaysCheck
Check access against policy even if the Subject is the root user.
The ImplicitAuthorization Enumeration
{
NotAuthorized = 0,
AuthenticationRequired = 1,
AdministratorAuthenticationRequired = 2,
AuthenticationRequiredRetained = 3,
AdministratorAuthenticationRequiredRetained = 4,
Authorized = 5
}
An enumeration for granting implicit authorizations.
NotAuthorized
The Subject is not authorized.
AuthenticationRequired
Authentication is required.
AdministratorAuthenticationRequired
Authentication as an administrator is required.
AuthenticationRequiredRetained
Authentication is required. If the authorization is obtained, it is retained.
AdministratorAuthenticationRequiredRetained
Authentication as an administrator is required. If the authorization is obtained, it is retained.
Authorized
The subject is authorized.
The org.freedesktop.PolicyKit1.Error.* Error Domain
{
org.freedesktop.PolicyKit1.Error.Failed,
org.freedesktop.PolicyKit1.Error.Cancelled,
org.freedesktop.PolicyKit1.Error.NotSupported,
org.freedesktop.PolicyKit1.Error.NotAuthorized,
org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique
}
Errors that can be returned by various method calls.
org.freedesktop.PolicyKit1.Error.Failed
The operation failed.
org.freedesktop.PolicyKit1.Error.Cancelled
The operation was cancelled.
org.freedesktop.PolicyKit1.Error.NotSupported
The operation is not supported.
org.freedesktop.PolicyKit1.Error.NotAuthorized
You are not authorized to perform the requested operation.
org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique
The passed cancellation_id is already in use.
The AuthorityFeatures Flags
{
None = 0x00000000,
TemporaryAuthorization = 0x00000001
}
Flags describing features supported by the Authority implementation.
None
No flags set.
TemporaryAuthorization
The authority supports temporary authorizations that can be obtained through authentication.
StructuresThe Subject Structure
{
String subject_kind,
Dict<String,Variant> subject_details
}
This struct describes subjects such as UNIX processes. It is typically used to check if a given process is authorized for an action.The following kinds of subjects are known:Unix Processsubject_kind should be set to unix-process with keys pidfd (of type int32) and uid (of type int32) (if the operating system supports ProcessID File Descriptors), or alternatively with keys pid (of type uint32), uid (of type int32) and start-time (of type uint64).Unix Sessionsubject_kind should be set to unix-session with the key session-id (of type string).System Bus Namesubject_kind should be set to system-bus-name with the key name (of type string).String subject_kind
The type of the subject.
Dict<String,Variant> subject_details
Details about the subject. Depending of the value of subject_kind, a set of well-defined key/value pairs are guaranteed to be available.
The Identity Structure
{
String identity_kind,
Dict<String,Variant> identity_details
}
This struct describes identities such as UNIX users and UNIX groups. It is typically used to check if a given process is authorized for an action.The following kinds of identities are known:Unix Useridentity_kind should be set to unix-user with key uid (of type uint32).Unix Groupidentity_kind should be set to unix-group with key gid (of type uint32).String identity_kind
Type of identity.
Dict<String,Variant> identity_details
Details about the identity. Depending of the value of identity_kind, a set of well-defined key/value pairs are guaranteed to be available.
The ActionDescription Structure
{
String action_id,
String description,
String message,
String vendor_name,
String vendor_url,
String icon_name,
ImplicitAuthorization implicit_any,
ImplicitAuthorization implicit_inactive,
ImplicitAuthorization implicit_active,
Dict<String,String> annotations
}
This struct describes actions registered with the PolicyKit daemon.
String action_id
Action Identifier.
String description
Localized description of the action.
String message
Localized message to be displayed when making the user authenticate for an action.
String vendor_name
Name of the provider of the action or the empty string.
String vendor_url
A URL pointing to a place with more information about the action or the empty string.
String icon_name
The themed icon describing the action or the empty string if no icon is set.
ImplicitAuthorization implicit_any
A value from the ImplicitAuthorization. enumeration for implicit authorizations that apply to any Subject.
ImplicitAuthorization implicit_inactive
A value from the ImplicitAuthorization. enumeration for implicit authorizations that apply any Subject in an inactive user session on the local console.
ImplicitAuthorization implicit_active
A value from the ImplicitAuthorization. enumeration for implicit authorizations that apply any Subject in an active user session on the local console.
Dict<String,String> annotations
Annotations for the action.
The AuthorizationResult Structure
{
Boolean is_authorized,
Boolean is_challenge,
Dict<String,String> details
}
Describes the result of calling CheckAuthorization().
Boolean is_authorized
TRUE if the given Subject is authorized for the given action.
Boolean is_challenge
TRUE if the given Subject could be authorized if more information was provided, and CheckAuthorizationFlags.AllowUserInteraction wasn't passed or no suitable authentication agent was available.
Dict<String,String> details
Details for the result. Known key/value-pairs include polkit.temporary_authorization_id (if the authorization is temporary, this is set to the opaque temporary authorization id), polkit.retains_authorization_after_challenge (Set to a non-empty string if the authorization will be retained after authentication (if is_challenge is TRUE)), polkit.dismissed (Set to a non-empty string if the authentication dialog was dismissed by the user), polkit.result (Set to the string value of the polkit.Result enum, e.g.: auth_admin).
The TemporaryAuthorization Structure
{
String id,
String action_id,
Subject subject,
UInt64 time_obtained,
UInt64 time_expires
}
This struct describes a temporary authorization.
String id
An opaque identifier for the temporary authorization.
String action_id
The action the temporary authorization is for.
Subject subject
The subject the temporary authorization is for.
UInt64 time_obtained
When the temporary authorization was obtained, in seconds since the Epoch Jan 1, 1970 0:00 UTC.
Note that the PolicyKit daemon is using monotonic time internally so the returned value may change if system time changes.
UInt64 time_expires
When the temporary authorization is set to expire, in seconds since the Epoch Jan 1, 1970 0:00 UTC.
Note that the PolicyKit daemon is using monotonic time internally so the returned value may change if system time changes.
Method DetailsEnumerateActions ()
EnumerateActions (IN String locale,
OUT Array<ActionDescription> action_descriptions)
Enumerates all registered PolicyKit actions.
IN String locale:
The locale to get descriptions in or the blank string to use the system locale.
OUT Array<ActionDescription> action_descriptions:
An array of ActionDescription structs.
CheckAuthorization ()
CheckAuthorization (IN Subject subject,
IN String action_id,
IN Dict<String,String> details,
IN CheckAuthorizationFlags flags,
IN String cancellation_id,
OUT AuthorizationResult result)
Checks if subject is authorized to
perform the action with identifier
action_id
If cancellation_id is non-empty and
already in use for the caller, the org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique
error is returned.
Note that CheckAuthorizationFlags.AllowUserInteraction
SHOULD be passed ONLY if the event that triggered the
authorization check is stemming from an user action, e.g. the
user pressing a button or attaching a device.
IN Subject subject:
A Subject struct.
IN String action_id:
Identifier for the action that subject is attempting to do.
IN Dict<String,String> details:
Details describing the action. Keys starting with polkit. are can only be set if defined in this document.
Known keys include polkit.message and
polkit.gettext_domain that can be used to
override the message shown to the user. This latter is needed
because the user could be running an authentication agent in
another locale than the calling process.
The (translated version of) polkit.message
may include references to other keys that are expanded with
their respective values. For example if the key
device_file has the value
/dev/sda then the message
"Authenticate to format $(device_file)" is
expanded to "Authenticate to format
/dev/sda".
The key polkit.icon_name is used to override the icon shown in the authentication dialog.
If non-empty, then the request will fail with
org.freedesktop.PolicyKit1.Error.Failed
unless the process doing the check itself is sufficiently authorized (e.g. running as uid 0).
IN CheckAuthorizationFlags flags:
A set of CheckAuthorizationFlags.
IN String cancellation_id:
A unique id used to cancel the the authentication check via CancelCheckAuthorization() or the empty string if cancellation is not needed.
OUT AuthorizationResult result:
An AuthorizationResult structure.
CancelCheckAuthorization ()
CancelCheckAuthorization (IN String cancellation_id)
Cancels an authorization check.
IN String cancellation_id:
The cancellation_id passed to CheckAuthorization().
RegisterAuthenticationAgent ()
RegisterAuthenticationAgent (IN Subject subject,
IN String locale,
IN String object_path)
Register an authentication agent.Note that this should be called by same effective UID which will be passed to AuthenticationAgentResponse2().IN Subject subject:
The subject to register the authentication agent for, typically a session subject.
IN String locale:
The locale of the authentication agent.
IN String object_path:
The object path of authentication agent object on the unique name of the caller.
RegisterAuthenticationAgentWithOptions ()
RegisterAuthenticationAgentWithOptions (IN Subject subject,
IN String locale,
IN String object_path,
IN Dict<String,Variant> options)
Like RegisterAuthenticationAgent but takes additional options. If the option fallback (of type Boolean) is TRUE, then the authentcation agent will only be used as a fallback, e.g. if another agent (without the fallback option set TRUE) is available, it will be used instead.UnregisterAuthenticationAgent ()
UnregisterAuthenticationAgent (IN Subject subject,
IN String object_path)
Unregister an authentication agent.
IN Subject subject:
The subject passed to RegisterAuthenticationAgent().
IN String object_path:
The object_path passed to RegisterAuthenticationAgent().
AuthenticationAgentResponse ()
AuthenticationAgentResponse (IN String cookie,
IN Identity identity)
Method for authentication agents to invoke on successful
authentication, intended only for use by a privileged helper process
internal to polkit. This method will fail unless a sufficiently privileged
+caller invokes it. Deprecated in favor of AuthenticationAgentResponse2().
IN String cookie:
The cookie identifying the authentication request that was passed to the authentication agent.
IN Identity identity:
A Identity struct describing what identity was authenticated.
AuthenticationAgentResponse2 ()
AuthenticationAgentResponse2 (IN uint32 uid,
IN String cookie,
IN Identity identity)
Method for authentication agents to invoke on successful
authentication, intended only for use by a privileged helper process
internal to polkit. This method will fail unless a sufficiently privileged
caller invokes it. Note this method was introduced in 0.114 and should be
preferred over AuthenticationAgentResponse()
as it fixes a security issue.
IN uint32 uid:
The user id of the agent; normally this is the owner of the parent pid
of the process that invoked the internal setuid helper.
IN String cookie:
The cookie identifying the authentication request that was passed to the authentication agent.
IN Identity identity:
A Identity struct describing what identity was authenticated.
AuthenticationAgentResponse3 ()
AuthenticationAgentResponse3 (IN String cookie,
IN Identity identity,
IN Subject subject)
Method for authentication agents to invoke on successful
authentication, intended only for use by a privileged helper process
running via socket activation. This method will fail unless a sufficiently privileged
caller invokes it. In contract to other methods this takes a subject as input, which
allows reliably tracking the requester via PID FD.
IN String cookie:
The cookie identifying the authentication request that was passed to the authentication agent.
IN Identity identity:
A Identity struct describing what identity was authenticated.
IN Subject subject:
A Subject struct describing what entity requested the authentication.
EnumerateTemporaryAuthorizations ()
EnumerateTemporaryAuthorizations (IN Subject subject,
OUT Array<TemporaryAuthorization> temporary_authorizations)
Retrieves all temporary authorizations that applies to subject.
IN Subject subject:
The subject to get temporary authorizations for.
OUT Array<TemporaryAuthorization> temporary_authorizations:
An array of TemporaryAuthorization structs.
RevokeTemporaryAuthorizations ()
RevokeTemporaryAuthorizations (IN Subject subject)
Revokes all temporary authorizations that applies to subject.
IN Subject subject:
The subject to revoke temporary authorizations from.
RevokeTemporaryAuthorizationById ()
RevokeTemporaryAuthorizationById (IN String id)
Revokes all temporary authorizations that applies to subject.
IN String id:
The opaque identifier of the temporary authorization.
Signal DetailsThe "Changed" signal
Changed ()
This signal is emitted when actions and/or authorizations change
Property DetailsThe "BackendName" property
BackendName readable String
The name of the currently used Authority backend.
The "BackendVersion" property
BackendVersion readable String
The version of the currently used Authority backend.
The "BackendFeatures" property
BackendFeatures readable AuthorityFeatures
The features supported by the currently used Authority backend.