msg.h (5611B)
1 #ifndef LIBQAEDA_MSG_H_ 2 #define LIBQAEDA_MSG_H_ 3 4 #include <stddef.h> 5 #include <time.h> 6 7 #include "lq/crypto.h" 8 #include "lq/store.h" 9 10 enum lq_msgstate_e { 11 LQ_MSG_INIT = 1, 12 LQ_MSG_RESOLVED = 2, 13 LQ_MSG_LITERAL = 4, 14 }; 15 16 /** 17 * \struct LQMsg 18 * 19 * \brief Represents a message that is used as part of certificate as request or response. 20 * 21 * \see lq_msg_t 22 */ 23 struct lq_msg_t { 24 char state; ///< Message resolution state 25 char *data; ///< Arbitrary data constituting the message. 26 size_t len; ///< Length of arbitrary data. 27 struct timespec time; ///< Nanosecond timestamp of when the message was created. 28 LQPubKey *pubkey; ///< Public key authoring the message. Must be checked against any private key calculating a signature over it. 29 }; 30 typedef struct lq_msg_t LQMsg; 31 32 /** 33 * \brief Instantiate a new message object. 34 * 35 * \param[in] Message data. Data will be copied. 36 * \param[in] Length of message data. 37 * \return Instantiated message object. It is the caller's responsibility to free to object. 38 * \see lq_msg_free 39 */ 40 LQMsg* lq_msg_new(const char *msg_data, size_t msg_len); 41 42 /** 43 * \brief Calculate a signature over the message. Uses default salt value. 44 * 45 * \param[in] Message to sign. 46 * \param[in] Private key to sign with. 47 * \param[in] Salt data to secure signature with. Set to NULL if salt is not to be used. 48 * \return Signature object. Object will be NULL if signature calculation failed. It is the caller's responsibility to free the signature object. 49 * 50 * \see lq_signature_free 51 */ 52 LQSig* lq_msg_sign(LQMsg *msg, LQPrivKey *pk, const char *salt); 53 54 /** 55 * \brief Calculate a signature over the message with a specified salt value. The salt value length must be LQ_SALT_LEN. 56 * 57 * \param[in] Message to sign. 58 * \param[in] Private key to sign with. 59 * \param[in] Salt data to secure signature with. Set to NULL if salt is not to be used. 60 * \param[in] Extra data to prefix message data with when calculating digest. If set to NULL, only message data will be used in digest. 61 * \param[in] Length of extra data. Ignored if extra data is NULL. 62 * \return Signature object. Object will be NULL if signature calculation failed. It is the caller's responsibility to free the signature object. 63 * 64 * \see lq_signature_free 65 */ 66 LQSig* lq_msg_sign_extra(LQMsg *msg, LQPrivKey *pk, const char *salt, const char *extra, size_t extra_len); 67 68 /** 69 * \brief Verify the signature over the message with specified salt value. The salt value length must be LQ_SALT_LEN. 70 * 71 * The message will be verified against the public key defined in the message structure. 72 * 73 * \param[in] Message to verify. (Must have the publickey member set). 74 * \param[in] Signature to verify. 75 * \param[in] Salt data that was used when calculating signature. Set to NULL if salt is not to be used. 76 * \param[in] Extra data to prefix message data with when calculating digest. If set to NULL, only message data will be used in digest. 77 * \param[in] Length of extra data. Ignored if extra data is NULL. 78 * \return ERR_OK on valid signature, ERR_NONSENSE if publickey missing. Any other value indicates failure. 79 * 80 * \see lq_signature_free 81 */ 82 int lq_msg_verify_extra(LQMsg *msg, LQSig *sig, const char *salt, const char *extra, size_t extra_len); 83 84 /** 85 * \brief Serialize message data payload for inclusion in certificate. 86 * 87 * \param[in] Message to serialize. 88 * \param[in] Store implementations to use for storing serialized message data. If NULL, content will not be stored in resolver. 89 * \param[out] Output buffer. 90 * \param[out] Value behind pointer must contain the capacity of output buffer. Will be overwritten with the actual number of bytes written. 91 * \return ERR_OK if serialization is successful, or: 92 * * ERR_INIT if the serialization object couldn't be instantiated. 93 * * ERR_OVERFLOW if output exceeded the available space in output buffer. 94 * * ERR_WRITE if serialization of an element failed. 95 * * ERR_ENCODING if generating the final serialization string failed. 96 */ 97 int lq_msg_serialize(LQMsg *msg, LQResolve *resolve, char *out, size_t *out_len); 98 99 /** 100 * \brief Deserialize message data payload from certificate. 101 * 102 * \param[out] Pointer to instantiated message. It is the caller's responsibility to free the message object. 103 * \param[in] Store implementations to use for resolving content key from deserialized message data. If NULL, content will not be resolved. 104 * \param[in] Serialized data. 105 * \param[in] Length of serialized data. 106 * \return ERR_OK if deserialization is successful, or: 107 * * ERR_INIT if the serialization object couldn't be instantiated. 108 * * ERR_READ if deserialization of an element failed. 109 * * ERR_ENCODING if interpretation of the serialized data failed. 110 * 111 * \see lq_msg_free 112 */ 113 int lq_msg_deserialize(LQMsg **msg, LQResolve *resolve, const char *in, size_t in_len); 114 115 /** 116 * \brief Mark message content as literal. 117 * 118 * In this case, the data of the message will be stored directly, instead of its hash. 119 * 120 * \param[in] Message to manipulate. 121 * \return ERR_OK if succesfully set, ERR_NOOP if already set. 122 */ 123 int lq_msg_literal(LQMsg *msg); 124 125 /** 126 * \brief Free an instantiated message. 127 * 128 * \param[in] Message to free. 129 */ 130 void lq_msg_free(LQMsg *msg); 131 132 /** 133 * \brief Serialize message content. 134 * 135 * \param[in] Content to serialize. 136 * \param[in] Length of content 137 * \param[out] Output buffer 138 * \param[in/out] Length of output buffer, will be overwritten by length of serialized data. 139 * 140 * \return ERR_OK on success. 141 * 142 * \see lq_msg_serialize 143 */ 144 int lq_attach_serialize(const char *in, size_t in_len, char *out, size_t *out_len); 145 146 #endif // LIBQAEDA_MSG_H_