p≡p engine
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.

569 lines
18 KiB

4 years ago
2 years ago
4 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
4 years ago
2 years ago
4 years ago
2 years ago
4 years ago
4 years ago
4 years ago
4 years ago
2 years ago
4 years ago
4 years ago
4 years ago
2 years ago
4 years ago
2 years ago
4 years ago
2 years ago
4 years ago
3 years ago
2 years ago
3 years ago
3 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
3 years ago
3 years ago
4 years ago
3 years ago
4 years ago
3 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
  1. // p≡p Message API
  2. // Copyleft (c) 2019-2020, p≡p foundation
  3. // this file is under GNU General Public License 3.0
  4. // see LICENSE.txt
  5. // written by Volker Birk and Nana Karlstetter
  6. enum text_format {
  7. hex plain 0;
  8. hex html 1;
  9. hex other 0xff;
  10. }
  11. enum direction {
  12. item incoming 0;
  13. item outgoing 1;
  14. }
  15. enum enc_format {
  16. item none 0 doc='message is not encrypted';
  17. item pieces 1 doc='inline PGP + PGP extensions';
  18. item S_MIME 2 doc='RFC5751';
  19. item PGP_MIME 3 doc='RFC3156';
  20. item PEP 4 doc='pEp encryption format';
  21. item PGP_MIME_Outlook1 5 doc='Message B0rken by Outlook type 1';
  22. }
  23. enum rating {
  24. item undefined 0 doc="no rating available";
  25. doc "no color";
  26. item cannot_decrypt 1;
  27. item have_no_key 2;
  28. item unencrypted 3;
  29. // 4 is reserved
  30. item unreliable 5;
  31. doc "yellow";
  32. item reliable 6;
  33. doc "green";
  34. item trusted 7;
  35. item trusted_and_anonymized 8;
  36. item fully_anonymous 9;
  37. doc "red";
  38. item mistrust -1;
  39. item b0rken -2;
  40. item under_attack -3;
  41. }
  42. enum color {
  43. item no_color 0;
  44. item yellow 1;
  45. item green 2;
  46. item red -1;
  47. }
  48. struct message {
  49. field direction dir;
  50. field string id doc='string of message ID';
  51. field string shortmsg doc='string of short message';
  52. field string longmsg doc='string of long message (plain)';
  53. field string longmsg_formatted doc='string of long message (formatted)';
  54. field blob_list attachments doc='blobs with attachements';
  55. field binary_ref rawmsg_ref doc='reference to raw message data';
  56. field size_t rawmsg_size doc='size of raw message data';
  57. field timestamp sent doc='when the message is sent';
  58. field timestamp recv doc='when the message is received';
  59. field identity from doc='whom the message is from';
  60. field identity_list to doc='whom the message is to';
  61. field identity recv_by doc='via which identity the message is received';
  62. field identity_list cc doc='whom a CC is being sent';
  63. field identity_list bcc doc='whom a BCC is being sent';
  64. field identity_list reply_to doc='where a reply should go to';
  65. field string_list in_reply_to doc='list of strings with MessageIDs of refering messages';
  66. field any_ref refering_msg_ref doc='reference to refering message';
  67. field string_list references doc='list of strings with references';
  68. field string_list refered_by doc='list of references to messages being refered';
  69. field string_list keywords doc='list of strings with keywords';
  70. field string comments doc='string with comments';
  71. field string_pair_list opt_fields doc='optional fields';
  72. field enc_format format doc='format of encrypted data';
  73. new (msg_direction dir);
  74. }
  75. protocol session {
  76. method encrypt_message
  77. doc="""
  78. encrypt message in memory. enc_format PEP_enc_inline_EA:
  79. internal format of the encrypted attachments is changing, see
  80. https://dev.pep.foundation/Engine/ElevatedAttachments
  81. Only use this for transports without support for attachments
  82. when attached data must be sent inline
  83. """;
  84. {
  85. // parms
  86. lend message src
  87. doc="""
  88. message to encrypt - usually in-only, but can be in-out for
  89. unencrypted messages; in that case, we may attach the key and
  90. decorate the message
  91. """;
  92. use hash_list extra doc="extra keys for encryption";
  93. create message dst
  94. doc="""
  95. pointer to new encrypted message or #NV if no encryption could
  96. take place
  97. """;
  98. use enc_format format doc="The desired format this message should be encrypted with";
  99. // flags
  100. flags {
  101. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  102. flag force_encryption 0x1;
  103. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  104. flag force_no_attached_key 0x4;
  105. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  106. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  107. flag key_reset_only 0x20
  108. doc="""This flag is used to let internal functions know that an encryption call is being
  109. used as part of a reencryption operation
  110. """;
  111. flag encrypt_reencrypt 0x40;
  112. }
  113. // exceptions
  114. throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
  115. throws unencrypted
  116. doc="""
  117. on demand or no recipients with usable key, is left unencrypted,
  118. and key is attached to it
  119. """;
  120. }
  121. method encrypt_message_and_add_priv_key
  122. doc="""
  123. encrypt message in memory, adding an encrypted private key (encrypted separately
  124. and sent within the inner message)
  125. """
  126. {
  127. // parms
  128. use message src doc="message to encrypt";
  129. create message dst
  130. doc="pointer to new encrypted message or empty if no encryption could take place";
  131. use hash to_fpr
  132. doc="fingerprint of the recipient key to which the private key should be encrypted";
  133. use enc_format format doc="encrypted format";
  134. // flags
  135. flags {
  136. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  137. flag force_encryption 0x1;
  138. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  139. flag force_no_attached_key 0x4;
  140. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  141. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  142. flag key_reset_only 0x20;
  143. }
  144. // exceptions
  145. throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
  146. throws unencrypted
  147. doc="""
  148. on demand or no recipients with usable key, is left unencrypted,
  149. and key is attached to it
  150. """;
  151. }
  152. method encrypt_message_for_self
  153. doc="""
  154. encrypt message in memory for user's identity only,
  155. ignoring recipients and other identities from the message
  156. """
  157. {
  158. // parms
  159. use identity target_id
  160. doc="""
  161. self identity this message should be encrypted for. Message is NOT encrypted for
  162. identities other than the target_id (and then, only if the target_id refers to self!).
  163. """;
  164. use message src doc="message to encrypt";
  165. use hash_list extra doc="extra keys for encryption";
  166. create message dst doc="pointer to new encrypted message or empty on failure";
  167. use enc_format format doc="encrypted format";
  168. // flags
  169. flags {
  170. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  171. flag force_encryption 0x1;
  172. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  173. flag force_no_attached_key 0x4;
  174. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  175. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  176. flag key_reset_only 0x20;
  177. }
  178. doc | (FIXME: The exceptions may not be correct or complete)
  179. throws key_not_found doc="at least one of the receipient keys could not be found";
  180. throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
  181. throws get_key_failed doc="cannot retrieve key";
  182. }
  183. method decrypt_message doc="decrypt message in memory"
  184. {
  185. // parms
  186. lend message src
  187. doc="""
  188. message to decrypt.
  189. The ownership of src remains with the caller - however, the contents
  190. might be modified (strings freed and allocated anew or set to empty,
  191. etc) intentionally; when this happens, decrypt_flag_src_modified is set.
  192. """;
  193. create message dst doc="pointer to new decrypted message or empty on failure";
  194. lend hash_list keylist
  195. doc="""
  196. in: stringlist with additional keyids for reencryption if needed
  197. (will be freed and replaced with output keylist)
  198. out: stringlist with keyids used for signing and encryption. first
  199. first key is signer, additional keys are the ones it was encrypted
  200. to. Only signer and whichever of the user's keys was used are reliable.
  201. The ownership of keylist goes to the caller.
  202. If src is unencrypted this function returns unencrypted and sets dst to empty.
  203. """;
  204. return rating msg_rating doc="rating for the message";
  205. // flags
  206. flags {
  207. flag decrypt_flag_own_private_key 0x1
  208. doc="""
  209. private key was imported for one of our addresses (NOT trusted
  210. or set to be used - handshake/trust is required for that)
  211. """;
  212. flag decrypt_flag_consume 0x2 doc='used by sync';
  213. flag decrypt_flag_ignore 0x4 doc='used by sync';
  214. flag decrypt_flag_src_modified 0x8
  215. doc="""
  216. indicates that the src object has been modified. At the moment,
  217. this is always as a direct result of the behaviour driven
  218. by the input flags. This flag is the ONLY value that should be
  219. relied upon to see if such changes have taken place.
  220. """;
  221. flag decrypt_flag_untrusted_server 0x100
  222. doc="""
  223. input flag. Used to signal that decrypt function should engage in behaviour
  224. specified for when the server storing the source is untrusted.
  225. """;
  226. flag decrypt_flag_dont_trigger_sync 0x200;
  227. }
  228. // exceptions
  229. throws decrypted doc="if message decrypted but not verified";
  230. throws cannot_reencrypt
  231. doc="""
  232. if message was decrypted (and possibly verified) but a reencryption
  233. operation is expected by the caller and failed.
  234. """;
  235. throws unencrypted
  236. doc="""
  237. if src is unencrypted this function returns unencrypted and sets
  238. dst to empty.
  239. """;
  240. throws any doc="all error status values allowed";
  241. }
  242. method own_message_private_key_details
  243. doc="""
  244. details on own key in own message. Note: In order to obtain details about key
  245. to be possibly imported as a replacement of key currently used as own identity,
  246. application passes message that have been previously flagged by decrypt_message()
  247. as own message containing own key to this function.
  248. """
  249. {
  250. // parms
  251. use message msg
  252. doc="""
  253. message to decrypt. msg MUST be encrypted so that this function
  254. can check own signature.
  255. """;
  256. create identity ident doc="identity containing uid, address and fpr of key";
  257. // exceptions
  258. throws any doc="error status";
  259. }
  260. method outgoing_message_rating doc="get rating for an outgoing message"
  261. {
  262. // parms
  263. use message msg
  264. doc="""
  265. message to get the rating for. From must point to a valid pEp_identity.
  266. Dir must be dir_outgoing.
  267. """;
  268. return rating msg_rating doc="rating for the message";
  269. // exceptions
  270. throws any doc="error status";
  271. }
  272. method outgoing_message_rating_preview doc="get rating preview"
  273. {
  274. // parms
  275. use message msg
  276. doc="""
  277. message to get the rating for. From must point to a valid pEp_identity.
  278. Dir must be dir_outgoing.
  279. """;
  280. return rating msg_rating doc="rating preview for the message";
  281. // exceptions
  282. throws any doc="error status";
  283. }
  284. method identity_rating doc="get rating for a single identity"
  285. {
  286. // parms
  287. use identity ident doc="identity to get the rating for";
  288. return rating identity_rating doc="rating for the identity";
  289. // exceptions
  290. throws any doc="error status";
  291. }
  292. method get_trustwords doc="get full trustwords string for a *pair* of identities"
  293. {
  294. // parms
  295. use identity id1 doc="identity of first party in communication - fpr can't be empty";
  296. use identity id2 doc="identity of second party in communication - fpr can't be empty";
  297. use ISO639_1 lang doc="string with ISO 639-1 language code";
  298. create string words
  299. doc="""
  300. string with all trustwords, separated
  301. by a blank each. Empty if language is not supported or trustword
  302. wordlist is damaged or unavailable.
  303. The word pointer goes to the ownership of the caller.
  304. The caller is responsible to free() it (on Windoze use pEp_free())
  305. """;
  306. use bool full
  307. doc="""
  308. if true, generate ALL trustwords for these identities.
  309. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  310. subset in next version)
  311. """;
  312. // exceptions
  313. throws out_of_memory doc="out of memory";
  314. throws trustword_not_found doc="at least one trustword not found";
  315. }
  316. method get_message_trustwords doc="get full trustwords string for message sender and reciever identities"
  317. {
  318. // parms
  319. use message msg doc="message to get sender identity from";
  320. use hash_list keylist doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise.";
  321. use identity received_by doc="identity for account receiving message can't be empty";
  322. use ISO639_1 lang doc="string with ISO 639-1 language code";
  323. create string words
  324. doc="""
  325. string with all trustwords, separated by a blank each.
  326. Empty if language is not supported or trustword wordlist is damaged or unavailable.
  327. """;
  328. use bool full
  329. doc="""
  330. if true, generate ALL trustwords for these identities.
  331. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  332. subset in next version)
  333. """;
  334. // exceptions
  335. throws out_of_memory doc="out of memory";
  336. throws trustword_not_found doc="at least one trustword not found";
  337. throws like decrypt_message doc="error status of decrypt_message() if decryption fails";
  338. }
  339. method get_trustwords_for_fprs doc="get full trustwords string for a pair of fingerprints"
  340. {
  341. // parms
  342. use string fpr1 doc="fingerprint 1";
  343. use string fpr2 doc="fingerprint 2";
  344. use ISO639_1 lang doc="string with ISO 639-1 language code";
  345. create string words
  346. doc="""
  347. pointer to string with all trustwords UTF-8 encoded, separated by a blank each.
  348. NULL if language is not supported or trustword wordlist is damaged or unavailable.
  349. The caller is responsible to free() it (on Windoze use pEp_free()).
  350. """;
  351. return size_t wsize doc="length of full trustwords string";
  352. use bool full
  353. doc="""
  354. if true, generate ALL trustwords for these identities. Else, generate a fixed-size
  355. subset. (TODO: fixed-minimum-entropy subset in next version)
  356. """;
  357. // exceptions
  358. throws out_of_memory doc="out of memory";
  359. throws trustword_not_found doc="at least one trustword not found";
  360. }
  361. method re_evaluate_message_rating doc="re-evaluate already decrypted message rating"
  362. {
  363. // parms
  364. use message msg doc="message to get the rating for. msg->from must point to a valid pEp_identity";
  365. use hash_list x_keylist doc="decrypted message recipients keys fpr";
  366. use rating x_enc_status doc="original rating for the decrypted message";
  367. return rating msg_rating doc="rating for the message";
  368. // exceptions
  369. throws illegal_value
  370. doc="""
  371. if decrypted message doesn't contain X-EncStatus optional field and
  372. x_enc_status is pEp_rating_udefined or if decrypted message doesn't
  373. contain X-Keylist optional field and x_keylist is empty.
  374. """;
  375. throws out_of_memory doc="if not enough memory could be allocated";
  376. }
  377. method get_key_rating_for_user doc="get the rating of a certain key for a certain user"
  378. {
  379. // parms
  380. use string user_id doc="string with user ID";
  381. use string fpr doc="string with fingerprint";
  382. return rating key_rating doc="rating of key for this user";
  383. // exceptions
  384. throws record_not_found doc="if no trust record for user_id and fpr can be found";
  385. }
  386. method rating_from_comm_type doc="get the rating for a comm type"
  387. {
  388. // parms
  389. use comm_type ct doc="the comm type to deliver the rating for";
  390. // exceptions
  391. throws any doc="rating value for comm type ct";
  392. }
  393. }
  394. func color_from_rating doc="calculate color from rating"
  395. {
  396. // parms
  397. use color_from_rating rating doc="color representing that rating";
  398. // return value
  399. return color rating_color doc="color representing that rating";
  400. }
  401. func get_binary_path doc="retrieve path of cryptotech binary if available"
  402. {
  403. //parms
  404. use cryptotech tech doc="cryptotech to get the binary for";
  405. use string path
  406. doc="""
  407. path to cryptotech binary or empty if not available. **path is owned by
  408. the library, do not change it!
  409. """;
  410. }