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.

419 lines
11 KiB

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