Security-57031.1.35.tar.gz

[apple/security.git] / securityd / src / key.h

diff --git a/securityd/src/key.h b/securityd/src/key.h
new file mode 100644 (file)
index 0000000..94c98cc
--- /dev/null
+++ b/securityd/src/key.h
@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2000-2004,2008 Apple Inc. All Rights Reserved.
+ * 
+ * @APPLE_LICENSE_HEADER_START@
+ * 
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ * 
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ * 
+ * @APPLE_LICENSE_HEADER_END@
+ */
+
+
+//
+// key - representation of securityd key objects
+//
+#ifndef _H_KEY
+#define _H_KEY
+
+#include "structure.h"
+#include "database.h"
+#include "acls.h"
+#include <security_cdsa_utilities/u32handleobject.h>
+#include <security_cdsa_client/keyclient.h>
+
+
+class Database;
+
+
+//
+// A Key object represents a cryptographic key known to securityd and accessed by clients
+// through securityd key references (KeyHandles). A Key may be raw or reference inside securityd,
+// but from outside it is always a reference key, and we hide (as best we can) the details of
+// its local storage and nature.
+//
+// Key is a very abstract class; it defines the minimal interface that all actual securityd
+// keys must provide. Actual Key subclasses are produced by (subclasses of) Databases, which
+// act as Key factories. Most Database subclasses will define Key class hierarchies to track
+// their internal structure, but from out here, all we know is that Databases yield Key objects
+// when asked nicely, and those subclass objects implement the Key protocol.
+//
+// A Key can be used by multiple Connections, even at the same time. It is possible for multiple
+// Key objects to represent the same underlying cryptographic secret, so don't assume a 1-1 mapping.
+//
+// Key is completely agnostic as to how the key is stored or maintained.
+// For all you know, it might be a virtual artifact of the Key subclass.
+//
+// All Key subclasses support ACLs. However, different subclasses may host
+// their SecurityServerAcls at different levels of the object mesh. Don't assume.
+//
+// Key::attribute is there for a reason. If you want to check attributes,
+// use it rather than returnKey - it may be much, much faster.
+//
+class Key : public Database::Subsidiary, public AclSource {
+public:
+       Key(Database &db);
+       
+       virtual const CssmData &canonicalDigest() = 0;
+       
+       Database &database() const { return referent<Database>(); }
+       
+       virtual CSSM_KEYATTR_FLAGS attributes() = 0;
+       bool attribute(CSSM_KEYATTR_FLAGS f) { return attributes() & f; }
+       
+       virtual void returnKey(U32HandleObject::Handle &h, CssmKey::Header &hdr) = 0;
+};
+
+
+#endif //_H_KEY