org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction Class Reference

This class takes a master symmetric key, and derives from it a key and initialization vector to be used to encrypt a specific content object. More...

List of all members.

Static Public Member Functions

static final KeyAndIV DeriveKeysForObject (String keyAlgorithm, byte[] masterKeyBytes, ContentInfo contentInfo) throws InvalidKeyException, ContentEncodingException
 Default parameterization of the KDF for standard algorithm type.
static final KeyAndIV DeriveKeysForObject (String keyAlgorithm, byte[] masterKeyBytes, int keyBitLength, int ivBitLength, ContentInfo contentInfo) throws InvalidKeyException, ContentEncodingException
 Derive a key and IV for a particular object.
static final byte[] DeriveKeyForNode (byte[] parentNodeKeyBytes, String label, ContentName nodeName) throws InvalidKeyException, ContentEncodingException
 Used to derive keys for nodes in a name hierarchy.
static final byte[] DeriveKeyForNode (ContentName ancestorNodeName, byte[] ancestorNodeKey, String label, ContentName nodeName) throws InvalidKeyException, ContentEncodingException
 Hierarchically derive keys for a child node, given an ancestor key.
static final byte[] DeriveKeyForNode (byte[] parentNodeKeyBytes, int keyLengthInBits, String label, ContentName nodeName) throws InvalidKeyException, ContentEncodingException
static final byte[] DeriveKeyForObjectOrNode (byte[] masterKeyBytes, int outputLengthInBits, ContentInfo contentInfo) throws InvalidKeyException, ContentEncodingException
 Derive a key for a particular object.
static final byte[] DeriveKey (byte[] masterKeyBytes, int outputLengthInBits, String label, XMLEncodable[] contextObjects) throws InvalidKeyException, ContentEncodingException
 Core key derivation mechanism.

Static Protected Attributes

static final String MAC_ALGORITHM = "HmacSHA256"
 MAC algorithm used as a PRF.

Detailed Description

This class takes a master symmetric key, and derives from it a key and initialization vector to be used to encrypt a specific content object.

This simplifies key management by allowing the same master key to be used for families of related content (e.g. all the versions of a file, all of the intrinsic metadata associated with that file, etc.), without having to manage an additional separately wrapped master key. It allows hierarchically delegated access control (i.e. when the children of a node inherit the permissions associated with that node) to proceed without requiring additional keys. It also acts to prevent errors, by limiting the risk of IV/counter reuse, both by distributing encryption across many derived keys, and deriving the IV/counter seeds automatically for programmers.

NOTE: This is a low-level cryptographic API. This class is used internally by CCN's built in access control prototype, and may be used for key derivation in general, for people building other encryption models for CCN. However, if you don't already know what "key derivation" means, you should NOT be using it -- there is probably a different API that more closely fits your needs.

For each block, we compute the PRF using key K over (counter || label || 0x00 || context || L) where L is the desired output length in bits.

We encode the counter and L both in 32 bit fields. The counter is initialized to 1.

The KDF implemented herein is from NIST special publication 108-008, and is described in more detail in the CCN documentation.


Member Function Documentation

static final byte [] org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKey ( byte[]  masterKeyBytes,
int  outputLengthInBits,
String  label,
XMLEncodable[]  contextObjects 
) throws InvalidKeyException, ContentEncodingException [static]

Core key derivation mechanism.

Parameters:
masterKeyBytes master key to derive a new key from
outputLengthInBits bit length of key to derive
label a text label to allow derivation of multiple key types from a single source key/path pair
contextObjects objects to add into the KDF as context. Usually at least the name of the node, also possibly the publisher.
Returns:
the derived key
Exceptions:
InvalidKeyException 
ContentEncodingException 
static final byte [] org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKeyForNode ( ContentName  ancestorNodeName,
byte[]  ancestorNodeKey,
String  label,
ContentName  nodeName 
) throws InvalidKeyException, ContentEncodingException [static]

Hierarchically derive keys for a child node, given an ancestor key.

Why not do this in one step, with no intervening keys? This way we can delegate/install backlinks to keys in the middle of the hierarchy and things continue to work.

Parameters:
ancestorNodeName the node with whom ancestorNodeKey is associated.
ancestorNodeKey the key associated with that ancestor node
label a text label to allow derivation of multiple key types from a single source key/path pair
nodeName the name of the node to derive a key for
Exceptions:
InvalidKeyException 
ContentEncodingException 
static final byte [] org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKeyForNode ( byte[]  parentNodeKeyBytes,
String  label,
ContentName  nodeName 
) throws InvalidKeyException, ContentEncodingException [static]

Used to derive keys for nodes in a name hierarchy.

The key must be independent of publisher, as it is used to derive keys for intermediate nodes. As this is used as input to another key derivation call, no IV is derived.

Parameters:
parentNodeKeyBytes the initial source key to derive further keys from
label a text label to allow derivation of multiple key types from a single source key/path pair
nodeName the name of the node to derive a key for
Exceptions:
InvalidKeyException 
ContentEncodingException 
static final byte [] org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKeyForObjectOrNode ( byte[]  masterKeyBytes,
int  outputLengthInBits,
ContentInfo  contentInfo 
) throws InvalidKeyException, ContentEncodingException [static]

Derive a key for a particular object.

Requested bit lengths must be divisible by BITS_PER_BYTE.

Parameters:
masterKeyBytes master key to derive a new key from
outputLengthInBits bit length of key to derive
label a text label to allow derivation of multiple key types from a single source key/path pair
contentName name to derive a key for
publisher publisher whose version of contentName we want to derive for
Returns:
returns a key for this object
Exceptions:
InvalidKeyException 
ContentEncodingException 
static final KeyAndIV org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKeysForObject ( String  keyAlgorithm,
byte[]  masterKeyBytes,
int  keyBitLength,
int  ivBitLength,
ContentInfo  contentInfo 
) throws InvalidKeyException, ContentEncodingException [static]

Derive a key and IV for a particular object.

Requested bit lengths must be divisible by BITS_PER_BYTE.

Parameters:
masterKeyBytes master key to derive a new key from
keyBitLength bit length of key to derive
ivBitLength bit length of iv to derive
label a text label to allow derivation of multiple key types from a single source key/path pair
contentName name to derive a key for
publisher publisher whose version of contentName we want to derive for
Returns:
returns an {key, iv/counter seed} pair suitable for use in segment encryption
Exceptions:
InvalidKeyException 
ContentEncodingException 
static final KeyAndIV org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.DeriveKeysForObject ( String  keyAlgorithm,
byte[]  masterKeyBytes,
ContentInfo  contentInfo 
) throws InvalidKeyException, ContentEncodingException [static]

Default parameterization of the KDF for standard algorithm type.

This is the routine that will be typically used by code that does not want to override default algorithms.

Parameters:
masterKeyBytes the source key from which to derive a subkey
label a text label for additional parameterization, if desired
contentName name of the specific object to derive a key for, including the version (but not including segment information).
publisher for this particular set of objects
Exceptions:
InvalidKeyException 
ContentEncodingException 

Member Data Documentation

final String org.ccnx.ccn.impl.security.crypto.KeyDerivationFunction.MAC_ALGORITHM = "HmacSHA256" [static, protected]

MAC algorithm used as a PRF.

We use HMAC-SHA256 as our primary PRF, because it is the most commonly implemented acceptable option. CMAC would be preferable, but is not universally available yet.


The documentation for this class was generated from the following file:
Generated on Fri May 13 16:27:41 2011 for Content-Centric Networking in Java by  doxygen 1.6.3