Condensation object

A Condensation object. Header and data are immutable byte sequences. The header includes the number of hashes (4 bytes), and the hashes (32 bytes each).

Instance creation

CondensationObject object = CondensationObject.from(bytes);

var object = cds.objectFromBytes(bytes);

my $object = CDS::Object->fromBytes($bytes);

Parses the bytes, and returns an instance. If the bytes do not contain a valid Condensation object, nullundef is returned.

Note that the bytes are not copied. If you reuse the byte array, clone it.

CondensationObject object = CondensationObject.create(headerBytes, dataBytes);

var object = cds.createObject(headerBytes, dataBytes);

my $object = CDS::Object->create($headerBytes, $dataBytes);

Parses the header bytes, and returns an instance. If the header is not valid, nullundef is returned.

Note that header and data bytes are not copied. If you reuse the byte arrays, clone them.

Accessing the hash list

Hash hash = object.hashAtIndex(i);

var hash = object.hashAtIndex(i);

my $hash = $object->hashAtIndex($i);

Returns the hash at index i in the object's header.

Hash[] hashes = object.hashes();

var hashes = object.hashes();

my @hashes = $object->hashes;

Returns the list of hashes referenced in the object's header.

Calculating the object hash

Hash hash = object.calculateHash();

var hash = object.calculateHash();

my $hash = $object->calculateHash;

Calculates the SHA-256 hash the object.

Note that hash calculation is a relatively time-intensive operation. Hence, hashes should only be calculated when necessary.

Hash hash = new CalculateHash(object, done);

			var done = object.calculateHashAsynchronously(object);
			done.onDone = function(hash) { ... };

Asynchronously calculates the SHA-256, and calls done.onCalculateHashDone(hash)done.onDone(hash) when done. This is particularly useful for large objects.

Encryption and decryption

CondensationObject encryptedObject = object.crypt(key);

var encryptedObject = object.crypt(key);

my $encryptedObject = $object->crypt(key);

Encrypts or decrypts the object with the given key.

In-place encryption and decryption

If an object and its data are fully owned, it may be encrypted or decrypted in-place. In-place en- or decryption is slightly more efficient, since no additional memory is allocated.

In-place encryption is sometimes used during object creation. Objects retrieved from a store must never be modified in-place, however. They remain owned by the store.

Bytes key = object.encryptInPlace();

var key = object.encryptInPlace();

Generates a random key, encrypts the object in-place, and returns the key.

object.cryptInPlace(key);

object.cryptInPlace(key);

Encrypts or decrypts an object in-place with the provided key.

Cloning

Bytes bytes = object.bytes();

var bytes = object.bytes();

my $bytes = $object->bytes;

Returns a copy of the bytes of this object. To avoid copying, consider accessing the header and data directly.

CondensationObject clonedObject = object.clone();

var clonedObject = object.clone();

my $clonedObject = $object->clone;

Returns a clone with copies of header and data.

Examples

Serializing and encrypting a record

		CondensationObject object = record.toObject();
		Bytes key = object.encryptInPlace();
		Hash hash = object.calculateHash();
		Reference reference = new Reference(hash, key);

		var object = record.toObject();
		var key = object.encryptInPlace();
		var hash = object.calculateHash();
		var reference = new cds.Reference(hash, key);

		my $key = CDS->randomKey;
		my $object = $record->toObject()->crypt($key);
		my $hash = $object->calculateHash;
		my $reference = CDS::Reference->new($hash, $key);

Since record serialization always allocates new memory, the resulting object is fully owned, and can therefore be encrypted in-place on platforms that allow this.

Creating an encrypted object from arbitrary data

		Bytes data = ...
		Bytes key = Condensation.randomKey();
		CondensationObject object = CondensationObject.create(CondensationObject.emptyHeader, data).crypt(key);
		Hash hash = object.calculateHash();
		Reference reference = new Reference(hash, key);

		var data = ...	// Uint8Array
		var key = cds.randomKey();
		var object = cds.createObject(cds.emptyHeader, data).crypt(key);
		var hash = object.calculateHash();
		var reference = new cds.Reference(hash, key);

		my $data = ...
		my $key = CDS->randomKey;
		my $object = CDS::Object->create(CDS::Object->emptyHeader, $data)->crypt($key);
		my $hash = $object->calculateHash;
		my $reference = CDS::Reference->new($hash, $key);

Creating an encrypted object from owned data

			Bytes data = ...
			CondensationObject object = CondensationObject.create(CondensationObject.emptyHeader, data);
			Bytes key = object.encryptInPlace();
			Hash hash = object.calculateHash();
			Reference reference = new Reference(hash, key);

			var data = ...	// Uint8Array
			var object = cds.createObject(cds.emptyHeader, data);
			var key = object.encryptInPlace();
			var hash = object.calculateHash();
			var reference = new cds.Reference(hash, key);

Note that data will be modified by encryptInPlace.