OSX/sec/SOSCircle/SecureObjectSync/SOSDataSource.h

   1 /*
   2  * Copyright (c) 2013-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 SOSDataSource.h
  27  The functions provided in SOSDataSource.h provide the protocol to a
  28  secure object syncing data source.  This is something than can produce
  29  manifests and manifest digests and query objects by digest and merge
  30  objects into the data source.
  31  */
  32
  33 #ifndef _SEC_SOSDATASOURCE_H_
  34 #define _SEC_SOSDATASOURCE_H_
  35
  36 #include <Security/SecureObjectSync/SOSManifest.h>
  37 #include <Security/SecureObjectSync/SOSCloudCircle.h>
  38 #include <utilities/array_size.h>
  39 #include <utilities/SecCFRelease.h>
  40
  41 __BEGIN_DECLS
  42
  43 /* SOSDataSource protocol (non opaque). */
  44 typedef struct SOSDataSourceFactory *SOSDataSourceFactoryRef;
  45 typedef struct SOSDataSource *SOSDataSourceRef;
  46 typedef struct __OpaqueSOSEngine *SOSEngineRef;
  47 typedef struct __OpaqueSOSObject *SOSObjectRef;
  48 typedef struct __OpaqueSOSTransaction *SOSTransactionRef;
  49
  50 //
  51 // MARK: - SOSDataSourceFactory protocol
  52 //
  53 struct SOSDataSourceFactory {
  54     CFStringRef      (*copy_name)(SOSDataSourceFactoryRef factory);
  55     SOSDataSourceRef (*create_datasource)(SOSDataSourceFactoryRef factory, CFStringRef dataSourceName, CFErrorRef *error);
  56     void             (*release)(SOSDataSourceFactoryRef factory);
  57     void             (*circle_changed)(SOSDataSourceFactoryRef factory, CFStringRef myPeerID, CFArrayRef trustedPeerIDs, CFArrayRef untrustedPeerIDs);
  58 };
  59
  60 static inline CFStringRef SOSDataSourceFactoryCopyName(SOSDataSourceFactoryRef dsf) {
  61     return dsf->copy_name(dsf);
  62 }
  63
  64 static inline SOSDataSourceRef SOSDataSourceFactoryCreateDataSource(SOSDataSourceFactoryRef dsf, CFStringRef dataSourceName, CFErrorRef *error) {
  65     return dsf->create_datasource(dsf, dataSourceName, error);
  66 }
  67
  68 static inline void SOSDataSourceFactoryRelease(SOSDataSourceFactoryRef dsf) {
  69     dsf->release(dsf);
  70 }
  71
  72 static inline void SOSDataSourceFactoryCircleChanged(SOSDataSourceFactoryRef dsf, CFStringRef myPeerID, CFArrayRef trustedPeerIDs, CFArrayRef untrustedPeerIDs) {
  73     dsf->circle_changed(dsf, myPeerID, trustedPeerIDs, untrustedPeerIDs);
  74 }
  75
  76
  77 //
  78 // MARK: - SOSDataSource protocol
  79 //
  80
  81 /* Implement this if you want to create a new type of sync client.
  82    Currently we support keychains, but the engine should scale to
  83    entire filesystems. */
  84 enum SOSMergeResult {
  85     kSOSMergeFailure = 0,   // CFErrorRef returned, no error returned in any other case
  86     kSOSMergeLocalObject,   // We choose the current object in the dataSource the manifest is still valid.
  87     kSOSMergePeersObject,   // We chose the peers object over our own, manifest is now dirty.
  88     kSOSMergeCreatedObject, // *createdObject is returned and should be released
  89 };
  90 typedef CFIndex SOSMergeResult;
  91
  92 //
  93 // MARK: SOSDataSourceTransactionType
  94 //
  95 enum SOSDataSourceTransactionType {
  96     kSOSDataSourceNoneTransactionType = 0,
  97     kSOSDataSourceImmediateTransactionType,
  98     kSOSDataSourceExclusiveTransactionType,
  99     kSOSDataSourceNormalTransactionType,
 100     kSOSDataSourceExclusiveRemoteTransactionType,
 101 };
 102 typedef CFOptionFlags SOSDataSourceTransactionType;
 103
 104 enum SOSDataSourceTransactionPhase {
 105     kSOSDataSourceTransactionDidRollback = 0,   // A transaction just got rolled back
 106     kSOSDataSourceTransactionWillCommit,        // A transaction is about to commit.
 107     kSOSDataSourceTransactionDidCommit,         // A transnaction sucessfully committed.
 108 };
 109 typedef CFOptionFlags SOSDataSourceTransactionPhase;
 110
 111 enum SOSDataSourceTransactionSource {
 112     kSOSDataSourceSOSTransaction,        // A remotely initated transaction.
 113     kSOSDataSourceAPITransaction,        // A user initated transaction.
 114 };
 115 typedef CFOptionFlags SOSDataSourceTransactionSource;
 116
 117 typedef void (^SOSDataSourceNotifyBlock)(SOSDataSourceRef ds, SOSTransactionRef txn, SOSDataSourceTransactionPhase phase, SOSDataSourceTransactionSource source, CFArrayRef changes);
 118
 119 //
 120 // MARK: - SOSDataSource struct
 121 //
 122
 123 struct SOSDataSource {
 124     // SOSEngine - every datasource has an engine that is notified of changes
 125     // to the datasource.
 126     SOSEngineRef engine;
 127
 128     // General SOSDataSource methods
 129     CFStringRef (*dsGetName)(SOSDataSourceRef ds);
 130     void (*dsSetNotifyPhaseBlock)(SOSDataSourceRef ds, dispatch_queue_t queue, SOSDataSourceNotifyBlock notifyBlock);
 131     SOSManifestRef (*dsCopyManifestWithViewNameSet)(SOSDataSourceRef ds, CFSetRef viewNameSet, CFErrorRef *error);
 132     bool (*dsForEachObject)(SOSDataSourceRef ds, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef key, SOSObjectRef object, bool *stop));
 133     CFDataRef (*dsCopyStateWithKey)(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, CFErrorRef *error);
 134     CFDataRef (*dsCopyItemDataWithKeys)(SOSDataSourceRef ds, CFDictionaryRef keys, CFErrorRef *error);
 135
 136     bool (*dsWith)(SOSDataSourceRef ds, CFErrorRef *error, SOSDataSourceTransactionSource source, void(^transaction)(SOSTransactionRef txn, bool *commit));
 137     bool (*dsRelease)(SOSDataSourceRef ds, CFErrorRef *error); // Destructor
 138
 139     // SOSTransaction methods, writes to a dataSource require a transaction.
 140     SOSMergeResult (*dsMergeObject)(SOSTransactionRef txn, SOSObjectRef object, SOSObjectRef *createdObject, CFErrorRef *error);
 141     bool (*dsSetStateWithKey)(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef pdmn, CFStringRef key, CFDataRef state, CFErrorRef *error);
 142     bool (*dsRestoreObject)(SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error);
 143
 144     // SOSObject methods
 145     CFDataRef (*objectCopyDigest)(SOSObjectRef object, CFErrorRef *error);
 146     SOSObjectRef (*objectCreateWithPropertyList)(CFDictionaryRef plist, CFErrorRef *error);
 147     CFDictionaryRef (*objectCopyPropertyList)(SOSObjectRef object, CFErrorRef *error);
 148     CFDictionaryRef (*objectCopyBackup)(SOSObjectRef object, uint64_t handle, CFErrorRef *error);
 149 };
 150
 151 //
 152 // MARK: - SOSDataSource protocol implementation
 153 //
 154 static inline SOSEngineRef SOSDataSourceGetSharedEngine(SOSDataSourceRef ds, CFErrorRef *error) {
 155     return ds->engine;
 156 }
 157
 158 static inline CFStringRef SOSDataSourceGetName(SOSDataSourceRef ds) {
 159     return ds->dsGetName(ds);
 160 }
 161
 162 static inline void SOSDataSourceSetNotifyPhaseBlock(SOSDataSourceRef ds, dispatch_queue_t queue, SOSDataSourceNotifyBlock notifyBlock) {
 163     ds->dsSetNotifyPhaseBlock(ds, queue, notifyBlock);
 164 }
 165
 166 static inline SOSManifestRef SOSDataSourceCopyManifestWithViewNameSet(SOSDataSourceRef ds, CFSetRef viewNameSet, CFErrorRef *error) {
 167     return ds->dsCopyManifestWithViewNameSet(ds, viewNameSet, error);
 168 }
 169
 170 static inline bool SOSDataSourceForEachObject(SOSDataSourceRef ds, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef digest, SOSObjectRef object, bool *stop)) {
 171     return ds->dsForEachObject(ds, manifest, error, handleObject);
 172 }
 173
 174 static inline bool SOSDataSourceWith(SOSDataSourceRef ds, CFErrorRef *error,
 175                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 176     return ds->dsWith(ds, error, kSOSDataSourceSOSTransaction, transaction);
 177 }
 178
 179 static inline bool SOSDataSourceWithAPI(SOSDataSourceRef ds, bool isAPI, CFErrorRef *error,
 180                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 181     return ds->dsWith(ds, error, isAPI ? kSOSDataSourceAPITransaction : kSOSDataSourceSOSTransaction, transaction);
 182 }
 183
 184 static inline CFDataRef SOSDataSourceCopyStateWithKey(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, CFErrorRef *error)
 185 {
 186     return ds->dsCopyStateWithKey(ds, key, pdmn, error);
 187 }
 188
 189 static inline CFDataRef SOSDataSourceCopyItemDataWithKeys(SOSDataSourceRef ds, CFDictionaryRef keys, CFErrorRef *error) {
 190     return ds->dsCopyItemDataWithKeys(ds, keys, error);
 191 }
 192
 193 static inline bool SOSDataSourceRelease(SOSDataSourceRef ds, CFErrorRef *error) {
 194     return !ds || ds->dsRelease(ds, error);
 195 }
 196
 197 //
 198 // MARK: - SOSTransaction
 199 //
 200
 201 static inline SOSMergeResult SOSDataSourceMergeObject(SOSDataSourceRef ds, SOSTransactionRef txn, SOSObjectRef peersObject, SOSObjectRef *mergedObject, CFErrorRef *error) {
 202     return ds->dsMergeObject(txn, peersObject, mergedObject, error);
 203 }
 204
 205 static inline bool SOSDataSourceSetStateWithKey(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef key, CFStringRef pdmn, CFDataRef state, CFErrorRef *error)
 206 {
 207     return ds->dsSetStateWithKey(ds, txn, key, pdmn, state, error);
 208 }
 209
 210
 211 //
 212 // MARK: - SOSObject methods
 213 //
 214 static inline CFDataRef SOSObjectCopyDigest(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 215     return ds->objectCopyDigest(object, error);
 216 }
 217
 218 static inline SOSObjectRef SOSObjectCreateWithPropertyList(SOSDataSourceRef ds, CFDictionaryRef plist, CFErrorRef *error) {
 219     return ds->objectCreateWithPropertyList(plist, error);
 220 }
 221
 222 static inline CFDictionaryRef SOSObjectCopyPropertyList(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 223     return ds->objectCopyPropertyList(object, error);
 224 }
 225
 226 static inline CFDictionaryRef SOSObjectCopyBackup(SOSDataSourceRef ds, SOSObjectRef object, uint64_t handle, CFErrorRef *error) {
 227     return ds->objectCopyBackup(object, handle, error);
 228 }
 229
 230 static inline bool SOSObjectRestoreObject(SOSDataSourceRef ds, SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error) {
 231     return ds->dsRestoreObject(txn, handle, item, error);
 232 }
 233
 234
 235 //
 236 // MARK: SOSDataSourceFactory helpers
 237 //
 238
 239 static inline SOSEngineRef SOSDataSourceFactoryGetEngineForDataSourceName(SOSDataSourceFactoryRef factory, CFStringRef dataSourceName, CFErrorRef *error)
 240 {
 241     SOSDataSourceRef ds = SOSDataSourceFactoryCreateDataSource(factory, dataSourceName, error);
 242     SOSEngineRef engine = ds ? SOSDataSourceGetSharedEngine(ds, error) : (SOSEngineRef) NULL;
 243     SOSDataSourceRelease(ds, NULL); // TODO: Log this error?!
 244
 245     return engine;
 246 }
 247
 248 __END_DECLS
 249
 250 #endif /* !_SEC_SOSDATASOURCE_H_ */