PQS native file-transfer helpers. More...

#include "pqscommon.h"
#include <stdio.h>

Typedefs
typedef enum pqs_xfer_walk_events	pqs_xfer_walk_events
typedef bool(*	pqs_xfer_walk_callback) (pqs_xfer_walk_events event, const char localpath, const char relative, void *context)
	File-transfer directory walk callback.

Enumerations
enum	pqs_xfer_walk_events { pqs_xfer_walk_event_directory_begin = 0x01U , pqs_xfer_walk_event_file = 0x02U , pqs_xfer_walk_event_directory_end = 0x03U }
	File-transfer directory walk event types. More...

Functions
PQS_EXPORT_API size_t	pqs_xfer_payload_size (const uint8_t *message, size_t msglen)
	Return the plaintext payload length carried after the PQS application message header.
PQS_EXPORT_API void	pqs_xfer_join_path (char output, size_t outlen, const char first, const char *second)
	Join two local file-system path components.
PQS_EXPORT_API void	pqs_xfer_join_remote (char output, size_t outlen, const char first, const char *second)
	Join two remote transfer path components using the PQS remote delimiter.
PQS_EXPORT_API bool	pqs_xfer_local_path_is_directory (const char *path)
	Test whether a local path is a directory.
PQS_EXPORT_API bool	pqs_xfer_create_parent_directories (const char *fpath)
	Create all parent directories for a local output path.
PQS_EXPORT_API bool	pqs_xfer_make_local_recursive_path (char output, size_t outlen, const char root, const char *relative)
	Build a local path for a recursive transfer member.
PQS_EXPORT_API bool	pqs_xfer_walk_directory (const char localroot, const char remoteroot, size_t maxdepth, pqs_xfer_walk_callback callback, void *context)
	Walk a local directory tree and report PQS transfer paths through a callback.
PQS_EXPORT_API bool	pqs_xfer_make_path (char output, size_t outlen, const char root, const char *relative)
	Build a confined absolute path from a transfer root and a relative remote path.
PQS_EXPORT_API bool	pqs_xfer_extract_relative (char output, size_t outlen, const uint8_t message, size_t msglen)
	Extract a bounded relative path from a file-transfer application message.
PQS_EXPORT_API bool	pqs_xfer_path_is_confined (const char root, const char path, bool existing)
	Test whether a local path resolves inside the configured root.
PQS_EXPORT_API bool	pqs_xfer_path_is_safe (const char *relative)
	Test whether a remote file-transfer path is safe.
PQS_EXPORT_API bool	pqs_xfer_make_user_root (char output, size_t outlen, const char root, const char *username)
	Build a per-user transfer root path.
PQS_EXPORT_API FILE *	pqs_xfer_open_read_confined (const char root, const char relative)
	Open a confined transfer file for binary reading.
PQS_EXPORT_API FILE *	pqs_xfer_open_write_confined (const char root, const char relative)
	Open a confined transfer file for binary writing.
PQS_EXPORT_API bool	pqs_xfer_make_temporary_path (char output, size_t outlen, const char relative)
	Build a confined temporary upload path from a relative target path.
PQS_EXPORT_API bool	pqs_xfer_remove_confined (const char root, const char relative)
	Remove a confined file inside the configured transfer root.
PQS_EXPORT_API bool	pqs_xfer_make_directory_confined (const char root, const char relative)
	Create a confined directory inside the configured transfer root.
PQS_EXPORT_API bool	pqs_xfer_publish_temporary_file (const char root, const char temporary, const char *relative)
	Publish a staged temporary upload as its final confined file.
PQS_EXPORT_API bool	pqs_xfer_hash_file (const char fpath, char hexhash, size_t hexlen, size_t *filesize)
	Compute the SHA3-256 hash of a local file.
PQS_EXPORT_API bool	pqs_xfer_format_metadata (char output, size_t outlen, size_t filesize, const char hexhash)
	Format file-transfer metadata text.
