OSX/sec/SOSCircle/SecureObjectSync/SOSAccount.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 /*!
  26  @header SOSAccount.h
  27  The functions provided in SOSCircle.h provide an interface to a
  28  secure object syncing circle for a single class
  29  */
  30
  31 #ifndef _SOSACCOUNT_H_
  32 #define _SOSACCOUNT_H_
  33
  34 /* Forward declarations of SOS types. */
  35 typedef struct __OpaqueSOSAccount *SOSAccountRef;
  36 typedef struct __OpaqueSOSRecoveryKeyBag *SOSRecoveryKeyBagRef;
  37
  38 #include <CoreFoundation/CoreFoundation.h>
  39
  40 #include <Security/SecureObjectSync/SOSAccountTransaction.h>
  41 #include <Security/SecureObjectSync/SOSCircle.h>
  42 #include <Security/SecureObjectSync/SOSFullPeerInfo.h>
  43 #include <Security/SecureObjectSync/SOSCloudCircle.h>
  44 #include <Security/SecureObjectSync/SOSCloudCircleInternal.h>
  45 #include <Security/SecureObjectSync/SOSTransportKeyParameter.h>
  46 #include <Security/SecureObjectSync/SOSTransportCircle.h>
  47 #include <Security/SecureObjectSync/SOSTransportMessage.h>
  48 #include <Security/SecureObjectSync/SOSRing.h>
  49 #include <Security/SecureObjectSync/SOSPeerInfoSecurityProperties.h>
  50 #include <Security/SecureObjectSync/SOSRecoveryKeyBag.h>
  51
  52 #include <dispatch/dispatch.h>
  53
  54 __BEGIN_DECLS
  55
  56 #define RETIREMENT_FINALIZATION_SECONDS (24*60*60)
  57
  58
  59 typedef void (^SOSAccountCircleMembershipChangeBlock)(SOSCircleRef new_circle,
  60                                                       CFSetRef added_peers, CFSetRef removed_peers,
  61                                                       CFSetRef added_applicants, CFSetRef removed_applicants);
  62 typedef void (^SOSAccountSyncablePeersBlock)(CFArrayRef trustedPeers, CFArrayRef addedPeers, CFArrayRef removedPeers);
  63 typedef bool (^SOSAccountWaitForInitialSyncBlock)(SOSAccountRef account);
  64 typedef void (^SOSAccountSaveBlock)(CFDataRef flattenedAccount, CFErrorRef flattenFailError);
  65
  66 SOSAccountRef SOSAccountCreate(CFAllocatorRef allocator,
  67                                CFDictionaryRef gestalt,
  68                                SOSDataSourceFactoryRef factory);
  69 SOSAccountRef SOSAccountCreateBasic(CFAllocatorRef allocator,
  70                                CFDictionaryRef gestalt,
  71                                SOSDataSourceFactoryRef factory);
  72
  73
  74 CFTypeID SOSAccountGetTypeID(void);
  75
  76 //
  77 // MARK: Persistent Encode decode
  78 //
  79
  80 SOSAccountRef SOSAccountCreateFromDER(CFAllocatorRef allocator, SOSDataSourceFactoryRef factory,
  81                                       CFErrorRef* error,
  82                                       const uint8_t** der_p, const uint8_t *der_end);
  83 SOSAccountRef SOSAccountCreateFromData(CFAllocatorRef allocator, CFDataRef circleData,
  84                                        SOSDataSourceFactoryRef factory,
  85                                        CFErrorRef* error);
  86
  87 size_t SOSAccountGetDEREncodedSize(SOSAccountRef cir, CFErrorRef *error);
  88 uint8_t* SOSAccountEncodeToDER(SOSAccountRef cir, CFErrorRef* error, const uint8_t* der, uint8_t* der_end);
  89 size_t SOSAccountGetDEREncodedSize_V3(SOSAccountRef cir, CFErrorRef *error);
  90 uint8_t* SOSAccountEncodeToDER_V3(SOSAccountRef cir, CFErrorRef* error, const uint8_t* der, uint8_t* der_end);
  91 CFDataRef SOSAccountCopyEncodedData(SOSAccountRef circle, CFAllocatorRef allocator, CFErrorRef *error);
  92 //
  93 //MARK: IDS Device ID
  94 CFStringRef SOSAccountCopyDeviceID(SOSAccountRef account, CFErrorRef *error);
  95 bool SOSAccountSetMyDSID(SOSAccountTransactionRef txn, CFStringRef IDS, CFErrorRef* errror);
  96 bool SOSAccountSendIDSTestMessage(SOSAccountRef account, CFStringRef message, CFErrorRef *error);
  97 bool SOSAccountStartPingTest(SOSAccountRef account, CFStringRef message, CFErrorRef *error);
  98 bool SOSAccountRetrieveDeviceIDFromKeychainSyncingOverIDSProxy(SOSAccountRef account, CFErrorRef *error);
  99
 100 //
 101 // MARK: Credential management
 102 //
 103
 104 SecKeyRef SOSAccountGetTrustedPublicCredential(SOSAccountRef account, CFErrorRef* error);
 105
 106 SecKeyRef SOSAccountGetPrivateCredential(SOSAccountRef account, CFErrorRef* error);
 107 CFDataRef SOSAccountGetCachedPassword(SOSAccountRef account, CFErrorRef* error);
 108
 109 void SOSAccountSetParameters(SOSAccountRef account, CFDataRef parameters);
 110
 111 void SOSAccountPurgePrivateCredential(SOSAccountRef account);
 112
 113 bool SOSAccountTryUserCredentials(SOSAccountRef account,
 114                                   CFStringRef user_account, CFDataRef user_password,
 115                                   CFErrorRef *error);
 116
 117 bool SOSAccountAssertUserCredentials(SOSAccountRef account,
 118                                      CFStringRef user_account, CFDataRef user_password,
 119                                      CFErrorRef *error);
 120
 121 bool SOSAccountRetryUserCredentials(SOSAccountRef account);
 122 void SOSAccountSetUnTrustedUserPublicKey(SOSAccountRef account, SecKeyRef publicKey);
 123
 124 bool SOSAccountGenerationSignatureUpdate(SOSAccountRef account, CFErrorRef *error);
 125
 126 //
 127 // MARK: Circle management
 128 //
 129
 130 bool SOSAccountUpdateCircle(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 131 void SOSTransportEachMessage(SOSAccountRef account, CFDictionaryRef updates, CFErrorRef *error);
 132
 133
 134 SOSCCStatus SOSAccountGetCircleStatus(SOSAccountRef account, CFErrorRef* error);
 135 CFStringRef SOSAccountGetSOSCCStatusString(SOSCCStatus status);
 136 bool SOSAccountIsInCircle(SOSAccountRef account, CFErrorRef *error);
 137 bool SOSAccountJoinCircles(SOSAccountTransactionRef aTxn, CFErrorRef* error);
 138 bool SOSAccountJoinCirclesAfterRestore(SOSAccountTransactionRef aTxn, CFErrorRef* error);
 139 bool SOSAccountLeaveCircle(SOSAccountRef account,CFErrorRef* error);
 140 bool SOSAccountRemovePeersFromCircle(SOSAccountRef account, CFArrayRef peers, CFErrorRef* error);
 141 bool SOSAccountBail(SOSAccountRef account, uint64_t limit_in_seconds, CFErrorRef* error);
 142 bool SOSAccountAcceptApplicants(SOSAccountRef account, CFArrayRef applicants, CFErrorRef* error);
 143 bool SOSAccountRejectApplicants(SOSAccountRef account, CFArrayRef applicants, CFErrorRef* error);
 144
 145 bool SOSAccountResetToOffering(SOSAccountTransactionRef aTxn, CFErrorRef* error);
 146 bool SOSAccountResetToEmpty(SOSAccountRef account, CFErrorRef* error);
 147 bool SOSValidateUserPublic(SOSAccountRef account, CFErrorRef* error);
 148
 149 void SOSAccountForEachCirclePeerExceptMe(SOSAccountRef account, void (^action)(SOSPeerInfoRef peer));
 150
 151 CFArrayRef SOSAccountCopyApplicants(SOSAccountRef account, CFErrorRef *error);
 152 CFArrayRef SOSAccountCopyGeneration(SOSAccountRef account, CFErrorRef *error);
 153 CFArrayRef SOSAccountCopyValidPeers(SOSAccountRef account, CFErrorRef *error);
 154 CFArrayRef SOSAccountCopyPeersToListenTo(SOSAccountRef account, CFErrorRef *error);
 155 CFArrayRef SOSAccountCopyNotValidPeers(SOSAccountRef account, CFErrorRef *error);
 156 CFArrayRef SOSAccountCopyRetired(SOSAccountRef account, CFErrorRef *error);
 157 CFArrayRef SOSAccountCopyViewUnaware(SOSAccountRef account, CFErrorRef *error);
 158 CFArrayRef SOSAccountCopyPeers(SOSAccountRef account, CFErrorRef *error);
 159 CFArrayRef SOSAccountCopyActivePeers(SOSAccountRef account, CFErrorRef *error);
 160 CFArrayRef SOSAccountCopyActiveValidPeers(SOSAccountRef account, CFErrorRef *error);
 161 CFArrayRef SOSAccountCopyConcurringPeers(SOSAccountRef account, CFErrorRef *error);
 162
 163 SOSFullPeerInfoRef SOSAccountCopyAccountIdentityPeerInfo(SOSAccountRef account, CFAllocatorRef allocator, CFErrorRef* error);
 164 bool SOSAccountIsAccountIdentity(SOSAccountRef account, SOSPeerInfoRef peer_info, CFErrorRef *error);
 165
 166 enum DepartureReason SOSAccountGetLastDepartureReason(SOSAccountRef account, CFErrorRef* error);
 167
 168 //
 169 // MARK: iCloud Identity
 170 //
 171 bool SOSAccountAddiCloudIdentity(SOSAccountRef account, SOSCircleRef circle, SecKeyRef user_key, CFErrorRef *error);
 172 bool SOSAccountRemoveIncompleteiCloudIdentities(SOSAccountRef account, SOSCircleRef circle, SecKeyRef privKey, CFErrorRef *error);
 173
 174 //
 175 // MARK: Save Block
 176 //
 177
 178 void SOSAccountSetSaveBlock(SOSAccountRef account, SOSAccountSaveBlock saveBlock);
 179 void SOSAccountFlattenToSaveBlock(SOSAccountRef account);
 180
 181 //
 182 // MARK: Change blocks
 183 //
 184 void SOSAccountAddChangeBlock(SOSAccountRef a, SOSAccountCircleMembershipChangeBlock changeBlock);
 185 void SOSAccountRemoveChangeBlock(SOSAccountRef a, SOSAccountCircleMembershipChangeBlock changeBlock);
 186
 187 void SOSAccountAddSyncablePeerBlock(SOSAccountRef a,
 188                                     CFStringRef ds_name,
 189                                     SOSAccountSyncablePeersBlock changeBlock);
 190
 191 //
 192 // MARK: Local device gestalt change.
 193 //
 194 bool SOSAccountUpdateGestalt(SOSAccountRef account, CFDictionaryRef new_gestalt);
 195
 196 CFDictionaryRef SOSAccountCopyGestalt(SOSAccountRef account);
 197
 198 CFDictionaryRef SOSAccountCopyV2Dictionary(SOSAccountRef account);
 199
 200 bool SOSAccountUpdateV2Dictionary(SOSAccountRef account, CFDictionaryRef newV2Dict);
 201
 202 bool SOSAccountUpdateFullPeerInfo(SOSAccountRef account, CFSetRef minimumViews, CFSetRef excludedViews);
 203
 204 SOSViewResultCode SOSAccountUpdateView(SOSAccountRef account, CFStringRef viewname, SOSViewActionCode actionCode, CFErrorRef *error);
 205
 206 SOSViewResultCode SOSAccountViewStatus(SOSAccountRef account, CFStringRef viewname, CFErrorRef *error);
 207
 208 bool SOSAccountUpdateViewSets(SOSAccountRef account, CFSetRef enabledViews, CFSetRef disabledViews);
 209
 210 void SOSAccountPendEnableViewSet(SOSAccountRef account, CFSetRef enabledViews);
 211 void SOSAccountPendDisableViewSet(SOSAccountRef account, CFSetRef disabledViews);
 212
 213
 214 SOSSecurityPropertyResultCode SOSAccountUpdateSecurityProperty(SOSAccountRef account, CFStringRef property, SOSSecurityPropertyActionCode actionCode, CFErrorRef *error);
 215
 216 SOSSecurityPropertyResultCode SOSAccountSecurityPropertyStatus(SOSAccountRef account, CFStringRef property, CFErrorRef *error);
 217
 218
 219 bool SOSAccountHandleParametersChange(SOSAccountRef account, CFDataRef updates, CFErrorRef *error);
 220
 221 //
 222 // MARK: Requests for syncing later
 223 //
 224 bool SOSAccountRequestSyncWithAllPeers(SOSAccountTransactionRef txn, CFErrorRef *error);
 225
 226 //
 227 // MARK: Outgoing/Sync functions
 228 //
 229
 230 bool SOSAccountSyncWithKVSPeerWithMessage(SOSAccountTransactionRef txn, CFStringRef peerid, CFDataRef message, CFErrorRef *error);
 231 bool SOSAccountClearPeerMessageKey(SOSAccountTransactionRef txn, CFStringRef peerID, CFErrorRef *error);
 232
 233 CF_RETURNS_RETAINED CFSetRef SOSAccountProcessSyncWithPeers(SOSAccountTransactionRef txn, CFSetRef /* CFStringRef */ peers, CFSetRef /* CFStringRef */ backupPeers, CFErrorRef *error);
 234
 235 bool SOSAccountSendIKSPSyncList(SOSAccountRef account, CFErrorRef *error);
 236 bool SOSAccountSyncWithKVSUsingIDSID(SOSAccountRef account, CFStringRef deviceID, CFErrorRef *error);
 237
 238
 239 //
 240 // MARK: Cleanup functions
 241 //
 242 bool SOSAccountCleanupAfterPeer(SOSAccountRef account, size_t seconds, SOSCircleRef circle,
 243                                 SOSPeerInfoRef cleanupPeer, CFErrorRef* error);
 244
 245 bool SOSAccountCleanupRetirementTickets(SOSAccountRef account, size_t seconds, CFErrorRef* error);
 246
 247 bool SOSAccountScanForRetired(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 248
 249 SOSCircleRef SOSAccountCloneCircleWithRetirement(SOSAccountRef account, SOSCircleRef starting_circle, CFErrorRef *error);
 250
 251 bool SOSAccountPostDebugScope(SOSAccountRef account, CFTypeRef scope, CFErrorRef *error);
 252
 253 //
 254 // MARK: Version incompatibility Functions
 255 //
 256 CFStringRef SOSAccountCopyIncompatibilityInfo(SOSAccountRef account, CFErrorRef* error);
 257
 258 //
 259 // MARK: Backup functions
 260 //
 261
 262 bool SOSAccountIsBackupRingEmpty(SOSAccountRef account, CFStringRef viewName);
 263 bool SOSAccountNewBKSBForView(SOSAccountRef account, CFStringRef viewName, CFErrorRef *error);
 264
 265 bool SOSAccountSetBackupPublicKey(SOSAccountTransactionRef aTxn, CFDataRef backupKey, CFErrorRef *error);
 266 bool SOSAccountRemoveBackupPublickey(SOSAccountTransactionRef aTxn, CFErrorRef *error);
 267 bool SOSAccountSetBSKBagForAllSlices(SOSAccountRef account, CFDataRef backupSlice, bool setupV0Only, CFErrorRef *error);
 268
 269 SOSBackupSliceKeyBagRef SOSAccountBackupSliceKeyBagForView(SOSAccountRef account, CFStringRef viewName, CFErrorRef* error);
 270
 271 bool SOSAccountIsLastBackupPeer(SOSAccountRef account, CFErrorRef *error);
 272
 273
 274 //
 275 // MARK: Recovery Public Key Functions
 276 //
 277 bool SOSAccountRegisterRecoveryPublicKey(SOSAccountTransactionRef txn, CFDataRef recovery_key, CFErrorRef *error);
 278 CFDataRef SOSAccountCopyRecoveryPublicKey(SOSAccountTransactionRef txn, CFErrorRef *error);
 279 bool SOSAccountClearRecoveryPublicKey(SOSAccountTransactionRef txn, CFDataRef recovery_key, CFErrorRef *error);
 280 bool SOSAccountSetRecoveryKey(SOSAccountRef account, CFDataRef pubData, CFErrorRef *error);
 281 bool SOSAccountRemoveRecoveryKey(SOSAccountRef account, CFErrorRef *error);
 282 SOSRecoveryKeyBagRef SOSAccountCopyRecoveryKeyBag(CFAllocatorRef allocator, SOSAccountRef account, CFErrorRef *error);
 283 CFDataRef SOSAccountCopyRecoveryPublic(CFAllocatorRef allocator, SOSAccountRef account, CFErrorRef *error);
 284 bool SOSAccountRecoveryKeyIsInBackupAndCurrentInView(SOSAccountRef account, CFStringRef viewname);
 285 bool SOSAccountSetRecoveryKeyBagEntry(CFAllocatorRef allocator, SOSAccountRef account, SOSRecoveryKeyBagRef rkbg, CFErrorRef *error);
 286 SOSRecoveryKeyBagRef SOSAccountCopyRecoveryKeyBagEntry(CFAllocatorRef allocator, SOSAccountRef account, CFErrorRef *error);
 287 void SOSAccountEnsureRecoveryRing(SOSAccountRef account);
 288
 289 //
 290 // MARK: Private functions
 291 //
 292
 293 dispatch_queue_t SOSAccountGetQueue(SOSAccountRef account);
 294
 295 typedef bool (^SOSAccountSendBlock)(CFStringRef key, CFDataRef message, CFErrorRef *error);
 296
 297 //
 298 // MARK: Utility functions
 299 //
 300
 301 CFStringRef SOSAccountCreateCompactDescription(SOSAccountRef a);
 302 CFStringRef SOSInterestListCopyDescription(CFArrayRef interests);
 303
 304 //
 305 // MARK: View Funcitons
 306 //
 307
 308 // Use these to tell the engine what views are common to myPeer and other circle peers
 309 CFArrayRef SOSCreateActiveViewIntersectionArrayForPeerID(SOSAccountRef account, CFStringRef peerID);
 310 CFDictionaryRef SOSViewsCreateActiveViewMatrixDictionary(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 311
 312 const uint8_t* der_decode_cloud_parameters(CFAllocatorRef allocator,
 313                                            CFIndex algorithmID, SecKeyRef* publicKey,
 314                                            CFDataRef *parameters,
 315                                            CFErrorRef* error,
 316                                            const uint8_t* der, const uint8_t* der_end);
 317
 318 /* CFSet <-> XPC functions */
 319 CFSetRef CreateCFSetRefFromXPCObject(xpc_object_t xpcSetDER, CFErrorRef* error);
 320 xpc_object_t CreateXPCObjectWithCFSetRef(CFSetRef setref, CFErrorRef *error);
 321
 322
 323 //
 324 // MARK: HSA2 Piggyback Support Functions
 325 //
 326
 327 SOSPeerInfoRef SOSAccountCopyApplication(SOSAccountRef account, CFErrorRef*);
 328 CFDataRef SOSAccountCopyCircleJoiningBlob(SOSAccountRef account, SOSPeerInfoRef applicant, CFErrorRef *error);
 329 bool SOSAccountJoinWithCircleJoiningBlob(SOSAccountRef account, CFDataRef joiningBlob, CFErrorRef *error);
 330
 331 //
 332 // MARK: Initial-Sync
 333 //
 334 bool SOSAccountHasCompletedInitialSync(SOSAccountRef account);
 335 CFMutableSetRef SOSAccountCopyUnsyncedInitialViews(SOSAccountRef account);
 336 bool SOSAccountHasCompletedRequiredBackupSync(SOSAccountRef account);
 337
 338 //
 339 // MARK: State Logging
 340 //
 341 void SOSAccountLogState(SOSAccountRef account);
 342 void SOSAccountLogViewState(SOSAccountRef account);
 343
 344 //
 345 // MARK: Checking other peer views
 346 //
 347
 348 CFBooleanRef SOSAccountPeersHaveViewsEnabled(SOSAccountRef account, CFArrayRef viewNames, CFErrorRef *error);
 349
 350 void SOSAccountSetTestSerialNumber(SOSAccountRef account, CFStringRef serial);
 351
 352
 353 //
 354 // MARK: Syncing status functions
 355 //
 356 bool SOSAccountMessageFromPeerIsPending(SOSAccountTransactionRef txn, SOSPeerInfoRef peer, CFErrorRef *error);
 357 bool SOSAccountSendToPeerIsPending(SOSAccountTransactionRef txn, SOSPeerInfoRef peer, CFErrorRef *error);
 358
 359 __END_DECLS
 360
 361 #endif /* !_SOSACCOUNT_H_ */