commit 891ef4e804916d29fbf8550d73ffe34cf5a45414
parent e8b0df236debe5f9500acba4eec72c230edfa6ac
Author: lash <dev@holbrook.no>
Date: Tue, 8 Apr 2025 05:26:20 +0100
Improve docs
Diffstat:
7 files changed, 122 insertions(+), 35 deletions(-)
diff --git a/src/lq/base.h b/src/lq/base.h
@@ -2,11 +2,22 @@
#define LQ_BASE_H_
#ifndef LQ_BLOCKSIZE
+/***
+ * \brief The buffer unit size used by libqaeda.
+ */
#define LQ_BLOCKSIZE 4096
#endif
+/***
+ * \brief Initialize libqaeda internals.
+ *
+ * \returns ERR_OK on successful initialization. On any other return value, library cannot be used.
+ */
int lq_init();
+
+/***
+ * \brief Release resources used by libqaeda internals.
+ */
void lq_finish();
#endif // LQ_BASE_H_
-
diff --git a/src/lq/cert.c b/src/lq/cert.c
@@ -165,7 +165,7 @@ int lq_certificate_verify(LQCert *cert) {
LQCert cert_valid;
if (cert->request_sig == NULL) {
- return debug_logerr(LLOG_DEBUG, ERR_NONSENSE, "no signatures");
+ return debug_logerr(LLOG_DEBUG, ERR_NOOP, "no signatures");
}
lq_cpy(&cert_valid, cert, sizeof(LQCert));
diff --git a/src/lq/cert.h b/src/lq/cert.h
@@ -34,17 +34,19 @@ struct lq_certificate_t {
* \brief Create a new certificate.
*
* \param[in] Previous certificate to link to.
- * \param[in] Context to control behavior of certificate processing. If NULL, default behavior will be used.
* \return The allocated certificate object. It is the caller's responsibility to free the object.
- * \todo request and response message does not make sense to set without option to set signature, factor out to separate functions.
+ *
* \see lq_certificate_free
*/
LQCert* lq_certificate_new(LQCert *parent);
/**
- * @brief Set the domain of the certificate. If not set, the default domain value will be used, which is LQ_DOMAIN_LEN bytes set to 0.
- * @param[in] Instantiated certificate to set domain on.
- * @param[in] Domain data. Must be LQ_DOMAIN_LEN bytes long.
+ * \brief Set the domain of the certificate.
+ *
+ * If not set, the default domain value will be used, which is LQ_DOMAIN_LEN bytes set to 0.
+ *
+ * \param[in] Instantiated certificate to set domain on.
+ * \param[in] Domain data. Must be LQ_DOMAIN_LEN bytes long.
*/
void lq_certificate_set_domain(LQCert *cert, const char *domain);
@@ -118,7 +120,7 @@ int lq_certificate_deserialize(LQCert **cert, LQResolve *resolve, char *in, size
* Messages must have public key set.
*
* \param[in] Certificate to verify
- * \return ERR_OK if verified.
+ * \return ERR_OK if verified, ERR_NOOP if no message.
*/
int lq_certificate_verify(LQCert *cert);
@@ -159,8 +161,9 @@ int lq_certificate_respond(LQCert *cert, LQMsg *rsp, LQPrivKey *pk);
/**
- * @brief Free an instantiated certificate.
- * @param[in] Certificate to free.
+ * \brief Free an instantiated certificate.
+ *
+ * \param[in] Certificate to free.
*/
void lq_certificate_free(LQCert *cert);
diff --git a/src/lq/config.h b/src/lq/config.h
@@ -12,7 +12,16 @@
#include "lq/mem.h"
/**
- * Core configuration keys.
+ * \brief Configuration data types
+ */
+enum lq_typ_e {
+ LQ_TYP_VOID,
+ LQ_TYP_NUM,
+ LQ_TYP_STR,
+};
+
+/**
+ * \brief Core configuration keys.
*/
enum lq_config_core_e {
LQ_CFG_DIR_BASE, ///< Base working directory.
@@ -26,7 +35,11 @@ enum lq_config_core_e {
/**
* \brief Initialize the instance-wide config singleton.
*
- * @return ERR_OK on success.
+ * \warning This method is called by lq_init, and should most likely not be called directly.
+ *
+ * \return ERR_OK on success.
+ *
+ * \see lq_init
*/
int lq_config_init();
@@ -54,7 +67,7 @@ int lq_config_set(int k, void *v);
* \brief Retrieve a value stored under a configuration key.
*
* \param[in] Configuration key.
- * \param[out] Pointer to value write location. Must be sufficient to hold the registered value type.
+ * \param[out] Pointer to value write location. Must have sufficient to hold the registered value type.
* \return ERR_OK on success.
*
* \see lq_config_register
diff --git a/src/lq/crypto.h b/src/lq/crypto.h
@@ -6,55 +6,88 @@
#include "base.h"
#ifndef LQ_DIGEST_LEN
+/**
+ * \brief Length of result produced by digest algorithm.
+ */
#define LQ_DIGEST_LEN 64
#endif
#ifndef LQ_DIGEST_SIG_LEN
-#define LQ_DIGEST_SIG_LEN 64
+/**
+ * \brief Length of digest expected by signature.
+ */
+#define LQ_DIGEST_SIG_LEN LQ_DIGEST_LEN
#endif
#ifndef LQ_PUBKEY_LEN
+/**
+ * \brief Length in bytes of the full publickey representation.
+ */
#define LQ_PUBKEY_LEN 32
#endif
#ifndef LQ_PRIVKEY_LEN
+/**
+ * \brief Length of the literal private key bytes.
+ */
#define LQ_PRIVKEY_LEN 32
#endif
#ifndef LQ_SIGN_LEN
+/**
+ * \brief Length of the full signature output.
+ */
#define LQ_SIGN_LEN 64
#endif
#ifndef LQ_FP_LEN
+/**
+ * \brief Length of the public key fingerprint data.
+ */
#define LQ_FP_LEN 20
#endif
#ifndef LQ_SALT_LEN
+/**
+ * \brief Length of salt used in signatures.
+ */
#define LQ_SALT_LEN 32
#endif
#ifndef LQ_CRYPTO_BUFLEN
+/**
+ * \brief Length of internal work buffer for crypto and signature operations.
+ */
#define LQ_CRYPTO_BUFLEN 65536
#endif
#ifndef LQ_CRYPTO_BLOCKSIZE
+/**
+ * \brief Storage size unit for encrypted data. Encrypted, padded data will be stored in a multiplier of this size.
+ */
#define LQ_CRYPTO_BLOCKSIZE LQ_BLOCKSIZE
#endif
#ifndef LQ_POINT_LEN
+/**
+ * \brief Size of coordinate point on cryptographic curve.
+ */
#define LQ_POINT_LEN 32
#endif
+/**
+ * \brief State of private key.
+ */
enum lq_keystate_e {
- LQ_KEY_INIT = 1,
- LQ_KEY_LOCK = 2,
+ LQ_KEY_INIT = 1, ///< Key contains valid data.
+ LQ_KEY_LOCK = 2, ///< Key is locked with passphrase.
};
/**
* \struct LQPrivKey
*
- * \brief Represents an unencrypted private key for message signing.
+ * \brief Represents a private key used for message signing.
*
* \see lq_privatekey_t
*/
@@ -68,9 +101,10 @@ typedef struct lq_privatekey_t LQPrivKey;
/**
* \struct LQPubKey
*
- * \brief Represents a public key embedded in private keys, certificates and signatures data.
+ * \brief Represents a public key, to include with certificates and signatures.
*
* \see lq_publickey_t
+ *
* \todo add serialization
*/
struct lq_publickey_t {
@@ -85,8 +119,13 @@ typedef struct lq_publickey_t LQPubKey;
*
* \brief Represents a cryptographic signature over a message digest.
*
+ * The public key must be set in order to use this signature in verification.
+ *
* \see lq_signature_t
+ * \see lq_signature_verify
+ *
* \todo add serialization
+ *
*/
struct lq_signature_t {
LQPubKey *pubkey; ///< Public key corresponding to the signature, used for verification. Optional (if public key can be recovered from signature)
@@ -95,15 +134,15 @@ struct lq_signature_t {
typedef struct lq_signature_t LQSig;
/**
- * \brief Perform necessary initializations of crypto component.
+ * \brief Initialize crypto component internals.
*
* \return ERR_OK on success.
*/
int lq_crypto_init(const char *base);
/**
- * \brief Perform necessary resource release of crypto component.
- */
+ * \brief Free resources used by crypto component internals.
+ **/
void lq_crypto_free();
/**
@@ -114,6 +153,7 @@ void lq_crypto_free();
* \param[in] Passphrase to encrypt key with. If NULL, key will be encrypted with a single 0-byte as passphrase.
* \param[in] Passphrase length. Ignored if passphrase is NULL.
* \return Pointer to new private key. Freeing the object is the caller's responsibility.
+ *
* \see lq_privatekey_free
*/
LQPrivKey* lq_privatekey_new(const char *passphrase, size_t passphrase_len);
@@ -125,17 +165,18 @@ LQPrivKey* lq_privatekey_new(const char *passphrase, size_t passphrase_len);
*
* \param[in] Passphrase to encrypt key with. If NULL, key will be encrypted with a single 0-byte as passphrase.
* \param[in] Passphrase length. Ignored if passphrase is NULL.
- * \return Pointer to new private key. Freeing the object is the caller's responsibility.
+ * \param[in] If not NULL, the private key matching the fingerprint will be loaded. If not, a "default" key will be loaded.
+ * \return Pointer to new private key, if found, or NULL if not. Freeing the object is the caller's responsibility.
*
* \see lq_privatekey_free
*/
LQPrivKey* lq_privatekey_load(const char *passphrase, size_t passphrase_len, const char *fingerprint);
/**
- * \brief Get raw private key bytes
+ * \brief Get the raw private key bytes.
*
* \param[in] Private key object.
- * \param[out] Pointer to start of data.
+ * \param[out] Pointer to start of data to write to. The buffer must be at least LQ_PRIVKEY_LEN long.
* \return Length of key. If 0, no key could be found.
*/
size_t lq_privatekey_bytes(LQPrivKey *pk, char **out);
@@ -145,6 +186,7 @@ size_t lq_privatekey_bytes(LQPrivKey *pk, char **out);
*
* \param[in] Uncompressed public key data.
* \return Pointer to new public key. Freeing the object is the caller's responsibility.
+ *
* \see lq_publickey_free
*/
LQPubKey* lq_publickey_new(const char *full);
@@ -156,6 +198,7 @@ LQPubKey* lq_publickey_new(const char *full);
*
* \param[in] Private key to generate public key from.
* \return Pointer to new public key. Freeing the object is the caller's responsibility.
+ *
* \see lq_publickey_free
*/
LQPubKey* lq_publickey_from_privatekey(LQPrivKey *pk);
@@ -173,7 +216,7 @@ size_t lq_publickey_bytes(LQPubKey *pubk, char **out);
* \brief Get the public key fingerprint bytes.
*
* \param[in] Public key object
- * \param[out] Pointer to start of data.
+ * \param[out] Pointer to start of data to write to. Buffer must have a capacity of at least LQ_PUBKEY_LEN bytes.
* \return Length of fingerprint data. If 0, no fingerprint could be found.
*/
size_t lq_publickey_fingerprint(LQPubKey *pubk, char **out);
@@ -183,7 +226,9 @@ size_t lq_publickey_fingerprint(LQPubKey *pubk, char **out);
*
* Must clear sensistive memory.
*
- * \param[in] Private Key object
+ * \param[in] Private Key object.
+ * \param[in] Passphrase to encrypt private key with.
+ * \param[in] Length of passphrase.
* \return ERR_OK if encrypted, ERR_NOOP if already encrypted, or ERR_INIT if encryption fails.
*/
int lq_privatekey_lock(LQPrivKey *pk, const char *passphrase, size_t passphrase_len);
@@ -191,7 +236,9 @@ int lq_privatekey_lock(LQPrivKey *pk, const char *passphrase, size_t passphrase_
/**
* \brief Decrypt private key in place.
*
- * \param[in] Private Key object
+ * \param[in] Private Key object.
+ * \param[in] Passphrase to decrypt private key with.
+ * \param[in] Length of passphrase.
* \return ERR_OK if decrypted, ERR_NOOP if not encrypted, or ERR_INIT if decryption fails.
*/
int lq_privatekey_unlock(LQPrivKey *pk, const char *passphrase, size_t passphrase_len);
@@ -201,9 +248,12 @@ int lq_privatekey_unlock(LQPrivKey *pk, const char *passphrase, size_t passphras
*
* \param[in] Decrypted private key to use for the signature.
* \param[in] Message digest to sign.
- * \param[in] Length of message to sign.
+ * \param[in] Length of message to sign. Must be
* \param[in] Salt data to use for the signature. Set to NULL if salt is not to be used. If not null, must be LQ_SALT_LEN long.
* \return Signature object if signing was successful. Returns NULL if signature failed. It is the caller's responsiblity to free the signature.
+ *
+ * \todo Remove msg_len, as it is inferred by LQ_DIGEST_SIG_LEN
+ *
* \see lq_signature_free
*/
LQSig* lq_privatekey_sign(LQPrivKey *pk, const char *msg, size_t msg_len, const char *salt);
@@ -215,6 +265,8 @@ LQSig* lq_privatekey_sign(LQPrivKey *pk, const char *msg, size_t msg_len, const
* \param[in] Length of data.
* \param[in] Public key used in signature. Can be NULL for recoverable signatures.
* \return Signature object if parse was successful. Returns NULL if parsing failed. It is the caller's responsiblity to free the signature.
+ *
+ * \todo Remove sig_len, as it is inferred by LQ_SIG_LEN
*/
LQSig* lq_signature_from_bytes(const char *sig_data, size_t sig_len, LQPubKey *pubkey);
@@ -222,7 +274,7 @@ LQSig* lq_signature_from_bytes(const char *sig_data, size_t sig_len, LQPubKey *p
* \brief Get raw signature bytes
*
* \param[in] Signature object.
- * \param[out] Pointer to start of data.
+ * \param[out] Pointer to start of data to write to. Buffer must have a capacity of at least LQ_SIG_LEN bytes.
* \return Length of signature. If 0, no signature data could be found.
*/
size_t lq_signature_bytes(LQSig *sig, char **out);
@@ -233,6 +285,8 @@ size_t lq_signature_bytes(LQSig *sig, char **out);
* \param[in] Message digest to sign.
* \param[in] Length of message to sign.
* \return ERR_OK if signature is verified.
+ *
+ * \todo remove msg_len, as it is inferred by LQ_DIGEST_SIG_LEN
*/
int lq_signature_verify(LQSig *sig, const char *msg, size_t msg_len);
@@ -247,12 +301,14 @@ void lq_publickey_free(LQPubKey *pubk);
/**
* \brief Free an allocated private key.
+ *
* \param[in] Private key to free.
*/
void lq_privatekey_free(LQPrivKey *pk);
/**
* \brief Free an allocated signature object.
+ *
* \param[in] Private key to free.
*/
void lq_signature_free(LQSig *sig);
@@ -262,7 +318,7 @@ void lq_signature_free(LQSig *sig);
*
* \param[in] Data to calculate digest over.
* \param[in] Length of data.
- * \param[out] Output buffer. Must be allocated to at least LQ_DIGEST_LENGTH
+ * \param[out] Output buffer. Buffer must have a capacity of at least LQ_DIGEST_LENGTH bytes.
* \return ERR_OK on success.
*/
int lq_digest(const char *in, size_t in_len, char *out);
diff --git a/src/lq/err.h b/src/lq/err.h
@@ -36,6 +36,15 @@ enum err_e {
ERR_SEQ = 0x402,
};
+/**
+ * \brief Initialize the error code and decriptions setup.
+ *
+ * \warning This method is called by lq_init, and should most likely not be called directly.
+ *
+ * \return ERR_OK on success.
+ *
+ * \see lq_init
+ */
void lq_err_init();
#endif // LIBQAEDA_ERR_H_
diff --git a/src/lq/mem.h b/src/lq/mem.h
@@ -1,11 +1,6 @@
#ifndef LIBQAEDA_MEM_H_
#define LIBQAEDA_MEM_H_
-enum lq_typ_e {
- LQ_TYP_VOID,
- LQ_TYP_NUM,
- LQ_TYP_STR,
-};
#include <stddef.h>