PQS_EXPORT_API bool	pqs_xfer_parse_metadata (const char metadata, size_t filesize, char *hexhash, size_t hexlen)
	Parse file-transfer metadata text.
PQS_EXPORT_API bool	pqs_xfer_format_file_metadata (char output, size_t outlen, const char relative, size_t filesize, const char *hexhash)
	Format recursive file-transfer metadata text.
PQS_EXPORT_API bool	pqs_xfer_parse_file_metadata (const char metadata, char relative, size_t relen, size_t filesize, char hexhash, size_t hexlen)
	Parse recursive file-transfer metadata text.
PQS_EXPORT_API bool	pqs_xfer_path_is_symlink (const char *path)
	Test whether a file-system path is a symbolic link or reparse point.

Detailed Description

PQS native file-transfer helpers.

Typedef Documentation

◆ pqs_xfer_walk_callback

typedef bool(* pqs_xfer_walk_callback) (pqs_xfer_walk_events event, const char *localpath, const char *relative, void *context)

File-transfer directory walk callback.

Parameters

event	The directory-walk event type.
localpath	[const] The local file-system path for the event.
relative	[const] The relative PQS transfer path for the event.
context	[void] An application-defined callback context.

Returns: Returns true to continue traversal; otherwise, false.

Enumeration Type Documentation

◆ pqs_xfer_walk_events

enum pqs_xfer_walk_events

File-transfer directory walk event types.

Enumerator
pqs_xfer_walk_event_directory_begin	A directory has been entered and its relative transfer path is available to the callback.
pqs_xfer_walk_event_file	A regular file has been discovered and its local and relative transfer paths are available to the callback.
pqs_xfer_walk_event_directory_end	A directory has been fully processed and its relative transfer path is available to the callback.

Function Documentation

◆ pqs_xfer_extract_relative()

PQS_EXPORT_API bool pqs_xfer_extract_relative	(	char *	output,
		size_t	outlen,
		const uint8_t *	message,
		size_t	msglen )

Extract a bounded relative path from a file-transfer application message.

Parameters

output	[char] The output path buffer.
outlen	The length of the output path buffer.
message	[const] The application message buffer.
msglen	The application message length.

Returns: Returns true if a NUL-terminated relative path was extracted safely; otherwise, false.

◆ pqs_xfer_format_file_metadata()

PQS_EXPORT_API bool pqs_xfer_format_file_metadata	(	char *	output,
		size_t	outlen,
		const char *	relative,
		size_t	filesize,
		const char *	hexhash )

Format recursive file-transfer metadata text.

Parameters

output	[char] The output metadata buffer.
outlen	The length of the output metadata buffer.
relative	[const] The relative file path inside the recursive transfer root.
filesize	The file size associated with the transfer.
hexhash	[const] The NUL-terminated SHA3-256 hexadecimal hash.

Returns: Returns true if metadata text was written successfully; otherwise, returns false.

◆ pqs_xfer_format_metadata()

PQS_EXPORT_API bool pqs_xfer_format_metadata	(	char *	output,
		size_t	outlen,
		size_t	filesize,
		const char *	hexhash )

Format file-transfer metadata text.

Parameters

output	[char] The output metadata buffer.
outlen	The length of the output metadata buffer.
filesize	The file size associated with the transfer.
hexhash	[const] The NUL-terminated SHA3-256 hexadecimal hash.

Returns: Returns true if metadata text was written successfully; otherwise, returns false.

◆ pqs_xfer_hash_file()

PQS_EXPORT_API bool pqs_xfer_hash_file	(	const char *	fpath,
		char *	hexhash,
		size_t	hexlen,
		size_t *	filesize )

Compute the SHA3-256 hash of a local file.

Parameters

fpath	[const] The local file path.
hexhash	[char] The output hexadecimal hash buffer.
hexlen	The length of the output hexadecimal hash buffer.
filesize	[size_t] An optional output parameter receiving the file size.

Returns: Returns true if the hash was computed successfully; otherwise, returns false.

