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 transaction 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 (*dsAddNotifyPhaseBlock)(SOSDataSourceRef ds, SOSDataSourceNotifyBlock notifyBlock);
 131     SOSManifestRef (*dsCopyManifestWithViewNameSet)(SOSDataSourceRef ds, CFSetRef viewNameSet, CFErrorRef *error);
 132     bool (*dsForEachObject)(SOSDataSourceRef ds, SOSTransactionRef txn, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef key, SOSObjectRef object, bool *stop));
 133     CFDataRef (*dsCopyStateWithKey)(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, SOSTransactionRef txn, CFErrorRef *error);
 134     CFDataRef (*dsCopyItemDataWithKeys)(SOSDataSourceRef ds, CFDictionaryRef keys, CFErrorRef *error);
 135     bool (*dsDeleteStateWithKey)(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, SOSTransactionRef txn, CFErrorRef *error);
 136
 137     bool (*dsWith)(SOSDataSourceRef ds, CFErrorRef *error, SOSDataSourceTransactionSource source, bool onCommitQueue, void(^transaction)(SOSTransactionRef txn, bool *commit));
 138     bool (*dsRelease)(SOSDataSourceRef ds, CFErrorRef *error); // Destructor
 139     bool (*dsReadWith)(SOSDataSourceRef ds, CFErrorRef *error, SOSDataSourceTransactionSource source, void(^perform)(SOSTransactionRef txn));
 140
 141     // SOSTransaction methods, writes to a dataSource require a transaction.
 142     SOSMergeResult (*dsMergeObject)(SOSTransactionRef txn, SOSObjectRef object, SOSObjectRef *createdObject, CFErrorRef *error);
 143     bool (*dsSetStateWithKey)(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef pdmn, CFStringRef key, CFDataRef state, CFErrorRef *error);
 144     bool (*dsRestoreObject)(SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error);
 145
 146     // SOSObject methods
 147     CFDataRef (*objectCopyDigest)(SOSObjectRef object, CFErrorRef *error);
 148     SOSObjectRef (*objectCreateWithPropertyList)(CFDictionaryRef plist, CFErrorRef *error);
 149     CFDictionaryRef (*objectCopyPropertyList)(SOSObjectRef object, CFErrorRef *error);
 150     CFDictionaryRef (*objectCopyBackup)(SOSObjectRef object, uint64_t handle, CFErrorRef *error);
 151 };
 152
 153 //
 154 // MARK: - SOSDataSource protocol implementation
 155 //
 156 static inline SOSEngineRef SOSDataSourceGetSharedEngine(SOSDataSourceRef ds, CFErrorRef *error) {
 157     return ds->engine;
 158 }
 159
 160 static inline CFStringRef SOSDataSourceGetName(SOSDataSourceRef ds) {
 161     return ds->dsGetName(ds);
 162 }
 163
 164 static inline void SOSDataSourceAddNotifyPhaseBlock(SOSDataSourceRef ds, SOSDataSourceNotifyBlock notifyBlock) {
 165     ds->dsAddNotifyPhaseBlock(ds, notifyBlock);
 166 }
 167
 168 static inline SOSManifestRef SOSDataSourceCopyManifestWithViewNameSet(SOSDataSourceRef ds, CFSetRef viewNameSet, CFErrorRef *error) {
 169     return ds->dsCopyManifestWithViewNameSet(ds, viewNameSet, error);
 170 }
 171
 172 static inline bool SOSDataSourceForEachObject(SOSDataSourceRef ds, SOSTransactionRef txn, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef digest, SOSObjectRef object, bool *stop)) {
 173     return ds->dsForEachObject(ds, txn, manifest, error, handleObject);
 174 }
 175
 176 static inline bool SOSDataSourceWith(SOSDataSourceRef ds, CFErrorRef *error,
 177                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 178     return ds->dsWith(ds, error, kSOSDataSourceSOSTransaction, false, transaction);
 179 }
 180
 181 static inline bool SOSDataSourceWithCommitQueue(SOSDataSourceRef ds, CFErrorRef *error,
 182                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 183     return ds->dsWith(ds, error, kSOSDataSourceSOSTransaction, true, transaction);
 184 }
 185
 186 static inline bool SOSDataSourceWithAPI(SOSDataSourceRef ds, bool isAPI, CFErrorRef *error,
 187                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 188     return ds->dsWith(ds, error, isAPI ? kSOSDataSourceAPITransaction : kSOSDataSourceSOSTransaction, false, transaction);
 189 }
 190
 191 static inline bool SOSDataSourceReadWithCommitQueue(SOSDataSourceRef ds, CFErrorRef *error,
 192                                                 void(^perform)(SOSTransactionRef txn)) {
 193     return ds->dsReadWith(ds, error, kSOSDataSourceSOSTransaction, perform);
 194 }
 195
 196
 197 static inline CFDataRef SOSDataSourceCopyStateWithKey(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, SOSTransactionRef txn, CFErrorRef *error)
 198 {
 199     return ds->dsCopyStateWithKey(ds, key, pdmn, txn, error);
 200 }
 201
 202 static inline CFDataRef SOSDataSourceCopyItemDataWithKeys(SOSDataSourceRef ds, CFDictionaryRef keys, CFErrorRef *error) {
 203     return ds->dsCopyItemDataWithKeys(ds, keys, error);
 204 }
 205
 206 static inline bool SOSDataSourceDeleteStateWithKey(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, SOSTransactionRef txn, CFErrorRef *error)
 207 {
 208     return ds->dsDeleteStateWithKey(ds, key, pdmn, txn, error);
 209 }
 210
 211 static inline bool SOSDataSourceRelease(SOSDataSourceRef ds, CFErrorRef *error) {
 212     return !ds || ds->dsRelease(ds, error);
 213 }
 214
 215 //
 216 // MARK: - SOSTransaction
 217 //
 218
 219 static inline SOSMergeResult SOSDataSourceMergeObject(SOSDataSourceRef ds, SOSTransactionRef txn, SOSObjectRef peersObject, SOSObjectRef *mergedObject, CFErrorRef *error) {
 220     return ds->dsMergeObject(txn, peersObject, mergedObject, error);
 221 }
 222
 223 static inline bool SOSDataSourceSetStateWithKey(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef key, CFStringRef pdmn, CFDataRef state, CFErrorRef *error)
 224 {
 225     return ds->dsSetStateWithKey(ds, txn, key, pdmn, state, error);
 226 }
 227
 228
 229 //
 230 // MARK: - SOSObject methods
 231 //
 232 static inline CFDataRef SOSObjectCopyDigest(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 233     return ds->objectCopyDigest(object, error);
 234 }
 235
 236 static inline SOSObjectRef SOSObjectCreateWithPropertyList(SOSDataSourceRef ds, CFDictionaryRef plist, CFErrorRef *error) {
 237     return ds->objectCreateWithPropertyList(plist, error);
 238 }
 239
 240 static inline CFDictionaryRef SOSObjectCopyPropertyList(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 241     return ds->objectCopyPropertyList(object, error);
 242 }
 243
 244 static inline CFDictionaryRef SOSObjectCopyBackup(SOSDataSourceRef ds, SOSObjectRef object, uint64_t handle, CFErrorRef *error) {
 245     return ds->objectCopyBackup(object, handle, error);
 246 }
 247
 248 static inline bool SOSObjectRestoreObject(SOSDataSourceRef ds, SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error) {
 249     return ds->dsRestoreObject(txn, handle, item, error);
 250 }
 251
 252
 253 //
 254 // MARK: SOSDataSourceFactory helpers
 255 //
 256
 257 static inline SOSEngineRef SOSDataSourceFactoryGetEngineForDataSourceName(SOSDataSourceFactoryRef factory, CFStringRef dataSourceName, CFErrorRef *error)
 258 {
 259     SOSDataSourceRef ds = SOSDataSourceFactoryCreateDataSource(factory, dataSourceName, error);
 260     SOSEngineRef engine = ds ? SOSDataSourceGetSharedEngine(ds, error) : (SOSEngineRef) NULL;
 261     SOSDataSourceRelease(ds, NULL); // TODO: Log this error?!
 262
 263     return engine;
 264 }
 265
 266 __END_DECLS
 267
 268 #endif /* !_SEC_SOSDATASOURCE_H_ */