org.ccnx.ccn.impl.CCNSegmenter Class Reference

Combines segmentation, signing and encryption. More...

List of all members.

Public Member Functions

 CCNSegmenter () throws ConfigurationException, IOException
 Create a segmenter with default (Merkle hash tree) bulk signing behavior, making a new handle for it to use.
 CCNSegmenter (CCNHandle handle) throws IOException
 Create a segmenter with default (Merkle hash tree) bulk signing behavior.
 CCNSegmenter (CCNFlowControl flowControl)
 Create a segmenter with default (Merkle hash tree) bulk signing behavior.
 CCNSegmenter (CCNFlowControl flowControl, CCNAggregatedSigner signer)
 Create a segmenter, specifying the signing behavior to use.
CCNHandle getLibrary ()
CCNFlowControl getFlowControl ()
ContentObject getFirstSegment ()
 Return the first segment.
void setBlockSize (int blockSize)
 Sets the segmentation block size to use.
int getBlockSize ()
 Gets the current block size.
void useByteCountSequenceNumbers ()
void useFixedIncrementSequenceNumbers (int increment)
void useScaledByteCountSequenceNumbers (int scale)
void setSequenceType (SegmentNumberType seqType)
void setBlockIncrement (int blockIncrement)
 Sets the increment between block numbers.
int getBlockIncrement ()
 Gets the increment between block numbers.
void setByteScale (int byteScale)
int getByteScale ()
long put (ContentName name, byte[] content, int offset, int length, boolean lastSegments, SignedInfo.ContentType type, Integer freshnessSeconds, KeyLocator locator, PublisherPublicKeyDigest publisher, ContentKeys keys) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException
 Puts a complete data item, segmenting it if necessary.
long fragmentedPut (ContentName name, byte[] content, int offset, int length, Long finalSegmentIndex, SignedInfo.ContentType type, Integer freshnessSeconds, KeyLocator locator, PublisherPublicKeyDigest publisher, ContentKeys keys) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException
 Segments content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.
long fragmentedPut (ContentName name, long baseSegmentNumber, byte[] content, int offset, int length, int blockWidth, ContentType type, CCNTime timestamp, Integer freshnessSeconds, Long finalSegmentIndex, KeyLocator locator, PublisherPublicKeyDigest publisher, ContentKeys keys) throws InvalidKeyException, SignatureException, IOException, InvalidAlgorithmParameterException, NoSuchAlgorithmException
 Segments content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.
long fragmentedPut (ContentName name, long baseSegmentNumber, byte contentBlocks[][], int blockCount, int firstBlockIndex, int lastBlockLength, ContentType type, CCNTime timestamp, Integer freshnessSeconds, Long finalSegmentIndex, KeyLocator locator, PublisherPublicKeyDigest publisher, ContentKeys keys) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException
 Takes pre-segmented content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.
long putFragment (ContentName name, long segmentNumber, byte[] content, int offset, int length, ContentType type, CCNTime timestamp, Integer freshnessSeconds, Long finalSegmentIndex, KeyLocator locator, PublisherPublicKeyDigest publisher, ContentKeys keys) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException
 Puts a single block of content of arbitrary length using a segment naming convention.
long nextSegmentIndex (long lastSegmentNumber, long lastSegmentLength)
 Increment segment number according to the numbering profile in force.
Long lastSegmentIndex (long currentSegmentNumber, long bytesIntervening, int blocksRemaining)
 Compute the index of the last block of a set of segments, according to the numbering profile.
void setTimeout (int timeout)
 Set the timeout on the contained flow controller.
long outputLength (int inputLength, ContentKeys keys)
 How many content bytes will it take to represent content of length length, including any padding incurred by encryption?

Static Public Member Functions

static CCNSegmenter getBlockSegmenter (int blockSize, CCNFlowControl flowControl)
 Factory method to create a standard segmenter that generates blocks of fixed length in bytes.
static CCNSegmenter getScaledByteCountSegmenter (int scale, CCNFlowControl flowControl)
 Factory method to create a standard segmenter that generates blocks of variable length in bytes, whose segment numbers are scaled by a fixed increment.
static CCNSegmenter getByteCountSegmenter (CCNFlowControl flowControl)
 Factory method to create a standard segmenter that generates blocks of variable length in bytes, whose segment numbers are scaled by a fixed increment.

