p≡p engine fork for my own dirty testing of stuff
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.

511 lines
14 KiB

3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
2 years ago
3 years ago
3 years ago
2 years ago
3 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
3 years ago
3 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
3 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
3 years ago
3 years ago
2 years ago
3 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
4 months ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
2 years ago
3 years ago
4 months ago
4 months ago
3 years ago
  1. // p≡p Basic 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 Nana Karlstetter and Volker Birk
  6. type ISO639_1 is string size=2 > a-z;
  7. type hexcode is string > a-f0-9;
  8. type hash doc="32bit Key ID to SHA512 in hexcode"
  9. is hexcode min=16, max=128;
  10. type hash_list doc="sequence of fingerprints of keys"
  11. is list< hash >;
  12. type TID doc="UUID version 4 variant 1"
  13. is binary size=16;
  14. type binary_ref is weak< binary >;
  15. enum content_disposition {
  16. item attachment 0;
  17. item inline 1;
  18. item other -1 doc="must be affirmatively set";
  19. }
  20. struct blob {
  21. field function=free binary_ref value;
  22. field size_t size;
  23. field string mime_type;
  24. field string filename;
  25. field content_disposition disposition;
  26. }
  27. type blob_list is list< blob >;
  28. type identity_list is list< identity >;
  29. type string_list is list< string >;
  30. type string_pair is pair< string, string >;
  31. type string_pair_list is list< string_pair >;
  32. type any_ref is weak< any >;
  33. enum cipher_suite {
  34. item default 0;
  35. item cv25519 1;
  36. item p256 2;
  37. item p384 3;
  38. item p521 4;
  39. item rsa2k 5;
  40. item rsa3k 6;
  41. item rsa4k 7;
  42. item rsa8k 8;
  43. }
  44. enum comm_type {
  45. hex unknown 0;
  46. doc > range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
  47. hex no_encryption 0x01;
  48. hex no_encrypted_channel 0x02;
  49. hex key_not_found 0x03;
  50. hex key_expired 0x04;
  51. hex key_revoked 0x05;
  52. hex key_b0rken 0x06;
  53. hex key_expired_but_confirmed 0x07
  54. doc="NOT with confirmed bit. Just retaining info here in case of renewal.";
  55. hex my_key_not_included 0x09;
  56. hex security_by_obscurity 0x0a;
  57. hex b0rken_crypto 0x0b;
  58. hex key_too_short 0x0c;
  59. hex compromised 0x0e doc="known compromised connection";
  60. hex mistrusted 0x0f doc="known mistrusted key";
  61. doc > range 0x10 to 0x3f: unconfirmed encryption
  62. hex unconfirmed_encryption 0x10 doc="generic";
  63. hex OpenPGP_weak_unconfirmed 0x11 doc="RSA 1024 is weak";
  64. hex to_be_checked 0x20 doc="generic";
  65. hex SMIME_unconfirmed 0x21 doc="encrypted with S/MIME";
  66. hex CMS_unconfirmed 0x22;
  67. hex strong_but_unconfirmed 0x30 doc="generic";
  68. hex OpenPGP_unconfirmed 0x38 doc="key at least 2048 bit RSA, EC, or anything useful";
  69. hex OTR_unconfirmed 0x3a doc="encrypted with OTR";
  70. doc > range 0x40 to 0x7f: unconfirmed encryption and anonymization
  71. hex unconfirmed_enc_anon 0x40 doc="generic";
  72. hex pEp_unconfirmed 0x7f doc="encrypted with pEp";
  73. hex confirmed 0x80 doc="this bit decides if trust is confirmed";
  74. doc > range 0x81 to 0x8f: reserved
  75. doc > range 0x90 to 0xbf: confirmed encryption
  76. hex confirmed_encryption 0x90 doc="generic";
  77. hex OpenPGP_weak 0x91 doc="RSA 1024 is weak (unused)";
  78. hex to_be_checked_confirmed 0xa0 doc="generic";
  79. hex SMIME 0xa1;
  80. hex CMS 0xa2;
  81. hex strong_encryption 0xb0 doc="generic";
  82. hex OpenPGP 0xb8 doc="key at least 2048 bit RSA or EC";
  83. hex OTR 0xba;
  84. doc > range 0xc0 to 0xff: confirmed encryption and anonymization
  85. hex confirmed_enc_anon 0xc0 doc="generic";
  86. hex pEp 0xff;
  87. } // enum comm_type
  88. struct identity {
  89. field string address doc="SMTP address or URI. String with address UTF-8 encoded";
  90. field hash fpr doc="fingerprint of key being used as ID. String with fingerprint UTF-8 encoded";
  91. field string user_id doc="ID for person or system in case of M2M";
  92. doc ||
  93. user_id MIGHT be set to "pEp_own_userId" (use PEP_OWN_USERID preprocessor define)
  94. if this is own user's identity. But it is not REQUIRED to be.
  95. ||
  96. field string username doc="descriptive string. String with user name UTF-8 encoded";
  97. field comm_type comm_type doc="type of communication with this ID";
  98. field ISO639_1 lang[3] doc="ISO 639-1 ALPHA-2, last byte is 0";
  99. field bool me doc="if this is the local user herself/himself";
  100. field unsigned major_ver doc="highest version of pEp message received, if any";
  101. field unsigned minor_ver doc="highest version of pEp message received, if any";
  102. flags {
  103. flag not_for_sync 0x0001
  104. doc="don't use this identity for Sync";
  105. flag list 0x0002
  106. doc="identity of list of persons";
  107. doc | the second octet flags are calculated
  108. flag devicegroup 0x0100
  109. doc="identity of a device group member";
  110. }
  111. } // struct Identity
  112. protocol session {
  113. callback messageToSend doc="a message needs to be delivered by application"
  114. {
  115. // parms
  116. provide struct_message msg doc="message struct with message to send";
  117. // exceptions
  118. throws any doc="any other value on error";
  119. }
  120. method config_passive_mode doc="enable passive mode"
  121. {
  122. // parms
  123. use bool enable doc="flag if enabled or disabled";
  124. }
  125. method config_unencrypted_subject doc="disable subject encryption"
  126. {
  127. // parms
  128. use bool enable doc="flag if enabled or disabled";
  129. }
  130. method config_use_only_own_private_keys doc="enable passive mode"
  131. {
  132. // parms
  133. use bool enable doc="flag if enabled or disabled";
  134. }
  135. method config_service_log doc="log more for service purposes"
  136. {
  137. // parms
  138. use bool enable doc="flag if enabled or disabled";
  139. }
  140. method config_cipher_suite doc="cipher suite being used when encrypting"
  141. {
  142. // parms
  143. use suite cipher_suite doc="cipher suite to use";
  144. // exceptions
  145. throws cannot_config
  146. doc="""
  147. configuration failed; falling back to default. the default
  148. ciphersuite for a crypt tech implementation is implementation
  149. defined.
  150. """;
  151. throws illegal_value doc="illegal parameter values";
  152. }
  153. method log_event
  154. doc="""
  155. log a user defined event defined by UTF-8 encoded strings into
  156. management log.
  157. """
  158. {
  159. // parms
  160. use string title doc="string with event name";
  161. use string entity doc="string with name of entity which is logging";
  162. use string description doc="string with long description for event or NULL if omitted";
  163. use string comment doc="string with user defined comment or NULL if omitted";
  164. // exceptions
  165. throws illegal_value doc="illegal parameter values";
  166. }
  167. method get_default own_userid doc="get the user_id of the own user"
  168. {
  169. // parms
  170. create string userid
  171. doc="""
  172. own user id (if it exists). userid will be NULL if not found; otherwise,
  173. returned string belongs to the caller.
  174. """;
  175. // exceptions
  176. throws cannot_find_identity doc="no own_user found in the DB";
  177. throws unknown_error
  178. doc="""
  179. results were returned, but no ID found (no reason this
  180. should ever occur).
  181. """;
  182. throws illegal_value doc="illegal parameter value";
  183. throws out_of_memory doc="out of memory";
  184. }
  185. method mark_as_compromised doc="mark key in trust db as compromised"
  186. {
  187. // parms
  188. use hash fpr doc="fingerprint of key to mark";
  189. // exceptions
  190. throws illegal_value doc="illegal parameter value";
  191. throws cannot_set_trust:
  192. }
  193. method mark_as_compromized doc="deprecated to fix misspelling. Please move to mark_as_compromised"
  194. method import_key_with_fpr_return
  195. doc="""
  196. import keys from data, return optional list of fprs imported
  197. """;
  198. {
  199. // parms
  200. use string key_data doc="key data, i.e. ASCII armored OpenPGP key";
  201. use size_t size doc="amount of data to handle";
  202. create identity_list private_keys
  203. doc="""
  204. list of identities containing the private keys that have been imported. Private_keys
  205. and imported_keys can be left NULL, it is then ignored.
  206. *** THIS IS THE ACTUAL FUNCTION IMPLEMENTED BY CRYPTOTECH "import_key" ***
  207. """;
  208. create identity_list imported keys doc="if non-NULL, list of actual keys imported"
  209. create identity_list changed_public_keys
  210. doc="""
  211. if non-NULL AND imported_keys is non-NULL: bitvector - corresponds to the first
  212. 64 keys imported. If nth bit is set, import changed a key corresponding to the nth
  213. element in imported keys (i.e. key was in DB and was changed by import).
  214. """;
  215. // exceptions
  216. throws out_of_memory doc="out of memory";
  217. throws illegal_value
  218. doc="""
  219. there is no key data to import, or imported keys was NULL and changed_public_keys
  220. was not.
  221. """;
  222. }
  223. method export_key doc="export ascii armored key"
  224. {
  225. // parms
  226. use hash fpr doc="fingerprint of key";
  227. create string key_data
  228. doc="""
  229. ASCII armored OpenPGP key. The key_data goes to the ownership of the
  230. caller. The caller is responsible to free() it (on Windoze use pEp_free())
  231. """;
  232. return size_t size doc="amount of data to handle";
  233. // exceptions
  234. throws out_of_memory doc="out of memory";
  235. throws key_not_found doc="key not found";
  236. throws illegal_value doc="illegal parameter value";
  237. }
  238. method export_secret_key doc="export secret key ascii armored"
  239. {
  240. // parms
  241. use hash fpr doc="fingerprint of key, at least 16 hex digits";
  242. create string key_data
  243. doc="""
  244. ASCII armored OpenPGP secret key. The key_data goes to the ownership of the
  245. caller. The caller is responsible to free() it (on Windoze use pEp_free()).
  246. beware of leaking secret key data - overwrite it in memory after use!
  247. """;
  248. return size_t size doc="amount of data to handle";
  249. // exceptions
  250. throws out_of_memory doc="out of memory";
  251. throws key_not_found doc="key not found";
  252. throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)";
  253. throws illegal_value doc="illegal parameter value";
  254. }
  255. method export_secrect_key doc="deprecated misspelled function. Please replace with export_secret_key"
  256. method get_crashdump_log doc="get the last log messages out"
  257. {
  258. // parms
  259. use int maxlines doc="maximum number of lines (0 for default)";
  260. create string logdata
  261. doc="""
  262. logdata as string in double quoted CSV format
  263. column1 is title
  264. column2 is entity
  265. column3 is description
  266. column4 is comment
  267. """;
  268. // exceptions
  269. throws out_of_memory doc="out of memory";
  270. throws illegal_value doc="illegal parameter value";
  271. throws unknown_error;
  272. }
  273. method get_languagelist doc="get the list of languages"
  274. {
  275. //parms
  276. create string language
  277. doc="""
  278. languages as string in double quoted CSV format
  279. column 1 is the ISO 639-1 language code
  280. column 2 is the name of the language
  281. """;
  282. // exceptions
  283. throws out_of_memory doc="out of memory";
  284. throws illegal_value doc="illegal parameter value";
  285. throws unknown_error;
  286. }
  287. method get_phrase doc="get phrase in a dedicated language through i18n"
  288. {
  289. // parms
  290. use string lang doc="string with ISO 639-1 language code";
  291. use int phrase_id doc="id of phrase in i18n";
  292. create string phrase doc="phrase as UTF-8 string";
  293. // exceptions
  294. throws out_of_memory doc="out of memory";
  295. throws illegal_value doc="illegal parameter value";
  296. throws unknown_db_error:
  297. throws phrase_not_found;
  298. }
  299. method get_engine_version
  300. doc="""
  301. returns the current version of pEpEngine (this is different
  302. from the pEp protocol version!).
  303. """
  304. {
  305. // parms doc="none"
  306. // exceptions
  307. throws engine_version;
  308. }
  309. method is_pEp_user
  310. doc="""
  311. returns true if the USER corresponding to this identity has been listed
  312. in the *person* table as a pEp user.
  313. """
  314. {
  315. // parms
  316. use identity ident
  317. doc="""
  318. identity containing the user_id to check (this is the only part of
  319. the struct we require to be set).
  320. """;
  321. return bool is_pEp
  322. doc="""
  323. boolean pointer - will return true or false by reference with respect
  324. to whether or not user is a known pEp user
  325. """;
  326. // exceptions
  327. throws illegal_value doc="if no user_id in input";
  328. throws cannot_find_person doc="if user_id doesn't exist";
  329. }
  330. method per_user_directory doc="returns the directory for pEp management db"
  331. {
  332. // exceptions
  333. throws char* doc="path to actual per user directory";
  334. throws NULL doc="on failure";
  335. }
  336. method per_machine_directory doc="returns the directory for pEp system db"
  337. {
  338. // exceptions
  339. throws char* doc="path to actual per machine directory";
  340. throws NULL doc="on failure";
  341. }
  342. }