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 authenticate(CSSM_DB_ACCESS_TYPE inAccessRequest,
 245                                                                 const CSSM_ACCESS_CREDENTIALS *inAccessCredentials);
 246         virtual void name(char *&outName);      // CSSM_DL_GetDbNameFromHandle()
 247
 248         virtual void createRelation(CSSM_DB_RECORDTYPE inRelationID,
 249                                                                 const char *inRelationName,
 250                                                                 uint32 inNumberOfAttributes,
 251                                                                 const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo,
 252                                                                 uint32 inNumberOfIndexes,
 253                                                                 const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo);
 254         virtual void destroyRelation(CSSM_DB_RECORDTYPE inRelationID);
 255
 256         virtual DbUniqueRecord insert(CSSM_DB_RECORDTYPE recordType,
 257                                                                         const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes,
 258                                                                         const CSSM_DATA *data);
 259
 260 #if 0
 261         // @@@ These methods have been moved to DbUniqueRecord.
 262         virtual void deleteRecord(const DbUniqueRecord &uniqueId);
 263         virtual void modify(CSSM_DB_RECORDTYPE recordType, DbUniqueRecord &uniqueId,
 264                                                 const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes,
 265                                                 const CSSM_DATA *data,
 266                                                 CSSM_DB_MODIFY_MODE modifyMode);
 267         virtual void get(const DbUniqueRecord &uniqueId, DbAttributes *attributes,
 268                                                 ::CssmDataContainer *data);
 269 #endif
 270
 271         const CSSM_DL_DB_HANDLE &handle() { activate(); return mHandle; }
 272
 273         const DbName &dbName() { return mDbName; }
 274         void dbName(const DbName &dbName) { mDbName = dbName; }
 275
 276         const char *name() const { return mDbName.dbName().c_str(); }
 277         const CSSM_NET_ADDRESS *dbLocation() const { return mDbName.dbLocation(); }
 278
 279         CSSM_DB_ACCESS_TYPE accessRequest() const { return mAccessRequest; }
 280         void accessRequest(CSSM_DB_ACCESS_TYPE inAccessRequest)
 281         { mAccessRequest = inAccessRequest; }
 282
 283         const CSSM_ACCESS_CREDENTIALS *accessCredentials() const
 284         { return mAccessCredentials; }
 285         void accessCredentials(const CSSM_ACCESS_CREDENTIALS *inAccessCredentials)
 286         { mAccessCredentials = inAccessCredentials; }
 287
 288         const void *openParameters() const { return mOpenParameters; }
 289         void openParameters(const void *inOpenParameters)
 290         { mOpenParameters = inOpenParameters; }
 291
 292         const CSSM_DBINFO *dbInfo() const { return mDbInfo; }
 293         void dbInfo(const CSSM_DBINFO *inDbInfo) { mDbInfo = inDbInfo; }
 294
 295         const CSSM_RESOURCE_CONTROL_CONTEXT *resourceControlContext() const
 296         { return mResourceControlContext; }
 297         void resourceControlContext(const CSSM_RESOURCE_CONTROL_CONTEXT *inResourceControlContext)
 298         { mResourceControlContext = inResourceControlContext; }
 299
 300         // Passthrough functions (only implemented by AppleCSPDL).
 301         virtual void lock();
 302         virtual void unlock();
 303         virtual void unlock(const CSSM_DATA &password);
 304         virtual void getSettings(uint32 &outIdleTimeout, bool &outLockOnSleep);
 305         virtual void setSettings(uint32 inIdleTimeout, bool inLockOnSleep);
 306         virtual bool isLocked();
 307         virtual void changePassphrase(const CSSM_ACCESS_CREDENTIALS *cred);
 308
 309         // Utility methods
 310         virtual DLDbIdentifier dlDbIdentifier() const;
 311
 312         // DbCursorMaker
 313         virtual DbCursorImpl *newDbCursor(const CSSM_QUERY &query, CssmAllocator &allocator);
 314         virtual DbCursorImpl *newDbCursor(uint32 capacity, CssmAllocator &allocator);
 315
 316         // DbUniqueRecordMaker
 317         virtual DbUniqueRecordImpl *newDbUniqueRecord();
 318
 319 protected:
 320         virtual void activate();
 321         virtual void deactivate();
 322
 323 private:
 324         CSSM_DL_DB_HANDLE mHandle;                      // CSSM DLDB handle
 325
 326         DbName mDbName;
 327         CSSM_DB_ACCESS_TYPE mAccessRequest;
 328         const CSSM_ACCESS_CREDENTIALS *mAccessCredentials;
 329         const void *mOpenParameters;
 330
 331         // Arguments to create
 332         const CSSM_DBINFO *mDbInfo;
 333         const CSSM_RESOURCE_CONTROL_CONTEXT *mResourceControlContext;
 334 };
 335
 336
 337 class Db : public Object
 338 {
 339 public:
 340         typedef DbImpl Impl;
 341
 342         explicit Db(Impl *impl) : Object(impl) {}
 343         Db() : Object(NULL) {}
 344         Db(DbMaker &maker, const char *inDbName, const CSSM_NET_ADDRESS *inDbLocation = NULL)
 345         : Object(maker.newDb(inDbName, inDbLocation)) {}
 346
 347         Impl *operator ->() const { return &impl<Impl>(); }
 348         Impl &operator *() const { return impl<Impl>(); }
 349
 350         // Conversion to DbCursorMaker.
 351         operator DbCursorMaker &() const { return impl<Impl>(); }
 352         // Conversion to DbUniqueRecordMaker.
 353         operator DbUniqueRecordMaker &() const { return impl<Impl>(); }
 354 };
 355
 356 //
 357 // DbCursor
 358 //
 359
 360 // This class is still abstract.  You must subclass it in order to be able to instantiate an instance.
 361 class DbCursorImpl : public ObjectImpl, public CssmAutoQuery
 362 {
 363 public:
 364         DbCursorImpl(const Object &parent, const CSSM_QUERY &query, CssmAllocator &allocator);
 365         DbCursorImpl(const Object &parent, uint32 capacity, CssmAllocator &allocator);
 366
 367         virtual CssmAllocator &allocator() const;
 368         virtual void allocator(CssmAllocator &alloc);
 369
 370         virtual bool next(DbAttributes *attributes, ::CssmDataContainer *data, DbUniqueRecord &uniqueId) = 0;
 371         void abort() { deactivate(); }
 372 };
 373
 374 class DbCursor : public Object
 375 {
 376 public:
 377         typedef DbCursorImpl Impl;
 378
 379         explicit DbCursor(Impl *impl) : Object(impl) {}
 380         DbCursor() : Object(NULL) {}
 381         DbCursor(DbCursorMaker &maker, const CSSM_QUERY &query,
 382                          CssmAllocator &allocator = CssmAllocator::standard())
 383         : Object(maker.newDbCursor(query, allocator)) {}
 384         DbCursor(DbCursorMaker &maker, uint32 capacity = 0,
 385                          CssmAllocator &allocator = CssmAllocator::standard())
 386         : Object(maker.newDbCursor(capacity, allocator)) {}
 387
 388         Impl *operator ->() const { return &impl<Impl>(); }
 389         Impl &operator *() const { return impl<Impl>(); }
 390 };
 391
 392
 393 //
 394 // DbUniqueRecord
 395 //
 396 class DbUniqueRecordImpl : public ObjectImpl
 397 {
 398 public:
 399         DbUniqueRecordImpl(const Db &db);
 400         virtual ~DbUniqueRecordImpl();
 401
 402         virtual void deleteRecord();
 403         virtual void modify(CSSM_DB_RECORDTYPE recordType,
 404                                                 const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes,
 405                                                 const CSSM_DATA *data,
 406                                                 CSSM_DB_MODIFY_MODE modifyMode);
 407         virtual void get(DbAttributes *attributes, ::CssmDataContainer *data);
 408
 409         Db database() const { return parent<Db>(); }
 410
 411         void free() { deactivate(); }
 412
 413         // Client must call activate() after calling this function if mUniqueId is successfully set.
 414         operator CSSM_DB_UNIQUE_RECORD_PTR *() { if (mActive) free(); return &mUniqueId; }
 415
 416         operator CSSM_DB_UNIQUE_RECORD *() { return mUniqueId; }
 417         operator const CSSM_DB_UNIQUE_RECORD *() const { return mUniqueId; }
 418
 419         void activate();
 420
 421 protected:
 422         void deactivate();
 423
 424         CSSM_DB_UNIQUE_RECORD_PTR mUniqueId;
 425 };
 426
 427 class DbUniqueRecord : public Object
 428 {
 429 public:
 430         typedef DbUniqueRecordImpl Impl;
 431
 432         explicit DbUniqueRecord(Impl *impl) : Object(impl) {}
 433         DbUniqueRecord() : Object(NULL) {}
 434         DbUniqueRecord(DbUniqueRecordMaker &maker) : Object(maker.newDbUniqueRecord()) {}
 435
 436         Impl *operator ->() { return &impl<Impl>(); }
 437         Impl &operator *() { return impl<Impl>(); }
 438         const Impl &operator *() const { return impl<Impl>(); }
 439
 440         // Conversion operators must be here.
 441
 442         // Client must activate after calling this function if mUniqueId is successfully set.
 443         operator CSSM_DB_UNIQUE_RECORD_PTR *() { return **this; }
 444
 445         operator CSSM_DB_UNIQUE_RECORD *() { return **this; }
 446         operator const CSSM_DB_UNIQUE_RECORD *() const { return **this; }
 447 };
 448
 449
 450 //
 451 // DbAttributes
 452 //
 453 class DbAttributes : public CssmAutoDbRecordAttributeData
 454 {
 455 public:
 456         DbAttributes();
 457         DbAttributes(const Db &db, uint32 capacity = 0, CssmAllocator &allocator = CssmAllocator::standard());
 458 };
 459
 460
 461 //
 462 // DbDbCursor -- concrete subclass of DbCursorImpl for querying Db's
 463 //
 464 class DbDbCursorImpl : public DbCursorImpl
 465 {
 466 public:
 467         DbDbCursorImpl(const Db &db, const CSSM_QUERY &query, CssmAllocator &allocator);
 468         DbDbCursorImpl(const Db &db, uint32 capacity, CssmAllocator &allocator);
 469         virtual ~DbDbCursorImpl();
 470
 471         bool next(DbAttributes *attributes, ::CssmDataContainer *data, DbUniqueRecord &uniqueId);
 472
 473 protected:
 474         Db database() { return parent<Db>(); }
 475
 476         void activate();
 477         void deactivate();
 478
 479 private:
 480         CSSM_HANDLE mResultsHandle;
 481 };
 482
 483 } // end namespace CssmClient
 484
 485 } // end namespace Security
 486
 487 #endif // _H_CDSA_CLIENT_DLCLIENT