1 // This file is under GNU General Public License 3.0
12 // update_identity() - update identity information
15 // session (in) session to use
16 // identity (inout) identity information of communication partner
17 // (identity->fpr is OUT ONLY), and at least
18 // .address must be set.
19 // If .username is set, it will be used to set or patch
20 // the username record for this identity.
22 // PEP_STATUS_OK if identity could be updated,
23 // PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
24 // with .me set or with an own user_id specified in the
25 // *input* (see caveats)
26 // PEP_KEY_UNSUITABLE if a default key was found for this identity, no
27 // other acceptable keys were found; if this is returned,
28 // the reason for rejecting the first default key found
29 // may be found in the comm_type
30 // any other value on error
33 // at least identity->address must be a non-empty UTF-8 string as input
34 // update_identity() never writes flags; use set_identity_flags() for
36 // this function NEVER reads the incoming fpr, only writes to it.
37 // this function will fail if called on an identity which, with its input
38 // values, *explicitly* indicates it is an own identity (i.e. .me is set
39 // to true on input, or a user_id is given AND it is a known own user_id).
40 // however, it can RETURN an own identity if this is not indicated a
41 // priori, and in fact will do so with prejudice when not faced with a
42 // matching default (i.e. it is forced to search by address only).
43 // if the identity is known to be an own identity (or the caller wishes
44 // to make it one), call myself() on the identity instead.
46 // FIXME: is this next point accurate?
47 // if this function returns PEP_ct_unknown or PEP_ct_key_expired in
48 // identity->comm_type, the caller must insert the identity into the
49 // asynchronous management implementation, so retrieve_next_identity()
50 // will return this identity later
53 DYNAMIC_API PEP_STATUS update_identity(
54 PEP_SESSION session, pEp_identity * identity
58 // initialise_own_identities () - ensures that an own identity is complete
61 // session (in) session to use
62 // my_idents (inout) identities of local user to quick-set
63 // For these, at least .address must be set.
64 // if no .user_id is set, AND the DB doesn't contain
65 // a default user_id, PEP_OWN_USERID will be used and
66 // become the perennial default for the DB.
69 // PEP_STATUS_OK if identity could be set,
70 // any other value on error
73 // this function does NOT generate keypairs. It is intended to
74 // precede running of the engine on actual messages. It effectively
75 // behaves like myself(), but when there would normally be key generation
76 // (when there is no valid key, for example),
77 // it instead stores an identity without keys.
79 // N.B. to adapter devs - this function is likely unnecessary, so please
80 // do not put work into exposing it yet. Tickets will be filed if need be.
82 // DYNAMIC_API PEP_STATUS initialise_own_identities(PEP_SESSION session,
83 // identity_list* my_idents);
85 // myself() - ensures that an own identity is complete
88 // session (in) session to use
89 // identity (inout) identity of local user
90 // both .address and .user_id must be set.
91 // if .fpr is set, an attempt will be made to make
92 // that the default key for this identity after key
94 // if .fpr is not set, key retrieval is performed
95 // If .username is set, it will be used to set or patch
96 // the username record for this identity.
99 // PEP_STATUS_OK if identity could be completed or was already complete,
100 // any other value on error
102 // If an fpr was entered and is not a valid key, the reason for failure
103 // is immediately returned in the status and, possibly, identity->comm_type
104 // If a default own user_id exists in the database, an alias will
105 // be created for the default for the input user_id. The ENGINE'S default
106 // user_id is always returned in the .user_id field
107 // myself() NEVER elects keys from the keyring; it will only choose keys
108 // which have been set up explicitly via myself(), or which were imported
109 // during a first time DB setup from an OpenPGP keyring (compatibility only)
110 // this function generates a keypair on demand; because it's synchronous
111 // it can need a decent amount of time to return
112 // if you need to do this asynchronous, you need to return an identity
113 // with retrieve_next_identity() where pEp_identity.me is true
115 DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
117 PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
119 // retrieve_next_identity() - callback being called by do_keymanagement()
122 // management (in) data structure to deliver (implementation defined)
125 // identity to check or NULL to terminate do_keymanagement()
126 // if given identity must be created with new_identity()
127 // the identity struct is going to the ownership of this library
128 // it must not be freed by the callee
131 // this callback has to block until an identity or NULL can be returned
132 // an implementation is not provided by this library; instead it has to be
133 // implemented by the user of this library
135 typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
138 // examine_identity() - callback for appending to queue
141 // ident (in) identity to examine
142 // management (in) data structure to deliver (implementation defined)
145 // 0 if identity was added successfully to queue or nonzero otherwise
147 typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
150 // register_examine_function() - register examine_identity() callback
153 // session (in) session to use
154 // examine_identity (in) examine_identity() function to register
155 // management (in) data structure to deliver (implementation defined)
157 DYNAMIC_API PEP_STATUS register_examine_function(
159 examine_identity_t examine_identity,
164 // do_keymanagement() - function to be run on an extra thread
167 // retrieve_next_identity pointer to retrieve_next_identity() callback
168 // which returns at least a valid address field in
169 // the identity struct
170 // management management data to give to keymanagement
171 // (implementation defined)
174 // PEP_STATUS_OK if thread has to terminate successfully or any other
178 // to ensure proper working of this library, a thread has to be started
179 // with this function immediately after initialization
180 // do_keymanagement() calls retrieve_next_identity(management)
182 DYNAMIC_API PEP_STATUS do_keymanagement(
183 retrieve_next_identity_t retrieve_next_identity,
188 // key_mistrusted() - mark key as being compromised
191 // session (in) session to use
192 // ident (in) person and key which was compromised
194 // ident is INPUT ONLY. If you want updated trust on the identity, you'll have
195 // to call update_identity or myself respectively after this.
196 // N.B. If you are calling this on a key that is the identity or user default,
197 // it will be removed as the default key for ANY identity and user for which
198 // it is the default. Please keep in mind that the undo in undo_last_mistrust
199 // will only undo the current identity's / it's user's default, not any
200 // other identities which may be impacted (this will not affect most use
203 DYNAMIC_API PEP_STATUS key_mistrusted(
208 // undo_last_mistrust() - reset identity and trust status for the last
209 // identity in this session marked as mistrusted
210 // to their cached values from the time of mistrust
212 // session (in) session to use
215 // PEP_STATUS_OK if identity and trust were successfully restored.
216 // Otherwise, error status from attempts to set.
219 // only works for this session, and only once. cache is invalidated
222 // WILL NOT WORK ON MISTRUSTED OWN KEY
224 DYNAMIC_API PEP_STATUS undo_last_mistrust(PEP_SESSION session);
227 // trust_personal_key() - mark a key as trusted for a user
230 // session (in) session to use
231 // ident (in) person and key to trust in
234 // the fields user_id, address and fpr must be supplied
235 // for non-own users, this will 1) set the trust bit on its comm type in the DB,
236 // 2) set this key as the identity default if the current identity default
237 // is not trusted, and 3) set this key as the user default if the current
238 // user default is not trusted.
239 // For an own user, this is simply a call to myself().
241 DYNAMIC_API PEP_STATUS trust_personal_key(
247 // key_reset_trust() - reset trust bit or explicitly mistrusted status for an identity and
248 // its accompanying key/user_id pair.
250 // session (in) session to use
251 // ident (in) identity for person and key whose trust status is to be reset
254 // ident is INPUT ONLY. If you want updated trust on the identity, you'll have
255 // to call update_identity or myself respectively after this.
256 // N.B. If you are calling this on a key that is the identity or user default,
257 // it will be removed as the default key for the identity and user (but is still
258 // available for key election, it is just not the cached default anymore)
260 DYNAMIC_API PEP_STATUS key_reset_trust(
265 // own_key_is_listed() - returns true id key is listed as own key
268 // session (in) session to use
269 // fpr (in) fingerprint of key to test
270 // listed (out) flags if key is own
272 DYNAMIC_API PEP_STATUS own_key_is_listed(
279 // _own_identities_retrieve() - retrieve all own identities
282 // session (in) session to use
283 // own_identities (out) list of own identities
284 // excluded_flags (int) flags to exclude from results
287 // the ownership of the copy of own_identities goes to the caller
289 DYNAMIC_API PEP_STATUS _own_identities_retrieve(
291 identity_list **own_identities,
292 identity_flags_t excluded_flags
295 // own_identities_retrieve() - retrieve all own identities
298 // session (in) session to use
299 // own_identities (out) list of own identities
302 // the ownership of the copy of own_identities goes to the caller
304 DYNAMIC_API PEP_STATUS own_identities_retrieve(
306 identity_list **own_identities
309 PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
312 // _own_keys_retrieve() - retrieve all flagged keypair fingerprints
315 // session (in) session to use
316 // keylist (out) list of fingerprints
317 // excluded_flags (int) flags to exclude from results
320 // the ownership of the list goes to the caller
321 DYNAMIC_API PEP_STATUS _own_keys_retrieve(
323 stringlist_t **keylist,
324 identity_flags_t excluded_flags
327 // own_keys_retrieve() - retrieve all flagged keypair fingerprints
330 // session (in) session to use
331 // keylist (out) list of fingerprints
334 // the ownership of the list goes to the caller
335 DYNAMIC_API PEP_STATUS own_keys_retrieve(
337 stringlist_t **keylist
340 // set_own_key() - mark a key as own key
343 // session (in) session to use
344 // me (inout) own identity this key is used for
345 // fpr (in) fingerprint of the key to mark as own key
348 // the key has to be in the key ring already
349 // me->address, me->user_id and me->username must be set to valid data
350 // myself() is called by set_own_key() without key generation
351 // me->flags are ignored
352 // me->address must not be an alias
353 // me->fpr will be ignored and replaced by fpr
355 DYNAMIC_API PEP_STATUS set_own_key(
361 PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
363 PEP_STATUS add_mistrusted_key(PEP_SESSION session, const char* fpr);
364 PEP_STATUS delete_mistrusted_key(PEP_SESSION session, const char* fpr);
365 PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr, bool* mistrusted);
366 PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
372 // Only call on retrieval of previously stored identity!
373 // Also, we presume that if the stored_identity was sent in
374 // without an fpr, there wasn't one in the trust DB for this
376 PEP_STATUS get_valid_pubkey(PEP_SESSION session,
377 pEp_identity* stored_identity,
378 bool* is_identity_default,
379 bool* is_user_default,
380 bool* is_address_default,
381 bool check_blacklist);