ch.epfl.dedis.calypso

Class Document

java.lang.Object

ch.epfl.dedis.calypso.Document

public class Document
extends Object

A document is an example how to use Calypso to store a document securely on Byzcoin. The document class always holds the data unencrypted, but encrypts - the data using the keyMaterial - the keyMaterial using the public key of the Long Term Secrets

It can return the document if it is given a ReadInstance and the private key to decrypt the keyMaterial.

Constructor Summary

Constructors

Constructor and Description
Document(byte[] data, byte[] keyMaterial, byte[] extraData, DarcId publisherId) Initialises a document.
Document(byte[] data, byte[] extraData, DarcId publisherId) Creates a new document from data, creates a new Darc, a symmetric symmetricKey and encrypts the data using AES-GCM.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object other) Compares this document with another document.
static Document	fromCalypso(CalypsoRPC calypso, InstanceId riId, Scalar reader) Fetches a document from calypso, once the read instance has been created.
static Document	fromWriteInstance(WriteInstance wi, byte[] keyMaterial) Recreate the document once all the material already is fetched from ByzCoin.
byte[]	getData()
byte[]	getExtraData()
byte[]	getKeyMaterial()
DarcId	getPublisherId()
WriteData	getWriteData(CreateLTSReply lts) Creates a WriteData object with the fields of the document.
WriteInstance	spawnWrite(CalypsoRPC calypso, DarcId publisherDarcId, Signer publisherSigner, Long signerCtr) Creates a new WriteInstance with the document stored in it.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Document

public Document(byte[] data,
                byte[] keyMaterial,
                byte[] extraData,
                DarcId publisherId)

Initialises a document. The data already has to be encrypted.

Parameters:

data - the data that will be encrypted using the keyMaterial

keyMaterial - key-material necessary for the unencryption of the document. This will be encrypted before the transmission to the skipchain.

extraData - any public data that will be stored unencrypted on the skipchain.

publisherId - the publisher darc with the rules to create a WriteInstance and a ReadInstance.

Document

public Document(byte[] data,
                byte[] extraData,
                DarcId publisherId)

Creates a new document from data, creates a new Darc, a symmetric symmetricKey and encrypts the data using AES-GCM.

Parameters:

data - any data that will be stored encrypted on the skipchain. There is a limit on how much data can be stored. The limit depends on the block size configuration in ByzCoin. It is slightly below the block size because metadata is also stored in the block. You can find the block size using ChainConfigInstance. If you need more, this must be a pointer to an off-chain storage.

extraData - any public data that will not be encrypted

publisherId - the publisher darc with the rules to create a WriteInstance and a ReadInstance.

Method Detail

getWriteData

public WriteData getWriteData(CreateLTSReply lts)
                       throws CothorityException

Creates a WriteData object with the fields of the document.

Parameters:

lts - the Long Term Secret to use.

Returns:

a WriteData with the encrypted data

Throws:

CothorityException - if something goes wrong

spawnWrite

public WriteInstance spawnWrite(CalypsoRPC calypso,
                                DarcId publisherDarcId,
                                Signer publisherSigner,
                                Long signerCtr)
                         throws CothorityException

Creates a new WriteInstance with the document stored in it.

Parameters:

calypso - an instance of the calypsoRPC

publisherDarcId - a darc with a 'spawn:calypsoWrite' rule

publisherSigner - a signer having the right to trigger the 'spawn:calypsoWrite' rule.

signerCtr - a monotonically increasing counter for publisherSigner

Returns:

a WriteInstance

Throws:

CothorityException - if something goes wrong

equals

public boolean equals(Object other)

Compares this document with another document. If this document has a writeRequestId, it will be compared against the other document's writeRequestId, else it will be ignored.

Overrides:

equals in class Object

Parameters:

other - another Document

Returns:

true if both are equal

getKeyMaterial

public byte[] getKeyMaterial()

Returns:

the key material used to encrypt the data

getExtraData

public byte[] getExtraData()

Returns:

the public data that is stored in cleartext on ByzCoin

getPublisherId

public DarcId getPublisherId()

Returns:

the Darc base ID protecting access to this document.

getData

public byte[] getData()

Returns:

the decrypted data stored in this document.

toString

public String toString()

Overrides:

toString in class Object

Returns:

a nicely formatted string representing the document.

fromCalypso

public static Document fromCalypso(CalypsoRPC calypso,
                                   InstanceId riId,
                                   Scalar reader)
                            throws CothorityException

Fetches a document from calypso, once the read instance has been created. It fetches the ReadInstance, WriteInstance, and the reader darc from ByzCoin, and then re-creates a document with the decrypted keyMaterial and decrypted data.

Parameters:

calypso - an existing calypso

riId - the instance Id of the read instance

reader - the private key of the reader (or ephemeral key)

Returns:

the document with the decrypted keyMaterial and decrypted data

Throws:

CothorityException - if something goes wrong

fromWriteInstance

public static Document fromWriteInstance(WriteInstance wi,
                                         byte[] keyMaterial)
                                  throws CothorityNotFoundException,
                                         CothorityCryptoException

Recreate the document once all the material already is fetched from ByzCoin.

Parameters:

wi - WriteInstance for this document

keyMaterial - the decrypted key material

Returns:

a new Document with the decrypted data

Throws:

CothorityNotFoundException - if the requested instance cannot be found

CothorityCryptoException - if there's a problem with the cryptography