Core API Reference - Authorization Contraints
Desktop Apps Training - Policy Kit

Authorization Constraints

Authorization Constraints — Conditions that must be satisfied in order for an authorization to apply

 

Synopsis



enum PolKitAuthorizationConstraintType;
PolKitAuthorizationConstraint;
PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_local
(void);
PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_active
(void);
PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_exe
(const char *path);
PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_selinux_context
(const char *context);
PolKitAuthorizationConstraint* polkit_authorization_constraint_ref
(PolKitAuthorizationConstraint *authc);
void polkit_authorization_constraint_unref
(PolKitAuthorizationConstraint *authc);
void polkit_authorization_constraint_debug
(PolKitAuthorizationConstraint *authc);
polkit_bool_t polkit_authorization_constraint_validate
(PolKitAuthorizationConstraint *authc);
PolKitAuthorizationConstraintType polkit_authorization_constraint_type
(PolKitAuthorizationConstraint *authc);
const char* polkit_authorization_constraint_get_exe
(PolKitAuthorizationConstraint *authc);
const char* polkit_authorization_constraint_get_selinux_context
(PolKitAuthorizationConstraint *authc);
polkit_bool_t polkit_authorization_constraint_check_session
(PolKitAuthorizationConstraint *authc,
PolKitSession *session);
polkit_bool_t polkit_authorization_constraint_check_caller
(PolKitAuthorizationConstraint *authc,
PolKitCaller *caller);
size_t polkit_authorization_constraint_to_string
(PolKitAuthorizationConstraint *authc,
char *out_buf,
size_t buf_size);
PolKitAuthorizationConstraint* polkit_authorization_constraint_from_string
(const char *str);
int polkit_authorization_constraint_get_from_caller
(PolKitCaller *caller,
PolKitAuthorizationConstraint **out_array,
size_t array_size);
polkit_bool_t polkit_authorization_constraint_equal
(PolKitAuthorizationConstraint *a,
PolKitAuthorizationConstraint *b);

Description

This class is used to represent conditions that must be satisfied in order for an authorization to apply

 

Details

enum PolKitAuthorizationConstraintType

typedef enum {
POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_LOCAL,
POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_ACTIVE,
POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_EXE,
POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_SELINUX_CONTEXT,
} PolKitAuthorizationConstraintType;

This enumeration describes the type of the authorization constraint.

 

POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_LOCAL

the session or caller must be local

POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_ACTIVE

the session or caller must be in an active local session

POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_EXE

the caller must be a specific program; use polkit_authorization_constraint_get_exe() to get the path of the program.

POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_SELINUX_CONTEXT

the caller must be in a specific security context; use polkit_authorization_constraint_get_selinux_context() to get the security context.

PolKitAuthorizationConstraint

typedef struct _PolKitAuthorizationConstraint PolKitAuthorizationConstraint;

Instances of this class are used to represent conditions that must be satisfied in order for an authorization to apply.

 

Since 0.7


polkit_authorization_constraint_get_require_local ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_local
(void);

Get a PolKitAuthorizationConstraint object that represents the constraint that the session or caller must be local.

 

Returns :

the constraint

Since 0.7


polkit_authorization_constraint_get_require_active ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_active
(void);

Get a PolKitAuthorizationConstraint object that represents the constraint that the session or caller must be active.

 

Returns :

the constraint

Since 0.7


polkit_authorization_constraint_get_require_exe ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_exe
(const char *path);

Get a PolKitAuthorizationConstraint object that represents the constraint that the caller must be a specific program

 

path :

path to program

Returns :

the constraint or NULL on OOM

Since 0.8


polkit_authorization_constraint_get_require_selinux_context ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_get_require_selinux_context
(const char *context);

Get a PolKitAuthorizationConstraint object that represents the constraint that the caller must be in a specific SELinux context.

 

context :

SELinux context

Returns :

the constraint or NULL on OOM

Since 0.8


polkit_authorization_constraint_ref ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_ref
(PolKitAuthorizationConstraint *authc);

Increase reference count.

 

authc :

the object

Returns :

the object

Since 0.7


polkit_authorization_constraint_unref ()

void                polkit_authorization_constraint_unref
(PolKitAuthorizationConstraint *authc);

Decreases the reference count of the object. If it becomes zero, the object is freed. Before freeing, reference counts on embedded objects are decresed by one.

 

authc :

the authorization_constraint object

Since 0.7


polkit_authorization_constraint_debug ()

void                polkit_authorization_constraint_debug
(PolKitAuthorizationConstraint *authc);

