pqspolicy.h File Reference

PQS server-side command policy database functions. More...

#include "pqs.h"

Go to the source code of this file.

Data Structures
struct	pqs_policy_record
	A PQS server command policy record. More...
struct	pqs_policy_store
	The fixed-size PQS command policy database. More...

Macros
#define	PQS_POLICY_DATABASE_MAGIC   "PQSPOLICYDB1"
	The fixed text header written to PQS command policy database files.
#define	PQS_POLICY_DEFAULT_GUEST   "guest"
	The default guest privilege command policy name.
#define	PQS_POLICY_DEFAULT_USER   "user"
	The default user privilege command policy name.
#define	PQS_POLICY_DEFAULT_ADMIN   "admin"
	The default administrative privilege command policy name.

Typedefs
typedef PQS_EXPORT_API enum pqs_policy_modes	pqs_policy_modes
typedef PQS_EXPORT_API struct pqs_policy_record	pqs_policy_record
typedef PQS_EXPORT_API struct pqs_policy_store	pqs_policy_store

Enumerations
enum	pqs_policy_modes { pqs_policy_mode_none = 0x00U , pqs_policy_mode_restricted = 0x01U , pqs_policy_mode_forced = 0x02U , pqs_policy_mode_raw = 0x03U }
	Command policy execution modes. More...

Functions
PQS_EXPORT_API bool	pqs_policy_store_add (pqs_policy_store *store, const char *name, pqs_policy_modes mode, uint32_t privilege_mask, bool enabled)
	Add a command policy record to a policy store.
PQS_EXPORT_API bool	pqs_policy_store_add_command (pqs_policy_store *store, const char *name, const char *command, bool allowed)
	Add a command verb to a policy allow-list or deny-list.
PQS_EXPORT_API bool	pqs_policy_store_assign_privilege (pqs_policy_store *store, pqs_user_privileges privilege, const char *policy)
	Assign a named policy to a privilege level.
PQS_EXPORT_API bool	pqs_policy_command_is_safe (const char *command)
	Authorize a command for a privilege level using the active policy assignment.
PQS_EXPORT_API bool	pqs_policy_store_authorize (const pqs_policy_store *store, pqs_user_privileges privilege, const char *command, const pqs_policy_record **matched)
	Authorizes a command request against the policy assigned to a privilege class.
PQS_EXPORT_API bool	pqs_policy_store_enable (pqs_policy_store *store, const char *name, bool enabled)
	Enable or disable a command policy record.
PQS_EXPORT_API const pqs_policy_record *	pqs_policy_store_find (const pqs_policy_store *store, const char *name)
	Find a command policy record by name.
PQS_EXPORT_API pqs_policy_record *	pqs_policy_store_find_mutable (pqs_policy_store *store, const char *name)
	Find a mutable command policy record by name.
PQS_EXPORT_API bool	pqs_policy_store_initialize (pqs_policy_store *store, const char *path)
	Initialize a command policy store from persistent storage.
PQS_EXPORT_API bool	pqs_policy_store_remove (pqs_policy_store *store, const char *name)
	Remove a command policy record from a policy store.
PQS_EXPORT_API bool	pqs_policy_store_remove_command (pqs_policy_store *store, const char *name, const char *command, bool allowed)
	Remove a command verb from a policy allow-list or deny-list.
PQS_EXPORT_API bool	pqs_policy_store_save (const pqs_policy_store *store)
	Save a command policy store to persistent storage.
PQS_EXPORT_API bool	pqs_policy_store_set_forced (pqs_policy_store *store, const char *name, const char *command)
	Set the forced command associated with a command policy.
PQS_EXPORT_API bool	pqs_policy_store_set_mode (pqs_policy_store *store, const char *name, pqs_policy_modes mode)
	Set the enforcement mode of a command policy.
PQS_EXPORT_API const char *	pqs_policy_mode_to_string (pqs_policy_modes mode)
	Convert a policy mode enumeration value to a string.
PQS_EXPORT_API pqs_policy_modes	pqs_policy_mode_from_string (const char *value)
	Convert a policy mode string to a policy mode enumeration value.
PQS_EXPORT_API uint32_t	pqs_policy_privilege_to_mask (pqs_user_privileges privilege)
	Convert a PQS user privilege level to a policy privilege mask.

Detailed Description

PQS server-side command policy database functions.

