bramble-api/src/main/java/org/briarproject/bramble/api/crypto/PrivateKey.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+/**
+ * The private half of a public/private {@link KeyPair}.
+ */
+@NotNullByDefault
+public interface PrivateKey {
+
+	/**
+	 * Returns the type of this key pair.
+	 */
+	String getKeyType();
+
+	/**
+	 * Returns the encoded representation of this key.
+	 */
+	byte[] getEncoded();
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/PublicKey.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+/**
+ * The public half of a public/private {@link KeyPair}.
+ */
+@NotNullByDefault
+public interface PublicKey {
+
+	/**
+	 * Returns the type of this key pair.
+	 */
+	String getKeyType();
+
+	/**
+	 * Returns the encoded representation of this key.
+	 */
+	byte[] getEncoded();
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/SecretKey.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.Bytes;
+
+/**
+ * A secret key used for encryption and/or authentication.
+ */
+public class SecretKey extends Bytes {
+
+	/**
+	 * The length of a secret key in bytes.
+	 */
+	public static final int LENGTH = 32;
+
+	public SecretKey(byte[] key) {
+		super(key);
+		if (key.length != LENGTH) throw new IllegalArgumentException();
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/SignaturePrivateKey.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.Bytes;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import javax.annotation.concurrent.Immutable;
+
+import static org.briarproject.bramble.api.crypto.CryptoConstants.KEY_TYPE_SIGNATURE;
+
+/**
+ * Type-safe wrapper for a public key used for signing.
+ */
+@Immutable
+@NotNullByDefault
+public class SignaturePrivateKey extends Bytes implements PrivateKey {
+
+	public SignaturePrivateKey(byte[] bytes) {
+		super(bytes);
+	}
+
+	@Override
+	public String getKeyType() {
+		return KEY_TYPE_SIGNATURE;
+	}
+
+	@Override
+	public byte[] getEncoded() {
+		return getBytes();
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/SignaturePublicKey.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.Bytes;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import javax.annotation.concurrent.Immutable;
+
+import static org.briarproject.bramble.api.crypto.CryptoConstants.KEY_TYPE_SIGNATURE;
+import static org.briarproject.bramble.api.crypto.CryptoConstants.MAX_SIGNATURE_PUBLIC_KEY_BYTES;
+
+/**
+ * Type-safe wrapper for a public key used for verifying signatures.
+ */
+@Immutable
+@NotNullByDefault
+public class SignaturePublicKey extends Bytes implements PublicKey {
+
+	public SignaturePublicKey(byte[] encoded) {
+		super(encoded);
+		if (encoded.length == 0 ||
+				encoded.length > MAX_SIGNATURE_PUBLIC_KEY_BYTES) {
+			throw new IllegalArgumentException();
+		}
+	}
+
+	@Override
+	public String getKeyType() {
+		return KEY_TYPE_SIGNATURE;
+	}
+
+	@Override
+	public byte[] getEncoded() {
+		return getBytes();
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/StreamDecrypter.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.IOException;
+
+@NotNullByDefault
+public interface StreamDecrypter {
+
+	/**
+	 * Reads a frame, decrypts its payload into the given buffer and returns
+	 * the payload length, or -1 if no more frames can be read from the stream.
+	 *
+	 * @throws IOException if an error occurs while reading the frame,
+	 * or if authenticated decryption fails.
+	 */
+	int readFrame(byte[] payload) throws IOException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/StreamDecrypterFactory.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.transport.StreamContext;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.InputStream;
+
+@NotNullByDefault
+public interface StreamDecrypterFactory {
+
+	/**
+	 * Creates a {@link StreamDecrypter} for decrypting a transport stream.
+	 */
+	StreamDecrypter createStreamDecrypter(InputStream in, StreamContext ctx);
+
+	/**
+	 * Creates a {@link StreamDecrypter} for decrypting a contact exchange
+	 * stream.
+	 */
+	StreamDecrypter createContactExchangeStreamDecrypter(InputStream in,
+			SecretKey headerKey);
+
+	/**
+	 * Creates a {@link StreamDecrypter} for decrypting a log stream.
+	 */
+	StreamDecrypter createLogStreamDecrypter(InputStream in,
+			SecretKey headerKey);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/StreamEncrypter.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.IOException;
+
+@NotNullByDefault
+public interface StreamEncrypter {
+
+	/**
+	 * Encrypts the given frame and writes it to the stream.
+	 */
+	void writeFrame(byte[] payload, int payloadLength, int paddingLength,
+			boolean finalFrame) throws IOException;
+
+	/**
+	 * Flushes the stream.
+	 */
+	void flush() throws IOException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/StreamEncrypterFactory.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.transport.StreamContext;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.OutputStream;
+
+@NotNullByDefault
+public interface StreamEncrypterFactory {
+
+	/**
+	 * Creates a {@link StreamEncrypter} for encrypting a transport stream.
+	 */
+	StreamEncrypter createStreamEncrypter(OutputStream out, StreamContext ctx);
+
+	/**
+	 * Creates a {@link StreamEncrypter} for encrypting a contact exchange
+	 * stream.
+	 */
+	StreamEncrypter createContactExchangeStreamEncrypter(OutputStream out,
+			SecretKey headerKey);
+
+	/**
+	 * Creates a {@link StreamEncrypter} for encrypting a log stream.
+	 */
+	StreamEncrypter createLogStreamEncrypter(OutputStream out,
+			SecretKey headerKey);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/crypto/TransportCrypto.java

+package org.briarproject.bramble.api.crypto;
+
+import org.briarproject.bramble.api.plugin.TransportId;
+import org.briarproject.bramble.api.transport.TransportKeys;
+
+import java.security.GeneralSecurityException;
+
+/**
+ * Crypto operations for the transport security protocol - see
+ * https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BTP.md
+ */
+public interface TransportCrypto {
+
+	/**
+	 * Returns true if the local peer is Alice.
+	 */
+	boolean isAlice(PublicKey theirHandshakePublicKey,
+			KeyPair ourHandshakeKeyPair);
+
+	/**
+	 * Derives the static master key shared with a contact or pending contact.
+	 */
+	SecretKey deriveStaticMasterKey(PublicKey theirHandshakePublicKey,
+			KeyPair ourHandshakeKeyPair) throws GeneralSecurityException;
+
+	/**
+	 * Derives the handshake mode root key from the static master key. To
+	 * prevent tag reuse, separate root keys are derived for contacts and
+	 * pending contacts.
+	 *
+	 * @param pendingContact Whether the static master key is shared with a
+	 * pending contact or a contact
+	 */
+	SecretKey deriveHandshakeRootKey(SecretKey staticMasterKey,
+			boolean pendingContact);
+
+	/**
+	 * Derives initial rotation mode transport keys for the given transport in
+	 * the given time period from the given root key.
+	 *
+	 * @param alice Whether the keys are for use by Alice or Bob
+	 * @param active Whether the keys are usable for outgoing streams
+	 */
+	TransportKeys deriveRotationKeys(TransportId t, SecretKey rootKey,
+			long timePeriod, boolean alice, boolean active);
+
+	/**
+	 * Derives handshake keys for the given transport in the given time period
+	 * from the given root key.
+	 *
+	 * @param alice Whether the keys are for use by Alice or Bob
+	 */
+	TransportKeys deriveHandshakeKeys(TransportId t, SecretKey rootKey,
+			long timePeriod, boolean alice);
+
+	/**
+	 * Updates the given transport keys to the given time period. If the keys
+	 * are for the given period or any later period they are not updated.
+	 */
+	TransportKeys updateTransportKeys(TransportKeys k, long timePeriod);
+
+	/**
+	 * Encodes the pseudo-random tag that is used to recognise a stream.
+	 */
+	void encodeTag(byte[] tag, SecretKey tagKey, int protocolVersion,
+			long streamNumber);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfDictionary.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.Bytes;
+import org.briarproject.bramble.api.FormatException;
+
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.TreeMap;
+
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.NotThreadSafe;
+
+/**
+ * A BDF dictionary contains zero or more key-value pairs, where the keys
+ * are strings and the values are BDF objects, which may be primitive types
+ * (null, boolean, integer, float, string, raw) or nested containers (list,
+ * dictionary).
+ * <p>
+ * Note that a BDF integer has the same range as a Java long, while a BDF
+ * float has the same range as a Java double. Method names in this class
+ * correspond to the Java types.
+ * <p>
+ * The getX() methods throw {@link FormatException} if the specified key is
+ * absent, the value is null, or the value does not have the requested type.
+ * <p>
+ * The getOptionalX() methods return null if the specified key is absent or
+ * the value is null, or throw {@link FormatException} if the value does not
+ * have the requested type.
+ * <p>
+ * The getX() methods that take a default value return the default value if
+ * the specified key is absent or the value is null, or throw
+ * {@link FormatException} if the value does not have the requested type.
+ */
+@NotThreadSafe
+public final class BdfDictionary extends TreeMap<String, Object> {
+
+	public static final Object NULL_VALUE = new Object();
+
+	/**
+	 * Factory method for constructing dictionaries inline.
+	 * <pre>
+	 * BdfDictionary.of(
+	 *     new BdfEntry("foo", foo),
+	 *     new BdfEntry("bar", bar)
+	 * );
+	 * </pre>
+	 */
+	public static BdfDictionary of(Entry<String, ?>... entries) {
+		BdfDictionary d = new BdfDictionary();
+		for (Entry<String, ?> e : entries) d.put(e.getKey(), e.getValue());
+		return d;
+	}
+
+	public BdfDictionary() {
+		super();
+	}
+
+	public BdfDictionary(Map<String, ?> m) {
+		super(m);
+	}
+
+	public Boolean getBoolean(String key) throws FormatException {
+		Boolean value = getOptionalBoolean(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Boolean getOptionalBoolean(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Boolean) return (Boolean) o;
+		throw new FormatException();
+	}
+
+	public Boolean getBoolean(String key, Boolean defaultValue)
+			throws FormatException {
+		Boolean value = getOptionalBoolean(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public Long getLong(String key) throws FormatException {
+		Long value = getOptionalLong(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Long getOptionalLong(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Long) return (Long) o;
+		if (o instanceof Integer) return ((Integer) o).longValue();
+		if (o instanceof Short) return ((Short) o).longValue();
+		if (o instanceof Byte) return ((Byte) o).longValue();
+		throw new FormatException();
+	}
+
+	public Long getLong(String key, Long defaultValue) throws FormatException {
+		Long value = getOptionalLong(key);
+		return value == null ? defaultValue : value;
+	}
+
+	/**
+	 * Returns the integer with the specified key.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getLong(key).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if there is no value at the specified key,
+	 * or if the value is null or cannot be represented as a Java int.
+	 */
+	public Integer getInt(String key) throws FormatException {
+		Integer value = getOptionalInt(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	/**
+	 * Returns the integer with the specified key, or null if the key is
+	 * absent or the value is null.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getOptionalLong(key).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if the value at the specified key is not null
+	 * and cannot be represented as a Java int.
+	 */
+	@Nullable
+	public Integer getOptionalInt(String key) throws FormatException {
+		Long value = getOptionalLong(key);
+		if (value == null) return null;
+		if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) {
+			throw new FormatException();
+		}
+		return value.intValue();
+	}
+
+	/**
+	 * Returns the integer with the specified key, or the given default
+	 * value if the key is absent or the value is null.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getLong(key, defaultValue).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if the value at the specified key is not null
+	 * and cannot be represented as a Java int.
+	 */
+	public Integer getInt(String key, Integer defaultValue)
+			throws FormatException {
+		Integer value = getOptionalInt(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public Double getDouble(String key) throws FormatException {
+		Double value = getOptionalDouble(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Double getOptionalDouble(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Double) return (Double) o;
+		if (o instanceof Float) return ((Float) o).doubleValue();
+		throw new FormatException();
+	}
+
+	public Double getDouble(String key, Double defaultValue)
+			throws FormatException {
+		Double value = getOptionalDouble(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public String getString(String key) throws FormatException {
+		String value = getOptionalString(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public String getOptionalString(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof String) return (String) o;
+		throw new FormatException();
+	}
+
+	public String getString(String key, String defaultValue)
+			throws FormatException {
+		String value = getOptionalString(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public byte[] getRaw(String key) throws FormatException {
+		byte[] value = getOptionalRaw(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public byte[] getOptionalRaw(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof byte[]) return (byte[]) o;
+		if (o instanceof Bytes) return ((Bytes) o).getBytes();
+		throw new FormatException();
+	}
+
+	public byte[] getRaw(String key, byte[] defaultValue)
+			throws FormatException {
+		byte[] value = getOptionalRaw(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public BdfList getList(String key) throws FormatException {
+		BdfList value = getOptionalList(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public BdfList getOptionalList(String key) throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof BdfList) return (BdfList) o;
+		throw new FormatException();
+	}
+
+	public BdfList getList(String key, BdfList defaultValue)
+			throws FormatException {
+		BdfList value = getOptionalList(key);
+		return value == null ? defaultValue : value;
+	}
+
+	public BdfDictionary getDictionary(String key) throws FormatException {
+		BdfDictionary value = getOptionalDictionary(key);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public BdfDictionary getOptionalDictionary(String key)
+			throws FormatException {
+		Object o = get(key);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof BdfDictionary) return (BdfDictionary) o;
+		throw new FormatException();
+	}
+
+	public BdfDictionary getDictionary(String key, BdfDictionary defaultValue)
+			throws FormatException {
+		BdfDictionary value = getOptionalDictionary(key);
+		return value == null ? defaultValue : value;
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfEntry.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.util.Map.Entry;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A convenience class for building {@link BdfDictionary BdfDictionaries}
+ * via the {@link BdfDictionary#of(Entry[]) factory method}. Entries in
+ * BdfDictionaries do not have to be BdfEntries.
+ */
+@Immutable
+@NotNullByDefault
+public class BdfEntry implements Entry<String, Object>, Comparable<BdfEntry> {
+
+	private final String key;
+	private final Object value;
+
+	public BdfEntry(String key, Object value) {
+		this.key = key;
+		this.value = value;
+	}
+
+	@Override
+	public String getKey() {
+		return key;
+	}
+
+	@Override
+	public Object getValue() {
+		return value;
+	}
+
+	@Override
+	public Object setValue(Object value) {
+		throw new UnsupportedOperationException();
+	}
+
+	@Override
+	public int compareTo(BdfEntry e) {
+		if (e == this) return 0;
+		return key.compareTo(e.key);
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfList.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.Bytes;
+import org.briarproject.bramble.api.FormatException;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.NotThreadSafe;
+
+import static org.briarproject.bramble.api.data.BdfDictionary.NULL_VALUE;
+
+/**
+ * A BDF list contains zero or more BDF objects, which may be primitive types
+ * (null, boolean, integer, float, string, raw) or nested containers (list,
+ * dictionary).
+ * <p>
+ * Note that a BDF integer has the same range as a Java long, while a BDF
+ * float has the same range as a Java double. Method names in this class
+ * correspond to the Java types.
+ * <p>
+ * The getX() methods throw {@link FormatException} if the object at the
+ * specified index is null or does not have the requested type.
+ * <p>
+ * The getOptionalX() methods return null if the object at the specified
+ * index is null, or throw {@link FormatException} if the object does not
+ * have the requested type.
+ * <p>
+ * The getX() methods that take a default value return the default value if
+ * the object at the specified index is null, or throw
+ * {@link FormatException} if the object does not have the requested type.
+ * <p>
+ * All of the getters throw {@link FormatException} if the specified index is
+ * out of range.
+ */
+@NotThreadSafe
+public final class BdfList extends ArrayList<Object> {
+
+	/**
+	 * Factory method for constructing lists inline.
+	 * <pre>
+	 * BdfList.of(1, 2, 3);
+	 * </pre>
+	 */
+	public static BdfList of(Object... items) {
+		return new BdfList(Arrays.asList(items));
+	}
+
+	public BdfList() {
+		super();
+	}
+
+	public BdfList(List<Object> items) {
+		super(items);
+	}
+
+	@SuppressWarnings("BooleanMethodIsAlwaysInverted")
+	private boolean isInRange(int index) {
+		return index >= 0 && index < size();
+	}
+
+	public Boolean getBoolean(int index) throws FormatException {
+		Boolean value = getOptionalBoolean(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Boolean getOptionalBoolean(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Boolean) return (Boolean) o;
+		throw new FormatException();
+	}
+
+	public Boolean getBoolean(int index, Boolean defaultValue)
+			throws FormatException {
+		Boolean value = getOptionalBoolean(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public Long getLong(int index) throws FormatException {
+		Long value = getOptionalLong(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Long getOptionalLong(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Long) return (Long) o;
+		if (o instanceof Integer) return ((Integer) o).longValue();
+		if (o instanceof Short) return ((Short) o).longValue();
+		if (o instanceof Byte) return ((Byte) o).longValue();
+		throw new FormatException();
+	}
+
+	public Long getLong(int index, Long defaultValue) throws FormatException {
+		Long value = getOptionalLong(index);
+		return value == null ? defaultValue : value;
+	}
+
+	/**
+	 * Returns the integer at the specified index.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getLong(index).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if the index is out of range, or if the
+	 * value at the specified index is null or cannot be represented as a
+	 * Java int.
+	 */
+	public Integer getInt(int index) throws FormatException {
+		Integer value = getOptionalInt(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	/**
+	 * Returns the integer at the specified index, or null if the object at
+	 * the specified index is null.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getOptionalLong(index).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if the index is out of range, or if the value
+	 * at the specified index cannot be represented as a Java int.
+	 */
+	@Nullable
+	public Integer getOptionalInt(int index) throws FormatException {
+		Long value = getOptionalLong(index);
+		if (value == null) return null;
+		if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) {
+			throw new FormatException();
+		}
+		return value.intValue();
+	}
+
+	/**
+	 * Returns the integer at the specified index, or the given default value
+	 * if the object at the specified index is null.
+	 * <p>
+	 * This method should be used in preference to
+	 * <code>getLong(index, defaultValue).intValue()</code> as it checks for
+	 * overflow/underflow.
+	 *
+	 * @throws FormatException if the index is out of range, or if the value
+	 * at the specified index cannot be represented as a Java int.
+	 */
+	public Integer getInt(int index, Integer defaultValue)
+			throws FormatException {
+		Integer value = getOptionalInt(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public Double getDouble(int index) throws FormatException {
+		Double value = getOptionalDouble(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public Double getOptionalDouble(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof Double) return (Double) o;
+		if (o instanceof Float) return ((Float) o).doubleValue();
+		throw new FormatException();
+	}
+
+	public Double getDouble(int index, Double defaultValue)
+			throws FormatException {
+		Double value = getOptionalDouble(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public String getString(int index) throws FormatException {
+		String value = getOptionalString(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public String getOptionalString(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof String) return (String) o;
+		throw new FormatException();
+	}
+
+	public String getString(int index, String defaultValue)
+			throws FormatException {
+		String value = getOptionalString(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public byte[] getRaw(int index) throws FormatException {
+		byte[] value = getOptionalRaw(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public byte[] getOptionalRaw(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof byte[]) return (byte[]) o;
+		if (o instanceof Bytes) return ((Bytes) o).getBytes();
+		throw new FormatException();
+	}
+
+	public byte[] getRaw(int index, byte[] defaultValue)
+			throws FormatException {
+		byte[] value = getOptionalRaw(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public BdfList getList(int index) throws FormatException {
+		BdfList value = getOptionalList(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public BdfList getOptionalList(int index) throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof BdfList) return (BdfList) o;
+		throw new FormatException();
+	}
+
+	public BdfList getList(int index, BdfList defaultValue)
+			throws FormatException {
+		BdfList value = getOptionalList(index);
+		return value == null ? defaultValue : value;
+	}
+
+	public BdfDictionary getDictionary(int index) throws FormatException {
+		BdfDictionary value = getOptionalDictionary(index);
+		if (value == null) throw new FormatException();
+		return value;
+	}
+
+	@Nullable
+	public BdfDictionary getOptionalDictionary(int index)
+			throws FormatException {
+		if (!isInRange(index)) throw new FormatException();
+		Object o = get(index);
+		if (o == null || o == NULL_VALUE) return null;
+		if (o instanceof BdfDictionary) return (BdfDictionary) o;
+		throw new FormatException();
+	}
+
+	public BdfDictionary getDictionary(int index, BdfDictionary defaultValue)
+			throws FormatException {
+		BdfDictionary value = getOptionalDictionary(index);
+		return value == null ? defaultValue : value;
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfReader.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.IOException;
+
+/**
+ * An interface for reading BDF objects from an input stream.
+ * <p>
+ * The readX() methods throw {@link FormatException} if the data is not in
+ * canonical form, but the hasX() and skipX() methods do not check for
+ * canonical form.
+ */
+@NotNullByDefault
+public interface BdfReader {
+
+	int DEFAULT_NESTED_LIMIT = 5;
+	int DEFAULT_MAX_BUFFER_SIZE = 64 * 1024;
+
+	/**
+	 * Returns true if the reader has reached the end of its input stream.
+	 */
+	boolean eof() throws IOException;
+
+	/**
+	 * Closes the reader's input stream.
+	 */
+	void close() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF null.
+	 */
+	boolean hasNull() throws IOException;
+
+	/**
+	 * Reads a BDF null from the input.
+	 */
+	void readNull() throws IOException;
+
+	/**
+	 * Skips over a BDF null.
+	 */
+	void skipNull() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF boolean.
+	 */
+	boolean hasBoolean() throws IOException;
+
+	/**
+	 * Reads a BDF boolean from the input and returns it.
+	 */
+	boolean readBoolean() throws IOException;
+
+	/**
+	 * Skips over a BDF boolean.
+	 */
+	void skipBoolean() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF integer, which
+	 * has the same range as a Java long.
+	 */
+	boolean hasLong() throws IOException;
+
+	/**
+	 * Reads a BDF integer from the input and returns it as a Java long.
+	 */
+	long readLong() throws IOException;
+
+	/**
+	 * Skips over a BDF integer.
+	 */
+	void skipLong() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF integer and the
+	 * value would fit within the range of a Java int.
+	 */
+	boolean hasInt() throws IOException;
+
+	/**
+	 * Reads a BDF integer from the input and returns it as a Java int.
+	 *
+	 * @throws FormatException if the value exceeds the range of a Java int.
+	 */
+	int readInt() throws IOException;
+
+	/**
+	 * Skips over a BDF integer.
+	 *
+	 * @throws FormatException if the value exceeds the range of a Java int.
+	 */
+	void skipInt() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF float, which has
+	 * the same range as a Java double.
+	 */
+	boolean hasDouble() throws IOException;
+
+	/**
+	 * Reads a BDF float from the input and returns it as a Java double.
+	 */
+	double readDouble() throws IOException;
+
+	/**
+	 * Skips over a BDF float.
+	 */
+	void skipDouble() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF string.
+	 */
+	boolean hasString() throws IOException;
+
+	/**
+	 * Reads a BDF string from the input.
+	 *
+	 * @throws IOException If the string is not valid UTF-8.
+	 */
+	String readString() throws IOException;
+
+	/**
+	 * Skips over a BDF string without checking whether it is valid UTF-8.
+	 */
+	void skipString() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF raw.
+	 */
+	boolean hasRaw() throws IOException;
+
+	/**
+	 * Reads a BDF raw from the input and returns it as a byte array.
+	 */
+	byte[] readRaw() throws IOException;
+
+	/**
+	 * Skips over a BDF raw.
+	 */
+	void skipRaw() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF list.
+	 */
+	boolean hasList() throws IOException;
+
+	/**
+	 * Reads a BDF list from the input and returns it. The list's contents
+	 * are parsed and validated.
+	 */
+	BdfList readList() throws IOException;
+
+	/**
+	 * Skips over a BDF list. The list's contents are parsed (to determine
+	 * their length) but not validated.
+	 */
+	void skipList() throws IOException;
+
+	/**
+	 * Returns true if the next object in the input is a BDF dictionary.
+	 */
+	boolean hasDictionary() throws IOException;
+
+	/**
+	 * Reads a BDF dictionary from the input and returns it. The dictionary's
+	 * contents are parsed and validated.
+	 */
+	BdfDictionary readDictionary() throws IOException;
+
+	/**
+	 * Skips over a BDF dictionary. The dictionary's contents are parsed
+	 * (to determine their length) but not validated.
+	 */
+	void skipDictionary() throws IOException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfReaderFactory.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.InputStream;
+
+@NotNullByDefault
+public interface BdfReaderFactory {
+
+	BdfReader createReader(InputStream in);
+
+	/**
+	 * Transitional alternative to {@link #createReader(InputStream)} that
+	 * can create a reader that accepts non-canonical input, for backward
+	 * compatibility.
+	 */
+	@Deprecated
+	BdfReader createReader(InputStream in, boolean canonical);
+
+	BdfReader createReader(InputStream in, int nestedLimit,
+			int maxBufferSize, boolean canonical);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfStringUtils.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.Bytes;
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import javax.annotation.Nullable;
+
+import static org.briarproject.bramble.api.data.BdfDictionary.NULL_VALUE;
+import static org.briarproject.bramble.util.StringUtils.toHexString;
+
+@NotNullByDefault
+public class BdfStringUtils {
+
+	public static String toString(@Nullable Object o) throws FormatException {
+		return toString(o, 0);
+	}
+
+	private static String toString(@Nullable Object o, int indent)
+			throws FormatException {
+		if (o == null || o == NULL_VALUE) return "null";
+		if (o instanceof Boolean) return o.toString();
+		if (o instanceof Number) return o.toString();
+		if (o instanceof String) return "\"" + o + "\"";
+		if (o instanceof Bytes)
+			return "x" + toHexString(((Bytes) o).getBytes());
+		if (o instanceof byte[])
+			return "x" + toHexString((byte[]) o);
+		if (o instanceof List) {
+			List<?> list = (List) o;
+			StringBuilder sb = new StringBuilder();
+			sb.append("[\n");
+			int i = 0, size = list.size();
+			for (Object e : list) {
+				indent(sb, indent + 1);
+				sb.append(toString(e, indent + 1));
+				if (i++ < size - 1) sb.append(',');
+				sb.append('\n');
+			}
+			indent(sb, indent);
+			sb.append(']');
+			return sb.toString();
+		}
+		if (o instanceof Map) {
+			Map<?, ?> map = (Map) o;
+			StringBuilder sb = new StringBuilder();
+			sb.append("{\n");
+			int i = 0, size = map.size();
+			for (Entry e : map.entrySet()) {
+				indent(sb, indent + 1);
+				sb.append(toString(e.getKey(), indent + 1));
+				sb.append(": ");
+				sb.append(toString(e.getValue(), indent + 1));
+				if (i++ < size - 1) sb.append(',');
+				sb.append('\n');
+			}
+			indent(sb, indent);
+			sb.append('}');
+			return sb.toString();
+		}
+		throw new FormatException();
+	}
+
+	private static void indent(StringBuilder sb, int indent) {
+		for (int i = 0; i < indent; i++) sb.append('\t');
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfWriter.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.FormatException;
+
+import java.io.IOException;
+import java.util.Collection;
+import java.util.Map;
+
+/**
+ * An interface for writing BDF objects to an output stream. The BDF output
+ * is in canonical form, ie integers and length fields are represented using
+ * the minimum number of bytes and dictionary keys are unique and sorted in
+ * lexicographic order.
+ */
+public interface BdfWriter {
+
+	/**
+	 * Flushes the writer's output stream.
+	 */
+	void flush() throws IOException;
+
+	/**
+	 * Closes the writer's output stream.
+	 */
+	void close() throws IOException;
+
+	/**
+	 * Writes a BDF null to the output stream.
+	 */
+	void writeNull() throws IOException;
+
+	/**
+	 * Writes a BDF boolean to the output stream.
+	 */
+	void writeBoolean(boolean b) throws IOException;
+
+	/**
+	 * Writes a BDF integer (which has the same range as a Java long) to the
+	 * output stream.
+	 */
+	void writeLong(long l) throws IOException;
+
+	/**
+	 * Writes a BDF float (which has the same range as a Java double) to the
+	 * output stream.
+	 */
+	void writeDouble(double d) throws IOException;
+
+	/**
+	 * Writes a BDF string (which uses UTF-8 encoding) to the output stream.
+	 */
+	void writeString(String s) throws IOException;
+
+	/**
+	 * Writes a BDF raw to the output stream.
+	 */
+	void writeRaw(byte[] b) throws IOException;
+
+	/**
+	 * Writes a BDF list to the output stream.
+	 *
+	 * @throws FormatException if the contents of the given collection cannot
+	 * be represented as (nested) BDF objects.
+	 */
+	void writeList(Collection<?> c) throws IOException;
+
+	/**
+	 * Writes a BDF dictionary to the output stream.
+	 *
+	 * @throws FormatException if the contents of the given map cannot be
+	 * represented as (nested) BDF objects.
+	 */
+	void writeDictionary(Map<?, ?> m) throws IOException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/BdfWriterFactory.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.io.OutputStream;
+
+@NotNullByDefault
+public interface BdfWriterFactory {
+
+	BdfWriter createWriter(OutputStream out);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/MetadataEncoder.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.db.Metadata;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+@NotNullByDefault
+public interface MetadataEncoder {
+
+	Metadata encode(BdfDictionary d) throws FormatException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/data/MetadataParser.java

+package org.briarproject.bramble.api.data;
+
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.db.Metadata;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+@NotNullByDefault
+public interface MetadataParser {
+
+	BdfDictionary parse(Metadata m) throws FormatException;
+}