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...
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. |
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.
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.
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. |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
InvalidKeyException | ||
ContentEncodingException |
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.