Enumeration Type Documentation

pqs_policy_modes

enum pqs_policy_modes

Command policy execution modes.

Enumerator
pqs_policy_mode_none	No command execution is permitted.
pqs_policy_mode_restricted	Only explicitly allowed commands are permitted.
pqs_policy_mode_forced	Only the configured forced command is permitted.
pqs_policy_mode_raw	Raw shell command execution is permitted.

Function Documentation

pqs_policy_command_is_safe()

PQS_EXPORT_API bool pqs_policy_command_is_safe

(

const char *

command

)

Authorize a command for a privilege level using the active policy assignment.

Parameters

store	[const struct] A pointer to the policy store to query.
privilege	[enum] The authenticated user's privilege level.
command	[const] The NUL-terminated command string or command verb to evaluate.
matched	[const struct] A pointer to the matched policy record output parameter.

Returns

Returns true if the command is authorized by the matched policy; otherwise, returns false.

Test whether a user-supplied shell command avoids shell-control metacharacters.

Parameters

command

[const] The NUL-terminated command string.

Returns

Returns true if the command contains only direct-command characters; otherwise, returns false.

pqs_policy_mode_from_string()

PQS_EXPORT_API pqs_policy_modes pqs_policy_mode_from_string

(

const char *

value

)

Convert a policy mode string to a policy mode enumeration value.

Parameters

value

[const] The NUL-terminated policy mode string.

Returns

Returns the corresponding policy mode value, or the default invalid/disabled value when the string is not recognized.

pqs_policy_mode_to_string()

PQS_EXPORT_API const char * pqs_policy_mode_to_string

(

pqs_policy_modes

mode

)

Convert a policy mode enumeration value to a string.

Parameters

mode	[enum] The policy mode value to convert.

Returns

Returns a constant NUL-terminated string representing the policy mode.

pqs_policy_privilege_to_mask()

PQS_EXPORT_API uint32_t pqs_policy_privilege_to_mask

(

pqs_user_privileges

privilege

)

Convert a PQS user privilege level to a policy privilege mask.

Parameters

privilege

[enum] The user privilege level to convert.

Returns

Returns the policy privilege mask corresponding to the user privilege level.

pqs_policy_store_add()

PQS_EXPORT_API bool pqs_policy_store_add	(	pqs_policy_store *	store,
		const char *	name,
		pqs_policy_modes	mode,
		uint32_t	privilege_mask,
		bool	enabled )

Add a command policy record to a policy store.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
mode	[enum] The policy enforcement mode.
privilege_mask	The privilege mask allowed to use the policy.
enabled	A flag indicating whether the policy is enabled.

Returns

Returns true if the policy record was added; otherwise, returns false.

pqs_policy_store_add_command()

PQS_EXPORT_API bool pqs_policy_store_add_command	(	pqs_policy_store *	store,
		const char *	name,
		const char *	command,
		bool	allowed )

Add a command verb to a policy allow-list or deny-list.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
command	[const] The NUL-terminated command verb to add.
allowed	A flag selecting the target list; true adds to the allow-list, false adds to the deny-list.

Returns

Returns true if the command was added to the selected policy list; otherwise, returns false.

pqs_policy_store_assign_privilege()

PQS_EXPORT_API bool pqs_policy_store_assign_privilege	(	pqs_policy_store *	store,
		pqs_user_privileges	privilege,
		const char *	policy )

Assign a named policy to a privilege level.

Parameters

store	[struct] A pointer to the policy store to update.
privilege	[enum] The privilege level to assign.
policy	[const] The NUL-terminated policy name to associate with the privilege level.

Returns

Returns true if the privilege assignment was updated; otherwise, returns false.

pqs_policy_store_authorize()

PQS_EXPORT_API bool pqs_policy_store_authorize	(	const pqs_policy_store *	store,
		pqs_user_privileges	privilege,
		const char *	command,
		const pqs_policy_record **	matched )

Authorizes a command request against the policy assigned to a privilege class.

Evaluates the command policy associated with the supplied privilege level and determines whether the requested command is permitted. The function resolves the policy record assigned to privilege, validates the supplied command string, extracts the command verb used for policy matching, and applies the configured policy mode.

The authorization result depends on the matched policy mode:

