root.h File Reference

The QSTP Root Security server. More...

#include "common.h"
#include "qstp.h"

Go to the source code of this file.

Functions
QSTP_EXPORT_API bool	qstp_root_certificate_export (const qstp_root_certificate *root, const char *fpath)
	Export the root certificate to a file.
QSTP_EXPORT_API void	qstp_root_key_generate (qstp_root_signature_key *kset, const char issuer[QSTP_CERTIFICATE_ISSUER_SIZE], uint32_t exp)
	Generate a new root key.
QSTP_EXPORT_API void	qstp_root_certificate_print (const qstp_root_certificate *root)
	Print the root certificate.
QSTP_EXPORT_API void	qstp_root_server_certificate_print (const qstp_server_certificate *cert)
	Print a server certificate.
QSTP_EXPORT_API qstp_errors	qstp_root_certificate_revoke (const uint8_t *rootkey, const uint8_t *serial, const qsc_ipinfo_ipv4_address *address)
	Send a certificate revocation request to a client.
QSTP_EXPORT_API bool	qstp_root_sign_certificate (const char *fpath, const qstp_root_certificate *root, const uint8_t *rootkey)
	Sign a child certificate.

Detailed Description

The QSTP Root Security server.

This header defines functions used by the QSTP Root Security server, which serves as the trust anchor within the Quantum Secure Tunneling Protocol (QSTP). The root server is responsible for managing root certificates and keys, including exporting certificates to persistent storage, generating new root signing keys, printing certificate details, revoking certificates, and signing child certificates. These operations are fundamental for establishing trust between the QSTP root, servers, and clients.

Note

These functions are internal and non-exportable.

Function Documentation

qstp_root_certificate_export()

QSTP_EXPORT_API bool qstp_root_certificate_export	(	const qstp_root_certificate *	root,
		const char *	fpath )

Export the root certificate to a file.

This function writes the given QSTP root certificate to a file at the specified file path. The exported certificate is used for distribution and for verifying the signatures of child certificates in the QSTP system.

Parameters

root	[const] A pointer to the QSTP root certificate to be exported.
fpath	The output file path where the root certificate will be saved.

Returns

Returns true if the export operation succeeds; otherwise, returns false.

qstp_root_certificate_print()

QSTP_EXPORT_API void qstp_root_certificate_print

(

const qstp_root_certificate *

root

)

Print the root certificate.

This function prints the details of the QSTP root certificate to the standard output or to a designated logging stream. It is typically used for debugging or verification of the root certificate information.

Parameters

root	[const] A pointer to the QSTP root certificate.

qstp_root_certificate_revoke()

QSTP_EXPORT_API qstp_errors qstp_root_certificate_revoke	(	const uint8_t *	rootkey,
		const uint8_t *	serial,
		const qsc_ipinfo_ipv4_address *	address )

Send a certificate revocation request to a client.

This function sends a certificate revocation request to a client, using the provided root signing key and the certificate serial number that identifies the certificate to be revoked. The request is sent to the specified server IPv4 network address.

Parameters

rootkey	A pointer to the root signing key.
serial	A pointer to the certificate serial number that should be revoked.
address	A pointer to the IPv4 network address of the target server.

Returns

Returns a value of type qstp_errors indicating the result of the revocation request.

qstp_root_key_generate()

QSTP_EXPORT_API void qstp_root_key_generate	(	qstp_root_signature_key *	kset,
		const char	issuer[QSTP_CERTIFICATE_ISSUER_SIZE],
		uint32_t	exp )

Generate a new root key.

This function generates a new QSTP root signing key. It populates the provided root signature key structure with a new key, using the specified issuer name and a validity period (in days). The newly generated root key is used to sign certificates for QSTP servers and clients, thus establishing a chain of trust.

Parameters

kset	A pointer to the QSTP root signature key structure that will receive the new key.
issuer	The issuer name to be associated with the new root key. The string length must be equal to QSTP_CERTIFICATE_ISSUER_SIZE.
exp	The number of valid days for the new root key.

qstp_root_server_certificate_print()

QSTP_EXPORT_API void qstp_root_server_certificate_print

(

const qstp_server_certificate *

cert

)

Print a server certificate.

This function prints the details of a QSTP server certificate, including issuer, serial number, validity period, and cryptographic parameters. It is used for debugging and verifying the server certificate.

Parameters

cert	[const] A pointer to the QSTP server certificate.

qstp_root_sign_certificate()

QSTP_EXPORT_API bool qstp_root_sign_certificate	(	const char *	fpath,
		const qstp_root_certificate *	root,
		const uint8_t *	rootkey )

Sign a child certificate.

This function signs a child certificate using the provided root certificate and root signing key. The signed certificate is then exported to the file specified by the file path. Signing a child certificate attests to its authenticity and establishes its chain of trust from the root.

Parameters

fpath	The file path where the signed child certificate will be saved.
root	A pointer to the QSTP root certificate.
rootkey	A pointer to the root signing key.

Returns

Returns true if the certificate signing is successful; otherwise, returns false.