org.ccnx.ccn.profiles.security.access.AccessControlManager Class Reference

Abstract class containing core functionality we expect to be common across all access control schemes. More...

Inheritance diagram for org.ccnx.ccn.profiles.security.access.AccessControlManager:

org.ccnx.ccn.profiles.security.access.group.GroupAccessControlManager

List of all members.

Public Member Functions

 AccessControlManager ()
 Subclasses should implement a default constructor and set themselves up with an initialize method.
abstract boolean initialize (AccessControlPolicyMarkerObject policyInformation, CCNHandle handle) throws IOException
String dataKeyLabel ()
 Labels for deriving various types of keys.
CCNHandle handle ()
AccessControlPolicyMarkerObject policy ()
boolean inProtectedNamespace (ContentName content)
ContentName getNamespaceRoot ()
Key getDataKey (ContentName dataNodeName) throws ContentDecodingException, IOException, InvalidKeyException, NoSuchAlgorithmException
 Used by content reader to retrieve the keys necessary to decrypt this content.
abstract NodeKey getDataKeyWrappingKey (ContentName dataNodeName, PublisherPublicKeyDigest publisher) throws AccessDeniedException, InvalidKeyException, ContentEncodingException, IOException, NoSuchAlgorithmException
 Find the key to use to wrap a data key at this node.
abstract Key getDataKeyWrappingKey (ContentName dataNodeName, ContentName wrappingKeyName, Key cachedWrappingKey) throws InvalidKeyException, ContentEncodingException
 Get the data key wrapping key if we happened to have cached a copy of the decryption key.
void storeDataKey (ContentName dataNodeName, Key dataKey, NodeKey wrappingKey) throws InvalidKeyException, ContentEncodingException, IOException
 Wrap a data key in a given node key and store it.
Key generateDataKey (ContentName dataNodeName)
 Generate a random data key.
ContentKeys getContentKeys (ContentName dataNodeName, PublisherPublicKeyDigest publisher) throws InvalidKeyException, AccessDeniedException, IOException, NoSuchAlgorithmException
 Given the name of a content stream, this function verifies that access is allowed and returns the keys required to decrypt the stream.
boolean isProtectedContent (ContentName name, PublisherPublicKeyDigest publisher, ContentType contentType, CCNHandle hande)
 Allow AccessControlManagers to specify some content is not to be protected; for example, access control lists are not themselves encrypted.
void shutdown ()
 Each access control manager subclass should shut down any ongoing network operations.

Static Public Member Functions

static synchronized void registerAccessControlManagerType (ContentName profileName, Class<?extends AccessControlManager > acmClazz)
static AccessControlManager createAccessControlManager (AccessControlPolicyMarkerObject policyInformation, CCNHandle handle) throws ContentNotReadyException, ContentGoneException, ErrorStateException, InstantiationException, IllegalAccessException, IOException
 Make an AccessControlManager of a particular type given stored policy information.
static AccessControlManager createAccessControlManager (ContentName accessControlPolicyName, CCNHandle handle) throws ContentNotReadyException, ContentGoneException, ErrorStateException, ConfigurationException, InstantiationException, IllegalAccessException, IOException
static ContentKeys getDefaultAlgorithmContentKeys (Key dataKey) throws InvalidKeyException
static ContentKeys keysForInput (ContentName name, PublisherPublicKeyDigest publisher, CCNHandle handle) throws IOException
 Called when a stream containing encrypted content is opened for reading, to determine if the name is under a root ACL, and if so find or create an AccessControlManager, and get keys for access.
static ContentKeys keysForOutput (ContentName name, PublisherPublicKeyDigest publisher, ContentType contentType, CCNHandle handle) throws IOException
 Get keys to encrypt content as its' written, if that content is to be protected.
static AccessControlManager findACM (ContentName name, CCNHandle handle) throws IOException
 Find an ACM that controls access to content in a given namespace.
