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