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
35class 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//
59class LocalKey : public Key {
60public:
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
81public:
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
97private:
98	void setup(const CssmKey &newKey, CSSM_KEYATTR_FLAGS attrs);
99	CssmClient::Key keyValue();
100
101protected:
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
108protected:
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
118