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

This is a very simple approach to encryption keying that uses a fixed, static encryption key and an IV "seed" that is used to prefix segment-specific IVs or counters. More...

List of all members.

Public Member Functions

 StaticContentKeys (String encryptionAlgorithm, byte[] key, byte[] ivCtr) throws NoSuchAlgorithmException, NoSuchPaddingException
 StaticContentKeys constructor.
 StaticContentKeys (byte[] key, byte[] ivCtr) throws NoSuchAlgorithmException, NoSuchPaddingException
 Create a StaticContentKeys with the default algorithm.
 StaticContentKeys (String encryptionAlgorithm, Key key, byte[] ivCtr) throws NoSuchAlgorithmException, NoSuchPaddingException
 StaticContentKeys constructor.
 StaticContentKeys (ContentKeys other)
ContentKeys clone ()
IvParameterSpec buildIVCtr (KeyAndIV keyAndIV, long segmentNumber, int ctrLen) throws InvalidKeyException, InvalidAlgorithmParameterException
 Turn a master IV and a segment number into an initial counter of IV for this segment (used in CTR mode).

Static Public Member Functions

static synchronized ContentKeys generateRandomKeys () throws NoSuchAlgorithmException, NoSuchPaddingException
 Create a set of random encryption/decryption keys using the default algorithm.
static byte[] segmentSeedValue (byte[] ivCtr, long segmentNumber, int seedLen)

Static Public Attributes

static final int IV_MASTER_LENGTH = 8
static final int SEGMENT_NUMBER_LENGTH = 6
static final int BLOCK_COUNTER_LENGTH = INITIAL_BLOCK_COUNTER_VALUE.length

Protected Member Functions

Cipher getSegmentCipher (ContentName contentName, PublisherPublicKeyDigest publisher, long segmentNumber, boolean encryption) throws InvalidKeyException, InvalidAlgorithmParameterException, ContentEncodingException
 Generate a segment encryption or decryption cipher using this stored key material to encrypt or decrypt a particular segment.
KeyAndIV getKeyAndIVForContent (ContentName contentName, PublisherPublicKeyDigest publisher, long segmentNumber) throws InvalidKeyException, ContentEncodingException

Detailed Description

This is a very simple approach to encryption keying that uses a fixed, static encryption key and an IV "seed" that is used to prefix segment-specific IVs or counters.

The segmenter will be called with parameters identifying:

* the encryption algorithm and mode to use, if any * the encryption key to use for this particular data item (the object to be segmented) * an 8-byte value used as an IV seed for this item (CBC or other block mode) or a random counter component (CTR) (derived in KeyDerivation) * the desired full segment (packet) length, including supporting data

The initial counter or IV for a given block B (number Bnum) in segment Snum will be constructed as follows:

Block IV/CTR = IVseed || Snum || Bnum

where the segment and block numbers is represented in unsigned, 1-based big endian format.

The total width of the IV/Counter value is B, the block width of the cipher. For a stream cipher (e.g. CTR mode), the width B is taken to be 16 bytes.

This IV/CTR is divided into 3 components:

Master IV/IVseed : the master IV seed value, specified by the caller. For this simple static key approach, this is by default 8 bytes. It is given by masterIVLength().

Segment number: this is a binary representation of the segment number. A single-segment object following the SegmentationProfile will still have a segment number component in its name, and will use the specified segment number (usually SegmentationProfile.baseSegment()).

The segment number is encoded in 1-based, unsigned, big-endian form, and represented in the L-N rightmost bytes of the plaintext above, where L is the length of the numeric representation of the segment number, and N is the length of the block number within the segment (for CTR mode, this value is fixed at 1 for CBC and other block modes).

The default width of the segment number is 6 bytes, leaving 8 bytes for the default Master IV width.

Block number: for CTR mode, the last 2 bytes of the IV contain the block (counter) index, starting with 1. For CBC and other block modes, that last two bytes contains the (big endian) value 0x0001.

The same IV expansion function is used regardless of mode for simplicity.

Many of the expansion function calculations are broken out into separate methods to allow for easier subclassing.

IMPORTANT NOTE: Do not use static keying to encrypt network objects in CTR mode, unless you are careful to only save them once per key. Use CBC mode (under development) or a dynamic keying method, such as KDFContentKeys.


