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.

653 lines
21 KiB

8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
  1. #pragma once
  2. #ifdef __cplusplus
  3. extern "C" {
  4. #endif
  5. #include <stddef.h>
  6. #include <stdint.h>
  7. #include <stdbool.h>
  8. #ifdef WIN32
  9. #ifdef _EXPORT_PEP_ENGINE_DLL
  10. #define DYNAMIC_API __declspec(dllexport)
  11. #else
  12. #define DYNAMIC_API __declspec(dllimport)
  13. #endif
  14. #else
  15. #define DYNAMIC_API
  16. #endif
  17. // pEp Engine API
  18. // caveat:
  19. // Unicode data has to be normalized to NFC before calling
  20. // UTF-8 strings are UTF-8 encoded C strings (zero terminated)
  21. typedef void * PEP_SESSION;
  22. typedef enum {
  23. PEP_STATUS_OK = 0,
  24. PEP_INIT_CANNOT_LOAD_GPGME = 0x0110,
  25. PEP_INIT_GPGME_INIT_FAILED = 0x0111,
  26. PEP_INIT_SQLITE3_WITHOUT_MUTEX = 0x0120,
  27. PEP_INIT_CANNOT_OPEN_DB = 0x0121,
  28. PEP_INIT_CANNOT_OPEN_SYSTEM_DB = 0x0122,
  29. PEP_KEY_NOT_FOUND = 0x0201,
  30. PEP_KEY_HAS_AMBIG_NAME = 0x0202,
  31. PEP_GET_KEY_FAILED = 0x0203,
  32. PEP_CANNOT_FIND_IDENTITY = 0x0301,
  33. PEP_CANNOT_SET_PERSON = 0x0381,
  34. PEP_CANNOT_SET_PGP_KEYPAIR = 0x0382,
  35. PEP_CANNOT_SET_IDENTITY = 0x0383,
  36. PEP_UNENCRYPTED = 0x0400,
  37. PEP_VERIFIED = 0x0401,
  38. PEP_DECRYPTED = 0x0402,
  39. PEP_DECRYPTED_AND_VERIFIED = 0x0403,
  40. PEP_DECRYPT_WRONG_FORMAT = 0x0404,
  41. PEP_DECRYPT_NO_KEY = 0x0405,
  42. PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH = 0x0406,
  43. PEP_VERIFY_NO_KEY = 0x0407,
  44. PEP_VERIFIED_AND_TRUSTED = 0x0408,
  45. PEP_CANNOT_DECRYPT_UNKNOWN = 0x04ff,
  46. PEP_SAFEWORD_NOT_FOUND = 0x0501,
  47. PEP_CANNOT_CREATE_KEY = 0x0601,
  48. PEP_CANNOT_SEND_KEY = 0x0602,
  49. PEP_COMMIT_FAILED = 0xff01,
  50. PEP_ILLEGAL_VALUE = -4,
  51. PEP_BUFFER_TOO_SMALL = -3,
  52. PEP_OUT_OF_MEMORY = -2,
  53. PEP_UNKNOWN_ERROR = -1
  54. } PEP_STATUS;
  55. // INIT_STATUS init() - initialize pEpEngine for a thread
  56. //
  57. // parameters:
  58. // session (out) init() allocates session memory and returns a pointer
  59. // as a handle
  60. //
  61. // return value:
  62. // PEP_STATUS_OK = 0 if init() succeeds
  63. // PEP_INIT_SQLITE3_WITHOUT_MUTEX if SQLite3 was compiled with
  64. // SQLITE_THREADSAFE 0
  65. // PEP_INIT_CANNOT_LOAD_GPGME if libgpgme.dll cannot be found
  66. // PEP_INIT_GPGME_INIT_FAILED if GPGME init fails
  67. // PEP_INIT_CANNOT_OPEN_DB if user's management db cannot be
  68. // opened
  69. // PEP_INIT_CANNOT_OPEN_SYSTEM_DB if system's management db cannot be
  70. // opened
  71. //
  72. // caveat:
  73. // the pointer is valid only if the return value is PEP_STATUS_OK
  74. // in other case a NULL pointer will be returned; a valid handle must
  75. // be released using release() when it's no longer needed
  76. DYNAMIC_API PEP_STATUS init(PEP_SESSION *session);
  77. // void release() - release thread session handle
  78. //
  79. // parameters:
  80. // session (in) session handle to release
  81. DYNAMIC_API void release(PEP_SESSION session);
  82. typedef struct _stringlist_t {
  83. char *value;
  84. struct _stringlist_t *next;
  85. } stringlist_t;
  86. // new_stringlist() - allocate a new stringlist
  87. //
  88. // parameters:
  89. // value (in) initial value as C string or NULL for empty list
  90. //
  91. // return value:
  92. // pointer to stringlist_t object or NULL if out of memory
  93. //
  94. // caveat:
  95. // the value is being copied before being added to the list
  96. // the original string is still being owned by the caller
  97. DYNAMIC_API stringlist_t *new_stringlist(const char *value);
  98. // stringlist_add() - add key to stringlist
  99. //
  100. // parameters:
  101. // stringlist (in) stringlist struct or NULL to create a new one
  102. // value (in) value as C string
  103. //
  104. // return value:
  105. // pointer to last element in stringlist or NULL if out of memory
  106. //
  107. // caveat:
  108. // the value is being copied before being added to the list
  109. // the original string is still being owned by the caller
  110. DYNAMIC_API stringlist_t *stringlist_add(stringlist_t *stringlist, const char *value);
  111. // stringlist_length() - get length of stringlist
  112. //
  113. // parameters:
  114. // stringlist (in) stringlist struct to determine length of
  115. //
  116. // return value:
  117. // length of stringlist in number of elements
  118. DYNAMIC_API int stringlist_length(const stringlist_t *stringlist);
  119. // free_stringlist() - free memory occupied by stringlist
  120. //
  121. // parameters:
  122. // stringlist (in) stringlist to free
  123. DYNAMIC_API void free_stringlist(stringlist_t *stringlist);
  124. // decrypt_and_verify() - decrypt and/or verify a message
  125. //
  126. // parameters:
  127. // session (in) session handle
  128. // ctext (in) cipher text to decrypt and/or verify
  129. // csize (in) size of cipher text
  130. // ptext (out) pointer to internal buffer with plain text
  131. // psize (out) size of plain text
  132. // keylist (out) list of key ids which where used to encrypt
  133. //
  134. // return value:
  135. // PEP_UNENCRYPTED message was unencrypted and not signed
  136. // PEP_VERIFIED message was unencrypted, signature matches
  137. // PEP_DECRYPTED message is decrypted now, no signature
  138. // PEP_DECRYPTED_AND_VERIFIED message is decrypted now and verified
  139. // PEP_DECRYPT_WRONG_FORMAT message has wrong format to handle
  140. // PEP_DECRYPT_NO_KEY key not available to decrypt and/or verify
  141. // PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH wrong signature
  142. //
  143. // caveat:
  144. // the ownerships of ptext as well as keylist are going to the caller
  145. // the caller must use free() (or an Windoze pEp_free()) and
  146. // free_stringlist() to free them
  147. //
  148. // if this function failes an error message may be the first element of
  149. // keylist and the other elements may be the keys used for encryption
  150. DYNAMIC_API PEP_STATUS decrypt_and_verify(
  151. PEP_SESSION session, const char *ctext, size_t csize,
  152. char **ptext, size_t *psize, stringlist_t **keylist
  153. );
  154. // verify_text() - verfy plain text with a digital signature
  155. //
  156. // parameters:
  157. // session (in) session handle
  158. // text (in) text to verify
  159. // size (in) size of text
  160. // signature (in) signature text
  161. // sig_size (in) size of signature
  162. // keylist (out) list of key ids which where used to encrypt or NULL on
  163. // error
  164. //
  165. // return value:
  166. // PEP_VERIFIED message was unencrypted, signature matches
  167. // PEP_DECRYPT_NO_KEY key not available to decrypt and/or verify
  168. // PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH wrong signature
  169. DYNAMIC_API PEP_STATUS verify_text(
  170. PEP_SESSION session, const char *text, size_t size,
  171. const char *signature, size_t sig_size, stringlist_t **keylist
  172. );
  173. // encrypt_and_sign() - encrypt and sign a message
  174. //
  175. // parameters:
  176. // session (in) session handle
  177. // keylist (in) list of key ids to encrypt with as C strings
  178. // ptext (in) plain text to decrypt and/or verify
  179. // psize (in) size of plain text
  180. // ctext (out) pointer to internal buffer with cipher text
  181. // csize (out) size of cipher text
  182. //
  183. // return value:
  184. // PEP_STATUS_OK = 0 encryption and signing succeeded
  185. // PEP_KEY_NOT_FOUND at least one of the receipient keys
  186. // could not be found
  187. // PEP_KEY_HAS_AMBIG_NAME at least one of the receipient keys has
  188. // an ambiguous name
  189. // PEP_GET_KEY_FAILED cannot retrieve key
  190. //
  191. // caveat:
  192. // the ownership of ctext is going to the caller
  193. // the caller is responsible to free() it (on Windoze use pEp_free())
  194. // the first key in keylist is being used to sign the message
  195. // this implies there has to be a private key for that keypair
  196. DYNAMIC_API PEP_STATUS encrypt_and_sign(
  197. PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
  198. size_t psize, char **ctext, size_t *csize
  199. );
  200. // log_event() - log a user defined event defined by UTF-8 encoded strings into
  201. // management log
  202. //
  203. // parameters:
  204. // session (in) session handle
  205. // title (in) C string with event name
  206. // entity (in) C string with name of entity which is logging
  207. // description (in) C string with long description for event or NULL if
  208. // omitted
  209. // comment (in) C string with user defined comment or NULL if
  210. // omitted
  211. //
  212. // return value:
  213. // PEP_STATUS_OK log entry created
  214. DYNAMIC_API PEP_STATUS log_event(
  215. PEP_SESSION session, const char *title, const char *entity,
  216. const char *description, const char *comment
  217. );
  218. // safeword() - get the corresponding safeword for a 16 bit value
  219. //
  220. // parameters:
  221. // session (in) session handle
  222. // value (in) value to find a safeword for
  223. // lang (in) C string with ISO 3166-1 ALPHA-2 language code
  224. // word (out) pointer to C string with safeword UTF-8 encoded
  225. // NULL if language is not supported or safeword
  226. // wordlist is damaged or unavailable
  227. // wsize (out) length of safeword
  228. //
  229. // return value:
  230. // PEP_STATUS_OK safeword retrieved
  231. // PEP_SAFEWORD_NOT_FOUND safeword not found
  232. //
  233. // caveat:
  234. // the word pointer goes to the ownership of the caller
  235. // the caller is responsible to free() it (on Windoze use pEp_free())
  236. DYNAMIC_API PEP_STATUS safeword(
  237. PEP_SESSION session, uint16_t value, const char *lang,
  238. char **word, size_t *wsize
  239. );
  240. // safewords() - get safewords for a string of hex values of a fingerprint
  241. //
  242. // parameters:
  243. // session (in) session handle
  244. // fingerprint (in) C string with hex values to find safewords for
  245. // lang (in) C string with ISO 3166-1 ALPHA-2 language code
  246. // words (out) pointer to C string with safewords UTF-8 encoded,
  247. // separated by a blank each
  248. // NULL if language is not supported or safeword
  249. // wordlist is damaged or unavailable
  250. // wsize (out) length of safewords string
  251. // max_words (in) only generate a string with max_words;
  252. // if max_words == 0 there is no such limit
  253. //
  254. // return value:
  255. // PEP_STATUS_OK safewords retrieved
  256. // PEP_OUT_OF_MEMORY out of memory
  257. // PEP_SAFEWORD_NOT_FOUND at least one safeword not found
  258. //
  259. // caveat:
  260. // the word pointer goes to the ownership of the caller
  261. // the caller is responsible to free() it (on Windoze use pEp_free())
  262. //
  263. // DON'T USE THIS FUNCTION FROM HIGH LEVEL LANGUAGES!
  264. //
  265. // Better implement a simple one in the adapter yourself using safeword(), and
  266. // return a list of safewords.
  267. // This function is provided for being used by C and C++ programs only.
  268. DYNAMIC_API PEP_STATUS safewords(
  269. PEP_SESSION session, const char *fingerprint, const char *lang,
  270. char **words, size_t *wsize, int max_words
  271. );
  272. typedef enum _PEP_comm_type {
  273. PEP_ct_unknown = 0,
  274. // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
  275. PEP_ct_no_encryption = 0x01, // generic
  276. PEP_ct_no_encrypted_channel = 0x02,
  277. PEP_ct_key_not_found = 0x03,
  278. PEP_ct_key_expired = 0x04,
  279. PEP_ct_key_revoked = 0x05,
  280. PEP_ct_key_b0rken = 0x06,
  281. PEP_ct_my_key_not_included = 0x09,
  282. PEP_ct_security_by_obscurity = 0x0a,
  283. PEP_ct_b0rken_crypto = 0x0b,
  284. PEP_ct_key_too_short = 0x0e,
  285. PEP_ct_compromized = 0x0f, // known compromized connection
  286. // range 0x10 to 0x3f: unconfirmed encryption
  287. PEP_ct_unconfirmed_encryption = 0x10, // generic
  288. PEP_ct_OpenPGP_1024_RSA_unconfirmed = 0x11, // RSA 1024 is weak
  289. PEP_ct_SMIME_unconfirmed = 0x20,
  290. PEP_ct_CMS_unconfirmed = 0x30,
  291. PEP_ct_OpenPGP_unconfirmed = 0x3f, // key at least 2048 bit RSA
  292. // or 1024 bit DSA
  293. // range 0x40 to 0x7f: unconfirmed encryption and anonymization
  294. PEP_ct_unconfirmed_enc_anon = 0x40, // generic
  295. PEP_ct_PEP_unconfirmed = 0x7f,
  296. PEP_ct_confirmed = 0x80, // this bit decides if trust is confirmed
  297. // range 0x81 to 0x8f: reserved
  298. // range 0x90 to 0xbf: confirmed encryption
  299. PEP_ct_confirmed_encryption = 0x90, // generic
  300. PEP_ct_OpenPGP_1024_RSA = 0x91, // RSA 1024 is weak
  301. PEP_ct_SMIME = 0xa0,
  302. PEP_ct_CMS = 0xb0,
  303. PEP_ct_OpenPGP = 0xbf, // key at least 2048 bit RSA or 1024 bit DSA
  304. // range 0xc0 to 0xff: confirmed encryption and anonymization
  305. PEP_ct_confirmed_enc_anon = 0xc0, // generic
  306. PEP_ct_pEp = 0xff
  307. } PEP_comm_type;
  308. typedef struct _pEp_identity {
  309. size_t struct_size; // size of whole struct
  310. char *address; // C string with address UTF-8 encoded
  311. size_t address_size; // size of address
  312. char *fpr; // C string with fingerprint UTF-8 encoded
  313. size_t fpr_size; // size of fingerprint
  314. char *user_id; // C string with user ID UTF-8 encoded
  315. size_t user_id_size; // size of user ID
  316. char *username; // C string with user name UTF-8 encoded
  317. size_t username_size; // size of user name
  318. PEP_comm_type comm_type; // type of communication with this ID
  319. char lang[3]; // language of conversation
  320. // ISO 639-1 ALPHA-2, last byte is 0
  321. bool me; // if this is the local user herself/himself
  322. } pEp_identity;
  323. // new_identity() - allocate memory and set the string and size fields
  324. //
  325. // parameters:
  326. // address (in) UTF-8 string or NULL
  327. // fpr (in) UTF-8 string or NULL
  328. // user_id (in) UTF-8 string or NULL
  329. // username (in) UTF-8 string or NULL
  330. //
  331. // return value:
  332. // pEp_identity struct with correct size values or NULL if out of memory
  333. //
  334. // caveat:
  335. // the strings are copied; the original strings are still being owned by
  336. // the caller
  337. DYNAMIC_API pEp_identity *new_identity(
  338. const char *address, const char *fpr, const char *user_id,
  339. const char *username
  340. );
  341. // identity_dup() - allocate memory and set the string and size fields
  342. //
  343. // parameters:
  344. // src (in) identity to duplicate
  345. //
  346. // return value:
  347. // pEp_identity struct with correct size values or NULL if out of memory
  348. //
  349. // caveat:
  350. // the strings are copied; the original strings are still being owned by
  351. // the caller
  352. DYNAMIC_API pEp_identity *identity_dup(const pEp_identity *src);
  353. // free_identity() - free all memory being occupied by a pEp_identity struct
  354. //
  355. // parameters:
  356. // identity (in) struct to release
  357. //
  358. // caveat:
  359. // not only the struct but also all string memory referenced by the
  360. // struct is being freed; all pointers inside are invalid afterwards
  361. DYNAMIC_API void free_identity(pEp_identity *identity);
  362. // get_identity() - get identity information
  363. //
  364. // parameters:
  365. // session (in) session handle
  366. // address (in) C string with communication address, UTF-8 encoded
  367. // identity (out) pointer to pEp_identity structure with results or
  368. // NULL if failure
  369. //
  370. // caveat:
  371. // the address string is being copied; the original string remains in the
  372. // ownership of the caller
  373. // the resulting pEp_identity structure goes to the ownership of the
  374. // caller and has to be freed with free_identity() when not in use any
  375. // more
  376. DYNAMIC_API PEP_STATUS get_identity(
  377. PEP_SESSION session, const char *address,
  378. pEp_identity **identity
  379. );
  380. // set_identity() - set identity information
  381. //
  382. // parameters:
  383. // session (in) session handle
  384. // identity (in) pointer to pEp_identity structure
  385. //
  386. // return value:
  387. // PEP_STATUS_OK = 0 encryption and signing succeeded
  388. // PEP_CANNOT_SET_PERSON writing to table person failed
  389. // PEP_CANNOT_SET_PGP_KEYPAIR writing to table pgp_keypair failed
  390. // PEP_CANNOT_SET_IDENTITY writing to table identity failed
  391. // PEP_COMMIT_FAILED SQL commit failed
  392. //
  393. // caveat:
  394. // in the identity structure you need to set the const char * fields to
  395. // UTF-8 C strings
  396. // the size fields are ignored
  397. DYNAMIC_API PEP_STATUS set_identity(
  398. PEP_SESSION session, const pEp_identity *identity
  399. );
  400. // generate_keypair() - generate a new key pair and add it to the key ring
  401. //
  402. // parameters:
  403. // session (in) session handle
  404. // identity (inout) pointer to pEp_identity structure
  405. //
  406. // return value:
  407. // PEP_STATUS_OK = 0 encryption and signing succeeded
  408. // PEP_ILLEGAL_VALUE illegal values for identity fields given
  409. // PEP_CANNOT_CREATE_KEY key engine is on strike
  410. //
  411. // caveat:
  412. // address and username fields must be set to UTF-8 strings
  413. // the fpr field must be set to NULL
  414. //
  415. // this function allocates a string and sets set fpr field of identity
  416. // the caller is responsible to call free() for that string or use
  417. // free_identity() on the struct
  418. DYNAMIC_API PEP_STATUS generate_keypair(
  419. PEP_SESSION session, pEp_identity *identity
  420. );
  421. // delete_keypair() - delete a public key or a key pair from the key ring
  422. //
  423. // parameters:
  424. // session (in) session handle
  425. // fpr (in) C string with key id or fingerprint of the
  426. // public key
  427. //
  428. // return value:
  429. // PEP_STATUS_OK = 0 key was successfully deleted
  430. // PEP_KEY_NOT_FOUND key not found
  431. // PEP_ILLEGAL_VALUE not a valid key id or fingerprint
  432. // PEP_KEY_HAS_AMBIG_NAME fpr does not uniquely identify a key
  433. // PEP_OUT_OF_MEMORY out of memory
  434. DYNAMIC_API PEP_STATUS delete_keypair(PEP_SESSION session, const char *fpr);
  435. // import_key() - import key from data
  436. //
  437. // parameters:
  438. // session (in) session handle
  439. // key_data (in) key data, i.e. ASCII armored OpenPGP key
  440. // size (in) amount of data to handle
  441. //
  442. // return value:
  443. // PEP_STATUS_OK = 0 key was successfully imported
  444. // PEP_OUT_OF_MEMORY out of memory
  445. // PEP_ILLEGAL_VALUE there is no key data to import
  446. DYNAMIC_API PEP_STATUS import_key(PEP_SESSION session, const char *key_data, size_t size);
  447. // export_key() - export ascii armored key
  448. //
  449. // parameters:
  450. // session (in) session handle
  451. // fpr (in) key id or fingerprint of key
  452. // key_data (out) ASCII armored OpenPGP key
  453. // size (out) amount of data to handle
  454. //
  455. // return value:
  456. // PEP_STATUS_OK = 0 key was successfully exported
  457. // PEP_OUT_OF_MEMORY out of memory
  458. // PEP_KEY_NOT_FOUND key not found
  459. //
  460. // caveat:
  461. // the key_data goes to the ownership of the caller
  462. // the caller is responsible to free() it (on Windoze use pEp_free())
  463. DYNAMIC_API PEP_STATUS export_key(
  464. PEP_SESSION session, const char *fpr, char **key_data, size_t *size
  465. );
  466. // recv_key() - update key(s) from keyserver
  467. //
  468. // parameters:
  469. // session (in) session handle
  470. // pattern (in) key id, user id or address to search for as
  471. // UTF-8 string
  472. DYNAMIC_API PEP_STATUS recv_key(PEP_SESSION session, const char *pattern);
  473. // find_keys() - find keys in keyring
  474. //
  475. // parameters:
  476. // session (in) session handle
  477. // pattern (in) key id, user id or address to search for as
  478. // UTF-8 string
  479. // keylist (out) list of fingerprints found or NULL on error
  480. //
  481. // caveat:
  482. // the ownerships of keylist isgoing to the caller
  483. // the caller must use free_stringlist() to free it
  484. DYNAMIC_API PEP_STATUS find_keys(
  485. PEP_SESSION session, const char *pattern, stringlist_t **keylist
  486. );
  487. // send_key() - send key(s) to keyserver
  488. //
  489. // parameters:
  490. // session (in) session handle
  491. // pattern (in) key id, user id or address to search for as
  492. // UTF-8 string
  493. DYNAMIC_API PEP_STATUS send_key(PEP_SESSION session, const char *pattern);
  494. // pEp_free() - free memory allocated by pEp engine
  495. //
  496. // parameters:
  497. // p (in) pointer to free
  498. //
  499. // The reason for this function is that heap management can be a pretty
  500. // complex task with Windoze. This free() version calls the free()
  501. // implementation of the C runtime library which was used to build pEp engine,
  502. // so you're using the correct heap. For more information, see:
  503. // <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
  504. DYNAMIC_API void pEp_free(void *p);
  505. // get_trust() - get the trust level a key has for a person
  506. //
  507. // parameters:
  508. // session (in) session handle
  509. // identity (inout) user_id and fpr to check as UTF-8 strings (in)
  510. // user_id and comm_type as result (out)
  511. //
  512. // this function modifies the given identity struct; the struct remains in
  513. // the ownership of the caller
  514. // if the trust level cannot be determined identity->comm_type is set
  515. // to PEP_ct_unknown
  516. DYNAMIC_API PEP_STATUS get_trust(PEP_SESSION session, pEp_identity *identity);
  517. // get_key_rating() - get the rating a bare key has
  518. //
  519. // parameters:
  520. // session (in) session handle
  521. // fpr (in) unique identifyer for key as UTF-8 string
  522. // comm_type (out) key rating
  523. //
  524. // if an error occurs, *comm_type is set to PEP_ct_unknown and an error
  525. // is returned
  526. DYNAMIC_API PEP_STATUS get_key_rating(
  527. PEP_SESSION session,
  528. const char *fpr,
  529. PEP_comm_type *comm_type
  530. );
  531. #ifdef __cplusplus
  532. }
  533. #endif