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.

683 lines
19 KiB

  1. /**
  2. * @file pEpEngine_internal.h
  3. * @brief Exposed internal functions and structures.
  4. * @license GNU General Public License 3.0 - see LICENSE.txt
  5. */
  6. #ifndef PEP_ENGINE_INTERNAL_H
  7. #define PEP_ENGINE_INTERNAL_H
  8. #ifdef __cplusplus
  9. extern "C" {
  10. #endif
  11. #include <stddef.h>
  12. #include <stdint.h>
  13. #include <stdbool.h>
  14. #include "dynamic_api.h"
  15. #include "stringlist.h"
  16. #include "stringpair.h"
  17. #include "labeled_int_list.h"
  18. #include "timestamp.h"
  19. /**
  20. * <!-- replace_identities_fpr() -->
  21. *
  22. * @brief TODO
  23. *
  24. * @param[in] session session handle
  25. * @param[in] old_fpr const char*
  26. * @param[in] new_fpr const char*
  27. *
  28. * @retval PEP_STATUS_OK
  29. * @retval PEP_CANNOT_SET_IDENTITY
  30. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  31. *
  32. */
  33. PEP_STATUS replace_identities_fpr(PEP_SESSION session,
  34. const char* old_fpr,
  35. const char* new_fpr);
  36. /**
  37. * <!-- set_trust() -->
  38. *
  39. * @brief TODO
  40. *
  41. * @param[in] session session handle
  42. * @param[in] identity pEp_identity*
  43. *
  44. * @retval PEP_STATUS_OK
  45. * @retval any other value on error
  46. */
  47. PEP_STATUS set_trust(PEP_SESSION session,
  48. pEp_identity* identity);
  49. /**
  50. * <!-- update_trust_for_fpr() -->
  51. *
  52. * @brief TODO
  53. *
  54. * @param[in] session session handle
  55. * @param[in] fpr const char*
  56. * @param[in] comm_type PEP_comm_type
  57. *
  58. *
  59. * @retval PEP_STATUS_OK
  60. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  61. * @retval PEP_CANNOT_SET_TRUST
  62. *
  63. */
  64. PEP_STATUS update_trust_for_fpr(PEP_SESSION session,
  65. const char* fpr,
  66. PEP_comm_type comm_type);
  67. /**
  68. * <!-- get_key_userids() -->
  69. *
  70. * @brief TODO
  71. *
  72. * @param[in] session session handle
  73. * @param[in] fpr const char*
  74. * @param[in] keylist stringlist_t**
  75. *
  76. */
  77. PEP_STATUS get_key_userids(
  78. PEP_SESSION session,
  79. const char* fpr,
  80. stringlist_t** keylist
  81. );
  82. /**
  83. * <!-- key_created() -->
  84. *
  85. * @brief Get creation date of a key
  86. *
  87. * @param[in] session session handle
  88. * @param[in] fpr fingerprint of key
  89. * @param[out] created date of creation
  90. *
  91. * @retval PEP_STATUS_OK
  92. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  93. *
  94. */
  95. PEP_STATUS key_created(
  96. PEP_SESSION session,
  97. const char *fpr,
  98. time_t *created
  99. );
  100. /**
  101. * <!-- find_private_keys() -->
  102. *
  103. * @brief Find keys in keyring
  104. *
  105. * @param[in] session session handle
  106. * @param[in] pattern fingerprint or address to search for as
  107. * UTF-8 string
  108. * @param[out] keylist list of fingerprints found or NULL on error
  109. *
  110. * @retval PEP_STATUS_OK
  111. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  112. *
  113. * @warning the ownerships of keylist isgoing to the caller
  114. * the caller must use free_stringlist() to free it
  115. *
  116. */
  117. PEP_STATUS find_private_keys(PEP_SESSION session, const char* pattern,
  118. stringlist_t **keylist);
  119. /**
  120. * <!-- _generate_keypair() -->
  121. *
  122. * @brief TODO
  123. *
  124. * @param[in] session session handle
  125. * @param[in] identity pEp_identity*
  126. * @param[in] suppress_event bool
  127. *
  128. * @retval PEP_STATUS_OK encryption and signing succeeded
  129. * @retval PEP_ILLEGAL_VALUE illegal values for identity fields given
  130. * @retval PEP_CANNOT_CREATE_KEY key engine is on strike
  131. * @retval PEP_OUT_OF_MEMORY out of memory
  132. * @retval any other value on error
  133. *
  134. */
  135. PEP_STATUS _generate_keypair(PEP_SESSION session,
  136. pEp_identity *identity,
  137. bool suppress_event);
  138. // This is used internally when there is a temporary identity to be retrieved
  139. // that may not yet have an FPR attached. See get_identity() for functionality,
  140. // params and caveats.
  141. /**
  142. * <!-- get_identity_without_trust_check() -->
  143. *
  144. * @brief TODO
  145. *
  146. * @param[in] session session handle
  147. * @param[in] address const char*
  148. * @param[in] user_id const char*
  149. * @param[in] identity pEp_identity**
  150. *
  151. * @retval PEP_STATUS_OK
  152. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  153. * @retval PEP_CANNOT_FIND_IDENTITY
  154. * @retval PEP_OUT_OF_MEMORY out of memory
  155. *
  156. */
  157. PEP_STATUS get_identity_without_trust_check(
  158. PEP_SESSION session,
  159. const char *address,
  160. const char *user_id,
  161. pEp_identity **identity
  162. );
  163. /**
  164. * <!-- get_identities_by_address() -->
  165. *
  166. * @brief TODO
  167. *
  168. * @param[in] session session handle
  169. * @param[in] address const char*
  170. * @param[in] id_list identity_list**
  171. *
  172. * @retval PEP_STATUS_OK
  173. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  174. * @retval PEP_CANNOT_FIND_IDENTITY
  175. * @retval PEP_OUT_OF_MEMORY out of memory
  176. *
  177. */
  178. PEP_STATUS get_identities_by_address(
  179. PEP_SESSION session,
  180. const char *address,
  181. identity_list** id_list
  182. );
  183. /**
  184. * <!-- get_identities_by_userid() -->
  185. *
  186. * @brief TODO
  187. *
  188. * @param[in] session session handle
  189. * @param[in] user_id const char*
  190. * @param[in] identities identity_list**
  191. *
  192. * @retval PEP_STATUS_OK
  193. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  194. * @retval PEP_CANNOT_FIND_IDENTITY
  195. * @retval PEP_OUT_OF_MEMORY out of memory
  196. *
  197. */
  198. PEP_STATUS get_identities_by_userid(
  199. PEP_SESSION session,
  200. const char *user_id,
  201. identity_list **identities
  202. );
  203. /**
  204. * <!-- is_own_address() -->
  205. *
  206. * @brief TODO
  207. *
  208. * @param[in] session session handle
  209. * @param[in] address const char*
  210. * @param[in] is_own_addr bool*
  211. *
  212. * @retval PEP_STATUS_OK
  213. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  214. * @retval PEP_RECORD_NOT_FOUND
  215. *
  216. */
  217. PEP_STATUS is_own_address(PEP_SESSION session,
  218. const char* address,
  219. bool* is_own_addr);
  220. /**
  221. * <!-- replace_userid() -->
  222. *
  223. * @brief TODO
  224. *
  225. * @param[in] session session handle
  226. * @param[in] old_uid const char*
  227. * @param[in] new_uid const char*
  228. *
  229. * @retval PEP_STATUS_OK
  230. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  231. * @retval PEP_CANNOT_SET_PERSON
  232. */
  233. PEP_STATUS replace_userid(PEP_SESSION session, const char* old_uid,
  234. const char* new_uid);
  235. /**
  236. * <!-- remove_key() -->
  237. *
  238. * @brief TODO
  239. *
  240. * @param[in] session session handle
  241. * @param[in] fpr const char*
  242. *
  243. * @retval PEP_STATUS_OK
  244. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  245. * @retval PEP_CANNOT_SET_PGP_KEYPAIR
  246. *
  247. */
  248. PEP_STATUS remove_key(PEP_SESSION session, const char* fpr);
  249. /**
  250. * <!-- remove_fpr_as_default() -->
  251. *
  252. * @brief TODO
  253. *
  254. * @param[in] session session handle
  255. * @param[in] fpr const char*
  256. *
  257. * @retval PEP_STATUS_OK
  258. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  259. * @retval PEP_CANNOT_SET_IDENTITY
  260. * @retval PEP_CANNOT_SET_PERSON
  261. *
  262. */
  263. PEP_STATUS remove_fpr_as_default(PEP_SESSION session,
  264. const char* fpr);
  265. /**
  266. * <!-- get_main_user_fpr() -->
  267. *
  268. * @brief TODO
  269. *
  270. * @param[in] session session handle
  271. * @param[in] user_id const char*
  272. * @param[in] main_fpr char**
  273. *
  274. * @retval PEP_STATUS_OK
  275. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  276. * @retval PEP_OUT_OF_MEMORY out of memory
  277. * @retval PEP_KEY_NOT_FOUND
  278. * @retval PEP_CANNOT_FIND_PERSON
  279. */
  280. PEP_STATUS get_main_user_fpr(PEP_SESSION session,
  281. const char* user_id,
  282. char** main_fpr);
  283. /**
  284. * <!-- replace_main_user_fpr() -->
  285. *
  286. * @brief TODO
  287. *
  288. * @param[in] session session handle
  289. * @param[in] user_id const char*
  290. * @param[in] new_fpr const char*
  291. *
  292. * @retval PEP_STATUS_OK
  293. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  294. * @retval PEP_CANNOT_SET_PERSON
  295. *
  296. */
  297. PEP_STATUS replace_main_user_fpr(PEP_SESSION session, const char* user_id,
  298. const char* new_fpr);
  299. /**
  300. * <!-- replace_main_user_fpr_if_equal() -->
  301. *
  302. * @brief TODO
  303. *
  304. * @param[in] session session handle
  305. * @param[in] user_id const char*
  306. * @param[in] new_fpr const char*
  307. * @param[in] compare_fpr const char*
  308. *
  309. * @retval PEP_STATUS_OK
  310. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  311. * @retval PEP_CANNOT_SET_PERSON
  312. *
  313. */
  314. PEP_STATUS replace_main_user_fpr_if_equal(PEP_SESSION session, const char* user_id,
  315. const char* new_fpr, const char* compare_fpr);
  316. /**
  317. * <!-- refresh_userid_default_key() -->
  318. *
  319. * @brief TODO
  320. *
  321. * @param[in] session session handle
  322. * @param[in] user_id const char*
  323. *
  324. * @retval PEP_STATUS_OK
  325. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  326. * @retval PEP_CANNOT_SET_PERSON
  327. *
  328. */
  329. PEP_STATUS refresh_userid_default_key(PEP_SESSION session, const char* user_id);
  330. // returns true (by reference) if a person with this user_id exists;
  331. // Also replaces aliased user_ids by defaults in identity.
  332. /**
  333. * <!-- exists_person() -->
  334. *
  335. * @brief TODO
  336. *
  337. * @param[in] session session handle
  338. * @param[in] identity pEp_identity*
  339. * @param[in] exists bool*
  340. *
  341. * @retval PEP_STATUS_OK
  342. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  343. * @retval PEP_UNKNOWN_DB_ERROR
  344. */
  345. PEP_STATUS exists_person(PEP_SESSION session, pEp_identity* identity, bool* exists);
  346. /**
  347. * <!-- set_pgp_keypair() -->
  348. *
  349. * @brief TODO
  350. *
  351. * @param[in] session session handle
  352. * @param[in] fpr const char*
  353. *
  354. * @retval PEP_STATUS_OK
  355. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  356. * @retval PEP_CANNOT_SET_PGP_KEYPAIR
  357. */
  358. PEP_STATUS set_pgp_keypair(PEP_SESSION session, const char* fpr);
  359. /**
  360. * <!-- set_pEp_version() -->
  361. *
  362. * @brief TODO
  363. *
  364. * @param[in] session session handle
  365. * @param[in] ident pEp_identity*
  366. * @param[in] new_ver_major unsigned int
  367. * @param[in] new_ver_minor unsigned int
  368. *
  369. * @retval PEP_STATUS_OK
  370. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  371. * @retval PEP_CANNOT_SET_PEP_VERSION
  372. *
  373. */
  374. PEP_STATUS set_pEp_version(PEP_SESSION session, pEp_identity* ident, unsigned int new_ver_major, unsigned int new_ver_minor);
  375. /**
  376. * <!-- clear_trust_info() -->
  377. *
  378. * @brief TODO
  379. *
  380. * @param[in] session session handle
  381. * @param[in] user_id const char*
  382. * @param[in] fpr const char*
  383. *
  384. * @retval PEP_STATUS_OK
  385. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  386. * @retval PEP_UNKNOWN_ERROR
  387. *
  388. */
  389. PEP_STATUS clear_trust_info(PEP_SESSION session,
  390. const char* user_id,
  391. const char* fpr);
  392. // Generally ONLY called by set_as_pEp_user, and ONLY from < 2.0 to 2.0.
  393. /**
  394. * <!-- upgrade_pEp_version_by_user_id() -->
  395. *
  396. * @brief TODO
  397. *
  398. * @param[in] session session handle
  399. * @param[in] ident pEp_identity*
  400. * @param[in] new_ver_major unsigned int
  401. * @param[in] new_ver_minor unsigned int
  402. *
  403. * @retval PEP_STATUS_OK
  404. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  405. * @retval PEP_CANNOT_SET_PEP_VERSION
  406. *
  407. */
  408. PEP_STATUS upgrade_pEp_version_by_user_id(PEP_SESSION session,
  409. pEp_identity* ident,
  410. unsigned int new_ver_major,
  411. unsigned int new_ver_minor
  412. );
  413. // exposed for testing
  414. /**
  415. * <!-- set_person() -->
  416. *
  417. * @brief TODO
  418. *
  419. * @param[in] session session handle
  420. * @param[in] identity pEp_identity*
  421. * @param[in] guard_transaction bool
  422. *
  423. * @retval PEP_STATUS_OK
  424. * @retval any other value on error
  425. */
  426. PEP_STATUS set_person(PEP_SESSION session, pEp_identity* identity,
  427. bool guard_transaction);
  428. /**
  429. * <!-- bind_own_ident_with_contact_ident() -->
  430. *
  431. * @brief TODO
  432. *
  433. * @param[in] session session handle
  434. * @param[in] own_ident pEp_identity*
  435. * @param[in] contact_ident pEp_identity*
  436. *
  437. * @retval PEP_STATUS_OK
  438. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  439. * @retval PEP_CANNOT_SET_PERSON
  440. *
  441. */
  442. PEP_STATUS bind_own_ident_with_contact_ident(PEP_SESSION session,
  443. pEp_identity* own_ident,
  444. pEp_identity* contact_ident);
  445. /**
  446. * <!-- get_last_contacted() -->
  447. *
  448. * @brief TODO
  449. *
  450. * @param[in] session session handle
  451. * @param[in] id_list identity_list**
  452. *
  453. * @retval PEP_STATUS_OK
  454. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  455. * @retval PEP_CANNOT_FIND_IDENTITY
  456. * @retval PEP_OUT_OF_MEMORY out of memory
  457. *
  458. */
  459. PEP_STATUS get_last_contacted(
  460. PEP_SESSION session,
  461. identity_list** id_list
  462. );
  463. /**
  464. * <!-- get_own_ident_for_contact_id() -->
  465. *
  466. * @brief TODO
  467. *
  468. * @param[in] session session handle
  469. * @param[in] contact const pEp_identity*
  470. * @param[out] own_ident pEp_identity**
  471. *
  472. * @retval PEP_STATUS_OK
  473. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  474. * @retval PEP_CANNOT_FIND_IDENTITY
  475. *
  476. */
  477. PEP_STATUS get_own_ident_for_contact_id(PEP_SESSION session,
  478. const pEp_identity* contact,
  479. pEp_identity** own_ident);
  480. /**
  481. * <!-- exists_trust_entry() -->
  482. *
  483. * @brief TODO
  484. *
  485. * @param[in] session session handle
  486. * @param[in] identity pEp_identity*
  487. * @param[out] exists bool*
  488. *
  489. * @retval PEP_STATUS_OK
  490. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  491. * @retval PEP_UNKNOWN_DB_ERROR
  492. *
  493. */
  494. PEP_STATUS exists_trust_entry(PEP_SESSION session, pEp_identity* identity,
  495. bool* exists);
  496. /**
  497. * <!-- is_own_key() -->
  498. *
  499. * @brief TODO
  500. *
  501. * @param[in] session session handle
  502. * @param[in] fpr const char*
  503. * @param[out] own_key bool*
  504. *
  505. * @retval PEP_STATUS_OK
  506. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  507. * @retval PEP_OUT_OF_MEMORY out of memory
  508. *
  509. */
  510. PEP_STATUS is_own_key(PEP_SESSION session, const char* fpr, bool* own_key);
  511. /**
  512. * <!-- get_identities_by_main_key_id() -->
  513. *
  514. * @brief TODO
  515. *
  516. * @param[in] session session handle
  517. * @param[in] fpr const char*
  518. * @param[out] identities identity_list**
  519. *
  520. * @retval PEP_STATUS_OK
  521. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  522. * @retval PEP_OUT_OF_MEMORY out of memory
  523. * @retval PEP_CANNOT_FIND_IDENTITY
  524. *
  525. */
  526. PEP_STATUS get_identities_by_main_key_id(
  527. PEP_SESSION session,
  528. const char *fpr,
  529. identity_list **identities);
  530. PEP_STATUS get_identities_by_address(
  531. PEP_SESSION session,
  532. const char *address,
  533. identity_list** id_list
  534. );
  535. /**
  536. *
  537. * @param session
  538. * @param address
  539. * @param user_id
  540. * @param main_fpr
  541. * @return
  542. */
  543. PEP_STATUS get_default_identity_fpr(PEP_SESSION session,
  544. const char* address,
  545. const char* user_id,
  546. char** main_fpr);
  547. /**
  548. * <!-- set_default_identity_fpr() -->
  549. * Set the default key fingerprint for the identity identitified by this address and user_id. Will only
  550. * succeed if identity is already in DB.
  551. *
  552. * @param[in] session session handle
  553. * @param[in] user_id user_id for identity - cannot be NULL
  554. * @param[in] address address for identity - cannot be NULL
  555. * @param[in] fpr fingerprint for identity - cannot be NULL
  556. *
  557. * @retval PEP_STATUS_OK if key was set or identity doesn't exists
  558. * @retval error otherwise
  559. */
  560. PEP_STATUS set_default_identity_fpr(PEP_SESSION session,
  561. const char* user_id,
  562. const char* address,
  563. const char* fpr);
  564. /**
  565. * <!-- sign_only() -->
  566. *
  567. * @brief TODO
  568. *
  569. * @param[in] session session handle
  570. * @param[in] data const char*
  571. * @param[in] data_size size_t
  572. * @param[in] fpr const char*
  573. * @param[out] sign char**
  574. * @param[out] sign_size size_t*
  575. *
  576. * @retval PEP_STATUS_OK
  577. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  578. *
  579. */
  580. PEP_STATUS sign_only(PEP_SESSION session,
  581. const char *data,
  582. size_t data_size,
  583. const char *fpr,
  584. char **sign,
  585. size_t *sign_size);
  586. /**
  587. * <!-- set_all_userids_to_own() -->
  588. *
  589. * @brief TODO
  590. *
  591. * @param[in] session session handle
  592. * @param[in] id_list identity_list*
  593. *
  594. */
  595. PEP_STATUS set_all_userids_to_own(PEP_SESSION session,
  596. identity_list* id_list);
  597. /**
  598. * <!-- has_partner_contacted_address() -->
  599. *
  600. * @brief TODO
  601. *
  602. * @param[in] session session handle
  603. * @param[in] partner_id const char*
  604. * @param[in] own_address const char*
  605. * @param[in] was_contacted bool*
  606. *
  607. * @retval PEP_STATUS_OK
  608. * @retval PEP_ILLEGAL_VALUE illegal parameter value
  609. * @retval PEP_UNKNOWN_DB_ERROR
  610. *
  611. */
  612. PEP_STATUS has_partner_contacted_address(PEP_SESSION session, const char* partner_id,
  613. const char* own_address, bool* was_contacted);
  614. /**
  615. *
  616. * @param session
  617. * @param identity
  618. * @param exists
  619. * @return
  620. */
  621. PEP_STATUS exists_identity_entry(PEP_SESSION session, pEp_identity* identity,
  622. bool* exists);
  623. /**
  624. *
  625. * @param session
  626. * @param identity
  627. * @param username
  628. * @return
  629. */
  630. PEP_STATUS force_set_identity_username(PEP_SESSION session, pEp_identity* identity, const char* username);
  631. #ifdef __cplusplus
  632. }
  633. #endif
  634. #endif