pqslogger.h File Reference

The PQS structured logging functions. More...

#include "pqscommon.h"

Go to the source code of this file.

Macros
#define	PQS_LOGGER_LINE_MAX   1536U
	The maximum formatted log line length.
#define	PQS_LOGGER_USER_MAX   64U
	The maximum user identifier length stored in a log event.
#define	PQS_LOGGER_DETAIL_MAX   384U
	The maximum detail field length stored in a log event.

Typedefs
typedef PQS_EXPORT_API enum pqs_log_level	pqs_log_level
typedef PQS_EXPORT_API enum pqs_log_event	pqs_log_event

Enumerations
enum	pqs_log_level {   pqs_log_level_none = 0x00U , pqs_log_level_error = 0x01U , pqs_log_level_warning = 0x02U , pqs_log_level_info = 0x03U ,   pqs_log_level_audit = 0x04U , pqs_log_level_debug = 0x05U }
	The PQS log severity levels. More...
enum	pqs_log_event {   pqs_log_event_none = 0x0000U , pqs_log_event_application_start = 0x1000U , pqs_log_event_application_stop = 0x1001U , pqs_log_event_key_loaded = 0x1100U ,   pqs_log_event_key_generated = 0x1101U , pqs_log_event_connection_open = 0x1200U , pqs_log_event_connection_close = 0x1201U , pqs_log_event_connection_refused = 0x1202U ,   pqs_log_event_command_received = 0x1300U , pqs_log_event_command_complete = 0x1301U , pqs_log_event_command_failed = 0x1302U , pqs_log_event_auth_success = 0x1400U ,   pqs_log_event_auth_failure = 0x1401U , pqs_log_event_auth_lockout = 0x1402U , pqs_log_event_user_database_loaded = 0x1410U , pqs_log_event_user_database_created = 0x1411U ,   pqs_log_event_user_added = 0x1412U , pqs_log_event_user_removed = 0x1413U , pqs_log_event_user_updated = 0x1414U , pqs_log_event_shell_database_loaded = 0x1420U ,   pqs_log_event_shell_database_created = 0x1421U , pqs_log_event_shell_added = 0x1422U , pqs_log_event_shell_removed = 0x1423U , pqs_log_event_shell_updated = 0x1424U ,   pqs_log_event_policy_database_loaded = 0x1430U , pqs_log_event_policy_database_created = 0x1431U , pqs_log_event_policy_added = 0x1432U , pqs_log_event_policy_removed = 0x1433U ,   pqs_log_event_policy_updated = 0x1434U , pqs_log_event_policy_allowed = 0x1435U , pqs_log_event_policy_denied = 0x1436U , pqs_log_event_hostkey_loaded = 0x1440U ,   pqs_log_event_hostkey_pinned = 0x1441U , pqs_log_event_hostkey_verified = 0x1442U , pqs_log_event_hostkey_changed = 0x1443U , pqs_log_event_sandbox_enabled = 0x1450U ,   pqs_log_event_sandbox_violation = 0x1451U , pqs_log_event_command_timeout = 0x1452U , pqs_log_event_command_output_limit = 0x1453U , pqs_log_event_file_transfer_start = 0x1460U ,   pqs_log_event_file_transfer_complete = 0x1461U , pqs_log_event_file_transfer_failed = 0x1462U , pqs_log_event_protocol_error = 0x1500U , pqs_log_event_admin_request = 0x1550U ,   pqs_log_event_admin_allowed = 0x1551U , pqs_log_event_admin_denied = 0x1552U , pqs_log_event_admin_complete = 0x1553U , pqs_log_event_admin_failed = 0x1554U ,   pqs_log_event_audit_chain_start = 0x1600U }
	The PQS structured log event identifiers. More...

Functions
PQS_EXPORT_API void	pqs_logger_dispose (void)
	Dispose of the PQS logger state.
PQS_EXPORT_API bool	pqs_logger_initialize (const char *path, pqs_log_level level)
	Initialize the PQS file logger.
PQS_EXPORT_API bool	pqs_logger_is_initialized (void)
	Test if the logger has been initialized.
PQS_EXPORT_API bool	pqs_logger_failure_occurred (void)
	Test whether a logger write failure has occurred since initialization.
PQS_EXPORT_API bool	pqs_logger_verify_chain (const char *path, uint64_t *records)
	Verify the tamper-evident PQS audit-log chain.
PQS_EXPORT_API bool	pqs_logger_write (pqs_log_level level, pqs_log_event event, const char *user, const char *peer, const char *detail)
	Write a structured PQS log event.

Detailed Description

The PQS structured logging functions.

Enumeration Type Documentation

pqs_log_event

enum pqs_log_event

The PQS structured log event identifiers.

