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