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