securityd/src/localkey.h

   1 /*
   2  * Copyright (c) 2000-2001,2004,2008 Apple 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_client/keyclient.h>
  33
  34
  35 class LocalDatabase;
  36
  37
  38 //
  39 // A LocalKey object represents a CssmKey known to securityd. This subclass of Key is the
  40 // parent of all Key objects that rely on local storage of the raw key matter. Cryptographic
  41 // operations are performed by a local CSP within securityd's address space.
  42 //
  43 // LocalKeys are paired with LocalDatabases; LocalKey subclasses must be produced by, and must
  44 // belong to, subclasses of LocalDatabase.
  45 //
  46 // LocalKeys implement their ACLs with a local evaluation machine that does not rely on an outside
  47 // agent for evaluation. It is still possible for different subclasses of LocalDatabase to host
  48 // their ObjectAcl instances at different globality layers.
  49 //
  50 // Since the local CSP refuses to deal with storage-related key attributes, we split the keys's
  51 // CSSM_KEY_ATTRBITS into two parts:
  52 //  (*) The KeyHeader.attributes() contain attributes as seen by the local CSP.
  53 //  (*) The local mAttributes member contains attributes as seen by the client.
  54 // The two are related by a simple formula: take the external attributes, remove the global-storage
  55 // bits, add the EXTRACTABLE bit (so securityd itself can get at the key matter), and use that in
  56 // the CssmKey. The reverse transition is done on the way out. A local subclass of KeySpec is used
  57 // to make this more consistent. Just follow the pattern.
  58 //
  59 class LocalKey : public Key {
  60 public:
  61         LocalKey(Database &db, const CssmKey &newKey, uint32 moreAttributes);
  62         virtual ~LocalKey();
  63
  64         LocalDatabase &database() const;
  65
  66     // yield the decoded internal key -- internal attributes
  67         CssmClient::Key key()           { return keyValue(); }
  68         const CssmKey &cssmKey()        { return keyValue(); }
  69         operator CssmClient::Key ()     { return keyValue(); }
  70         operator const CssmKey &()      { return keyValue(); }
  71     operator const CSSM_KEY & () { return keyValue(); }
  72
  73     // yield the approximate external key header -- external attributes
  74     void returnKey(U32HandleObject::Handle &h, CssmKey::Header &hdr);
  75
  76         // generate the canonical key digest
  77         const CssmData &canonicalDigest();
  78
  79         CSSM_KEYATTR_FLAGS attributes();
  80
  81 public:
  82     // key attributes that should not be passed on to the CSP
  83     static const CSSM_KEYATTR_FLAGS managedAttributes = KeyBlob::managedAttributes;
  84         // these attributes are "forced on" in internal keys (but not always in external attributes)
  85         static const CSSM_KEYATTR_FLAGS forcedAttributes = KeyBlob::forcedAttributes;
  86         // these attributes are internally generated, and invalid on input
  87         static const CSSM_KEYATTR_FLAGS generatedAttributes =
  88                 CSSM_KEYATTR_ALWAYS_SENSITIVE | CSSM_KEYATTR_NEVER_EXTRACTABLE;
  89
  90         // a version of KeySpec that self-checks and masks for CSP operation
  91         class KeySpec : public CssmClient::KeySpec {
  92         public:
  93                 KeySpec(CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attrs);
  94                 KeySpec(CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attrs, const CssmData &label);
  95         };
  96
  97 private:
  98         void setup(const CssmKey &newKey, CSSM_KEYATTR_FLAGS attrs);
  99         CssmClient::Key keyValue();
 100
 101 protected:
 102         LocalKey(Database &db, CSSM_KEYATTR_FLAGS attributes);
 103         void setOwner(const AclEntryPrototype *owner);
 104
 105         virtual void getKey();                          // decode into mKey or throw
 106         virtual void getHeader(CssmKey::Header &hdr); // get header (only) without mKey
 107
 108 protected:
 109         bool mValidKey;                 // CssmKey form is valid
 110         CssmClient::Key mKey;   // clear form CssmKey (attributes modified)
 111
 112     CSSM_KEYATTR_FLAGS mAttributes; // full attributes (external form)
 113         CssmAutoData mDigest;   // computed key digest (cached)
 114 };
 115
 116
 117 #endif //_H_LOCALKEY