Enumerator
pqs_log_event_none	No event.
pqs_log_event_application_start	The application started.
pqs_log_event_application_stop	The application stopped.
pqs_log_event_key_loaded	The PQS key was loaded.
pqs_log_event_key_generated	A new PQS key was generated.
pqs_log_event_connection_open	A connection opened.
pqs_log_event_connection_close	A connection closed.
pqs_log_event_connection_refused	A connection was refused.
pqs_log_event_command_received	A command request was received.
pqs_log_event_command_complete	Command output completed.
pqs_log_event_command_failed	Command execution failed.
pqs_log_event_auth_success	Authentication succeeded.
pqs_log_event_auth_failure	Authentication failed.
pqs_log_event_auth_lockout	Authentication failed and the account was locked.
pqs_log_event_user_database_loaded	The server user database was loaded.
pqs_log_event_user_database_created	The server user database was created.
pqs_log_event_user_added	A server user record was added.
pqs_log_event_user_removed	A server user record was removed.
pqs_log_event_user_updated	A server user record was updated.
pqs_log_event_shell_database_loaded	The server shell profile database was loaded.
pqs_log_event_shell_database_created	The server shell profile database was created.
pqs_log_event_shell_added	A server shell profile was added.
pqs_log_event_shell_removed	A server shell profile was removed.
pqs_log_event_shell_updated	A server shell profile was updated.
pqs_log_event_policy_database_loaded	The server command policy database was loaded.
pqs_log_event_policy_database_created	The server command policy database was created.
pqs_log_event_policy_added	A server command policy was added.
pqs_log_event_policy_removed	A server command policy was removed.
pqs_log_event_policy_updated	A server command policy was updated.
pqs_log_event_policy_allowed	A command was permitted by policy.
pqs_log_event_policy_denied	A command was denied by policy.
pqs_log_event_hostkey_loaded	A host key was loaded.
pqs_log_event_hostkey_pinned	A host key fingerprint was pinned.
pqs_log_event_hostkey_verified	A host key fingerprint was verified.
pqs_log_event_hostkey_changed	A host key fingerprint differed from a known-hosts entry.
pqs_log_event_sandbox_enabled	The command sandbox was initialized.
pqs_log_event_sandbox_violation	The command sandbox rejected an execution condition.
pqs_log_event_command_timeout	A command was terminated by the sandbox timeout.
pqs_log_event_command_output_limit	A command was terminated by the sandbox output limit.
pqs_log_event_file_transfer_start	A file-transfer operation started.
pqs_log_event_file_transfer_complete	A file-transfer operation completed.
pqs_log_event_file_transfer_failed	A file-transfer operation failed.
pqs_log_event_protocol_error	A protocol error was detected.
pqs_log_event_admin_request	A typed administrative command was requested.
pqs_log_event_admin_allowed	A typed administrative command was authorized.
pqs_log_event_admin_denied	A typed administrative command was denied.
pqs_log_event_admin_complete	A typed administrative command completed.
pqs_log_event_admin_failed	A typed administrative command failed.
pqs_log_event_audit_chain_start	The audit-log hash chain was initialized.

pqs_log_level

enum pqs_log_level

The PQS log severity levels.

Enumerator
pqs_log_level_none	Logging is disabled.
pqs_log_level_error	Error-level events.
pqs_log_level_warning	Warning-level events.
pqs_log_level_info	Informational events.
pqs_log_level_audit	Security audit events.
pqs_log_level_debug	Debug events.

Function Documentation

pqs_logger_failure_occurred()

PQS_EXPORT_API bool pqs_logger_failure_occurred

(

void

)

Test whether a logger write failure has occurred since initialization.

Returns

[bool] Returns true if a logger write or initialization append failed.

pqs_logger_initialize()

PQS_EXPORT_API bool pqs_logger_initialize	(	const char *	path,
		pqs_log_level	level )

Initialize the PQS file logger.

Parameters

path	[const char*] The log file path.
level	[enum] The minimum enabled log level.

Returns

[bool] Returns true if the logger was initialized.

pqs_logger_is_initialized()

PQS_EXPORT_API bool pqs_logger_is_initialized

(

void

)

Test if the logger has been initialized.

Returns

[bool] Returns true if initialized.

pqs_logger_verify_chain()

PQS_EXPORT_API bool pqs_logger_verify_chain	(	const char *	path,
		uint64_t *	records )

Verify the tamper-evident PQS audit-log chain.

Parameters

path	[const char*] The log file path.
records	[uint64_t*] The number of verified records, or NULL.

Returns

[bool] Returns true if every chained record verifies.

pqs_logger_write()

PQS_EXPORT_API bool pqs_logger_write	(	pqs_log_level	level,
		pqs_log_event	event,
		const char *	user,
		const char *	peer,
		const char *	detail )

Write a structured PQS log event.

Parameters

level	[enum] The event log level.
event	[enum] The event identifier.
user	[const char*] The authenticated PQS user, or NULL.
peer	[const char*] The peer address, or NULL.
detail	[const char*] A non-secret event detail string, or NULL.

Returns

[bool] Returns true if the event was written.