◆ pqs_xfer_make_directory_confined()

PQS_EXPORT_API bool pqs_xfer_make_directory_confined	(	const char *	root,
		const char *	relative )

Create a confined directory inside the configured transfer root.

Parameters

root	[const] The configured transfer root directory.
relative	[const] The relative directory path to create.

Returns: Returns true if the confined directory was created or already exists; otherwise, false.

◆ pqs_xfer_make_path()

PQS_EXPORT_API bool pqs_xfer_make_path	(	char *	output,
		size_t	outlen,
		const char *	root,
		const char *	relative )

Build a confined absolute path from a transfer root and a relative remote path.

Parameters

output	[char] The output path buffer.
outlen	The length of the output path buffer.
root	[const] The configured transfer root directory.
relative	[const] The remote path supplied by the peer.

Returns: Returns true if the resulting path is confined to the root; otherwise, returns false.

◆ pqs_xfer_make_temporary_path()

PQS_EXPORT_API bool pqs_xfer_make_temporary_path	(	char *	output,
		size_t	outlen,
		const char *	relative )

Build a confined temporary upload path from a relative target path.

The temporary path remains relative to the same transfer root and is suitable for writing a staged upload before final hash verification.

Parameters

output	[char] The output relative temporary path.
outlen	The length of the output path buffer.
relative	[const] The final relative target path.

Returns: Returns true if the temporary relative path was created safely.

◆ pqs_xfer_make_user_root()

PQS_EXPORT_API bool pqs_xfer_make_user_root	(	char *	output,
		size_t	outlen,
		const char *	root,
		const char *	username )

Build a per-user transfer root path.

Parameters

output	[char] The output path buffer.
outlen	The length of the output path buffer.
root	[const] The configured global transfer root directory.
username	[const] The authenticated PQS user name.

Returns: Returns true if the per-user root path was created or already existed; otherwise, returns false.

◆ pqs_xfer_open_read_confined()

PQS_EXPORT_API FILE * pqs_xfer_open_read_confined	(	const char *	root,
		const char *	relative )

Open a confined transfer file for binary reading.

Parameters

root	[const] The configured transfer root directory.
relative	[const] The relative transfer path.

Returns: [FILE*] Returns an open file pointer, or NULL on failure.

◆ pqs_xfer_open_write_confined()

PQS_EXPORT_API FILE * pqs_xfer_open_write_confined	(	const char *	root,
		const char *	relative )

Open a confined transfer file for binary writing.

Parameters

root	[const] The configured transfer root directory.
relative	[const] The relative transfer path.

Returns: [FILE*] Returns an open file pointer, or NULL on failure.

◆ pqs_xfer_parse_file_metadata()

PQS_EXPORT_API bool pqs_xfer_parse_file_metadata	(	const char *	metadata,
		char *	relative,
		size_t	relen,
		size_t *	filesize,
		char *	hexhash,
		size_t	hexlen )

Parse recursive file-transfer metadata text.

Parameters

metadata	[const] The NUL-terminated metadata string.
relative	[char] The output relative path buffer.
relen	The length of the relative path output buffer.
filesize	[size_t] The parsed file size output parameter.
hexhash	[char] The output hash text buffer.
hexlen	The length of the output hash text buffer.

Returns: Returns true if the metadata was parsed successfully; otherwise, returns false.

◆ pqs_xfer_parse_metadata()

PQS_EXPORT_API bool pqs_xfer_parse_metadata	(	const char *	metadata,
		size_t *	filesize,
		char *	hexhash,
		size_t	hexlen )

Parse file-transfer metadata text.

Parameters

metadata	[const] The NUL-terminated metadata string.
filesize	[size_t] The parsed file size output parameter.
hexhash	[char] The output hash text buffer.
hexlen	The length of the output hash text buffer.

Returns: Returns true if the metadata was parsed successfully; otherwise, returns false.

◆ pqs_xfer_path_is_confined()

