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