2 * Copyright (c) 2012 Apple Computer, Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
28 #ifndef _SECURITY_SOSCLOUDCIRCLE_H_
29 #define _SECURITY_SOSCLOUDCIRCLE_H_
31 #include <CoreFoundation/CoreFoundation.h>
32 #include <CoreFoundation/CFArray.h>
33 #include <CoreFoundation/CFError.h>
35 // #include <SecureObjectSync/SOSPeer.h>
41 // CFError info for propogated errors
44 extern CFStringRef kSOSErrorDomain
;
47 kSOSErrorPrivateKeyAbsent
= 1,
48 kSOSErrorPublicKeyAbsent
= 2,
50 kSOSErrorWrongPassword
= 3,
52 kSOSErrorNotReady
= 4, // System not yet ready (before first unlock)
54 kSOSErrorIncompatibleCircle
= 5, // We saw an incompatible circle out there.
63 kSOSCCNotInCircle
= 1,
64 kSOSCCRequestPending
= 2,
65 kSOSCCCircleAbsent
= 3,
68 // Never being used, were a bad idea, have clients leaving here deprecated.
69 kSOSCCParamErr
__attribute__((deprecated
)) = -2,
70 kSOSCCMemoryErr
__attribute__((deprecated
)) = -3
73 typedef int SOSCCStatus
;
75 extern const char * kSOSCCCircleChangedNotification
;
78 @function SOSCCSetUserCredentials
79 @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
80 @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
81 @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
82 @param error What went wrong if we returned false.
83 @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).
85 Any caller to SetUserCredential is asserting that they know the credential is correct.
87 If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
88 to call Set so we can recover from password change.
91 bool SOSCCSetUserCredentials(CFStringRef user_label
, CFDataRef user_password
, CFErrorRef
* error
);
95 @function SOSCCTryUserCredentials
96 @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
97 @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
98 @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
99 @param error What went wrong if we returned false.
100 @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.
103 bool SOSCCTryUserCredentials(CFStringRef user_label
, CFDataRef user_password
, CFErrorRef
* error
);
107 @function SOSCCRegisterUserCredentials
108 @abstract Deprecated name for SOSCCSetUserCredentials.
110 bool SOSCCRegisterUserCredentials(CFStringRef user_label
, CFDataRef user_password
, CFErrorRef
*error
);
113 @function SOSCCCanAuthenticate
114 @abstract Determines whether we currently have valid credentials to authenticate a circle operation.
115 @param error What went wrong if we returned false.
118 bool SOSCCCanAuthenticate(CFErrorRef
*error
);
121 @function SOSCCThisDeviceIsInCircle
122 @abstract Finds and returns if this devices status in the user's circle.
123 @param error What went wrong if we returned kSOSCCError.
124 @result kSOSCCInCircle if we're in the circle.
125 @discussion If we have an error figuring out if we're in the circle we return false and the error.
127 SOSCCStatus
SOSCCThisDeviceIsInCircle(CFErrorRef
* error
);
130 @function SOSCCRequestToJoinCircle
131 @abstract Requests that this device join the circle.
132 @param error What went wrong if we tried to join.
133 @result true if we pushed the request out successfully. False if there was an error.
134 @discussion Requests to join the user's circle or all the pending circles (other than his) if there are multiple pending circles.
136 bool SOSCCRequestToJoinCircle(CFErrorRef
* error
);
139 @function SOSCCRequestToJoinCircleAfterRestore
140 @abstract Requests that this device join the circle and do the magic just after restore approval.
141 @param error What went wrong if we tried to join.
142 @result true if we joined or pushed a request out. False if we failed to try.
143 @discussion Uses the cloud identity to get in the circle if it can. If it cannot it falls back on simple application.
145 bool SOSCCRequestToJoinCircleAfterRestore(CFErrorRef
* error
);
148 @function SOSCCResetToOffering
149 @abstract Resets the cloud to offer this device's circle.
150 @param error What went wrong if we tried to post our circle.
151 @result true if we posted the circle successfully. False if there was an error.
153 bool SOSCCResetToOffering(CFErrorRef
* error
);
156 @function SOSCCResetToEmpty
157 @abstract Resets the cloud to a completely empty circle.
158 @param error What went wrong if we tried to post our circle.
159 @result true if we posted the circle successfully. False if there was an error.
161 bool SOSCCResetToEmpty(CFErrorRef
* error
);
164 @function SOSCCRemoveThisDeviceFromCircle
165 @abstract Removes the current device from the circle.
166 @param error What went wrong trying to remove ourselves.
167 @result true if we posted the removal. False if there was an error.
168 @discussion This removes us from the circle.
170 bool SOSCCRemoveThisDeviceFromCircle(CFErrorRef
* error
);
173 @function SOSCCBailFromCircle_BestEffort
174 @abstract Attempts to publish a retirement ticket for the current device.
175 @param error What went wrong trying to remove ourselves.
176 @result true if we posted the ticket. False if there was an error.
177 @discussion This attempts to post a retirement ticket that should
178 result in other devices removing this device from the circle. It does so
179 with a 5 second timeout. The only use for this call is when doing a device
182 bool SOSCCBailFromCircle_BestEffort(uint64_t limit_in_seconds
, CFErrorRef
* error
);
185 @function SOSCCCopyApplicantPeerInfo
186 @abstract Get the list of peers wishing admittance.
187 @param error What went wrong.
188 @result Array of PeerInfos for applying peers.
190 CFArrayRef
SOSCCCopyApplicantPeerInfo(CFErrorRef
* error
);
193 @function SOSCCAcceptApplicants
194 @abstract Accepts the applicants into the circle (requires that we recently had the user enter the credentials).
195 @param applicants List of applicants to accept.
196 @param error What went wrong if we tried to post our circle.
197 @result true if we accepted the applicants. False if there was an error.
199 bool SOSCCAcceptApplicants(CFArrayRef applicants
, CFErrorRef
* error
);
202 @function SOSCCRejectApplicants
203 @abstract Rejects the applications for admission (requires that we recently had the user enter the credentials).
204 @param applicants List of applicants to reject.
205 @param error What went wrong if we tried to post our circle.
206 @result true if we rejected the applicants. False if there was an error.
208 bool SOSCCRejectApplicants(CFArrayRef applicants
, CFErrorRef
*error
);
211 @function SOSCCCopyPeerPeerInfo
212 @abstract Returns peers in the circle (we may not be in it).
213 @param error What went wrong trying look at the circle.
214 @result Returns a list of peers in the circle currently syncing.
215 @discussion We get the list of all peers syncing in the circle.
217 CFArrayRef
SOSCCCopyPeerPeerInfo(CFErrorRef
* error
);
220 @function SOSCCGetLastDepartureReason
221 @abstract Returns the information (string, hopefully URL) that will lead to an explanation of why you have an incompatible circle.
222 @param error What went wrong if we returned NULL.
224 enum DepartureReason
{
225 kSOSDepartureReasonError
= 0,
226 kSOSNeverLeftCircle
, // We haven't ever left a circle
227 kSOSWithdrewMembership
, // SOSCCRemoveThisDeviceFromCircle
228 kSOSMembershipRevoked
, // Via reset or remote removal.
229 kSOSLeftUntrustedCircle
, // We saw a circle we could no longer trust
230 kSOSNeverAppliedToCircle
, // We've never applied to a circle
233 enum DepartureReason
SOSCCGetLastDepartureReason(CFErrorRef
*error
);
236 @function SOSCCGetIncompatibilityInfo
237 @abstract Returns the information (string, hopefully URL) that will lead to an explinatoin of why you have an incompatible circle.
238 @param error What went wrong if we returned NULL.
240 CFStringRef
SOSCCCopyIncompatibilityInfo(CFErrorRef
*error
);
242 typedef enum SyncWithAllPeersReason
{
243 kSyncWithAllPeersOtherFail
= 0,
244 kSyncWithAllPeersSuccess
,
245 kSyncWithAllPeersLocked
,
246 } SyncWithAllPeersReason
;