pqskey.h File Reference

PQS host-key fingerprint and known-hosts helper functions. More...

#include "pqscommon.h"
#include "qsms.h"

Go to the source code of this file.

Macros
#define	PQS_KEY_FINGERPRINT_SIZE   32U
	The binary SHA3-256 host-key fingerprint size.
#define	PQS_KEY_FINGERPRINT_STRING_SIZE   ((PQS_KEY_FINGERPRINT_SIZE * 2U) + PQS_STRING_TERMINATOR_SIZE)
	The NUL-terminated hexadecimal host-key fingerprint string size.
#define	PQS_KEY_KNOWN_HOST_LINE_MAX   384U
	The maximum known-hosts line length.
#define	PQS_KEY_HOST_NAME_MAX   256U
	The maximum host identifier length in a known-hosts record.
#define	PQS_KEY_KNOWN_HOST_MAGIC   "# PQSKNOWNHOSTS1"
	The known-hosts database header string.

Functions
PQS_EXPORT_API bool	pqs_key_host_is_valid (const char *host)
	Test whether a host token is valid for known-host storage.
PQS_EXPORT_API bool	pqs_key_private_file_permissions_are_strict (const char *fpath)
	Test whether a private key file has strict local permissions where supported.
PQS_EXPORT_API void	pqs_key_fingerprint (uint8_t output[PQS_KEY_FINGERPRINT_SIZE], const qsms_client_verification_key *pubkey)
	Compute the PQS host-key fingerprint.
PQS_EXPORT_API bool	pqs_key_fingerprint_string (char *output, size_t outlen, const qsms_client_verification_key *pubkey)
	Compute the PQS host-key fingerprint as hexadecimal text.
PQS_EXPORT_API bool	pqs_key_fingerprint_file (char *output, size_t outlen, const char *fpath)
	Compute the PQS host-key fingerprint from an encoded public-key file.
PQS_EXPORT_API bool	pqs_key_known_host_find (const char *fpath, const char *host, char *fingerprint, size_t fplen)
	Read the expected fingerprint for a host from a known-hosts file.
PQS_EXPORT_API bool	pqs_key_known_host_set (const char *fpath, const char *host, const char *fingerprint)
	Add or replace a host fingerprint in a known-hosts file.
PQS_EXPORT_API bool	pqs_key_known_host_remove (const char *fpath, const char *host)
	Remove a host fingerprint from a known-hosts file.
PQS_EXPORT_API bool	pqs_key_fingerprint_is_valid (const char *fingerprint)
	Test whether a string is a valid PQS host-key fingerprint.
PQS_EXPORT_API bool	pqs_key_known_host_verify (const char *fpath, const char *host, const char *fingerprint)
	Verify a host fingerprint against the known-hosts file.

Detailed Description

PQS host-key fingerprint and known-hosts helper functions.

Function Documentation

pqs_key_fingerprint()

PQS_EXPORT_API void pqs_key_fingerprint	(	uint8_t	output[PQS_KEY_FINGERPRINT_SIZE],
		const qsms_client_verification_key *	pubkey )

Compute the PQS host-key fingerprint.

The fingerprint is SHA3-256 over the QSMS public-key identity fields used by PQS.

Parameters

output	[uint8_t*] The fingerprint output buffer.
pubkey	[const struct] The QSMS public verification key.

pqs_key_fingerprint_file()

PQS_EXPORT_API bool pqs_key_fingerprint_file	(	char *	output,
		size_t	outlen,
		const char *	fpath )

Compute the PQS host-key fingerprint from an encoded public-key file.

Parameters

output	[char*] The output buffer receiving a NUL-terminated hexadecimal fingerprint.
outlen	[size_t] The output buffer length.
fpath	[const char*] The encoded server public-key path.

Returns

[bool] Returns true if the public key was loaded and fingerprinted.

pqs_key_fingerprint_is_valid()

PQS_EXPORT_API bool pqs_key_fingerprint_is_valid

(

const char *

fingerprint

)

Test whether a string is a valid PQS host-key fingerprint.

Parameters

fingerprint

[const char*] The NUL-terminated hexadecimal fingerprint string.

Returns

[bool] Returns true if the fingerprint has the expected length and hex format.

pqs_key_fingerprint_string()

PQS_EXPORT_API bool pqs_key_fingerprint_string	(	char *	output,
		size_t	outlen,
		const qsms_client_verification_key *	pubkey )

Compute the PQS host-key fingerprint as hexadecimal text.

Parameters

output	[char*] The output buffer receiving a NUL-terminated hexadecimal fingerprint.
outlen	[size_t] The output buffer length.
pubkey	[const struct] The QSMS public verification key.

Returns

[bool] Returns true if the fingerprint was written.

pqs_key_host_is_valid()

PQS_EXPORT_API bool pqs_key_host_is_valid

(

const char *

host

)

Test whether a host token is valid for known-host storage.

Parameters

host	[const char*] The host identifier.

Returns

[bool] Returns true if the host token is bounded and contains no control characters or record separators.

pqs_key_known_host_find()

PQS_EXPORT_API bool pqs_key_known_host_find	(	const char *	fpath,
		const char *	host,
		char *	fingerprint,
		size_t	fplen )

Read the expected fingerprint for a host from a known-hosts file.

Parameters

fpath	[const char*] The known-hosts database path.
host	[const char*] The host identifier.
fingerprint	[char*] The output buffer receiving the fingerprint.
fplen	[size_t] The fingerprint output buffer length.

Returns

[bool] Returns true if a matching host entry was found.

pqs_key_known_host_remove()

PQS_EXPORT_API bool pqs_key_known_host_remove	(	const char *	fpath,
		const char *	host )

Remove a host fingerprint from a known-hosts file.

Parameters

fpath	[const char*] The known-hosts database path.
host	[const char*] The host identifier.

Returns

[bool] Returns true if the known-hosts file was updated.

pqs_key_known_host_set()

PQS_EXPORT_API bool pqs_key_known_host_set	(	const char *	fpath,
		const char *	host,
		const char *	fingerprint )

Add or replace a host fingerprint in a known-hosts file.

Parameters

fpath	[const char*] The known-hosts database path.
host	[const char*] The host identifier.
fingerprint	[const char*] The NUL-terminated hexadecimal fingerprint.

Returns

[bool] Returns true if the known-hosts file was updated.

pqs_key_known_host_verify()

PQS_EXPORT_API bool pqs_key_known_host_verify	(	const char *	fpath,
		const char *	host,
		const char *	fingerprint )

Verify a host fingerprint against the known-hosts file.

Parameters

fpath	[const char*] The known-hosts database path.
host	[const char*] The host identifier.
fingerprint	[const char*] The NUL-terminated hexadecimal fingerprint.

Returns

[bool] Returns true only if a matching host entry exists and matches the fingerprint.

pqs_key_private_file_permissions_are_strict()

PQS_EXPORT_API bool pqs_key_private_file_permissions_are_strict

(

const char *

fpath

)

Test whether a private key file has strict local permissions where supported.

On POSIX systems this requires a regular file with no group or world permissions. On Windows this verifies that the path exists and is not a directory; detailed DACL validation is deployment-specific and should be handled by installer policy.

Parameters

fpath

[const char*] The private key path.

Returns

[bool] Returns true if the file permission posture is acceptable for the platform check.