Security/sec/SOSCircle/SecureObjectSync/SOSCloudCircle.h

   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
  44 extern CFStringRef kSOSErrorDomain;
  45
  46 enum {
  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
  61 enum {
  62     kSOSCCInCircle          = 0,
  63     kSOSCCNotInCircle       = 1,
  64     kSOSCCRequestPending    = 2,
  65     kSOSCCCircleAbsent      = 3,
  66     kSOSCCError             = -1,
  67 };
  68
  69 typedef int SOSCCStatus;
  70
  71 extern 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
  87 bool 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
  99 bool 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  */
 106 CFStringRef 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  */
 114 bool SOSCCSetDeviceID(CFStringRef IDS, CFErrorRef* error);
 115
 116 /*!
 117  @function SOSCCRegisterUserCredentials
 118  @abstract Deprecated name for SOSCCSetUserCredentials.
 119  */
 120 bool 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
 128 bool 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  */
 137 SOSCCStatus 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  */
 146 bool 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  */
 155 bool 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 */
 163 bool 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  */
 171 bool 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  */
 179 bool 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  */
 188 bool 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  */
 200 bool 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  */
 212 bool 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  */
 220 CFArrayRef 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  */
 228 CFArrayRef 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  */
 236 CFArrayRef 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  */
 244 bool 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  */
 252 CFArrayRef 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  */
 260 CFArrayRef 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  */
 269 bool 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  */
 278 bool 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  */
 287 CFArrayRef 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  */
 294 enum 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
 303 enum 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  */
 310 CFStringRef SOSCCCopyIncompatibilityInfo(CFErrorRef *error);
 311
 312 typedef enum SyncWithAllPeersReason {
 313     kSyncWithAllPeersOtherFail = 0,
 314     kSyncWithAllPeersSuccess,
 315     kSyncWithAllPeersLocked,
 316 } SyncWithAllPeersReason;
 317
 318 __END_DECLS
 319
 320 #endif