commit 9fc72ce1b493e6b60067f7054ef4f17fe45f677a
parent 1ee10d6c9a296ad04180519874704bcb15e942ec
Author: lash <dev@holbrook.no>
Date: Sat, 19 Apr 2025 16:27:15 +0100
Add docs, minor cleanup
Diffstat:
5 files changed, 75 insertions(+), 16 deletions(-)
diff --git a/src/lq/cert.h b/src/lq/cert.h
@@ -96,7 +96,7 @@ int lq_certificate_serialize(LQCert *cert, LQResolve *resolve, char *out, size_t
/**
* \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[out] Pointer to where certificate will be instantiated. It is the caller's responsibility to free the certificate object.
* \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved.
* \param[in] Serialized data.
* \param[in] Length of serialized data.
diff --git a/src/lq/envelope.c b/src/lq/envelope.c
@@ -65,6 +65,8 @@ LQEnvelope *lq_envelope_new(LQCert *cert, int hint) {
env->cert = cert;
env->attach_start = lq_attach_new();
env->attach_cur = env->attach_start;
+
+ return env;
}
int lq_envelope_attach(LQEnvelope *env, const char *data, size_t data_len) {
@@ -97,7 +99,6 @@ int lq_envelope_serialize(LQEnvelope *env, LQResolve *resolve, char *out, size_t
int r;
char err[LQ_ERRSIZE];
char buf[LQ_BLOCKSIZE];
- char node_seq_name[64];
asn1_node item;
mx = *out_len;
@@ -155,6 +156,8 @@ int lq_envelope_serialize(LQEnvelope *env, LQResolve *resolve, char *out, size_t
if (r != ASN1_SUCCESS) {
return ERR_FAIL;
}
+
+ return ERR_OK;
}
int lq_envelope_deserialize(LQEnvelope **env, LQResolve *resolve, const char *in, size_t in_len) {
@@ -163,7 +166,7 @@ int lq_envelope_deserialize(LQEnvelope **env, LQResolve *resolve, const char *in
int i;
char err[LQ_ERRSIZE];
char tmp[LQ_BLOCKSIZE];
- char node_seq_name[16];
+ char node_seq_name[32];
int hint;
LQCert *cert;
asn1_node item;
@@ -199,7 +202,7 @@ int lq_envelope_deserialize(LQEnvelope **env, LQResolve *resolve, const char *in
i = 0;
while(++i) {
c = LQ_BLOCKSIZE;
- sprintf(node_seq_name, "attach.?%d", i);
+ sprintf(node_seq_name, "attach.?%i", i);
r = asn1_read_value(item, node_seq_name, tmp, &c);
if (r != ASN1_SUCCESS) {
break;
diff --git a/src/lq/envelope.h b/src/lq/envelope.h
@@ -4,36 +4,94 @@
#include <stddef.h>
#include <lq/cert.h>
+/***
+ * \brief Encapsulates a single data blob, referenced by message digest, to be bundled with the envelope.
+ */
struct lq_attach {
- char *data;
- size_t len;
- struct lq_attach *next;
+ char *data; ///< Data to bundle.
+ size_t len; ///< Length of data to bundle.
+ struct lq_attach *next; ///< Next attachment to bundle, linked-list.
};
+/**
+ * \brief Structure used for end-user transport of certificate.
+ *
+ * The envelope enables bundling of the message data referenced by the message hashes. If the message is not literal, then the interpreter of the certificate will have to resolve the contents through other means.
+ */
struct lq_envelope {
- int hint;
- LQCert *cert;
- struct lq_attach *attach_start;
- struct lq_attach *attach_cur;
- struct lq_attach *attach;
+ int hint; ///< Application level hint to assist in interpreting contents of envelope.
+ LQCert *cert; ///< Certificate to bundle.
+ struct lq_attach *attach_start; ///< Pointer to first attachment to include.
+ struct lq_attach *attach_cur; ///< Pointer to next position to add a new attachment.
};
typedef struct lq_envelope LQEnvelope;
/**
- * \brief Set up a new attachment object
+ * \brief Allocate a new attachment object
+ *
*
+ * \param[in] Certificate to bundle.
+ * \param[in] Application level interpretation hint.
+ * \return Newly allocated LQEnvelope object, NULL if failed.
*
+ * \see lq_envelope_free
*/
LQEnvelope *lq_envelope_new(LQCert *cert, int hint);
/**
+ * \brief Add a single data blob to the bundle.
*
+ * \param[in] Envelope to add data to.
+ * \param[in] Buffer containing the data to add.
+ * \param[in] Length of data to add.
* \return ERR_OK on success.
*/
int lq_envelope_attach(LQEnvelope *env, const char *data, size_t data_len);
+
+
+/**
+ * \brief Serialize envelope data for transport.
+ *
+ * \param[in] Envelope to serialize.
+ * \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved.
+ * \param[out] Data buffer where serialized data will be written.
+ * \param[in/out] Length of data buffer. Will be overwritten with the length of the written data.
+ * \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.
+ *
+ * \see lq_certificate_serialize
+ */
int lq_envelope_serialize(LQEnvelope *env, LQResolve *resolve, char *data, size_t *data_len);
+
+/**
+ * \brief Deserialize certificate data payload from storage or transport.
+ *
+ * \param[out] Pointer where envelope will be instantiated. It is the caller's responsibility to free the envelope object.
+ * \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved.
+ * \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_deserialize
+ * \see lq_envelope_free
+ */
+
int lq_envelope_deserialize(LQEnvelope **env, LQResolve *resolve, const char *data, size_t data_len);
+
+/**
+ * \brief Free an instantiated envelope.
+ *
+ * For convenience, this will also free the associated certificate.
+ *
+ * \param[in] Envelope to free.
+ */
void lq_envelope_free(LQEnvelope *env);
#endif // LIBQAEDA_ENVELOPE_H_
diff --git a/src/lq/msg.c b/src/lq/msg.c
@@ -272,7 +272,6 @@ int lq_msg_deserialize(LQMsg **msg, LQResolve *resolve, const char *in, size_t i
char err[LQ_ERRSIZE];
char tmp[LQ_BLOCKSIZE];
char z[LQ_DIGEST_LEN];
- char *p;
char msg_state;
asn1_node item;
LQResolve *resolve_active;
diff --git a/src/test/test_msg.c b/src/test/test_msg.c
@@ -61,7 +61,6 @@ START_TEST(check_msg_symmetric_literal) {
char *p;
LQMsg *msg;
LQResolve resolve;
- LQResolve resolve_dummy;
LQStore *store;
lq_cpy(path, "/tmp/lqstore_file_XXXXXX", 25);
@@ -96,7 +95,7 @@ Suite * common_suite(void) {
s = suite_create("msg");
tc = tcase_create("serialize");
-// tcase_add_test(tc, check_msg_symmetric);
+ tcase_add_test(tc, check_msg_symmetric);
tcase_add_test(tc, check_msg_symmetric_literal);
suite_add_tcase(s, tc);
