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  CFStringRef SOSEngineEnsureCopyBackupPeerForView(SOSEngineRef engine, CFStringRef backupPeerID, CFErrorRef *error);
139  
140  void logRawMessage(CFDataRef message, bool sending, uint64_t seqno);
141  
142  // TODO: TEMPORARY: Get the list of IDs for cleanup, this shouldn't be used instead transport should iterate KVS.
143  CFArrayRef SOSEngineGetPeerIDs(SOSEngineRef engine);
144  
145  CFArrayRef SOSEngineCopyPeerConfirmedDigests(SOSEngineRef engine, CFErrorRef *error);
146  
147  // Private do not use!
148  SOSDataSourceRef SOSEngineGetDataSource(SOSEngineRef engine);
149  bool SOSTestEngineSaveWithDER(SOSEngineRef engine, CFDataRef derState, CFErrorRef *error);
150  bool SOSTestEngineSave(SOSEngineRef engine, SOSTransactionRef txn, CFErrorRef *error);
151  bool SOSTestEngineLoad(SOSEngineRef engine, SOSTransactionRef txn, CFErrorRef *error);
152  CFMutableDictionaryRef derStateToDictionaryCopy(CFDataRef state, CFErrorRef *error);
153  bool SOSTestEngineSaveCoders(CFTypeRef engine, SOSTransactionRef txn, CFErrorRef *error);
154  bool TestSOSEngineLoadCoders(CFTypeRef engine, SOSTransactionRef txn, CFErrorRef *error);
155  void TestSOSEngineDoOnQueue(CFTypeRef engine, dispatch_block_t action);
156  bool TestSOSEngineDoTxnOnQueue(CFTypeRef engine, CFErrorRef *error, void(^transaction)(SOSTransactionRef txn, bool *commit));
157  CFMutableDictionaryRef TestSOSEngineGetCoders(CFTypeRef engine);
158  
159  // MARK: Sync completion notification registration
160  
161  typedef void (^SOSEnginePeerInSyncBlock)(CFStringRef peerID, CFSetRef views);
162  void SOSEngineSetSyncCompleteListener(SOSEngineRef engine, SOSEnginePeerInSyncBlock notify_block);
163  void SOSEngineSetSyncCompleteListenerQueue(SOSEngineRef engine, dispatch_queue_t notify_queue);
164  
165  // Engine State by Log
166  void SOSEngineLogState(SOSEngineRef engine);
167  
168  // Keychain/datasource items
169  // Used for the kSecAttrAccount when saving in the datasource with dsSetStateWithKey
170  // Class D [kSecAttrAccessibleAlwaysPrivate/kSecAttrAccessibleAlwaysThisDeviceOnly]
171  extern CFStringRef kSOSEngineStatev2;
172  extern CFStringRef kSOSEnginePeerStates;
173  extern CFStringRef kSOSEngineManifestCache;
174  #define kSOSEngineProtectionDomainClassD kSecAttrAccessibleAlwaysPrivate
175  // Class A [kSecAttrAccessibleWhenUnlockedThisDeviceOnly]
176  extern CFStringRef kSOSEngineCoders;
177  #define kSOSEngineProtectionDomainClassA kSecAttrAccessibleWhenUnlockedThisDeviceOnly
178  bool SOSEngineGetCodersNeedSaving(SOSEngineRef engine);
179  void SOSEngineSetCodersNeedSaving(SOSEngineRef engine, bool saved);
180  
181  extern CFStringRef kSOSEngineStateVersionKey;
182  
183  __END_DECLS
184  
185  #endif /* !_SEC_SOSENGINE_H_ */