sec/SOSCircle/SecureObjectSync/SOSAccount.h

   1 /*
   2  * Created by Michael Brouwer on 6/22/12.
   3  * Copyright 2012 Apple Inc. All Rights Reserved.
   4  */
   5
   6 /*!
   7  @header SOSAccount.h
   8  The functions provided in SOSCircle.h provide an interface to a
   9  secure object syncing circle for a single class
  10  */
  11
  12 #ifndef _SOSACCOUNT_H_
  13 #define _SOSACCOUNT_H_
  14
  15 #include <CoreFoundation/CoreFoundation.h>
  16
  17 #include <SecureObjectSync/SOSCircle.h>
  18 #include <SecureObjectSync/SOSFullPeerInfo.h>
  19 #include <SecureObjectSync/SOSCloudCircle.h>
  20 #include <dispatch/dispatch.h>
  21
  22 __BEGIN_DECLS
  23
  24 #define RETIREMENT_FINALIZATION_SECONDS (24*60*60)
  25
  26
  27 /* Forward declarations of SOS types. */
  28 typedef struct __OpaqueSOSAccount *SOSAccountRef;
  29
  30 typedef void (^SOSAccountKeyInterestBlock)(bool getNewKeysOnly, CFArrayRef alwaysKeys, CFArrayRef afterFirstUnlockKeys, CFArrayRef unlockedKeys);
  31 typedef bool (^SOSAccountDataUpdateBlock)(CFDictionaryRef keys, CFErrorRef *error);
  32 typedef void (^SOSAccountCircleMembershipChangeBlock)(SOSCircleRef new_circle,
  33                                                       CFArrayRef added_peers, CFArrayRef removed_peers,
  34                                                       CFArrayRef added_applicants, CFArrayRef removed_applicants);
  35
  36 SOSAccountRef SOSAccountGetShared(void);
  37 SOSAccountRef SOSAccountCreate(CFAllocatorRef allocator,
  38                                CFDictionaryRef gestalt,
  39                                SOSDataSourceFactoryRef factory,
  40                                SOSAccountKeyInterestBlock interest_block,
  41                                SOSAccountDataUpdateBlock update_block);
  42
  43 //
  44 // MARK: Persistent Encode decode
  45 //
  46
  47 SOSAccountRef SOSAccountCreateFromDER(CFAllocatorRef allocator, SOSDataSourceFactoryRef factory,
  48                                       SOSAccountKeyInterestBlock interest_block, SOSAccountDataUpdateBlock update_block,
  49                                       CFErrorRef* error,
  50                                       const uint8_t** der_p, const uint8_t *der_end);
  51
  52 SOSAccountRef SOSAccountCreateFromDER_V3(CFAllocatorRef allocator,
  53                                          SOSDataSourceFactoryRef factory,
  54                                          SOSAccountKeyInterestBlock interest_block,
  55                                          SOSAccountDataUpdateBlock update_block,
  56                                          CFErrorRef* error,
  57                                          const uint8_t** der_p, const uint8_t *der_end);
  58
  59 SOSAccountRef SOSAccountCreateFromData(CFAllocatorRef allocator, CFDataRef circleData,
  60                                        SOSDataSourceFactoryRef factory,
  61                                        SOSAccountKeyInterestBlock interest_block, SOSAccountDataUpdateBlock update_block,
  62                                        CFErrorRef* error);
  63
  64 size_t SOSAccountGetDEREncodedSize(SOSAccountRef cir, CFErrorRef *error);
  65 uint8_t* SOSAccountEncodeToDER(SOSAccountRef cir, CFErrorRef* error, const uint8_t* der, uint8_t* der_end);
  66 size_t SOSAccountGetDEREncodedSize_V3(SOSAccountRef cir, CFErrorRef *error);
  67 uint8_t* SOSAccountEncodeToDER_V3(SOSAccountRef cir, CFErrorRef* error, const uint8_t* der, uint8_t* der_end);
  68 CFDataRef SOSAccountCopyEncodedData(SOSAccountRef circle, CFAllocatorRef allocator, CFErrorRef *error);
  69
  70
  71 //
  72 // MARK: Local Peer finding
  73 //
  74 SOSPeerInfoRef SOSAccountGetMyPeerInCircle(SOSAccountRef account, SOSCircleRef circle, CFErrorRef* error);
  75 SOSPeerInfoRef SOSAccountGetMyPeerInCircleNamed(SOSAccountRef account, CFStringRef circle, CFErrorRef* error);
  76
  77 SOSFullPeerInfoRef SOSAccountGetMyFullPeerInCircle(SOSAccountRef account, SOSCircleRef circle, CFErrorRef* error);
  78 SOSFullPeerInfoRef SOSAccountGetMyFullPeerInCircleNamed(SOSAccountRef account, CFStringRef name, CFErrorRef *error);
  79
  80 //
  81 // MARK: Credential management
  82 //
  83
  84 SecKeyRef SOSAccountGetPrivateCredential(SOSAccountRef account, CFErrorRef* error);
  85 void SOSAccountPurgePrivateCredential(SOSAccountRef account);
  86
  87 bool SOSAccountTryUserCredentials(SOSAccountRef account,
  88                                   CFStringRef user_account, CFDataRef user_password,
  89                                   CFErrorRef *error);
  90
  91 bool SOSAccountAssertUserCredentials(SOSAccountRef account,
  92                                      CFStringRef user_account, CFDataRef user_password,
  93                                      CFErrorRef *error);
  94
  95
  96 //
  97 // MARK: Circle management
  98 //
  99 int SOSAccountCountCircles(SOSAccountRef a);
 100
 101 void SOSAccountForEachCircle(SOSAccountRef account, void (^process)(SOSCircleRef circle));
 102
 103 SOSCircleRef SOSAccountFindCompatibleCircle(SOSAccountRef a, CFStringRef name);
 104 SOSCircleRef SOSAccountFindCircle(SOSAccountRef a, CFStringRef name, CFErrorRef *error);
 105 SOSCircleRef SOSAccountEnsureCircle(SOSAccountRef a, CFStringRef name, CFErrorRef *error);
 106 bool SOSAccountUpdateCircle(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 107
 108 bool SOSAccountModifyCircle(SOSAccountRef account,
 109                             CFStringRef circleName,
 110                             CFErrorRef *error,
 111                             void (^action)(SOSCircleRef circle));
 112
 113
 114 SOSCCStatus SOSAccountIsInCircles(SOSAccountRef account, CFErrorRef* error);
 115 bool SOSAccountJoinCircles(SOSAccountRef account, CFErrorRef* error);
 116 bool SOSAccountJoinCirclesAfterRestore(SOSAccountRef account, CFErrorRef* error);
 117 bool SOSAccountLeaveCircles(SOSAccountRef account, CFErrorRef* error);
 118 bool SOSAccountBail(SOSAccountRef account, uint64_t limit_in_seconds, CFErrorRef* error);
 119 bool SOSAccountAcceptApplicants(SOSAccountRef account, CFArrayRef applicants, CFErrorRef* error);
 120 bool SOSAccountRejectApplicants(SOSAccountRef account, CFArrayRef applicants, CFErrorRef* error);
 121
 122 bool SOSAccountResetToOffering(SOSAccountRef account, CFErrorRef* error);
 123 bool SOSAccountResetToEmpty(SOSAccountRef account, CFErrorRef* error);
 124
 125 CFArrayRef SOSAccountCopyApplicants(SOSAccountRef account, CFErrorRef *error);
 126 CFArrayRef SOSAccountCopyPeers(SOSAccountRef account, CFErrorRef *error);
 127 CFArrayRef SOSAccountCopyActivePeers(SOSAccountRef account, CFErrorRef *error);
 128 CFArrayRef SOSAccountCopyActiveValidPeers(SOSAccountRef account, CFErrorRef *error);
 129 CFArrayRef SOSAccountCopyConcurringPeers(SOSAccountRef account, CFErrorRef *error);
 130
 131 CFArrayRef SOSAccountCopyAccountIdentityPeerInfos(SOSAccountRef account, CFAllocatorRef allocator, CFErrorRef* error);
 132 bool SOSAccountIsAccountIdentity(SOSAccountRef account, SOSPeerInfoRef peer_info, CFErrorRef *error);
 133
 134 enum DepartureReason SOSAccountGetLastDepartureReason(SOSAccountRef account, CFErrorRef* error);
 135
 136 //
 137 // MARK: Change blocks
 138 //
 139 void SOSAccountAddChangeBlock(SOSAccountRef a, SOSAccountCircleMembershipChangeBlock changeBlock);
 140 void SOSAccountRemoveChangeBlock(SOSAccountRef a, SOSAccountCircleMembershipChangeBlock changeBlock);
 141
 142 //
 143 // MARK: Local device gestalt change.
 144 //
 145 bool SOSAccountUpdateGestalt(SOSAccountRef account, CFDictionaryRef new_gestalt);
 146
 147 // TODO: ds should be a SOSDataSourceFactoryRef
 148 bool SOSAccountHandleUpdates(SOSAccountRef account,
 149                              CFDictionaryRef updates,
 150                              CFErrorRef *error);
 151
 152 bool SOSAccountSyncWithPeer(SOSAccountRef account, SOSCircleRef circle, SOSPeerInfoRef thisPeer, bool* didSendData, CFErrorRef* error);
 153 bool SOSAccountSyncWithAllPeers(SOSAccountRef account, CFErrorRef *error);
 154 bool SOSAccountSyncWithAllPeersInCircle(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 155
 156 bool SOSAccountCleanupAfterPeer(SOSAccountRef account, size_t seconds, SOSCircleRef circle,
 157                                 SOSPeerInfoRef cleanupPeer, CFErrorRef* error);
 158
 159 bool SOSAccountCleanupRetirementTickets(SOSAccountRef account, size_t seconds, CFErrorRef* error);
 160
 161 bool SOSAccountScanForRetired(SOSAccountRef account, SOSCircleRef circle, CFErrorRef *error);
 162
 163 SOSCircleRef SOSAccountCloneCircleWithRetirement(SOSAccountRef account, SOSCircleRef starting_circle, CFErrorRef *error);
 164
 165 //
 166 // MARK: Version incompatibility Functions
 167 //
 168 CFStringRef SOSAccountCopyIncompatibilityInfo(SOSAccountRef account, CFErrorRef* error);
 169
 170 //
 171 // MARK: Private functions
 172 //
 173
 174 dispatch_queue_t SOSAccountGetQueue(SOSAccountRef account);
 175
 176
 177 //
 178 // MARK: Private functions for testing
 179 //
 180
 181
 182 typedef enum {
 183     kCircleKey,
 184     kMessageKey,
 185     kParametersKey,
 186     kInitialSyncKey,
 187     kRetirementKey,
 188     kAccountChangedKey,
 189     kUnknownKey,
 190 } SOSKVSKeyType;
 191
 192 extern const CFStringRef kSOSKVSKeyParametersKey;
 193 extern const CFStringRef kSOSKVSInitialSyncKey;
 194 extern const CFStringRef kSOSKVSAccountChangedKey;
 195
 196 SOSKVSKeyType SOSKVSKeyGetKeyType(CFStringRef key);
 197 SOSKVSKeyType SOSKVSKeyGetKeyTypeAndParse(CFStringRef key, CFStringRef *circle, CFStringRef *from, CFStringRef *to);
 198
 199 CFStringRef SOSCircleKeyCreateWithCircle(SOSCircleRef circle, CFErrorRef *error);
 200 CFStringRef SOSCircleKeyCreateWithName(CFStringRef name, CFErrorRef *error);
 201 CFStringRef SOSCircleKeyCopyCircleName(CFStringRef key, CFErrorRef *error);
 202
 203 CFStringRef SOSMessageKeyCopyCircleName(CFStringRef key, CFErrorRef *error);
 204 CFStringRef SOSMessageKeyCopyFromPeerName(CFStringRef messageKey, CFErrorRef *error);
 205 CFStringRef SOSMessageKeyCreateWithCircleAndPeerNames(SOSCircleRef circle, CFStringRef from_peer_name, CFStringRef to_peer_name);
 206 CFStringRef SOSMessageKeyCreateWithCircleAndPeerInfos(SOSCircleRef circle, SOSPeerInfoRef from_peer, SOSPeerInfoRef to_peer);
 207 CFStringRef SOSMessageKeyCreateWithAccountAndPeer(SOSAccountRef account, SOSCircleRef circle, CFStringRef peer_name);
 208
 209 CFStringRef SOSRetirementKeyCreateWithCircleAndPeer(SOSCircleRef circle, CFStringRef retirement_peer_name);
 210
 211 typedef void (^SOSAccountMessageProcessedBlock)(SOSCircleRef circle, CFDataRef messageIn, CFDataRef messageOut);
 212 typedef bool (^SOSAccountSendBlock)(SOSCircleRef circle, CFStringRef key, CFDataRef message, CFErrorRef *error);
 213
 214 void SOSAccountSetMessageProcessedBlock(SOSAccountRef account, SOSAccountMessageProcessedBlock processedBlock);
 215
 216 //
 217 // MARK: Utility functions
 218 //
 219
 220 CFStringRef SOSInterestListCopyDescription(CFArrayRef interests);
 221
 222 __END_DECLS
 223
 224 #endif /* !_SOSACCOUNT_H_ */