You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

190 lines
6.1 KiB

6 years ago
3 years ago
1 year ago
6 years ago
6 years ago
6 years ago
3 years ago
6 years ago
1 year ago
1 year ago
6 years ago
  1. /**
  2. * @file baseprotocol.h
  3. * @brief Basic functions for administrative pEp messages (preparation,
  4. * decoration, payload, extraction, etc.). These are used for
  5. * protocol messages in, for example, key sync and key reset.
  6. * The payloads of these messages are, in general, not human-readable.
  7. * @license GNU General Public License 3.0 - see LICENSE.txt
  8. */
  9. #ifndef BASEPROTOCOL_H
  10. #define BASEPROTOCOL_H
  11. #include "message.h"
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15. #define _BASE_PROTO_MIME_TYPE_SIGN "application/pEp.sign"
  16. #define _BASE_PROTO_MIME_TYPE_SYNC "application/pEp.sync"
  17. #define _BASE_PROTO_MIME_TYPE_DIST "application/pEp.distribution"
  18. /**
  19. * @enum base_protocol_type
  20. *
  21. * @brief TODO
  22. *
  23. */
  24. typedef enum _base_protocol_type {
  25. BASE_SIGN = 0,
  26. BASE_SYNC = 1,
  27. BASE_DISTRIBUTION = 2
  28. } base_protocol_type;
  29. /**
  30. * <!-- base_decorate_message() -->
  31. *
  32. * @brief Given the data payload for an administrative message, add the appropriate
  33. * information for the payload based on type and insert the payload into the
  34. * message
  35. *
  36. * @param[in] session session handle
  37. * @param[in,out] msg message to decorate
  38. * @param[in] type base protocol type
  39. * @param[in] payload payload to send
  40. * @param[in] size size of payload
  41. * @param[in] fpr optional key to sign or NULL
  42. *
  43. * @retval PEP_STATUS_OK on success
  44. * @retval error_status on failure
  45. *
  46. * @ownership
  47. * - On success (and only then), ownership of the payload is assigned to the msg structure
  48. * - Ownership of the msg remains with the caller
  49. *
  50. */
  51. PEP_STATUS base_decorate_message(
  52. PEP_SESSION session,
  53. message *msg,
  54. base_protocol_type type,
  55. char *payload,
  56. size_t size,
  57. const char *fpr
  58. );
  59. /**
  60. * <!-- base_prepare_message() -->
  61. *
  62. * @brief Given a protocol data payload and a message type, prepare an administrative
  63. * protocol message for encryption and/or delivery
  64. *
  65. * @param[in] session session handle
  66. * @param[in] me identity to use for the sender
  67. * @param[in] partner identity to use for the receiver
  68. * @param[in] type base protocol type
  69. * @param[in] payload payload to send
  70. * @param[in] size size of payload
  71. * @param[in] fpr optional key to sign or NULL
  72. * @param[out] result returned message with payload on success
  73. *
  74. * @retval PEP_STATUS_OK on success
  75. * @retval PEP_OUT_OF_MEMORY out of memory
  76. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  77. * @retval any other value on failure
  78. *
  79. * @ownership
  80. * - On (and only on) success, ownership of payload is assigned to the result structure
  81. * - Ownership of the result goes to the caller
  82. *
  83. */
  84. PEP_STATUS base_prepare_message(
  85. PEP_SESSION session,
  86. const pEp_identity *me,
  87. const pEp_identity *partner,
  88. base_protocol_type type,
  89. char *payload,
  90. size_t size,
  91. const char *fpr,
  92. message **result
  93. );
  94. /**
  95. * <!-- base_extract_message() -->
  96. *
  97. * @brief Extract protocol data from a pEp administrative message
  98. *
  99. * @param[in] session session handle
  100. * @param[in] msg message to analyze
  101. * @param[in] type base protocol type to extract
  102. * @param[out] size size of extracted payload, or 0 if not found
  103. * @param[out] payload extracted payload, if sync message is found.
  104. * otherwise, NULL
  105. * @param[out] fpr if message was correctly signed then fpr of signature's
  106. * key, otherwise NULL
  107. *
  108. * @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
  109. * @retval PEP_OUT_OF_MEMORY out of memory
  110. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  111. * @retval error_status any other value on error
  112. *
  113. * @ownership
  114. * - Payload may point to msg attachment, but the ownership does not change
  115. * - If fpr != NULL the ownership goes to the caller
  116. *
  117. * @todo Volker, expand this definition from sync message. What do we call these? Administrative messages? - K
  118. *
  119. */
  120. PEP_STATUS base_extract_message(
  121. PEP_SESSION session,
  122. message *msg,
  123. base_protocol_type type,
  124. size_t *size,
  125. const char **payload,
  126. char **fpr
  127. );
  128. /**
  129. * <!-- try_base_prepare_message() -->
  130. *
  131. * @brief Prepare an administrative message with payload. This is the internal function to be used by
  132. * asynchronous network protocol implementations. This function differs from
  133. * base_prepare_message in that it calls messageToSend(NULL) in case there is a missing
  134. * or wrong passphrase, but more explanation is required here.
  135. *
  136. * @param[in] session session handle
  137. * @param[in] me identity to use for the sender
  138. * @param[in] partner identity to use for the receiver
  139. * @param[in] type base protocol type
  140. * @param[in] payload payload to send
  141. * @param[in] size size of payload
  142. * @param[in] fpr optional key to sign or NULL
  143. * @param[out] result returned message with payload on success
  144. *
  145. * @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
  146. * @retval PEP_OUT_OF_MEMORY out of memory
  147. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  148. * @retval error_status any other value on error
  149. *
  150. * @ownership
  151. * - On (and only on) success, ownership of payload is assigned to the result structure
  152. * - Ownership of the result goes to the caller
  153. *
  154. * @todo Volker, I need a better explanation of the use case here to document correctly - K
  155. *
  156. * @see base_prepare_message()
  157. */
  158. PEP_STATUS try_base_prepare_message(
  159. PEP_SESSION session,
  160. const pEp_identity *me,
  161. const pEp_identity *partner,
  162. base_protocol_type type,
  163. char *payload,
  164. size_t size,
  165. const char *fpr,
  166. message **result
  167. );
  168. #ifdef __cplusplus
  169. }
  170. #endif
  171. #endif