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