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