• pqs_policy_mode_none denies all command execution.
• pqs_policy_mode_restricted permits only commands present in the policy allow list.
• pqs_policy_mode_forced permits execution through the configured forced command.
• pqs_policy_mode_raw permits commands unless explicitly denied by the policy.

User-supplied command strings are also subject to shell-safety validation. Commands containing shell-control metacharacters or unsafe shell syntax are rejected before execution authorization succeeds. This prevents a permitted command verb from being used to carry additional shell expressions that would bypass the policy decision.

If matched is not NULL, it receives the address of the policy record used for the decision when a policy is resolved. The returned pointer refers to storage owned by store and remains valid only while the store remains valid and unmodified.

Parameters

store	[const] A pointer to the initialized policy store.
privilege	[enum] The user privilege class whose assigned policy is evaluated.
command	[const] A pointer to the NUL-terminated command string to authorize.
matched	[out] An optional pointer that receives the matched policy record.

Returns

Returns true if the command is authorized by the matched policy; otherwise, returns false.

pqs_policy_store_enable()

PQS_EXPORT_API bool pqs_policy_store_enable	(	pqs_policy_store *	store,
		const char *	name,
		bool	enabled )

Enable or disable a command policy record.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
enabled	A flag indicating whether the policy is enabled.

Returns

Returns true if the policy state was updated; otherwise, returns false.

pqs_policy_store_find()

PQS_EXPORT_API const pqs_policy_record * pqs_policy_store_find	(	const pqs_policy_store *	store,
		const char *	name )

Find a command policy record by name.

Parameters

store	[const struct] A pointer to the policy store to query.
name	[const] The NUL-terminated policy name.

Returns

Returns a constant pointer to the matching policy record, or NULL if no matching record exists.

pqs_policy_store_find_mutable()

PQS_EXPORT_API pqs_policy_record * pqs_policy_store_find_mutable	(	pqs_policy_store *	store,
		const char *	name )

Find a mutable command policy record by name.

Parameters

store	[struct] A pointer to the policy store to query.
name	[const] The NUL-terminated policy name.

Returns

Returns a mutable pointer to the matching policy record, or NULL if no matching record exists.

pqs_policy_store_initialize()

PQS_EXPORT_API bool pqs_policy_store_initialize	(	pqs_policy_store *	store,
		const char *	path )

Initialize a command policy store from persistent storage.

Parameters

store	[struct] A pointer to the policy store to initialize.
path	[const] The NUL-terminated path to the policy database file.

Returns

Returns true if the policy store was initialized; otherwise, returns false.

pqs_policy_store_remove()

PQS_EXPORT_API bool pqs_policy_store_remove	(	pqs_policy_store *	store,
		const char *	name )

Remove a command policy record from a policy store.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.

Returns

Returns true if the policy record was removed; otherwise, returns false.

pqs_policy_store_remove_command()

PQS_EXPORT_API bool pqs_policy_store_remove_command	(	pqs_policy_store *	store,
		const char *	name,
		const char *	command,
		bool	allowed )

Remove a command verb from a policy allow-list or deny-list.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
command	[const] The NUL-terminated command verb to remove.
allowed	A flag selecting the target list; true removes from the allow-list, false removes from the deny-list.

Returns

Returns true if the command was removed from the selected policy list; otherwise, returns false.

pqs_policy_store_save()

PQS_EXPORT_API bool pqs_policy_store_save

(

const pqs_policy_store *

store

)

Save a command policy store to persistent storage.

Parameters

store

[const struct] A pointer to the policy store to save.

Returns

Returns true if the policy store was written successfully; otherwise, returns false.

pqs_policy_store_set_forced()

PQS_EXPORT_API bool pqs_policy_store_set_forced	(	pqs_policy_store *	store,
		const char *	name,
		const char *	command )

Set the forced command associated with a command policy.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
command	[const] The NUL-terminated forced command string.

Returns

Returns true if the forced command was updated; otherwise, returns false.

pqs_policy_store_set_mode()

PQS_EXPORT_API bool pqs_policy_store_set_mode	(	pqs_policy_store *	store,
		const char *	name,
		pqs_policy_modes	mode )

Set the enforcement mode of a command policy.

Parameters

store	[struct] A pointer to the policy store to update.
name	[const] The NUL-terminated policy name.
mode	[enum] The new policy enforcement mode.

Returns

Returns true if the policy mode was updated; otherwise, returns false.