Static Public Attributes

static final int HOLD_COUNT = 128
 Number of content objects we keep around prior to signing and outputting to the flow controller Note that the flow controller also uses this value to determine its default high water mark.
static final String PROP_BLOCK_SIZE = "ccn.lib.blocksize"
static final long LAST_SEGMENT = Long.valueOf(-1)

Protected Member Functions

void initializeBlockSize ()
void outputCurrentBlocks (PrivateKey signingKey) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException
 Sign and output all outstanding blocks to the flow controller.
long buildBlocks (ContentName rootName, long baseSegmentNumber, SignedInfo signedInfo, byte[] content, int offset, int length, int blockWidth, ContentKeys keys, PrivateKey signingKey, boolean finalFlush) throws InvalidKeyException, InvalidAlgorithmParameterException, IOException, SignatureException, NoSuchAlgorithmException
 Helper method to build ContentObjects for segments out of a contiguous buffer.
long newBlock (ContentName rootName, long segmentNumber, SignedInfo signedInfo, byte contentBlock[], int offset, int blockLength, ContentKeys keys) throws InvalidKeyException, InvalidAlgorithmParameterException, ContentEncodingException
 Create a ContentObject, encrypt it if requested, and add it to the list of ContentObjects awaiting signing and output to the flow controller.

Protected Attributes

int _blockSize = SegmentationProfile.DEFAULT_BLOCKSIZE
int _blockIncrement = SegmentationProfile.DEFAULT_INCREMENT
int _byteScale = SegmentationProfile.DEFAULT_SCALE
SegmentNumberType _sequenceType = SegmentNumberType.SEGMENT_FIXED_INCREMENT
ArrayList< ContentObject_blocks = new ArrayList<ContentObject>(HOLD_COUNT + 1)
CCNHandle _handle
CCNFlowControl _flowControl
 Eventually may not contain this; callers may access it exogenously.
CCNAggregatedSigner _bulkSigner
 Handle multi-block amortized signing.
ContentObject _firstSegment = null
 The first segment, useful for obtaining starting segment number and digest to characterize set of segmented content.

Detailed Description

Combines segmentation, signing and encryption.

This is used to prepare data for writing out to ccnd. The intent is to provide a user-friendly, efficient, minimum-copy interface, with some support for extensibility.

Overall this class attempts to minimize copying of data. Data must be copied into final ContentObjects returned by the signing operations. On the way, it may need to pass through a block encrypter, which may perform local copies. Higher-level constructs, such as streams, may buffer it above.


Constructor & Destructor Documentation

org.ccnx.ccn.impl.CCNSegmenter.CCNSegmenter (  )  throws ConfigurationException, IOException

Create a segmenter with default (Merkle hash tree) bulk signing behavior, making a new handle for it to use.

Exceptions:
ConfigurationException if there is a problem creating the handle
IOException if there is a problem creating the handle
org.ccnx.ccn.impl.CCNSegmenter.CCNSegmenter ( CCNHandle  handle  )  throws IOException

Create a segmenter with default (Merkle hash tree) bulk signing behavior.

Parameters:
handle the handle to use, will open a new one if null
Exceptions:
IOException if there is a problem creating the handle
org.ccnx.ccn.impl.CCNSegmenter.CCNSegmenter ( CCNFlowControl  flowControl  ) 

Create a segmenter with default (Merkle hash tree) bulk signing behavior.

Parameters:
flowControl the specified flow controller to use
org.ccnx.ccn.impl.CCNSegmenter.CCNSegmenter ( CCNFlowControl  flowControl,
CCNAggregatedSigner  signer 
)

Create a segmenter, specifying the signing behavior to use.

Parameters:
flowControl the specified flow controller to use
signer the bulk signer to use. If null, will use default Merkle hash tree behavior.

Member Function Documentation

long org.ccnx.ccn.impl.CCNSegmenter.buildBlocks ( ContentName  rootName,
long  baseSegmentNumber,
SignedInfo  signedInfo,
byte[]  content,
int  offset,
int  length,
int  blockWidth,
ContentKeys  keys,
PrivateKey  signingKey,
boolean  finalFlush 
) throws InvalidKeyException, InvalidAlgorithmParameterException, IOException, SignatureException, NoSuchAlgorithmException [protected]

Helper method to build ContentObjects for segments out of a contiguous buffer.