Print debug details

 

authc :

the object

Since 0.7


polkit_authorization_constraint_validate ()

polkit_bool_t       polkit_authorization_constraint_validate
(PolKitAuthorizationConstraint *authc);

Validate the object

 

authc :

the object

Returns :

TRUE iff the object is valid.

Since 0.7


polkit_authorization_constraint_type ()

PolKitAuthorizationConstraintType polkit_authorization_constraint_type
(PolKitAuthorizationConstraint *authc);

Describe the constraint; this is only useful when inspecting an authorization to present information to the user (e.g. as polkit-auth(1) does).

 

authc :

the object

Returns :

type from PolKitAuthorizationConstraintType

Since 0.7


polkit_authorization_constraint_get_exe ()

const char*         polkit_authorization_constraint_get_exe
(PolKitAuthorizationConstraint *authc);

Get the exe path for the constraint.

 

authc :

the object

Returns :

The exe path or NULL if type isn't POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_EXE. Caller shall not free this string.

Since 0.8


polkit_authorization_constraint_get_selinux_context ()

const char*         polkit_authorization_constraint_get_selinux_context
(PolKitAuthorizationConstraint *authc);

Get the SELinux context for the constraint.

 

authc :

the object

Returns :

The selinux context or NULL if type isn't POLKIT_AUTHORIZATION_CONSTRAINT_TYPE_REQUIRE_SELINUX_CONTEXT. Caller shall not free this string.

Since 0.8


polkit_authorization_constraint_check_session ()

polkit_bool_t       polkit_authorization_constraint_check_session
(PolKitAuthorizationConstraint *authc,
PolKitSession *session);

Determine if the given session satisfies the conditions imposed by the given constraint.

 

authc :

the object

session :

the session

Returns :

TRUE if, and only if, the given session satisfies the conditions imposed by the given constraint.

Since 0.7


polkit_authorization_constraint_check_caller ()

polkit_bool_t       polkit_authorization_constraint_check_caller
(PolKitAuthorizationConstraint *authc,
PolKitCaller *caller);

Determine if the given caller satisfies the conditions imposed by the given constraint

 

authc :

the object

caller :

the caller

Returns :

TRUE if, and only if, the given caller satisfies the conditions imposed by the given constraint.

Since 0.7


polkit_authorization_constraint_to_string ()

size_t              polkit_authorization_constraint_to_string
(PolKitAuthorizationConstraint *authc,
char *out_buf,
size_t buf_size);

Get a textual representation of the constraint; this is only useful for serializing; it's a machine, not human, readable string.

 

authc :

the object

out_buf :

buffer to store the string representation in

buf_size :

size of buffer

Returns :

Number of characters written (not including trailing '\0'). If the output was truncated due to the buffer being too small, buf_size will be returned. Thus, a return value of buf_size or more indicates that the output was truncated (see snprintf(3)) or an error occured.

Since 0.7


polkit_authorization_constraint_from_string ()

PolKitAuthorizationConstraint* polkit_authorization_constraint_from_string
(const char *str);

Construct a constraint from a textual representation as returned by polkit_authorization_constraint_to_string().

 

str :

textual representation of constraint

Returns :

the constraint or NULL if the string coulnd't be parsed.

polkit_authorization_constraint_get_from_caller ()

int                 polkit_authorization_constraint_get_from_caller
(PolKitCaller *caller,
PolKitAuthorizationConstraint **out_array,
size_t array_size);

Given a caller, return the set of most restrictive constraints possible. For example, if the caller is local and active, a set constraints requiring this will be returned.

This function is typically used when the caller obtains an authorization through authentication; the goal is to put constraints on the authorization such that it's only valid when the caller is in the context as where she obtained it.

The caller must unref all the created objects using polkit_authorization_constraint_unref().

 

caller :

caller

out_array :

return location for constraints

array_size :

size of the passed array

Returns :

If OOM -1 is returned. This function do not create more than array_size constraints (including the trailing NULL). If the output was truncated due to this limit then the return value is the number of objects (not including the trailing NULL) which would have been written to the final array if enough space had been available. Thus, a return value of array_size or more means that the output was truncated.

Since 0.7


polkit_authorization_constraint_equal ()

polkit_bool_t       polkit_authorization_constraint_equal
(PolKitAuthorizationConstraint *a,
PolKitAuthorizationConstraint *b);

Determines if two constraints are equal

 

a :

first constraint

b :

first constraint

Returns :

TRUE only if the given constraints are equal

Since 0.7