Private box reader

A private box reader lists an actor's private box, opens and verifies each envelope, and passes each entry to a delegate for further processing. The root object is supposed to contain a record.

Instance creation

PrivateBoxReader privateBoxReader = new PrivateBoxReader(keyPair, store, delegate);

var privateBoxReader = new cds.PrivateBoxReader(keyPair, store, delegate);

my $privateBoxReader = CDS::PrivateBoxReader->new($keyPair, $store, $delegate);

Creates a private box reader for the provided key pair and store.

Reading the private box

privateBoxReader.read();

privateBoxReader.read();

my $error = $privateBoxReader->read;

Starts reading the private box, unless a read operation is ongoing already.

A read operation first lists the private box. If listing fails, the store error is reported to the delegate, and the read operation stops immediately.

The reader then processes each message. Up to approximately 4 messages are processed in parallel.

1. The envelope is retrieved from the store, and parsed.
2. The signature is verified.
3. The AES key is decrypted using the key pair.
4. The content is retrieved from the store, parsed, and passed to the delegate.

If any of these steps fails, the entry is passed to the delegate as invalid, and processing stops. Invalid entries are remembered for 24 hours, and not reported again during this time.

If a store error occurs, processing stops immediately, and the error is returned. If the operation succeeds, the function returns undef.

boolean isReading = privateBoxReader.isReading();

var isReading = privateBoxReader.isReading();

Implementing a delegate

		@Override
		public void onPrivateBoxEntry(Source source, Record envelope, Reference contentReference, Record content) {
			// An valid entry was found.
		}

		@Override
		public void onPrivateBoxInvalidEntry(Source source, String reason) {
			// An invalid entry was found.
		}

		@Override
		public void onPrivateBoxStoreError(String error) {
			// An object could not be retrieved from the store.
		}

		@Override
		public void onPrivateBoxReadingDone() {
			// All entries have been read.
		}
	

Handling invalid entries

Entries on the private box are written by the application itself, and should therefore always be valid. Invalid entries could point to serious issues with the store (e.g. lost objects), or malicious attempts to modify the private data (e.g. wrong signatures).

In general, invalid entries require human investigation to figure out what happened. Where this is not possible, it is best to delete these entries, and synchronize the latest state from another actor of the group.