pqsuser.h File Reference

PQS server-side user database and passphrase verifier functions. More...

#include "pqs.h"

Go to the source code of this file.

Data Structures
struct	pqs_user_record
	A PQS server user account record. More...
struct	pqs_user_store
	The fixed-size PQS server user database. More...

Macros
#define	PQS_USER_DATABASE_MAGIC   "PQSUSERDB1"
	The fixed text header written to PQS user database files.
#define	PQS_USER_DEFAULT_SHELL_PROFILE   "default"
	The default shell profile name assigned to new users.

Typedefs
typedef PQS_EXPORT_API struct pqs_user_record	pqs_user_record
typedef PQS_EXPORT_API struct pqs_user_store	pqs_user_store

Functions
PQS_EXPORT_API bool	pqs_user_store_add (pqs_user_store *store, const char *username, const char *passphrase, pqs_user_privileges privilege)
	Add a user to the user database.
PQS_EXPORT_API bool	pqs_user_store_enable (pqs_user_store *store, const char *username, bool enabled)
	Disable or enable a user account.
PQS_EXPORT_API const pqs_user_record *	pqs_user_store_find (const pqs_user_store *store, const char *username)
	Find a user record by name.
PQS_EXPORT_API pqs_user_record *	pqs_user_store_find_mutable (pqs_user_store *store, const char *username)
	Find a mutable user record by name.
PQS_EXPORT_API bool	pqs_user_store_initialize (pqs_user_store *store, const char *path)
	Initialize and load the user database.
PQS_EXPORT_API bool	pqs_user_store_remove (pqs_user_store *store, const char *username)
	Remove a user from the user database.
PQS_EXPORT_API bool	pqs_user_store_save (const pqs_user_store *store)
	Save the user database to disk.
PQS_EXPORT_API bool	pqs_user_store_set_privilege (pqs_user_store *store, const char *username, pqs_user_privileges privilege)
	Set the user privilege level.
PQS_EXPORT_API bool	pqs_user_store_set_shell_profile (pqs_user_store *store, const char *username, const char *shellprofile)
	Set a user's assigned shell profile name.
PQS_EXPORT_API bool	pqs_user_store_set_passphrase (pqs_user_store *store, const char *username, const char *passphrase)
	Set a user's passphrase verifier.
PQS_EXPORT_API bool	pqs_user_name_is_valid (const char *username)
	Test whether a user name is valid for a PQS account and login request.
PQS_EXPORT_API bool	pqs_user_passphrase_is_valid (const char *passphrase)
	Test whether a passphrase length is valid for a PQS account and login request.
PQS_EXPORT_API const char *	pqs_user_privilege_to_string (pqs_user_privileges privilege)
	Convert a privilege level to its stable text name.
PQS_EXPORT_API pqs_user_privileges	pqs_user_privilege_from_string (const char *value)
	Convert a stable text name to a privilege level.
PQS_EXPORT_API bool	pqs_user_verify_passphrase (const pqs_user_record *record, const char *passphrase)
	Verify a plaintext passphrase against a user record.
PQS_EXPORT_API bool	pqs_user_verify_passphrase_timing_neutral (const pqs_user_record *record, const char *username, const char *passphrase)
	Verify a passphrase using a timing-neutral valid or dummy account path.

Detailed Description

PQS server-side user database and passphrase verifier functions.

Function Documentation

pqs_user_name_is_valid()

PQS_EXPORT_API bool pqs_user_name_is_valid

(

const char *

username

)

Test whether a user name is valid for a PQS account and login request.

Parameters

username

[const char*] The user name to validate.

Returns

[bool] Returns true if the user name is syntactically valid.

pqs_user_passphrase_is_valid()

PQS_EXPORT_API bool pqs_user_passphrase_is_valid

(

const char *

passphrase

)

Test whether a passphrase length is valid for a PQS account and login request.

Parameters

passphrase

[const char*] The passphrase to validate.

Returns

[bool] Returns true if the passphrase length is valid.

pqs_user_privilege_from_string()

PQS_EXPORT_API pqs_user_privileges pqs_user_privilege_from_string

(

const char *

value

)

Convert a stable text name to a privilege level.

Parameters

value

[const char*] The privilege name.

Returns

[enum] Returns the privilege level.

pqs_user_privilege_to_string()

PQS_EXPORT_API const char * pqs_user_privilege_to_string

(

pqs_user_privileges

privilege

)

Convert a privilege level to its stable text name.

Parameters

privilege

[enum] The privilege level.

Returns

