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