envelope.h (3572B)
1 #ifndef LIBQAEDA_ENVELOPE_H_ 2 #define LIBQAEDA_ENVELOPE_H_ 3 4 #include <stddef.h> 5 #include <lq/cert.h> 6 7 /*** 8 * \brief Encapsulates a single data blob, referenced by message digest, to be bundled with the envelope. 9 */ 10 struct lq_attach { 11 char *data; ///< Data to bundle. 12 size_t len; ///< Length of data to bundle. 13 struct lq_attach *next; ///< Next attachment to bundle, linked-list. 14 }; 15 16 /** 17 * \brief Structure used for end-user transport of certificate. 18 * 19 * 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. 20 */ 21 struct lq_envelope { 22 int hint; ///< Application level hint to assist in interpreting contents of envelope. 23 LQCert *cert; ///< Certificate to bundle. 24 struct lq_attach *attach_start; ///< Pointer to first attachment to include. 25 struct lq_attach *attach_cur; ///< Pointer to next position to add a new attachment. 26 }; 27 typedef struct lq_envelope LQEnvelope; 28 29 30 /** 31 * \brief Allocate a new attachment object 32 * 33 * 34 * \param[in] Certificate to bundle. 35 * \param[in] Application level interpretation hint. 36 * \return Newly allocated LQEnvelope object, NULL if failed. 37 * 38 * \see lq_envelope_free 39 */ 40 LQEnvelope *lq_envelope_new(LQCert *cert, int hint); 41 42 /** 43 * \brief Add a single data blob to the bundle. 44 * 45 * \param[in] Envelope to add data to. 46 * \param[in] Buffer containing the data to add. 47 * \param[in] Length of data to add. 48 * \return ERR_OK on success. 49 */ 50 int lq_envelope_attach(LQEnvelope *env, const char *data, size_t data_len); 51 52 53 /** 54 * \brief Serialize envelope data for transport. 55 * 56 * \param[in] Envelope to serialize. 57 * \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved. 58 * \param[out] Data buffer where serialized data will be written. 59 * \param[in/out] Length of data buffer. Will be overwritten with the length of the written data. 60 * \return ERR_OK if serialization is successful, or: 61 * * ERR_INIT if the serialization object couldn't be instantiated. 62 * * ERR_OVERFLOW if output exceeded the available space in output buffer. 63 * * ERR_WRITE if serialization of an element failed. 64 * * ERR_ENCODING if generating the final serialization string failed. 65 * 66 * \see lq_certificate_serialize 67 */ 68 int lq_envelope_serialize(LQEnvelope *env, LQResolve *resolve, char *data, size_t *data_len); 69 70 /** 71 * \brief Deserialize certificate data payload from storage or transport. 72 * 73 * \param[out] Pointer where envelope will be instantiated. It is the caller's responsibility to free the envelope object. 74 * \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved. 75 * \param[in] Serialized data. 76 * \param[in] Length of serialized data. 77 * \return ERR_OK if deserialization is successful, or: 78 * * ERR_INIT if the serialization object couldn't be instantiated. 79 * * ERR_READ if deserialization of an element failed. 80 * * ERR_ENCODING if interpretation of the serialized data failed. 81 * 82 * \see lq_certificate_deserialize 83 * \see lq_envelope_free 84 */ 85 86 int lq_envelope_deserialize(LQEnvelope **env, LQResolve *resolve, const char *data, size_t data_len); 87 88 /** 89 * \brief Free an instantiated envelope. 90 * 91 * For convenience, this will also free the associated certificate. 92 * 93 * \param[in] Envelope to free. 94 */ 95 void lq_envelope_free(LQEnvelope *env); 96 97 #endif // LIBQAEDA_ENVELOPE_H_