keychain/SecureObjectSync/SOSEngine.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 SOSEngine.h - Manifest managent engine and decision making for
  27  object syncing protocol.
  28  */
  29
  30 #ifndef _SEC_SOSENGINE_H_
  31 #define _SEC_SOSENGINE_H_
  32
  33 #include "keychain/SecureObjectSync/SOSDataSource.h"
  34 #include "keychain/SecureObjectSync/SOSMessage.h"
  35 #include "keychain/SecureObjectSync/SOSPeer.h"
  36 #include <dispatch/dispatch.h>
  37
  38 __BEGIN_DECLS
  39
  40 typedef void (^SOSEnginePeerMessageSentBlock)(bool success);
  41
  42 typedef struct {
  43     __unsafe_unretained SOSEnginePeerMessageSentBlock block;
  44     SOSEngineRef engine;
  45     SOSPeerRef peer;
  46     SOSCoderRef coder;
  47     SOSManifestRef local;
  48     SOSManifestRef proposed;
  49     SOSManifestRef confirmed;
  50     SOSMessageRef message;
  51 } SOSEnginePeerMessageSentCallback;
  52 void SOSEngineMessageCallCallback(SOSEnginePeerMessageSentCallback *sent, bool ok);
  53
  54 // Must always be in C or obj-c; splitting is unwise
  55 void SOSEngineMessageCallbackSetCallback(SOSEnginePeerMessageSentCallback *sent, SOSEnginePeerMessageSentBlock block);
  56
  57
  58 // Return a new engine instance for a given data source.
  59 SOSEngineRef SOSEngineCreate(SOSDataSourceRef dataSource, CFErrorRef *error);
  60
  61 // TODO: Nuke from orbit
  62 SOSManifestRef SOSEngineCopyManifest(SOSEngineRef engine, CFErrorRef *error);
  63
  64 // Return a snapshot of the current manifest of the engines data source for the views that the given peer is in.
  65 SOSManifestRef SOSEngineCopyLocalPeerManifest(SOSEngineRef engine, SOSPeerRef peer, CFErrorRef *error);
  66 SOSManifestRef SOSEngineCopyLocalPeerManifest_locked(SOSEngineRef engine, SOSPeerRef peer, CFErrorRef *error);
  67
  68 // Apply changes to all views manifests, and update all peers accordingly
  69 bool SOSEngineUpdateChanges(SOSEngineRef engine, SOSDataSourceTransactionSource source, CFArrayRef changes, CFErrorRef *error);
  70
  71 // Store manifest indexed by it's own digest.  Can be retrieved with SOSEngineGetManifestForDigest()
  72 void SOSEngineAddManifest(SOSEngineRef engine, SOSManifestRef manifest);
  73
  74 // Retrive a digest stored with SOSEngineAddManifest()
  75 SOSManifestRef SOSEngineGetManifestForDigest(SOSEngineRef engine, CFDataRef digest);
  76
  77 // Return the digest for a patched manifest (which is stored in the cache already).
  78 CFDataRef SOSEnginePatchRecordAndCopyDigest(SOSEngineRef engine, SOSManifestRef base, SOSManifestRef removals, SOSManifestRef additions, CFErrorRef *error);
  79
  80 // Copy a manifest for a key persisted in a persisted dictionary
  81 SOSManifestRef SOSEngineCopyPersistedManifest(SOSEngineRef engine, CFDictionaryRef persisted, CFStringRef key);
  82
  83 // Copy a manifest for a key persisted in a persisted dictionary
  84 CFMutableArrayRef SOSEngineCopyPersistedManifestArray(SOSEngineRef engine, CFDictionaryRef persisted, CFStringRef key, CFErrorRef *error);
  85
  86 void SOSEngineClearCache(SOSEngineRef engine);
  87
  88 // Dispose of an engine when it's no longer needed.
  89 void SOSEngineDispose(SOSEngineRef engine);
  90
  91 // Handle incoming message from a remote peer.
  92 bool SOSEngineHandleMessage(SOSEngineRef engine, CFStringRef peerID,
  93                             CFDataRef message, CFErrorRef *error);
  94
  95 // Change the set of peers we know about.  trustedPeers and untrustedPeers are arrays of SOSPeerMetaRef
  96 // trustedPeers is an array of SOSPeerMetaRef (peer SOSPeer.h), untrustedpeers is redundant as the engine
  97 // treats a trustedPeer with no views and no publicKey the same as an untrustedPeer.
  98 // TODO: Fix the documentation above this line.
  99 void SOSEngineCircleChanged(SOSEngineRef engine, CFStringRef myPeerID, CFArrayRef trustedPeers, CFArrayRef untrustedPeers);
 100
 101 // Iterate over all peers.
 102 void SOSEngineForEachPeer(SOSEngineRef engine, void (^with)(SOSPeerRef peer));
 103
 104 CF_RETURNS_RETAINED CFSetRef SOSEngineSyncWithBackupPeers(SOSEngineRef engine, CFSetRef /* CFStringRef */ peers, bool forceReset, CFErrorRef *error);
 105
 106 // Don't call this unless you know what you are doing.  If you do then still don't call it.
 107 bool SOSEngineHandleMessage_locked(SOSEngineRef engine, CFStringRef peerID, SOSMessageRef message,
 108                                    SOSTransactionRef txn, bool *commit, bool *somethingChanged, CFErrorRef *error);
 109
 110 CFDataRef SOSEngineCreateMessage_locked(SOSEngineRef engine, SOSTransactionRef txn, SOSPeerRef peer,
 111                                         CFMutableArrayRef *attributeList, CFErrorRef *error, SOSEnginePeerMessageSentCallback **sentCallback);
 112
 113 // When you're done with the *sent parameter from SOSEngineCreateMessage_locked, you must call this on the returned object
 114 void SOSEngineFreeMessageCallback(SOSEnginePeerMessageSentCallback* sentCallback);
 115
 116 // Return a SOSPeerRef for a given peer_id.
 117 SOSPeerRef SOSEngineCopyPeerWithID(SOSEngineRef engine, CFStringRef peer_id, CFErrorRef *error);
 118
 119 // Operate on a peer with a given peer_id under the engine lock
 120 bool SOSEngineForPeerID(SOSEngineRef engine, CFStringRef peer_id, CFErrorRef *error, void (^forPeer)(SOSTransactionRef txn, SOSPeerRef peer));
 121
 122 // Modify a peer inside a transaction under then engine lock and optionally force an engine state save when done.
 123 bool SOSEngineWithPeerID(SOSEngineRef engine, CFStringRef peer_id, CFErrorRef *error, void (^with)(SOSPeerRef peer, SOSCoderRef coder, SOSDataSourceRef dataSource, SOSTransactionRef txn, bool *forceSaveState));
 124
 125 bool SOSEngineInitializePeerCoder(SOSEngineRef engine, SOSFullPeerInfoRef myPeerInfo, SOSPeerInfoRef peerInfo, CFErrorRef *error);
 126
 127 // Return a message to be sent for the current state.  Returns NULL on errors,
 128 // return a zero length CFDataRef if there is nothing to send.
 129 // If *ProposedManifest is set the caller is responsible for updating their
 130 // proposed manifest upon successful transmission of the message.
 131 CFDataRef SOSEngineCreateMessageToSyncToPeer(SOSEngineRef engine, CFStringRef peerID, CFMutableArrayRef *attributeList, SOSEnginePeerMessageSentCallback **sentBlock, CFErrorRef *error);
 132
 133 CFStringRef SOSEngineGetMyID(SOSEngineRef engine);
 134 bool SOSEnginePeerDidConnect(SOSEngineRef engine, CFStringRef peerID, CFErrorRef *error);
 135 bool SOSEngineSetPeerConfirmedManifest(SOSEngineRef engine, CFStringRef backupName,
 136                                        CFDataRef keybagDigest, CFDataRef manifestData, CFErrorRef *error);
 137 CFArrayRef SOSEngineCopyBackupPeerNames(SOSEngineRef engine, CFErrorRef *error);
 138
 139 void logRawMessage(CFDataRef message, bool sending, uint64_t seqno);
 140
 141 // TODO: TEMPORARY: Get the list of IDs for cleanup, this shouldn't be used instead transport should iterate KVS.
 142 CFArrayRef SOSEngineGetPeerIDs(SOSEngineRef engine);
 143
 144 CFArrayRef SOSEngineCopyPeerConfirmedDigests(SOSEngineRef engine, CFErrorRef *error);
 145
 146 // Private do not use!
 147 SOSDataSourceRef SOSEngineGetDataSource(SOSEngineRef engine);
 148 bool SOSTestEngineSaveWithDER(SOSEngineRef engine, CFDataRef derState, CFErrorRef *error);
 149 bool SOSTestEngineSave(SOSEngineRef engine, SOSTransactionRef txn, CFErrorRef *error);
 150 bool SOSTestEngineLoad(SOSEngineRef engine, SOSTransactionRef txn, CFErrorRef *error);
 151 CFMutableDictionaryRef derStateToDictionaryCopy(CFDataRef state, CFErrorRef *error);
 152 bool SOSTestEngineSaveCoders(CFTypeRef engine, SOSTransactionRef txn, CFErrorRef *error);
 153 bool TestSOSEngineLoadCoders(CFTypeRef engine, SOSTransactionRef txn, CFErrorRef *error);
 154 void TestSOSEngineDoOnQueue(CFTypeRef engine, dispatch_block_t action);
 155 bool TestSOSEngineDoTxnOnQueue(CFTypeRef engine, CFErrorRef *error, void(^transaction)(SOSTransactionRef txn, bool *commit));
 156 CFMutableDictionaryRef TestSOSEngineGetCoders(CFTypeRef engine);
 157
 158 // MARK: Sync completion notification registration
 159
 160 typedef void (^SOSEnginePeerInSyncBlock)(CFStringRef peerID, CFSetRef views);
 161 void SOSEngineSetSyncCompleteListener(SOSEngineRef engine, SOSEnginePeerInSyncBlock notify_block);
 162 void SOSEngineSetSyncCompleteListenerQueue(SOSEngineRef engine, dispatch_queue_t notify_queue);
 163
 164 // Engine State by Log
 165 void SOSEngineLogState(SOSEngineRef engine);
 166
 167 // Keychain/datasource items
 168 // Used for the kSecAttrAccount when saving in the datasource with dsSetStateWithKey
 169 // Class D [kSecAttrAccessibleAlwaysPrivate/kSecAttrAccessibleAlwaysThisDeviceOnly]
 170 extern CFStringRef kSOSEngineStatev2;
 171 extern CFStringRef kSOSEnginePeerStates;
 172 extern CFStringRef kSOSEngineManifestCache;
 173 #define kSOSEngineProtectionDomainClassD kSecAttrAccessibleAlwaysPrivate
 174 // Class A [kSecAttrAccessibleWhenUnlockedThisDeviceOnly]
 175 extern CFStringRef kSOSEngineCoders;
 176 #define kSOSEngineProtectionDomainClassA kSecAttrAccessibleWhenUnlockedThisDeviceOnly
 177 bool SOSEngineGetCodersNeedSaving(SOSEngineRef engine);
 178 void SOSEngineSetCodersNeedSaving(SOSEngineRef engine, bool saved);
 179
 180 extern CFStringRef kSOSEngineStateVersionKey;
 181
 182 __END_DECLS
 183
 184 #endif /* !_SEC_SOSENGINE_H_ */