[tor-commits] [metrics-lib/master] Document all public parts using Javadoc.

commit 6d05ae95e968806351892b09f7b9653ff82879ed Author: Karsten Loesing karsten.loesing@gmx.net Date: Fri May 20 11:40:35 2016 +0200

Document all public parts using Javadoc.

Based in parts on very helpful suggestions and feedback by iwakeh.

Implements #16873. --- CHANGELOG.md | 2 + build.xml | 18 + resources/overview.html | 69 +++ .../torproject/descriptor/BandwidthHistory.java | 46 +- .../descriptor/BridgeExtraInfoDescriptor.java | 20 +- .../torproject/descriptor/BridgeNetworkStatus.java | 114 +++- .../descriptor/BridgePoolAssignment.java | 40 +- .../descriptor/BridgeServerDescriptor.java | 19 +- src/org/torproject/descriptor/Descriptor.java | 32 +- .../torproject/descriptor/DescriptorCollector.java | 52 +- .../descriptor/DescriptorDownloader.java | 205 +++++-- src/org/torproject/descriptor/DescriptorFile.java | 70 ++- .../descriptor/DescriptorParseException.java | 9 +- .../torproject/descriptor/DescriptorParser.java | 46 +- .../torproject/descriptor/DescriptorReader.java | 146 ++++- .../torproject/descriptor/DescriptorRequest.java | 91 ++- .../descriptor/DescriptorSourceFactory.java | 128 +++- src/org/torproject/descriptor/DirSourceEntry.java | 81 ++- .../descriptor/DirectoryKeyCertificate.java | 98 ++- .../torproject/descriptor/DirectorySignature.java | 43 +- src/org/torproject/descriptor/ExitList.java | 76 ++- src/org/torproject/descriptor/ExitListEntry.java | 48 +- .../torproject/descriptor/ExtraInfoDescriptor.java | 670 +++++++++++++++------ .../ImplementationNotAccessibleException.java | 10 +- src/org/torproject/descriptor/Microdescriptor.java | 130 +++- .../torproject/descriptor/NetworkStatusEntry.java | 169 ++++-- src/org/torproject/descriptor/RelayDirectory.java | 93 ++- .../descriptor/RelayExtraInfoDescriptor.java | 16 +- .../torproject/descriptor/RelayNetworkStatus.java | 156 ++++- .../descriptor/RelayNetworkStatusConsensus.java | 181 +++++- .../descriptor/RelayNetworkStatusVote.java | 342 +++++++++-- .../descriptor/RelayServerDescriptor.java | 15 +- .../torproject/descriptor/RouterStatusEntry.java | 43 +- .../torproject/descriptor/ServerDescriptor.java | 436 ++++++++++---- src/org/torproject/descriptor/TorperfResult.java | 194 ++++-- src/org/torproject/descriptor/package-info.java | 80 +++ 36 files changed, 3208 insertions(+), 780 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md index a1b9a75..bfd4755 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ implementation classes. - Actually return the signing key digest in network status votes. - Parse crypto parts in network status votes. + - Document all public parts in org.torproject.descriptor and add + an Ant target to generate Javadocs.

* Minor changes - Include a Torperf results line with more than one unrecognized diff --git a/build.xml b/build.xml index f7ef7ca..129c4ed 100644 --- a/build.xml +++ b/build.xml @@ -1,7 +1,9 @@ <project default="jar" name="descriptor" basedir="."> <property name="release.version" value="1.1.0-dev" /> <property name="sources" value="src"/> + <property name="resources" value="resources"/> <property name="classes" value="classes"/> + <property name="docs" value="javadoc"/> <property name="tests" value="test"/> <property name="libs" value="lib"/> <property name="jarfile" value="descriptor-${release.version}.jar" /> @@ -25,6 +27,7 @@ <target name="clean" > <delete includeEmptyDirs="true"> <fileset dir="${classes}" defaultexcludes="false" includes="**" /> + <fileset dir="${docs}" defaultexcludes="false" includes="**" /> </delete> <delete file="${jarfile}"/> <delete file="${jarsourcesfile}"/> @@ -33,6 +36,7 @@

<target name="init"> <mkdir dir="${classes}"/> + <mkdir dir="${docs}"/> </target>

<target name="compile" @@ -50,6 +54,20 @@ </javac> </target>

+ <target name="docs"> + <javadoc destdir="${docs}" + footer="&amp;copy; 2016 The Tor Project" + doctitle="DescripTor API Documentation" + overview="${basedir}/${resources}/overview.html" + use="true" + windowtitle="DescripTor API Documentation"> + <classpath refid="classpath"/> + <fileset dir="${sources}"> + <exclude name="**/impl/**"/> + </fileset> + </javadoc> + </target> + <target name="test" depends="compile"> <javac destdir="${classes}" srcdir="${tests}" diff --git a/resources/overview.html b/resources/overview.html new file mode 100644 index 0000000..f5c6b51 --- /dev/null +++ b/resources/overview.html @@ -0,0 +1,69 @@ +<html> +<body> +<p>DescripTor API, which is provided and supported by Tor's Metrics +Team, is a library to obtain and process descriptors containing Tor +network data. It is the main Java tool for processing Tor descriptors +and provides a standard API consisting of interfaces and a reference +implementation for all of them.</p> + +<p>Most Tor descriptors understood by this library are specified in the +<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor +directory protocol, version 3</a> or in the earlier +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a> +of that document. +Other descriptors are specified on the +<a href="https://collector.torproject.org/">CollecTor website</a>.</p> + +<p>The interfaces in +<a href="./org/torproject/descriptor/package-summary.html">{@code org.torproject.descriptor}</a> +as well as their implementations in the +{@code org.torproject.descriptor.impl} package were driven by two main +goals originating from the primary use case to make Tor network data +accessible for statistical analysis:</p> + +<ul> +<li><em>Complete coverage:</em> This library is supposed to cover the +complete range of Tor descriptors made available by the +<a href="https://collector.torproject.org">CollecTor</a> service.</li> +<li><em>Runtime and memory efficiency:</em> Processing large amounts of +descriptors in bulk is supposed to be efficient in terms of runtime and +required memory.</li> +</ul> + +<p>At the same time the current design and implementation were done with a +number of non-goals in mind, even though some of these might turn into +goals in the future:</p> + +<p><ul> +<li><em>Verification:</em> The descriptor parser performs some basic +verifications of descriptor formats, but no cryptographic verifications. +It may not even be possible to write a cryptographic verification tool +using parsed descriptor contents, though this has not been attempted +yet.</li> +<li><em>Potentially lossy conversion:</em> Descriptor contents may be +converted to a format that is easier to process, even if that conversion +makes it harder or impossible to re-create the original descriptor +contents from a parsed descriptor.</li> +<li><em>Generating descriptors:</em> This library does not contain any +functionality to generate new descriptors for testing or related purposes, +neither from previously set data nor randomly.</li> +<li><em>Writing descriptors:</em> This library does not support writing +descriptors to the file system or a database, both of which are left to +the application. Stated differently, there are no descriptor sinks that +would correspond to the provided descriptor sources.</li> +</ul></p> + +<p>Hints about using DescripTor can be found in the +<a href="./org/torproject/descriptor/package-summary.html#package.description">{@code org.torproject.descriptor} package description</a>. +</p> + +<p>Contact and further information: +<ul> +<li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics%2Fmetrics-lib">DescripTor Bug Tracker</a></li> +<li><a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team">Metrics Team Mailing List</a></li> +<li><a href="https://trac.torproject.org/projects/tor/wiki/org/teams/MetricsTeam">Metrics Team Website</a></li> +</ul> +</body> +</html> + diff --git a/src/org/torproject/descriptor/BandwidthHistory.java b/src/org/torproject/descriptor/BandwidthHistory.java index 4431ee2..0be1a53 100644 --- a/src/org/torproject/descriptor/BandwidthHistory.java +++ b/src/org/torproject/descriptor/BandwidthHistory.java @@ -1,26 +1,52 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.SortedMap;

-/* Contains the bandwidth history of a relay or bridge. */ +/** + * Contains the bandwidth history of a relay or bridge. + * + * <p>A bandwidth history is not a descriptor type of its own but usually + * part of extra-info descriptors ({@link ExtraInfoDescriptor}) or server + * descriptors ({@link ServerDescriptor}).</p> + * + * @since 1.0.0 + */ public interface BandwidthHistory {

- /* Return the original bandwidth history line as contained in the - * descriptor, possibly prefixed with "opt ". */ + /** + * Return the original bandwidth history line as contained in the + * descriptor, possibly prefixed with {@code "opt "}. + * + * @since 1.0.0 + */ public String getLine();

- /* Return the end of the most recent interval in millis. */ + /** + * Return the time in milliseconds since the epoch when the most recent + * interval ends. + * + * @since 1.0.0 + */ public long getHistoryEndMillis();

- /* Return the interval length in seconds, which is typically 900 seconds - * or 15 minutes. */ + /** + * Return the interval length in seconds. + * + * @since 1.0.0 + */ public long getIntervalLength();

- /* Return the (possibly empty) bandwidth history with map keys being - * interval ends in millis and map values being number of bytes used in - * the interval, ordered from oldest to newest interval. */ + /** + * Return the (possibly empty) bandwidth history with map keys being + * times in milliseconds since the epoch when intervals end and map + * values being number of bytes used in the interval, ordered from + * oldest to newest interval. + * + * @since 1.0.0 + */ public SortedMap<Long, Long> getBandwidthValues(); }

diff --git a/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java b/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java index b566283..a3c168d 100644 --- a/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java +++ b/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java @@ -1,8 +1,24 @@ -/* Copyright 2015 The Tor Project +/* Copyright 2015--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Contains a bridge extra-info descriptor. */ +/** + * Contains a sanitized bridge extra-info descriptor. + * + * <p>Sanitized bridge extra-info descriptors share many contents with + * relay extra-info descriptors ({@link RelayExtraInfoDescriptor}), which + * is why they share a common + * superinterface ({@link ExtraInfoDescriptor}). The main purpose of + * having two subinterfaces is being able to distinguish descriptor types + * more easily.</p> + * + * <p>Details about sanitizing bridge extra-info descriptors can be found + * <a href="https://collector.torproject.org/#type-bridge-extra-info">here</a>. + * </p> + * + * @since 1.1.0 + */ public interface BridgeExtraInfoDescriptor extends ExtraInfoDescriptor {

} diff --git a/src/org/torproject/descriptor/BridgeNetworkStatus.java b/src/org/torproject/descriptor/BridgeNetworkStatus.java index 1a28ebf..c7458fd 100644 --- a/src/org/torproject/descriptor/BridgeNetworkStatus.java +++ b/src/org/torproject/descriptor/BridgeNetworkStatus.java @@ -1,62 +1,128 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.SortedMap;