Parameters:
rootName 
baseSegmentNumber 
signedInfo 
content 
offset 
length 
blockWidth 
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
signingKey 
Returns:
Exceptions:
InvalidKeyException 
InvalidAlgorithmParameterException 
IOException 
NoSuchAlgorithmException 
SignatureException 
long org.ccnx.ccn.impl.CCNSegmenter.fragmentedPut ( ContentName  name,
long  baseSegmentNumber,
byte  contentBlocks[][],
int  blockCount,
int  firstBlockIndex,
int  lastBlockLength,
ContentType  type,
CCNTime  timestamp,
Integer  freshnessSeconds,
Long  finalSegmentIndex,
KeyLocator  locator,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys 
) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException

Takes pre-segmented content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.

Parameters:
name name prefix to use for the segments
baseSegmentNumber the segment number to start this batch with
contentBlocks content buffers containing content to put, one buffer per ContentObject
blockCount the number of these content buffers to write
firstBlockIndex the index into the content buffer array to start writing blocks
lastBlockLength the number of bytes of the last block to be written to use -- this allows a fixed set of byte [] to be used to buffer content for segmentation, and still cope with variable-length last blocks
type the type for the content
timestamp the timestamp for the content
freshnessSeconds the number of seconds this content should be considered fresh, or null to leave unset
finalSegmentIndex the expected segment number of the last segment of this stream, null to omit, Long(-1) to set as the last segment of this put, whatever its number turns out to be
locator the key locator to use
publisher the publisher to use
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
Returns:
returns the segment identifier for the next segment to be written, if any. If the caller doesn't want to override this, they can hand this number back to a subsequent call to fragmentedPut.
Exceptions:
InvalidKeyException 
SignatureException 
NoSuchAlgorithmException 
IOException 
InvalidAlgorithmParameterException 
See also:
fragmentedPut(ContentName, byte[], int, int, Long, ContentType, Integer, KeyLocator, PublisherPublicKeyDigest) Starts segmentation at segment SegmentationProfile().baseSegment().
long org.ccnx.ccn.impl.CCNSegmenter.fragmentedPut ( ContentName  name,
long  baseSegmentNumber,
byte[]  content,
int  offset,
int  length,
int  blockWidth,
ContentType  type,
CCNTime  timestamp,
Integer  freshnessSeconds,
Long  finalSegmentIndex,
KeyLocator  locator,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys 
) throws InvalidKeyException, SignatureException, IOException, InvalidAlgorithmParameterException, NoSuchAlgorithmException

Segments content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.

NOTE - ControlFlow.addNameSpace must be done before calling this

Parameters:
name name prefix to use for the segments
baseSegmentNumber the segment number to start this batch with
content content buffer containing content to put
offset offset into buffer at which to start reading content to put
length number of bytes of buffer to put
blockWidth the block size to use
type the type for the content
timestamp the timestamp for the content
freshnessSeconds the number of seconds this content should be considered fresh, or null to leave unset
finalSegmentIndex the expected segment number of the last segment of this stream, null to omit, Long(-1) to set as the last segment of this put, whatever its number turns out to be
locator the key locator to use
publisher the publisher to use
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
Returns:
returns the segment identifier for the next segment to be written, if any. If the caller doesn't want to override this, they can hand this number back to a subsequent call to fragmentedPut.
Exceptions:
InvalidKeyException 
SignatureException 
NoSuchAlgorithmException 
IOException 
InvalidAlgorithmParameterException 
See also:
fragmentedPut(ContentName, byte[], int, int, Long, ContentType, Integer, KeyLocator, PublisherPublicKeyDigest) Starts segmentation at segment SegmentationProfile().baseSegment().
long org.ccnx.ccn.impl.CCNSegmenter.fragmentedPut ( ContentName  name,
byte[]  content,
int  offset,
int  length,
Long  finalSegmentIndex,
SignedInfo.ContentType  type,
Integer  freshnessSeconds,
KeyLocator  locator,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys 
) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException

Segments content, builds segment names and ContentObjects, signs them, and writes them to the flow controller to go out to the network.

Low-level segmentation interface. Assume arguments have been cleaned prior to arrival -- name is not already segmented, type is set, etc.

Starts segmentation at segment SegmentationProfile().baseSegment().

