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.

747 lines
27 KiB

  1. ### Detailed Function reference for the p≡p JSON Server Adapter. Version “(38) Frankenberg”, API version 0.15.0 ###
  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, StringList extra, 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. extra (in) extra keys for encryption
  35. mime_ciphertext (out) encrypted, encoded message
  36. enc_format (in) encrypted format
  37. flags (in) flags to set special encryption features
  38. return value:
  39. PEP_STATUS_OK if everything worked
  40. PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
  41. PEP_CANNOT_CREATE_TEMP_FILE
  42. if there are issues with temp files; in
  43. this case errno will contain the underlying
  44. error
  45. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  46. caveat:
  47. the encrypted, encoded mime text will go to the ownership of the caller; mimetext
  48. will remain in the ownership of the caller
  49. ```
  50. ##### MIME_decrypt_message(String mimetext, Integer size, String⇑ mime_plaintext, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇕ flags, String⇑ modified_src)
  51. decrypt a MIME message, with MIME output
  52. ```
  53. parameters:
  54. mimetext (in) MIME encoded text to decrypt
  55. size (in) size of mime text to decode (in order to decrypt)
  56. mime_plaintext (out) decrypted, encoded message
  57. keylist (out) stringlist with keyids
  58. rating (out) rating for the message
  59. flags (inout) flags to signal special decryption features
  60. modified_src (out) modified source string, if decrypt had reason to change it
  61. return value:
  62. decrypt status if everything worked with MIME encode/decode,
  63. the status of the decryption is returned
  64. (PEP_STATUS_OK or decryption error status)
  65. PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
  66. PEP_CANNOT_CREATE_TEMP_FILE
  67. if there are issues with temp files; in
  68. this case errno will contain the underlying
  69. error
  70. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  71. flag values:
  72. in:
  73. PEP_decrypt_flag_untrusted_server
  74. used to signal that decrypt function should engage in behaviour
  75. specified for when the server storing the source is untrusted.
  76. out:
  77. PEP_decrypt_flag_own_private_key
  78. private key was imported for one of our addresses (NOT trusted
  79. or set to be used - handshake/trust is required for that)
  80. PEP_decrypt_flag_src_modified
  81. indicates that the modified_src field should contain a modified
  82. version of the source, at the moment always as a result of the
  83. input flags.
  84. PEP_decrypt_flag_consume
  85. used by sync
  86. PEP_decrypt_flag_ignore
  87. used by sync
  88. caveat:
  89. the decrypted, encoded mime text will go to the ownership of the caller; mimetext
  90. will remain in the ownership of the caller
  91. ```
  92. ##### startKeySync()
  93. Start Key Synchronization for the current session.
  94. ##### stopKeySync()
  95. Stop Key Synchronization for the current session.
  96. ##### encrypt_message(Message src, StringList extra_keys, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
  97. encrypt message in memory
  98. ```
  99. parameters:
  100. src (in) message to encrypt
  101. extra_keys (in) extra keys for encryption
  102. dst (out) pointer to new encrypted message or NULL on failure
  103. enc_format (in) encrypted format
  104. flags (in) flags to set special encryption features
  105. return value:
  106. PEP_STATUS_OK on success
  107. PEP_KEY_NOT_FOUND at least one of the receipient keys
  108. could not be found
  109. PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  110. an ambiguous name
  111. PEP_GET_KEY_FAILED cannot retrieve key
  112. PEP_UNENCRYPTED no recipients with usable key,
  113. message is left unencrypted,
  114. and key is attached to it
  115. ```
  116. ##### encrypt_message_and_add_priv_key( Message src, Message⇑ dst, String to_fingerprint, PEP_enc_format enc_format, Integer flags)
  117. encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)
  118. ```
  119. parameters:
  120. session (in) session handle
  121. src (in) message to encrypt
  122. dst (out) pointer to new encrypted message or NULL if no
  123. encryption could take place
  124. to_fpr fingerprint of the recipient key to which the private key
  125. should be encrypted
  126. enc_format (in) encrypted format
  127. flags (in) flags to set special encryption features
  128. return value:
  129. PEP_STATUS_OK on success
  130. PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  131. an ambiguous name
  132. PEP_UNENCRYPTED on demand or no recipients with usable
  133. key, is left unencrypted, and key is
  134. attached to it
  135. caveat:
  136. the ownershop of src remains with the caller
  137. the ownership of dst goes to the caller
  138. ```
  139. ##### encrypt_message_for_self(Identity target_id, Message src, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
  140. encrypt message in memory for user's identity only,
  141. ignoring recipients and other identities from
  142. the message.
  143. ```
  144. parameters:
  145. target_id (in) self identity this message should be encrypted for
  146. src (in) message to encrypt
  147. dst (out) pointer to new encrypted message or NULL on failure
  148. enc_format (in) encrypted format
  149. flags (in) flags to set special encryption features
  150. return value: (FIXME: This may not be correct or complete)
  151. PEP_STATUS_OK on success
  152. PEP_KEY_NOT_FOUND at least one of the receipient keys
  153. could not be found
  154. PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  155. an ambiguous name
  156. PEP_GET_KEY_FAILED cannot retrieve key
  157. ```
  158. *Caveat:* message is NOT encrypted for identities other than the target_id (and then,
  159. only if the target_id refers to self!)
  160. ##### decrypt_message(Message⇕ src, Message⇑ dst, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇕ flags)
  161. decrypt message in memory
  162. ```
  163. parameters:
  164. src (inout) message to decrypt
  165. dst (out) pointer to new decrypted message or NULL on failure
  166. keylist (out) stringlist with keyids
  167. rating (out) rating for the message
  168. flags (inout) flags to signal special decryption features
  169. return value:
  170. error status
  171. or PEP_DECRYPTED if message decrypted but not verified
  172. or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
  173. verified) but a reencryption operation is expected by the caller
  174. and failed
  175. or PEP_STATUS_OK on success
  176. flag values:
  177. in:
  178. PEP_decrypt_flag_untrusted_server
  179. used to signal that decrypt function should engage in behaviour
  180. specified for when the server storing the source is untrusted
  181. out:
  182. PEP_decrypt_flag_own_private_key
  183. private key was imported for one of our addresses (NOT trusted
  184. or set to be used - handshake/trust is required for that)
  185. PEP_decrypt_flag_src_modified
  186. indicates that the src object has been modified. At the moment,
  187. this is always as a direct result of the behaviour driven
  188. by the input flags. This flag is the ONLY value that should be
  189. relied upon to see if such changes have taken place.
  190. PEP_decrypt_flag_consume
  191. used by sync
  192. PEP_decrypt_flag_ignore
  193. used by sync
  194. caveat:
  195. the ownership of src remains with the caller - however, the contents
  196. might be modified (strings freed and allocated anew or set to NULL,
  197. etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
  198. is set.
  199. the ownership of dst goes to the caller
  200. the ownership of keylist goes to the caller
  201. if src is unencrypted this function returns PEP_UNENCRYPTED and sets
  202. dst to NULL
  203. ```
  204. ##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
  205. get rating for an outgoing message
  206. ```
  207. parameters:
  208. msg (in) message to get the rating for
  209. rating (out) rating for the message
  210. return value:
  211. error status or PEP_STATUS_OK on success
  212. caveat:
  213. msg->from must point to a valid pEp_identity
  214. msg->dir must be PEP_dir_outgoing
  215. ```
  216. ##### re_evaluate_message_rating(Message msg, StringList keylist, PEP_rating enc_status, PEP_rating⇑ rating)
  217. re-evaluate already decrypted message rating
  218. ```
  219. parameters:
  220. msg (in) message to get the rating for
  221. keylist (in) decrypted message recipients keys fpr
  222. enc_status (in) original rating for the decrypted message
  223. rating (out) rating for the message
  224. return value:
  225. PEP_ILLEGAL_VALUE if decrypted message doesn't contain
  226. X-EncStatus optional field and x_enc_status is
  227. pEp_rating_udefined
  228. or if decrypted message doesn't contain
  229. X-Keylist optional field and x_keylist is NULL
  230. PEP_OUT_OF_MEMORY if not enough memory could be allocated
  231. caveat:
  232. msg->from must point to a valid pEp_identity
  233. ```
  234. ##### identity_rating(Identity ident, PEP_rating⇑ rating)
  235. get rating for a single identity
  236. ```
  237. parameters:
  238. ident (in) identity to get the rating for
  239. rating (out) rating for the identity
  240. return value:
  241. error status or PEP_STATUS_OK on success
  242. ```
  243. ##### get_gpg_path(String⇑)
  244. get path of gpg binary.
  245. #### MIME message handling ####
  246. ##### mime_decode_message(String mime_message, Integer message_lenght, Message msg)
  247. #### pEp Engine Core API ####
  248. ##### get_trustwords(Identity id1, Identity id2, Language lang, String⇑ words, Integer⇑ wsize, Bool full)
  249. get full trustwords string for a *pair* of identities
  250. ```
  251. parameters:
  252. id1 (in) identity of first party in communication - fpr can't be NULL
  253. id2 (in) identity of second party in communication - fpr can't be NULL
  254. lang (in) C string with ISO 639-1 language code
  255. words (out) pointer to C string with all trustwords UTF-8 encoded,
  256. separated by a blank each
  257. NULL if language is not supported or trustword
  258. wordlist is damaged or unavailable
  259. wsize (out) length of full trustwords string
  260. full (in) if true, generate ALL trustwords for these identities.
  261. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
  262. subset in next version)
  263. return value:
  264. PEP_STATUS_OK trustwords retrieved
  265. PEP_OUT_OF_MEMORY out of memory
  266. PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
  267. ```
  268. ##### get_languagelist(String⇑ languages)
  269. get the list of languages
  270. ```
  271. parameters:
  272. languages (out) languages as string in double quoted CSV format
  273. column 1 is the ISO 639-1 language code
  274. column 2 is the name of the language
  275. ```
  276. ##### is_pep_user(Identity id, Bool⇑ ia_pwp)
  277. returns true if the USER corresponding to this identity has been listed in the *person* table as a pEp user
  278. ```
  279. parameters:
  280. identity (in) - identity containing the user_id to check (this is
  281. the only part of the struct we require to be set)
  282. is_pep (out) - boolean pointer - will return true or false by
  283. reference with respect to whether or not user is
  284. a known pep user
  285. ```
  286. ##### config_passive_mode(Bool enable)
  287. enable passive mode
  288. * parameters: enable (in) flag if enabled or disabled
  289. ##### config_unencrypted_subject(Bool enable)
  290. disable subject encryption
  291. * parameters: enable (in) flag if enabled or disabled
  292. #### Identity Management API ####
  293. ##### get_identity(String address, String user_id, Identity⇑ identity)
  294. get identity information
  295. ```
  296. parameters:
  297. address (in) string with communication address, UTF-8 encoded
  298. user_id (in) unique string to identify person that identity is refering to
  299. identity (out) pEp_identity structure with results or NULL if failure
  300. ```
  301. ##### set_identity(Identity)
  302. set identity information
  303. ```
  304. parameters:
  305. identity (in) pEp_identity structure
  306. return value:
  307. PEP_STATUS_OK = 0 encryption and signing succeeded
  308. PEP_CANNOT_SET_PERSON writing to table person failed
  309. PEP_CANNOT_SET_PGP_KEYPAIR writing to table pgp_keypair failed
  310. PEP_CANNOT_SET_IDENTITY writing to table identity failed
  311. PEP_COMMIT_FAILED SQL commit failed
  312. PEP_KEY_BLACKLISTED Key blacklisted, cannot set identity
  313. caveat:
  314. address, fpr, user_id and username must be given
  315. ```
  316. ##### mark_as_comprimized(String fpr)
  317. mark key in trust db as compromized
  318. * parameters: fpr (in) fingerprint of key to mark
  319. ##### identity_rating(Identity ident, PEP_rating⇑ rating)
  320. get rating for a single identity
  321. ```
  322. parameters:
  323. ident (in) identity to get the rating for
  324. rating (out) rating for the identity
  325. return value:
  326. error status or PEP_STATUS_OK on success
  327. ```
  328. ##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
  329. get rating for an outgoing message
  330. ```
  331. parameters:
  332. msg (in) message to get the rating for
  333. rating (out) rating for the message
  334. return value:
  335. error status or PEP_STATUS_OK on success
  336. caveat:
  337. msg->from must point to a valid pEp_identity
  338. msg->dir must be PEP_dir_outgoing
  339. ```
  340. ##### set_identity_flags(Identity⇕ identity, Integer flags)
  341. update identity flags on existing identity
  342. ```
  343. parameters:
  344. identity (in,out) pointer to pEp_identity structure
  345. flags (in) new value for flags
  346. return value:
  347. PEP_STATUS_OK = 0 encryption and signing succeeded
  348. PEP_CANNOT_SET_IDENTITY update of identity failed
  349. caveat:
  350. address and user_id must be given in identity
  351. ```
  352. ##### unset_identity_flags(Identity⇕ identity, Integer flags)
  353. update identity flags on existing identity
  354. ```
  355. parameters:
  356. identity (in,out) pointer to pEp_identity structure
  357. flags (in) new value for flags
  358. return value:
  359. PEP_STATUS_OK = 0 encryption and signing succeeded
  360. PEP_CANNOT_SET_IDENTITY update of identity failed
  361. caveat:
  362. address and user_id must be given in identity
  363. ```
  364. #### Low level Key Management API ####
  365. ##### generate_keypair(Identity⇕ identity)
  366. generate a new key pair and add it to the key ring
  367. ```
  368. parameters:
  369. identity (inout) pEp_identity structure
  370. return value:
  371. PEP_STATUS_OK = 0 encryption and signing succeeded
  372. PEP_ILLEGAL_VALUE illegal values for identity fields given
  373. PEP_CANNOT_CREATE_KEY key engine is on strike
  374. caveat:
  375. address and username fields must be set to UTF-8 strings
  376. the fpr field must be set to NULL
  377. ```
  378. ##### delete_keypair(String fpr)
  379. delete a public key or a key pair from the key ring
  380. ```
  381. parameters:
  382. fpr (in) string with key id or fingerprint of the public key
  383. return value:
  384. PEP_STATUS_OK = 0 key was successfully deleted
  385. PEP_KEY_NOT_FOUND key not found
  386. PEP_ILLEGAL_VALUE not a valid key id or fingerprint
  387. PEP_KEY_HAS_AMBIG_NAME fpr does not uniquely identify a key
  388. PEP_OUT_OF_MEMORY out of memory
  389. ```
  390. ##### import_key(String key_data, Integer size, IdentityList⇑ private_keys)
  391. import key from data
  392. ```
  393. parameters:
  394. key_data (in) key data, i.e. ASCII armored OpenPGP key
  395. size (in) amount of data to handle
  396. private_keys (out) list of private keys that have been imported
  397. return value:
  398. PEP_STATUS_OK = 0 key was successfully imported
  399. PEP_OUT_OF_MEMORY out of memory
  400. PEP_ILLEGAL_VALUE there is no key data to import
  401. ```
  402. ##### export_key(String fpr, String⇑ key_data, Integer⇑ size)
  403. export ascii armored key
  404. ```
  405. parameters:
  406. fpr (in) key id or fingerprint of key
  407. key_data (out) ASCII armored OpenPGP key
  408. size (out) amount of data to handle
  409. return value:
  410. PEP_STATUS_OK = 0 key was successfully exported
  411. PEP_OUT_OF_MEMORY out of memory
  412. PEP_KEY_NOT_FOUND key not found
  413. ```
  414. ##### find_keys(String pattern, StringList⇑ keylist)
  415. find keys in keyring
  416. ```
  417. parameters:
  418. pattern (in) key id, user id or address to search for as UTF-8 string
  419. keylist (out) list of fingerprints found or NULL on error
  420. ```
  421. ##### get_trust(Identity⇕ identity)
  422. get the trust level a key has for a person
  423. ```
  424. parameters:
  425. identity (inout) user_id and fpr to check as UTF-8 strings (in)
  426. user_id and comm_type as result (out)
  427. ```
  428. This function modifies the given identity struct; the struct remains in
  429. the ownership of the caller.
  430. If the trust level cannot be determined identity->comm_type is set
  431. to PEP_ct_unknown.
  432. ##### own_key_is_listed(String fpr, Bool⇑ listed)
  433. returns true id key is listed as own key
  434. ```
  435. parameters:
  436. fpr (in) fingerprint of key to test
  437. listed (out) flags if key is own
  438. ```
  439. ##### own_identities_retrieve(IdentityList⇑ own_identities)
  440. retrieve all own identities
  441. ```
  442. parameters:
  443. own_identities (out) list of own identities
  444. ```
  445. ##### set_own_key( Identity⇕ id, String fpr)
  446. mark key as own key
  447. ```
  448. parameters:
  449. me (inout) own identity this key is used for
  450. fpr (in) fingerprint of the key to mark as own key
  451. ```
  452. ##### undo_last_mistrust()
  453. reset identity and trust status for the last`identity in this session marked
  454. as mistrusted to their cached values from the time of mistrust
  455. ```
  456. parameters:
  457. (none)
  458. return value:
  459. PEP_STATUS_OK if identity and trust were successfully restored.
  460. Otherwise, error status from attempts to set.
  461. caveat:
  462. only works for this session, and only once. cache is invalidated
  463. upon use.
  464.   WILL NOT WORK ON MISTRUSTED OWN KEY
  465. ```
  466. ##### myself(Identity⇕ identity)
  467. ensures that the own identity is being complete
  468. ```
  469. parameters:
  470. identity (inout) identity of local user. At least .address, .username, .user_id must be set.
  471. return value:
  472. PEP_STATUS_OK if identity could be completed or was already complete, any other value on error
  473. caveat:
  474. This function generates a keypair on demand; because it's synchronous
  475. it can need a decent amount of time to return.
  476. If you need to do this asynchronous, you need to return an identity
  477. with retrieve_next_identity() where pEp_identity.me is true.
  478. ```
  479. ##### update_identity(Identity⇕)
  480. update identity information
  481. ```
  482. parameters:
  483. identity (inout) identity information of communication partner
  484. (identity->fpr is OUT ONLY)
  485. return value:
  486. PEP_STATUS_OK if identity could be updated,
  487. PEP_GET_KEY_FAILED for own identity that must be completed (myself())
  488. any other value on error
  489. caveat:
  490. if this function returns PEP_ct_unknown or PEP_ct_key_expired in
  491. identity->comm_type, the caller must insert the identity into the
  492. asynchronous management implementation, so retrieve_next_identity()
  493. will return this identity later
  494. at least identity->address must be a non-empty UTF-8 string as input
  495. update_identity() never writes flags; use set_identity_flags() for
  496. writing
  497. this function NEVER reads the incoming fpr, only writes to it.
  498. ```
  499. ##### trust_personal_key(Identity)
  500. mark a key as trusted with a person
  501. ```
  502. parameters:
  503. ident (in) person and key to trust in
  504. caveat:
  505. the fields user_id, address and fpr must be supplied
  506. ```
  507. ##### key_mistrusted(Identity)
  508. mark key as being compromized
  509. ```
  510. parameters:
  511. ident (in) person and key which was compromized
  512. ```
  513. ##### key_reset_trust(Identity)
  514. undo trust_personal_key and key_mistrusted() for keys we don't own
  515. ```
  516. parameters:
  517. ident (in) person and key which was compromized
  518. ```
  519. ##### least_trust(String fpr, PEP_comm_type⇑ comm_type)
  520. get the least known trust level for a key in the database
  521. ```
  522. parameters:
  523. fpr (in) fingerprint of key to check
  524. comm_type (out) least comm_type as result (out)
  525. ```
  526. If the trust level cannot be determined comm_type is set to PEP_ct_unknown.
  527. ##### get_key_rating(String fpr, PEP_comm_type⇑ comm_type)
  528. get the rating a bare key has
  529. ```
  530. parameters:
  531. fpr (in) unique identifyer for key as UTF-8 string
  532. comm_type (out) key rating
  533. ```
  534. Iif an error occurs, *comm_type is set to PEP_ct_unknown and an error is returned
  535. ##### renew_key(String fpr, Timestamp ts)
  536. renew an expired key
  537. ```
  538. parameters:
  539. fpr (in) ID of key to renew as UTF-8 string
  540. ts (in) timestamp when key should expire or NULL for default
  541. ```
  542. ##### revoke(String fpr, String reason)
  543. revoke a key
  544. ```
  545. parameters:
  546. fpr (in) ID of key to revoke as UTF-8 string
  547. reason (in) text with reason for revoke as UTF-8 string
  548. or NULL if reason unknown
  549. caveat:
  550. reason text must not include empty lines
  551. this function is meant for internal use only; better use
  552. key_mistrusted() of keymanagement API
  553. ```
  554. ##### key_expired(String fpr, Integer when, Bool⇑ expired)
  555. flags if a key is already expired
  556. ```
  557. parameters:
  558. fpr (in) ID of key to check as UTF-8 string
  559. when (in) UTC time of when should expiry be considered
  560. expired (out) flag if key expired
  561. ```
  562. #### from blacklist.h & OpenPGP_compat.h ####
  563. ##### blacklist_add(String fpr)
  564. add to blacklist
  565. * parameters: fpr (in) fingerprint of key to blacklist
  566. ##### blacklist_delete(String fpr)
  567. delete from blacklist
  568. * parameters: fpr (in) fingerprint of key to blacklist
  569. ##### blacklist_is_listed(String fpr, Bool⇑ listed)
  570. is_listed in blacklist
  571. ```
  572. parameters:
  573. session (in) session to use
  574. fpr (in) fingerprint of key to blacklist
  575. listted (out)
  576. ```
  577. ##### blacklist_retrieve(StringList⇑ blacklist)
  578. retrieve full blacklist of key fingerprints
  579. * parameters: blacklist (out) copy of blacklist
  580. ##### OpenPGP_list_keyinfo(String search_pattern, StringPairList⇑ keyinfo_list)
  581. get a key/UID list for pattern matches in keyring ("" to return entire keyring), filtering out revoked keys in the results
  582. ```
  583. parameters:
  584. search_pattern (in) search pattern - either an fpr, or something within the UID, or "" for all keys
  585. keyinfo_list (out) a key/value pair list for each key / UID combination
  586. ```
  587. #### Event Listener & Results ####
  588. ##### registerEventListener(String address, Integer port, String security_context)
  589. Register an address/port pair where a JSON-RPC call shall be made to, when the Engine wants to call the client application.
  590. These RPC calls are authenticated with a security_context parameter that is given to all calls (and can be different from the security_context
  591. that is used for calls from the client to the JSON Server Adapter).
  592. Currently there are two functions that can be called:
  593. * messageToSend( Message )
  594. * notifyHandshake( Identity self, Identity partner, sync_handshake_signal sig )
  595. ##### unregisterEventListener(String address, Integer port, String security_context)
  596. Unregister a previous registered JSON-RPC listener.
  597. ##### deliverHandshakeResult(Identity partner, PEP_sync_handshake_result result)
  598. give the result of the handshake dialog back to the Engine
  599. ```
  600. parameters:
  601. partner (in) the parther of the handshake
  602. result (in) handshake result
  603. ```
  604. #### Other ####
  605. ##### serverVersion()
  606. Returns a struct with SemVer-compatible ABI version, the codename of the
  607. JSON Adapter version etc.
  608. ##### version()
  609. Returns a codename for the current JSON Server Adapter's version.
  610. ##### shutdown()
  611. shutdown the JSON Adapter