p≡p engine fork for my own dirty testing of stuff
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.

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