OSX/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 #if __OBJC__
  32 #import <Foundation/Foundation.h>
  33 #endif
  34
  35 #include <CoreFoundation/CoreFoundation.h>
  36 #include <CoreFoundation/CFArray.h>
  37 #include <CoreFoundation/CFSet.h>
  38 #include <CoreFoundation/CFError.h>
  39
  40 #include <Security/SecureObjectSync/SOSTypes.h>
  41 #include <Security/SecureObjectSync/SOSPeerInfo.h>
  42 #import <Security/SFSignInAnalytics.h>
  43
  44 __BEGIN_DECLS
  45
  46
  47 //
  48 // CFError info for propogated errors
  49 //
  50
  51 extern const CFStringRef kSOSErrorDomain;
  52
  53 enum {
  54     kSOSErrorPrivateKeyAbsent = 1,
  55     kSOSErrorPublicKeyAbsent = 2,
  56
  57     kSOSErrorWrongPassword = 3,
  58
  59     kSOSErrorNotReady = 4, // System not yet ready (before first unlock)
  60
  61     kSOSErrorIncompatibleCircle = 5, // We saw an incompatible circle out there.
  62     kSOSInitialSyncFailed = 6,  //we timed out when syncing during approving from another device
  63     kSOSEntitlementMissing = 7,
  64 };
  65
  66 //
  67 // Types
  68 //
  69
  70 enum {
  71     kSOSCCInCircle          = 0,
  72     kSOSCCNotInCircle       = 1,
  73     kSOSCCRequestPending    = 2,
  74     kSOSCCCircleAbsent      = 3,
  75     kSOSCCError             = -1,   // unable to determine circle status, inspect CFError to find out why
  76 };
  77
  78 typedef int SOSCCStatus;
  79
  80 extern const char * kSOSCCCircleChangedNotification;
  81 extern const char * kSOSCCViewMembershipChangedNotification;
  82 extern const char * kSOSCCInitialSyncChangedNotification;
  83 extern const char * kSOSCCHoldLockForInitialSync;
  84 extern const char * kSOSCCPeerAvailable;
  85 extern const char * kSOSCCRecoveryKeyChanged;
  86 extern const char * kSOSCCCircleOctagonKeysChangedNotification;
  87
  88 /*!
  89  @function SOSCCSetUserCredentials
  90  @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
  91  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
  92  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
  93  @param error What went wrong if we returned false.
  94  @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).
  95
  96      Any caller to SetUserCredential is asserting that they know the credential is correct.
  97
  98      If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
  99      to call Set so we can recover from password change.
 100  */
 101
 102 bool SOSCCSetUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
 103
 104
 105 /*!
 106  @function SOSCCSetUserCredentialsAndDSID
 107  @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.  Passes the DSID to ensure user credentials are passed to the correct account.
 108  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
 109  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
 110  @param dsid This is a string of a dsid associated with an account
 111  @param error What went wrong if we returned false.
 112  @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).
 113
 114  Any caller to SetUserCredential is asserting that they know the credential is correct.
 115
 116  If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
 117  to call Set so we can recover from password change.
 118  */
 119
 120 bool SOSCCSetUserCredentialsAndDSID(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFErrorRef *error);
 121 bool SOSCCSetUserCredentialsAndDSIDWithAnalytics(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFDataRef parentevent, CFErrorRef *error);
 122
 123 /*!
 124  @function SOSCCTryUserCredentials
 125  @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
 126  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
 127  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
 128  @param error What went wrong if we returned false.
 129  @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.
 130  */
 131
 132 bool SOSCCTryUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
 133
 134 /*!
 135  This variant adds the dsid to the call
 136  */
 137
 138 bool SOSCCTryUserCredentialsAndDSID(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFErrorRef *error);
 139
 140 /*!
 141  @function SOSCCRegisterUserCredentials
 142  @abstract Deprecated name for SOSCCSetUserCredentials.
 143  */
 144 bool SOSCCRegisterUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef *error);
 145
 146 /*!
 147  @function SOSCCWaitForInitialSync
 148  @abstract returns true if it waited, false if we didn't due to some error
 149  @param error Error ref
 150  @return if we waited successfully
 151  */
 152 bool SOSCCWaitForInitialSync(CFErrorRef* error);
 153 bool SOSCCWaitForInitialSyncWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 154
 155 /*!
 156  @function SOSCCCopyYetToSyncViewsList
 157  @abstract returns views not yet synced
 158  @param error error to fill in if we have one
 159  @return List of view names that we haven't synced yet.
 160  */
 161 CFArrayRef SOSCCCopyYetToSyncViewsList(CFErrorRef* error);
 162
 163 /*!
 164  @function SOSCCCanAuthenticate
 165  @abstract Determines whether we currently have valid credentials to authenticate a circle operation.
 166  @param error What went wrong if we returned false.
 167  */
 168
 169 bool SOSCCCanAuthenticate(CFErrorRef *error);
 170
 171 /*!
 172  @function SOSCCThisDeviceIsInCircle
 173  @abstract Finds and returns if this devices status in the user's circle.
 174  @param error What went wrong if we returned kSOSCCError.
 175  @result kSOSCCInCircle if we're in the circle.
 176  @discussion If we have an error figuring out if we're in the circle we return false and the error.
 177  */
 178 SOSCCStatus SOSCCThisDeviceIsInCircle(CFErrorRef* error);
 179
 180 /*!
 181  @function SOSCCThisDeviceIsInCircleNonCached
 182  @abstract Finds and returns if this devices status in the user's circle.  This call is added explicitly for CDP.
 183  @param error What went wrong if we returned kSOSCCError.
 184  @result kSOSCCInCircle if we're in the circle.
 185  @discussion If we have an error figuring out if we're in the circle we return false and the error.
 186  */
 187 SOSCCStatus SOSCCThisDeviceIsInCircleNonCached(CFErrorRef* error);
 188
 189 /*!
 190  @function SOSCCIsIcloudKeychainSyncing
 191  @abstract determines whether baseline keychain syncing is occuring (V0/V2)
 192  @result true if we're in the circle and baseline keychain syncing views
 193     (kSOSViewAutofillPasswords/kSOSViewSafariCreditCards/kSOSViewWiFi/kSOSViewOtherSyncable
 194     are enabled. false otherwise.
 195  */
 196
 197 bool SOSCCIsIcloudKeychainSyncing(void);
 198
 199 /*!
 200  @function SOSCCIsSafariSyncing
 201  @abstract determines whether Safari keychain item syncing is occuring (kSOSViewAutofillPasswords/kSOSViewSafariCreditCards)
 202  @result true if we're in the circle and the kSOSViewAutofillPasswords/kSOSViewSafariCreditCards views are enabled. false otherwise.
 203  */
 204
 205 bool SOSCCIsSafariSyncing(void);
 206
 207 /*!
 208  @function SOSCCIsAppleTVSyncing
 209  @abstract determines whether appleTV keychain syncing is occuring (kSOSViewAppleTV)
 210  @result true if we're in the circle and the kSOSViewAppleTV view is enabled. false otherwise.
 211  */
 212
 213 bool SOSCCIsAppleTVSyncing(void);
 214
 215
 216 /*!
 217  @function SOSCCIsHomeKitSyncing
 218  @abstract determines whether homekit keychain syncing is occuring (kSOSViewHomeKit)
 219  @result true if we're in the circle and the kSOSViewHomeKit view is enabled. false otherwise.
 220  */
 221
 222 bool SOSCCIsHomeKitSyncing(void);
 223
 224
 225 /*!
 226  @function SOSCCIsWiFiSyncing
 227  @abstract determines whether WiFi keychain syncing is occuring (kSOSViewWiFi)
 228  @result true if we're in the circle and the kSOSViewWiFi view is enabled. false otherwise.
 229  */
 230
 231 bool SOSCCIsWiFiSyncing(void);
 232
 233 /*!
 234  @function SOSCCIsContinuityUnlockSyncing
 235  @abstract determines whether Continuity Unlock keychain syncing is occuring (kSOSViewContinuityUnlock)
 236  @result true if we're in the circle and the kSOSViewContinuityUnlock view is enabled. false otherwise.
 237 .
 238  */
 239
 240 bool SOSCCIsContinuityUnlockSyncing(void);
 241
 242 /*!
 243  @function SOSCCRequestToJoinCircle
 244  @abstract Requests that this device join the circle.
 245  @param error What went wrong if we tried to join.
 246  @result true if we pushed the request out successfully. False if there was an error.
 247  @discussion Requests to join the user's circle or all the pending circles (other than his) if there are multiple pending circles.
 248  */
 249 bool SOSCCRequestToJoinCircle(CFErrorRef* error);
 250 bool SOSCCRequestToJoinCircleWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 251
 252
 253 /*!
 254  @function SOSCCRequestToJoinCircleAfterRestore
 255  @abstract Requests that this device join the circle and do the magic just after restore approval.
 256  @param error What went wrong if we tried to join.
 257  @result true if we joined or pushed a request out. False if we failed to try.
 258  @discussion Uses the cloud identity to get in the circle if it can. If it cannot it falls back on simple application.
 259  */
 260 bool SOSCCRequestToJoinCircleAfterRestore(CFErrorRef* error);
 261 bool SOSCCRequestToJoinCircleAfterRestoreWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 262
 263 /*!
 264  @function SOSCCRequestEnsureFreshParameters
 265  @abstract function to help debug problems with EnsureFreshParameters
 266  @param error What went wrong if we tried to refresh parameters
 267  @result true if we successfully retrieved fresh parameters.  False if we failed.
 268 */
 269 bool SOSCCRequestEnsureFreshParameters(CFErrorRef* error);
 270
 271 /*!
 272  @function SOSCCAccountSetToNew
 273  @abstract reset account to new
 274  @param error What went wrong if we tried to refresh parameters
 275  @result true if we successfully reset the account object
 276  */
 277 bool SOSCCAccountSetToNew(CFErrorRef *error);
 278
 279 /*!
 280  @function SOSCCResetToOffering
 281  @abstract Resets the cloud to offer this device's circle.
 282  @param error What went wrong if we tried to post our circle.
 283  @result true if we posted the circle successfully. False if there was an error.
 284  */
 285 bool SOSCCResetToOffering(CFErrorRef* error);
 286
 287 /*!
 288  @function SOSCCResetToEmpty
 289  @abstract Resets the cloud to a completely empty circle.
 290  @param error What went wrong if we tried to post our circle.
 291  @result true if we posted the circle successfully. False if there was an error.
 292  */
 293 bool SOSCCResetToEmpty(CFErrorRef* error);
 294 bool SOSCCResetToEmptyWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 295
 296 /*!
 297  @function SOSCCRemoveThisDeviceFromCircle
 298  @abstract Removes the current device from the circle.
 299  @param error What went wrong trying to remove ourselves.
 300  @result true if we posted the removal. False if there was an error.
 301  @discussion This removes us from the circle.
 302  */
 303 bool SOSCCRemoveThisDeviceFromCircle(CFErrorRef* error);
 304
 305 bool SOSCCRemoveThisDeviceFromCircleWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 306
 307 /*!
 308  @function SOSCCRemoveThisDeviceFromCircle
 309  @abstract Removes a list of peers from the circle.
 310  @param peerList List of peers to ensure aren't in the circle
 311  @param error What went wrong trying to remove the peers.
 312  @result true if we posted a circle with none of the peers listed as members, false if we had an error.
 313  @discussion This removes peers in the list from the circle. One likely error is
 314              that we don't have the user credentail (need to prompt for password)
 315  */
 316 bool SOSCCRemovePeersFromCircle(CFArrayRef peerList, CFErrorRef* error);
 317 bool SOSCCRemovePeersFromCircleWithAnalytics(CFArrayRef peers, CFDataRef parentEvent, CFErrorRef* error);
 318
 319 /*!
 320  @function SOSCCRemoveThisDeviceFromCircle
 321  @abstract Removes the current device from the circle.
 322  @param error What went wrong trying to remove ourselves.
 323  @result true if we posted the removal. False if there was an error.
 324  @discussion This removes us from the circle.
 325  */
 326 bool SOSCCLoggedOutOfAccount(CFErrorRef* error);
 327
 328 /*!
 329  @function SOSCCBailFromCircle_BestEffort
 330  @abstract Attempts to publish a retirement ticket for the current device.
 331  @param error What went wrong trying to remove ourselves.
 332  @result true if we posted the ticket. False if there was an error.
 333  @discussion This attempts to post a retirement ticket that should
 334  result in other devices removing this device from the circle.  It does so
 335  with a 5 second timeout.  The only use for this call is when doing a device
 336  erase.
 337  */
 338 bool SOSCCBailFromCircle_BestEffort(uint64_t limit_in_seconds, CFErrorRef* error);
 339
 340 /*!
 341  @function SOSCCSignedOut
 342  @abstract Attempts to publish a retirement ticket for the current device.
 343  @param immediate If we should remove the device immediately or to leave the circle with best effort.
 344  @param error What went wrong trying to remove ourselves.
 345  @result true if we posted the ticket. False if there was an error.
 346  @discussion This attempts to post a retirement ticket that should
 347  result in other devices removing this device from the circle.  It does so
 348  with a 5 second timeout or immediately.
 349  */
 350 bool SOSCCSignedOut(bool immediate, CFErrorRef* error);
 351
 352 /*!
 353  @function SOSCCCopyApplicantPeerInfo
 354  @abstract Get the list of peers wishing admittance.
 355  @param error What went wrong.
 356  @result Array of PeerInfos for applying peers.
 357  */
 358 CFArrayRef SOSCCCopyApplicantPeerInfo(CFErrorRef* error);
 359
 360 /*!
 361  @function SOSCCCopyGenerationPeerInfo
 362  @abstract Get the list of generation count per circle.
 363  @param error What went wrong.
 364  @result Array of Circle generation counts.
 365  */
 366 CFArrayRef SOSCCCopyGenerationPeerInfo(CFErrorRef* error);
 367
 368 /*!
 369  @function SOSCCCopyValidPeerPeerInfo
 370  @abstract Get the list of valid peers.
 371  @param error What went wrong.
 372  @result Array of PeerInfos for applying valid peers.
 373  */
 374 CFArrayRef SOSCCCopyValidPeerPeerInfo(CFErrorRef* error);
 375
 376 /*!
 377  @function SOSCCValidateUserPublic
 378  @abstract Validate whether the account's user public key is trustworthy.
 379  @param error What went wrong.
 380  @result true if the user public key is trusted, false if not.
 381  */
 382 bool SOSCCValidateUserPublic(CFErrorRef *error);
 383
 384 /*!
 385  @function SOSCCCopyNotValidPeerPeerInfo
 386  @abstract Get the list of not valid peers.
 387  @param error What went wrong.
 388  @result Array of PeerInfos for non-valid peers.
 389  */
 390 CFArrayRef SOSCCCopyNotValidPeerPeerInfo(CFErrorRef* error);
 391
 392 /*!
 393  @function SOSCCCopyRetirementPeerInfo
 394  @abstract Get the list of retired peers.
 395  @param error What went wrong.
 396  @result Array of PeerInfos for retired peers.
 397  */
 398 CFArrayRef SOSCCCopyRetirementPeerInfo(CFErrorRef* error);
 399
 400 /*!
 401  @function SOSCCCopyViewUnawarePeerInfo
 402  @abstract Copies all the peers who are in the circle but are unable to handle views.
 403  @param error What went wrong.
 404  @result   Array of peer infos.
 405  */
 406 CFArrayRef SOSCCCopyViewUnawarePeerInfo(CFErrorRef* error);
 407
 408 /*
 409  * Keys to find data in engine state dictionary
 410  */
 411 extern CFStringRef kSOSCCEngineStatePeerIDKey;
 412 extern CFStringRef kSOSCCEngineStateManifestCountKey;
 413 extern CFStringRef kSOSCCEngineStateSyncSetKey;
 414 extern CFStringRef kSOSCCEngineStateCoderKey;
 415 extern CFStringRef kSOSCCEngineStateManifestHashKey;
 416
 417 /*!
 418  @function SOSCCForEachEngineStateAsString
 419  @abstract Get a string for each peer to dump to your favorite location.
 420  @param error What went wrong.
 421  @result if we had an error.
 422  */
 423 bool SOSCCForEachEngineStateAsString(CFErrorRef* error, void (^block)(CFStringRef oneStateString));
 424
 425 /*!
 426  @function SOSCCAcceptApplicants
 427  @abstract Accepts the applicants into the circle (requires that we recently had the user enter the credentials).
 428  @param applicants List of applicants to accept.
 429  @param error What went wrong if we tried to post our circle.
 430  @result true if we accepted the applicants. False if there was an error.
 431  */
 432 bool SOSCCAcceptApplicants(CFArrayRef applicants, CFErrorRef* error);
 433
 434 /*!
 435  @function SOSCCRejectApplicants
 436  @abstract Rejects the applications for admission (requires that we recently had the user enter the credentials).
 437  @param applicants List of applicants to reject.
 438  @param error What went wrong if we tried to post our circle.
 439  @result true if we rejected the applicants. False if there was an error.
 440  */
 441 bool SOSCCRejectApplicants(CFArrayRef applicants, CFErrorRef *error);
 442
 443 /*!
 444  @function SOSCCCopyPeerPeerInfo
 445  @abstract Returns peers in the circle (we may not be in it).
 446  @param error What went wrong trying look at the circle.
 447  @result Returns a list of peers in the circle currently syncing.
 448  @discussion We get the list of all peers syncing in the circle.
 449  */
 450 CFArrayRef SOSCCCopyPeerPeerInfo(CFErrorRef* error);
 451
 452 /*
 453  * Return values for SOSCCGetLastDepartureReason
 454  */
 455 enum DepartureReason {
 456     kSOSDepartureReasonError = 0,
 457     kSOSNeverLeftCircle,       // We haven't ever left a circle
 458     kSOSWithdrewMembership,    // SOSCCRemoveThisDeviceFromCircle
 459     kSOSMembershipRevoked,     // Via reset or remote removal.
 460     kSOSLeftUntrustedCircle,   // We saw a circle we could no longer trust
 461     kSOSNeverAppliedToCircle,  // We've never applied to a circle
 462     kSOSDiscoveredRetirement,  // We discovered that we were retired.
 463     kSOSLostPrivateKey,        // We lost our private key
 464     kSOSPasswordChanged,        // We lost our public key, password change?
 465                                 // <-- add additional departure reason codes HERE!
 466         kSOSNumDepartureReasons,   // ACHTUNG: this *MUST* be the last entry - ALWAYS!
 467 };
 468
 469 /*!
 470  @function SOSCCGetLastDepartureReason
 471  @abstract Returns the code of why you left the circle.
 472  @param error What went wrong if we returned kSOSDepartureReasonError.
 473  */
 474 enum DepartureReason SOSCCGetLastDepartureReason(CFErrorRef *error);
 475
 476 /*!
 477  @function SOSCCSetLastDepartureReason
 478  @abstract Manually set the code of why the circle was left.
 479  @param reason Custom departure reason be be set.
 480  @param error What went wrong if we returned false.
 481  */
 482
 483 bool SOSCCSetLastDepartureReason(enum DepartureReason reason, CFErrorRef *error);
 484
 485 /*!
 486  @function SOSCCGetIncompatibilityInfo
 487  @abstract Returns the information (string, hopefully URL) that will lead to an explanation of why you have an incompatible circle.
 488  @param error What went wrong if we returned NULL.
 489  */
 490 CFStringRef SOSCCCopyIncompatibilityInfo(CFErrorRef *error);
 491
 492
 493 /*
 494     Views
 495
 496     Initial View List - To be expanded
 497
 498     For now for any peer joining a circle we only enable:
 499     kSOSViewKeychainV0
 500 */
 501
 502 //
 503 // -- Views that sync to os in (iOS in (7.1, 8.*) Mac OS in (10.9, 10.10)) peers
 504 //
 505
 506 // kSOSViewKeychainV0 - All items in the original iCloud Keychain are in the views listed below
 507 // It is defined by the query:
 508 // class in (genp inet keys) and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and tkid = NULL
 509
 510 // kSOSViewWiFi - class = genp and  pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = apple and svce = AirPort
 511 extern const CFStringRef kSOSViewWiFi;
 512
 513 // kSOSViewAutofillPasswords - class = inet and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.cfnetwork
 514 extern const CFStringRef kSOSViewAutofillPasswords;
 515
 516 // kSOSViewSafariCreditCards - class = genp and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.safari.credit-cards
 517 extern const CFStringRef kSOSViewSafariCreditCards;
 518
 519 // kSOSViewiCloudIdentity - class = keys and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.security.sos
 520 extern const CFStringRef kSOSViewiCloudIdentity;
 521 // End of KeychainV0 views
 522
 523 // kSOSViewBackupBagV0 - class = genp and and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.sbd
 524 // (LEAVE OUT FOR NOW) and svce = SecureBackupService pdmn = ak acct = SecureBackupPublicKeybag
 525 extern const CFStringRef kSOSViewBackupBagV0;
 526
 527 // kSOSViewOtherSyncable - An or of the following 5 queries:
 528 // class = cert and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL
 529 // class = genp and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = "apple" and svce != "AirPort"
 530 // class = genp and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp not in ("apple", "com.apple.safari.credit-cards", "com.apple.sbd")
 531 // class = inet and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp not in ("com.apple.cfnetwork")
 532 // class = keys and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp not in ("com.apple.security.sos")
 533 extern const CFStringRef kSOSViewOtherSyncable;
 534
 535 //
 536 // Views below this line all match a kSecAttrSyncViewHint attribute value that matches their name.
 537 //
 538
 539 // PCS (Protected Cloud Storage) Views
 540 extern const CFStringRef kSOSViewPCSMasterKey;
 541 extern const CFStringRef kSOSViewPCSiCloudDrive;
 542 extern const CFStringRef kSOSViewPCSPhotos;
 543 extern const CFStringRef kSOSViewPCSCloudKit;
 544 extern const CFStringRef kSOSViewPCSEscrow;
 545 extern const CFStringRef kSOSViewPCSFDE;
 546 extern const CFStringRef kSOSViewPCSMailDrop;
 547 extern const CFStringRef kSOSViewPCSiCloudBackup;
 548 extern const CFStringRef kSOSViewPCSNotes;
 549 extern const CFStringRef kSOSViewPCSiMessage;
 550 extern const CFStringRef kSOSViewPCSFeldspar;
 551 extern const CFStringRef kSOSViewPCSSharing;
 552
 553 extern const CFStringRef kSOSViewAppleTV;
 554 extern const CFStringRef kSOSViewHomeKit;
 555 extern const CFStringRef kSOSViewContinuityUnlock;
 556 extern const CFStringRef kSOSViewAccessoryPairing;
 557 extern const CFStringRef kSOSViewNanoRegistry;
 558 extern const CFStringRef kSOSViewWatchMigration;
 559 extern const CFStringRef kCKKSViewEngram;
 560 extern const CFStringRef kCKKSViewManatee;
 561 extern const CFStringRef kCKKSViewAutoUnlock;
 562 extern const CFStringRef kCKKSViewHealth;
 563 extern const CFStringRef kCKKSViewApplePay;
 564 extern const CFStringRef kCKKSViewHome;
 565
 566
 567 /*!
 568  @function SOSCCView
 569  @abstract Enable, disable or query status of a View for this peer.
 570  @param view The View for which the action should be performed.
 571  @param action The action code to take with the View
 572  @param error More description of the error if one occurred.
 573  @discussion
 574     For all actions any error return can fallback to kSOSCCGeneralViewError.  This is a catch-all until
 575     more code is written and specific additional error returns are identified.
 576     For kSOSCCViewEnable actions other possible return codes are:
 577         kSOSCCViewMember if the operation was successful and the peer has access to the View
 578         kSOSCCViewNotMember if the operation was a successful application to a View, yet the peer must be vetted by another peer.
 579         kSOSCCViewNotQualified if the device can't support prerequisite security capabilities
 580         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 581
 582     For kSOSCCViewDisable actions other possible return codes are:
 583         kSOSCCViewNotMember for successfully disabling the View
 584         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 585
 586     For kSOSCCViewQuery actions other possible return codes are:
 587         kSOSCCViewMember or kSOSCCDSNotMember for successful querying of the status for a View for this peer
 588         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 589
 590  */
 591
 592 SOSViewResultCode SOSCCView(CFStringRef view, SOSViewActionCode action, CFErrorRef *error);
 593
 594
 595 /*!
 596  @function SOSCCViewSet
 597  @abstract Enable, disable or query status of a views for this peer.
 598  @param enabledviews The views (as CFSet) for which the action should be performed.
 599  @param disabledviews TODO
 600  @discussion
 601    This call enables bulk setting of views for a peer.  This is done for convenience as well as
 602    better performance; it requires less circle changes by grouping all the view enabling/disabling.
 603
 604  Separate calls to SOSCCView is required to determine resulting view settings.
 605  */
 606
 607 bool SOSCCViewSet(CFSetRef enabledviews, CFSetRef disabledviews);
 608 bool SOSCCViewSetWithAnalytics(CFSetRef enabledviews, CFSetRef disabledviews, CFDataRef parentEvent);
 609 /*
 610  Security Attributes for PeerInfos
 611
 612  Initial View List - To be expanded
 613  */
 614
 615
 616 //
 617 // Backup APIs
 618 //
 619
 620 /*!
 621  @function SOSCCCopyMyPeerWithNewDeviceRecoverySecret
 622  @abstract Returns retained peer info for this device
 623  @param secret user provided entropy
 624  @param error What went wrong trying to register the new secret
 625  @result Returns our peer info.
 626  @discussion For miCSCs this creates a new wrapping of the view master key in the view bag protected by the secret.
 627  */
 628 SOSPeerInfoRef SOSCCCopyMyPeerWithNewDeviceRecoverySecret(CFDataRef secret, CFErrorRef *error);
 629
 630 /*!
 631  @function SOSCCRegisterSingleRecoverySecret
 632  @param aks_bag TODO
 633  @param error What went wrong trying to register the new secret
 634  @result true if we saved the bag, false if we had an error
 635  @discussion Asserts the keybag for use for backups when having a single secret. All views get backed up with this single bag.
 636  */
 637 bool SOSCCRegisterSingleRecoverySecret(CFDataRef aks_bag, bool forV0Only, CFErrorRef *error);
 638
 639
 640 /*!
 641  @function SOSCCIsThisDeviceLastBackup
 642  @param error Why this query can't be accepted.
 643  @result true if this is the last backup device, false otherwise.
 644  */
 645
 646 bool SOSCCIsThisDeviceLastBackup(CFErrorRef *error);
 647
 648 /*!
 649  @function SOSCCSetEscrowRecord
 650  @param escrow_label Account label
 651  @param tries Number of attempts
 652  @param error What went wrong trying to set the escrow label
 653  @result true if we saved the escrow record, false if we had an error
 654  @discussion persist escrow records in the account object or the peer info
 655  */
 656 bool SOSCCSetEscrowRecord(CFStringRef escrow_label, uint64_t tries, CFErrorRef *error);
 657
 658 /*!
 659  @function SOSCCCopyEscrowRecord
 660  @param error What went wrong trying to set the escrow label
 661  @result dictionary of the escrow record, false if we had an error, dictionary will be of format: [account label: <dictionary>], dictionary will contain (ex):   "Burned Recovery Attempt Attestation Date" = "[2015-08-19 15:21]";
 662                                      "Burned Recovery Attempt Count" = 8;
 663  @discussion for debugging - retrieve the escrow record
 664  */
 665 CFDictionaryRef SOSCCCopyEscrowRecord(CFErrorRef *error);
 666
 667 /*!
 668  @function SOSCCCopyApplication
 669  @param error What went wrong getting the applicant peerInfo.
 670  @result PeerInfoRef that's an applicant peerinfo to be used as the start of an HSA2 piggyback entry.
 671  */
 672
 673 SOSPeerInfoRef SOSCCCopyApplication(CFErrorRef *error);
 674
 675 /*!
 676  @function SOSCCCopyCircleJoiningBlob
 677  @param applicant The peerInfo applicant to pre-approve for membership in the circle
 678  @param error Why this peerInfo wasn't accepted.
 679  @result DER blob containing the gencount and this peerkey signature of the current circle with the applicant as a member at the gencount.
 680  */
 681 CFDataRef SOSCCCopyCircleJoiningBlob(SOSPeerInfoRef applicant, CFErrorRef *error);
 682
 683 /*!
 684  @function SOSCCJoinWithCircleJoiningBlob
 685  @param joiningBlob DER blob to be used to create a suitable circle for this pre-approved peer to join.
 686  @param error Why this peerInfo can't be accepted.
 687  @result true if this succeeded.
 688  */
 689
 690 bool SOSCCJoinWithCircleJoiningBlob(CFDataRef joiningBlob, PiggyBackProtocolVersion version, CFErrorRef *error);
 691
 692 /*!
 693  @function: bool SOSCCPeersHaveViewsEnabled(CFSetRef viewNames)
 694  @param viewNames the collection of views we want to know if other peers have enabled
 695  @result CFBooleanTrue if we are in circle and all views are enabled by at least one other peer,
 696          CFBooleanFalse if we are in circle and any of the views aren't avaialbe
 697          NULL if we have an error.
 698  */
 699 CFBooleanRef SOSCCPeersHaveViewsEnabled(CFArrayRef viewNames, CFErrorRef *error);
 700
 701 /*!
 702  @function: bool SOSCCRegisterRecoveryPublicKey(CFDataRef recovery_key, CFErrorRef *error);
 703  @param recovery_key the cf data representation of the recovery public key
 704  Can be passed in as NULL to indicate the CFDataRef should be removed from the keychain
 705  @result CFBooleanTrue if the public key was successfully stored in the syncable keychain
 706  CFBooleanFalse if securityd could not store the recovery key (locked?)
 707  NULL if we have an error.
 708  */
 709 bool SOSCCRegisterRecoveryPublicKey(CFDataRef recovery_key, CFErrorRef *error);
 710
 711 /*!
 712  @function: bool SOSCCMessageFromPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error)
 713  @param peer PeerInfo for the peer to ask about
 714  @param error failure if we fail
 715  @result true if we have a message pending that we haven't processed, false if we don't have one queued right now or an error occurred.
 716  */
 717 bool SOSCCMessageFromPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error);
 718
 719 /*!
 720  @function: bool SOSCCSendToPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error)
 721  @param peer PeerInfo for the peer to ask about
 722  @param error failure if we fail
 723  @result true if we have an attempt to sync pending that we haven't processed, false if we don't have one queued right now or an error occurred.
 724  */
 725 bool SOSCCSendToPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error);
 726
 727 #if __OBJC__
 728 /*
 729  @function: SOSCCAccountGetPublicKey
 730  @param reply fetch the current user public key as SubjectPublicKeyInfoi
 731  */
 732 void SOSCCAccountGetPublicKey(void (^reply)(BOOL trusted, NSData *data, NSError *error));
 733
 734 /*
 735  @function: SOSCCAccountGetAccountPrivateCredential
 736  @param reply fetch the current user public key as SubjectPublicKeyInfoi
 737  */
 738 void SOSCCAccountGetAccountPrivateCredential(void (^complete)(NSData *data, NSError *error));
 739
 740 void SOSCCAccountGetKeyCircleGeneration(void (^reply)(NSData *data, NSError *error));
 741
 742 CFDataRef SOSCCCopyInitialSyncData(CFErrorRef *error);
 743
 744 #endif
 745
 746 __END_DECLS
 747
 748 #endif