src/localkey.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24
  25 //
  26 // localkey - Key objects that store a local CSSM key object
  27 //
  28 #ifndef _H_LOCALKEY
  29 #define _H_LOCALKEY
  30
  31 #include "key.h"
  32 #include <security_cdsa_utilities/handleobject.h>
  33 #include <security_cdsa_client/keyclient.h>
  34
  35
  36 class LocalDatabase;
  37
  38
  39 //
  40 // A LocalKey object represents a CssmKey known to securityd. This subclass of Key is the
  41 // parent of all Key objects that rely on local storage of the raw key matter. Cryptographic
  42 // operations are performed by a local CSP within securityd's address space.
  43 //
  44 // LocalKeys are paired with LocalDatabases; LocalKey subclasses must be produced by, and must
  45 // belong to, subclasses of LocalDatabase.
  46 //
  47 // LocalKeys implement their ACLs with a local evaluation machine that does not rely on an outside
  48 // agent for evaluation. It is still possible for different subclasses of LocalDatabase to host
  49 // their ObjectAcl instances at different globality layers.
  50 //
  51 // Since the local CSP refuses to deal with storage-related key attributes, we split the keys's
  52 // CSSM_KEY_ATTRBITS into two parts:
  53 //  (*) The KeyHeader.attributes() contain attributes as seen by the local CSP.
  54 //  (*) The local mAttributes member contains attributes as seen by the client.
  55 // The two are related by a simple formula: take the external attributes, remove the global-storage
  56 // bits, add the EXTRACTABLE bit (so securityd itself can get at the key matter), and use that in
  57 // the CssmKey. The reverse transition is done on the way out. A local subclass of KeySpec is used
  58 // to make this more consistent. Just follow the pattern.
  59 //
  60 class LocalKey : public Key {
  61 public:
  62         LocalKey(Database &db, const CssmKey &newKey, uint32 moreAttributes);
  63         virtual ~LocalKey();
  64
  65         LocalDatabase &database() const;
  66
  67     // yield the decoded internal key -- internal attributes
  68         CssmClient::Key key()           { return keyValue(); }
  69         const CssmKey &cssmKey()        { return keyValue(); }
  70         operator CssmClient::Key ()     { return keyValue(); }
  71         operator const CssmKey &()      { return keyValue(); }
  72     operator const CSSM_KEY & () { return keyValue(); }
  73
  74     // yield the approximate external key header -- external attributes
  75     void returnKey(Handle &h, CssmKey::Header &hdr);
  76
  77         // generate the canonical key digest
  78         const CssmData &canonicalDigest();
  79
  80         CSSM_KEYATTR_FLAGS attributes();
  81
  82 public:
  83     // key attributes that should not be passed on to the CSP
  84     static const CSSM_KEYATTR_FLAGS managedAttributes = KeyBlob::managedAttributes;
  85         // these attributes are "forced on" in internal keys (but not always in external attributes)
  86         static const CSSM_KEYATTR_FLAGS forcedAttributes = KeyBlob::forcedAttributes;
  87         // these attributes are internally generated, and invalid on input
  88         static const CSSM_KEYATTR_FLAGS generatedAttributes =
  89                 CSSM_KEYATTR_ALWAYS_SENSITIVE | CSSM_KEYATTR_NEVER_EXTRACTABLE;
  90
  91         // a version of KeySpec that self-checks and masks for CSP operation
  92         class KeySpec : public CssmClient::KeySpec {
  93         public:
  94                 KeySpec(CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attrs);
  95                 KeySpec(CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attrs, const CssmData &label);
  96         };
  97
  98 private:
  99         void setup(const CssmKey &newKey, CSSM_KEYATTR_FLAGS attrs);
 100         CssmClient::Key keyValue();
 101
 102 protected:
 103         LocalKey(Database &db, CSSM_KEYATTR_FLAGS attributes);
 104         void setOwner(const AclEntryPrototype *owner);
 105
 106         virtual void getKey();                          // decode into mKey or throw
 107         virtual void getHeader(CssmKey::Header &hdr); // get header (only) without mKey
 108
 109 protected:
 110         bool mValidKey;                 // CssmKey form is valid
 111         CssmClient::Key mKey;   // clear form CssmKey (attributes modified)
 112
 113     CSSM_KEYATTR_FLAGS mAttributes; // full attributes (external form)
 114         CssmAutoData mDigest;   // computed key digest (cached)
 115 };
 116
 117
 118 #endif //_H_LOCALKEY