Parameters:
name name prefix to use for the segments
content content buffer containing content to put
offset offset into buffer at which to start reading content to put
length number of bytes of buffer to put
finalSegmentIndex the expected segment number of the last segment of this stream, null to omit, Long(-1) to set as the last segment of this put, whatever its number turns out to be
type the type for the content
freshnessSeconds the number of seconds this content should be considered fresh, or null to leave unset
locator the key locator to use
publisher the publisher to use
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
Returns:
returns the segment identifier for the next segment to be written, if any. If the caller doesn't want to override this, they can hand this number back to a subsequent call to fragmentedPut.
Exceptions:
InvalidKeyException 
SignatureException 
NoSuchAlgorithmException 
IOException 
InvalidAlgorithmParameterException 
int org.ccnx.ccn.impl.CCNSegmenter.getBlockIncrement (  ) 

Gets the increment between block numbers.

Returns:
static CCNSegmenter org.ccnx.ccn.impl.CCNSegmenter.getBlockSegmenter ( int  blockSize,
CCNFlowControl  flowControl 
) [static]

Factory method to create a standard segmenter that generates blocks of fixed length in bytes.

Parameters:
blockSize number of bytes to put in each block (the last block will have an odd number of bytes)
flowControl the flow controller to use
Returns:
the new segmenter
int org.ccnx.ccn.impl.CCNSegmenter.getBlockSize (  ) 

Gets the current block size.

Returns:
block size in bytes
static CCNSegmenter org.ccnx.ccn.impl.CCNSegmenter.getByteCountSegmenter ( CCNFlowControl  flowControl  )  [static]

Factory method to create a standard segmenter that generates blocks of variable length in bytes, whose segment numbers are scaled by a fixed increment.

This could be used, for example to generate segments that had variable number of bytes in each, and naming them by byte offset. NOTE: This is used by CCNBlockInputStream and CCNBlockOutputStream; the other stream classes will not read data generated this way.

Parameters:
flowControl the flow controller to use
Returns:
the new segmenter
ContentObject org.ccnx.ccn.impl.CCNSegmenter.getFirstSegment (  ) 

Return the first segment.

Returns:
The first segment or null if no segments generated yet
static CCNSegmenter org.ccnx.ccn.impl.CCNSegmenter.getScaledByteCountSegmenter ( int  scale,
CCNFlowControl  flowControl 
) [static]

Factory method to create a standard segmenter that generates blocks of variable length in bytes, whose segment numbers are scaled by a fixed increment.

This could be used, for example to generate segments that had variable number of bytes in each, and naming them by scaling the byte offset by a scale useful to the application - e.g. to end up with millisecond offsets for a video or audio stream, etc. NOTE: the reader infrastructure currently expects incrementing segment numbers; a special stream class is necessary to read data generated this way. That would not be difficult to write.

Parameters:
scale multiplier to apply to the byte count before recording it as a sequence number
flowControl the flow controller to use
Returns:
the new segmenter
Long org.ccnx.ccn.impl.CCNSegmenter.lastSegmentIndex ( long  currentSegmentNumber,
long  bytesIntervening,
int  blocksRemaining 
)

Compute the index of the last block of a set of segments, according to the numbering profile.

Parameters:
currentSegmentNumber 
bytesIntervening 
blocksRemaining 
Returns:
long org.ccnx.ccn.impl.CCNSegmenter.newBlock ( ContentName  rootName,
long  segmentNumber,
SignedInfo  signedInfo,
byte  contentBlock[],
int  offset,
int  blockLength,
ContentKeys  keys 
) throws InvalidKeyException, InvalidAlgorithmParameterException, ContentEncodingException [protected]

Create a ContentObject, encrypt it if requested, and add it to the list of ContentObjects awaiting signing and output to the flow controller.

Also creates the segmented name for the CO.

Parameters:
rootName 
segmentNumber 
signedInfo 
contentBlock 
offset 
blockLength 
keys 
Returns:
next segment number to use
Exceptions:
InvalidKeyException 
InvalidAlgorithmParameterException 
ContentEncodingException 
long org.ccnx.ccn.impl.CCNSegmenter.nextSegmentIndex ( long  lastSegmentNumber,
long  lastSegmentLength 
)

Increment segment number according to the numbering profile in force.

Parameters:
lastSegmentNumber the last segment number we emitted
lastSegmentLength the length of the last segment we emitted
Returns:
void org.ccnx.ccn.impl.CCNSegmenter.outputCurrentBlocks ( PrivateKey  signingKey  )  throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException [protected]

