'\" t
.\" Title: pkla-check-authorization
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: May 2013
.\" Manual: pkla-check-authorization
.\" Source: polkit-pkla-compat
.\" Language: English
.\"
.TH "PKLA\-CHECK\-AUTHORI" "8" "May 2013" "polkit-pkla-compat" "pkla-check-authorization"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pkla-check-authorization \- Evaluate pklocalauthority authorization configuration
.SH "SYNOPSIS"
.HP \w'\fBpkla\-check\-authorization\fR\ 'u
\fBpkla\-check\-authorization\fR [\fB\-\-help\fR]
.HP \w'\fBpkla\-check\-authorization\fR\ 'u
\fBpkla\-check\-authorization\fR [\fB\-\-paths\fR\ \fIpaths\fR] {\fIuser\-name\fR} {\fIis\-local\fR} {\fIis\-active\fR} {\fIaction\fR}
.SH "DESCRIPTION"
.PP
\fBpkla\-check\-authorization\fR
interprets non\-JavaScript configuration files described below to determine the response of
\fBpolkit\fR(8)
to authorization queries\&.
.PP
\fINote:\fR
Authorization decision evaluation is driven by JavaScript rules as described in
\fBpolkit\fR(8)\&.
\fBpkla\-check\-authorization\fR
is called by a JavaScript rule file named
49\-polkit\-pkla\-compat\&.rules; other JavaScript rules with a higher priority may exist, so the
\fBpkla\-check\-authorization\fR
configuration may not necessarily govern the final
\fBpolkit\fR(8)
authorization decision\&.
.PP
The ordering of the JavaScript rule files and the ordering of
\fBpkla\-check\-authorization\fR
configuration files is not integrated and uses different rules; the
\fBpkla\-check\-authorization\fR
configuration evaluation is happens at a single point within the JavaScript rule evaluation order\&.
.PP
\fBpkla\-check\-authorization\fR
is an internal helper program of
pkla\-polkit\-compat\&. You shouldn\*(Aqt need to run it directly, except for debugging purposes\&.
.PP
The arguments to
\fBpkla\-check\-authorization\fR
are, in order:
.PP
\fIuser\-name\fR
.RS 4
Name of the user account asking for authorization
.RE
.PP
\fIis\-local\fR
.RS 4
Whether the attempted action is performed from a local login session,
true
or
false\&.
.RE
.PP
\fIis\-active\fR
.RS 4
Whether the attempted action is performed from a currently active session (e\&.g\&. currently active virtual console),
true
or
false\&.
.RE
.PP
\fIaction\fR
.RS 4
A string identifying the
\fBpolkit\fR(8)
action\&.
.RE
.PP
If the configuration specifies an authorization decision,
\fBpkla\-check\-authorization\fR
outputs the decision and a terminating newline\&. If no decision is configured, the output is empty\&.
.SH "OPTIONS"
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Write a summary of the available options to standard output and exit successfully\&.
.RE
.PP
\fB\-p\fR, \fB\-\-paths\fR=\fIpaths\fR
.RS 4
Search for configuration files in semicolon\-separated
\fIpaths\fR
instead of the default
/var/lib/polkit\-1/localauthority;/etc/polkit\-1/localauthority\&.
.RE
.SH "EXIT STATUS"
.PP
\fBpkla\-check\-authorization\fR
exits with 0 on success (even if there is no decision configured), and a non\-zero status on error\&.
.SH "DIRECTORY STRUCTURE"
.PP
Files with
\&.pkla
extension are read from all directories located inside the
/etc/polkit\-1/localauthority
and
/var/lib/polkit\-1/localauthority
directories (or as specified using the
\fB\-\-paths\fR
option)\&. By default, the following sub\-directories are installed\&.
.sp
.if n \{\
.RS 4
.\}
.nf
/etc/polkit\-1/
`\-\- localauthority
|\-\- 10\-vendor\&.d
|\-\- 20\-org\&.d
|\-\- 30\-site\&.d
|\-\- 50\-local\&.d
`\-\- 90\-mandatory\&.d
.fi
.if n \{\
.RE
.\}
.PP
and
.sp
.if n \{\
.RS 4
.\}
.nf
/var/lib/polkit\-1/
`\-\- localauthority
|\-\- 10\-vendor\&.d
|\-\- 20\-org\&.d
|\-\- 30\-site\&.d
|\-\- 50\-local\&.d
`\-\- 90\-mandatory\&.d
.fi
.if n \{\
.RE
.\}
.PP
The
/etc/polkit\-1/localauthority
hierarchy is intended for local configuration and the
/var/lib/polkit\-1/localauthority
is intended for 3rd party packages\&.
.PP
Each
\&.pkla
file contains one or more authorization entries\&. If the underlying filesystem supports file monitoring, the Local Authority will reload information whenever
\&.pkla
files are added, removed or changed\&.
.PP
Each directory is intended for a specific audience
.PP
\fI10\-vendor\&.d\fR
.RS 4
Intended for use by the OS vendor\&.
.RE
.PP
\fI20\-org\&.d\fR
.RS 4
Intended for the organization deploying the OS\&.
.RE
.PP
\fI30\-site\&.d\fR
.RS 4
Intended for the site deploying the system\&.
.RE
.PP
\fI50\-local\&.d\fR
.RS 4
Intended for local usage\&.
.RE
.PP
\fI90\-mandatory\&.d\fR
.RS 4
Intended for the organization deploying the OS\&.
.RE
.PP
and new directories can be added/removed as needed\&.
.PP
As to regards to the content, each
\&.pkla
file is a standard
\fIkey file\fR
and contains key/value pairs in one or more groups with each group representing an authorization entry\&. A
\&.pkla
file MUST be named by using a scheme to ensure that the name is unique, e\&.g\&. reverse DNS notation or similar\&. For example, if the organization is
\(lqAcme Corp\(rq
needs to modify policy for the product
\(lqFrobnicator\(rq, a name like
com\&.acme\&.frobnicator\&.pkla
would be suitable\&.
.SH "AUTHORIZATION ENTRY"
.PP
Each group in a
\&.pkla
file must have a name that is unique within the file it belongs to\&. The following keys are recognized:
.PP
\fIIdentity\fR
.RS 4
A semi\-colon separated list of entries to match identities\&. Each entry should start with
unix\-user:
or
unix\-group:
to specify whether to match on a UNIX user name or a UNIX group name, and continue with a glob matching the group or user name\&. Netgroups are supported with the
unix\-netgroup:
prefix, but cannot support glob syntax\&. Finally, an entry "default" (with no prefix) can be used to specify the default match\&.
.RE
.PP
\fIAction\fR
.RS 4
A semi\-colon separated list of globs to match action identifiers\&.
.RE
.PP
\fIResultActive\fR
.RS 4
The result to return for subjects in an active local session that matches one or more of the given identities\&. Allowed values are similar to what can be used in the
\fIdefaults\fR
section of
\&.policy
files used to define actions, e\&.g\&.
yes,
no,
auth_self,
auth_self_keep,
auth_admin
and
auth_admin_keep\&.
.RE
.PP
\fIResultInactive\fR
.RS 4
Like
\fIResultActive\fR
but instead applies to subjects in inactive local sessions\&.
.RE
.PP
\fIResultAny\fR
.RS 4
Like
\fIResultActive\fR
but instead applies to any subject\&.
.RE
.PP
All keys specified above are required except that only at least one of
\fIResultAny\fR,
\fIResultInactive\fR
and
\fIResultActive\fR
must be present\&.
.SH "EVALUATION ORDER"
.PP
The authorization entries discussed above are consulted using the following algorithm\&.
.PP
The authorization entries from all \&.pkla files are ordered using the following rules\&. First all the basename of all sub\-directories (e\&.g\&.
\fI30\-site\&.d\fR) from both the
/etc/polkit\-1/localauthority
and
/var/lib/polkit\-1/localauthority
directories are enumerated and sorted (using the C locale)\&. If a name exists in both
/etc
and
/var, the one in
/etc
takes precedence\&. Then all
\&.pkla
files are read in order from this list of sub\-directories\&. For each
\&.pkla
file, authorizations from each file are appended in order resulting in an ordered list of authorization entries\&.
.PP
For example, given the following files
.sp
.if n \{\
.RS 4
.\}
.nf
/var/lib/polkit\-1
└── localauthority
├── 10\-vendor\&.d
│ └── 10\-desktop\-policy\&.pkla
├── 20\-org\&.d
├── 30\-site\&.d
├── 50\-local\&.d
├── 55\-org\&.my\&.company\&.d
│ └── 10\-org\&.my\&.company\&.product\&.pkla
└── 90\-mandatory\&.d
/etc/polkit\-1
└── localauthority
├── 10\-vendor\&.d
│ └── 01\-some\-changes\-from\-a\-subvendor\&.pkla
├── 20\-org\&.d
├── 30\-site\&.d
├── 50\-local\&.d
├── 55\-org\&.my\&.company\&.d
│ └── 10\-org\&.my\&.company\&.product\&.pkla
└── 90\-mandatory\&.d
.fi
.if n \{\
.RE
.\}
.PP
the evaluation order of the
\&.pkla
files is:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
10\-desktop\-policy\&.pkla
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
01\-some\-changes\-from\-a\-subvendor\&.pkla
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
10\-org\&.my\&.company\&.product\&.pkla
(the
/var
one)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
10\-org\&.my\&.company\&.product\&.pkla
(the
/etc
one)
.RE
.PP
When the list of authorization entries has been calculated, the authorization check can be made\&. First, the user of the Subject is determined and the groups that the user belongs are looked up\&.
.PP
Then, authorization entries that include the "default" field value in the
\fIIdentity\fR
field are consulted in order\&. If the authorization entry matches the data from the authorization check, then the authorization result from
\fIRequireAny\fR,
\fIRequireInactive\fR
or
\fIRequireActive\fR
is used\&.
.PP
Next, for each group identity, all authorization entries that contain a matching group entry are again consulted in the same manner\&.
.PP
Finally, the authorization entries are consulted using the user identity in the same manner\&.
.PP
Note that processing continues even after a match\&. This allows for so called
\(lqnegative authorizations\(rq, see
the section called \(lqEXAMPLE\(rq
for further discussion\&.
.SH "EXAMPLE"
.PP
The following
\&.pkla
file grants authorization to all users in the
staff
group for actions matching the glob
com\&.example\&.awesomeproduct\&.*
provided they are in an active session on the local console:
.sp
.if n \{\
.RS 4
.\}
.nf
[Normal Staff Permissions]
Identity=unix\-group:staff
Action=com\&.example\&.awesomeproduct\&.*
ResultAny=no
ResultInactive=no
ResultActive=yes
.fi
.if n \{\
.RE
.\}
.PP
If the users
homer
and
grimes
are member of the
staff
group but policy requires that an administrator needs to authenticate every time authorization for any action matching
com\&.example\&.awesomeproduct\&.*
is required, one would add
.sp
.if n \{\
.RS 4
.\}
.nf
[Exclude Some Problematic Users]
Identity=unix\-user:homer;unix\-user:grimes
Action=com\&.example\&.awesomeproduct\&.*
ResultAny=no
ResultInactive=no
ResultActive=auth_admin
.fi
.if n \{\
.RE
.\}
.PP
and make sure this authorization entry is after the first one\&.
.PP
The following entry modifies the default authorization decision (it is overridden by any entry that matches using
unix\-user:
or
unix\-group:, but overrides any defaults set by the application author in an
\&.action
file):
.sp
.if n \{\
.RS 4
.\}
.nf
[Disable Access by Default]
Identity=default
Action=com\&.example\&.awesomeproduct\&.*
ResultAny=no
ResultInactive=no
ResultActive=no
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.PP
/etc/polkit\-1/localauthority, /var/lib/polkit\-1/localauthority
.RS 4
Default directories containing decision configuration files\&.
.RE
.SH "AUTHOR"
.PP
Written by David Zeuthen
with a lot of help from many others\&. Adapted by Miloslav Trmač
\&.
.SH "SEE ALSO"
.PP
\fBpolkit\fR(8)