keychain/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     KSOSCantParseSOSMessage = 8,
  66 };
  67
  68 //
  69 // Types
  70 //
  71
  72 typedef CF_OPTIONS(uint32_t, SOSInitialSyncFlags) {
  73     kSOSInitialSyncFlagTLKs = (1UL << 0),
  74     kSOSInitialSyncFlagiCloudIdentity = (1UL << 1),
  75 };
  76
  77
  78 enum {
  79     kSOSCCInCircle          = 0,
  80     kSOSCCNotInCircle       = 1,
  81     kSOSCCRequestPending    = 2,
  82     kSOSCCCircleAbsent      = 3,
  83     kSOSCCError             = -1,   // unable to determine circle status, inspect CFError to find out why
  84 };
  85
  86 typedef int SOSCCStatus;
  87
  88 extern const char * kSOSCCCircleChangedNotification;
  89 extern const char * kSOSCCViewMembershipChangedNotification;
  90 extern const char * kSOSCCInitialSyncChangedNotification;
  91 extern const char * kSOSCCHoldLockForInitialSync;
  92 extern const char * kSOSCCPeerAvailable;
  93 extern const char * kSOSCCRecoveryKeyChanged;
  94 extern const char * kSOSCCCircleOctagonKeysChangedNotification;
  95
  96 /*!
  97  @function SOSCCSetUserCredentials
  98  @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
  99  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
 100  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
 101  @param error What went wrong if we returned false.
 102  @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).
 103
 104      Any caller to SetUserCredential is asserting that they know the credential is correct.
 105
 106      If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
 107      to call Set so we can recover from password change.
 108  */
 109
 110 bool SOSCCSetUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
 111
 112
 113 /*!
 114  @function SOSCCSetUserCredentialsAndDSID
 115  @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.
 116  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
 117  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
 118  @param dsid This is a string of a dsid associated with an account
 119  @param error What went wrong if we returned false.
 120  @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).
 121
 122  Any caller to SetUserCredential is asserting that they know the credential is correct.
 123
 124  If you are uncertain (unable to verify) use TryUserCredentials, but if you can know it's better
 125  to call Set so we can recover from password change.
 126  */
 127
 128 bool SOSCCSetUserCredentialsAndDSID(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFErrorRef *error);
 129 bool SOSCCSetUserCredentialsAndDSIDWithAnalytics(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFDataRef parentevent, CFErrorRef *error);
 130
 131 /*!
 132  @function SOSCCTryUserCredentials
 133  @abstract Uses the user authentication credential (password) to create an internal EC Key Pair for authenticating Circle changes.
 134  @param user_label This string can be used for a label to tag the resulting credential data for persistent storage.
 135  @param user_password The user's password that's used as input to generate EC keys for Circle authenticating operations.
 136  @param error What went wrong if we returned false.
 137  @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.
 138  */
 139
 140 bool SOSCCTryUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef* error);
 141
 142 /*!
 143  This variant adds the dsid to the call
 144  */
 145
 146 bool SOSCCTryUserCredentialsAndDSID(CFStringRef user_label, CFDataRef user_password, CFStringRef dsid, CFErrorRef *error);
 147
 148 /*!
 149  @function SOSCCRegisterUserCredentials
 150  @abstract Deprecated name for SOSCCSetUserCredentials.
 151  */
 152 bool SOSCCRegisterUserCredentials(CFStringRef user_label, CFDataRef user_password, CFErrorRef *error);
 153
 154 /*!
 155  @function SOSCCWaitForInitialSync
 156  @abstract returns true if it waited, false if we didn't due to some error
 157  @param error Error ref
 158  @return if we waited successfully
 159  */
 160 bool SOSCCWaitForInitialSync(CFErrorRef* error);
 161 bool SOSCCWaitForInitialSyncWithAnalytics(CFDataRef parentEvent, 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 SOSCCAccountSetToNew
 265  @abstract reset account to new
 266  @param error What went wrong if we tried to refresh parameters
 267  @result true if we successfully reset the account object
 268  */
 269 bool SOSCCAccountSetToNew(CFErrorRef *error);
 270
 271 /*!
 272  @function SOSCCResetToOffering
 273  @abstract Resets the cloud to offer this device's circle.
 274  @param error What went wrong if we tried to post our circle.
 275  @result true if we posted the circle successfully. False if there was an error.
 276  */
 277 bool SOSCCResetToOffering(CFErrorRef* error);
 278
 279 /*!
 280  @function SOSCCResetToEmpty
 281  @abstract Resets the cloud to a completely empty 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 SOSCCResetToEmpty(CFErrorRef* error);
 286 bool SOSCCResetToEmptyWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 287
 288 /*!
 289  @function SOSCCRemoveThisDeviceFromCircle
 290  @abstract Removes the current device from the circle.
 291  @param error What went wrong trying to remove ourselves.
 292  @result true if we posted the removal. False if there was an error.
 293  @discussion This removes us from the circle.
 294  */
 295 bool SOSCCRemoveThisDeviceFromCircle(CFErrorRef* error);
 296
 297 bool SOSCCRemoveThisDeviceFromCircleWithAnalytics(CFDataRef parentEvent, CFErrorRef* error);
 298
 299 /*!
 300  @function SOSCCRemoveThisDeviceFromCircle
 301  @abstract Removes a list of peers from the circle.
 302  @param peerList List of peers to ensure aren't in the circle
 303  @param error What went wrong trying to remove the peers.
 304  @result true if we posted a circle with none of the peers listed as members, false if we had an error.
 305  @discussion This removes peers in the list from the circle. One likely error is
 306              that we don't have the user credentail (need to prompt for password)
 307  */
 308 bool SOSCCRemovePeersFromCircle(CFArrayRef peerList, CFErrorRef* error);
 309 bool SOSCCRemovePeersFromCircleWithAnalytics(CFArrayRef peers, CFDataRef parentEvent, CFErrorRef* error);
 310
 311 /*!
 312  @function SOSCCRemoveThisDeviceFromCircle
 313  @abstract Removes the current device from the circle.
 314  @param error What went wrong trying to remove ourselves.
 315  @result true if we posted the removal. False if there was an error.
 316  @discussion This removes us from the circle.
 317  */
 318 bool SOSCCLoggedOutOfAccount(CFErrorRef* error);
 319
 320 /*!
 321  @function SOSCCBailFromCircle_BestEffort
 322  @abstract Attempts to publish a retirement ticket for the current device.
 323  @param error What went wrong trying to remove ourselves.
 324  @result true if we posted the ticket. False if there was an error.
 325  @discussion This attempts to post a retirement ticket that should
 326  result in other devices removing this device from the circle.  It does so
 327  with a 5 second timeout.  The only use for this call is when doing a device
 328  erase.
 329  */
 330 bool SOSCCBailFromCircle_BestEffort(uint64_t limit_in_seconds, CFErrorRef* error);
 331
 332 /*!
 333  @function SOSCCCopyApplicantPeerInfo
 334  @abstract Get the list of peers wishing admittance.
 335  @param error What went wrong.
 336  @result Array of PeerInfos for applying peers.
 337  */
 338 CFArrayRef SOSCCCopyApplicantPeerInfo(CFErrorRef* error);
 339
 340 /*!
 341  @function SOSCCCopyGenerationPeerInfo
 342  @abstract Get the list of generation count per circle.
 343  @param error What went wrong.
 344  @result Array of Circle generation counts.
 345  */
 346 CFArrayRef SOSCCCopyGenerationPeerInfo(CFErrorRef* error);
 347
 348 /*!
 349  @function SOSCCCopyValidPeerPeerInfo
 350  @abstract Get the list of valid peers.
 351  @param error What went wrong.
 352  @result Array of PeerInfos for applying valid peers.
 353  */
 354 CFArrayRef SOSCCCopyValidPeerPeerInfo(CFErrorRef* error);
 355
 356 /*!
 357  @function SOSCCValidateUserPublic
 358  @abstract Validate whether the account's user public key is trustworthy.
 359  @param error What went wrong.
 360  @result true if the user public key is trusted, false if not.
 361  */
 362 bool SOSCCValidateUserPublic(CFErrorRef *error);
 363
 364 /*!
 365  @function SOSCCCopyNotValidPeerPeerInfo
 366  @abstract Get the list of not valid peers.
 367  @param error What went wrong.
 368  @result Array of PeerInfos for non-valid peers.
 369  */
 370 CFArrayRef SOSCCCopyNotValidPeerPeerInfo(CFErrorRef* error);
 371
 372 /*!
 373  @function SOSCCCopyRetirementPeerInfo
 374  @abstract Get the list of retired peers.
 375  @param error What went wrong.
 376  @result Array of PeerInfos for retired peers.
 377  */
 378 CFArrayRef SOSCCCopyRetirementPeerInfo(CFErrorRef* error);
 379
 380 /*!
 381  @function SOSCCCopyViewUnawarePeerInfo
 382  @abstract Copies all the peers who are in the circle but are unable to handle views.
 383  @param error What went wrong.
 384  @result   Array of peer infos.
 385  */
 386 CFArrayRef SOSCCCopyViewUnawarePeerInfo(CFErrorRef* error);
 387
 388 /*
 389  * Keys to find data in engine state dictionary
 390  */
 391 extern CFStringRef kSOSCCEngineStatePeerIDKey;
 392 extern CFStringRef kSOSCCEngineStateManifestCountKey;
 393 extern CFStringRef kSOSCCEngineStateSyncSetKey;
 394 extern CFStringRef kSOSCCEngineStateCoderKey;
 395 extern CFStringRef kSOSCCEngineStateManifestHashKey;
 396
 397 /*!
 398  @function SOSCCForEachEngineStateAsString
 399  @abstract Get a string for each peer to dump to your favorite location.
 400  @param error What went wrong.
 401  @result if we had an error.
 402  */
 403 bool SOSCCForEachEngineStateAsString(CFErrorRef* error, void (^block)(CFStringRef oneStateString));
 404
 405 /*!
 406  @function SOSCCAcceptApplicants
 407  @abstract Accepts the applicants into the circle (requires that we recently had the user enter the credentials).
 408  @param applicants List of applicants to accept.
 409  @param error What went wrong if we tried to post our circle.
 410  @result true if we accepted the applicants. False if there was an error.
 411  */
 412 bool SOSCCAcceptApplicants(CFArrayRef applicants, CFErrorRef* error);
 413
 414 /*!
 415  @function SOSCCRejectApplicants
 416  @abstract Rejects the applications for admission (requires that we recently had the user enter the credentials).
 417  @param applicants List of applicants to reject.
 418  @param error What went wrong if we tried to post our circle.
 419  @result true if we rejected the applicants. False if there was an error.
 420  */
 421 bool SOSCCRejectApplicants(CFArrayRef applicants, CFErrorRef *error);
 422
 423 /*!
 424  @function SOSCCCopyPeerPeerInfo
 425  @abstract Returns peers in the circle (we may not be in it).
 426  @param error What went wrong trying look at the circle.
 427  @result Returns a list of peers in the circle currently syncing.
 428  @discussion We get the list of all peers syncing in the circle.
 429  */
 430 CFArrayRef SOSCCCopyPeerPeerInfo(CFErrorRef* error);
 431
 432 /*
 433  * Return values for SOSCCGetLastDepartureReason
 434  */
 435 enum DepartureReason {
 436     kSOSDepartureReasonError = 0,
 437     kSOSNeverLeftCircle,       // We haven't ever left a circle
 438     kSOSWithdrewMembership,    // SOSCCRemoveThisDeviceFromCircle
 439     kSOSMembershipRevoked,     // Via reset or remote removal.
 440     kSOSLeftUntrustedCircle,   // We saw a circle we could no longer trust
 441     kSOSNeverAppliedToCircle,  // We've never applied to a circle
 442     kSOSDiscoveredRetirement,  // We discovered that we were retired.
 443     kSOSLostPrivateKey,        // We lost our private key
 444     kSOSPasswordChanged,        // We lost our public key, password change?
 445                                 // <-- add additional departure reason codes HERE!
 446         kSOSNumDepartureReasons,   // ACHTUNG: this *MUST* be the last entry - ALWAYS!
 447 };
 448
 449 /*!
 450  @function SOSCCGetLastDepartureReason
 451  @abstract Returns the code of why you left the circle.
 452  @param error What went wrong if we returned kSOSDepartureReasonError.
 453  */
 454 enum DepartureReason SOSCCGetLastDepartureReason(CFErrorRef *error);
 455
 456 /*!
 457  @function SOSCCSetLastDepartureReason
 458  @abstract Manually set the code of why the circle was left.
 459  @param reason Custom departure reason be be set.
 460  @param error What went wrong if we returned false.
 461  */
 462
 463 bool SOSCCSetLastDepartureReason(enum DepartureReason reason, CFErrorRef *error);
 464
 465 /*
 466     Views
 467
 468     Initial View List - To be expanded
 469
 470     For now for any peer joining a circle we only enable:
 471     kSOSViewKeychainV0
 472 */
 473
 474 //
 475 // -- Views that sync to os in (iOS in (7.1, 8.*) Mac OS in (10.9, 10.10)) peers
 476 //
 477
 478 // kSOSViewKeychainV0 - All items in the original iCloud Keychain are in the views listed below
 479 // It is defined by the query:
 480 // class in (genp inet keys) and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and tkid = NULL
 481
 482 // kSOSViewWiFi - class = genp and  pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = apple and svce = AirPort
 483 extern const CFStringRef kSOSViewWiFi;
 484
 485 // kSOSViewAutofillPasswords - class = inet and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.cfnetwork
 486 extern const CFStringRef kSOSViewAutofillPasswords;
 487
 488 // kSOSViewSafariCreditCards - class = genp and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.safari.credit-cards
 489 extern const CFStringRef kSOSViewSafariCreditCards;
 490
 491 // kSOSViewiCloudIdentity - class = keys and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.security.sos
 492 extern const CFStringRef kSOSViewiCloudIdentity;
 493 // End of KeychainV0 views
 494
 495 // kSOSViewBackupBagV0 - class = genp and and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = com.apple.sbd
 496 // (LEAVE OUT FOR NOW) and svce = SecureBackupService pdmn = ak acct = SecureBackupPublicKeybag
 497 extern const CFStringRef kSOSViewBackupBagV0;
 498
 499 // kSOSViewOtherSyncable - An or of the following 5 queries:
 500 // class = cert and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL
 501 // class = genp and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp = "apple" and svce != "AirPort"
 502 // 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")
 503 // class = inet and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp not in ("com.apple.cfnetwork")
 504 // class = keys and pdmn in (ak,ck,dk,aku,cku,dku) and vwht = NULL and agrp not in ("com.apple.security.sos")
 505 extern const CFStringRef kSOSViewOtherSyncable;
 506
 507 //
 508 // Views below this line all match a kSecAttrSyncViewHint attribute value that matches their name.
 509 //
 510
 511 // PCS (Protected Cloud Storage) Views
 512 extern const CFStringRef kSOSViewPCSMasterKey;
 513 extern const CFStringRef kSOSViewPCSiCloudDrive;
 514 extern const CFStringRef kSOSViewPCSPhotos;
 515 extern const CFStringRef kSOSViewPCSCloudKit;
 516 extern const CFStringRef kSOSViewPCSEscrow;
 517 extern const CFStringRef kSOSViewPCSFDE;
 518 extern const CFStringRef kSOSViewPCSMailDrop;
 519 extern const CFStringRef kSOSViewPCSiCloudBackup;
 520 extern const CFStringRef kSOSViewPCSNotes;
 521 extern const CFStringRef kSOSViewPCSiMessage;
 522 extern const CFStringRef kSOSViewPCSFeldspar;
 523 extern const CFStringRef kSOSViewPCSSharing;
 524
 525 extern const CFStringRef kSOSViewAppleTV;
 526 extern const CFStringRef kSOSViewHomeKit;
 527 extern const CFStringRef kSOSViewContinuityUnlock;
 528 extern const CFStringRef kSOSViewAccessoryPairing;
 529 extern const CFStringRef kSOSViewNanoRegistry;
 530 extern const CFStringRef kSOSViewWatchMigration;
 531 extern const CFStringRef kCKKSViewEngram;
 532 extern const CFStringRef kCKKSViewManatee;
 533 extern const CFStringRef kCKKSViewAutoUnlock;
 534 extern const CFStringRef kCKKSViewHealth;
 535 extern const CFStringRef kCKKSViewApplePay;
 536 extern const CFStringRef kCKKSViewHome;
 537 extern const CFStringRef kCKKSViewLimitedPeersAllowed;
 538
 539
 540 /*!
 541  @function SOSCCView
 542  @abstract Enable, disable or query status of a View for this peer.
 543  @param view The View for which the action should be performed.
 544  @param action The action code to take with the View
 545  @param error More description of the error if one occurred.
 546  @discussion
 547     For all actions any error return can fallback to kSOSCCGeneralViewError.  This is a catch-all until
 548     more code is written and specific additional error returns are identified.
 549     For kSOSCCViewEnable actions other possible return codes are:
 550         kSOSCCViewMember if the operation was successful and the peer has access to the View
 551         kSOSCCViewNotMember if the operation was a successful application to a View, yet the peer must be vetted by another peer.
 552         kSOSCCViewNotQualified if the device can't support prerequisite security capabilities
 553         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 554
 555     For kSOSCCViewDisable actions other possible return codes are:
 556         kSOSCCViewNotMember for successfully disabling the View
 557         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 558
 559     For kSOSCCViewQuery actions other possible return codes are:
 560         kSOSCCViewMember or kSOSCCDSNotMember for successful querying of the status for a View for this peer
 561         kSOSCCNoSuchView if the CFStringRef doesn't match one of the known Views
 562
 563  */
 564
 565 SOSViewResultCode SOSCCView(CFStringRef view, SOSViewActionCode action, CFErrorRef *error);
 566
 567
 568 /*!
 569  @function SOSCCViewSet
 570  @abstract Enable, disable or query status of a views for this peer.
 571  @param enabledviews The views (as CFSet) for which the action should be performed.
 572  @param disabledviews TODO
 573  @discussion
 574    This call enables bulk setting of views for a peer.  This is done for convenience as well as
 575    better performance; it requires less circle changes by grouping all the view enabling/disabling.
 576
 577  Separate calls to SOSCCView is required to determine resulting view settings.
 578  */
 579
 580 bool SOSCCViewSet(CFSetRef enabledviews, CFSetRef disabledviews);
 581 bool SOSCCViewSetWithAnalytics(CFSetRef enabledviews, CFSetRef disabledviews, CFDataRef parentEvent);
 582 /*
 583  Security Attributes for PeerInfos
 584
 585  Initial View List - To be expanded
 586  */
 587
 588
 589 //
 590 // Backup APIs
 591 //
 592
 593 /*!
 594  @function SOSCCCopyMyPeerWithNewDeviceRecoverySecret
 595  @abstract Returns retained peer info for this device
 596  @param secret user provided entropy
 597  @param error What went wrong trying to register the new secret
 598  @result Returns our peer info.
 599  @discussion For miCSCs this creates a new wrapping of the view master key in the view bag protected by the secret.
 600  */
 601 SOSPeerInfoRef SOSCCCopyMyPeerWithNewDeviceRecoverySecret(CFDataRef secret, CFErrorRef *error);
 602
 603 /*!
 604  @function SOSCopyDeviceBackupPublicKey
 605  @param entropy user provided entropy
 606  @param error what, if anything, went wrong creating the backup key
 607  @result returns the public key bytes which will be eventually generated by a call to SOSCCCopyMyPeerWithNewDeviceRecoverySecret. Note that this function does not change any state.
 608  */
 609 CFDataRef SOSCopyDeviceBackupPublicKey(CFDataRef entropy, CFErrorRef *error);
 610
 611 /*!
 612  @function SOSCCRegisterSingleRecoverySecret
 613  @param aks_bag TODO
 614  @param error What went wrong trying to register the new secret
 615  @result true if we saved the bag, false if we had an error
 616  @discussion Asserts the keybag for use for backups when having a single secret. All views get backed up with this single bag.
 617  */
 618 bool SOSCCRegisterSingleRecoverySecret(CFDataRef aks_bag, bool forV0Only, CFErrorRef *error);
 619
 620 /*!
 621  @function SOSCCCopyApplication
 622  @param error What went wrong getting the applicant peerInfo.
 623  @result PeerInfoRef that's an applicant peerinfo to be used as the start of an HSA2 piggyback entry.
 624  */
 625
 626 SOSPeerInfoRef SOSCCCopyApplication(CFErrorRef *error);
 627
 628 /*!
 629  @function SOSCCCopyCircleJoiningBlob
 630  @param applicant The peerInfo applicant to pre-approve for membership in the circle
 631  @param error Why this peerInfo wasn't accepted.
 632  @result DER blob containing the gencount and this peerkey signature of the current circle with the applicant as a member at the gencount.
 633  */
 634 CFDataRef SOSCCCopyCircleJoiningBlob(SOSPeerInfoRef applicant, CFErrorRef *error);
 635
 636 /*!
 637  @function SOSCCJoinWithCircleJoiningBlob
 638  @param joiningBlob DER blob to be used to create a suitable circle for this pre-approved peer to join.
 639  @param error Why this peerInfo can't be accepted.
 640  @result true if this succeeded.
 641  */
 642
 643 bool SOSCCJoinWithCircleJoiningBlob(CFDataRef joiningBlob, PiggyBackProtocolVersion version, CFErrorRef *error);
 644
 645 /*!
 646  @function: bool SOSCCPeersHaveViewsEnabled(CFSetRef viewNames)
 647  @param viewNames the collection of views we want to know if other peers have enabled
 648  @result CFBooleanTrue if we are in circle and all views are enabled by at least one other peer,
 649          CFBooleanFalse if we are in circle and any of the views aren't avaialbe
 650          NULL if we have an error.
 651  */
 652 CFBooleanRef SOSCCPeersHaveViewsEnabled(CFArrayRef viewNames, CFErrorRef *error);
 653
 654 /*!
 655  @function: bool SOSCCRegisterRecoveryPublicKey(CFDataRef recovery_key, CFErrorRef *error);
 656  @param recovery_key the cf data representation of the recovery public key
 657  Can be passed in as NULL to indicate the CFDataRef should be removed from the keychain
 658  @result CFBooleanTrue if the public key was successfully stored in the syncable keychain
 659  CFBooleanFalse if securityd could not store the recovery key (locked?)
 660  NULL if we have an error.
 661  */
 662 bool SOSCCRegisterRecoveryPublicKey(CFDataRef recovery_key, CFErrorRef *error);
 663
 664 /*!
 665  @function: bool SOSCCMessageFromPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error)
 666  @param peer PeerInfo for the peer to ask about
 667  @param error failure if we fail
 668  @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.
 669  */
 670 bool SOSCCMessageFromPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error);
 671
 672 /*!
 673  @function: bool SOSCCSendToPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error)
 674  @param peer PeerInfo for the peer to ask about
 675  @param error failure if we fail
 676  @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.
 677  */
 678 bool SOSCCSendToPeerIsPending(SOSPeerInfoRef peer, CFErrorRef *error);
 679
 680 #if __OBJC__
 681 /*
 682  @function: SOSCCAccountGetPublicKey
 683  @param reply fetch the current user public key as SubjectPublicKeyInfoi
 684  */
 685 void SOSCCAccountGetPublicKey(void (^reply)(BOOL trusted, NSData *data, NSError *error));
 686
 687 /*
 688  @function: SOSCCAccountGetAccountPrivateCredential
 689  @param reply fetch the current user public key as SubjectPublicKeyInfoi
 690  */
 691 void SOSCCAccountGetAccountPrivateCredential(void (^complete)(NSData *data, NSError *error));
 692
 693 void SOSCCAccountGetKeyCircleGeneration(void (^reply)(NSData *data, NSError *error));
 694
 695 void SOSCCGhostBust(SOSAccountGhostBustingOptions options, void (^complete)(bool ghostsBusted, NSError *error));
 696
 697 void SOSCCGhostBustTriggerTimed(SOSAccountGhostBustingOptions options, void (^complete)(bool ghostsBusted, NSError *error));
 698
 699 void SOSCCGhostBustInfo(void (^complete)(NSData *json, NSError *error));
 700
 701 CFDataRef SOSCCCopyInitialSyncData(SOSInitialSyncFlags flags, CFErrorRef *error);
 702
 703 NSString * SOSCCCircleHash(NSError **error);
 704
 705 #endif
 706
 707 __END_DECLS
 708
 709 #endif