p≡p JSON adapter
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.

664 lines
23 KiB

  1. ### Detailed Function reference for the p≡p JSON Server Adapter. Version “(29) Wenden” ###
  2. Output parameters are denoted by a **⇑** , InOut parameters are denoted by a **⇕** after the parameter type.
  3. Nota bene: This list was created manually from the "authorative API description" and might be outdated.
  4. #### Message API ####
  5. ##### MIME_encrypt_message( String mimetext, Integer size, StringList extra, String⇑ mime_ciphertext, PEP_enc_format env_format, Integer flags)
  6. encrypt a MIME message, with MIME output
  7. ```
  8. parameters:
  9. mimetext (in) MIME encoded text to encrypt
  10. size (in) size of input mime text
  11. extra (in) extra keys for encryption
  12. mime_ciphertext (out) encrypted, encoded message
  13. enc_format (in) encrypted format
  14. flags (in) flags to set special encryption features
  15. return value:
  16. PEP_STATUS_OK if everything worked
  17. PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
  18. PEP_CANNOT_CREATE_TEMP_FILE
  19. if there are issues with temp files; in
  20. this case errno will contain the underlying
  21. error
  22. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  23. ```
  24. *Caveat:* the encrypted, encoded mime text will go to the ownership of the caller; mimetext
  25. will remain in the ownership of the caller
  26. ##### MIME_encrypt_message_for_self(Identity target_id, String mimetext, Integer size, String⇑ mime_ciphertext, PEP_enc_format enc_format, Integer flags)
  27. encrypt MIME message for user's identity only, ignoring recipients and other identities from
  28. the message, with MIME output.
  29. ```
  30. parameters:
  31. target_id (in) self identity this message should be encrypted for
  32. mimetext (in) MIME encoded text to encrypt
  33. size (in) size of input mime text
  34. mime_ciphertext (out) encrypted, encoded message
  35. enc_format (in) encrypted format
  36. flags (in) flags to set special encryption features
  37. return value:
  38. PEP_STATUS_OK if everything worked
  39. PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
  40. PEP_CANNOT_CREATE_TEMP_FILE
  41. if there are issues with temp files; in
  42. this case errno will contain the underlying
  43. error
  44. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  45. ```
  46. ##### MIME_decrypt_message(String mimetext, Integer size, String⇑ mime_plaintext, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇑ flags)
  47. decrypt a MIME message, with MIME output
  48. ```
  49. parameters:
  50. mimetext (in) MIME encoded text to decrypt
  51. size (in) size of mime text to decode (in order to decrypt)
  52. mime_plaintext (out) decrypted, encoded message
  53. keylist (out) stringlist with keyids
  54. rating (out) rating for the message
  55. flags (out) flags to signal special decryption features
  56. return value:
  57. decrypt status if everything worked with MIME encode/decode,
  58. the status of the decryption is returned
  59. (PEP_STATUS_OK or decryption error status)
  60. PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
  61. PEP_CANNOT_CREATE_TEMP_FILE
  62. if there are issues with temp files; in
  63. this case errno will contain the underlying
  64. error
  65. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  66. ```
  67. ##### MIME_encrypt_message_ex(String, Integer, StringList, Bool, String⇑, PEP_enc_format, Integer )
  68. (deprecated)
  69. ##### MIME_decrypt_message_ex(String, Integer, Bool, String⇑, StringList⇑, PEP_rating⇑, Integer⇑ )
  70. (deprecated)
  71. ##### startKeySync()
  72. Start Key Synchronization for the current session.
  73. ##### stopKeySync()
  74. Stop Key Synchronization for the current session.
  75. ##### startKeyserverLookup()
  76. Start a global thread for Keyserver Lookup. This thread handles all keyserver communication for all sessions.
  77. ##### stopKeyserverLookup()
  78. Stop the global thread for Keyserver Lookup.
  79. ##### encrypt_message(Message src, StringList extra_keys, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
  80. encrypt message in memory
  81. ```
  82. parameters:
  83. src (in) message to encrypt
  84. extra_keys (in) extra keys for encryption
  85. dst (out) pointer to new encrypted message or NULL on failure
  86. enc_format (in) encrypted format
  87. flags (in) flags to set special encryption features
  88. return value:
  89. PEP_STATUS_OK on success
  90. PEP_KEY_NOT_FOUND at least one of the receipient keys
  91. could not be found
  92. PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  93. an ambiguous name
  94. PEP_GET_KEY_FAILED cannot retrieve key
  95. PEP_UNENCRYPTED no recipients with usable key,
  96. message is left unencrypted,
  97. and key is attached to it
  98. ```
  99. ##### encrypt_message_for_self(Identity target_id, Message src, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
  100. encrypt message in memory for user's identity only,
  101. ignoring recipients and other identities from
  102. the message.
  103. ```
  104. parameters:
  105. target_id (in) self identity this message should be encrypted for
  106. src (in) message to encrypt
  107. dst (out) pointer to new encrypted message or NULL on failure
  108. enc_format (in) encrypted format
  109. flags (in) flags to set special encryption features
  110. return value: (FIXME: This may not be correct or complete)
  111. PEP_STATUS_OK on success
  112. PEP_KEY_NOT_FOUND at least one of the receipient keys
  113. could not be found
  114. PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  115. an ambiguous name
  116. PEP_GET_KEY_FAILED cannot retrieve key
  117. ```
  118. *Caveat:* message is NOT encrypted for identities other than the target_id (and then,
  119. only if the target_id refers to self!)
  120. ##### decrypt_message(Message src, Message⇑ dst, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇑ flags)
  121. decrypt message in memory
  122. ```
  123. parameters:
  124. src (in) message to decrypt
  125. dst (out) pointer to new decrypted message or NULL on failure
  126. keylist (out) stringlist with keyids
  127. rating (out) rating for the message
  128. flags (out) flags to signal special decryption features
  129. return value:
  130. error status
  131. or PEP_DECRYPTED if message decrypted but not verified
  132. or PEP_STATUS_OK on success
  133. caveat:
  134. if src is unencrypted this function returns PEP_UNENCRYPTED and sets
  135. dst to NULL
  136. ```
  137. ##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
  138. get rating for an outgoing message
  139. ```
  140. parameters:
  141. msg (in) message to get the rating for
  142. rating (out) rating for the message
  143. return value:
  144. error status or PEP_STATUS_OK on success
  145. caveat:
  146. msg->from must point to a valid pEp_identity
  147. msg->dir must be PEP_dir_outgoing
  148. ```
  149. ##### re_evaluate_message_rating(Message msg, StringList keylist, PEP_rating enc_status, PEP_rating⇑ rating)
  150. re-evaluate already decrypted message rating
  151. ```
  152. parameters:
  153. msg (in) message to get the rating for
  154. keylist (in) decrypted message recipients keys fpr
  155. enc_status (in) original rating for the decrypted message
  156. rating (out) rating for the message
  157. return value:
  158. PEP_ILLEGAL_VALUE if decrypted message doesn't contain
  159. X-EncStatus optional field and x_enc_status is
  160. pEp_rating_udefined
  161. or if decrypted message doesn't contain
  162. X-Keylist optional field and x_keylist is NULL
  163. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  164. caveat:
  165. msg->from must point to a valid pEp_identity
  166. ```
  167. ##### identity_rating(Identity ident, PEP_rating⇑ rating)
  168. get rating for a single identity
  169. ```
  170. parameters:
  171. ident (in) identity to get the rating for
  172. rating (out) rating for the identity
  173. return value:
  174. error status or PEP_STATUS_OK on success
  175. ```
  176. ##### get_gpg_path(String⇑)
  177. get path of gpg binary.
  178. #### pEp Engine Core API ####
  179. ##### log_event(String title, String entity, String description, String comment)
  180. log a user defined event defined by UTF-8 encoded strings into management log
  181. parameters:
  182. title (in) C string with event name
  183. entity (in) C string with name of entity which is logging
  184. description (in) C string with long description for event or NULL if omitted
  185. comment (in) C string with user defined comment or NULL if omitted
  186. return value:
  187. PEP_STATUS_OK log entry created
  188. ```
  189. ##### get_trustwords(Identity id1, Identity id2, Language lang, String⇑ words, Integer⇑ wsize, Bool full)
  190. get full trustwords string for a *pair* of identities
  191. ``
  192. parameters:
  193. id1 (in) identity of first party in communication - fpr can't be NULL
  194. id2 (in) identity of second party in communication - fpr can't be NULL
  195. lang (in) C string with ISO 639-1 language code
  196. words (out) pointer to C string with all trustwords UTF-8 encoded,
  197. separated by a blank each
  198. NULL if language is not supported or trustword
  199. wordlist is damaged or unavailable
  200. wsize (out) length of full trustwords string
  201. full (in) if true, generate ALL trustwords for these identities.
  202. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  203. subset in next version)
  204. return value:
  205. PEP_STATUS_OK trustwords retrieved
  206. PEP_OUT_OF_MEMORY out of memory
  207. PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
  208. ```
  209. ##### get_languagelist(String⇑ languages)
  210. get the list of languages
  211. ```
  212. parameters:
  213. languages (out) languages as string in double quoted CSV format
  214. column 1 is the ISO 639-1 language code
  215. column 2 is the name of the language
  216. ```
  217. ##### get_phrase(Language lang, Integer phrase_id, String⇑ phrase)
  218. get phrase in a dedicated language through i18n
  219. ``
  220. parameters:
  221. lang (in) C string with ISO 639-1 language code
  222. phrase_id (in) id of phrase in i18n
  223. phrase (out) phrase as UTF-8 string
  224. ```
  225. ##### get_engine_version()
  226. returns the current version of pEpEngine (this is different from the pEp protocol version!)
  227. * parameters: (none)
  228. * return_value: String containing the engine version string constant
  229. ##### config_passive_mode(Bool enable)
  230. enable passive mode
  231. * parameters: enable (in) flag if enabled or disabled
  232. ##### config_unencrypted_subject(Bool enable)
  233. disable subject encryption
  234. * parameters: enable (in) flag if enabled or disabled
  235. #### Identity Management API ####
  236. ##### get_identity(String address, String user_id, Identity⇑ identity)
  237. get identity information
  238. ```
  239. parameters:
  240. address (in) string with communication address, UTF-8 encoded
  241. user_id (in) unique string to identify person that identity is refering to
  242. identity (out) pEp_identity structure with results or NULL if failure
  243. ```
  244. ##### set_identity(Identity)
  245. set identity information
  246. ```
  247. parameters:
  248. identity (in) pEp_identity structure
  249. return value:
  250. PEP_STATUS_OK = 0 encryption and signing succeeded
  251. PEP_CANNOT_SET_PERSON writing to table person failed
  252. PEP_CANNOT_SET_PGP_KEYPAIR writing to table pgp_keypair failed
  253. PEP_CANNOT_SET_IDENTITY writing to table identity failed
  254. PEP_COMMIT_FAILED SQL commit failed
  255. PEP_KEY_BLACKLISTED Key blacklisted, cannot set identity
  256. caveat:
  257. address, fpr, user_id and username must be given
  258. ```
  259. ##### mark_as_comprimized(String fpr)
  260. mark key in trust db as compromized
  261. * parameters: fpr (in) fingerprint of key to mark
  262. ##### identity_rating(Identity ident, PEP_rating⇑ rating)
  263. get rating for a single identity
  264. ```
  265. parameters:
  266. ident (in) identity to get the rating for
  267. rating (out) rating for the identity
  268. return value:
  269. error status or PEP_STATUS_OK on success
  270. ```
  271. ##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
  272. get rating for an outgoing message
  273. ```
  274. parameters:
  275. msg (in) message to get the rating for
  276. rating (out) rating for the message
  277. return value:
  278. error status or PEP_STATUS_OK on success
  279. caveat:
  280. msg->from must point to a valid pEp_identity
  281. msg->dir must be PEP_dir_outgoing
  282. ```
  283. ##### set_identity_flags(Identity⇕ identity, Integer flags)
  284. update identity flags on existing identity
  285. ```
  286. parameters:
  287. identity (in,out) pointer to pEp_identity structure
  288. flags (in) new value for flags
  289. return value:
  290. PEP_STATUS_OK = 0 encryption and signing succeeded
  291. PEP_CANNOT_SET_IDENTITY update of identity failed
  292. caveat:
  293. address and user_id must be given in identity
  294. ```
  295. ##### unset_identity_flags(Identity⇕ identity, Integer flags)
  296. update identity flags on existing identity
  297. ```
  298. parameters:
  299. identity (in,out) pointer to pEp_identity structure
  300. flags (in) new value for flags
  301. return value:
  302. PEP_STATUS_OK = 0 encryption and signing succeeded
  303. PEP_CANNOT_SET_IDENTITY update of identity failed
  304. caveat:
  305. address and user_id must be given in identity
  306. ```
  307. #### Low level Key Management API ####
  308. ##### generate_keypair(Identity⇕ identity)
  309. generate a new key pair and add it to the key ring
  310. ```
  311. parameters:
  312. identity (inout) pEp_identity structure
  313. return value:
  314. PEP_STATUS_OK = 0 encryption and signing succeeded
  315. PEP_ILLEGAL_VALUE illegal values for identity fields given
  316. PEP_CANNOT_CREATE_KEY key engine is on strike
  317. caveat:
  318. address and username fields must be set to UTF-8 strings
  319. the fpr field must be set to NULL
  320. ```
  321. ##### delete_keypair(String fpr)
  322. delete a public key or a key pair from the key ring
  323. ```
  324. parameters:
  325. fpr (in) string with key id or fingerprint of the public key
  326. return value:
  327. PEP_STATUS_OK = 0 key was successfully deleted
  328. PEP_KEY_NOT_FOUND key not found
  329. PEP_ILLEGAL_VALUE not a valid key id or fingerprint
  330. PEP_KEY_HAS_AMBIG_NAME fpr does not uniquely identify a key
  331. PEP_OUT_OF_MEMORY out of memory
  332. ```
  333. ##### import_key(String key_data, Integer size, IdentityList⇑ private_keys)
  334. import key from data
  335. ```
  336. parameters:
  337. key_data (in) key data, i.e. ASCII armored OpenPGP key
  338. size (in) amount of data to handle
  339. private_keys (out) list of private keys that have been imported
  340. return value:
  341. PEP_STATUS_OK = 0 key was successfully imported
  342. PEP_OUT_OF_MEMORY out of memory
  343. PEP_ILLEGAL_VALUE there is no key data to import
  344. ```
  345. ##### export_key(String fpr, String⇑ key_data, Integer⇑ size)
  346. export ascii armored key
  347. ```
  348. parameters:
  349. fpr (in) key id or fingerprint of key
  350. key_data (out) ASCII armored OpenPGP key
  351. size (out) amount of data to handle
  352. return value:
  353. PEP_STATUS_OK = 0 key was successfully exported
  354. PEP_OUT_OF_MEMORY out of memory
  355. PEP_KEY_NOT_FOUND key not found
  356. ```
  357. ##### find_keys(String pattern, StringList⇑ keylist)
  358. find keys in keyring
  359. ```
  360. parameters:
  361. pattern (in) key id, user id or address to search for as UTF-8 string
  362. keylist (out) list of fingerprints found or NULL on error
  363. ```
  364. ##### get_trust(Identity⇕ identity)
  365. get the trust level a key has for a person
  366. ```
  367. parameters:
  368. identity (inout) user_id and fpr to check as UTF-8 strings (in)
  369. user_id and comm_type as result (out)
  370. ```
  371. This function modifies the given identity struct; the struct remains in
  372. the ownership of the caller.
  373. If the trust level cannot be determined identity->comm_type is set
  374. to PEP_ct_unknown.
  375. ##### own_key_is_listed(String fpr, Bool⇑ listed)
  376. returns true id key is listed as own key
  377. ```
  378. parameters:
  379. fpr (in) fingerprint of key to test
  380. listed (out) flags if key is own
  381. ```
  382. ##### own_identities_retrieve(IdentityList⇑ own_identities)
  383. retrieve all own identities
  384. ```
  385. parameters:
  386. own_identities (out) list of own identities
  387. ```
  388. ##### myself(Identity⇕ identity)
  389. ensures that the own identity is being complete
  390. ```
  391. parameters:
  392. identity (inout) identity of local user. At least .address, .username, .user_id must be set.
  393. return value:
  394. PEP_STATUS_OK if identity could be completed or was already complete, any other value on error
  395. caveat:
  396. This function generates a keypair on demand; because it's synchronous
  397. it can need a decent amount of time to return.
  398. If you need to do this asynchronous, you need to return an identity
  399. with retrieve_next_identity() where pEp_identity.me is true.
  400. ```
  401. ##### update_dentity(Identity⇕)
  402. update identity information
  403. ```
  404. parameters:
  405. identity (inout) identity information of communication partner
  406. (identity->fpr is OUT ONLY)
  407. return value:
  408. PEP_STATUS_OK if identity could be updated,
  409. PEP_GET_KEY_FAILED for own identity that must be completed (myself())
  410. any other value on error
  411. caveat:
  412. if this function returns PEP_ct_unknown or PEP_ct_key_expired in
  413. identity->comm_type, the caller must insert the identity into the
  414. asynchronous management implementation, so retrieve_next_identity()
  415. will return this identity later
  416. at least identity->address must be a non-empty UTF-8 string as input
  417. update_identity() never writes flags; use set_identity_flags() for
  418. writing
  419. this function NEVER reads the incoming fpr, only writes to it.
  420. ```
  421. ##### trust_personal_key(Identity)
  422. mark a key as trusted with a person
  423. ```
  424. parameters:
  425. ident (in) person and key to trust in
  426. caveat:
  427. the fields user_id, address and fpr must be supplied
  428. ```
  429. ##### key_mistrusted(Identity)
  430. mark key as being compromized
  431. ```
  432. parameters:
  433. ident (in) person and key which was compromized
  434. ```
  435. ##### key_reset_trust(Identity)
  436. undo trust_personal_key and key_mistrusted() for keys we don't own
  437. ```
  438. parameters:
  439. ident (in) person and key which was compromized
  440. ```
  441. ##### least_trust(String fpr, PEP_comm_type⇑ comm_type)
  442. get the least known trust level for a key in the database
  443. ```
  444. parameters:
  445. fpr (in) fingerprint of key to check
  446. comm_type (out) least comm_type as result (out)
  447. ```
  448. If the trust level cannot be determined comm_type is set to PEP_ct_unknown.
  449. ##### get_key_rating(String fpr, PEP_comm_type⇑ comm_type)
  450. get the rating a bare key has
  451. ```
  452. parameters:
  453. fpr (in) unique identifyer for key as UTF-8 string
  454. comm_type (out) key rating
  455. ```
  456. Iif an error occurs, *comm_type is set to PEP_ct_unknown and an error is returned
  457. ##### renew_key(String fpr, Timestamp ts)
  458. renew an expired key
  459. ```
  460. parameters:
  461. fpr (in) ID of key to renew as UTF-8 string
  462. ts (in) timestamp when key should expire or NULL for default
  463. ```
  464. ##### revoke(String fpr, String reason)
  465. revoke a key
  466. ```
  467. parameters:
  468. fpr (in) ID of key to revoke as UTF-8 string
  469. reason (in) text with reason for revoke as UTF-8 string
  470. or NULL if reason unknown
  471. caveat:
  472. reason text must not include empty lines
  473. this function is meant for internal use only; better use
  474. key_mistrusted() of keymanagement API
  475. ```
  476. ##### key_expired(String fpr, Integer when, Bool⇑ expired)
  477. flags if a key is already expired
  478. ```
  479. parameters:
  480. fpr (in) ID of key to check as UTF-8 string
  481. when (in) UTC time of when should expiry be considered
  482. expired (out) flag if key expired
  483. ```
  484. #### from blacklist.h & OpenPGP_compat.h ####
  485. ##### blacklist_add(String fpr)
  486. add to blacklist
  487. * parameters: fpr (in) fingerprint of key to blacklist
  488. ##### blacklist_delete(String fpr)
  489. delete from blacklist
  490. * parameters: fpr (in) fingerprint of key to blacklist
  491. ##### blacklist_is_listed(String fpr, Bool⇑ listed)
  492. is_listed in blacklist
  493. ```
  494. parameters:
  495. session (in) session to use
  496. fpr (in) fingerprint of key to blacklist
  497. listted (out)
  498. ```
  499. ##### blacklist_retrieve(StringList⇑ blacklist)
  500. retrieve full blacklist of key fingerprints
  501. * parameters: blacklist (out) copy of blacklist
  502. ##### OpenPGP_list_keyinfo(String search_pattern, StringPairList⇑ keyinfo_list)
  503. get a key/UID list for pattern matches in keyring ("" to return entire keyring), filtering out revoked keys in the results
  504. ```
  505. parameters:
  506. search_pattern (in) search pattern - either an fpr, or something within the UID, or "" for all keys
  507. keyinfo_list (out) a key/value pair list for each key / UID combination
  508. ```
  509. #### Event Listener & Results ####
  510. ##### registerEventListener(String address, Integer port, String security_context)
  511. Register an address/port pair where a JSON-RPC call shall be made to, when the Engine wants to call the client application.
  512. These RPC calls are authenticated with a security_context parameter that is given to all calls (and can be different from the security_context
  513. that is used for calls from the client to the JSON Server Adapter).
  514. Currently there are two functions that can be called:
  515. * messageToSend( Message )
  516. * notifyHandshake( Identity self, Identity partner, sync_handshake_signal sig )
  517. ##### unregisterEventListener(String address, Integer port, String security_context)
  518. Unregister a previous registered JSON-RPC listener.
  519. ##### deliverHandshakeResult(Identity partner, PEP_sync_handshake_result result)
  520. give the result of the handshake dialog back to the Engine
  521. ```
  522. parameters:
  523. partner (in) the parther of the handshake
  524. result (in) handshake result
  525. ```
  526. #### Other ####
  527. ##### version()
  528. Returns a codename for the current JSON Server Adapter's version.
  529. ##### apiVersion()
  530. Returns a numerical API version, currently the API version is 2.
  531. ##### getGpgEnvironment()
  532. Returns a struct holding 3 members
  533. * gnupg_path
  534. * gnupg_home environment variable, if set
  535. * gpg_agent_info environment variable, if set.