keychain/SecureObjectSync/SOSCloudCircle.h

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