Sign and output all outstanding blocks to the flow controller.

This is done when the number of blocks reaches HOLD_COUNT (see above) or we are doing a final flush of a file.

There are 2 cases: 1) we're flushing a single block and can put it out with a straight signature (includes 0-length file case) 2) we're flushing more than one block, and need to use a bulk signer.

All code is capable of handling any mix of these types of blocks but internal mixing should not happen anymore unless we decide to add a higher level capability to allow an immediate flush all the way to the flow controller. Normally we would see groups of bulk signatures followed by a straight signature block in rare cases where only a single block is left over for the flush after a bulk signing pass.

Parameters:
signingKey 
finalFlush sign and dump everything if true
Exceptions:
InvalidKeyException 
SignatureException 
NoSuchAlgorithmException 
IOException 
long org.ccnx.ccn.impl.CCNSegmenter.outputLength ( int  inputLength,
ContentKeys  keys 
)

How many content bytes will it take to represent content of length length, including any padding incurred by encryption?

Parameters:
inputLength 
Returns:
the output length
long org.ccnx.ccn.impl.CCNSegmenter.put ( ContentName  name,
byte[]  content,
int  offset,
int  length,
boolean  lastSegments,
SignedInfo.ContentType  type,
Integer  freshnessSeconds,
KeyLocator  locator,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys 
) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException

Puts a complete data item, segmenting it if necessary.

The assumption of this method is that this single call puts all the blocks of the item; if multiple calls to the segmenter will be required to output an item, use other methods to manage segment identifiers.

If the data is small enough this doesn't fragment. Otherwise, does. If multi-fragment, uses the naming profile and specified bulk signer (default: Merkle Hash Tree) to generate names and signatures.

Parameters:
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
Returns:
ContentObject of the data that was put (in the case of fragmented data, the first fragment is returned). This way the caller can then easily link to the data if they need to, or put again with a different name.
Exceptions:
InvalidAlgorithmParameterException 
long org.ccnx.ccn.impl.CCNSegmenter.putFragment ( ContentName  name,
long  segmentNumber,
byte[]  content,
int  offset,
int  length,
ContentType  type,
CCNTime  timestamp,
Integer  freshnessSeconds,
Long  finalSegmentIndex,
KeyLocator  locator,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys 
) throws InvalidKeyException, SignatureException, NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException

Puts a single block of content of arbitrary length using a segment naming convention.

The only current use of this is to allow a Segmenter.put of less than a blocksize. I'm not quite sure why that needs to use this and it would be nice to get rid of this since its mostly superfluous and duplicating other code at this point but for now I'll leave it in.

Parameters:
name name prefix to use for the object, without the segment number
segmentNumber the segment number to use for this object
content content buffer containing content to put
offset offset into buffer at which to start reading content to put
length number of bytes of buffer to put
type the type for the content
timestamp the timestamp for the content
freshnessSeconds the number of seconds this content should be considered fresh, or null to leave unset
finalSegmentIndex the expected segment number of the last segment of this stream, null to omit, Long(-1) to set as the last segment of this put, whatever its number turns out to be
locator the key locator to use
publisher the publisher to use
keys the keys to use for encrypting this segment, or null if unencrypted. The specific Key/IV used for this segment will be obtained by calling keys.getSegmentEncryptionCipher().
Returns:
returns the segment identifier for the next segment to be written, if any. If the caller doesn't want to override this, they can hand this number back to a subsequent call to fragmentedPut.
Exceptions:
InvalidKeyException 
SignatureException 
NoSuchAlgorithmException 
IOException 
InvalidAlgorithmParameterException 
void org.ccnx.ccn.impl.CCNSegmenter.setBlockIncrement ( int  blockIncrement  ) 

Sets the increment between block numbers.

Parameters:
blockIncrement 
void org.ccnx.ccn.impl.CCNSegmenter.setBlockSize ( int  blockSize  ) 

Sets the segmentation block size to use.

Parameters:
blockSize block size in bytes
void org.ccnx.ccn.impl.CCNSegmenter.setTimeout ( int  timeout  ) 

Set the timeout on the contained flow controller.

Parameters:
timeout 

Member Data Documentation

Handle multi-block amortized signing.

If null, default to single-block signing.


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