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 // 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.
  46 //
  47 class Key : public HandleObject, public SecurityServerAcl {
  48 public:
  49         Key(Database &db, const KeyBlob *blob);
  50         Key(Database *db, const CssmKey &newKey, uint32 moreAttributes,
  51                 const AclEntryPrototype *owner = NULL);
  52         virtual ~Key();
  53
  54     Database *database() const { return mDatabase; }
  55     bool hasDatabase() const { return mDatabase != NULL; }
  56
  57     // yield the decoded internal key -- internal attributes
  58         CssmClient::Key key()           { return keyValue(); }
  59         const CssmKey &cssmKey()        { return keyValue(); }
  60         operator CssmClient::Key ()     { return keyValue(); }
  61         operator const CssmKey &()      { return keyValue(); }
  62     operator const CSSM_KEY & () { return keyValue(); }
  63
  64     // yield the approximate external key header -- external attributes
  65     void returnKey(Handle &h, CssmKey::Header &hdr);
  66
  67         // generate the canonical key digest
  68         const CssmData &canonicalDigest();
  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 changedAcl();
  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 "forced on" in internal keys (but not always in external attributes)
  84         static const uint32 forcedAttributes = KeyBlob::forcedAttributes;
  85         // these attributes are internally generated, and invalid on input
  86         static const uint32 generatedAttributes =
  87                 CSSM_KEYATTR_ALWAYS_SENSITIVE | CSSM_KEYATTR_NEVER_EXTRACTABLE;
  88
  89         // a version of KeySpec that self-checks and masks for CSP operation
  90         class KeySpec : public CssmClient::KeySpec {
  91         public:
  92                 KeySpec(uint32 usage, uint32 attrs);
  93                 KeySpec(uint32 usage, uint32 attrs, const CssmData &label);
  94         };
  95         CSSM_KEYATTR_FLAGS attributes() { return mAttributes; }
  96
  97 private:
  98         void setup(const CssmKey &newKey, uint32 attrs);
  99     void decode();
 100         CssmClient::Key keyValue();
 101
 102 private:
 103         CssmClient::Key mKey;   // clear form CssmKey (attributes modified)
 104         CssmKey::Header mHeaderCache; // cached, cleaned blob header cache
 105     CSSM_KEYATTR_FLAGS mAttributes; // full attributes (external form)
 106         bool mValidKey;                 // CssmKey form is valid
 107         CssmAutoData mDigest;   // computed key digest (cached)
 108
 109         Database *mDatabase;    // the database we belong to, NULL if independent
 110
 111         KeyBlob *mBlob;                 // key blob encoded by mDatabase
 112         bool mValidBlob;                // mBlob is valid key encoding
 113
 114     KeyUID mUID;                        // cached UID
 115     bool mValidUID;                     // UID has been calculated
 116 };
 117
 118
 119 #endif //_H_KEY