SecurityServer/key.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 // key - representation of SecurityServer key objects
  21 //
  22 #ifndef _H_KEY
  23 #define _H_KEY
  24
  25 #include "securityserver.h"
  26 #include "acls.h"
  27 #include <Security/utilities.h>
  28 #include <Security/handleobject.h>
  29
  30
  31 class Database;
  32
  33
  34 //
  35 // A Key object represents a CSSM_KEY known to the SecurityServer.
  36 // We give each Key a handle that allows our clients to access it, while we use
  37 // the Key's ACL to control such accesses.
  38 // A Key can be used by multiple Connections. Whether more than one Key can represent
  39 // the same actual key object is up to the CSP we use, so let's be tolerant about that.
  40 //
  41 // A note on key attributes: We keep two sets of attribute bits. The internal bits are used
  42 // when talking to our CSP; the external bits are used when negotiating with our client(s).
  43 // The difference is the bits in managedAttributes, which relate to persistent key storage
  44 // and are not digestible by our CSP. The internal attributes are kept in mKey. The external
  45 // ones are kept in mAttributes, and are a superset of the internal ones.
  46 //
  47 class Key : public HandleObject, public SecurityServerAcl {
  48 public:
  49         //Key(Database *db, const CssmKey &newKey, uint32 usage, uint32 attrs,
  50         //      const AclEntryPrototype *owner = NULL);
  51         //Key(Database *db, const CssmKey &newKey, const AclEntryPrototype *owner = NULL);
  52         Key(Database &db, const KeyBlob *blob);
  53         Key(Database *db, const CssmKey &newKey, uint32 moreAttributes,
  54                 const AclEntryPrototype *owner = NULL);
  55         virtual ~Key();
  56
  57     Database *database() const { return mDatabase; }
  58     bool hasDatabase() const { return mDatabase != NULL; }
  59
  60     // yield the decoded internal key -- internal attributes
  61         operator CssmKey &()            { return keyValue(); }
  62         size_t length()                         { return keyValue().length(); }
  63         void *data()                            { return keyValue().data(); }
  64
  65     // yield the approximate external key header -- external attributes
  66     void returnKey(Handle &h, CssmKey::Header &hdr);
  67
  68     // we can also yield an encoded KeyBlob *if* we belong to a database
  69         KeyBlob *blob();
  70
  71     // calculate the UID value for this key (if possible)
  72     KeyUID &uid();
  73
  74     // ACL state management hooks
  75         void instantiateAcl();
  76         void noticeAclChange();
  77     const Database *relatedDatabase() const;
  78
  79     // key attributes that should not be passed on to the CSP
  80     static const uint32 managedAttributes = KeyBlob::managedAttributes;
  81
  82 private:
  83         void setup(const CssmKey &newKey, uint32 attrs);
  84     void decode();
  85     CssmKey::Header &keyHeader();
  86         CssmKey &keyValue();
  87
  88 private:
  89         CssmKey mKey;                   // clear form CssmKey (attributes modified)
  90     CSSM_KEYATTR_FLAGS mAttributes; // full attributes (external form)
  91         bool mValidKey;                 // CssmKey form is valid
  92
  93         Database *mDatabase;    // the database we belong to, NULL if independent
  94
  95         KeyBlob *mBlob;                 // key blob encoded by mDatabase
  96         bool mValidBlob;                // mBlob is valid key encoding
  97
  98     KeyUID mUID;                        // cached UID
  99     bool mValidUID;                     // UID has been calculated
 100 };
 101
 102
 103 #endif //_H_KEY