1/*
2 * Copyright (c) 2012-2014 Apple Inc. All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24//
25//  SOSCloudCircle.h
26//
27
28#ifndef _SECURITY_SOSCLOUDCIRCLE_H_
29#define _SECURITY_SOSCLOUDCIRCLE_H_
30
31#include <CoreFoundation/CoreFoundation.h>
32#include <CoreFoundation/CFArray.h>
33#include <CoreFoundation/CFError.h>
34
35// #include <SecureObjectSync/SOSPeer.h>
36
37__BEGIN_DECLS
38
39
40//
41// CFError info for propogated errors
42//
43
44extern CFStringRef kSOSErrorDomain;
45
46enum {
47    kSOSErrorPrivateKeyAbsent = 1,
48    kSOSErrorPublicKeyAbsent = 2,
49
50    kSOSErrorWrongPassword = 3,
51
52    kSOSErrorNotReady = 4, // System not yet ready (before first unlock)
53
54    kSOSErrorIncompatibleCircle = 5, // We saw an incompatible circle out there.
55};
56
57//
58// Types
59//
60
61enum {
62    kSOSCCInCircle          = 0,
63    kSOSCCNotInCircle       = 1,
64    kSOSCCRequestPending    = 2,
65    kSOSCCCircleAbsent      = 3,
66    kSOSCCError             = -1,
67};
68
69typedef int SOSCCStatus;
70
71extern const char * kSOSCCCircleChangedNotification;
72
73/*!
74 @function SOSCCSetUserCredentials
75 @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
76 @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
77 @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
78 @param error What went wrong if we returned false.
79 @discussion This call needs to be made whenever a call that updates a Cloud Circle returns an error of kSOSErrorPrivateKeyAbsent (credential timeout) or kSOSErrorPublicKeyAbsent (programmer error).
80
81     Any caller to SetUserCredential is asserting that they know the credential is correct.
82
83     If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
84     to call Set so we can recover from password change.
85 */
86
87bool SOSCCSetUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
88
89
90/*!
91 @function SOSCCTryUserCredentials
92 @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
93 @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
94 @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
95 @param error What went wrong if we returned false.
96 @discussion When one of the user credential requiring calls below (almost all) need a credential it will fail with kSOSErrorPrivateKeyAbsent. If you don't have an outside way to confirm correctness of the password we will attempt to use the passed in value and if it doesn't match the public information we currently have we'll fail.
97 */
98
99bool SOSCCTryUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
100
101/*!
102 @function SOSCCRequestDeviceID
103 @abstract Retrieves this device's IDS device ID
104 @param error What went wrong if we returned false
105 */
106CFStringRef SOSCCRequestDeviceID(CFErrorRef* error);
107
108/*!
109 @function SOSCCSetDeviceID
110 @abstract Sets this device's IDS device ID
111 @param IDS The ID to set
112 @param error What went wrong if we returned false
113 */
114bool SOSCCSetDeviceID(CFStringRef IDS, CFErrorRef* error);
115
116/*!
117 @function SOSCCRegisterUserCredentials
118 @abstract Deprecated name for SOSCCSetUserCredentials.
119 */
120bool SOSCCRegisterUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef *error);
121
122/*!
123 @function SOSCCCanAuthenticate
124 @abstract Determines whether we currently have valid credentials to authenticate a circle operation.
125 @param error What went wrong if we returned false.
126 */
127
128bool SOSCCCanAuthenticate(CFErrorRef *error);
129
130/*!
131 @function SOSCCThisDeviceIsInCircle
132 @abstract Finds and returns if this devices status in the user's circle.
133 @param error What went wrong if we returned kSOSCCError.
134 @result kSOSCCInCircle if we're in the circle.
135 @discussion If we have an error figuring out if we're in the circle we return false and the error.
136 */
137SOSCCStatus SOSCCThisDeviceIsInCircle(CFErrorRef* error);
138
139/*!
140 @function SOSCCRequestToJoinCircle
141 @abstract Requests that this device join the circle.
142 @param error What went wrong if we tried to join.
143 @result true if we pushed the request out successfully. False if there was an error.
144 @discussion Requests to join the user's circle or all the pending circles (other than his) if there are multiple pending circles.
145 */
146bool SOSCCRequestToJoinCircle(CFErrorRef* error);
147
148/*!
149 @function SOSCCRequestToJoinCircleAfterRestore
150 @abstract Requests that this device join the circle and do the magic just after restore approval.
151 @param error What went wrong if we tried to join.
152 @result true if we joined or pushed a request out. False if we failed to try.
153 @discussion Uses the cloud identity to get in the circle if it can. If it cannot it falls back on simple application.
154 */
155bool SOSCCRequestToJoinCircleAfterRestore(CFErrorRef* error);
156
157/*!
158 @function SOSCCRequestEnsureFreshParameters
159 @abstract function to help debug problems with EnsureFreshParameters
160 @param error What went wrong if we tried to refresh parameters
161 @result true if we successfully retrieved fresh parameters.  False if we failed.
162*/
163bool SOSCCRequestEnsureFreshParameters(CFErrorRef* error);
164
165/*!
166 @function SOSCCResetToOffering
167 @abstract Resets the cloud to offer this device's circle.
168 @param error What went wrong if we tried to post our circle.
169 @result true if we posted the circle successfully. False if there was an error.
170 */
171bool SOSCCResetToOffering(CFErrorRef* error);
172
173/*!
174 @function SOSCCResetToEmpty
175 @abstract Resets the cloud to a completely empty circle.
176 @param error What went wrong if we tried to post our circle.
177 @result true if we posted the circle successfully. False if there was an error.
178 */
179bool SOSCCResetToEmpty(CFErrorRef* error);
180
181/*!
182 @function SOSCCRemoveThisDeviceFromCircle
183 @abstract Removes the current device from the circle.
184 @param error What went wrong trying to remove ourselves.
185 @result true if we posted the removal. False if there was an error.
186 @discussion This removes us from the circle.
187 */
188bool SOSCCRemoveThisDeviceFromCircle(CFErrorRef* error);
189
190/*!
191 @function SOSCCBailFromCircle_BestEffort
192 @abstract Attempts to publish a retirement ticket for the current device.
193 @param error What went wrong trying to remove ourselves.
194 @result true if we posted the ticket. False if there was an error.
195 @discussion This attempts to post a retirement ticket that should
196 result in other devices removing this device from the circle.  It does so
197 with a 5 second timeout.  The only use for this call is when doing a device
198 erase.
199 */
200bool SOSCCBailFromCircle_BestEffort(uint64_t limit_in_seconds, CFErrorRef* error);
201
202/*!
203 @function SOSCCSignedOut
204 @abstract Attempts to publish a retirement ticket for the current device.
205 @param immediate If we should remove the device immediately or to leave the circle with best effort.
206 @param error What went wrong trying to remove ourselves.
207 @result true if we posted the ticket. False if there was an error.
208 @discussion This attempts to post a retirement ticket that should
209 result in other devices removing this device from the circle.  It does so
210 with a 5 second timeout or immediately.
211 */
212bool SOSCCSignedOut(bool immediate, CFErrorRef* error);
213
214/*!
215 @function SOSCCCopyApplicantPeerInfo
216 @abstract Get the list of peers wishing admittance.
217 @param error What went wrong.
218 @result Array of PeerInfos for applying peers.
219 */
220CFArrayRef SOSCCCopyApplicantPeerInfo(CFErrorRef* error);
221
222/*!
223 @function SOSCCCopyGenerationPeerInfo
224 @abstract Get the list of generation count per circle.
225 @param error What went wrong.
226 @result Array of Circle generation counts.
227 */
228CFArrayRef SOSCCCopyGenerationPeerInfo(CFErrorRef* error);
229
230/*!
231 @function SOSCCCopyValidPeerPeerInfo
232 @abstract Get the list of valid peers.
233 @param error What went wrong.
234 @result Array of PeerInfos for applying valid peers.
235 */
236CFArrayRef SOSCCCopyValidPeerPeerInfo(CFErrorRef* error);
237
238/*!
239 @function SOSCCValidateUserPublic
240 @abstract Validate whether the account's user public key is trustworthy.
241 @param error What went wrong.
242 @result true if the user public key is trusted, false if not.
243 */
244bool SOSCCValidateUserPublic(CFErrorRef *error);
245
246/*!
247 @function SOSCCCopyNotValidPeerPeerInfo
248 @abstract Get the list of not valid peers.
249 @param error What went wrong.
250 @result Array of PeerInfos for non-valid peers.
251 */
252CFArrayRef SOSCCCopyNotValidPeerPeerInfo(CFErrorRef* error);
253
254/*!
255 @function SOSCCCopyRetirementPeerInfo
256 @abstract Get the list of retired peers.
257 @param error What went wrong.
258 @result Array of PeerInfos for retired peers.
259 */
260CFArrayRef SOSCCCopyRetirementPeerInfo(CFErrorRef* error);
261
262/*!
263 @function SOSCCAcceptApplicants
264 @abstract Accepts the applicants into the circle (requires that we recently had the user enter the credentials).
265 @param applicants List of applicants to accept.
266 @param error What went wrong if we tried to post our circle.
267 @result true if we accepted the applicants. False if there was an error.
268 */
269bool SOSCCAcceptApplicants(CFArrayRef applicants, CFErrorRef* error);
270
271/*!
272 @function SOSCCRejectApplicants
273 @abstract Rejects the applications for admission (requires that we recently had the user enter the credentials).
274 @param applicants List of applicants to reject.
275 @param error What went wrong if we tried to post our circle.
276 @result true if we rejected the applicants. False if there was an error.
277 */
278bool SOSCCRejectApplicants(CFArrayRef applicants, CFErrorRef *error);
279
280/*!
281 @function SOSCCCopyPeerPeerInfo
282 @abstract Returns peers in the circle (we may not be in it).
283 @param error What went wrong trying look at the circle.
284 @result Returns a list of peers in the circle currently syncing.
285 @discussion We get the list of all peers syncing in the circle.
286 */
287CFArrayRef SOSCCCopyPeerPeerInfo(CFErrorRef* error);
288
289/*!
290 @function SOSCCGetLastDepartureReason
291 @abstract Returns the information (string, hopefully URL) that will lead to an explanation of why you have an incompatible circle.
292 @param error What went wrong if we returned NULL.
293 */
294enum DepartureReason {
295    kSOSDepartureReasonError = 0,
296    kSOSNeverLeftCircle,       // We haven't ever left a circle
297    kSOSWithdrewMembership,    // SOSCCRemoveThisDeviceFromCircle
298    kSOSMembershipRevoked,     // Via reset or remote removal.
299    kSOSLeftUntrustedCircle,   // We saw a circle we could no longer trust
300    kSOSNeverAppliedToCircle,  // We've never applied to a circle
301};
302
303enum DepartureReason SOSCCGetLastDepartureReason(CFErrorRef *error);
304
305/*!
306 @function SOSCCGetIncompatibilityInfo
307 @abstract Returns the information (string, hopefully URL) that will lead to an explinatoin of why you have an incompatible circle.
308 @param error What went wrong if we returned NULL.
309 */
310CFStringRef SOSCCCopyIncompatibilityInfo(CFErrorRef *error);
311
312typedef enum SyncWithAllPeersReason {
313    kSyncWithAllPeersOtherFail = 0,
314    kSyncWithAllPeersSuccess,
315    kSyncWithAllPeersLocked,
316} SyncWithAllPeersReason;
317
318__END_DECLS
319
320#endif
321