PQS_EXPORT_API bool pqs_xfer_path_is_confined	(	const char *	root,
		const char *	path,
		bool	existing )

Test whether a local path resolves inside the configured root.

Parameters

root	[const] The configured root path.
path	[const] The path to test.
existing	Set to true when the target path must already exist.

Returns: Returns true if the resolved path remains inside the root; otherwise, false.

◆ pqs_xfer_path_is_safe()

PQS_EXPORT_API bool pqs_xfer_path_is_safe ( const char * relative )

Test whether a remote file-transfer path is safe.

Parameters

relative [const] The NUL-terminated remote path to test.

Returns: Returns true if the path is a relative, non-traversing PQS transfer path; otherwise, returns false.

◆ pqs_xfer_path_is_symlink()

PQS_EXPORT_API bool pqs_xfer_path_is_symlink ( const char * path )

Test whether a file-system path is a symbolic link or reparse point.

Parameters

path	[const] The local file-system path to test.

Returns: Returns true if the path is a symbolic link or reparse point; otherwise, returns false.

◆ pqs_xfer_payload_size()

PQS_EXPORT_API size_t pqs_xfer_payload_size	(	const uint8_t *	message,
		size_t	msglen )

Return the plaintext payload length carried after the PQS application message header.

Parameters

message	[const] The application message buffer.
msglen	The application message length.

Returns: Returns the payload length, or zero if the message is not valid.

◆ pqs_xfer_publish_temporary_file()

PQS_EXPORT_API bool pqs_xfer_publish_temporary_file	(	const char *	root,
		const char *	temporary,
		const char *	relative )

Publish a staged temporary upload as its final confined file.

Parameters

root	[const] The configured transfer root directory.
temporary	[const] The relative temporary upload path.
relative	[const] The final relative target path.

Returns: Returns true if the temporary file was renamed into its final path; otherwise, false.

◆ pqs_xfer_remove_confined()

PQS_EXPORT_API bool pqs_xfer_remove_confined	(	const char *	root,
		const char *	relative )

Remove a confined file inside the configured transfer root.

Parameters

root	[const] The configured transfer root directory.
relative	[const] The relative transfer path to remove.

Returns: Returns true if the confined file was removed; otherwise, false.

◆ pqs_xfer_walk_directory()

PQS_EXPORT_API bool pqs_xfer_walk_directory	(	const char *	localroot,
		const char *	remoteroot,
		size_t	maxdepth,
		pqs_xfer_walk_callback	callback,
		void *	context )

Walk a local directory tree and report PQS transfer paths through a callback.

Parameters

localroot	[const] The local root directory to traverse.
remoteroot	[const] The relative PQS transfer root associated with localroot.
maxdepth	The maximum recursion depth accepted by the traversal.
callback	[pqs_xfer_walk_callback] The traversal callback.
context	[void] The caller-defined callback context.

Returns: Returns true if the traversal completed successfully; otherwise, false.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ pqs_xfer_walk_callback

Enumeration Type Documentation

◆ pqs_xfer_walk_events

Function Documentation

◆ pqs_xfer_extract_relative()

◆ pqs_xfer_format_file_metadata()

◆ pqs_xfer_format_metadata()

◆ pqs_xfer_hash_file()

◆ pqs_xfer_make_directory_confined()

◆ pqs_xfer_make_path()

◆ pqs_xfer_make_temporary_path()

◆ pqs_xfer_make_user_root()

◆ pqs_xfer_open_read_confined()

◆ pqs_xfer_open_write_confined()

◆ pqs_xfer_parse_file_metadata()

◆ pqs_xfer_parse_metadata()

◆ pqs_xfer_path_is_confined()

◆ pqs_xfer_path_is_safe()

◆ pqs_xfer_path_is_symlink()

◆ pqs_xfer_payload_size()

◆ pqs_xfer_publish_temporary_file()

◆ pqs_xfer_remove_confined()

◆ pqs_xfer_walk_directory()