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