commit 5b0094b198b47ad7512fdb1013ac712edb3ecaea
parent a93646993a3daf74bbbaa3cafa587e58ccb895b7
Author: lash <dev@holbrook.no>
Date: Sun, 2 Mar 2025 16:16:13 +0000
Add documentation to header files
Diffstat:
7 files changed, 293 insertions(+), 16 deletions(-)
diff --git a/src/lq/cert.h b/src/lq/cert.h
@@ -11,6 +11,24 @@
#define LQ_CERT_DOMAIN_LEN 8
#endif
+/***
+ * @struct LQCert
+ * @brief A certificate is a counter-signed piece of arbitrary data within a designated domain. It may or may not be linked to a previous certificate.
+ * @var LQCert::parent
+ * Link to previous certificate. Optional. Set to NULL if no link exists.
+ * @var LQCert::domain
+ * Domain data is used by application data to evaluate whether a record is relevant for it or not.
+ * @var LQCert::request
+ * A request message encapsulates an arbitrary string of data that should be confirmed by a responder.
+ * @var LQCert::request_sig
+ * Signature over a request message and the linked certificate. If the linked certificate is NULL, the certificate data used in the signature with be a LQ_DIGEST_LEN string with all bytes set to 0.
+ * @var LQCert::response
+ * A response message encapsulates an arbitrary string of data that confirms a request. This field must be NULL unless a signed requests exists.
+ * @var LQCert::response_sig
+ * Signature over a response message. This field must be NULL unless a response message is set. The signature is calculated over both the response and the signed request.
+ * @var LQCert::ctx
+ * Context reflecting the behavior of state, validation and serialization of the certificate.
+ */
typedef struct lq_certificate_t LQCert;
struct lq_certificate_t {
LQCert *parent;
@@ -22,12 +40,77 @@ struct lq_certificate_t {
LQCtx *ctx;
};
+/***
+ * @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.
+ * @param[in] Request message.
+ * @param[in] Response message.
+ * @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, LQCtx *ctx, LQMsg *req, LQMsg *rsp);
+
+/***
+ * @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);
+
+/***
+ * @brief Sign the next pending message in the certificate. If the request message is set but not signed, the request message will be signed. If the response message is set but not signed, the response message will be signed. The limitations described in the struct declaration apply.
+ * @param[in] Instantiated certificate to perform signature on.
+ * @param[in] Private key to use for signature.
+ * @return ERR_OK on successful signature, or:
+ * * ERR_REQUEST if request has already been signed (and response is not set)
+ * * ERR_RESPONSE if response has already been signed.
+ * * ERR_ENCODING if calculateing the signature failed.
+ * * ERR_INIT if no message eligible for signature exists.
+ */
int lq_certificate_sign(LQCert *cert, LQPrivKey *pk);
+
+/***
+ * @brief Serialize certificate data payload for storage and transport.
+ * @param[in] Certificate to serialize
+ * @param[out] Buffer to write data to.
+ * @param[out] Value behind pointer must contain the capacity of the output buffer. Will be overwritten with the actual number of bytes written.
+ * @return ERR_OK if serialization is successful, or:
+ * * ERR_INIT if the serialization object couldn't be instantiated.
+ * * ERR_OVERFLOW if output exceeded the available space in output buffer.
+ * * ERR_WRITE if serialization of an element failed.
+ * * ERR_ENCODING if generating the final serialization string failed.
+ */
int lq_certificate_serialize(LQCert *cert, char *out, size_t *out_len);
+
+/***
+ * @brief Deserialize certificate data payload from storage or transport.
+ * @param[out] Pointer to instantiated certificate. It is the caller's responsibility to free the certificate object.
+ * @param[in] Serialized data.
+ * @param[in] Length of serialized data.
+ * @return ERR_OK if deserialization is successful, or:
+ * * ERR_INIT if the serialization object couldn't be instantiated.
+ * * ERR_READ if deserialization of an element failed.
+ * * ERR_ENCODING if interpretation of the serialized data failed.
+ * @see lq_certificate_free
+ */
int lq_certificate_deserialize(LQCert **cert, char *in, size_t in_len);
+
+
+/***
+ * @brief UNIMPLEMENTED verify the integrity of a certificate. Specifically that signatures in the certificate match given keys and data.
+ * @param[in] Certificate to verify
+ * @return ERR_OK if verified, or:
+ * ....
+ */
int lq_certificate_verify(LQCert *cert);
+
+
+/***
+ * @brief Free an instantiated certificate.
+ * @param[in] Certificate to free.
+ */
void lq_certificate_free(LQCert *cert);
#endif // LIBQAEDA_CERT_H_
diff --git a/src/lq/crypto.h b/src/lq/crypto.h
@@ -20,34 +20,130 @@
#endif
+/***
+ * @struct LQPrivKey
+ * @brief Represents an unencrypted private key for message signing.
+ * @var LQPrivKey::lokey
+ * Literal private key data.
+ * @var LQPrivKey::lolen
+ * Length of private key data.
+ * @var LQPrivKey::key_typ
+ * Key type identifier. Unused for now.
+ */
struct lq_privatekey_t {
- int key_typ;
void *lokey;
size_t lolen;
+ int key_typ;
};
typedef struct lq_privatekey_t LQPrivKey;
+/***
+ * @struct LQPubKey
+ * @brief Represents a public key embedded in private keys, certificates and signatures data.
+ * @var LQPubKey::lokey
+ * Literal uncompressed public key data.
+ * @var LQPubKey::lolen
+ * Length of public key data.
+ * @var LQPubKey::key_typ
+ * Key type identifier. Unused for now.
+ * @var LQPubKey::pk
+ * Corresponding private key. Optional, and set to NULL if not available.
+ */
struct lq_publickey_t {
- LQPrivKey *pk;
void *lokey;
size_t lolen;
+ int key_typ;
+ LQPrivKey *pk;
};
typedef struct lq_publickey_t LQPubKey;
+/***
+ * @struct LQSig
+ * @brief Represents a cryptographic signature over a message digest.
+ * @var LQSig::losig
+ * Literal signature data.
+ * @var LQSig::lolen
+ * Length of signature data.
+ * @var LQSig::pubkey
+ * Public key corresponding to the signature, used for verification. Optional (if public key can be recovered from signature)
+ */
struct lq_signature_t {
- LQPubKey *pubkey;
void *losig;
size_t lolen;
+ LQPubKey *pubkey;
};
typedef struct lq_signature_t LQSig;
+/***
+ * @brief Create a new private key
+ *
+ * @param[in] Key material. If NULL, a new random private key will be generated.
+ * @param[in] Length of key material. Ignored if seed parameter 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 *seed, size_t seed_len);
+
+/***
+ * @brief Create a new public key object.
+ *
+ * @param[in] Uncompressed public key data.
+ * @param[out] Pointer to new public key. Freeing the object is the caller's responsibility.
+ * @see lq_publickey_free
+ */
LQPubKey* lq_publickey_new(const char *full);
+
+/***
+ * @brief Create a new public key object from a private key.
+ *
+ * @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);
+
+
+/***
+ * @brief Sign digest data using a private key.
+ *
+ * @param[in] Unencrypted private key to use for the signature.
+ * @param[in] Message digest to sign.
+ * @param[in] Length of message to sign.
+ * @param[in] Salt data to use for the signature.
+ * @param[in] Length of salt data.
+ * @return Signature object if signing was successful. Returns NULL if signature failed.
+ * @see lq_signature_free
+ */
LQSig* lq_privatekey_sign(LQPrivKey *pk, const char *msg, size_t msg_len, const char *salt, size_t salt_len);
+
+
+/***
+ * @brief Free an allocated public key.
+ * @param[in] Public key to free.
+ */
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);
+
+
+/***
+ * @brief Calculate digest over arbitrary data.
+ * @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
+ * @return ERR_OK on success.
+ */
int lq_digest(const char *in, size_t in_len, char *out);
#endif // LIBQAEDA_CRYPTO_H_
diff --git a/src/lq/err.h b/src/lq/err.h
@@ -1,16 +1,17 @@
#ifndef LIBQAEDA_ERR_H_
#define LIBQAEDA_ERR_H_
+/// Error values used across all error contexts.
enum err_e {
- ERR_OK,
- ERR_BYTEORDER,
- ERR_OVERFLOW,
- ERR_INIT,
- ERR_READ,
- ERR_WRITE,
- ERR_ENCODING,
- ERR_REQUEST,
- ERR_RESPONSE,
+ ERR_OK, ///< No error
+ ERR_BYTEORDER, ///< Errors related to endianness
+ ERR_OVERFLOW, ///< Not enough space to write
+ ERR_INIT, ///< Failure instantiating object or data
+ ERR_READ, ///< General data read failure
+ ERR_WRITE, ///< General data write failure
+ ERR_ENCODING, ///< Failure in serialization and data transformation
+ ERR_REQUEST, ///< Error related to certificate request messages
+ ERR_RESPONSE, ///< Error related to certificate response messages
};
typedef enum err_e LQErr;
diff --git a/src/lq/mem.h b/src/lq/mem.h
@@ -3,9 +3,40 @@
#include <stddef.h>
+/***
+ * @brief Allocate heap memory.
+ *
+ * @param[in] Number of memory bytes to allocate.
+ * @return Pointer to allocated memory. Returns NULL if allocation has failed.
+ */
void* lq_alloc(size_t bytes);
+
+/***
+ * @brief Free a memory pointer.
+ *
+ * @param[in] Pointer to free.
+ */
void lq_free(void *o);
+
+/***
+ * @brief Copy memory region.
+ *
+ * @param[out] Destination memory.
+ * @param[in] Source memory.
+ * @param[in] Number of bytes to copy.
+ * @return Pointer to written memory.
+ */
void* lq_cpy(void *dst, const void *src, size_t len);
+
+/***
+ *
+ * @brief Fill memory region with value.
+ *
+ * @param[out] Destination memory.
+ * @param[in] Value to write.
+ * @param[in] Number of bytes to write.
+ * @return Pointer to written memory.
+ */
void* lq_set(void *dst, const char b, size_t len);
#endif // LIBQAEDA_MEM_H_
diff --git a/src/lq/msg.c b/src/lq/msg.c
@@ -32,10 +32,10 @@ LQMsg* lq_msg_new(const char *msg_data, size_t msg_len) {
}
LQSig* lq_msg_sign(LQMsg *msg, LQPrivKey *pk) {
- return lq_msg_sign_salted(msg, pk, nosalt, LQ_SALT_LEN);
+ return lq_msg_sign_salted(msg, pk, nosalt);
}
-LQSig* lq_msg_sign_salted(LQMsg *msg, LQPrivKey *pk, const char *salt, size_t salt_len) {
+LQSig* lq_msg_sign_salted(LQMsg *msg, LQPrivKey *pk, const char *salt) {
int r;
char *data;
char digest[LQ_DIGEST_LEN];
@@ -49,7 +49,7 @@ LQSig* lq_msg_sign_salted(LQMsg *msg, LQPrivKey *pk, const char *salt, size_t sa
if (r != ERR_OK) {
return NULL;
}
- sig = lq_privatekey_sign(pk, digest, LQ_DIGEST_LEN, salt, salt_len);
+ sig = lq_privatekey_sign(pk, digest, LQ_DIGEST_LEN, salt, LQ_SALT_LEN);
return sig;
}
diff --git a/src/lq/msg.h b/src/lq/msg.h
@@ -6,6 +6,18 @@
#include "lq/crypto.h"
+/***
+ * @struct LQMsg
+ * @brief Represents a message that is used as part of certificate as request or response.
+ * @var LQMsg::data
+ * Arbitrary data constituting the message.
+ * @var LQMsg::len
+ * Length of arbitrary data.
+ * @var LQMsg::time
+ * Nanosecond timestamp of when the message was created.
+ * @var LQMsg::pubkey
+ * Public key authoring the message. Must be checked against any private key calculating a signature over it.
+ */
struct lq_msg_t {
char *data;
size_t len;
@@ -14,10 +26,63 @@ struct lq_msg_t {
};
typedef struct lq_msg_t LQMsg;
+/***
+ * @brief Instantiate a new message object.
+ * @param[in] Message data. Data will be copied.
+ * @param[in] Length of message data.
+ * @return Instantiated message object. It is the caller's responsibility to free to object.
+ * @see lq_msg_free
+ */
LQMsg* lq_msg_new(const char *msg_data, size_t msg_len);
+
+/***
+ * @brief Calculate a signature over the message. Uses default salt value.
+ * @param[in] Message to sign.
+ * @param[in] Private key to sign with.
+ * @return Signature object. Object will be NULL if signature calculation failed. It is the caller's responsibility to free the signature object.
+ * @see lq_signature_free
+ */
LQSig* lq_msg_sign(LQMsg *msg, LQPrivKey *pk);
-LQSig* lq_msg_sign_salted(LQMsg *msg, LQPrivKey *pk, const char *salt, size_t salt_len);
+
+/***
+ * @brief Calculate a signature over the message with a specified salt value. The salt value length must be LQ_SALT_LEN.
+ * @param[in] Message to sign.
+ * @param[in] Private key to sign with.
+ * @return Signature object. Object will be NULL if signature calculation failed. It is the caller's responsibility to free the signature object.
+ * @see lq_signature_free
+ */
+LQSig* lq_msg_sign_salted(LQMsg *msg, LQPrivKey *pk, const char *salt);
+
+/***
+ * @brief Serialize message data payload for inclusion in certificate.
+ * @param[in] Message to serialize.
+ * @param[out] Output buffer.
+ * @param[out] Value behind pointer must contain the capacity of output buffer. Will be overwritten with the actual number of bytes written.
+ * @return ERR_OK if serialization is successful, or:
+ * * ERR_INIT if the serialization object couldn't be instantiated.
+ * * ERR_OVERFLOW if output exceeded the available space in output buffer.
+ * * ERR_WRITE if serialization of an element failed.
+ * * ERR_ENCODING if generating the final serialization string failed.
+ */
int lq_msg_serialize(LQMsg *msg, char *out, size_t *out_len);
+
+/***
+ * @brief Deserialize message data payload from certificate.
+ * @param[out] Pointer to instantiated message. It is the caller's responsibility to free the message object.
+ * @param[in] Serialized data.
+ * @param[in] Length of serialized data.
+ * @return ERR_OK if deserialization is successful, or:
+ * * ERR_INIT if the serialization object couldn't be instantiated.
+ * * ERR_READ if deserialization of an element failed.
+ * * ERR_ENCODING if interpretation of the serialized data failed.
+ * @see lq_msg_free
+ */
int lq_msg_deserialize(LQMsg **msg, const char *in, size_t in_len);
+
+/***
+ * @brief Free an instantiated message.
+ * @param[in] Message to free.
+ */
void lq_msg_free(LQMsg *msg);
+
#endif // LIBQAEDA_MSG_H_
diff --git a/src/lq/wire.h b/src/lq/wire.h
@@ -1,6 +1,7 @@
#ifndef LIBQAEDA_WIRE_H_
#define LIBQAEDA_WIRE_H_
+/// Serialization structures
extern const asn1_static_node defs_asn1_tab[];
#endif // LIBQAEDA_WIRE_H_
