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