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