securityd/src/key.h

   1 /*
   2  * Copyright (c) 2000-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 // key - representation of securityd key objects
  27 //
  28 #ifndef _H_KEY
  29 #define _H_KEY
  30
  31 #include "structure.h"
  32 #include "database.h"
  33 #include "acls.h"
  34 #include <security_cdsa_utilities/u32handleobject.h>
  35 #include <security_cdsa_client/keyclient.h>
  36
  37
  38 class Database;
  39
  40
  41 //
  42 // A Key object represents a cryptographic key known to securityd and accessed by clients
  43 // through securityd key references (KeyHandles). A Key may be raw or reference inside securityd,
  44 // but from outside it is always a reference key, and we hide (as best we can) the details of
  45 // its local storage and nature.
  46 //
  47 // Key is a very abstract class; it defines the minimal interface that all actual securityd
  48 // keys must provide. Actual Key subclasses are produced by (subclasses of) Databases, which
  49 // act as Key factories. Most Database subclasses will define Key class hierarchies to track
  50 // their internal structure, but from out here, all we know is that Databases yield Key objects
  51 // when asked nicely, and those subclass objects implement the Key protocol.
  52 //
  53 // A Key can be used by multiple Connections, even at the same time. It is possible for multiple
  54 // Key objects to represent the same underlying cryptographic secret, so don't assume a 1-1 mapping.
  55 //
  56 // Key is completely agnostic as to how the key is stored or maintained.
  57 // For all you know, it might be a virtual artifact of the Key subclass.
  58 //
  59 // All Key subclasses support ACLs. However, different subclasses may host
  60 // their SecurityServerAcls at different levels of the object mesh. Don't assume.
  61 //
  62 // Key::attribute is there for a reason. If you want to check attributes,
  63 // use it rather than returnKey - it may be much, much faster.
  64 //
  65 class Key : public Database::Subsidiary, public AclSource {
  66 public:
  67         Key(Database &db);
  68
  69         virtual const CssmData &canonicalDigest() = 0;
  70
  71         Database &database() const { return referent<Database>(); }
  72
  73         virtual CSSM_KEYATTR_FLAGS attributes() = 0;
  74         bool attribute(CSSM_KEYATTR_FLAGS f) { return attributes() & f; }
  75
  76         virtual void returnKey(U32HandleObject::Handle &h, CssmKey::Header &hdr) = 0;
  77 };
  78
  79
  80 #endif //_H_KEY