+/** + * Contains a sanitized bridge network status document. + * + * <p>The bridge directory authority periodically publishes a network + * status document with one entry per known bridge in the network + * ({@link NetworkStatusEntry}) containing: a hash of its identity key, a + * hash of its most recent server descriptor, and a summary of what the + * bridge authority believed about its status.</p> + * + * <p>The main purpose of this document is to get an authoritative list of + * running bridges to the bridge distribution service BridgeDB.</p> + * + * <p>Details about sanitizing bridge network statuses can be found + * <a href="https://collector.torproject.org/#type-bridge-network-status">here</a>. + * </p> + * + * @since 1.0.0 + */ public interface BridgeNetworkStatus extends Descriptor {

- /* Return the published time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the minimum uptime in seconds that this authority requires for - * assigning the Stable flag, or -1 if the authority doesn't report this - * value. */ + /** + * Return the minimum uptime in seconds that this authority requires + * for assigning the Stable flag, or -1 if the authority doesn't report + * this value. + * + * @since 1.1.0 + */ public long getStableUptime();

- /* Return the minimum MTBF (mean time between failure) that this + /** + * Return the minimum MTBF (mean time between failure) that this * authority requires for assigning the Stable flag, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.1.0 + */ public long getStableMtbf();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Fast flag, or -1 if the authority doesn't report this - * value. */ + * value. + * + * @since 1.1.0 + */ public long getFastBandwidth();

- /* Return the minimum WFU (weighted fractional uptime) in percent that - * this authority requires for assigning the Guard flag, or -1.0 if the - * authority doesn't report this value. */ + /** + * Return the minimum WFU (weighted fractional uptime) in percent that + * this authority requires for assigning the Guard flag, or -1 if the + * authority doesn't report this value. + * + * @since 1.1.0 + */ public double getGuardWfu();

- /* Return the minimum weighted time in seconds that this authority needs - * to know about a relay before assigning the Guard flag, or -1 if the - * authority doesn't report this information. */ + /** + * Return the minimum weighted time in seconds that this authority + * needs to know about a relay before assigning the Guard flag, or -1 if + * the authority doesn't report this information. + * + * @since 1.1.0 + */ public long getGuardTk();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Guard flag if exits can be guards, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.1.0 + */ public long getGuardBandwidthIncludingExits();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Guard flag if exits can not be guards, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.1.0 + */ public long getGuardBandwidthExcludingExits();

- /* Return 1 if the authority has measured enough MTBF info to use the + /** + * Return 1 if the authority has measured enough MTBF info to use the * MTBF requirement instead of the uptime requirement for assigning the * Stable flag, 0 if not, or -1 if the authority doesn't report this - * information. */ + * information. + * + * @since 1.1.0 + */ public int getEnoughMtbfInfo();

- /* Return 1 if the authority has enough measured bandwidths that it'll + /** + * Return 1 if the authority has enough measured bandwidths that it'll * ignore the advertised bandwidth claims of routers without measured * bandwidth, 0 if not, or -1 if the authority doesn't report this - * information. */ + * information. + * + * @since 1.1.0 + */ public int getIgnoringAdvertisedBws();

- /* Return status entries, one for each contained bridge. */ + /** + * Return status entries for each contained bridge, with map keys being + * SHA-1 digests of SHA-1 digest of the bridges' public identity keys, + * encoded as 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, NetworkStatusEntry> getStatusEntries(); }

diff --git a/src/org/torproject/descriptor/BridgePoolAssignment.java b/src/org/torproject/descriptor/BridgePoolAssignment.java index 5186b2b..2de4ee9 100644 --- a/src/org/torproject/descriptor/BridgePoolAssignment.java +++ b/src/org/torproject/descriptor/BridgePoolAssignment.java @@ -1,17 +1,47 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.SortedMap;

+/** + * Contains a sanitized list of bridges together with the distribution + * pools they have been assigned to by the bridge distribution service + * BridgeDB. + * + * <p>BridgeDB receives bridge network statuses + * ({@link BridgeNetworkStatus}) from the bridge authority, assigns these + * bridges to persistent distribution rings, and hands them out to bridge + * users. BridgeDB periodically dumps the list of running bridges with + * information about the rings, subrings, and file buckets to which they + * are assigned to a local file.</p> + * + * <p>Details about sanitizing bridge pool assignments can be found + * <a href="https://collector.torproject.org/#type-bridge-pool-assignment">here</a>. + * </p> + * + * @since 1.0.0 + */ public interface BridgePoolAssignment extends Descriptor {

- /* Return the publication time of this bridge pool assignment list. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the entries contained in this bridge pool assignment list with - * map keys being bridge fingerprints and map values being assignment - * strings, e.g. "https ring=3 flag=stable". */ + /** + * Return the entries contained in this bridge pool assignment list + * with map keys being SHA-1 digests of SHA-1 digest of the bridges' + * public identity keys, encoded as 40 upper-case hexadecimal + * characters, and map values being assignment strings, e.g. + * {@code "https ring=3 flag=stable"}. + * + * @since 1.0.0 + */ public SortedMap<String, String> getEntries(); }

diff --git a/src/org/torproject/descriptor/BridgeServerDescriptor.java b/src/org/torproject/descriptor/BridgeServerDescriptor.java index 15b618a..7d4503f 100644 --- a/src/org/torproject/descriptor/BridgeServerDescriptor.java +++ b/src/org/torproject/descriptor/BridgeServerDescriptor.java @@ -1,8 +1,23 @@ -/* Copyright 2015 The Tor Project +/* Copyright 2015--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Contains a bridge server descriptor. */ +/** + * Contains a sanitized bridge server descriptor. + * + * <p>Sanitized bridge server descriptors share many contents with relay + * server descriptors ({@link RelayServerDescriptor}), which is why they + * share a common superinterface ({@link ServerDescriptor}). The main + * purpose of having two subinterfaces is being able to distinguish + * descriptor types more easily.</p> + * + * <p>Details about sanitizing bridge server descriptors can be found + * <a href="https://collector.torproject.org/#type-bridge-server-descriptor">here</a>. + * </p> + * + * @since 1.1.0 + */ public interface BridgeServerDescriptor extends ServerDescriptor {

} diff --git a/src/org/torproject/descriptor/Descriptor.java b/src/org/torproject/descriptor/Descriptor.java index 267caf1..7cad109 100644 --- a/src/org/torproject/descriptor/Descriptor.java +++ b/src/org/torproject/descriptor/Descriptor.java @@ -1,21 +1,39 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

-/* Store meta-data about how a descriptor was downloaded or read from - * disk. */ +/** + * Superinterface for any descriptor with access to generic information + * about the descriptor. + * + * @since 1.0.0 + */ public interface Descriptor {

- /* Return the raw descriptor bytes. */ + /** + * Return the raw descriptor bytes. + * + * @since 1.0.0 + */ public byte[] getRawDescriptorBytes();

- /* Return the (possibly empty) list of annotations. */ + /** + * Return the (possibly empty) list of annotations in the format + * {@code "@key( value)*"}. + * + * @since 1.0.0 + */ public List<String> getAnnotations();

- /* Return any unrecognized lines when parsing this descriptor, or an - * empty list if there were no unrecognized lines. */ + /** + * Return any unrecognized lines when parsing this descriptor, or an + * empty list if there were no unrecognized lines. + * + * @since 1.0.0 + */ public List<String> getUnrecognizedLines(); }

diff --git a/src/org/torproject/descriptor/DescriptorCollector.java b/src/org/torproject/descriptor/DescriptorCollector.java index 18e594d..b1027dc 100644 --- a/src/org/torproject/descriptor/DescriptorCollector.java +++ b/src/org/torproject/descriptor/DescriptorCollector.java @@ -1,12 +1,39 @@ -/* Copyright 2015 The Tor Project +/* Copyright 2015--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.io.File;

-/** Fetch descriptors from the CollecTor service available at - * https://collector.torproject.org/ and store them to a local - * directory. */ +/** + * Descriptor source that synchronizes descriptors from the CollecTor + * service to a given local directory. + * + * <p>This type is not a descriptor source in the proper sense, because it + * does not produce descriptors by itself. But it often creates the + * prerequisites for reading descriptors from disk using + * {@link DescriptorReader}.</p> + * + * <p>Code sample:</p> + * <pre>{@code + * DescriptorCollector descriptorCollector = + * DescriptorSourceFactory.createDescriptorCollector(); + * descriptorCollector.collectDescriptors( + * // Download from Tor's main CollecTor instance, + * "https://collector.torproject.org", + * // include network status consensuses and relay server descriptors + * new String[] { "/recent/relay-descriptors/consensuses/", + * "/recent/relay-descriptors/server-descriptors/" }, + * // regardless of last-modified time, + * 0L, + * // write to the local directory called in/, + * new File("in"), + * // and delete extraneous files that do not exist remotely anymore. + * true); + * }</pre> + * + * @since 1.0.0 + */ public interface DescriptorCollector {

/** @@ -15,17 +42,18 @@ public interface DescriptorCollector { * anymore. * * @param collecTorBaseUrl CollecTor base URL without trailing slash, - * e.g., "https://collector.torproject.org". + * e.g., {@code "https://collector.torproject.org%22%7D * @param remoteDirectories Remote directories to collect descriptors - * from, e.g., "/recent/relay-descriptors/server-descriptors/". Only - * files in this directory will be collected, no files in its sub - * directories. + * from, e.g., + * {@code "/recent/relay-descriptors/server-descriptors/"}, without + * processing subdirectories unless they are explicitly listed * @param minLastModified Minimum last-modified time in milliseconds of - * files to be collected. Set to 0 for collecting all files. - * @param localDirectory Directory where collected files will be - * written. + * files to be collected, or 0 for collecting all files + * @param localDirectory Directory where collected files will be written * @param deleteExtraneousLocalFiles Whether to delete all local files - * that do not exist remotely anymore. + * that do not exist remotely anymore + * + * @since 1.0.0 */ public void collectDescriptors(String collecTorBaseUrl, String[] remoteDirectories, long minLastModified, diff --git a/src/org/torproject/descriptor/DescriptorDownloader.java b/src/org/torproject/descriptor/DescriptorDownloader.java index 1fc68a0..f0b1101 100644 --- a/src/org/torproject/descriptor/DescriptorDownloader.java +++ b/src/org/torproject/descriptor/DescriptorDownloader.java @@ -1,109 +1,198 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.Iterator; import java.util.Set;

-/* Download relay descriptors from directory mirrors or authorities. */ +/** + * Descriptor source that downloads relay descriptors from directory + * authorities or mirrors. + * + * <p>Downloading descriptors is done in a batch which starts after + * setting any configuration options and initiating the download + * process.</p> + * + * @since 1.0.0 + */ public interface DescriptorDownloader {

- /* Add a directory authority to download descriptors from. A directory - * authority is only required for downloading network status vote and - * will be used when no directory mirrors are available. */ + /** + * Add a directory authority to download descriptors from, which is + * only required for downloading network status votes and will be used + * when no directory mirrors are available. + * + * @since 1.0.0 + */ public void addDirectoryAuthority(String nickname, String ip, int dirPort);

- /* Add a directory mirror to download descriptors from. Directory - * mirrors are preferred when downloading descriptors, except for - * network status votes which are only available on directory - * authorities. */ + /** + * Add a directory mirror to download descriptors from, which is + * preferred for downloading descriptors, except for network status + * votes which are only available on directory authorities. + * + * @since 1.0.0 + */ public void addDirectoryMirror(String nickname, String ip, int dirPort);

- /* Include the current network status consensus in the downloads. */ + /** + * Include the current network status consensus in the downloads. + * + * @since 1.0.0 + */ public void setIncludeCurrentConsensus();

- /* Include the current network status consensus in the downloads, and - * attempt to download it from all directory authorities. The primary - * purpose of doing this is to compare different consensuses and - * download characteristics to each other. Typically, downloading from - * a single directory mirror or authority is sufficient. */ + /** + * Include the current network status consensus in the downloads, and + * attempt to download it from all directory authorities. + * + * <p>The primary purpose of doing this is to compare different + * consensuses and download characteristics to each other. Typically, + * downloading from a single directory mirror or authority is + * sufficient.</p> + * + * @since 1.0.0 + */ public void setIncludeCurrentConsensusFromAllDirectoryAuthorities();

- /* Include the current network status votes referenced from a previously - * downloaded consensus in the downloads. This requires downloading the - * current consensus from at least one directory mirror or authority. */ + /** + * Include the current network status votes referenced from a + * previously downloaded consensus in the downloads, which requires + * downloading the current consensus from at least one directory mirror + * or authority. + * + * @since 1.0.0 + */ public void setIncludeCurrentReferencedVotes();

- /* Include the current network status vote published by the given - * directory authority in the downloads. This requires downloading from - * at least one directory authority. */ + /** + * Include the current network status vote published by the given + * directory authority in the downloads, which requires downloading from + * at least one directory authority. + * + * @since 1.0.0 + */ public void setIncludeCurrentVote(String fingerprint);

- /* Include the current network status votes published by the given - * directory authorities in the downloads. This requires downloading - * from at least one directory authority. */ + /** + * Include the current network status votes published by the given + * directory authorities in the downloads, which requires downloading + * from at least one directory authority. + * + * @since 1.0.0 + */ public void setIncludeCurrentVotes(Set<String> fingerprints);

- /* Include all server descriptors referenced from a previously - * downloaded network status consensus in the downloads. */ + /** + * Include all server descriptors referenced from a previously + * downloaded network status consensus in the downloads. + * + * @since 1.0.0 + */ public void setIncludeReferencedServerDescriptors();

- /* Exclude the server descriptor with the given identifier from the + /** + * Exclude the server descriptor with the given identifier from the * downloads even if it's referenced from a consensus and we're supposed - * to download all referenced server descriptors. */ + * to download all referenced server descriptors. + * + * @since 1.0.0 + */ public void setExcludeServerDescriptor(String identifier);

- /* Exclude the server descriptors with the given identifiers from the + /** + * Exclude the server descriptors with the given identifiers from the * downloads even if they are referenced from a consensus and we're - * supposed to download all referenced server descriptors. */ + * supposed to download all referenced server descriptors. + * + * @since 1.0.0 + */ public void setExcludeServerDescriptors(Set<String> identifier);

- /* Include all extra-info descriptors referenced from previously - * downloaded server descriptors in the downloads. */ + /** + * Include all extra-info descriptors referenced from previously + * downloaded server descriptors in the downloads. + * + * @since 1.0.0 + */ public void setIncludeReferencedExtraInfoDescriptors();

- /* Exclude the extra-info descriptor with the given identifier from the + /** + * Exclude the extra-info descriptor with the given identifier from the * downloads even if it's referenced from a server descriptor and we're - * supposed to download all referenced extra-info descriptors. */ + * supposed to download all referenced extra-info descriptors. + * + * @since 1.0.0 + */ public void setExcludeExtraInfoDescriptor(String identifier);

- /* Exclude the extra-info descriptors with the given identifiers from + /** + * Exclude the extra-info descriptors with the given identifiers from * the downloads even if they are referenced from server descriptors * and we're supposed to download all referenced extra-info - * descriptors. */ + * descriptors. + * + * @since 1.0.0 + */ public void setExcludeExtraInfoDescriptors(Set<String> identifiers);

- /* Define a connect timeout for a single request. If a timeout expires, - * no further requests will be sent to the directory authority or - * mirror. Setting this value to 0 disables the connect timeout. - * Default value is 1 minute (60 * 1000). */ + /** + * Define a connect timeout for a single request. + * + * <p>If a timeout expires, no further requests will be sent to the + * directory authority or mirror. Setting this value to 0 disables the + * connect timeout. Default value is 1 minute (60 * 1000).</p> + * + * @since 1.0.0 + */ public void setConnectTimeout(long connectTimeoutMillis);

- /* Define a read timeout for a single request. If a timeout expires, - * no further requests will be sent to the directory authority or - * mirror. Setting this value to 0 disables the read timeout. - * Default value is 1 minute (60 * 1000). */ + /** + * Define a read timeout for a single request. + * + * <p>If a timeout expires, no further requests will be sent to the + * directory authority or mirror. Setting this value to 0 disables the + * read timeout. Default value is 1 minute (60 * 1000).</p> + * + * @since 1.0.0 + */ public void setReadTimeout(long readTimeoutMillis);

- /* Define a global timeout for all requests. Once this timeout expires, - * all running requests are aborted and no further requests are made. - * Setting this value to 0 disables the global timeout. Default is 1 - * hour (60 * 60 * 1000). */ + /** + * Define a global timeout for all requests. + * + * <p>Once this timeout expires, all running requests are aborted and no + * further requests are made. Setting this value to 0 disables the + * global timeout. Default is 1 hour (60 * 60 * 1000).</p> + * + * @since 1.0.0 + */ public void setGlobalTimeout(long globalTimeoutMillis);

- /* Fail descriptor parsing when encountering an unrecognized line. This - * is not set by default, because the Tor specifications allow for new - * lines to be added that shall be ignored by older Tor versions. But - * some applications may want to handle unrecognized descriptor lines - * explicitly. */ + /** + * Fail descriptor parsing when encountering an unrecognized line. + * + * <p>This option is not set by default, because the Tor specifications + * allow for new lines to be added that shall be ignored by older Tor + * versions. But some applications may want to handle unrecognized + * descriptor lines explicitly.</p> + * + * @since 1.0.0 + */ public void setFailUnrecognizedDescriptorLines();

- /* Download the previously configured relay descriptors and make them - * available via the returned blocking iterator. Whenever the - * downloader runs out of descriptors and expects to provide more - * shortly after, it blocks the caller. This method can only be run - * once. */ + /** + * Download the previously configured relay descriptors and make them + * available via the returned blocking iterator. + * + * <p>Whenever the downloader runs out of descriptors and expects to + * provide more shortly after, it blocks the caller. This method can + * only be run once.</p> + * + * @since 1.0.0 + */ public Iterator<DescriptorRequest> downloadDescriptors(); }

diff --git a/src/org/torproject/descriptor/DescriptorFile.java b/src/org/torproject/descriptor/DescriptorFile.java index ec012ca..417d7f9 100644 --- a/src/org/torproject/descriptor/DescriptorFile.java +++ b/src/org/torproject/descriptor/DescriptorFile.java @@ -1,39 +1,77 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.io.File; import java.util.List;

-/* Store meta-data about a descriptor file and a list of the contained - * descriptors. */ +/** + * Container for descriptors read from a file. + * + * <p>When the {@link DescriptorReader} reads descriptors from local files + * it provides an iterator over these containers which in turn contain + * references to classes implementing the {@link Descriptor} interface. + * This container also stores potentially useful meta-data about the + * descriptor file.</p> + * + * @since 1.0.0 + */ public interface DescriptorFile {

- /* Return the directory where this descriptor file was contained, or - * null if the file was contained in a tarball. */ + /** + * Return the directory where this descriptor file was contained, or + * null if the file was contained in a tarball. + * + * @since 1.0.0 + */ public File getDirectory();

- /* Return the tarball where this descriptor file was contained, or null - * if the file was not contained in a tarball. */ + /** + * Return the tarball where this descriptor file was contained, or null + * if the file was not contained in a tarball. + * + * @since 1.0.0 + */ public File getTarball();

- /* Return the descriptor file itself, or null if the descriptor file was - * contained in a tarball. */ + /** + * Return the descriptor file itself, or null if the descriptor file + * was contained in a tarball. + * + * @since 1.0.0 + */ public File getFile();

- /* Return the descriptor file name, which is either the absolute path of - * the file on disk, or the tar file entry name. */ + /** + * Return the descriptor file name, which is either the absolute path + * of the file on disk, or the tar file entry name. + * + * @since 1.0.0 + */ public String getFileName();

- /* Return the time in millis when the descriptor file on disk was last - * modified. */ + /** + * Return the time in milliseconds since the epoch when the descriptor + * file on disk was last modified. + * + * @since 1.0.0 + */ public long getLastModified();

- /* Return the descriptors contained in the descriptor file. */ + /** + * Return the descriptors contained in the descriptor file. + * + * @since 1.0.0 + */ public List<Descriptor> getDescriptors();

- /* Return the first exception that was thrown when reading this file or - * parsing its content, or null if no exception was thrown. */ + /** + * Return the first exception that was thrown when reading this file or + * parsing its content, or null if no exception was thrown. + * + * @since 1.0.0 + */ public Exception getException(); }

diff --git a/src/org/torproject/descriptor/DescriptorParseException.java b/src/org/torproject/descriptor/DescriptorParseException.java index ff5707d..309d3f7 100644 --- a/src/org/torproject/descriptor/DescriptorParseException.java +++ b/src/org/torproject/descriptor/DescriptorParseException.java @@ -1,7 +1,14 @@ -/* Copyright 2014--2015 The Tor Project +/* Copyright 2014--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

+/** + * Thrown if raw descriptor contents cannot be parsed to one or more + * {@link Descriptor} instances, according to descriptor specifications. + * + * @since 1.0.0 + */ @SuppressWarnings("deprecation") public class DescriptorParseException extends org.torproject.descriptor.impl.DescriptorParseException { diff --git a/src/org/torproject/descriptor/DescriptorParser.java b/src/org/torproject/descriptor/DescriptorParser.java index 7c59cea..680b8b2 100644 --- a/src/org/torproject/descriptor/DescriptorParser.java +++ b/src/org/torproject/descriptor/DescriptorParser.java @@ -1,25 +1,47 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

- -/* Parse descriptors that are already in memory instead of using the - * descriptor reader or downloader. */ +/** + * Descriptor source that parses descriptors from raw descriptor contents. + * + * <p>Unlike most of the other descriptor sources this descriptor source + * does not operate in a batch-processing mode. It takes the raw + * descriptor contents of one or more descriptors, parses them, and + * returns a list of descriptors.</p> + * + * <p>This descriptor source is internally used by other descriptor + * sources but can also be used directly by applications that obtain + * raw descriptor contents via other means than one of the existing + * descriptor sources.</p> + * + * @since 1.0.0 + */ public interface DescriptorParser {

- /* Fail descriptor parsing when encountering an unrecognized line. This - * is not set by default, because the Tor specifications allow for new - * lines to be added that shall be ignored by older Tor versions. But - * some applications may want to handle unrecognized descriptor lines - * explicitly. */ + /** + * Fail descriptor parsing when encountering an unrecognized line. + * + * <p>This option is not set by default, because the Tor specifications + * allow for new lines to be added that shall be ignored by older Tor + * versions. But some applications may want to handle unrecognized + * descriptor lines explicitly.</p> + * + * @since 1.0.0 + */ public void setFailUnrecognizedDescriptorLines( boolean failUnrecognizedDescriptorLines);

- /* Parse descriptors in the given byte array, possibly parsing the - * publication time from the file name (depending on the descriptor - * type). */ + /** + * Parse descriptors in the given byte array, possibly parsing the + * publication time from the file name, depending on the descriptor + * type. + * + * @since 1.0.0 + */ public List<Descriptor> parseDescriptors(byte[] rawDescriptorBytes, String fileName) throws DescriptorParseException; } diff --git a/src/org/torproject/descriptor/DescriptorReader.java b/src/org/torproject/descriptor/DescriptorReader.java index 0e2fe27..771755e 100644 --- a/src/org/torproject/descriptor/DescriptorReader.java +++ b/src/org/torproject/descriptor/DescriptorReader.java @@ -1,63 +1,143 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.io.File; import java.util.Iterator; import java.util.SortedMap;

-/* Read descriptors from one or more local directories. */ +/** + * Descriptor source that reads descriptors from local files and provides + * an iterator over parsed descriptors. + * + * <p>This descriptor source is likely the most widely used one, possibly + * in combination with {@link DescriptorCollector} to synchronize + * descriptors from the CollecTor service.</p> + * + * <p>Reading descriptors is done in a batch which starts after setting + * any configuration options and initiating the read process.</p> + * + * <p>Code sample:</p> + * <pre>{@code + * DescriptorReader descriptorReader = + * DescriptorSourceFactory.createDescriptorReader(); + * // Read descriptors from local directory called in/. + * descriptorReader.addDirectory(new File("in")); + * Iterator<DescriptorFile> descriptorFiles = + * descriptorReader.readDescriptors(); + * while (descriptorFiles.hasNext()) { + * DescriptorFile descriptorFile = descriptorFiles.next(); + * for (Descriptor descriptor : descriptorFile.getDescriptors()) { + * if ((descriptor instanceof RelayNetworkStatusConsensus)) { + * // Only process network status consensuses, ignore the rest. + * RelayNetworkStatusConsensus consensus = + * (RelayNetworkStatusConsensus) descriptor; + * processConsensus(consensus); + * } + * } + * }}</pre> + * + * @since 1.0.0 + */ public interface DescriptorReader {

- /* Add a local directory to read descriptor files or tarballs containing - * descriptor files from. */ + /** + * Add a local directory to read descriptors from, which may contain + * descriptor files or tarballs containing descriptor files. + * + * @since 1.0.0 + */ public void addDirectory(File directory);

- /* Add an uncompressed or bz2-compressed tarball to read descriptors - * from. */ + /** + * Add a tarball to read descriptors from, which may be uncompressed, + * bz2-compressed, or xz-compressed. + * + * @since 1.0.0 + */ public void addTarball(File tarball);

- /* Exclude files that are contained in the given history file and that - * haven't changed since they were last read. Add reads from the - * current run to the history file. Remove files that don't exist - * anymore from the history file. Lines in the history file contain the - * last modified timestamp and the absolute path of a file. */ + /** + * Exclude files that are listed in the given history file and that + * haven't changed since they have last been read. + * + * <p>Add a new line for each descriptor that is read in this execution + * and remove lines for files that don't exist anymore.</p> + * + * <p>Lines in the history file contain the last modified time in + * milliseconds since the epoch and the absolute path of a file.</p> + * + * @since 1.0.0 + */ public void setExcludeFiles(File historyFile);

- /* Exclude files if they haven't changed since the corresponding last - * modified timestamps. Can be used instead of (or in addition to) a - * history file. */ + /** + * Exclude files if they haven't changed since the corresponding last + * modified timestamps. + * + * <p>Can be used instead of (or in addition to) a history file.</p> + * + * @since 1.0.0 + */ public void setExcludedFiles(SortedMap<String, Long> excludedFiles);

- /* Return files and lost modified timestamps of files that exist in the + /** + * Return files and last modified timestamps of files that exist in the * input directory or directories, but that have been excluded from * parsing, because they haven't changed since they were last read. - * Can be used instead of (or in addition to) a history file when - * combined with the set of parsed files. */ + * + * <p>Can be used instead of (or in addition to) a history file when + * combined with the set of parsed files.</p> + * + * @since 1.0.0 + */ public SortedMap<String, Long> getExcludedFiles();

- /* Return files and last modified timestamps of files that exist in the - * input directory or directories and that have been parsed. Can be - * used instead of (or in addition to) a history file when combined with - * the set of excluded files. */ + /** + * Return files and last modified timestamps of files that exist in the + * input directory or directories and that have been parsed. + * + * <p>Can be used instead of (or in addition to) a history file when + * combined with the set of excluded files.</p> + * + * @since 1.0.0 + */ public SortedMap<String, Long> getParsedFiles();

- /* Fail descriptor parsing when encountering an unrecognized line. This - * is not set by default, because the Tor specifications allow for new - * lines to be added that shall be ignored by older Tor versions. But - * some applications may want to handle unrecognized descriptor lines - * explicitly. */ + /** + * Fail descriptor parsing when encountering an unrecognized line. + * + * <p>This option is not set by default, because the Tor specifications + * allow for new lines to be added that shall be ignored by older Tor + * versions. But some applications may want to handle unrecognized + * descriptor lines explicitly.</p> + * + * @since 1.0.0 + */ public void setFailUnrecognizedDescriptorLines();

- /* Don't keep more than this number of parsed descriptor files in the - * queue. The default is 100, but if descriptor files contain hundreds - * or even thousands of descriptors, that default may be too high. */ + /** + * Don't keep more than this number of parsed descriptor files in the + * queue. + * + * <p>The default is 100, but if descriptor files contain hundreds or + * even thousands of descriptors, that default may be too high.</p> + * + * @since 1.0.0 + */ public void setMaxDescriptorFilesInQueue(int max);

- /* Read the previously configured descriptors and make them available - * via the returned blocking iterator. Whenever the reader runs out of - * descriptors and expects to provide more shortly after, it blocks the - * caller. This method can only be run once. */ + /** + * Read the previously configured descriptors and make them available + * via the returned blocking iterator. + * + * <p>Whenever the reader runs out of descriptors and expects to provide + * more shortly after, it blocks the caller. This method can only be + * run once.</p> + * + * @since 1.0.0 + */ public Iterator<DescriptorFile> readDescriptors(); }

diff --git a/src/org/torproject/descriptor/DescriptorRequest.java b/src/org/torproject/descriptor/DescriptorRequest.java index 067cd1b..c36c0c0 100644 --- a/src/org/torproject/descriptor/DescriptorRequest.java +++ b/src/org/torproject/descriptor/DescriptorRequest.java @@ -1,47 +1,100 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

-/* Store meta-data about a descriptor request and a list of the returned - * descriptors. */ +/** + * Container for descriptors downloaded from a directory authority or + * mirror. + * + * <p>When the {@link DescriptorDownloader} downloads descriptors from + * directory authorities or mirrors it provides an iterator over these + * containers which in turn contain references to classes implementing the + * {@link Descriptor} interface. This container also stores potentially + * useful meta-data about the descriptor request.</p> + * + * @since 1.0.0 + */ public interface DescriptorRequest {

- /* Return the request URL that was used in this request. */ + /** + * Return the request URL that was used in this request. + * + * @since 1.0.0 + */ public String getRequestUrl();

- /* Return the nickname of the directory mirror or authority as - * previously configured. */ + /** + * Return the nickname of the directory mirror or authority as + * previously configured. + * + * @since 1.0.0 + */ public String getDirectoryNickname();

- /* Return the first exception that was thrown when making this request - * or parsing the response, or null if no exception was thrown. */ + /** + * Return the first exception that was thrown when making this request + * or parsing the response, or null if no exception was thrown. + * + * @since 1.0.0 + */ public Exception getException();

- /* Return the response code that the directory mirror or authority - * returned. */ + /** + * Return the response code that the directory mirror or authority + * returned. + * + * @since 1.0.0 + */ public int getResponseCode();

- /* Return the time in millis when this request was started. */ + /** + * Return the time in milliseconds since the epoch when this request + * was started. + * + * @since 1.0.0 + */ public long getRequestStart();

- /* Return the time in millis when this request ended. */ + /** + * Return the time in milliseconds since the epoch when this request + * ended. + * + * @since 1.0.0 + */ public long getRequestEnd();

- /* Return whether this request ended, because the connect timeout has - * expired. */ + /** + * Return whether this request ended, because the connect timeout has + * expired. + * + * @since 1.0.0 + */ public boolean connectTimeoutHasExpired();

- /* Return whether this request ended, because the read timeout has - * expired. */ + /** + * Return whether this request ended, because the read timeout has + * expired. + * + * @since 1.0.0 + */ public boolean readTimeoutHasExpired();

- /* Return whether this request ended, because the global timeout for all - * requests has expired. */ + /** + * Return whether this request ended, because the global timeout for + * all requests has expired. + * + * @since 1.0.0 + */ public boolean globalTimeoutHasExpired();

- /* Return the descriptors contained in the reply. */ + /** + * Return the descriptors contained in the reply. + * + * @since 1.0.0 + */ public List<Descriptor> getDescriptors(); }

diff --git a/src/org/torproject/descriptor/DescriptorSourceFactory.java b/src/org/torproject/descriptor/DescriptorSourceFactory.java index 728c3eb..af13f39 100644 --- a/src/org/torproject/descriptor/DescriptorSourceFactory.java +++ b/src/org/torproject/descriptor/DescriptorSourceFactory.java @@ -1,49 +1,151 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Create descriptor source instances. */ +/** + * Factory for descriptor sources which in turn produce descriptors. + * + * <p>Descriptor sources are the only producers of classes implementing + * the {@link Descriptor} superinterface. There exist descriptor sources + * for obtaining remote descriptor data ({@link DescriptorDownloader} and + * {@link DescriptorCollector}) and descriptor sources for processing + * local descriptor data ({@link DescriptorReader} and + * {@link DescriptorParser}).</p> + * + * <p>By default, this factory returns implementations from the library's + * own impl package. This may be overridden by setting Java properties, + * though most users will simply use the default implementations.</p> + * + * <p>These properties can be used for setting the implementation:</p> + * <ul> + * <li>{@code descriptor.collector}</li> + * <li>{@code descriptor.downloader}</li> + * <li>{@code descriptor.parser}</li> + * <li>{@code descriptor.reader}</li> + * </ul> + * + * <p>Assuming the classpath contains the special implementation + * referenced, your application classes as well as a descriptor API jar + * the following is an example for using a different implementation of the + * descriptor downloader:</p> + * + * <p><code> + * java -Ddescriptor.downloader=my.special.descriptorimpl.Downloader my.app.Mainclass + * </code></p> + * + * @since 1.0.0 + */ public final class DescriptorSourceFactory {

- /* default implementations */ - public final static String LOADER_DEFAULT = + /** + * Default implementation of the {@link DescriptorDownloader} + * descriptor source. + * + * @since 1.0.0 + */ + public final static String DOWNLOADER_DEFAULT = "org.torproject.descriptor.impl.DescriptorDownloaderImpl"; + + /** + * Default implementation of the {@link DescriptorParser} descriptor + * source. + * + * @since 1.0.0 + */ public final static String PARSER_DEFAULT = "org.torproject.descriptor.impl.DescriptorParserImpl"; + + /** + * Default implementation of the {@link DescriptorReader} descriptor + * source. + * + * @since 1.0.0 + */ public final static String READER_DEFAULT = "org.torproject.descriptor.impl.DescriptorReaderImpl"; + + /** + * Default implementation of the {@link DescriptorCollector} descriptor + * source. + * + * @since 1.0.0 + */ public final static String COLLECTOR_DEFAULT = "org.torproject.descriptor.impl.DescriptorCollectorImpl";

- /* property names */ + /** + * Property name for overriding the implementation of the + * {@link DescriptorParser} descriptor source, which is by default set + * to the class in {@link #PARSER_DEFAULT}. + * + * @since 1.0.0 + */ public final static String PARSER_PROPERTY = "descriptor.parser"; + + /** + * Property name for overriding the implementation of the + * {@link DescriptorReader} descriptor source, which is by default set + * to the class in {@link #READER_DEFAULT}. + * + * @since 1.0.0 + */ public final static String READER_PROPERTY = "descriptor.reader"; - public final static String LOADER_PROPERTY = "descriptor.downloader"; + + /** + * Property name for overriding the implementation of the + * {@link DescriptorDownloader} descriptor source, which is by default + * set to the class in {@link #DOWNLOADER_DEFAULT}. + * + * @since 1.0.0 + */ + public final static String DOWNLOADER_PROPERTY = + "descriptor.downloader"; + + /** + * Property name for overriding the implementation of the + * {@link DescriptorCollector} descriptor source, which is by default + * set to the class in {@link #COLLECTOR_DEFAULT}. + * + * @since 1.0.0 + */ public final static String COLLECTOR_PROPERTY = "descriptor.collector";

/** - * Create a descriptor parser. + * Create a new {@link DescriptorParser} by instantiating the class in + * {@link #PARSER_PROPERTY}. + * + * @since 1.0.0 */ public final static DescriptorParser createDescriptorParser() { return (DescriptorParser) retrieve(PARSER_PROPERTY); }

/** - * Create a descriptor reader. + * Create a new {@link DescriptorReader} by instantiating the class in + * {@link #READER_PROPERTY}. + * + * @since 1.0.0 */ public final static DescriptorReader createDescriptorReader() { return (DescriptorReader) retrieve(READER_PROPERTY); }

/** - * Create a descriptor downloader. + * Create a new {@link DescriptorDownloader} by instantiating the class + * in {@link #DOWNLOADER_PROPERTY}. + * + * @since 1.0.0 */ public final static DescriptorDownloader createDescriptorDownloader() { - return (DescriptorDownloader) retrieve(LOADER_PROPERTY); + return (DescriptorDownloader) retrieve(DOWNLOADER_PROPERTY); }

/** - * Create a descriptor collector. + * Create a new {@link DescriptorCollector} by instantiating the class + * in {@link #COLLECTOR_PROPERTY}. + * + * @since 1.0.0 */ public final static DescriptorCollector createDescriptorCollector() { return (DescriptorCollector) retrieve(COLLECTOR_PROPERTY); @@ -57,8 +159,8 @@ public final class DescriptorSourceFactory { case PARSER_PROPERTY: clazzName = System.getProperty(type, PARSER_DEFAULT); break; - case LOADER_PROPERTY: - clazzName = System.getProperty(type, LOADER_DEFAULT); + case DOWNLOADER_PROPERTY: + clazzName = System.getProperty(type, DOWNLOADER_DEFAULT); break; case READER_PROPERTY: clazzName = System.getProperty(type, READER_DEFAULT); diff --git a/src/org/torproject/descriptor/DirSourceEntry.java b/src/org/torproject/descriptor/DirSourceEntry.java index da898d0..96d81ee 100644 --- a/src/org/torproject/descriptor/DirSourceEntry.java +++ b/src/org/torproject/descriptor/DirSourceEntry.java @@ -1,37 +1,96 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

+/** + * Contains details about an authority and its vote that contributed to a + * consensus. + * + * <p>A directory source entry is not a descriptor type of its own but is + * part of a network status consensus + * ({@link RelayNetworkStatusConsensus}).</p> + * + * @since 1.0.0 + */ public interface DirSourceEntry {

- /* Return the raw dir-source bytes. */ + /** + * Return the raw directory source entry bytes. + * + * @since 1.0.0 + */ public byte[] getDirSourceEntryBytes();

- /* Return the directory nickname. */ + /** + * Return the authority's nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the identity fingerprint. */ + /** + * Return a SHA-1 digest of the authority's long-term authority + * identity key used for the version 3 directory protocol, encoded as + * 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public String getIdentity();

- /* Return the hostname. */ + /** + * Return the authority's hostname. + * + * @since 1.2.0 + */ public String getHostname();

- /* Return the IP address. */ + /** + * Return the authority's primary IPv4 address in dotted-quad format. + * + * @since 1.0.0 + */ public String getIp();

- /* Return the DirPort. */ + /** + * Return the TCP port where this authority accepts directory-related + * HTTP connections. + * + * @since 1.0.0 + */ public int getDirPort();

- /* Return the ORPort. */ + /** + * Return the TCP port where this authority accepts TLS connections for + * the main OR protocol. + * + * @since 1.0.0 + */ public int getOrPort();

- /* Return whether the dir-source was created using a legacy key. */ + /** + * Return whether this directory source entry was created using a + * legacy key. + * + * @since 1.0.0 + */ public boolean isLegacy();

- /* Return the contact line. */ + /** + * Return the contact information for this authority, which may contain + * non-ASCII characters. + * + * @since 1.0.0 + */ public String getContactLine();

- /* Return the vote digest. */ + /** + * Return the SHA-1 vote digest, encoded as 40 lower-case hexadecimal + * characters. + * + * @since 1.0.0 + */ public String getVoteDigest(); }

diff --git a/src/org/torproject/descriptor/DirectoryKeyCertificate.java b/src/org/torproject/descriptor/DirectoryKeyCertificate.java index 61986cf..07211ef 100644 --- a/src/org/torproject/descriptor/DirectoryKeyCertificate.java +++ b/src/org/torproject/descriptor/DirectoryKeyCertificate.java @@ -1,45 +1,109 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

+/** + * Contains a key certificate in the version 3 directory protocol. + * + * <p>Every directory authority in the version 3 directory protocol uses + * two keys: a medium-term signing key, and a long-term authority identity + * key. (Authorities also have a relay identity key used in their role as + * a relay and by earlier versions of the directory protocol.) The + * identity key is used from time to time to sign new key certificates + * containing signing keys. The contained signing key is used to sign key + * certificates and status documents.</p> + * + * @since 1.0.0 + */ public interface DirectoryKeyCertificate extends Descriptor {

- /* Return the directory key certificate version. */ + /** + * Return the version of this descriptor, which must be 3 or higher. + * + * @since 1.0.0 + */ public int getDirKeyCertificateVersion();

- /* Return the IP address, or null if the certificate does not contain an - * address. */ + /** + * Return the authority's primary IPv4 address in dotted-quad format, + * or null if the certificate does not contain an address. + * + * @since 1.0.0 + */ public String getAddress();

- /* Return the directory port, or -1 if the certificate does not contain - * one. */ + /** + * Return the TCP port where this authority accepts directory-related + * HTTP connections, or -1 if the certificate does not contain a port. + * + * @since 1.0.0 + */ public int getPort();

- /* Return the directory identity fingerprint. */ + /** + * Return a SHA-1 digest of the authority's long-term authority + * identity key used for the version 3 directory protocol, encoded as + * 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return the directory identity key. */ + /** + * Return the authority's identity key in PEM format. + * + * @since 1.0.0 + */ public String getDirIdentityKey();

- /* Return the directory key certificate publication timestamp. */ + /** + * Return the time in milliseconds since the epoch when the authority's + * signing key and this key certificate were generated. + * + * @since 1.0.0 + */ public long getDirKeyPublishedMillis();

- /* Return the directory key certificate expiration timestamp. */ + /** + * Return the time in milliseconds since the epoch after which the + * authority's signing key is no longer valid. + * + * @since 1.0.0 + */ public long getDirKeyExpiresMillis();

- /* Return the directory signing key digest. */ + /** + * Return the authority's signing key in PEM format. + * + * @since 1.0.0 + */ public String getDirSigningKey();

- /* Return the signature of the directory identity key made using the - * directory signing key, or null if the certificate does not contain - * this signature. */ + /** + * Return the signature of the authority's identity key made using the + * authority's signing key, or null if the certificate does not contain + * such a signature. + * + * @since 1.0.0 + */ public String getDirKeyCrosscert();

- /* Return the certificate signature made using the directory identity - * key. */ + /** + * Return the certificate signature from the initial item + * "dir-key-certificate-version" until the final item + * "dir-key-certification", signed with the authority identity key. + * + * @since 1.0.0 + */ public String getDirKeyCertification();

- /* Return the calculated certificate digest. */ + /** + * Return the SHA-1 certificate digest, encoded as 40 lower-case + * hexadecimal characters. + * + * @since 1.0.0 + */ public String getCertificateDigest(); }

diff --git a/src/org/torproject/descriptor/DirectorySignature.java b/src/org/torproject/descriptor/DirectorySignature.java index ff706ea..8877a4e 100644 --- a/src/org/torproject/descriptor/DirectorySignature.java +++ b/src/org/torproject/descriptor/DirectorySignature.java @@ -1,19 +1,52 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

+/** + * Contains the signature of a network status consensus or vote. + * + * <p>A directory signature is not a descriptor type of its own but is + * part of a network status consensus + * ({@link RelayNetworkStatusConsensus}) or vote + * ({@link RelayNetworkStatusVote}).</p> + * + * @since 1.0.0 + */ public interface DirectorySignature {

- /* Return the digest algorithm, which is "sha1" by default. */ + /** + * Return the digest algorithm, which is "sha1" by default and which + * can be "sha256" or another digest algorithm. + * + * @since 1.0.0 + */ public String getAlgorithm();

- /* Return the directory identity fingerprint. */ + /** + * Return the SHA-1 digest of the authority's long-term identity key in + * the version 3 directory protocol, encoded as 40 upper-case + * hexadecimal characters. + * + * @since 1.0.0 + */ public String getIdentity();

- /* Return the directory signing key digest. */ + /** + * Return the SHA-1 digest of the authority's medium-term signing key + * in the version 3 directory protocol, encoded as 40 upper-case + * hexadecimal characters. + * + * @since 1.0.0 + */ public String getSigningKeyDigest();

- /* Return the directory signature made using the signing key. */ + /** + * Return the directory signature string made with the authority's + * identity key in the version 3 directory protocol. + * + * @since 1.0.0 + */ public String getSignature(); }

diff --git a/src/org/torproject/descriptor/ExitList.java b/src/org/torproject/descriptor/ExitList.java index c813a6b..2a5cb2e 100644 --- a/src/org/torproject/descriptor/ExitList.java +++ b/src/org/torproject/descriptor/ExitList.java @@ -1,42 +1,92 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.Map; import java.util.Set;

-/* Exit list containing all known exit scan results at a given time. */ +/** + * Contains an exit list containing the IP addresses of relays that the + * exit list service TorDNSEL found when exiting through them. + * + * @since 1.0.0 + */ public interface ExitList extends Descriptor {

+ /** + * End-of-line character expected in exit lists. + * + * @since 1.0.0 + */ public final static String EOL = "\n";

- /* Exit list entry containing results from a single exit scan. */ + /** + * Exit list entry containing results from a single exit scan. + * + * @since 1.1.0 + */ public interface Entry {

- /* Return the scanned relay's fingerprint. */ + /** + * Return the scanned relay's fingerprint, which is a SHA-1 digest of + * the relays's public identity key, encoded as 40 upper-case + * hexadecimal characters. + * + * @since 1.1.0 + */ public String getFingerprint();

- /* Return the publication time of the scanned relay's last known - * descriptor. */ + /** + * Return the time in milliseconds since the epoch when the scanned + * relay's last known descriptor was published. + * + * @since 1.1.0 + */ public long getPublishedMillis();

- /* Return the publication time of the network status that this scan - * was based on. */ + /** + * Return the time in milliseconds since the epoch when the network + * status that this scan was based on was published. + * + * @since 1.1.0 + */ public long getLastStatusMillis();

- /* Return the IP addresses that were determined in the scan. */ + /** + * Return the IP addresses that were determined in the scan with map + * keys being IPv4 addresses in dotted-quad format and map values + * being scan times in milliseconds since the epoch. + * + * @since 1.1.0 + */ public Map<String, Long> getExitAddresses(); }

- /* Return the download time of the exit list. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was downloaded. + * + * @since 1.0.0 + */ public long getDownloadedMillis();

- /* Return the unordered set of exit scan results. */ - /* Use getEntries instead. */ + /** + * Return the unordered set of exit scan results. + * + * @since 1.0.0 + * @deprecated The {@link ExitListEntry} type has been deprecated and + * superseded by {@link ExitList.Entry} which is returned by + * {@link #getEntries()}. + */ @Deprecated public Set<ExitListEntry> getExitListEntries();

- /* Return the unordered set of exit scan results. */ + /** + * Return the unordered set of exit scan results. + * + * @since 1.1.0 + */ public Set<ExitList.Entry> getEntries(); }

diff --git a/src/org/torproject/descriptor/ExitListEntry.java b/src/org/torproject/descriptor/ExitListEntry.java index 7b69483..2a3d79f 100644 --- a/src/org/torproject/descriptor/ExitListEntry.java +++ b/src/org/torproject/descriptor/ExitListEntry.java @@ -1,27 +1,55 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Exit list entry containing results from a single exit scan. */ -/* Use org.torproject.descriptor.ExitList.Entry instead. */ +/** + * Exit list entry containing results from a single exit scan. + * + * @since 1.0.0 + * @deprecated Superseded by {@link ExitList.Entry}. + */ @Deprecated public interface ExitListEntry extends ExitList.Entry {

- /* Return the scanned relay's fingerprint. */ + /** + * Return the scanned relay's fingerprint, which is a SHA-1 digest of + * the relays's public identity key, encoded as 40 upper-case + * hexadecimal characters. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return the publication time of the scanned relay's last known - * descriptor. */ + /** + * Return the time in milliseconds since the epoch when the scanned + * relay's last known descriptor was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the publication time of the network status that this scan was - * based on. */ + /** + * Return the time in milliseconds since the epoch when the network + * status that this scan was based on was published. + * + * @since 1.0.0 + */ public long getLastStatusMillis();

- /* Return the IP address that was determined in the scan. */ + /** + * Return the IPv4 address in dotted-quad format that was determined in + * the scan. + * + * @since 1.0.0 + */ public String getExitAddress();

- /* Return the scan time. */ + /** + * Return the scan time in milliseconds since the epoch. + * + * @since 1.0.0 + */ public long getScanMillis(); }

diff --git a/src/org/torproject/descriptor/ExtraInfoDescriptor.java b/src/org/torproject/descriptor/ExtraInfoDescriptor.java index ed0141d..49efbf3 100644 --- a/src/org/torproject/descriptor/ExtraInfoDescriptor.java +++ b/src/org/torproject/descriptor/ExtraInfoDescriptor.java @@ -1,322 +1,646 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.Map; import java.util.SortedMap;

-/* Contains a relay or bridge extra-info descriptor. */ +/** + * Contains a relay or sanitized bridge extra-info descriptor. + * + * <p>Relays publish extra-info descriptors as an addendum to server + * descriptors ({@link ServerDescriptor}) to report extraneous information + * to the directory authorities that clients do not need to download in + * order to function. This information primarily consists of statistics + * gathered by the relay about its usage and can take up a lot of + * descriptor space. The separation of server descriptors and extra-info + * descriptors has become less relevant with the introduction of + * microdescriptors ({@link Microdescriptor}) that are derived from server + * descriptors by the directory authority and which clients download + * instead of server descriptors, but it persists.</p> + * + * <p>Bridges publish extra-info descriptors to the bridge authority for + * the same reason, to include statistics about their usage without + * increasing the directory protocol overhead for bridge clients. In this + * case, the separation of server descriptors and extra-info descriptors + * is slightly more relevant, because there are no microdescriptors for + * bridges, so that bridge clients still download server descriptors of + * bridges they're using. Another reason is that bridges need to include + * information like details of all the transports they support in their + * descriptors, and bridge clients using one such transport are not + * supposed to learn the details of the other transports.</p> + * + * <p>It's worth noting that all contents of extra-info descriptors are + * written and signed by relays and bridges without a third party + * verifying their correctness. The (bridge) directory authorities may + * decide to exclude dishonest servers from the network statuses they + * produce, but that wouldn't be reflected in extra-info descriptors.</p> + * + * @since 1.0.0 + */ public interface ExtraInfoDescriptor extends Descriptor {

- /* Return the descriptor digest that is used to reference this - * extra-info descriptor in a server descriptor. */ + /** + * Return the SHA-1 descriptor digest, encoded as 40 lower-case (relay + * descriptors) or upper-case (bridge descriptors) hexadecimal + * characters, that is used to reference this descriptor from a server + * descriptor. + * + * @since 1.0.0 + */ public String getExtraInfoDigest();

- /* Return the base64-encoded SHA-256 descriptor digest that may be used - * to reference this extra-info descriptor in a server descriptor. */ + /** + * Return the SHA-256 descriptor digest, encoded as 43 base64 + * characters without padding characters, that may be used to reference + * this descriptor from a server descriptor. + * + * @since 1.1.0 + */ public String getExtraInfoDigestSha256();

- /* Return the relay's nickname. */ + /** + * Return the server's nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the relay's fingerprint. */ + /** + * Return a SHA-1 digest of the server's public identity key, encoded + * as 40 upper-case hexadecimal characters, that is typically used to + * uniquely identify the server. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return the publication time of this descriptor. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * and the corresponding server descriptor were generated. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the read history contained in this descriptor, or null if no - * read history is contained. */ + /** + * Return the server's history of read bytes, or null if the descriptor + * does not contain a bandwidth history; older Tor versions included + * bandwidth histories in their server descriptors + * ({@link ServerDescriptor#getReadHistory()}). + * + * @since 1.0.0 + */ public BandwidthHistory getReadHistory();

- /* Return the write history contained in this descriptor, or null if no - * read history is contained. */ + /** + * Return the server's history of written bytes, or null if the + * descriptor does not contain a bandwidth history; older Tor versions + * included bandwidth histories in their server descriptors + * ({@link ServerDescriptor#getWriteHistory()}). + * + * @since 1.0.0 + */ public BandwidthHistory getWriteHistory();

- /* Return the SHA1 digest of the GeoIP database used by this relay, or - * null if no GeoIP database digest is included. */ + /** + * Return a SHA-1 digest of the GeoIP database file used by this server + * to resolve client IP addresses to country codes, encoded as 40 + * upper-case hexadecimal characters, or null if no GeoIP database + * digest is included. + * + * @since 1.0.0 + */ public String getGeoipDbDigest();

- /* Return the SHA1 digest of the GeoIPv6 database used by this relay, or - * null if no GeoIPv6 database digest is included. */ + /** + * Return a SHA-1 digest of the GeoIPv6 database file used by this + * server to resolve client IP addresses to country codes, encoded as 40 + * upper-case hexadecimal characters, or null if no GeoIPv6 database + * digest is included. + * + * @since 1.0.0 + */ public String getGeoip6DbDigest();

- /* Return the end of the included directory request statistics interval, - * or -1 if no directory request statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * directory request statistics interval ended, or -1 if no such + * statistics are included. + * + * @since 1.0.0 + */ public long getDirreqStatsEndMillis();

- /* Return the interval length of the included directory request - * statistics in seconds, or -1 if no directory request statistics are - * included. */ + /** + * Return the interval length of the included directory request + * statistics in seconds, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public long getDirreqStatsIntervalLength();

- /* Return statistics on unique IP addresses requesting v2 network + /** + * Return statistics on unique IP addresses requesting v2 network * statuses with map keys being country codes and map values being * numbers of unique IP addresses rounded up to the nearest multiple of - * 8, or null if no such statistics are included. */ + * 8, or null if no such statistics are included (which is the case with + * recent Tor versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV2Ips();

- /* Return statistics on unique IP addresses requesting v3 network status - * consensuses with map keys being country codes and map values being - * numbers of unique IP addresses rounded up to the nearest multiple of - * 8, or null if no such statistics are included. */ + /** + * Return statistics on unique IP addresses requesting v3 network + * status consensuses of any flavor with map keys being country codes + * and map values being numbers of unique IP addresses rounded up to the + * nearest multiple of 8, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV3Ips();

- /* Return statistics on directory requests for v2 network statuses with + /** + * Return statistics on directory requests for v2 network statuses with * map keys being country codes and map values being request numbers * rounded up to the nearest multiple of 8, or null if no such - * statistics are included. */ + * statistics are included (which is the case with recent Tor + * versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV2Reqs();

- /* Return statistics on directory requests for v3 network status - * consensuses with map keys being country codes and map values being - * request numbers rounded up to the nearest multiple of 8, or null if - * no such statistics are included. */ + /** + * Return statistics on directory requests for v3 network status + * consensuses of any flavor with map keys being country codes and map + * values being request numbers rounded up to the nearest multiple of 8, + * or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV3Reqs();

- /* Return the share of requests for v2 network statuses that the - * directory expects to receive from clients, or -1.0 if no such - * statistics are included. */ + /** + * Return the share of requests for v2 network statuses that the server + * expects to receive from clients, or -1.0 if this share is not + * included (which is the case with recent Tor versions). + * + * @since 1.0.0 + */ public double getDirreqV2Share();

- /* Return the share of requests for v3 network status consensuses that - * the directory expects to receive from clients, or -1.0 if no such - * statistics are included. */ + /** + * Return the share of requests for v3 network status consensuses of + * any flavor that the server expects to receive from clients, or -1.0 + * if this share is not included (which is the case with recent Tor + * versions). + * + * @since 1.0.0 + */ public double getDirreqV3Share();

- /* Return statistics on directory request responses for v2 network + /** + * Return statistics on responses to directory requests for v2 network * statuses with map keys being response strings and map values being * response numbers rounded up to the nearest multiple of 4, or null if - * no such statistics are included. */ + * no such statistics are included (which is the case with recent Tor + * versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV2Resp();

- /* Return statistics on directory request responses for v3 network - * status consensuses with map keys being response strings and map - * values being response numbers rounded up to the nearest multiple of - * 4, or null if no such statistics are included. */ + /** + * Return statistics on responses to directory requests for v3 network + * status consensuses of any flavor with map keys being response strings + * and map values being response numbers rounded up to the nearest + * multiple of 4, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV3Resp();

- /* Return statistics on direct directory requests asking for v2 network - * statuses with map keys being statistic keys and map values being - * statistic values, or null if no such statistics are included. */ + /** + * Return statistics on directory requests for v2 network statuses to + * the server's directory port with map keys being statistic keys and + * map values being statistic values like counts or quantiles, or null + * if no such statistics are included (which is the case with recent Tor + * versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV2DirectDl();

- /* Return statistics on direct directory requests asking for v3 network - * status consensuses with map keys being statistic keys and map - * values being statistic values, or null if no such statistics are - * included. */ + /** + * Return statistics on directory requests for v3 network status + * consensuses of any flavor to the server's directory port with map + * keys being statistic keys and map values being statistic values like + * counts or quantiles, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV3DirectDl();

- /* Return statistics on tunneled directory requests asking for v2 - * network statuses with map keys being statistic keys and map values - * being statistic values, or null if no such statistics are - * included. */ + /** + * Return statistics on directory requests for v2 network statuses + * tunneled through a circuit with map keys being statistic keys and map + * values being statistic values, or null if no such statistics are + * included (which is the case with recent Tor versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV2TunneledDl();

- /* Return statistics on tunneled directory requests asking for v3 - * network status consensuses with map keys being statistic keys and map - * values being statistic values, or null if no such statistics are - * included. */ + /** + * Return statistics on directory requests for v3 network status + * consensuses of any flavor tunneled through a circuit with map keys + * being statistic keys and map values being statistic values, or null + * if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getDirreqV3TunneledDl();

- /* Return the directory request read history contained in this - * descriptor, or null if no directory request read history is - * contained. */ + /** + * Return the directory request read history contained in this + * descriptor, or null if no such history is contained. + * + * @since 1.0.0 + */ public BandwidthHistory getDirreqReadHistory();

- /* Return the directory request write history contained in this - * descriptor, or null if no directory request write history is - * contained. */ + /** + * Return the directory request write history contained in this + * descriptor, or null if no such history is contained. + * + * @since 1.0.0 + */ public BandwidthHistory getDirreqWriteHistory();

- /* Return the end of the included entry statistics interval, or -1 if no - * entry statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * entry statistics interval ended, or -1 if no such statistics are + * included. + * + * @since 1.0.0 + */ public long getEntryStatsEndMillis();

- /* Return the interval length of the included entry statistics in - * seconds, or -1 if no entry statistics are included. */ + /** + * Return the interval length of the included entry statistics in + * seconds, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public long getEntryStatsIntervalLength();

- /* Return statistics on client IP addresses with map keys being country + /** + * Return statistics on client IP addresses with map keys being country * codes and map values being the number of unique IP addresses that * have connected from that country rounded up to the nearest multiple - * of 8, or null if no entry statistics are included. */ + * of 8, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getEntryIps();

- /* Return the end of the included cell statistics interval, or -1 if no - * cell statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * cell statistics interval ended, or -1 if no such statistics are + * included. + * + * @since 1.0.0 + */ public long getCellStatsEndMillis();

- /* Return the interval length of the included cell statistics in - * seconds, or -1 if no cell statistics are included. */ + /** + * Return the interval length of the included cell statistics in + * seconds, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public long getCellStatsIntervalLength();

- /* Return the mean number of processed cells per circuit by circuit - * deciles. */ + /** + * Return the mean number of processed cells per circuit by circuit + * decile starting with the loudest decile at index 0 and the quietest + * decile at index 8, or null if no such statistics are included. + * + * @since 1.0.0 + */ public List<Integer> getCellProcessedCells();

- /* Return the mean number of cells contained in circuit queues by - * circuit deciles. */ + /** + * Return the mean number of cells contained in circuit queues by + * circuit decile starting with the loudest decile at index 0 and the + * quietest decile at index 8, or null if no such statistics are + * included. + * + * @since 1.0.0 + */ public List<Double> getCellQueuedCells();

- /* Return the mean times in milliseconds that cells spend in circuit - * queues by circuit deciles. */ + /** + * Return the mean times in milliseconds that cells spend in circuit + * queues by circuit decile starting with the loudest decile at index 0 + * and the quietest decile at index 8, or null if no such statistics are + * included. + * + * @since 1.0.0 + */ public List<Integer> getCellTimeInQueue();

- /* Return the mean number of circuits included in any of the cell - * statistics deciles, or -1 if no cell statistics are included. */ + /** + * Return the mean number of circuits included in any of the cell + * statistics deciles, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public int getCellCircuitsPerDecile();

- /* Return the end of the included statistics interval on bi-directional - * connection usage, or -1 if no such statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * statistics on bi-directional connection usage ended, or -1 if no such + * statistics are included. + * + * @since 1.0.0 + */ public long getConnBiDirectStatsEndMillis();

- /* Return the interval length of the included statistics on + /** + * Return the interval length of the included statistics on * bi-directional connection usage in seconds, or -1 if no such - * statistics are included. */ + * statistics are included. + * + * @since 1.0.0 + */ public long getConnBiDirectStatsIntervalLength();

- /* Return the number of connections on which this relay read and wrote - * less than 2 KiB/s in a 10-second interval, or -1 if no statistics on - * bi-directional connection usage are included. */ + /** + * Return the number of connections on which this server read and wrote + * less than 2 KiB/s in a 10-second interval, or -1 if no such + * statistics are included. + * + * @since 1.0.0 + */ public int getConnBiDirectBelow();

- /* Return the number of connections on which this relay read and wrote + /** + * Return the number of connections on which this server read and wrote * at least 2 KiB/s in a 10-second interval and at least 10 times more - * in read direction than in write direction, or -1 if no statistics on - * bi-directional connection usage are included. */ + * in read direction than in write direction, or -1 if no such + * statistics are included. + * + * @since 1.0.0 + */ public int getConnBiDirectRead();

- /* Return the number of connections on which this relay read and wrote + /** + * Return the number of connections on which this server read and wrote * at least 2 KiB/s in a 10-second interval and at least 10 times more - * in write direction than in read direction, or -1 if no statistics on - * bi-directional connection usage are included. */ + * in write direction than in read direction, or -1 if no such + * statistics are included. + * + * @since 1.0.0 + */ public int getConnBiDirectWrite();

- /* Return the number of connections on which this relay read and wrote + /** + * Return the number of connections on which this server read and wrote * at least 2 KiB/s in a 10-second interval but not 10 times more in - * either direction, or -1 if no statistics on bi-directional connection - * usage are included. */ + * either direction, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public int getConnBiDirectBoth();

- /* Return the end of the included exit statistics interval, or -1 if no - * exit statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * exit statistics interval ended, or -1 if no such statistics are + * included. + * + * @since 1.0.0 + */ public long getExitStatsEndMillis();

- /* Return the interval length of the included exit statistics in - * seconds, or -1 if no exit statistics are included. */ + /** + * Return the interval length of the included exit statistics in + * seconds, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public long getExitStatsIntervalLength();

- /* Return statistics on KiB written by port with map keys being ports - * (or "other") and map values being KiB rounded up to the next full - * KiB, or null if no exit statistics are included. */ + /** + * Return statistics on KiB written to streams exiting the Tor network + * by target TCP port with map keys being string representations of + * ports (or {@code "other"}) and map values being KiB rounded up to the + * next full KiB, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Long> getExitKibibytesWritten();

- /* Return statistics on KiB read by port with map keys being ports (or - * "other") and map values being KiB rounded up to the next full KiB, or - * null if no exit statistics are included. */ + /** + * Return statistics on KiB read from streams exiting the Tor network + * by target TCP port with map keys being string representations of + * ports (or {@code "other"}) and map values being KiB rounded up to the + * next full KiB, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Long> getExitKibibytesRead();

- /* Return statistics on opened exit streams with map keys being ports - * (or "other") and map values being the number of opened streams, - * rounded up to the nearest multiple of 4, or null if no exit - * statistics are included. */ + /** + * Return statistics on opened streams exiting the Tor network by + * target TCP port with map keys being string representations of ports + * (or {@code "other"}) and map values being the number of opened + * streams, rounded up to the nearest multiple of 4, or null if no such + * statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Long> getExitStreamsOpened();

- /* Return the start of the included geoip statistics, or -1 if no geoip - * statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * "geoip" statistics interval started, or -1 if no such statistics are + * included (which is the case except for very old Tor versions). + * + * @since 1.0.0 + */ public long getGeoipStartTimeMillis();

- /* Return statistics on client IP addresses with map keys being country - * codes and map values being the number of unique IP addresses that - * have connected from that country rounded up to the nearest multiple - * of 8, or null if no geoip statistics are included. */ + /** + * Return statistics on the origin of client IP addresses with map keys + * being country codes and map values being the number of unique IP + * addresses that have connected from that country between the start of + * the statistics interval and the descriptor publication time rounded + * up to the nearest multiple of 8, or null if no such statistics are + * included (which is the case except for very old Tor versions). + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getGeoipClientOrigins();

- /* Return the end of the included bridge statistics, or -1 if no bridge - * statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * bridge statistics interval ended, or -1 if no such statistics are + * included. + * + * @since 1.0.0 + */ public long getBridgeStatsEndMillis();

- /* Return the interval length of the included bridge statistics in - * seconds, or -1 if no bridge statistics are included. */ + /** + * Return the interval length of the included bridge statistics in + * seconds, or -1 if no such statistics are included. + * + * @since 1.0.0 + */ public long getBridgeStatsIntervalLength();

- /* Return statistics on client IP addresses with map keys being country - * codes and map values being the number of unique IP addresses that - * have connected from that country rounded up to the nearest multiple - * of 8, or null if no bridge statistics are included. */ + /** + * Return statistics on bridge client IP addresses by country with map + * keys being country codes and map values being the number of unique IP + * addresses that have connected from that country rounded up to the + * nearest multiple of 8, or null if no such statistics are included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getBridgeIps();

- /* Return statistics on client IP addresses with map keys being protocol - * family, e.g., "v4" or "v6", and map values being the number of unique - * IP addresses rounded up to the nearest multiple of 8, or null if no - * bridge IP version statistics are included. */ + /** + * Return statistics on bridge client IP addresses by IP version with + * map keys being protocol families, e.g., {@code "v4"} or {@code "v6"}, + * and map values being the number of unique IP addresses rounded up to + * the nearest multiple of 8, or null if no such statistics are + * included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getBridgeIpVersions();

- /* Return statistics on client IP addresses with map keys being - * pluggable transport names, e.g., "obfs2" or "obfs3" for known - * transports, "<OR>" for no transport, or "<??>" for an unknown - * transport, and map values being the number of unique IP addresses - * rounded up to the nearest multiple of 8, or null if no bridge IP - * transport statistics are included. */ + /** + * Return statistics on bridge client IP addresses by transport with + * map keys being pluggable transport names, e.g., {@code "obfs2"} or + * {@code "obfs3"} for known transports, {@code "<OR>"} for the default + * onion routing protocol, or {@code "<??>"} for an unknown transport, + * and map values being the number of unique IP addresses rounded up to + * the nearest multiple of 8, or null if no such statistics are + * included. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getBridgeIpTransports();

- /* Return the (possibly empty) list of transports supported by this - * bridge. */ + /** + * Return the (possibly empty) list of pluggable transports supported + * by this server. + * + * @since 1.0.0 + */ public List<String> getTransports();

- /* Return the end of the included hidden-service statistics, or -1 if no - * hidden-service statistics are included. */ + /** + * Return the time in milliseconds since the epoch when the included + * hidden-service statistics interval ended, or -1 if no such statistics + * are included. + * + * @since 1.1.0 + */ public long getHidservStatsEndMillis();

- /* Return the interval length of the included hidden-service statistics - * in seconds, or -1 if no hidden-service statistics are included. */ + /** + * Return the interval length of the included hidden-service statistics + * in seconds, or -1 if no such statistics are included. + * + * @since 1.1.0 + */ public long getHidservStatsIntervalLength();

- /* Return the approximate number of RELAY cells seen in either direction - * on a circuit after receiving and successfully processing a - * RENDEZVOUS1 cell, or null if no hidden-service statistics are - * included. */ + /** + * Return the approximate number of RELAY cells seen in either + * direction on a circuit after receiving and successfully processing a + * RENDEZVOUS1 cell, or null if no such statistics are included. + * + * @since 1.1.0 + */ public Double getHidservRendRelayedCells();

- /* Return the obfuscation parameters applied to the original measurement - * value of RELAY cells seen in either direction on a circuit after - * receiving and successfully processing a RENDEZVOUS1 cell, or null if - * no hidden-service statistics are included.. */ + /** + * Return the obfuscation parameters applied to the original + * measurement value of RELAY cells seen in either direction on a + * circuit after receiving and successfully processing a RENDEZVOUS1 + * cell, or null if no such statistics are included. + * + * @since 1.1.0 + */ public Map<String, Double> getHidservRendRelayedCellsParameters();

- /* Return the approximate number of unique hidden-service identities + /** + * Return the approximate number of unique hidden-service identities * seen in descriptors published to and accepted by this hidden-service - * directory, or null if no hidden-service statistics are included. */ + * directory, or null if no such statistics are included. + * + * @since 1.1.0 + */ public Double getHidservDirOnionsSeen();

- /* Return the obfuscation parameters applied to the original measurement - * value of unique hidden-service identities seen in descriptors - * published to and accepted by this hidden-service directory, or null - * if no hidden-service statistics are included. */ + /** + * Return the obfuscation parameters applied to the original + * measurement value of unique hidden-service identities seen in + * descriptors published to and accepted by this hidden-service + * directory, or null if no such statistics are included. + * + * @since 1.1.0 + */ public Map<String, Double> getHidservDirOnionsSeenParameters();

- /* Return the signature of the PKCS1-padded extra-info descriptor - * digest, or null if the descriptor doesn't contain a signature (which - * is the case in sanitized bridge descriptors). */ + /** + * Return the RSA-1024 signature of the PKCS1-padded descriptor digest, + * taken from the beginning of the router line through the newline after + * the router-signature line, or null if the descriptor doesn't contain + * a signature (which is the case in sanitized bridge descriptors). + * + * @since 1.1.0 + */ public String getRouterSignature();

- /* Return the base64-encoded Ed25519 certificate, or null if the - * descriptor doesn't contain one. */ + /** + * Return the Ed25519 certificate in PEM format, or null if the + * descriptor doesn't contain one. + * + * @since 1.1.0 + */ public String getIdentityEd25519();

- /* Return the base64-encoded Ed25519 master key, which may either be - * parsed from the optional "master-key-ed25519" line or derived from - * the (likewise optional) Ed25519 certificate following the - * "identity-ed25519" line, or null if the descriptor contains neither - * Ed25519 master key nor Ed25519 certificate. */ + /** + * Return the Ed25519 master key, encoded as 43 base64 characters + * without padding characters, which was either parsed from the optional + * {@code "master-key-ed25519"} line or derived from the (likewise + * optional) Ed25519 certificate following the + * {@code "identity-ed25519"} line, or null if the descriptor contains + * neither Ed25519 master key nor Ed25519 certificate. + * + * @since 1.1.0 + */ public String getMasterKeyEd25519();

- /* Return the base64-encoded Ed25519 signature of a SHA-256 digest of - * the entire descriptor, from the first character up to and including - * the first space after the "router-sig-ed25519" string, prefixed with - * the string "Tor router descriptor signature v1". */ + /** + * Return the Ed25519 signature of the SHA-256 digest of the entire + * descriptor, encoded as 86 base64 characters without padding + * characters, from the first character up to and including the first + * space after the {@code "router-sig-ed25519"} string, prefixed with + * the string {@code "Tor router descriptor signature v1"}. + * + * @since 1.1.0 + */ public String getRouterSignatureEd25519(); }

diff --git a/src/org/torproject/descriptor/ImplementationNotAccessibleException.java b/src/org/torproject/descriptor/ImplementationNotAccessibleException.java index fda3e24..c54e48f 100644 --- a/src/org/torproject/descriptor/ImplementationNotAccessibleException.java +++ b/src/org/torproject/descriptor/ImplementationNotAccessibleException.java @@ -1,7 +1,15 @@ -/* Copyright 2014--2015 The Tor Project +/* Copyright 2014--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

+/** + * Thrown if a descriptor source implementation class cannot be found, + * instantiated, or accessed. + * + * @see DescriptorSourceFactory + * @since 1.0.0 + */ @SuppressWarnings("serial") public class ImplementationNotAccessibleException extends RuntimeException { diff --git a/src/org/torproject/descriptor/Microdescriptor.java b/src/org/torproject/descriptor/Microdescriptor.java index 3cebeb6..f19b7df 100644 --- a/src/org/torproject/descriptor/Microdescriptor.java +++ b/src/org/torproject/descriptor/Microdescriptor.java @@ -1,57 +1,135 @@ -/* Copyright 2014--2015 The Tor Project +/* Copyright 2014--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

-/* Contains a relay microdescriptor. */ +/** + * Contains a relay microdescriptor. + * + * <p>A microdescriptor is a stripped-down version of a relay server + * descriptor ({@link RelayServerDescriptor}) generated by the directory + * authorities by extracting and/or transforming relay server descriptor + * contents following strict rules without adding the authority's opinion + * about the relay. Microdescriptors are referenced from microdescriptor + * consensuses ({@link RelayNetworkStatusConsensus}) and downloaded by + * clients to make path-selection decisions and to build circuits. + * Microdescriptors contain only the most relevant parts that clients care + * about. Microdescriptors are expected to be relatively static and only + * change about once per week.</p> + * + * @since 1.0.0 + */ public interface Microdescriptor extends Descriptor {

- /* Return the descriptor digest that is used to reference this - * microdescriptor in a network status. */ + /** + * Return the SHA-256 descriptor digest, encoded as 43 base64 + * characters without padding characters, that is used to reference this + * descriptor from a vote or microdescriptor consensus. + * + * @since 1.0.0 + */ public String getMicrodescriptorDigest();

- /* Return the onion key in PEM format. */ + /** + * Return the RSA-1024 public key in PEM format used to encrypt CREATE + * cells for this server, or null if the descriptor doesn't contain an + * onion key. + * + * @since 1.0.0 + */ public String getOnionKey();

- /* Return the ntor onion key base64 string with padding omitted, or null - * if the microdescriptor didn't contain an ntor onion key line. */ + /** + * Return the curve25519 public key, encoded as 43 base64 characters + * without padding characters, that is used for the ntor circuit + * extended handshake, or null if the descriptor didn't contain an + * ntor-onion-key line. + * + * @since 1.0.0 + */ public String getNtorOnionKey();

- /* Return the relay's additional OR addresses and ports contained in - * or-address lines, or an empty list if the microdescriptor doesn't - * contain such lines. */ + /** + * Return IP addresses and TCP ports where this server accepts TLS + * connections for the main OR protocol, or an empty list if the server + * does not support additional addresses or ports; entries are given in + * the order as they are listed in the descriptor; IPv4 addresses are + * given in dotted-quad format, IPv6 addresses use the colon-separated + * hexadecimal format surrounded by square brackets, and TCP ports are + * separated from the IP address using a colon. + * + * @since 1.0.0 + */ public List<String> getOrAddresses();

- /* Return nicknames, ($-prefixed) fingerprints, $fingerprint=nickname, - * or $fingerprint~nickname tuples contained in the family line of this - * relay, or null if the descriptor does not contain a family line. */ + /** + * Return nicknames, $-prefixed identity fingerprints, or tuples of the + * format {@code $fingerprint=nickname} or {@code $fingerprint~nickname} + * of servers contained in this server's family, or null if the + * descriptor does not contain a family line. + * + * @since 1.0.0 + */ public List<String> getFamilyEntries();

- /* Return the default policy of the port summary or null if the - * microdescriptor didn't contain a port summary line. */ + /** + * Return the default policy, {@code "accept"} or {@code "reject"}, of + * the IPv4 port summary, or null if the descriptor didn't contain an + * IPv4 exit-policy summary line which is equivalent to rejecting all + * streams to IPv4 targets. + * + * @since 1.0.0 + */ public String getDefaultPolicy();

- /* Return the port list of the port summary or null if the - * microdescriptor didn't contain a port summary line. */ + /** + * Return the port list of the IPv4 exit-policy summary, or null if the + * descriptor didn't contain an IPv4 exit-policy summary line which is + * equivalent to rejecting all streams to IPv4 targets. + * + * @since 1.0.0 + */ public String getPortList();

- /* Return the default policy of the IPv6 port summary or null if the - * microdescriptor didn't contain an IPv6 port summary line. */ + /** + * Return the default policy, {@code "accept"} or {@code "reject"}, of + * the IPv6 port summary, or null if the descriptor didn't contain an + * IPv6 exit-policy summary line which is equivalent to rejecting all + * streams to IPv6 targets. + * + * @since 1.0.0 + */ public String getIpv6DefaultPolicy();

- /* Return the port list of the IPv6 port summary or null if the - * microdescriptor didn't contain an IPv6 port summary line. */ + /** + * Return the port list of the IPv6 exit-policy summary, or null if the + * descriptor didn't contain an IPv6 exit-policy summary line which is + * equivalent to rejecting all streams to IPv6 targets. + * + * @since 1.0.0 + */ public String getIpv6PortList();

- /* Return the optional, base64-encoded RSA-1024 identity that is only + /** + * Return a SHA-1 digest of the server's RSA-1024 identity key, encoded + * as 27 base64 characters without padding characters, that is only * included to prevent collisions between microdescriptors, or null if - * no such identity is included. */ + * no such digest is included. + * + * @since 1.1.0 + */ public String getRsa1024Identity();

- /* Return the optional, base64-encoded Ed25519 identity that is only - * included to prevent collisions between microdescriptors, or null if - * no such identity is included. */ + /** + * Return a SHA-256 digest of the server's Ed25519 identity key, + * encoded as 43 base64 characters without padding characters, that is + * only included to prevent collisions between microdescriptors, or null + * if no such digest is included. + * + * @since 1.1.0 + */ public String getEd25519Identity(); }

diff --git a/src/org/torproject/descriptor/NetworkStatusEntry.java b/src/org/torproject/descriptor/NetworkStatusEntry.java index 584f07b..43b3175 100644 --- a/src/org/torproject/descriptor/NetworkStatusEntry.java +++ b/src/org/torproject/descriptor/NetworkStatusEntry.java @@ -1,84 +1,177 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.Set; import java.util.SortedSet;

-/* Status entry contained in a network status with version 2 or higher or - * in a bridge network status. */ +/** + * Contains an entry in a network status in the version 2 or 3 directory + * protocol or in a bridge network status. + * + * <p>A network status entry is not a descriptor type of its own but is + * part of a network status in the version 2 directory protocol + * ({@link RelayNetworkStatus}), a vote ({@link RelayNetworkStatusVote}) + * or flavored/unflavored consensus (@link RelayNetworkStatusConsensus}) + * in the version 3 directory protocol, or a bridge network status + * ({@link BridgeNetworkStatus}). Entries in signed directories in the + * version 1 directory protocol are represented by router status entries + * ({@link RouterStatusEntry}).</p> + * + * @since 1.0.0 + */ public interface NetworkStatusEntry {

- /* Return the raw status entry bytes. */ + /** + * Return the raw network status entry bytes. + * + * @since 1.0.0 + */ public byte[] getStatusEntryBytes();

- /* Return the relay nickname. */ + /** + * Return the server nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the relay fingerprint. */ + /** + * Return a SHA-1 digest of the server's identity key, encoded as 40 + * upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return the descriptor identity or null if the containing status is a - * microdesc consensus. */ + /** + * Return the SHA-1 digest of the server descriptor, or null if the + * containing network status does not contain server descriptor + * references, like a microdesc consensus. + * + * @since 1.0.0 + */ public String getDescriptor();

- /* Return the publication timestamp. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the IP address. */ + /** + * Return the server's primary IPv4 address in dotted-quad format. + * + * @since 1.0.0 + */ public String getAddress();

- /* Return the ORPort. */ + /** + * Return the TCP port where this server accepts TLS connections for + * the main OR protocol. + * + * @since 1.0.0 + */ public int getOrPort();

- /* Return the DirPort. */ + /** + * Return the TCP port where this server accepts directory-related HTTP + * connections. + * + * @since 1.0.0 + */ public int getDirPort();

- /* Return the (possibly empty) set of microdescriptor digest(s) if the - * containing status is a vote or microdesc consensus, or null - * otherwise. */ + /** + * Return the (possibly empty) set of microdescriptor digests if the + * containing network status is a vote or microdesc consensus, or null + * otherwise. + * + * @since 1.0.0 + */ public Set<String> getMicrodescriptorDigests();

- /* Return the relay's additional OR addresses and ports contained in - * or-address lines, or an empty list if the network status doesn't - * contain such lines. */ + /** + * Return additional IP addresses and TCP ports where this server + * accepts TLS connections for the main OR protocol, or an empty list if + * the network status doesn't contain any such additional addresses and + * ports. + * + * @since 1.0.0 + */ public List<String> getOrAddresses();

- /* Return the relay flags or null if the status entry didn't contain any - * relay flags. */ + /** + * Return the relay flags assigned to this server, or null if the + * status entry didn't contain any relay flags. + * + * @since 1.0.0 + */ public SortedSet<String> getFlags();

- /* Return the Tor software version or null if the status entry didn't - * contain a version line. */ + /** + * Return the Tor software version, or null if the status entry didn't + * contain version information. + * + * @since 1.0.0 + */ public String getVersion();

- /* Return the bandwidth weight or -1L if the status entry didn't - * contain a bandwidth line. */ + /** + * Return the bandwidth weight of this server or -1 if the status entry + * didn't contain a bandwidth line. + * + * @since 1.0.0 + */ public long getBandwidth();

- /* Return the measured bandwidth or -1L if the status entry didn't - * contain a bandwidth line or didn't contain a Measured= keyword in its - * bandwidth line. */ + /** + * Return the measured bandwidth or -1 if the status entry either + * didn't contain bandwidth information or didn't contain an indication + * that this information is based on measured bandwidth. + * + * @since 1.0.0 + */ public long getMeasured();

- /* Return whether the status entry contained an Unmeasured=1 entry in - * its bandwidth line, meaning that the bandwidth authorities didn't - * measure this relay yet. Only included in consensuses using method - * 17 or higher. */ + /** + * Return whether the status entry is yet unmeasured by the bandwidth + * authorities; only included in consensuses using method 17 or higher. + * + * @since 1.0.0 + */ public boolean getUnmeasured();

- /* Return the default policy of the port summary or null if the status - * entry didn't contain a port summary line. */ + /** + * Return the default policy of the port summary, which can be either + * {@code "accept"} or {@code "reject"}, or null if the status entry + * didn't contain an exit policy summary. + * + * @since 1.0.0 + */ public String getDefaultPolicy();

- /* Return the port list of the port summary or null if the status entry - * didn't contain a port summary line. */ + /** + * Return the list of ports or port intervals of the exit port summary, + * or null if the status entry didn't contain an exit policy summary. + * + * @since 1.0.0 + */ public String getPortList();

- /* Return the relay's base64-encoded Ed25519 master key, "none" if the - * relay doesn't have an Ed25519 identity, or null if the status entry - * didn't contain this information. Only included in votes. */ + /** + * Return the server's Ed25519 master key, encoded as 43 base64 + * characters without padding characters, "none" if the relay doesn't + * have an Ed25519 identity, or null if the status entry didn't contain + * this information or if the status is not a vote. + * + * @since 1.1.0 + */ public String getMasterKeyEd25519(); }

diff --git a/src/org/torproject/descriptor/RelayDirectory.java b/src/org/torproject/descriptor/RelayDirectory.java index 209c080..8f3e58b 100644 --- a/src/org/torproject/descriptor/RelayDirectory.java +++ b/src/org/torproject/descriptor/RelayDirectory.java @@ -1,41 +1,104 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

-/* Contains a v1 signed directory. */ +/** + * Contains a signed directory in the version 1 directory protocol. + * + * <p>Directory authorities in the (long outdated) version 1 of the + * directory protocol served signed directory documents containing a list + * of signed server descriptors ({@link ServerDescriptor}) along with + * short summaries of the status of each server + * ({@link RouterStatusEntry}).</p> + * + * <p>Clients in that version of the directory protocol would fetch this + * signed directory to get up-to-date information on the state of the + * network and be certain that the list was attested by a trusted + * directory authority.</p> + * + * <p>Signed directories in the version 1 directory protocol have first + * been superseded by network status documents in the version 2 directory + * protocol ({@link RelayNetworkStatus}) and later by network status + * consensuses ({@link RelayNetworkStatusConsensus}) in the version 3 + * directory protocol.</p> + * + * @since 1.0.0 + */ public interface RelayDirectory extends Descriptor {

- /* Return the published time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the directory signing key digest. */ + /** + * Return the RSA-1024 public key in PEM format used by this authority + * as long-term identity key and to sign network statuses, or null if + * this key is not included in the descriptor header. + * + * @since 1.0.0 + */ public String getDirSigningKey();

- /* Return recommended software versions or null if the directory doesn't - * list recommended software. */ + /** + * Return recommended Tor versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedSoftware();

- /* Return the directory signature. */ + /** + * Return the directory signature string made with the authority's + * identity key. + * + * @since 1.0.0 + */ public String getDirectorySignature();

- /* Return router status entries, one for each contained relay. */ + /** + * Return router status entries, one for each contained relay. + * + * @since 1.0.0 + */ public List<RouterStatusEntry> getRouterStatusEntries();

- /* Return a list of server descriptors contained in the signed - * directory. */ + /** + * Return a list of server descriptors contained in the signed + * directory. + * + * @since 1.0.0 + */ public List<ServerDescriptor> getServerDescriptors();

- /* Return a (very likely empty) list of exceptions from parsing the - * contained server descriptors. */ + /** + * Return a (very likely empty) list of exceptions from parsing the + * contained server descriptors. + * + * @since 1.0.0 + */ public List<Exception> getServerDescriptorParseExceptions();

- /* Return the directory nickname. */ + /** + * Return the directory nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the directory digest that the directory authority used to sign - * the directory. */ + /** + * Return the SHA-1 directory digest, encoded as 40 lower-case + * hexadecimal characters, that the directory authority used to sign the + * directory. + * + * @since 1.0.0 + */ public String getDirectoryDigest(); }

diff --git a/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java b/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java index 01e2716..73f8438 100644 --- a/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java +++ b/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java @@ -1,8 +1,20 @@ -/* Copyright 2015 The Tor Project +/* Copyright 2015--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Contains a relay extra-info descriptor. */ +/** + * Contains a relay extra-info descriptor. + * + * <p>Relay extra-info descriptors share many contents with sanitized + * bridge extra-info descriptors ({@link BridgeExtraInfoDescriptor}), + * which is why they share a common superinterface + * ({@link ExtraInfoDescriptor}). The main purpose of having two + * subinterfaces is being able to distinguish descriptor types more + * easily.</p> + * + * @since 1.1.0 + */ public interface RelayExtraInfoDescriptor extends ExtraInfoDescriptor {

} diff --git a/src/org/torproject/descriptor/RelayNetworkStatus.java b/src/org/torproject/descriptor/RelayNetworkStatus.java index acbdb90..db3ddac 100644 --- a/src/org/torproject/descriptor/RelayNetworkStatus.java +++ b/src/org/torproject/descriptor/RelayNetworkStatus.java @@ -1,68 +1,176 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.SortedMap; import java.util.SortedSet;

-/* Contains a v2 network status. */ +/** + * Contains a network status document in the version 2 directory protocol. + * + * <p>Directory authorities in the (outdated) version 2 of the directory + * protocol published signed network status documents. Each network + * status listed, for every relay in the network + * ({@link NetworkStatusEntry}): a hash of its identity key, a hash of its + * most recent server descriptor, and a summary of what the authority + * believed about its status.</p> + * + * <p>Clients would download the authorities' network status documents in + * turn, and believe statements about routers iff they were attested to by + * more than half of the authorities.</p> + * + * <p>Network status documents in the version 2 directory protocol + * supersede signed directories in the version 1 directory protocol + * ({@link RelayDirectory}) and have been superseded by network status + * consensuses ({@link RelayNetworkStatusConsensus}) in the version 3 + * directory protocol.</p> + * + * @since 1.0.0 + */ public interface RelayNetworkStatus extends Descriptor {

- /* Return the network status version. */ + /** + * Return the document format version of this descriptor which is 2. + * + * @since 1.0.0 + */ public int getNetworkStatusVersion();

- /* Return the authority's hostname. */ + /** + * Return the authority's hostname. + * + * @since 1.0.0 + */ public String getHostname();

- /* Return the authority's IP address. */ + /** + * Return the authority's primary IPv4 address in dotted-quad format, + * or null if the descriptor does not contain an address. + * + * @since 1.0.0 + */ public String getAddress();

- /* Return the authority's directory port. */ + /** + * Return the TCP port where this authority accepts directory-related + * HTTP connections, or 0 if the authority does not accept such + * connections. + * + * @since 1.0.0 + */ public int getDirport();

- /* Return the directory's signing key's fingerprint. */ + /** + * Return a SHA-1 digest of the authority's public identity key, + * encoded as 40 upper-case hexadecimal characters, which is also used + * to sign network statuses. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return the contact line. */ + /** + * Return the contact information for this authority, which may contain + * non-ASCII characters. + * + * @since 1.0.0 + */ public String getContactLine();

- /* Return the directory signing key digest. */ + /** + * Return the RSA-1024 public key in PEM format used by this authority + * as long-term identity key and to sign network statuses. + * + * @since 1.0.0 + */ public String getDirSigningKey();

- /* Return recommended server versions or null if the status doesn't - * contain recommended server versions. */ + /** + * Return recommended Tor versions for server usage, or null if the + * authority does not recommend server versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedServerVersions();

- /* Return recommended client versions or null if the status doesn't - * contain recommended client versions. */ + /** + * Return recommended Tor versions for client usage, or null if the + * authority does not recommend client versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedClientVersions();

- /* Return the published time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the set of flags that this directory assigns to relays, or - * null if the status does not contain a dir-options line. */ + /** + * Return the set of flags that this directory assigns to relays, or + * null if the status does not assign such flags. + * + * @since 1.0.0 + */ public SortedSet<String> getDirOptions();

- /* Return status entries, one for each contained relay. */ + /** + * Return status entries for each contained server, with map keys being + * SHA-1 digests of the servers' public identity keys, encoded as 40 + * upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, NetworkStatusEntry> getStatusEntries();

- /* Return whether a status entry with the given fingerprint exists. */ + /** + * Return whether a status entry with the given relay fingerprint + * (SHA-1 digest of the server's public identity key, encoded as 40 + * upper-case hexadecimal characters) exists; convenience method for + * {@code getStatusEntries().containsKey(fingerprint)}. + * + * @since 1.0.0 + */ public boolean containsStatusEntry(String fingerprint);

- /* Return a status entry by fingerprint or null if no such status entry - * exists. */ + /** + * Return a status entry by relay fingerprint (SHA-1 digest of the + * server's public identity key, encoded as 40 upper-case hexadecimal + * characters), or null if no such status entry exists; convenience + * method for {@code getStatusEntries().get(fingerprint)}. + * + * @since 1.0.0 + */ public NetworkStatusEntry getStatusEntry(String fingerprint);

- /* Return the directory nickname. */ + /** + * Return the authority's nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the directory signature. */ + /** + * Return the directory signature string made with the authority's + * identity key. + * + * @since 1.0.0 + */ public String getDirectorySignature();

- /* Return the status digest that the directory authority used to sign - * the network status. */ + /** + * Return the SHA-1 status digest, encoded as 40 lower-case hexadecimal + * characters, that the directory authority used to sign the network + * status. + * + * @since 1.0.0 + */ public String getStatusDigest(); }

diff --git a/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java b/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java index 0419acc..624f1cc 100644 --- a/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java +++ b/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java @@ -1,76 +1,201 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.SortedMap; import java.util.SortedSet;

-/* Contains a network status consensus. */ +/** + * Contains a network status consensus in the version 3 directory protocol. + * + * <p>Directory authorities in the version 3 of the directory protocol + * periodically generate a view of the current descriptors and status for + * known relays and send a signed summary of this view to the other + * authorities ({@link RelayNetworkStatusVote}). The authorities compute + * the result of this vote and sign a network status consensus containing + * the result of the vote, which is this document.</p> + * + * <p>Clients use consensus documents to find out when their list of + * relays is out-of-date by looking at the contained network status + * entries ({@link NetworkStatusEntry}). If it is, they download any + * missing server descriptors ({@link ServerDescriptor}).</p> + * + * @since 1.0.0 + */ public interface RelayNetworkStatusConsensus extends Descriptor {

- /* Return the network status version. */ + /** + * Return the document format version of this descriptor which is 3 or + * higher. + * + * @since 1.0.0 + */ public int getNetworkStatusVersion();

- /* Return the flavor name, or null if this consensus is unflavored. */ + /** + * Return the consensus flavor name, which denotes the variant of the + * original, unflavored consensus, encoded as a string of alphanumeric + * characters and dashes, or null if this descriptor is the unflavored + * consensus. + * + * @since 1.0.0 + */ public String getConsensusFlavor();

- /* Return the consensus method. */ + /** + * Return the consensus method number of this descriptor, which is the + * highest consensus method supported by more than 2/3 of voting + * authorities, or 0 if no consensus method is contained in the + * descriptor. + * + * @since 1.0.0 + */ public int getConsensusMethod();

- /* Return the valid-after time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch at which this + * descriptor became valid. + * + * @since 1.0.0 + */ public long getValidAfterMillis();

- /* Return the fresh-until time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch until which this + * descriptor is the freshest that is available. + * + * @since 1.0.0 + */ public long getFreshUntilMillis();

- /* Return the valid-until time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch until which this + * descriptor was valid. + * + * @since 1.0.0 + */ public long getValidUntilMillis();

- /* Return the VoteSeconds time in seconds. */ + /** + * Return the number of seconds that the directory authorities will + * allow to collect votes from the other authorities when producing the + * next consensus. + * + * @since 1.0.0 + */ public long getVoteSeconds();

- /* Return the DistSeconds time in seconds. */ + /** + * Return the number of seconds that the directory authorities will + * allow to collect signatures from the other authorities when producing + * the next consensus. + * + * @since 1.0.0 + */ public long getDistSeconds();

- /* Return recommended server versions or null if the consensus doesn't - * contain recommended server versions. */ + /** + * Return recommended Tor versions for server usage, or null if the + * consensus does not contain an opinion about server versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedServerVersions();

- /* Return recommended client versions or null if the consensus doesn't - * contain recommended client versions. */ + /** + * Return recommended Tor versions for client usage, or null if the + * consensus does not contain an opinion about client versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedClientVersions();

- /* Return known relay flags. */ + /** + * Return known relay flags in this descriptor that were contained in + * enough votes for this consensus to be an authoritative opinion for + * these relay flags. + * + * @since 1.0.0 + */ public SortedSet<String> getKnownFlags();

- /* Return consensus parameters or null if the consensus doesn't contain - * consensus parameters. */ + /** + * Return consensus parameters contained in this descriptor with map + * keys being case-sensitive parameter identifiers and map values being + * parameter values, or null if the consensus doesn't contain consensus + * parameters. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getConsensusParams();

- /* Return dir-source entries representing the directories of which - * votes are contained in this consensus. */ + /** + * Return directory source entries for each directory authority that + * contributed to the consensus, with map keys being SHA-1 digests of + * the authorities' identity keys in the version 3 directory protocol, + * encoded as 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, DirSourceEntry> getDirSourceEntries();

- /* Return status entries, one for each contained relay. */ + /** + * Return status entries for each contained server, with map keys being + * SHA-1 digests of the servers' public identity keys, encoded as 40 + * upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, NetworkStatusEntry> getStatusEntries();

- /* Return whether a status entry with the given fingerprint exists. */ + /** + * Return whether a status entry with the given relay fingerprint + * (SHA-1 digest of the server's public identity key, encoded as 40 + * upper-case hexadecimal characters) exists; convenience method for + * {@code getStatusEntries().containsKey(fingerprint)}. + * + * @since 1.0.0 + */ public boolean containsStatusEntry(String fingerprint);

- /* Return a status entry by fingerprint or null if no such status entry - * exists. */ + /** + * Return a status entry by relay fingerprint (SHA-1 digest of the + * server's public identity key, encoded as 40 upper-case hexadecimal + * characters), or null if no such status entry exists; convenience + * method for {@code getStatusEntries().get(fingerprint)}. + * + * @since 1.0.0 + */ public NetworkStatusEntry getStatusEntry(String fingerprint);

- /* Return directory signatures. */ + /** + * Return directory signatures of this consensus, with map keys being + * SHA-1 digests of the authorities' identity keys in the version 3 + * directory protocol, encoded as 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, DirectorySignature> getDirectorySignatures();

- /* Return bandwidth weights or null if the consensus doesn't contain - * bandwidth weights. */ + /** + * Return optional weights to be applied to router bandwidths during + * path selection with map keys being case-sensitive weight identifiers + * and map values being weight values, or null if the consensus doesn't + * contain such weights. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getBandwidthWeights();

- /* Return the consensus digest that directory authorities use to sign - * the consensus. */ + /** + * Return the SHA-1 digest of this consensus, encoded as 40 upper-case + * hexadecimal characters that directory authorities use to sign the + * consensus. + * + * @since 1.0.0 + */ public String getConsensusDigest(); }

diff --git a/src/org/torproject/descriptor/RelayNetworkStatusVote.java b/src/org/torproject/descriptor/RelayNetworkStatusVote.java index f4fad2a..5e0c7cd 100644 --- a/src/org/torproject/descriptor/RelayNetworkStatusVote.java +++ b/src/org/torproject/descriptor/RelayNetworkStatusVote.java @@ -1,147 +1,379 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.SortedMap; import java.util.SortedSet;

-/* Contains a network status vote. */ +/** + * Contains a network status vote in the version 3 directory protocol. + * + * <p>Directory authorities in the version 3 of the directory protocol + * periodically generate a view of the current descriptors and status for + * known relays and send a signed summary of this view to the other + * authorities, which is this document. The authorities compute the + * result of this vote and sign a network status consensus containing the + * result of the vote ({@link RelayNetworkStatusConsensus}).</p> + * + * @since 1.0.0 + */ public interface RelayNetworkStatusVote extends Descriptor {

- /* Return the network status version. */ + /** + * Return the document format version of this descriptor which is 3 or + * higher. + * + * @since 1.0.0 + */ public int getNetworkStatusVersion();

- /* Return the consensus method. */ + /** + * Return the list of consensus method numbers supported by this + * authority, or null if the descriptor doesn't say so, which would mean + * that only method 1 is supported. + * + * @since 1.0.0 + */ public List<Integer> getConsensusMethods();

- /* Return the publication time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * was published. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the valid-after time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch at which the + * consensus is supposed to become valid. + * + * @since 1.0.0 + */ public long getValidAfterMillis();

- /* Return the fresh-until time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch until which the + * consensus is supposed to be the freshest that is available. + * + * @since 1.0.0 + */ public long getFreshUntilMillis();

- /* Return the valid-until time in milliseconds. */ + /** + * Return the time in milliseconds since the epoch until which the + * consensus is supposed to be valid. + * + * @since 1.0.0 + */ public long getValidUntilMillis();

- /* Return the VoteSeconds time in seconds. */ + /** + * Return the number of seconds that the directory authorities will + * allow to collect votes from the other authorities when producing the + * next consensus. + * + * @since 1.0.0 + */ public long getVoteSeconds();

- /* Return the DistSeconds time in seconds. */ + /** + * Return the number of seconds that the directory authorities will + * allow to collect signatures from the other authorities when producing + * the next consensus. + * + * @since 1.0.0 + */ public long getDistSeconds();

- /* Return recommended server versions or null if the authority doesn't - * recommend server versions. */ + /** + * Return recommended Tor versions for server usage, or null if the + * authority does not recommend server versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedServerVersions();

- /* Return recommended client versions or null if the authority doesn't - * recommend server versions. */ + /** + * Return recommended Tor versions for client usage, or null if the + * authority does not recommend client versions. + * + * @since 1.0.0 + */ public List<String> getRecommendedClientVersions();

- /* Return known relay flags. */ + /** + * Return known relay flags by this authority. + * + * @since 1.0.0 + */ public SortedSet<String> getKnownFlags();

- /* Return the minimum uptime in seconds that this authority requires for - * assigning the Stable flag, or -1 if the authority doesn't report this - * value. */ + /** + * Return the minimum uptime in seconds that this authority requires + * for assigning the Stable flag, or -1 if the authority doesn't report + * this value. + * + * @since 1.0.0 + */ public long getStableUptime();

- /* Return the minimum MTBF (mean time between failure) that this + /** + * Return the minimum MTBF (mean time between failure) that this * authority requires for assigning the Stable flag, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.0.0 + */ public long getStableMtbf();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Fast flag, or -1 if the authority doesn't report this - * value. */ + * value. + * + * @since 1.0.0 + */ public long getFastBandwidth();

- /* Return the minimum WFU (weighted fractional uptime) in percent that - * this authority requires for assigning the Guard flag, or -1.0 if the - * authority doesn't report this value. */ + /** + * Return the minimum WFU (weighted fractional uptime) in percent that + * this authority requires for assigning the Guard flag, or -1 if the + * authority doesn't report this value. + * + * @since 1.0.0 + */ public double getGuardWfu();

- /* Return the minimum weighted time in seconds that this authority needs - * to know about a relay before assigning the Guard flag, or -1 if the - * authority doesn't report this information. */ + /** + * Return the minimum weighted time in seconds that this authority + * needs to know about a relay before assigning the Guard flag, or -1 if + * the authority doesn't report this information. + * + * @since 1.0.0 + */ public long getGuardTk();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Guard flag if exits can be guards, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.0.0 + */ public long getGuardBandwidthIncludingExits();

- /* Return the minimum bandwidth that this authority requires for + /** + * Return the minimum bandwidth that this authority requires for * assigning the Guard flag if exits can not be guards, or -1 if the - * authority doesn't report this value. */ + * authority doesn't report this value. + * + * @since 1.0.0 + */ public long getGuardBandwidthExcludingExits();

- /* Return 1 if the authority has measured enough MTBF info to use the + /** + * Return 1 if the authority has measured enough MTBF info to use the * MTBF requirement instead of the uptime requirement for assigning the * Stable flag, 0 if not, or -1 if the authority doesn't report this - * information. */ + * information. + * + * @since 1.0.0 + */ public int getEnoughMtbfInfo();

- /* Return 1 if the authority has enough measured bandwidths that it'll + /** + * Return 1 if the authority has enough measured bandwidths that it'll * ignore the advertised bandwidth claims of routers without measured * bandwidth, 0 if not, or -1 if the authority doesn't report this - * information. */ + * information. + * + * @since 1.1.0 + */ public int getIgnoringAdvertisedBws();

- /* Return consensus parameters. */ + /** + * Return consensus parameters contained in this descriptor with map + * keys being case-sensitive parameter identifiers and map values being + * parameter values, or null if the authority doesn't include consensus + * parameters in its vote. + * + * @since 1.0.0 + */ public SortedMap<String, Integer> getConsensusParams();

- /* Return the directory nickname. */ + /** + * Return the authority's nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the directory identity. */ + /** + * Return a SHA-1 digest of the authority's long-term authority + * identity key used for the version 3 directory protocol, encoded as + * 40 upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public String getIdentity();

- /* Return the hostname. */ + /** + * Return the authority's hostname. + * + * @since 1.2.0 + */ public String getHostname();

- /* Return the IP address. */ + /** + * Return the authority's primary IPv4 address in dotted-quad format, + * or null if the descriptor does not contain an address. + * + * @since 1.0.0 + */ public String getAddress();

- /* Return the DiRPort. */ + /** + * Return the TCP port where this authority accepts directory-related + * HTTP connections, or 0 if the authority does not accept such + * connections. + * + * @since 1.0.0 + */ public int getDirport();

- /* Return the ORPort. */ + /** + * Return the TCP port where this authority accepts TLS connections for + * the main OR protocol, or 0 if the authority does not accept such + * connections. + * + * @since 1.0.0 + */ public int getOrport();

- /* Return the contact line. */ + /** + * Return the contact information for this authority, which may contain + * non-ASCII characters, or null if no contact information is included + * in the descriptor. + * + * @since 1.0.0 + */ public String getContactLine();

- /* Return the directory key certificate version. */ + /** + * Return the version of the directory key certificate used by this + * authority, which must be 3 or higher. + * + * @since 1.0.0 + */ public int getDirKeyCertificateVersion();

- /* Return the legacy dir key or null if the directory authority does not - * use a legacy dir key. */ + /** + * Return the SHA-1 digest for an obsolete authority identity key still + * used by this authority to keep older clients working, or null if this + * authority does not use such a key. + * + * @since 1.0.0 + */ public String getLegacyDirKey();

- /* Return the directory key publication timestamp. */ + /** + * Return the authority's identity key in PEM format. + * + * @since 1.2.0 + */ + public String getDirIdentityKey(); + + /** + * Return the time in milliseconds since the epoch when the authority's + * signing key and corresponding key certificate were generated. + * + * @since 1.0.0 + */ public long getDirKeyPublishedMillis();

- /* Return the directory key expiration timestamp. */ + /** + * Return the time in milliseconds since the epoch after which the + * authority's signing key is no longer valid. + * + * @since 1.0.0 + */ public long getDirKeyExpiresMillis();

- /* Return the signing key digest. */ + /** + * Return the authority's signing key in PEM format. + * + * @since 1.2.0 + */ + public String getDirSigningKey(); + + /** + * Return the SHA-1 digest of the authority's signing key, encoded as + * 40 upper-case hexadecimal characters, or null if this digest cannot + * be obtained from the directory signature. + * + * @since 1.0.0 + */ public String getSigningKeyDigest();

- /* Return status entries, one for each contained relay. */ + /** + * Return the signature of the authority's identity key made using the + * authority's signing key, or null if the vote does not contain such a + * signature. + * + * @since 1.2.0 + */ + public String getDirKeyCrosscert(); + + /** + * Return the certificate signature from the initial item + * "dir-key-certificate-version" until the final item + * "dir-key-certification", signed with the authority identity key. + * + * @since 1.2.0 + */ + public String getDirKeyCertification(); + + /** + * Return status entries for each contained server, with map keys being + * SHA-1 digests of the servers' public identity keys, encoded as 40 + * upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public SortedMap<String, NetworkStatusEntry> getStatusEntries();

- /* Return whether a status entry with the given fingerprint exists. */ + /** + * Return whether a status entry with the given relay fingerprint + * (SHA-1 digest of the server's public identity key, encoded as 40 + * upper-case hexadecimal characters) exists; convenience method for + * {@code getStatusEntries().containsKey(fingerprint)}. + * + * @since 1.0.0 + */ public boolean containsStatusEntry(String fingerprint);

- /* Return a status entry by fingerprint or null if no such status entry - * exists. */ + /** + * Return a status entry by relay fingerprint (SHA-1 digest of the + * server's public identity key, encoded as 40 upper-case hexadecimal + * characters), or null if no such status entry exists; convenience + * method for {@code getStatusEntries().get(fingerprint)}. + * + * @since 1.0.0 + */ public NetworkStatusEntry getStatusEntry(String fingerprint);

- /* Return directory signatures. */ + /** + * Return the directory signature of this vote, with the single map key + * being the SHA-1 digest of the authority's identity key in the version + * 3 directory protocol, encoded as 40 upper-case hexadecimal + * characters. + * + * @since 1.0.0 + */ public SortedMap<String, DirectorySignature> getDirectorySignatures(); }

diff --git a/src/org/torproject/descriptor/RelayServerDescriptor.java b/src/org/torproject/descriptor/RelayServerDescriptor.java index 402ddfc..6ef3140 100644 --- a/src/org/torproject/descriptor/RelayServerDescriptor.java +++ b/src/org/torproject/descriptor/RelayServerDescriptor.java @@ -1,8 +1,19 @@ -/* Copyright 2015 The Tor Project +/* Copyright 2015--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Contains a relay server descriptor. */ +/** + * Contains a relay server descriptor. + * + * <p>Relay server descriptors share many contents with sanitized bridge + * server descriptors ({@link BridgeServerDescriptor}), which is why they + * share a common superinterface ({@link ServerDescriptor}). The main + * purpose of having two subinterfaces is being able to distinguish + * descriptor types more easily.</p> + * + * @since 1.1.0 + */ public interface RelayServerDescriptor extends ServerDescriptor {

} diff --git a/src/org/torproject/descriptor/RouterStatusEntry.java b/src/org/torproject/descriptor/RouterStatusEntry.java index 978e6e1..f9a56db 100644 --- a/src/org/torproject/descriptor/RouterStatusEntry.java +++ b/src/org/torproject/descriptor/RouterStatusEntry.java @@ -1,20 +1,51 @@ -/* Copyright 2012--2015 The Tor Project +/* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

-/* Status entry contained in a v1 signed directory. */ +/** + * Contains a router status entry contained in a signed directory in the + * version 1 directory protocol. + * + * <p>Directory authorities in the (long outdated) version 1 of the + * directory protocol included router status entries with short summaries + * of the status of each server in the signed directories they produced + * ({@link RelayDirectory}). These entries contained references to server + * descriptors published by relays together with the authorities' opinion + * on whether relays were verified and live.</p> + * + * @since 1.0.0 + */ public interface RouterStatusEntry {

- /* Return the relay nickname, or null if the relay is unverified. */ + /** + * Return the relay nickname consisting of 1 to 19 alphanumeric + * characters, or null if the relay is unverified. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the relay fingerprint. */ + /** + * Return a SHA-1 digest of the relay's identity key, encoded as 40 + * upper-case hexadecimal characters. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return whether the relay is verified. */ + /** + * Return whether the relay is verified. + * + * @since 1.0.0 + */ public boolean isVerified();

- /* Return whether the relay is live. */ + /** + * Return whether the relay is live. + * + * @since 1.0.0 + */ public boolean isLive(); }

diff --git a/src/org/torproject/descriptor/ServerDescriptor.java b/src/org/torproject/descriptor/ServerDescriptor.java index 49eaa92..17c7e82 100644 --- a/src/org/torproject/descriptor/ServerDescriptor.java +++ b/src/org/torproject/descriptor/ServerDescriptor.java @@ -1,195 +1,427 @@ -/* Copyright 2011--2015 The Tor Project +/* Copyright 2011--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List;

-/* Contains a relay or bridge server descriptor. */ +/** + * Contains a relay or sanitized bridge server descriptor. + * + * <p>Relays publish server descriptors to the directory authorities to + * register in the network. Server descriptors contain information about + * the capabilities of a server, like their exit policy, that clients use + * to select servers for their circuits (along with information provided + * by directory authorities on reachability, stability, and capacity of + * servers). Server descriptors also contain network addresses and + * cryptographic material that clients use to build circuits.</p> + * + * <p>Prior to the introduction of microdescriptors + * ({@link Microdescriptor}), the directory authorities included + * cryptographic digests of server descriptors in network statuses + * ({@link RelayNetworkStatusConsensus}) and clients downloaded all + * referenced server descriptors. Nowadays, the directory authorities + * derive microdescriptors from server descriptors and reference those + * in network statuses, and clients only download microdescriptors instead + * of server descriptors.</p> + * + * <p>Bridges publish server descriptors to the bridge directory + * authority, also to announce themselves in the network. The bridge + * directory authority compiles a list of available bridges + * ({@link BridgeNetworkStatus}) for the bridge distribution service + * BridgeDB. There are no microdescriptors for bridges, so that bridge + * clients still rely on downloading bridge server descriptors directly + * from the bridge they're connecting to.</p> + * + * <p>It's worth noting that all contents of server descriptors are + * written and signed by relays and bridges without a third party + * verifying their correctness. The (bridge) directory authorities may + * decide to exclude dishonest servers from the network statuses they + * produce, but that wouldn't be reflected in server descriptors.</p> + * + * @since 1.0.0 + */ public interface ServerDescriptor extends Descriptor {

- /* Return the descriptor digest that is used to reference this server - * descriptor in a network status. */ + /** + * Return the SHA-1 descriptor digest, encoded as 40 lower-case (relay + * descriptors) or upper-case (bridge descriptors) hexadecimal + * characters, that is used to reference this descriptor from a network + * status descriptor. + * + * @since 1.0.0 + */ public String getServerDescriptorDigest();

- /* Return the base64-encoded SHA-256 descriptor digest that may be used - * to reference this server descriptor in a network status. */ + /** + * Return the SHA-256 descriptor digest, encoded as 43 base64 + * characters without padding characters, that may be used to reference + * this server descriptor from a network status descriptor. + * + * @since 1.1.0 + */ public String getServerDescriptorDigestSha256();

- /* Return the relay's nickname. */ + /** + * Return the server's nickname consisting of 1 to 19 alphanumeric + * characters. + * + * @since 1.0.0 + */ public String getNickname();

- /* Return the relay's IPv4 address in dotted-quad format. */ + /** + * Return the server's primary IPv4 address in dotted-quad format. + * + * @since 1.0.0 + */ public String getAddress();

- /* Return the relay's OR port. */ + /** + * Return the TCP port where this server accepts TLS connections for + * the main OR protocol, or 0 if the server does not accept such + * connections. + * + * @since 1.0.0 + */ public int getOrPort();

- /* Return the relay's SOCKS port which should always be 0. */ + /** + * Return the TCP port where this server accepts SOCKS connections, + * which is deprecated and should always be 0. + * + * @since 1.0.0 + */ public int getSocksPort();

- /* Return the relay's directory port. */ + /** + * Return the TCP port where this server accepts directory-related HTTP + * connections, or 0 if the server does not accept such connections. + * + * @since 1.0.0 + */ public int getDirPort();

- /* Return the relay's additional OR addresses and ports contained in - * or-address lines, or an empty list if the descriptor doesn't contain - * such lines. */ + /** + * Return IP addresses and TCP ports where this server accepts TLS + * connections for the main OR protocol, or an empty list if the server + * does not support additional addresses or ports; entries are given in + * the order as they are listed in the descriptor; IPv4 addresses are + * given in dotted-quad format, IPv6 addresses use the colon-separated + * hexadecimal format surrounded by square brackets, and TCP ports are + * separated from the IP address using a colon. + * + * @since 1.0.0 + */ public List<String> getOrAddresses();

- /* Return the average bandwidth in bytes per second that the relay is - * willing to sustain over long periods. */ + /** + * Return the average bandwidth in bytes per second that the server is + * willing to sustain over long periods. + * + * @since 1.0.0 + */ public int getBandwidthRate();

- /* Return the burst bandwidth in bytes per second that the relay is - * willing to sustain in very short intervals. */ + /** + * Return the burst bandwidth in bytes per second that the server is + * willing to sustain in very short intervals. + * + * @since 1.0.0 + */ public int getBandwidthBurst();

- /* Return the observed bandwidth in bytes per second as an estimate of - * the capacity that the relay can handle, or -1 if the descriptor + /** + * Return the observed bandwidth in bytes per second as an estimate of + * the capacity that the server can handle, or -1 if the descriptor * doesn't contain an observed bandwidth value (which is the case for - * Tor versions 0.0.8 or older). */ + * Tor 0.0.8 or older). + * + * @since 1.0.0 + */ public int getBandwidthObserved();

- /* Return the platform string containing the Tor software version and - * the operating system, or null if this descriptor does not contain a - * platform line. */ + /** + * Return a human-readable string describing the Tor software version + * and the operating system of this server, which may contain non-ASCII + * characters, typically written as {@code "Tor $version on $system"}, + * or null if this descriptor does not contain a platform line. + * + * @since 1.0.0 + */ public String getPlatform();

- /* Return the time when this descriptor and the corresponding extra-info - * document was generated. */ + /** + * Return the time in milliseconds since the epoch when this descriptor + * and the corresponding extra-info descriptor were generated. + * + * @since 1.0.0 + */ public long getPublishedMillis();

- /* Return the relay fingerprint, or null if this descriptor does not - * contain a fingerprint line. */ + /** + * Return a SHA-1 digest of the server's public identity key, encoded + * as 40 upper-case hexadecimal characters (without spaces after every 4 + * characters as opposed to the encoding in the descriptor), that is + * typically used to uniquely identify the server, or null if this + * descriptor does not contain a fingerprint line. + * + * @since 1.0.0 + */ public String getFingerprint();

- /* Return whether the relay was hibernating when this descriptor was - * published. */ + /** + * Return whether the server was hibernating when this descriptor was + * published and should not be used to build circuits. + * + * @since 1.0.0 + */ public boolean isHibernating();

- /* Return the number of seconds that this relay has been running (which - * might even be negative in a few descriptors due to a bug that was - * fixed in 0.1.2.7-alpha), or null if the descriptor does not contain - * an uptime line. */ + /** + * Return the number of seconds that the server process has been + * running (which might even be negative in a few descriptors due to a + * bug that was fixed in Tor 0.1.2.7-alpha), or null if the descriptor + * does not contain an uptime line. + * + * @since 1.0.0 + */ public Long getUptime();

- /* Return the onion key in PEM format, or null if the descriptor - * doesn't contain a signing key (which is the case in sanitized bridge - * descriptors). */ + /** + * Return the RSA-1024 public key in PEM format used to encrypt CREATE + * cells for this server, or null if the descriptor doesn't contain an + * onion key (which is the case in sanitized bridge descriptors). + * + * @since 1.0.0 + */ public String getOnionKey();

- /* Return the signing key in PEM format, or null if the descriptor - * doesn't contain a signing key (which is the case in sanitized bridge - * descriptors). */ + /** + * Return the RSA-1024 public key in PEM format used by this server as + * long-term identity key, or null if the descriptor doesn't contain a + * signing key (which is the case in sanitized bridge descriptors). + * + * @since 1.0.0 + */ public String getSigningKey();

- /* Return the relay's exit policy consisting of one or more accept or - * reject lines. */ + /** + * Return the server's exit policy consisting of one or more accept or + * reject rules that the server follows when deciding whether to allow a + * new stream to a given IP address and TCP port. + * + * @since 1.0.0 + */ public List<String> getExitPolicyLines();

- /* Return the signature of the PKCS1-padded server descriptor digest, or - * null if the descriptor doesn't contain a signature (which is the case - * in sanitized bridge descriptors). */ + /** + * Return the RSA-1024 signature of the PKCS1-padded descriptor digest, + * taken from the beginning of the router line through the newline after + * the router-signature line, or null if the descriptor doesn't contain + * a signature (which is the case in sanitized bridge descriptors). + * + * @since 1.0.0 + */ public String getRouterSignature();

- /* Return the contact information for this relay, or null if no contact - * information is included in the descriptor. */ + /** + * Return the contact information for this server, which may contain + * non-ASCII characters, or null if no contact information is included + * in the descriptor. + * + * @since 1.0.0 + */ public String getContact();

- /* Return nicknames, ($-prefixed) fingerprints, $fingerprint=nickname, - * or $fingerprint~nickname tuples contained in the family line of this - * relay, or null if the descriptor does not contain a family line. */ + /** + * Return nicknames, $-prefixed identity fingerprints, or tuples of the + * format {@code $fingerprint=nickname} or {@code $fingerprint~nickname} + * of servers contained in this server's family, or null if the + * descriptor does not contain a family line. + * + * @since 1.0.0 + */ public List<String> getFamilyEntries();

- /* Return the relay's read history. (Current Tor versions include their - * bandwidth histories in their extra-info descriptors, not in their - * server descriptors.) */ + /** + * Return the server's history of read bytes, or null if the descriptor + * does not contain a bandwidth history; current Tor versions include + * bandwidth histories in their extra-info descriptors + * ({@link ExtraInfoDescriptor#getReadHistory()}), not in their server + * descriptors. + * + * @since 1.0.0 + */ public BandwidthHistory getReadHistory();

- /* Return the relay's write history. (Current Tor versions include - * their bandwidth histories in their extra-info descriptors, not in - * their server descriptors.) */ + /** + * Return the server's history of written bytes, or null if the + * descriptor does not contain a bandwidth history; current Tor versions + * include bandwidth histories in their extra-info descriptors + * ({@link ExtraInfoDescriptor#getWriteHistory()}), not in their server + * descriptors. + * + * @since 1.0.0 + */ public BandwidthHistory getWriteHistory();

- /* Return true if the relay uses the enhanced DNS logic, or false if + /** + * Return true if the server uses the enhanced DNS logic, or false if * doesn't use it or doesn't include an eventdns line in its - * descriptor. */ + * descriptor; current Tor versions should be presumed to have the evdns + * backend. + * + * @since 1.0.0 + */ public boolean getUsesEnhancedDnsLogic();

- /* Return whether this relay is a directory cache that provides - * extra-info descriptors. */ + /** + * Return whether this server is a directory cache that provides + * extra-info descriptors. + * + * @since 1.0.0 + */ public boolean getCachesExtraInfo();

- /* Return the digest of the relay's extra-info descriptor, or null if - * the relay did not upload a corresponding extra-info descriptor. */ + /** + * Return the SHA-1 digest of the server's extra-info descriptor, + * encoded as 40 upper-case hexadecimal characters, or null if the + * server did not upload a corresponding extra-info descriptor. + * + * @since 1.0.0 + */ public String getExtraInfoDigest();

- /* Return the base64-encoded SHA-256 digest of the extra-info descriptor - * referenced from this server descriptor, or null if the relay either - * did not upload a corresponding extra-info descriptor or did not refer - * to it using a SHA-256 digest. */ + /** + * Return the SHA-256 digest of the server's extra-info descriptor, + * encoded as 43 base64 characters without padding characters, or null + * if the server either did not upload a corresponding extra-info + * descriptor or did not refer to it using a SHA-256 digest. + * + * @since 1.1.0 + */ public String getExtraInfoDigestSha256();

- /* Return the hidden service descriptor version(s) that this relay - * stores and serves, or null if it doesn't store and serve any hidden - * service descriptors. */ + /** + * Return the list of hidden service descriptor version numbers that + * this server stores and serves, or null if it doesn't store and serve + * any hidden service descriptors. + * + * @since 1.0.0 + */ public List<Integer> getHiddenServiceDirVersions();

- /* Return the list of link protocol versions that this relay - * supports. */ + /** + * Return the list of link protocol versions that this server + * supports. + * + * @since 1.0.0 + */ public List<Integer> getLinkProtocolVersions();

- /* Return the list of circuit protocol versions that this relay - * supports. */ + /** + * Return the list of circuit protocol versions that this server + * supports. + * + * @since 1.0.0 + */ public List<Integer> getCircuitProtocolVersions();

- /* Return whether this relay allows single-hop circuits to make exit - * connections. */ + /** + * Return whether this server allows single-hop circuits to make exit + * connections. + * + * @since 1.0.0 + */ public boolean getAllowSingleHopExits();

- /* Return the default policy of the IPv6 port summary or null if the - * server descriptor didn't contain an IPv6 port summary line. */ + /** + * Return the default policy, {@code "accept"} or {@code "reject"}, of + * the IPv6 port summary, or null if the descriptor didn't contain an + * IPv6 exit-policy summary line which is equivalent to rejecting all + * streams to IPv6 targets. + * + * @since 1.0.0 + */ public String getIpv6DefaultPolicy();

- /* Return the port list of the IPv6 port summary or null if the server - * descriptor didn't contain an IPv6 port summary line. */ + /** + * Return the port list of the IPv6 exit-policy summary, or null if the + * descriptor didn't contain an IPv6 exit-policy summary line which is + * equivalent to rejecting all streams to IPv6 targets. + * + * @since 1.0.0 + */ public String getIpv6PortList();

- /* Return the ntor onion key base64 string with padding omitted, or null - * if the server descriptors didn't contain an ntor onion key line. */ + /** + * Return the curve25519 public key, encoded as 43 base64 characters + * without padding characters, that is used for the ntor circuit + * extended handshake, or null if the descriptor didn't contain an + * ntor-onion-key line. */ public String getNtorOnionKey();

- /* Return the base64-encoded Ed25519 certificate, or null if the - * descriptor doesn't contain one. */ + /** + * Return the Ed25519 certificate in PEM format, or null if the + * descriptor doesn't contain one. + * + * @since 1.1.0 + */ public String getIdentityEd25519();

- /* Return the base64-encoded Ed25519 master key, which may either be - * parsed from the optional "master-key-ed25519" line or derived from - * the (likewise optional) Ed25519 certificate following the - * "identity-ed25519" line, or null if the descriptor contains neither - * Ed25519 master key nor Ed25519 certificate. */ + /** + * Return the Ed25519 master key, encoded as 43 base64 characters + * without padding characters, which was either parsed from the optional + * {@code "master-key-ed25519"} line or derived from the (likewise + * optional) Ed25519 certificate following the + * {@code "identity-ed25519"} line, or null if the descriptor contains + * neither Ed25519 master key nor Ed25519 certificate. + * + * @since 1.1.0 + */ public String getMasterKeyEd25519();

- /* Return the base64-encoded Ed25519 signature of a SHA-256 digest of - * the entire descriptor, from the first character up to and including - * the first space after the "router-sig-ed25519" string, prefixed with - * the string "Tor router descriptor signature v1". */ + /** + * Return the Ed25519 signature of the SHA-256 digest of the entire + * descriptor, encoded as 86 base64 characters without padding + * characters, from the first character up to and including the first + * space after the {@code "router-sig-ed25519"} string, prefixed with + * the string {@code "Tor router descriptor signature v1"}. + * + * @since 1.1.0 + */ public String getRouterSignatureEd25519();

- /* Return an RSA signature, generated using the onion-key, that proves - * that the party creating the descriptor had control over the secret - * key corresponding to the onion-key, or null if the descriptor does - * not contain such a signature. */ + /** + * Return an RSA-1024 signature in PEM format, generated using the + * server's onion key, that proves that the party creating the + * descriptor had control over the private key corresponding to the + * onion key, or null if the descriptor does not contain such a + * signature. + * + * @since 1.1.0 + */ public String getOnionKeyCrosscert();

- /* Return an Ed25519 signature, generated using the ntor-onion-key, that - * proves that the party creating the descriptor had control over the - * secret key corresponding to the ntor-onion-key, or null if the - * descriptor does not contain such a signature. */ + /** + * Return an Ed25519 signature in PEM format, generated using the + * server's ntor onion key, that proves that the party creating the + * descriptor had control over the private key corresponding to the ntor + * onion key, or null if the descriptor does not contain such a + * signature. + * + * @since 1.1.0 + */ public String getNtorOnionKeyCrosscert();

- /* Return the sign of the Ed25519 public key corresponding to the ntor + /** + * Return the sign of the Ed25519 public key corresponding to the ntor * onion key as 0 or 1, or -1 if the descriptor does not contain this - * information. */ + * information. + * + * @since 1.1.0 + */ public int getNtorOnionKeyCrosscertSign(); }

diff --git a/src/org/torproject/descriptor/TorperfResult.java b/src/org/torproject/descriptor/TorperfResult.java index 9c47a61..188200b 100644 --- a/src/org/torproject/descriptor/TorperfResult.java +++ b/src/org/torproject/descriptor/TorperfResult.java @@ -1,97 +1,215 @@ /* Copyright 2012--2016 The Tor Project * See LICENSE for licensing information */ + package org.torproject.descriptor;

import java.util.List; import java.util.SortedMap;

+/** + * Contains performance measurement results from making simple HTTP + * requests over the Tor network. + * + * <p>The performance measurement service Torperf publishes performance + * data from making simple HTTP requests over the Tor network. Torperf + * uses a trivial SOCKS client to download files of various sizes over the + * Tor network and notes how long substeps take.</p> + * + * @since 1.0.0 + */ public interface TorperfResult extends Descriptor {

- /* Return all unrecognized keys together with their values, or null if - * all keys were recognized. */ + /** + * Return all unrecognized keys together with their values, or null if + * all keys were recognized. + * + * @since 1.2.0 + */ public SortedMap<String, String> getUnrecognizedKeys();

- /* Return the configured name of the data source. */ + /** + * Return the configured name of the data source. + * + * @since 1.0.0 + */ public String getSource();

- /* Return the configured file size in bytes. */ + /** + * Return the configured file size in bytes. + * + * @since 1.0.0 + */ public int getFileSize();

- /* Return the time when the connection process starts. */ + /** + * Return the time in milliseconds since the epoch when the connection + * process started. + * + * @since 1.0.0 + */ public long getStartMillis();

- /* Return the time when the socket was created. */ + /** + * Return the time in milliseconds since the epoch when the socket was + * created. + * + * @since 1.0.0 + */ public long getSocketMillis();

- /* Return the time when the socket was connected. */ + /** + * Return the time in milliseconds since the epoch when the socket was + * connected. + * + * @since 1.0.0 + */ public long getConnectMillis();

- /* Return the time when SOCKS 5 authentication methods have been - * negotiated. */ + /** + * Return the time in milliseconds since the epoch when SOCKS 5 + * authentication methods have been negotiated. + * + * @since 1.0.0 + */ public long getNegotiateMillis();

- /* Return the time when the SOCKS request was sent. */ + /** + * Return the time in milliseconds since the epoch when the SOCKS + * request was sent. + * + * @since 1.0.0 + */ public long getRequestMillis();

- /* Return the time when the SOCKS response was received. */ + /** + * Return the time in milliseconds since the epoch when the SOCKS + * response was received. + * + * @since 1.0.0 + */ public long getResponseMillis();

- /* Return the time when the HTTP request was written. */ + /** + * Return the time in milliseconds since the epoch when the HTTP + * request was written. + * + * @since 1.0.0 + */ public long getDataRequestMillis();

- /* Return the time when the first response was received. */ + /** + * Return the time in milliseconds since the epoch when the first + * response was received. + * + * @since 1.0.0 + */ public long getDataResponseMillis();

- /* Return the time when the payload was complete. */ + /** + * Return the time in milliseconds since the epoch when the payload was + * complete. + * + * @since 1.0.0 + */ public long getDataCompleteMillis();

- /* Return the total number of bytes written. */ + /** + * Return the total number of bytes written. + * + * @since 1.0.0 + */ public int getWriteBytes();

- /* Return the total number of bytes read. */ + /** + * Return the total number of bytes read. + * + * @since 1.0.0 + */ public int getReadBytes();

- /* Return whether the request timed out (as opposed to failing), or null - * if the torperf line didn't contain that information. */ + /** + * Return whether the request timed out (as opposed to failing), or + * null if the torperf line didn't contain that information. + * + * @since 1.0.0 + */ public Boolean didTimeout();

- /* Return the times when x% of expected bytes were read for - * 0 <= x <= 100, or null if the torperf line didn't contain that - * information. */ + /** + * Return the times in milliseconds since the epoch when {@code x%} of + * expected bytes were read for {@code 0 <= x <= 100}, or null if the + * torperf line didn't contain that information. + * + * @since 1.0.0 + */ public SortedMap<Integer, Long> getDataPercentiles();

- /* Return the time when the circuit was launched, or -1 if the torperf - * line didn't contain that information. */ + /** + * Return the time in milliseconds since the epoch when the circuit was + * launched, or -1 if the torperf line didn't contain that + * information. + * + * @since 1.0.0 + */ public long getLaunchMillis();

- /* Return the time when the circuit was used, or -1 if the torperf line - * didn't contain that information. */ + /** + * Return the time in milliseconds since the epoch when the circuit was + * used, or -1 if the torperf line didn't contain that information. + * + * @since 1.0.0 + */ public long getUsedAtMillis();

- /* Return a list of fingerprints of the relays in the circuit, or null - * if the torperf line didn't contain that information. */ + /** + * Return a list of fingerprints of the relays in the circuit, or null + * if the torperf line didn't contain that information. + * + * @since 1.0.0 + */ public List<String> getPath();

- /* Return a list of times in millis when circuit hops were built, or - * null if the torperf line didn't contain that information. */ + /** + * Return a list of times in milliseconds since the epoch when circuit + * hops were built, or null if the torperf line didn't contain that + * information. + * + * @since 1.0.0 + */ public List<Long> getBuildTimes();

- /* Return the circuit build timeout that the Tor client used when + /** + * Return the circuit build timeout that the Tor client used when * building this circuit, or -1 if the torperf line didn't contain that - * information. */ + * information. + * + * @since 1.0.0 + */ public long getTimeout();

- /* Return the circuit build time quantile that the Tor client uses to - * determine its circuit-build timeout, or -1.0 if the torperf line - * didn't contain that information. */ + /** + * Return the circuit build time quantile that the Tor client uses to + * determine its circuit-build timeout, or -1 if the torperf line + * didn't contain that information. + * + * @since 1.0.0 + */ public double getQuantile();

- /* Return the identifier of the circuit used for this measurement, or -1 - * if the torperf line didn't contain that information. */ + /** + * Return the identifier of the circuit used for this measurement, or + * -1 if the torperf line didn't contain that information. + * + * @since 1.0.0 + */ public int getCircId();

- /* Return the identifier of the stream used for this measurement, or -1 - * if the torperf line didn't contain that information. */ + /** + * Return the identifier of the stream used for this measurement, or -1 + * if the torperf line didn't contain that information. + * + * @since 1.0.0 + */ public int getUsedBy(); }

diff --git a/src/org/torproject/descriptor/package-info.java b/src/org/torproject/descriptor/package-info.java new file mode 100644 index 0000000..5b34554 --- /dev/null +++ b/src/org/torproject/descriptor/package-info.java @@ -0,0 +1,80 @@ +/* Copyright 2016 The Tor Project + * See LICENSE for licensing information */ + +/** + * Interfaces and essential classes for obtaining and processing Tor + * descriptors. + * + * <p>This package contains all relevant interfaces and + * classes that an application would need to use this library. + * Applications are strongly discouraged from accessing types from the + * implementation package ({@code org.torproject.descriptor.impl}) + * directly, because those may change without prior notice.</p> + * + * <p>Interfaces and classes in this package can be grouped into + * general-purpose types to obtain and process any type of descriptor and + * descriptors produced by different components of the Tor network:</p> + * + * <ol> + * <li>General-purpose types comprise + * {@link org.torproject.descriptor.DescriptorSourceFactory} which is the + * main entry point into using this library. This factory is used to + * create the descriptor sources for obtaining remote descriptor data + * ({@link org.torproject.descriptor.DescriptorDownloader} and + * {@link org.torproject.descriptor.DescriptorCollector}) and descriptor + * sources for processing local descriptor data + * ({@link org.torproject.descriptor.DescriptorReader} and + * {@link org.torproject.descriptor.DescriptorParser}). General-purpose + * types also include descriptor containers + * ({@link org.torproject.descriptor.DescriptorRequest} and + * {@link org.torproject.descriptor.DescriptorFile}) and the + * superinterface for all provided descriptors + * ({@link org.torproject.descriptor.Descriptor}).</li> + * + * <li>The first group of descriptors is published by relays and servers + * in the Tor network. These interfaces include server descriptors + * ({@link org.torproject.descriptor.ServerDescriptor} with subinterfaces + * {@link org.torproject.descriptor.RelayServerDescriptor} and + * {@link org.torproject.descriptor.BridgeServerDescriptor}), extra-info + * descriptors ({@link org.torproject.descriptor.ExtraInfoDescriptor} with + * subinterfaces + * {@link org.torproject.descriptor.RelayExtraInfoDescriptor} and + * {@link org.torproject.descriptor.BridgeExtraInfoDescriptor}), + * microdescriptors which are derived from server descriptors by the + * directory authorities + * ({@link org.torproject.descriptor.Microdescriptor}), and helper types + * for parts of the aforementioned descriptors + * ({@link org.torproject.descriptor.BandwidthHistory}).</li> + * + * <li>The second group of descriptors is generated by authoritative + * directory servers that form an opinion about relays and bridges in the + * Tor network. These include descriptors specified in version 3 of the + * directory protocol + * ({@link org.torproject.descriptor.RelayNetworkStatusConsensus}, + * {@link org.torproject.descriptor.RelayNetworkStatusVote}, + * {@link org.torproject.descriptor.DirectoryKeyCertificate}, and helper + * types for descriptor parts + * {@link org.torproject.descriptor.DirSourceEntry}, + * {@link org.torproject.descriptor.NetworkStatusEntry}, and + * {@link org.torproject.descriptor.DirectorySignature}), descriptors from + * earlier directory protocol version 2 + * ({@link org.torproject.descriptor.RelayNetworkStatus}) and version 1 + * ({@link org.torproject.descriptor.RelayDirectory} and + * {@link org.torproject.descriptor.RouterStatusEntry}), as well as + * descriptors published by the bridge authority and sanitized by the + * CollecTor service + * ({@link org.torproject.descriptor.BridgeNetworkStatus}).</li> + * + * <li>The third group of descriptors is created by auxiliary services + * connected to the Tor network rather than by the Tor software. This + * group comprises descriptors by the bridge distribution service BridgeDB + * ({@link org.torproject.descriptor.BridgePoolAssignment}), the exit list + * service TorDNSEL ({@link org.torproject.descriptor.ExitList}), and the + * performance measurement service Torperf + * ({@link org.torproject.descriptor.TorperfResult}).</li> + * </ol> + * + * @since 1.0.0 + */ +package org.torproject.descriptor; +