vb@39
|
1 |
#pragma once
|
vb@39
|
2 |
|
vb@217
|
3 |
#include "pEpEngine.h"
|
vb@217
|
4 |
|
vb@0
|
5 |
#ifdef __cplusplus
|
vb@0
|
6 |
extern "C" {
|
vb@0
|
7 |
#endif
|
vb@0
|
8 |
|
vb@0
|
9 |
// update_identity() - update identity information
|
vb@0
|
10 |
//
|
vb@0
|
11 |
// parameters:
|
vb@0
|
12 |
// session (in) session to use
|
vb@0
|
13 |
// identity (inout) identity information of communication partner
|
krista@1220
|
14 |
// (identity->fpr is OUT ONLY)
|
vb@0
|
15 |
// caveat:
|
vb@10
|
16 |
// if this function returns PEP_ct_unknown or PEP_ct_key_expired in
|
vb@10
|
17 |
// identity->comm_type, the caller must insert the identity into the
|
vb@10
|
18 |
// asynchronous management implementation, so retrieve_next_identity()
|
vb@10
|
19 |
// will return this identity later
|
vb@21
|
20 |
// at least identity->address must be a non-empty UTF-8 string as input
|
vb@932
|
21 |
// update_identity() never writes flags; use set_identity_flags() for
|
vb@932
|
22 |
// writing
|
krista@1220
|
23 |
// this function NEVER reads the incoming fpr, only writes to it.
|
vb@0
|
24 |
|
vb@1387
|
25 |
DYNAMIC_API PEP_STATUS update_identity(
|
vb@0
|
26 |
PEP_SESSION session, pEp_identity * identity
|
vb@0
|
27 |
);
|
vb@0
|
28 |
|
vb@0
|
29 |
|
vb@0
|
30 |
// myself() - ensures that the own identity is being complete
|
vb@0
|
31 |
//
|
vb@0
|
32 |
// parameters:
|
vb@0
|
33 |
// session (in) session to use
|
vb@0
|
34 |
// identity (inout) identity of local user
|
vb@0
|
35 |
// at least .address, .username, .user_id must be set
|
vb@0
|
36 |
//
|
vb@0
|
37 |
// return value:
|
vb@0
|
38 |
// PEP_STATUS_OK if identity could be completed or was already complete,
|
vb@0
|
39 |
// any other value on error
|
vb@0
|
40 |
//
|
vb@0
|
41 |
// caveat:
|
vb@0
|
42 |
// this function generates a keypair on demand; because it's synchronous
|
vb@0
|
43 |
// it can need a decent amount of time to return
|
vb@0
|
44 |
// if you need to do this asynchronous, you need to return an identity
|
vb@0
|
45 |
// with retrieve_next_identity() where pEp_identity.me is true
|
vb@0
|
46 |
|
vb@0
|
47 |
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
|
vb@0
|
48 |
|
edouard@1406
|
49 |
PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
|
vb@0
|
50 |
|
vb@0
|
51 |
// retrieve_next_identity() - callback being called by do_keymanagement()
|
vb@0
|
52 |
//
|
vb@0
|
53 |
// parameters:
|
vb@0
|
54 |
// management (in) data structure to deliver (implementation defined)
|
vb@0
|
55 |
//
|
vb@0
|
56 |
// return value:
|
vb@0
|
57 |
// identity to check or NULL to terminate do_keymanagement()
|
vb@0
|
58 |
// if given identity must be created with new_identity()
|
vb@0
|
59 |
// the identity struct is going to the ownership of this library
|
vb@0
|
60 |
// it must not be freed by the callee
|
vb@0
|
61 |
//
|
vb@0
|
62 |
// caveat:
|
vb@0
|
63 |
// this callback has to block until an identity or NULL can be returned
|
vb@0
|
64 |
// an implementation is not provided by this library; instead it has to be
|
vb@0
|
65 |
// implemented by the user of this library
|
vb@0
|
66 |
|
vb@0
|
67 |
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
|
vb@0
|
68 |
|
vb@0
|
69 |
|
vb@292
|
70 |
// examine_identity() - callback for appending to queue
|
vb@292
|
71 |
//
|
vb@292
|
72 |
// parameters:
|
vb@292
|
73 |
// ident (in) identity to examine
|
vb@292
|
74 |
// management (in) data structure to deliver (implementation defined)
|
vb@292
|
75 |
//
|
vb@292
|
76 |
// return value:
|
vb@292
|
77 |
// 0 if identity was added successfully to queue or nonzero otherwise
|
vb@292
|
78 |
|
vb@296
|
79 |
typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
|
vb@292
|
80 |
|
vb@292
|
81 |
|
vb@292
|
82 |
// register_examine_function() - register examine_identity() callback
|
vb@292
|
83 |
//
|
vb@292
|
84 |
// parameters:
|
vb@292
|
85 |
// session (in) session to use
|
vb@292
|
86 |
// examine_identity (in) examine_identity() function to register
|
vb@292
|
87 |
// management (in) data structure to deliver (implementation defined)
|
vb@292
|
88 |
|
vb@296
|
89 |
DYNAMIC_API PEP_STATUS register_examine_function(
|
vb@292
|
90 |
PEP_SESSION session,
|
vb@292
|
91 |
examine_identity_t examine_identity,
|
vb@292
|
92 |
void *management
|
vb@292
|
93 |
);
|
vb@292
|
94 |
|
vb@292
|
95 |
|
vb@0
|
96 |
// do_keymanagement() - function to be run on an extra thread
|
vb@0
|
97 |
//
|
vb@0
|
98 |
// parameters:
|
vb@0
|
99 |
// retrieve_next_identity pointer to retrieve_next_identity() callback
|
vb@0
|
100 |
// which returns at least a valid address field in
|
vb@0
|
101 |
// the identity struct
|
vb@0
|
102 |
// management management data to give to keymanagement
|
vb@0
|
103 |
// (implementation defined)
|
vb@0
|
104 |
//
|
vb@0
|
105 |
// return value:
|
vb@0
|
106 |
// PEP_STATUS_OK if thread has to terminate successfully or any other
|
vb@0
|
107 |
// value on failure
|
vb@0
|
108 |
//
|
vb@0
|
109 |
// caveat:
|
vb@0
|
110 |
// to ensure proper working of this library, a thread has to be started
|
vb@0
|
111 |
// with this function immediately after initialization
|
vb@0
|
112 |
// do_keymanagement() calls retrieve_next_identity(management)
|
vb@0
|
113 |
|
vb@0
|
114 |
DYNAMIC_API PEP_STATUS do_keymanagement(
|
vb@0
|
115 |
retrieve_next_identity_t retrieve_next_identity,
|
vb@0
|
116 |
void *management
|
vb@0
|
117 |
);
|
vb@0
|
118 |
|
vb@215
|
119 |
|
krista@1213
|
120 |
// key_mistrusted() - mark key as being compromized
|
vb@215
|
121 |
//
|
vb@215
|
122 |
// parameters:
|
vb@215
|
123 |
// session (in) session to use
|
vb@357
|
124 |
// ident (in) person and key which was compromized
|
vb@215
|
125 |
|
krista@1213
|
126 |
DYNAMIC_API PEP_STATUS key_mistrusted(
|
vb@357
|
127 |
PEP_SESSION session,
|
vb@357
|
128 |
pEp_identity *ident
|
vb@357
|
129 |
);
|
vb@215
|
130 |
|
vb@215
|
131 |
|
vb@354
|
132 |
// trust_personal_key() - mark a key as trusted with a person
|
vb@354
|
133 |
//
|
vb@354
|
134 |
// parameters:
|
vb@354
|
135 |
// session (in) session to use
|
vb@354
|
136 |
// ident (in) person and key to trust in
|
vb@354
|
137 |
//
|
vb@354
|
138 |
// caveat:
|
vb@354
|
139 |
// the fields user_id, address and fpr must be supplied
|
vb@354
|
140 |
|
vb@354
|
141 |
DYNAMIC_API PEP_STATUS trust_personal_key(
|
vb@354
|
142 |
PEP_SESSION session,
|
vb@354
|
143 |
pEp_identity *ident
|
vb@354
|
144 |
);
|
vb@354
|
145 |
|
vb@354
|
146 |
|
krista@1213
|
147 |
// key_reset_trust() - undo trust_personal_key and key_mistrusted() for keys
|
vb@421
|
148 |
// we don't own
|
Edouard@410
|
149 |
//
|
Edouard@410
|
150 |
// parameters:
|
Edouard@410
|
151 |
// session (in) session to use
|
Edouard@410
|
152 |
// ident (in) person and key which was compromized
|
Edouard@410
|
153 |
|
Edouard@410
|
154 |
DYNAMIC_API PEP_STATUS key_reset_trust(
|
Edouard@410
|
155 |
PEP_SESSION session,
|
Edouard@410
|
156 |
pEp_identity *ident
|
Edouard@410
|
157 |
);
|
Edouard@410
|
158 |
|
Edouard@584
|
159 |
|
Edouard@584
|
160 |
// own_key_is_listed() - returns true id key is listed as own key
|
Edouard@584
|
161 |
//
|
Edouard@584
|
162 |
// parameters:
|
Edouard@584
|
163 |
// session (in) session to use
|
Edouard@584
|
164 |
// fpr (in) fingerprint of key to test
|
Edouard@584
|
165 |
// bool (out) flags if key is own
|
Edouard@584
|
166 |
|
Edouard@584
|
167 |
DYNAMIC_API PEP_STATUS own_key_is_listed(
|
Edouard@584
|
168 |
PEP_SESSION session,
|
Edouard@584
|
169 |
const char *fpr,
|
Edouard@584
|
170 |
bool *listed
|
Edouard@584
|
171 |
);
|
Edouard@584
|
172 |
|
Edouard@584
|
173 |
|
edouard@1412
|
174 |
// _own_identities_retrieve() - retrieve all own identities
|
edouard@1412
|
175 |
//
|
edouard@1412
|
176 |
// parameters:
|
edouard@1412
|
177 |
// session (in) session to use
|
edouard@1412
|
178 |
// own_identities (out) list of own identities
|
edouard@1412
|
179 |
// excluded_flags (int) flags to exclude from results
|
edouard@1412
|
180 |
//
|
edouard@1412
|
181 |
// caveat:
|
edouard@1412
|
182 |
// the ownership of the copy of own_identities goes to the caller
|
edouard@1412
|
183 |
|
edouard@1412
|
184 |
DYNAMIC_API PEP_STATUS _own_identities_retrieve(
|
edouard@1412
|
185 |
PEP_SESSION session,
|
edouard@1412
|
186 |
identity_list **own_identities,
|
edouard@1412
|
187 |
identity_flags_t excluded_flags
|
edouard@1412
|
188 |
);
|
edouard@1412
|
189 |
|
vb@955
|
190 |
// own_identities_retrieve() - retrieve all own identities
|
Edouard@584
|
191 |
//
|
Edouard@584
|
192 |
// parameters:
|
vb@955
|
193 |
// session (in) session to use
|
vb@955
|
194 |
// own_identities (out) list of own identities
|
Edouard@584
|
195 |
//
|
Edouard@584
|
196 |
// caveat:
|
vb@1133
|
197 |
// the ownership of the copy of own_identities goes to the caller
|
Edouard@584
|
198 |
|
vb@955
|
199 |
DYNAMIC_API PEP_STATUS own_identities_retrieve(
|
Edouard@584
|
200 |
PEP_SESSION session,
|
vb@955
|
201 |
identity_list **own_identities
|
Edouard@584
|
202 |
);
|
Edouard@410
|
203 |
|
krista@1357
|
204 |
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
|
krista@1357
|
205 |
bool *has_private);
|
krista@1357
|
206 |
|
edouard@1412
|
207 |
// _own_keys_retrieve() - retrieve all flagged keypair fingerprints
|
edouard@1412
|
208 |
//
|
edouard@1412
|
209 |
// parameters:
|
edouard@1412
|
210 |
// session (in) session to use
|
edouard@1412
|
211 |
// keylist (out) list of fingerprints
|
edouard@1412
|
212 |
// excluded_flags (int) flags to exclude from results
|
edouard@1412
|
213 |
//
|
edouard@1412
|
214 |
// caveat:
|
edouard@1412
|
215 |
// the ownership of the list goes to the caller
|
edouard@1412
|
216 |
DYNAMIC_API PEP_STATUS _own_keys_retrieve(
|
edouard@1412
|
217 |
PEP_SESSION session,
|
edouard@1412
|
218 |
stringlist_t **keylist,
|
edouard@1412
|
219 |
identity_flags_t excluded_flags
|
edouard@1412
|
220 |
);
|
edouard@1412
|
221 |
|
edouard@1394
|
222 |
// own_keys_retrieve() - retrieve all flagged keypair fingerprints
|
edouard@1370
|
223 |
//
|
edouard@1370
|
224 |
// parameters:
|
edouard@1370
|
225 |
// session (in) session to use
|
edouard@1370
|
226 |
// keylist (out) list of fingerprints
|
edouard@1370
|
227 |
//
|
edouard@1370
|
228 |
// caveat:
|
edouard@1370
|
229 |
// the ownership of the list goes to the caller
|
edouard@1394
|
230 |
DYNAMIC_API PEP_STATUS own_keys_retrieve(
|
edouard@1370
|
231 |
PEP_SESSION session,
|
edouard@1370
|
232 |
stringlist_t **keylist
|
edouard@1370
|
233 |
);
|
edouard@1370
|
234 |
|
vb@0
|
235 |
#ifdef __cplusplus
|
vb@0
|
236 |
}
|
vb@0
|
237 |
#endif
|
vb@0
|
238 |
|