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