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