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.

531 lines
12 KiB

4 years ago
4 years ago
4 years ago
  1. // p≡p Message API
  2. // Copyleft (c) 2019, p≡p foundation
  3. // this file is under GNU General Public License 3.0
  4. // see LICENSE.txt
  5. // written by Volker Birk
  6. protocol session {
  7. method encrypt_message
  8. doc="encrypt message in memory"
  9. {
  10. // parms
  11. supply message src
  12. doc="""
  13. message to encrypt - usually in-only, but can be in-out for
  14. unencrypted messages; in that case, we may attach the key and
  15. decorate the message
  16. """;
  17. use hash_list extra doc="extra keys for encryption";
  18. create message dst
  19. doc="""
  20. pointer to new encrypted message or #NV if no encryption could
  21. take place
  22. """
  23. use encformat format doc="encrypted format";
  24. // flags
  25. flags {
  26. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  27. flag force_encryption 0x1;
  28. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  29. flag force_no_attached_key 0x4;
  30. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  31. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  32. flag key_reset_only 0x20
  33. }
  34. // exceptions
  35. throws key_has_ambig_name
  36. doc="at least one of the receipient keys has an ambiguous name";
  37. throws unencrypted
  38. doc="""
  39. on demand or no recipients with usable key, is left unencrypted,
  40. and key is attached to it
  41. """
  42. }
  43. }
  44. protocol session {
  45. method encrypt_message_and_add_priv_key
  46. doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)"
  47. {
  48. // parms
  49. use message src
  50. doc="message to encrypt";
  51. create message dst
  52. doc="pointer to new encrypted message or NULL if no encryption could take place";
  53. to_fpr
  54. doc="fingerprint of the recipient key to which the private key should be encrypted";
  55. use format enc_format?
  56. doc="encrypted format";
  57. // flags
  58. flags {
  59. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  60. flag force_encryption 0x1;
  61. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  62. flag force_no_attached_key 0x4;
  63. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  64. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  65. flag key_reset_only 0x20
  66. }
  67. // exceptions
  68. throws key_has_ambig_name
  69. doc="at least one of the receipient keys has an ambiguous name";
  70. throws unencrypted
  71. doc="""
  72. on demand or no recipients with usable key, is left unencrypted,
  73. and key is attached to it
  74. """
  75. }
  76. }
  77. protocol session {
  78. method encrypt_message_for_self
  79. doc="""
  80. encrypt message in memory for user's identity only,
  81. ignoring recipients and other identities from the message
  82. """
  83. {
  84. // parms
  85. use message target_id
  86. doc="self identity this message should be encrypted for";
  87. use message src
  88. doc="message to encrypt";
  89. provide key? extra
  90. doc="extra keys for encryption";
  91. create message dst
  92. doc="pointer to new encrypted message or NULL on failure";
  93. use format enc_format?
  94. doc="encrypted format";
  95. // flags
  96. flags {
  97. flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
  98. flag force_encryption 0x1;
  99. flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
  100. flag force_no_attached_key 0x4;
  101. flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
  102. flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
  103. flag key_reset_only 0x20
  104. }
  105. // exceptions
  106. throws key_not_found
  107. doc="at least one of the receipient keys could not be found";
  108. throws key_has_ambig_name
  109. doc="at least one of the receipient keys has an ambiguous name";
  110. throws get_key_failed
  111. doc="cannot retrieve key"
  112. }
  113. }
  114. protocol session {
  115. method color_from_rating
  116. doc="calculate color from rating"
  117. {
  118. // parms
  119. provide message rating?
  120. doc="color representing that rating";
  121. // ratings
  122. ratings {
  123. rating_undefined 0;
  124. rating_cannot_decrypt,
  125. rating_have_no_key,
  126. rating_unencrypted,
  127. rating_unencrypted_for_some doc="don't use this any more",
  128. rating_unreliable,
  129. rating_reliable,
  130. rating_trusted,
  131. rating_trusted_and_anonymized,
  132. rating_fully_anonymous,
  133. rating_mistrust -1;
  134. rating_b0rken -2;
  135. rating_under_attack -3
  136. }
  137. // colors
  138. colors {
  139. color_no_color 0;
  140. color_yellow,
  141. color_green,
  142. color_red -1
  143. }
  144. // return value
  145. doc="color representing that rating"
  146. }
  147. }
  148. protocol session {
  149. method decrypt_message
  150. doc="decrypt message in memory"
  151. {
  152. // parms
  153. supply message src
  154. doc="""
  155. message to decrypt.
  156. The ownership of src remains with the caller - however, the contents
  157. might be modified (strings freed and allocated anew or set to NULL,
  158. etc) intentionally; when this happens, decrypt_flag_src_modified is set.
  159. """;
  160. create message dst
  161. doc="pointer to new decrypted message or NULL on failure";
  162. supply message keylist
  163. doc="""
  164. in: stringlist with additional keyids for reencryption if needed
  165. (will be freed and replaced with output keylist)
  166. out: stringlist with keyids used for signing and encryption. first
  167. first key is signer, additional keys are the ones it was encrypted
  168. to. Only signer and whichever of the user's keys was used are reliable.
  169. """;
  170. return message rating
  171. doc="rating for the message";
  172. // flags
  173. decrypt_flags {
  174. decrypt_flag_own_private_key 0x1
  175. doc="""
  176. private key was imported for one of our addresses (NOT trusted
  177. or set to be used - handshake/trust is required for that)
  178. """
  179. decrypt_flag_consume 0x2 doc=’used by sync';
  180. decrypt_flag_ignore 0x4 doc=’used by sync';
  181. decrypt_flag_src_modified 0x8
  182. doc="""
  183. indicates that the src object has been modified. At the moment,
  184. this is always as a direct result of the behaviour driven
  185. by the input flags. This flag is the ONLY value that should be
  186. relied upon to see if such changes have taken place.
  187. """;
  188. decrypt_flag_untrusted_server 0x100
  189. doc="""
  190. input flags. Used to signal that decrypt function should engage in behaviour
  191. specified for when the server storing the source is untrusted.
  192. """
  193. }
  194. // exceptions
  195. throws decrypted
  196. doc="if message decrypted but not verified";
  197. throws cannot_reencrypt
  198. doc="""
  199. if message was decrypted (and possibly verified) but a reencryption
  200. operation is expected by the caller and failed.
  201. """;
  202. throws unencrypted
  203. doc="""
  204. if src is unencrypted this function returns unencrypted and sets
  205. dst to NULL.
  206. """
  207. }
  208. }
  209. protocol session {
  210. method own_message_private_key_details
  211. doc="details on own key in own message"
  212. {
  213. //parms
  214. use message msg
  215. doc="""
  216. message to decrypt. msg MUST be encrypted so that this function
  217. can check own signature.
  218. """;
  219. create @type? ident
  220. doc="identity containing uid, address and fpr of key"
  221. }
  222. }
  223. protocol session {
  224. method outgoing_message_rating
  225. doc="get rating for an outgoing message"
  226. {
  227. //parms
  228. use message msg
  229. doc="""
  230. message to get the rating for. From must point to a valid pEp_identity.
  231. Dir must be dir_outgoing.
  232. """;
  233. create message rating
  234. doc="rating for the message"
  235. }
  236. }
  237. protocol session {
  238. method outgoing_message_rating_preview
  239. doc="get rating preview"
  240. {
  241. //parms
  242. use message msg
  243. doc="""
  244. message to get the rating for. From must point to a valid pEp_identity.
  245. Dir must be dir_outgoing.
  246. """;
  247. create message rating
  248. doc="rating preview for the message"
  249. }
  250. }
  251. protocol session {
  252. method identity_rating
  253. doc="get rating for a single identity"
  254. {
  255. //parms
  256. use @type ident
  257. doc="identity to get the rating for";
  258. create identity rating
  259. doc="rating for the identity"
  260. }
  261. }
  262. protocol session {
  263. method get_binary_path
  264. doc="retrieve path of cryptotech binary if available"
  265. {
  266. //parms
  267. use @type tech
  268. doc="cryptotech to get the binary for";
  269. use @type path
  270. doc="""
  271. path to cryptotech binary or NULL if not available. **path is owned by
  272. the library, do not change it!
  273. """
  274. }
  275. }
  276. protocol session {
  277. method get_trustwords
  278. doc="get full trustwords string for a *pair* of identities"
  279. {
  280. //parms
  281. provide message id1
  282. doc="identity of first party in communication - fpr can't be NULL";
  283. provide message id2
  284. doc="identity of second party in communication - fpr can't be NULL";
  285. provide message lang
  286. doc="C string with ISO 639-1 language code";
  287. create message words
  288. doc="""
  289. pointer to C string with all trustwords UTF-8 encoded, separated
  290. by a blank each NULL if language is not supported or trustword
  291. wordlist is damaged or unavailable.
  292. The word pointer goes to the ownership of the caller.
  293. The caller is responsible to free() it (on Windoze use pEp_free())
  294. """;
  295. create @type? wsize
  296. doc="length of full trustwords string";
  297. provide @type full
  298. doc="""
  299. if true, generate ALL trustwords for these identities.
  300. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  301. subset in next version)
  302. """
  303. // exceptions
  304. throws out_of_memory
  305. doc="out of memory";
  306. throws trustword_not_found
  307. doc="at least one trustword not found"
  308. }
  309. }
  310. protocol session
  311. method get_message_trustwords
  312. doc="get full trustwords string for message sender and reciever identities"
  313. {
  314. //parms
  315. provide @type msg
  316. doc="message to get sender identity from";
  317. provide message keylist
  318. doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
  319. provide message received_by
  320. doc="identity for account receiving message can't be NULL";
  321. provide @type? lang
  322. doc="C string with ISO 639-1 language code";
  323. create message words
  324. doc="""
  325. pointer to C string with all trustwords UTF-8 encoded, separated by a blank each.
  326. NULL if language is not supported or trustword wordlist is damaged or unavailable.
  327. The word pointer goes to the ownership of the caller.
  328. The caller is responsible to free() it (on Windoze use pEp_free())
  329. """;
  330. provide @type full
  331. doc="""
  332. if true, generate ALL trustwords for these identities.
  333. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  334. subset in next version)
  335. """
  336. // exceptions
  337. throws out_of_memory
  338. doc="out of memory";
  339. throws trustword_not_found
  340. doc="at least one trustword not found"
  341. }
  342. }
  343. protocol session
  344. method re_evaluate_message_rating
  345. doc="re-evaluate already decrypted message rating"
  346. {
  347. //parms
  348. use @type msg
  349. doc="message to get the rating for. msg->from must point to a valid pEp_identity";
  350. use message x_keylist
  351. doc="decrypted message recipients keys fpr";
  352. provide message x_enc_status
  353. doc="original rating for the decrypted message";
  354. create message rating
  355. doc="rating for the message"
  356. // exceptions
  357. throws illegal_value
  358. doc="""
  359. if decrypted message doesn't contain X-EncStatus optional field and
  360. x_enc_status is pEp_rating_udefined or if decrypted message doesn't
  361. contain X-Keylist optional field and x_keylist is NULL.
  362. """;
  363. throws out_of_memory
  364. doc="if not enough memory could be allocated"
  365. }
  366. }
  367. protocol session
  368. method get_key_rating_for_user
  369. doc="get the rating of a certain key for a certain user"
  370. {
  371. //parms
  372. provide @type? user_id
  373. doc="string with user ID";
  374. provide @type fpr
  375. doc="string with fingerprint";
  376. create @type rating
  377. doc="rating of key for this user"
  378. // exceptions
  379. throws record_not_found
  380. doc="if no trust record for user_id and fpr can be found"
  381. }
  382. }