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.

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