cdsa/cdsa_client/dlclient.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 //
  20 // dlclient - client interface to CSSM DLs and their operations
  21 //
  22
  23 #ifndef _H_CDSA_CLIENT_DLCLIENT
  24 #define _H_CDSA_CLIENT_DLCLIENT  1
  25
  26 #include <Security/cssmclient.h>
  27 #include <Security/DLDBList.h>
  28 #include <Security/cssmacl.h>
  29 #include <Security/cssmdb.h>
  30 #include <Security/cssmdata.h>
  31
  32
  33 namespace Security
  34 {
  35
  36 namespace CssmClient
  37 {
  38
  39 #define CSSM_DB_ATTR(ATTR) ATTR
  40 #define CSSM_DB_ATTR_SCHEMA(ATTR) ATTR ## Schema
  41
  42 #define CSSM_DB_INDEX(ATTR) ATTR ## Index
  43 #define CSSM_DB_UNIQUE(ATTR) ATTR ## Unique
  44
  45 //
  46 // Helper macro for declaring and defining a Db index unique and non-unique attributes
  47 //
  48 #define CSSM_DB_INDEX_DECL(ATTR)  static const CSSM_DB_INDEX_INFO CSSM_DB_INDEX(ATTR)
  49 #define CSSM_DB_UNIQUE_DECL(ATTR)  static const CSSM_DB_INDEX_INFO CSSM_DB_UNIQUE(ATTR)
  50
  51
  52 //
  53 // Use this macro for defining a non-unique attribute
  54 //
  55 #define CSSM_DB_INDEX_DEF(ATTR) \
  56 const CSSM_DB_INDEX_INFO CSSM_DB_INDEX(ATTR) = \
  57 { \
  58         CSSM_DB_INDEX_NONUNIQUE, \
  59         CSSM_DB_INDEX_ON_ATTRIBUTE, \
  60         CSSM_DB_ATTR(ATTR) \
  61 }
  62
  63 //
  64 //  Use this macro for defining a unique attribute
  65
  66 //
  67 #define CSSM_DB_UNIQUE_DEF(ATTR) \
  68 const CSSM_DB_INDEX_INFO CSSM_DB_UNIQUE(ATTR) = \
  69 { \
  70         CSSM_DB_INDEX_UNIQUE, \
  71         CSSM_DB_INDEX_ON_ATTRIBUTE, \
  72         CSSM_DB_ATTR(ATTR) \
  73 }
  74
  75
  76
  77 //
  78 // Helper macro for declaring and defining a Db schema attributes
  79 // Use this macro in your header to declare each attribute you require.
  80 //
  81 #define CSSM_DB_ATTR_DECL(ATTR) \
  82 static const CSSM_DB_ATTRIBUTE_INFO CSSM_DB_ATTR(ATTR); \
  83 static const CSSM_DB_SCHEMA_ATTRIBUTE_INFO CSSM_DB_ATTR_SCHEMA(ATTR)
  84
  85 //
  86 // Don't directly use this macro use one of the below instead.
  87 //
  88 #define CSSM_DB_ATTR_DEFINE_SCHEMA(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE) \
  89 const CSSM_DB_SCHEMA_ATTRIBUTE_INFO CSSM_DB_ATTR_SCHEMA(ATTR) = \
  90 { \
  91         INTEGER, \
  92         NAME, \
  93         { OID_LEN, OID_DATA }, \
  94         CSSM_DB_ATTRIBUTE_FORMAT_ ## VALUETYPE \
  95 }
  96
  97
  98 //
  99 // Use one of the following macros to defined each declared attribute required by your application.
 100 //
 101 //
 102 // Use this macro to define attributes which are looked up by integer AttributeID.
 103 //
 104 #define CSSM_DB_INTEGER_ATTR(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE) \
 105 const CSSM_DB_ATTRIBUTE_INFO ATTR = \
 106 { \
 107     CSSM_DB_ATTRIBUTE_NAME_AS_INTEGER, \
 108     {(char *)INTEGER}, \
 109     CSSM_DB_ATTRIBUTE_FORMAT_ ## VALUETYPE \
 110 };\
 111 \
 112 CSSM_DB_ATTR_DEFINE_SCHEMA(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE)
 113
 114 //
 115 // Use this macro to define attributes which are looked up by string AttributeName.
 116 //
 117 #define CSSM_DB_NAME_ATTR(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE) \
 118 const CSSM_DB_ATTRIBUTE_INFO ATTR = \
 119 { \
 120     CSSM_DB_ATTRIBUTE_NAME_AS_STRING, \
 121     {NAME}, \
 122     CSSM_DB_ATTRIBUTE_FORMAT_ ## VALUETYPE \
 123 };\
 124 \
 125 CSSM_DB_ATTR_DEFINE_SCHEMA(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE)
 126
 127 //
 128 // Use this macro to define attributes which are looked up by OID AttributeNameID.
 129 // XXX This does not work yet.
 130 //
 131 #define CSSM_DB_OID_ATTR(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE) \
 132 const CSSM_DB_ATTRIBUTE_INFO ATTR = \
 133 { \
 134     CSSM_DB_ATTRIBUTE_NAME_AS_OID, \
 135     {{OID_LEN, OID_DATA}}, \
 136     CSSM_DB_ATTRIBUTE_FORMAT_ ## VALUETYPE \
 137 };\
 138 \
 139 CSSM_DB_ATTR_DEFINE_SCHEMA(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE)
 140
 141
 142 //
 143 // Use this macro to define attributes which are part of the primary key.
 144 //
 145 #define CSSM_DB_PRIMARKEY_ATTR(ATTR, NAME) \
 146 const CSSM_DB_ATTRIBUTE_INFO ATTR = \
 147 { \
 148     CSSM_DB_INDEX_UNIQUE, \
 149     CSSM_DB_INDEX_ON_ATTRIBUTE, \
 150     CSSM_DB_ATTRIBUTE_FORMAT_ ## VALUETYPE \
 151 };\
 152 \
 153 CSSM_DB_ATTR_DEFINE_SCHEMA(ATTR, INTEGER, NAME, OID_LEN, OID_DATA, VALUETYPE)
 154
 155
 156
 157 //
 158 // Maker interfaces used by various Impl objects
 159 //
 160
 161 // DbMaker -- someone who can create a new DbImpl.
 162 class DbImpl;
 163 class DbMaker
 164 {
 165 public:
 166         virtual DbImpl *newDb(const char *inDbName, const CSSM_NET_ADDRESS *inDbLocation) = 0;
 167 };
 168
 169 // DbCursorMaker -- someone who can create a new DbCursorImpl.
 170 class DbCursorImpl;
 171 class DbCursorMaker
 172 {
 173 public:
 174         virtual DbCursorImpl *newDbCursor(const CSSM_QUERY &query, CssmAllocator &allocator) = 0;
 175         virtual DbCursorImpl *newDbCursor(uint32 capacity, CssmAllocator &allocator) = 0;
 176 };
 177
 178 // DbUniqueRecordMaker -- someone who can create a new DbUniqueRecordImpl.
 179 class DbUniqueRecordImpl;
 180 class DbUniqueRecordMaker
 181 {
 182 public:
 183         virtual DbUniqueRecordImpl *newDbUniqueRecord() = 0;
 184 };
 185
 186
 187 //
 188 // A DL attachment
 189 //
 190 class DLImpl : public AttachmentImpl, public DbMaker
 191 {
 192 public:
 193         DLImpl(const Guid &guid);
 194         DLImpl(const Module &module);
 195         virtual ~DLImpl();
 196
 197         virtual void getDbNames(char **);
 198         virtual void freeNameList(char **);
 199
 200         // DbMaker
 201         virtual DbImpl *newDb(const char *inDbName, const CSSM_NET_ADDRESS *inDbLocation);
 202 private:
 203 };
 204
 205 class DL : public Attachment
 206 {
 207 public:
 208         typedef DLImpl Impl;
 209
 210         explicit DL(Impl *impl) : Attachment(impl) {}
 211         DL() : Attachment(NULL) {}
 212         DL(const Guid &guid) : Attachment(new Impl(guid)) {}
 213         DL(const Module &module) : Attachment(new Impl(module)) {}
 214
 215         Impl *operator ->() const { return &impl<Impl>(); }
 216         Impl &operator *() const { return impl<Impl>(); }
 217
 218         // Conversion to DbMaker.
 219         operator DbMaker &() const { return impl<Impl>(); }
 220 };
 221
 222
 223 class DbAttributes;
 224 class DbUniqueRecord;
 225
 226
 227 //
 228 // A CSSM_DLDB handle.
 229 // Dbs always belong to DLs (DL attachments)
 230 //
 231 class DbImpl : public ObjectImpl, public DbCursorMaker, public DbUniqueRecordMaker
 232 {
 233 public:
 234         DbImpl(const DL &dl, const char *inDbName, const CSSM_NET_ADDRESS *inDbLocation);
 235         virtual ~DbImpl();
 236
 237         DL dl() const { return parent<DL>(); }
 238         Module module() const { return dl()->module(); }
 239
 240         virtual void open();
 241         virtual void create();
 242         virtual void close();
 243         virtual void deleteDb();
 244         virtual void rename(const char *newName);
 245         virtual void authenticate(CSSM_DB_ACCESS_TYPE inAccessRequest,
 246                                                                 const CSSM_ACCESS_CREDENTIALS *inAccessCredentials);
 247         virtual void name(char *&outName);      // CSSM_DL_GetDbNameFromHandle()
 248
 249         virtual void createRelation(CSSM_DB_RECORDTYPE inRelationID,
 250                                                                 const char *inRelationName,
 251                                                                 uint32 inNumberOfAttributes,
 252                                                                 const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo,
 253                                                                 uint32 inNumberOfIndexes,
 254                                                                 const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo);
 255         virtual void destroyRelation(CSSM_DB_RECORDTYPE inRelationID);
 256
 257         virtual DbUniqueRecord insert(CSSM_DB_RECORDTYPE recordType,
 258                                                                         const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes,
 259                                                                         const CSSM_DATA *data);
 260
 261         const CSSM_DL_DB_HANDLE &handle() { activate(); return mHandle; }
 262
 263         const DbName &dbName() { return mDbName; }
 264         void dbName(const DbName &dbName) { mDbName = dbName; }
 265
 266         const char *name() const { return mDbName.dbName().c_str(); }
 267         const CSSM_NET_ADDRESS *dbLocation() const { return mDbName.dbLocation(); }
 268
 269         CSSM_DB_ACCESS_TYPE accessRequest() const { return mAccessRequest; }
 270         void accessRequest(CSSM_DB_ACCESS_TYPE inAccessRequest)
 271         { mAccessRequest = inAccessRequest; }
 272
 273         const CSSM_ACCESS_CREDENTIALS *accessCredentials() const
 274         { return mAccessCredentials; }
 275         void accessCredentials(const CSSM_ACCESS_CREDENTIALS *inAccessCredentials)
 276         { mAccessCredentials = inAccessCredentials; }
 277
 278         const void *openParameters() const { return mOpenParameters; }
 279         void openParameters(const void *inOpenParameters)
 280         { mOpenParameters = inOpenParameters; }
 281
 282         const CSSM_DBINFO *dbInfo() const { return mDbInfo; }
 283         void dbInfo(const CSSM_DBINFO *inDbInfo) { mDbInfo = inDbInfo; }
 284
 285         const ResourceControlContext *resourceControlContext() const
 286         { return mResourceControlContext; }
 287         void resourceControlContext(const CSSM_RESOURCE_CONTROL_CONTEXT *inResourceControlContext)
 288         { mResourceControlContext = ResourceControlContext::overlay(inResourceControlContext); }
 289
 290         void passThrough(uint32 passThroughId, const void *in, void **out = NULL);
 291
 292         template <class TIn, class TOut>
 293         void passThrough(uint32 passThroughId, const TIn *in, TOut *out = NULL)
 294         { passThrough(passThroughId, (const void *)in, (void **)out); }
 295
 296         // Passthrough functions (only implemented by AppleCSPDL).
 297         virtual void lock();
 298         virtual void unlock();
 299         virtual void unlock(const CSSM_DATA &password);
 300         virtual void getSettings(uint32 &outIdleTimeout, bool &outLockOnSleep);
 301         virtual void setSettings(uint32 inIdleTimeout, bool inLockOnSleep);
 302         virtual bool isLocked();
 303         virtual void changePassphrase(const CSSM_ACCESS_CREDENTIALS *cred);
 304         virtual bool getUnlockKeyIndex(CssmData &index);
 305
 306         // Utility methods
 307         virtual DLDbIdentifier dlDbIdentifier() const;
 308
 309         // DbCursorMaker
 310         virtual DbCursorImpl *newDbCursor(const CSSM_QUERY &query, CssmAllocator &allocator);
 311         virtual DbCursorImpl *newDbCursor(uint32 capacity, CssmAllocator &allocator);
 312
 313         // DbUniqueRecordMaker
 314         virtual DbUniqueRecordImpl *newDbUniqueRecord();
 315
 316 protected:
 317         virtual void activate();
 318         virtual void deactivate();
 319
 320 private:
 321         CSSM_DL_DB_HANDLE mHandle;                      // CSSM DLDB handle
 322
 323         DbName mDbName;
 324         CSSM_DB_ACCESS_TYPE mAccessRequest;
 325         const CSSM_ACCESS_CREDENTIALS *mAccessCredentials;
 326         const void *mOpenParameters;
 327
 328         // Arguments to create
 329         const CSSM_DBINFO *mDbInfo;
 330         const ResourceControlContext *mResourceControlContext;
 331 };
 332
 333
 334 class Db : public Object
 335 {
 336 public:
 337         typedef DbImpl Impl;
 338
 339         explicit Db(Impl *impl) : Object(impl) {}
 340         Db() : Object(NULL) {}
 341         Db(DbMaker &maker, const char *inDbName, const CSSM_NET_ADDRESS *inDbLocation = NULL)
 342         : Object(maker.newDb(inDbName, inDbLocation)) {}
 343
 344         Impl *operator ->() const { return &impl<Impl>(); }
 345         Impl &operator *() const { return impl<Impl>(); }
 346
 347         // Conversion to DbCursorMaker.
 348         operator DbCursorMaker &() const { return impl<Impl>(); }
 349         // Conversion to DbUniqueRecordMaker.
 350         operator DbUniqueRecordMaker &() const { return impl<Impl>(); }
 351 };
 352
 353 //
 354 // DbCursor
 355 //
 356
 357 // This class is still abstract.  You must subclass it in order to be able to instantiate an instance.
 358 class DbCursorImpl : public ObjectImpl, public CssmAutoQuery
 359 {
 360 public:
 361         DbCursorImpl(const Object &parent, const CSSM_QUERY &query, CssmAllocator &allocator);
 362         DbCursorImpl(const Object &parent, uint32 capacity, CssmAllocator &allocator);
 363
 364         virtual CssmAllocator &allocator() const;
 365         virtual void allocator(CssmAllocator &alloc);
 366
 367         virtual bool next(DbAttributes *attributes, ::CssmDataContainer *data, DbUniqueRecord &uniqueId) = 0;
 368         void abort() { deactivate(); }
 369 };
 370
 371 class DbCursor : public Object
 372 {
 373 public:
 374         typedef DbCursorImpl Impl;
 375
 376         explicit DbCursor(Impl *impl) : Object(impl) {}
 377         DbCursor() : Object(NULL) {}
 378         DbCursor(DbCursorMaker &maker, const CSSM_QUERY &query,
 379                          CssmAllocator &allocator = CssmAllocator::standard())
 380         : Object(maker.newDbCursor(query, allocator)) {}
 381         DbCursor(DbCursorMaker &maker, uint32 capacity = 0,
 382                          CssmAllocator &allocator = CssmAllocator::standard())
 383         : Object(maker.newDbCursor(capacity, allocator)) {}
 384
 385         Impl *operator ->() const { return &impl<Impl>(); }
 386         Impl &operator *() const { return impl<Impl>(); }
 387 };
 388
 389
 390 //
 391 // DbUniqueRecord
 392 //
 393 class DbUniqueRecordImpl : public ObjectImpl
 394 {
 395 public:
 396         DbUniqueRecordImpl(const Db &db);
 397         virtual ~DbUniqueRecordImpl();
 398
 399         virtual void deleteRecord();
 400         virtual void modify(CSSM_DB_RECORDTYPE recordType,
 401                                                 const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes,
 402                                                 const CSSM_DATA *data,
 403                                                 CSSM_DB_MODIFY_MODE modifyMode);
 404         virtual void get(DbAttributes *attributes, ::CssmDataContainer *data);
 405
 406         Db database() const { return parent<Db>(); }
 407
 408         void free() { deactivate(); }
 409
 410         // Client must call activate() after calling this function if mUniqueId is successfully set.
 411         operator CSSM_DB_UNIQUE_RECORD_PTR *() { if (mActive) free(); return &mUniqueId; }
 412
 413         operator CSSM_DB_UNIQUE_RECORD *() { return mUniqueId; }
 414         operator const CSSM_DB_UNIQUE_RECORD *() const { return mUniqueId; }
 415
 416         void activate();
 417
 418 protected:
 419         void deactivate();
 420
 421         CSSM_DB_UNIQUE_RECORD_PTR mUniqueId;
 422 };
 423
 424 class DbUniqueRecord : public Object
 425 {
 426 public:
 427         typedef DbUniqueRecordImpl Impl;
 428
 429         explicit DbUniqueRecord(Impl *impl) : Object(impl) {}
 430         DbUniqueRecord() : Object(NULL) {}
 431         DbUniqueRecord(DbUniqueRecordMaker &maker) : Object(maker.newDbUniqueRecord()) {}
 432
 433         Impl *operator ->() { return &impl<Impl>(); }
 434         Impl &operator *() { return impl<Impl>(); }
 435         const Impl &operator *() const { return impl<Impl>(); }
 436
 437         // Conversion operators must be here.
 438
 439         // Client must activate after calling this function if mUniqueId is successfully set.
 440         operator CSSM_DB_UNIQUE_RECORD_PTR *() { return **this; }
 441
 442         operator CSSM_DB_UNIQUE_RECORD *() { return **this; }
 443         operator const CSSM_DB_UNIQUE_RECORD *() const { return **this; }
 444 };
 445
 446
 447 //
 448 // DbAttributes
 449 //
 450 class DbAttributes : public CssmAutoDbRecordAttributeData
 451 {
 452 public:
 453         DbAttributes();
 454         DbAttributes(const Db &db, uint32 capacity = 0, CssmAllocator &allocator = CssmAllocator::standard());
 455 };
 456
 457
 458 //
 459 // DbDbCursor -- concrete subclass of DbCursorImpl for querying Db's
 460 //
 461 class DbDbCursorImpl : public DbCursorImpl
 462 {
 463 public:
 464         DbDbCursorImpl(const Db &db, const CSSM_QUERY &query, CssmAllocator &allocator);
 465         DbDbCursorImpl(const Db &db, uint32 capacity, CssmAllocator &allocator);
 466         virtual ~DbDbCursorImpl();
 467
 468         bool next(DbAttributes *attributes, ::CssmDataContainer *data, DbUniqueRecord &uniqueId);
 469
 470 protected:
 471         Db database() { return parent<Db>(); }
 472
 473         void activate();
 474         void deactivate();
 475
 476 private:
 477         CSSM_HANDLE mResultsHandle;
 478 };
 479
 480 } // end namespace CssmClient
 481
 482 } // end namespace Security
 483
 484 #endif // _H_CDSA_CLIENT_DLCLIENT