Constructor & Destructor Documentation

org.ccnx.ccn.impl.security.crypto.StaticContentKeys.StaticContentKeys ( String  encryptionAlgorithm,
byte[]  key,
byte[]  ivCtr 
) throws NoSuchAlgorithmException, NoSuchPaddingException

StaticContentKeys constructor.

Parameters:
encryptionAlgorithm (e.g. AES/CTR/NoPadding) the encryption algorithm to use. First component of algorithm should be the algorithm associated with the key.
key key material to be used
ivctr iv or counter material to be used with specified algorithm
Exceptions:
NoSuchPaddingException 
NoSuchAlgorithmException 
org.ccnx.ccn.impl.security.crypto.StaticContentKeys.StaticContentKeys ( byte[]  key,
byte[]  ivCtr 
) throws NoSuchAlgorithmException, NoSuchPaddingException

Create a StaticContentKeys with the default algorithm.

Exceptions:
NoSuchPaddingException 
NoSuchAlgorithmException 

Member Function Documentation

IvParameterSpec org.ccnx.ccn.impl.security.crypto.StaticContentKeys.buildIVCtr ( KeyAndIV  keyAndIV,
long  segmentNumber,
int  ctrLen 
) throws InvalidKeyException, InvalidAlgorithmParameterException

Turn a master IV and a segment number into an initial counter of IV for this segment (used in CTR mode).

Parameters:
masterIV the master IV
segmentNumber the segment number
ctrLen the output IV length requested
Returns:
the initial counter
Exceptions:
InvalidAlgorithmParameterException 
InvalidKeyException 

Reimplemented in org.ccnx.ccn.impl.security.crypto.EncryptedIVStaticContentKeys.

static synchronized ContentKeys org.ccnx.ccn.impl.security.crypto.StaticContentKeys.generateRandomKeys (  )  throws NoSuchAlgorithmException, NoSuchPaddingException [static]

Create a set of random encryption/decryption keys using the default algorithm.

Returns:
a randomly-generated set of keys and IV that can be used for encryption
Exceptions:
NoSuchPaddingException 
NoSuchAlgorithmException 

Reimplemented in org.ccnx.ccn.impl.security.crypto.EncryptedIVStaticContentKeys.

Cipher org.ccnx.ccn.impl.security.crypto.StaticContentKeys.getSegmentCipher ( ContentName  contentName,
PublisherPublicKeyDigest  publisher,
long  segmentNumber,
boolean  encryption 
) throws InvalidKeyException, InvalidAlgorithmParameterException, ContentEncodingException [protected, virtual]

Generate a segment encryption or decryption cipher using this stored key material to encrypt or decrypt a particular segment.

This will use the CCN defaults for IV handling, to ensure that segments of a given larger piece of content do not have overlapping key streams. Higher-level functionality embodied in the library (or application-specific code) should be used to make sure that the key, _masterIV pair used for a given multi-block piece of content is unique for that content.

CCN encryption algorithms assume deterministic IV generation (e.g. from cryptographic MAC or ciphers themselves), and therefore do not transport the IV explicitly. Applications that wish to do so need to arrange IV transport.

We assume this stream starts on the first block of a multi-block segement, so for CTR mode, the initial block counter is 1 (block == encryption block). (Conventions for counter start them at 1, not 0.) The cipher will automatically increment the counter; if it overflows the two bytes we've given to it it will start to increment into the segment number. This runs the risk of potentially using up some of the IV space of other segments.

CTR_init = IV_master || segment_number || block_counter CBC_iv = E_Ko(IV_master || segment_number || 0x0001) (just to make it easier, use the same feed value)

CTR value is 16 bytes. 8 bytes are the IV. 6 bytes are the segment number. last 2 bytes are the block number (for 16 byte blocks); if you have more space, use it for the block counter. IV value is the block width of the cipher.

Parameters:
segmentNumber segment to encrypt/decrypt
encryption true for encryption, false for decryption
Returns:
the Cipher
Exceptions:
InvalidKeyException 
InvalidAlgorithmParameterException 
ContentEncodingException 
See also:
getSegmentEncryptionCipher(long)

Implements org.ccnx.ccn.impl.security.crypto.ContentKeys.


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