static AccessControlManager loadAccessControlManagerForNamespace (ContentName namespace, CCNHandle handle) throws ContentNotReadyException, ContentGoneException, ErrorStateException, IOException
 Given a name prefix, search for policy markers along that name path and load corresponding access control managers.

Static Public Attributes

static final int DEFAULT_DATA_KEY_LENGTH = 16
 Default data key length in bytes.
static final String DEFAULT_DATA_KEY_ALGORITHM = "AES"
 The keys we're wrapping are really seeds for a KDF, not keys in their own right.
static final String DATA_KEY_LABEL = "Data Key"

Protected Member Functions

abstract Key getDataKeyWrappingKey (ContentName dataNodeName, WrappedKeyObject wrappedDataKeyObject) throws InvalidKeyException, ContentNotReadyException, ContentGoneException, ContentEncodingException, ContentDecodingException, IOException, NoSuchAlgorithmException
WrappedKeyObject retrieveWrappedDataKey (ContentName dataNodeName) throws ContentDecodingException, ContentGoneException, ContentNotReadyException, IOException
void storeKeyContent (ContentName dataNodeName, WrappedKey wrappedKey) throws ContentEncodingException, IOException
 Actual output functions.

Protected Attributes

ContentName _namespace
CCNHandle _handle
SecureRandom _random = new SecureRandom()
AccessControlPolicyMarkerObject _policy

Static Protected Attributes

static Map< ContentName, Class
<?extends AccessControlManager > > 
_accessControlManagerTypes
 Track available access control profiles.

Static Package Functions

 [static initializer]


Detailed Description

Abstract class containing core functionality we expect to be common across all access control schemes.

Key functionality provided:

* maintain static cache of AccessControlManager instances, one per controlled namespace; and provide code to load ACMs (by retrieving a policy marker from a given nametree root and loading the type of ACM specified in that policy marker), and to look them up

* whenever any content is to be written using a CCNOutputStream (or subclass) or network object, keysForOutput is called to determine whether there is an access control manger in force for that content's namespace, and to retrieve the appropriate content encryption keys to protect it using that ACM instance.

* when a piece of encrypted content is read, keysForInput is used to retrieve the keys necessary to decrypt it using the loaded ACM instance for that namespace (TODO could load ACMs automatically in this case); according to the access control scheme supported by that ACM instance