[const char*] Returns the privilege name.

pqs_user_store_add()

PQS_EXPORT_API bool pqs_user_store_add	(	pqs_user_store *	store,
		const char *	username,
		const char *	passphrase,
		pqs_user_privileges	privilege )

Add a user to the user database.

Parameters

store	[struct] The user database.
username	[const char*] The user name.
passphrase	[const char*] The plaintext passphrase used to create the SCB verifier.
privilege	[enum] The assigned privilege level.

Returns

[bool] Returns true if the user was added.

pqs_user_store_enable()

PQS_EXPORT_API bool pqs_user_store_enable	(	pqs_user_store *	store,
		const char *	username,
		bool	enabled )

Disable or enable a user account.

Parameters

store	[struct] The user database.
username	[const char*] The user name.
enabled	[bool] The requested enabled state.

Returns

[bool] Returns true if the user was updated.

pqs_user_store_find()

PQS_EXPORT_API const pqs_user_record * pqs_user_store_find	(	const pqs_user_store *	store,
		const char *	username )

Find a user record by name.

Parameters

store	[const struct] The user database.
username	[const char*] The user name.

Returns

[struct] Returns a pointer to the record, or NULL if not found.

pqs_user_store_find_mutable()

PQS_EXPORT_API pqs_user_record * pqs_user_store_find_mutable	(	pqs_user_store *	store,
		const char *	username )

Find a mutable user record by name.

Parameters

store	[struct] The user database.
username	[const char*] The user name.

Returns

[struct] Returns a pointer to the record, or NULL if not found.

pqs_user_store_initialize()

PQS_EXPORT_API bool pqs_user_store_initialize	(	pqs_user_store *	store,
		const char *	path )

Initialize and load the user database.

Parameters

store	[struct] The user database.
path	[const char*] The database file path.

Returns

[bool] Returns true if the database was initialized.

pqs_user_store_remove()

PQS_EXPORT_API bool pqs_user_store_remove	(	pqs_user_store *	store,
		const char *	username )

Remove a user from the user database.

Parameters

store	[struct] The user database.
username	[const char*] The user name.

Returns

[bool] Returns true if the user was removed.

pqs_user_store_save()

PQS_EXPORT_API bool pqs_user_store_save

(

const pqs_user_store *

store

)

Save the user database to disk.

Parameters

store

[const struct] The user database.

Returns

[bool] Returns true if the database was saved.

pqs_user_store_set_passphrase()

PQS_EXPORT_API bool pqs_user_store_set_passphrase	(	pqs_user_store *	store,
		const char *	username,
		const char *	passphrase )

Set a user's passphrase verifier.

Parameters

store	[struct] The user database.
username	[const char*] The user name.
passphrase	[const char*] The new passphrase.

Returns

[bool] Returns true if the passphrase verifier was updated.

pqs_user_store_set_privilege()

PQS_EXPORT_API bool pqs_user_store_set_privilege	(	pqs_user_store *	store,
		const char *	username,
		pqs_user_privileges	privilege )

Set the user privilege level.

Parameters

store	[struct] The user database.
username	[const char*] The user name.
privilege	[enum] The requested privilege level.

Returns

[bool] Returns true if the user was updated.

pqs_user_store_set_shell_profile()

PQS_EXPORT_API bool pqs_user_store_set_shell_profile	(	pqs_user_store *	store,
		const char *	username,
		const char *	shellprofile )

Set a user's assigned shell profile name.

Parameters

store	[struct] The user database.
username	[const char*] The user name.
shellprofile	[const char*] The shell profile name.

Returns

[bool] Returns true if the user was updated.

pqs_user_verify_passphrase()

PQS_EXPORT_API bool pqs_user_verify_passphrase	(	const pqs_user_record *	record,
		const char *	passphrase )

Verify a plaintext passphrase against a user record.

Parameters

record	[const struct] The user record.
passphrase	[const char*] The plaintext passphrase.

Returns

[bool] Returns true if the passphrase matches the stored verifier.

pqs_user_verify_passphrase_timing_neutral()

PQS_EXPORT_API bool pqs_user_verify_passphrase_timing_neutral	(	const pqs_user_record *	record,
		const char *	username,
		const char *	passphrase )

Verify a passphrase using a timing-neutral valid or dummy account path.

Parameters

record	[const struct] The user record, or NULL for an unknown account.
username	[const char*] The requested user name used for the dummy verifier path.
passphrase	[const char*] The plaintext passphrase.

Returns

[bool] Returns true if the passphrase matches an enabled user record.