* isProtectedContent determines whether a given piece of content that is about to be written should be encrypted or not. The default policy exempts content of type KEY, LINK, and access control metadata (data used to control access control) from encryption. (TODO need a special encrypted LINK type - ELNK). Subclasses can add to this list of exemptions (by calling super.isProtectedContent to determine their superclass' exemptions and then adding their own. They should not override the superclass' request to exempt something, otherwise things may break (in other words, they can leave unencrypted more content than the superclass suggests, but probably should not encrypt content the superclass says should not be encrypted).

* data key handling -- content streams are encrypted using nonce keys; access control is used to protect those nonce keys. Basic nonce key handling (creation, content encryption) is implemented in this class, protection of nonce keys is left abstract for subclassess to implement.


Member Function Documentation

static AccessControlManager org.ccnx.ccn.profiles.security.access.AccessControlManager.createAccessControlManager ( AccessControlPolicyMarkerObject  policyInformation,
CCNHandle  handle 
) throws ContentNotReadyException, ContentGoneException, ErrorStateException, InstantiationException, IllegalAccessException, IOException [static]

Make an AccessControlManager of a particular type given stored policy information.

Parameters:
policyInformation 
handle 
Returns:
Exceptions:
ContentNotReadyException 
ContentGoneException 
ErrorStateException 
InstantiationException 
IllegalAccessException 
ConfigurationException 
IOException 

String org.ccnx.ccn.profiles.security.access.AccessControlManager.dataKeyLabel (  ) 

Labels for deriving various types of keys.

Returns:

Key org.ccnx.ccn.profiles.security.access.AccessControlManager.getDataKey ( ContentName  dataNodeName  )  throws ContentDecodingException, IOException, InvalidKeyException, NoSuchAlgorithmException

Used by content reader to retrieve the keys necessary to decrypt this content.

Delegates to specific subclasses to retrieve data key using retrieveWrappedDataKey, and then if key used to encrypt data key isn't in cache, delegates retrieving the unwrapping key to subclasses using getDataKeyUnwrappingKey. Provides a default implementation of retrieveDataKey. To turn the result of this into a key for decrypting content, follow the steps in the comments to generateAndStoreDataKey(ContentName).

Parameters:
dataNodeName 
Returns:
Exceptions:
IOException 
ContentDecodingException 
InvalidKeyException 
NoSuchAlgorithmException 

abstract NodeKey org.ccnx.ccn.profiles.security.access.AccessControlManager.getDataKeyWrappingKey ( ContentName  dataNodeName,
PublisherPublicKeyDigest  publisher 
) throws AccessDeniedException, InvalidKeyException, ContentEncodingException, IOException, NoSuchAlgorithmException [pure virtual]

Find the key to use to wrap a data key at this node.

This requires the current effective node key, and wrapping this data key in it. If the current node key is dirty, this causes a new one to be generated. If data at the current node is public, this returns null. Does not check to see whether content is excluded from encryption (e.g. by being access control data).

Parameters:
dataNodeName the node for which to find a data key wrapping key
publisher in case output key retrieval needs to be specialized by publisher
Returns:
if null, the data is to be unencrypted. (Alteratively, could return a NodeKey that indicates public.)
Parameters:
newRandomDataKey 
Exceptions:
AccessDeniedException if we don't have rights to retrieve key.
InvalidKeyException 
ContentEncodingException 
IOException 
NoSuchAlgorithmException 

Implemented in org.ccnx.ccn.profiles.security.access.group.GroupAccessControlManager.

abstract Key org.ccnx.ccn.profiles.security.access.AccessControlManager.getDataKeyWrappingKey ( ContentName  dataNodeName,
ContentName  wrappingKeyName,
Key  cachedWrappingKey 
) throws InvalidKeyException, ContentEncodingException [pure virtual]

Get the data key wrapping key if we happened to have cached a copy of the decryption key.

Parameters:
dataNodeName 
wrappedDataKeyObject 
cachedWrappingKey 
Returns:
Exceptions:
ContentEncodingException 
InvalidKeyException 

Implemented in org.ccnx.ccn.profiles.security.access.group.GroupAccessControlManager.

void org.ccnx.ccn.profiles.security.access.AccessControlManager.storeDataKey ( ContentName  dataNodeName,
Key  dataKey,
NodeKey  wrappingKey 
) throws InvalidKeyException, ContentEncodingException, IOException

Wrap a data key in a given node key and store it.

Parameters:
dataNodeName 
dataKey 
wrappingKey 
Exceptions:
InvalidKeyException 
ContentEncodingException 
IOException 

void org.ccnx.ccn.profiles.security.access.AccessControlManager.storeKeyContent ( ContentName  dataNodeName,
WrappedKey  wrappedKey 
) throws ContentEncodingException, IOException [protected]

Actual output functions.

Parameters:
dataNodeName -- the content node for whom this is the data key.
wrappedDataKey 
Exceptions:
IOException 
ContentEncodingException 

ContentKeys org.ccnx.ccn.profiles.security.access.AccessControlManager.getContentKeys ( ContentName  dataNodeName,
PublisherPublicKeyDigest  publisher 
) throws InvalidKeyException, AccessDeniedException, IOException, NoSuchAlgorithmException

Given the name of a content stream, this function verifies that access is allowed and returns the keys required to decrypt the stream.

Parameters:
dataNodeName The name of the stream, including version component, but excluding segment component.
publisher the publisher to get keys for, if it matters
Returns:
Returns the keys ready to be used for en/decryption, or null if the content is not encrypted.
Exceptions:
IOException 
InvalidKeyException 
AccessDeniedException 
NoSuchAlgorithmException 

static ContentKeys org.ccnx.ccn.profiles.security.access.AccessControlManager.keysForInput ( ContentName  name,
PublisherPublicKeyDigest  publisher,
CCNHandle  handle 
) throws IOException [static]

Called when a stream containing encrypted content is opened for reading, to determine if the name is under a root ACL, and if so find or create an AccessControlManager, and get keys for access.

Parameters:
name name of the stream to be opened, without the segment number
publisher the publisher of the stream to open, in case that matters for key retrieva
library CCN Library instance to use for any network operations.
Returns:
If the stream is under access control then keys to decrypt the data are returned if it's encrypted. If the stream is not under access control (no Root ACL block can be found) then null is returned.
Exceptions:
IOException if a problem happens getting keys.

static ContentKeys org.ccnx.ccn.profiles.security.access.AccessControlManager.keysForOutput ( ContentName  name,
PublisherPublicKeyDigest  publisher,
ContentType  contentType,
CCNHandle  handle 
) throws IOException [static]

Get keys to encrypt content as its' written, if that content is to be protected.

Called by the CCNOutputStream subclasses to get encryption keys for specific content segments.

Parameters:
name 
publisher 
type the type of content to be written. Mostly used to determine whether content is protected, but could also be used to specialize keys.
handle 
Returns:
Exceptions:
IOException 

static AccessControlManager org.ccnx.ccn.profiles.security.access.AccessControlManager.findACM ( ContentName  name,
CCNHandle  handle 
) throws IOException [static]

Find an ACM that controls access to content in a given namespace.

Only looks in the cache of already-loaded AccessControlManagers; it doesn't load additional ACMs or search for policy objects. This is called by keysForOutput *every* time content is written. It can't do extensive search. Use loadAccessControlManagerForNamespace to load an ACM for a namespace if policy specifies to use one.

Parameters:
name 
handle 
Returns:
null if namespace is not under access control, or an ACM to perform operations on the name if it is.
Exceptions:
IOException 

static AccessControlManager org.ccnx.ccn.profiles.security.access.AccessControlManager.loadAccessControlManagerForNamespace ( ContentName  namespace,
CCNHandle  handle 
) throws ContentNotReadyException, ContentGoneException, ErrorStateException, IOException [static]

Given a name prefix, search for policy markers along that name path and load corresponding access control managers.

TODO handle multiple policy points TODO maybe handle policies overlapping in namespace

Parameters:
namespace 
handle 
Returns:
The ACM we find if one already existed, or the new one we created, if configured; if no AC configured for this namespace, return null;
Exceptions:
ConfigurationException 
ContentNotReadyException 
ContentGoneException 
ErrorStateException 
IOException 

boolean org.ccnx.ccn.profiles.security.access.AccessControlManager.isProtectedContent ( ContentName  name,
PublisherPublicKeyDigest  publisher,
ContentType  contentType,
CCNHandle  hande 
)

Allow AccessControlManagers to specify some content is not to be protected; for example, access control lists are not themselves encrypted.

TODO: should headers be exempt from encryption?

Reimplemented in org.ccnx.ccn.profiles.security.access.group.GroupAccessControlManager.

void org.ccnx.ccn.profiles.security.access.AccessControlManager.shutdown (  ) 

Each access control manager subclass should shut down any ongoing network operations.

We don't own our handle, so can't close that. But any outstanding interests should be canceled; filters should be unregistered, and so on.


Member Data Documentation

Initial value:

 
                new TreeMap<ContentName, Class<? extends AccessControlManager>>()
Track available access control profiles.

Default data key length in bytes.

No real reason this can't be bumped up to 32. It acts as the seed for a KDF, not an encryption key.

The keys we're wrapping are really seeds for a KDF, not keys in their own right.

Eventually we'll use CMAC, so call them AES...


The documentation for this class was generated from the following file:

Generated on Thu Feb 16 00:45:04 2012 for Content-Centric Networking in Java by  doxygen 1.5.6