May 2016 - tor-commits - lists.torproject.org

[translation/torbutton-torbuttondtd] Update translations for torbutton-torbuttondtd
by translation＠torproject.org 31 May '16

31 May '16

commit 16d38832c506bd267adce53e5944368330060f21 Author: Translation commit bot <translation(a)torproject.org> Date: Tue May 31 21:15:52 2016 +0000 Update translations for torbutton-torbuttondtd --- br/torbutton.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/torbutton.dtd b/br/torbutton.dtd index 32c680f..76b12d9 100644 --- a/br/torbutton.dtd +++ b/br/torbutton.dtd @@ -1,5 +1,5 @@ <!ENTITY torbutton.prefs.title "Torbutton Preferences"> -<!ENTITY torbutton.prefs.tor_settings "Proxy Settings"> +<!ENTITY torbutton.prefs.tor_settings "Dibarzhioù ar Proxy"> <!ENTITY torbutton.prefs.recommended_settings "Use the recommended proxy settings for my version of Firefox"> <!ENTITY torbutton.prefs.use_privoxy "Use Privoxy"> <!ENTITY torbutton.prefs.use_polipo "Use Polipo">

1 0

[metrics-lib/master] Prepare for 1.2.0 release.
by karsten＠torproject.org 31 May '16

31 May '16

commit 7e58458e7aaffce88321e59370d0c18e0c899002 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue May 31 20:23:15 2016 +0200 Prepare for 1.2.0 release. --- CERT | 16 ++++++++-------- CHANGELOG.md | 2 +- build.xml | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CERT b/CERT index 3683158..eaeef50 100644 --- a/CERT +++ b/CERT @@ -1,7 +1,7 @@ -----BEGIN CERTIFICATE----- -MIIDbTCCAlWgAwIBAgIEOUQZDTANBgkqhkiG9w0BAQsFADBnMQswCQYDVQQGEwJVUzELMAkGA1UE +MIIDbTCCAlWgAwIBAgIEca8MxDANBgkqhkiG9w0BAQsFADBnMQswCQYDVQQGEwJVUzELMAkGA1UE CBMCTUExEjAQBgNVBAcTCUNhbWJyaWRnZTEdMBsGA1UEChMUVGhlIFRvciBQcm9qZWN0LCBJbmMx -GDAWBgNVBAMTD0thcnN0ZW4gTG9lc2luZzAeFw0xNTExMjAxMTUzNTFaFw0xNjAyMTgxMTUzNTFa +GDAWBgNVBAMTD0thcnN0ZW4gTG9lc2luZzAeFw0xNjA1MzExODIwMjlaFw0xNjA4MjkxODIwMjla MGcxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJNQTESMBAGA1UEBxMJQ2FtYnJpZGdlMR0wGwYDVQQK ExRUaGUgVG9yIFByb2plY3QsIEluYzEYMBYGA1UEAxMPS2Fyc3RlbiBMb2VzaW5nMIIBIjANBgkq hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgJCqHFgEhyj8AI4w93YcyZEkKwn2Jw5t7bYcaLieP0wa @@ -9,10 +9,10 @@ Ai2xrRFROo0eofjIllPlYTFtj9jLAZf+MQ1/Sdv7SLdlpasBCS0deTGlxuMzyMP9ztkkkAeibc+F IXYPJArwGJiycnd+obW8b8KNrJQsnb0Se5Fdgo/PSu1rqMh/Mylv9vLqUzB4hbN4bg5+7THlTAOK egYyR0NEPDzi327MAvzzle27kXV9yOCQr01zXW9NeWYed6JMXCZwaMN6nTVEFiwTfAyATfPncarf gZ1kyAkQ6/Sw2bGMv8jHqB63Ka0/6GXHRbFgCeWU+c/1sfEMBD3ZurEjwSjWGl73E4GBswIDAQAB -oyEwHzAdBgNVHQ4EFgQUJbu6UT97IU4utjyc4zYUrLIgzvQwDQYJKoZIhvcNAQELBQADggEBADT/ -QEbkx0tVKWWkeahVBt76LG50iO0OQ5dP3SCdhZoudt7jIFifrAcGlOG6vAKXT6/dAhDkKiKXzxQo -8mt3wdkN4sIZDuXroJ+42s6ZED2L1HP6/daLlwaAfnx0b9LAAGKF7CMqxgPpiqiJ3K4LB4I1kFRJ -uzjy+/XTOR9aF5o0AGAb5jMmv/BtVu2cH+UgixH/FVhyfZekja2OAN/N2VE0BuzJEDApEJ9p9j5I -CRzeAuvOGT1CIEJR/fAuM5WZN6rD8nB7zwGCZP/RKvRdw0m89wMvHnvRvPZchSVf2PNoNy2GoqN6 -nWsS1VYgwYfyGV+br7U+YKCoKTKJ1jRxpAs= +oyEwHzAdBgNVHQ4EFgQUJbu6UT97IU4utjyc4zYUrLIgzvQwDQYJKoZIhvcNAQELBQADggEBAHOF +jMP0rNa+cKy8beEpU0VRZ1RNLb70BoFjXZvzgv92MGnojg509fYO3PgzXUZv5v50VenexZjeZ9to +iiqw5zDelg1maVSZwKrQVgFIwXnP4+okIcPMtFjSNiF9VyhRd8OE3U/kpIBdecMVIEhCIKOaF/nq +uBwilXAK7VwYN7hQgKbIODoX9Y3dr9QDvrILkFDEmOudmDRo+RePAKJum+/E0RuUYjOeXpFmzXOf +5LJ/Y4hMKuLfuxoWasHOV0IRx///CNgF1L287TCyjrYUbEjWwMtFQc0NRjedhcWUzwXLpbk2unxM +j6ElkADaczDG20ZGSgrFfU4MYb1RFeQu6yk= -----END CERTIFICATE----- diff --git a/CHANGELOG.md b/CHANGELOG.md index f694f84..ecb1523 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# Changes in version 1.2.0 - 2016-05-?? +# Changes in version 1.2.0 - 2016-05-31 * Medium changes - Include the hostname in directory source entries of consensuses diff --git a/build.xml b/build.xml index f77f83b..8bd3841 100644 --- a/build.xml +++ b/build.xml @@ -1,5 +1,5 @@ <project default="jar" name="descriptor" basedir="."> - <property name="release.version" value="1.1.0-dev" /> + <property name="release.version" value="1.2.0" /> <property name="sources" value="src"/> <property name="resources" value="resources"/> <property name="classes" value="classes"/>

1 0

[metrics-lib/master] Add benchmark code.
by karsten＠torproject.org 31 May '16

31 May '16

commit 58fe9880434dc73c74779236ef1f3fcddeec933f Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Wed May 18 09:49:50 2016 +0200 Add benchmark code. Implements #19051. --- CHANGELOG.md | 1 + build.xml | 13 +- .../descriptor/benchmark/MeasurePerformance.java | 278 +++++++++++++++++++++ 3 files changed, 291 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfd4755..f694f84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ which would mean that only method 1 is supported. - Stop reporting "-----END .*-----" lines in directory key certificates as unrecognized. + - Add code used for benchmarking. # Changes in version 1.1.0 - 2015-12-28 diff --git a/build.xml b/build.xml index 129c4ed..f77f83b 100644 --- a/build.xml +++ b/build.xml @@ -68,7 +68,7 @@ </javadoc> </target> - <target name="test" depends="compile"> + <target name="testcompile" depends="init"> <javac destdir="${classes}" srcdir="${tests}" source="${source-and-target-java-version}" @@ -80,6 +80,9 @@ includeantruntime="false"> <classpath refid="classpath"/> </javac> + </target> + + <target name="test" depends="compile,testcompile"> <junit fork="true" haltonfailure="true" printsummary="off"> <classpath refid="classpath"/> <formatter type="plain" usefile="false"/> @@ -90,6 +93,14 @@ </junit> </target> + <target name="benchmark" depends="compile,testcompile"> + <java fork="true" + maxmemory="2048m" + classname="org.torproject.descriptor.benchmark.MeasurePerformance"> + <classpath refid="classpath"/> + </java> + </target> + <target name="jar" depends="compile"> <exec executable="git" outputproperty="git.revision"> <arg value="rev-parse" /> diff --git a/test/org/torproject/descriptor/benchmark/MeasurePerformance.java b/test/org/torproject/descriptor/benchmark/MeasurePerformance.java new file mode 100644 index 0000000..a52020a --- /dev/null +++ b/test/org/torproject/descriptor/benchmark/MeasurePerformance.java @@ -0,0 +1,278 @@ +/* Copyright 2016 The Tor Project + * See LICENSE for licensing information */ +package org.torproject.descriptor.benchmark; + +import org.torproject.descriptor.Descriptor; +import org.torproject.descriptor.DescriptorFile; +import org.torproject.descriptor.DescriptorReader; +import org.torproject.descriptor.DescriptorSourceFactory; +import org.torproject.descriptor.ExtraInfoDescriptor; +import org.torproject.descriptor.Microdescriptor; +import org.torproject.descriptor.NetworkStatusEntry; +import org.torproject.descriptor.RelayNetworkStatusConsensus; +import org.torproject.descriptor.ServerDescriptor; + +import java.io.File; +import java.util.HashSet; +import java.util.Iterator; +import java.util.Set; +import java.util.SortedMap; + +public class MeasurePerformance { + + /* Check if all necessary files are available and then measure + * performance of some more or less common use cases. */ + public static void main(String[] args) { + if (!filesAvailable()) { + return; + } + measureAverageAdvertisedBandwidth(new File(resDir, resPaths[0])); + pause(); + measureAverageAdvertisedBandwidth(new File(resDir, resPaths[1])); + pause(); + measureAverageAdvertisedBandwidth(new File(resDir, resPaths[2])); + pause(); + measureCountriesV3Requests(new File(resDir, resPaths[3])); + pause(); + measureCountriesV3Requests(new File(resDir, resPaths[4])); + pause(); + measureAverageRelaysExit(new File(resDir, resPaths[5])); + pause(); + measureAverageRelaysExit(new File(resDir, resPaths[6])); + pause(); + measureAverageRelaysExit(new File(resDir, resPaths[7])); + measureFractionRelaysExit80Microdescriptors( + new File(resDir, resPaths[8])); + measureFractionRelaysExit80Microdescriptors( + new File(resDir, resPaths[9])); + } + + private static File resDir = new File("res"); + private static String[] resPaths = new String[] { + "archive/relay-descriptors/server-descriptors/" + + "server-descriptors-2015-11.tar.xz", + "archive/relay-descriptors/server-descriptors/" + + "server-descriptors-2015-11.tar", + "archive/relay-descriptors/server-descriptors/" + + "server-descriptors-2015-11", + "archive/relay-descriptors/extra-infos/extra-infos-2015-11.tar.xz", + "archive/relay-descriptors/extra-infos/extra-infos-2015-11.tar", + "archive/relay-descriptors/consensuses/consensuses-2015-11.tar.xz", + "archive/relay-descriptors/consensuses/consensuses-2015-11.tar", + "archive/relay-descriptors/consensuses/consensuses-2015-11", + "archive/relay-descriptors/microdescs/microdescs-2015-11.tar.xz", + "archive/relay-descriptors/microdescs/microdescs-2015-11.tar" + }; + + private static boolean filesAvailable() { + if (!resDir.exists() || !resDir.isDirectory()) { + return false; + } + for (String resPath : resPaths) { + if (!(new File(resDir, resPath).exists())) { + System.err.println("Missing resource: " + resDir + "/" + resPath); + return false; + } + } + return true; + } + + private static void pause() { + try { + Thread.sleep(15L * 1000L); + } catch (InterruptedException e) { + e.printStackTrace(); + } + } + + private static void measureAverageAdvertisedBandwidth( + File tarballFileOrDirectory) { + System.out.println("Starting measureAverageAdvertisedBandwidth"); + long startedMillis = System.currentTimeMillis(); + long sumAdvertisedBandwidth = 0, countedServerDescriptors = 0; + DescriptorReader descriptorReader = + DescriptorSourceFactory.createDescriptorReader(); + descriptorReader.addTarball(tarballFileOrDirectory); + descriptorReader.addDirectory(tarballFileOrDirectory); + Iterator<DescriptorFile> descriptorFiles = + descriptorReader.readDescriptors(); + while (descriptorFiles.hasNext()) { + DescriptorFile descriptorFile = descriptorFiles.next(); + for (Descriptor descriptor : descriptorFile.getDescriptors()) { + if (!(descriptor instanceof ServerDescriptor)) { + continue; + } + ServerDescriptor serverDescriptor = (ServerDescriptor) descriptor; + sumAdvertisedBandwidth += (long) Math.min(Math.min( + serverDescriptor.getBandwidthRate(), + serverDescriptor.getBandwidthBurst()), + serverDescriptor.getBandwidthObserved()); + countedServerDescriptors++; + } + } + long endedMillis = System.currentTimeMillis(); + System.out.println("Ending measureAverageAdvertisedBandwidth"); + System.out.printf("Total time: %d millis%n", + endedMillis - startedMillis); + System.out.printf("Processed server descriptors: %d%n", + countedServerDescriptors); + System.out.printf("Average advertised bandwidth: %d%n", + sumAdvertisedBandwidth / countedServerDescriptors); + System.out.printf("Time per server descriptor: %.6f millis%n", + ((double) (endedMillis - startedMillis)) + / ((double) countedServerDescriptors)); + } + + private static void measureCountriesV3Requests(File tarballFile) { + System.out.println("Starting measureCountriesV3Requests"); + long startedMillis = System.currentTimeMillis(); + Set<String> countries = new HashSet<>(); + long countedExtraInfoDescriptors = 0; + DescriptorReader descriptorReader = + DescriptorSourceFactory.createDescriptorReader(); + descriptorReader.addTarball(tarballFile); + Iterator<DescriptorFile> descriptorFiles = + descriptorReader.readDescriptors(); + while (descriptorFiles.hasNext()) { + DescriptorFile descriptorFile = descriptorFiles.next(); + for (Descriptor descriptor : descriptorFile.getDescriptors()) { + if (!(descriptor instanceof ExtraInfoDescriptor)) { + continue; + } + ExtraInfoDescriptor extraInfoDescriptor = + (ExtraInfoDescriptor) descriptor; + SortedMap<String, Integer> dirreqV3Reqs = + extraInfoDescriptor.getDirreqV3Reqs(); + if (dirreqV3Reqs != null) { + countries.addAll(dirreqV3Reqs.keySet()); + } + countedExtraInfoDescriptors++; + } + } + long endedMillis = System.currentTimeMillis(); + System.out.println("Ending measureCountriesV3Requests"); + System.out.printf("Total time: %d millis%n", + endedMillis - startedMillis); + System.out.printf("Processed extra-info descriptors: %d%n", + countedExtraInfoDescriptors); + System.out.printf("Number of countries: %d%n", + countries.size()); + System.out.printf("Time per extra-info descriptor: %.6f millis%n", + ((double) (endedMillis - startedMillis)) + / ((double) countedExtraInfoDescriptors)); + } + + private static void measureAverageRelaysExit( + File tarballFileOrDirectory) { + System.out.println("Starting measureAverageRelaysExit"); + long startedMillis = System.currentTimeMillis(); + long totalRelaysWithExitFlag = 0L, totalRelays = 0L, + countedConsensuses = 0L; + DescriptorReader descriptorReader = + DescriptorSourceFactory.createDescriptorReader(); + descriptorReader.addTarball(tarballFileOrDirectory); + descriptorReader.addDirectory(tarballFileOrDirectory); + Iterator<DescriptorFile> descriptorFiles = + descriptorReader.readDescriptors(); + while (descriptorFiles.hasNext()) { + DescriptorFile descriptorFile = descriptorFiles.next(); + for (Descriptor descriptor : descriptorFile.getDescriptors()) { + if (!(descriptor instanceof RelayNetworkStatusConsensus)) { + continue; + } + RelayNetworkStatusConsensus consensus = + (RelayNetworkStatusConsensus) descriptor; + for (NetworkStatusEntry entry : + consensus.getStatusEntries().values()) { + if (entry.getFlags().contains("Exit")) { + totalRelaysWithExitFlag++; + } + totalRelays++; + } + countedConsensuses++; + } + } + long endedMillis = System.currentTimeMillis(); + System.out.println("Ending measureAverageRelaysExit"); + System.out.printf("Total time: %d millis%n", + endedMillis - startedMillis); + System.out.printf("Processed consensuses: %d%n", countedConsensuses); + System.out.printf("Total number of status entries: %d%n", + totalRelays); + System.out.printf("Total number of status entries with Exit flag: " + + "%d%n", totalRelaysWithExitFlag); + System.out.printf("Average number of relays with Exit Flag: %.2f%n", + (double) totalRelaysWithExitFlag / (double) totalRelays); + System.out.printf("Time per consensus: %.6f millis%n", + ((double) (endedMillis - startedMillis)) + / ((double) countedConsensuses)); + } + + private static void measureFractionRelaysExit80Microdescriptors( + File tarballFile) { + System.out.println("Starting " + + "measureFractionRelaysExit80Microdescriptors"); + long startedMillis = System.currentTimeMillis(); + long totalRelaysWithExitFlag = 0L, countedMicrodescriptors = 0L; + DescriptorReader descriptorReader = + DescriptorSourceFactory.createDescriptorReader(); + descriptorReader.addTarball(tarballFile); + Iterator<DescriptorFile> descriptorFiles = + descriptorReader.readDescriptors(); + while (descriptorFiles.hasNext()) { + DescriptorFile descriptorFile = descriptorFiles.next(); + for (Descriptor descriptor : descriptorFile.getDescriptors()) { + if (!(descriptor instanceof Microdescriptor)) { + continue; + } + countedMicrodescriptors++; + Microdescriptor microdescriptor = + (Microdescriptor) descriptor; + String defaultPolicy = microdescriptor.getDefaultPolicy(); + if (defaultPolicy == null) { + continue; + } + boolean accept = "accept".equals( + microdescriptor.getDefaultPolicy()); + for (String ports : microdescriptor.getPortList().split(",")) { + if (ports.contains("-")) { + String[] parts = ports.split("-"); + int from = Integer.parseInt(parts[0]); + int to = Integer.parseInt(parts[1]); + if (from <= 80 && to >= 80) { + if (accept) { + totalRelaysWithExitFlag++; + } + } else if (to > 80) { + if (!accept) { + totalRelaysWithExitFlag++; + } + break; + } + } else if ("80".equals(ports)) { + if (accept) { + totalRelaysWithExitFlag++; + } + break; + } + } + } + } + long endedMillis = System.currentTimeMillis(); + System.out.println("Ending " + + "measureFractionRelaysExit80Microdescriptors"); + System.out.printf("Total time: %d millis%n", + endedMillis - startedMillis); + System.out.printf("Processed microdescriptors: %d%n", + countedMicrodescriptors); + System.out.printf("Total number of microdescriptors that exit to 80: " + + "%d%n", totalRelaysWithExitFlag); + System.out.printf("Average number of relays that exit to 80: %.2f%n", + (double) totalRelaysWithExitFlag + / (double) countedMicrodescriptors); + System.out.printf("Time per microdescriptor: %.6f millis%n", + ((double) (endedMillis - startedMillis)) + / ((double) countedMicrodescriptors)); + } +} +

1 0

[metrics-lib/master] Bump version to 1.2.0-dev.
by karsten＠torproject.org 31 May '16

31 May '16

commit fecd53b1a9ad1ee3c939a6cd73fce3f7750c11cf Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue May 31 20:44:08 2016 +0200 Bump version to 1.2.0-dev. --- build.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.xml b/build.xml index 8bd3841..6bb773b 100644 --- a/build.xml +++ b/build.xml @@ -1,5 +1,5 @@ <project default="jar" name="descriptor" basedir="."> - <property name="release.version" value="1.2.0" /> + <property name="release.version" value="1.2.0-dev" /> <property name="sources" value="src"/> <property name="resources" value="resources"/> <property name="classes" value="classes"/>

1 0

[metrics-lib/master] Document all public parts using Javadoc.
by karsten＠torproject.org 31 May '16

31 May '16

commit 6d05ae95e968806351892b09f7b9653ff82879ed Author: Karsten Loesing <karsten.loesing(a)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="&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> +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. + +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>. + +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: + +<ul> +<li>Complete coverage: 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>Runtime and memory efficiency: Processing large amounts of +descriptors in bulk is supposed to be efficient in terms of runtime and +required memory.</li> +</ul> + +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: + +<ul> +<li>Verification: 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>Potentially lossy conversion: 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>Generating descriptors: 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>Writing descriptors: 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> + +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>. + + +Contact and further information: +<ul> +<li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Met…">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. + * + * 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}). + * + * @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. + * + * 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. + * + * Details about sanitizing bridge extra-info descriptors can be found + * <a href="https://collector.torproject.org/#type-bridge-extra-info">here</a>. + * + * + * @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. + * + * 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. + * + * The main purpose of this document is to get an authoritative list of + * running bridges to the bridge distribution service BridgeDB. + * + * Details about sanitizing bridge network statuses can be found + * <a href="https://collector.torproject.org/#type-bridge-network-status">here</a>. + * + * + * @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. + * + * 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. + * + * Details about sanitizing bridge pool assignments can be found + * <a href="https://collector.torproject.org/#type-bridge-pool-assignment">here</a>. + * + * + * @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. + * + * 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. + * + * Details about sanitizing bridge server descriptors can be found + * <a href="https://collector.torproject.org/#type-bridge-server-descriptor">here</a>. + * + * + * @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. + * + * 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}. + * + * Code sample: + * <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"} * @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. + * + * Downloading descriptors is done in a batch which starts after + * setting any configuration options and initiating the download + * process. + * + * @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. + * + * 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. + * + * @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. + * + * 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). + * + * @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. + * + * 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). + * + * @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. + * + * 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). + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * This descriptor source is likely the most widely used one, possibly + * in combination with {@link DescriptorCollector} to synchronize + * descriptors from the CollecTor service. + * + * Reading descriptors is done in a batch which starts after setting + * any configuration options and initiating the read process. + * + * Code sample: + * <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. + * + * Add a new line for each descriptor that is read in this execution + * and remove lines for files that don't exist anymore. + * + * Lines in the history file contain the last modified time in + * milliseconds since the epoch and the absolute path of a file. + * + * @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. + * + * Can be used instead of (or in addition to) a history file. + * + * @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. */ + * + * Can be used instead of (or in addition to) a history file when + * combined with the set of parsed files. + * + * @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. + * + * Can be used instead of (or in addition to) a history file when + * combined with the set of excluded files. + * + * @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. + * + * 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. + * + * @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. + * + * The default is 100, but if descriptor files contain hundreds or + * even thousands of descriptors, that default may be too high. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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}). + * + * 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. + * + * These properties can be used for setting the implementation: + * <ul> + * <li>{@code descriptor.collector}</li> + * <li>{@code descriptor.downloader}</li> + * <li>{@code descriptor.parser}</li> + * <li>{@code descriptor.reader}</li> + * </ul> + * + * 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: + * + * <code> + * java -Ddescriptor.downloader=my.special.descriptorimpl.Downloader my.app.Mainclass + * </code> + * + * @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. + * + * A directory source entry is not a descriptor type of its own but is + * part of a network status consensus + * ({@link RelayNetworkStatusConsensus}). + * + * @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. + * + * 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. + * + * @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. + * + * 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}). + * + * @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. + * + * 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. + * + * 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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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}). + * + * @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. + * + * 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}). + * + * 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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * 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. + * + * 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. + * + * @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. + * + * 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. + * + * 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}). + * + * @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. + * + * 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}). + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * @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. + * + * 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. + * + * @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. + * + * 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. + * + * 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: + * + * <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; +

1 0

[metrics-lib/master] Parse crypto parts in network status votes.
by karsten＠torproject.org 31 May '16

31 May '16

commit 1413dfb124729a3c41dd1a9ac9c2823b2e608aa2 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Fri May 20 11:39:51 2016 +0200 Parse crypto parts in network status votes. --- CHANGELOG.md | 1 + .../impl/RelayNetworkStatusVoteImpl.java | 92 +++++++++++++++++++++- .../impl/RelayNetworkStatusVoteImplTest.java | 15 ++++ 3 files changed, 104 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66da859..a1b9a75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ - Rename properties for overriding default descriptor source implementation classes. - Actually return the signing key digest in network status votes. + - Parse crypto parts in network status votes. * Minor changes - Include a Torperf results line with more than one unrecognized diff --git a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java index 68f3b38..8d18919 100644 --- a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java +++ b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java @@ -3,6 +3,7 @@ package org.torproject.descriptor.impl; import org.torproject.descriptor.DescriptorParseException; + import java.util.ArrayList; import java.util.Arrays; import java.util.HashSet; @@ -75,7 +76,8 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl this.ignoringAdvertisedBws = -1; Scanner s = new Scanner(new String(headerBytes)).useDelimiter("\n"); - boolean skipCrypto = false; /* TODO Parse crypto parts. */ + String nextCrypto = ""; + StringBuilder crypto = null; while (s.hasNext()) { String line = s.next(); String[] parts = line.split("[ \t]+"); @@ -145,18 +147,52 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl this.parseDirKeyExpiresLine(line, parts); break; case "dir-identity-key": + this.parseDirIdentityKeyLine(line, parts); + nextCrypto = "dir-identity-key"; + break; case "dir-signing-key": + this.parseDirSigningKeyLine(line, parts); + nextCrypto = "dir-signing-key"; + break; case "dir-key-crosscert": + this.parseDirKeyCrosscertLine(line, parts); + nextCrypto = "dir-key-crosscert"; + break; case "dir-key-certification": + this.parseDirKeyCertificationLine(line, parts); + nextCrypto = "dir-key-certification"; break; case "-----BEGIN": - skipCrypto = true; + crypto = new StringBuilder(); + crypto.append(line).append("\n"); break; case "-----END": - skipCrypto = false; + crypto.append(line).append("\n"); + String cryptoString = crypto.toString(); + crypto = null; + switch (nextCrypto) { + case "dir-identity-key": + this.dirIdentityKey = cryptoString; + break; + case "dir-signing-key": + this.dirSigningKey = cryptoString; + break; + case "dir-key-crosscert": + this.dirKeyCrosscert = cryptoString; + break; + case "dir-key-certification": + this.dirKeyCertification = cryptoString; + break; + default: + throw new DescriptorParseException("Unrecognized crypto " + + "block in vote."); + } + nextCrypto = ""; break; default: - if (!skipCrypto) { + if (crypto != null) { + crypto.append(line).append("\n"); + } else { if (this.failUnrecognizedDescriptorLines) { throw new DescriptorParseException("Unrecognized line '" + line + "' in vote."); @@ -414,6 +450,34 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl parts, 1, 2); } + private void parseDirIdentityKeyLine(String line, String[] parts) + throws DescriptorParseException { + if (!line.equals("dir-identity-key")) { + throw new DescriptorParseException("Illegal line '" + line + "'."); + } + } + + private void parseDirSigningKeyLine(String line, String[] parts) + throws DescriptorParseException { + if (!line.equals("dir-signing-key")) { + throw new DescriptorParseException("Illegal line '" + line + "'."); + } + } + + private void parseDirKeyCrosscertLine(String line, String[] parts) + throws DescriptorParseException { + if (!line.equals("dir-key-crosscert")) { + throw new DescriptorParseException("Illegal line '" + line + "'."); + } + } + + private void parseDirKeyCertificationLine(String line, String[] parts) + throws DescriptorParseException { + if (!line.equals("dir-key-certification")) { + throw new DescriptorParseException("Illegal line '" + line + "'."); + } + } + protected void parseFooter(byte[] footerBytes) throws DescriptorParseException { Scanner s = new Scanner(new String(footerBytes)).useDelimiter("\n"); @@ -488,6 +552,26 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl return this.dirKeyExpiresMillis; } + private String dirIdentityKey; + public String getDirIdentityKey() { + return this.dirIdentityKey; + } + + private String dirSigningKey; + public String getDirSigningKey() { + return this.dirSigningKey; + } + + private String dirKeyCrosscert; + public String getDirKeyCrosscert() { + return this.dirKeyCrosscert; + } + + private String dirKeyCertification; + public String getDirKeyCertification() { + return this.dirKeyCertification; + } + public String getSigningKeyDigest() { String signingKeyDigest = null; if (!this.directorySignatures.isEmpty()) { diff --git a/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java b/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java index 6111b59..261abd4 100644 --- a/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java +++ b/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java @@ -506,6 +506,21 @@ public class RelayNetworkStatusVoteImplTest { assertEquals("Tor 0.2.1.29 (r8e9b25e6c7a2e70c)", vote.getStatusEntry("00343A8024F70E214728F0C5AF7ACE0C1508F073"). getVersion()); + assertEquals(3, vote.getDirKeyCertificateVersion()); + assertEquals("80550987E1D626E3EBA5E5E75A458DE0626D088C", + vote.getIdentity()); + assertEquals(1303882477000L, /* 2011-04-27 05:34:37 */ + vote.getDirKeyPublishedMillis()); + assertEquals(1335504877000L, /* 2012-04-27 05:34:37 */ + vote.getDirKeyExpiresMillis()); + assertEquals("-----BEGIN RSA PUBLIC KEY-----", + vote.getDirIdentityKey().split("\n")[0]); + assertEquals("-----BEGIN RSA PUBLIC KEY-----", + vote.getDirSigningKey().split("\n")[0]); + assertEquals("-----BEGIN ID SIGNATURE-----", + vote.getDirKeyCrosscert().split("\n")[0]); + assertEquals("-----BEGIN SIGNATURE-----", + vote.getDirKeyCertification().split("\n")[0]); assertTrue(vote.getUnrecognizedLines().isEmpty()); }

1 0

[metrics-lib/master] Actually return the signing key digest in votes.
by karsten＠torproject.org 31 May '16

31 May '16

commit 4299213a36517cff283db0d026230b2aa3a7f3ac Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Fri May 20 11:38:41 2016 +0200 Actually return the signing key digest in votes. --- CHANGELOG.md | 1 + .../torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java | 8 ++++++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 45ce45f..66da859 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ read for 0 <= x <= 100 rather than just x = { 10, 20, ..., 90 }. - Rename properties for overriding default descriptor source implementation classes. + - Actually return the signing key digest in network status votes. * Minor changes - Include a Torperf results line with more than one unrecognized diff --git a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java index 886612f..68f3b38 100644 --- a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java +++ b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java @@ -488,9 +488,13 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl return this.dirKeyExpiresMillis; } - private String signingKeyDigest; public String getSigningKeyDigest() { - return this.signingKeyDigest; + String signingKeyDigest = null; + if (!this.directorySignatures.isEmpty()) { + signingKeyDigest = this.directorySignatures.get( + this.directorySignatures.firstKey()).getSigningKeyDigest(); + } + return signingKeyDigest; } private int networkStatusVersion;

1 0

[metrics-lib/master] Make "consensus-methods" line optional in votes.
by karsten＠torproject.org 31 May '16

31 May '16

commit 8b814ef8db2b83af1fb9cd1ed69f3d2d92a33331 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Fri May 20 11:36:06 2016 +0200 Make "consensus-methods" line optional in votes. --- CHANGELOG.md | 2 ++ .../torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java | 8 +++++--- .../descriptor/impl/RelayNetworkStatusVoteImplTest.java | 7 +++++-- 3 files changed, 12 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e5789c1..45ce45f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ * Minor changes - Include a Torperf results line with more than one unrecognized key only once in the unrecognized lines. + - Make "consensus-methods" line optional in network statuses votes, + which would mean that only method 1 is supported. - Stop reporting "-----END .*-----" lines in directory key certificates as unrecognized. diff --git a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java index 7d59282..886612f 100644 --- a/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java +++ b/src/org/torproject/descriptor/impl/RelayNetworkStatusVoteImpl.java @@ -42,14 +42,15 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl throws DescriptorParseException { super(voteBytes, failUnrecognizedDescriptorLines, false, false); Set<String> exactlyOnceKeywords = new HashSet<>(Arrays.asList(( - "vote-status,consensus-methods,published,valid-after,fresh-until," + "vote-status,published,valid-after,fresh-until," + "valid-until,voting-delay,known-flags,dir-source," + "dir-key-certificate-version,fingerprint,dir-key-published," + "dir-key-expires,dir-identity-key,dir-signing-key," + "dir-key-certification,directory-signature").split(","))); this.checkExactlyOnceKeywords(exactlyOnceKeywords); Set<String> atMostOnceKeywords = new HashSet<>(Arrays.asList(( - "client-versions,server-versions,flag-thresholds,params,contact," + "consensus-methods,client-versions,server-versions," + + "flag-thresholds,params,contact," + "legacy-key,dir-key-crosscert,dir-address,directory-footer"). split(","))); this.checkAtMostOnceKeywords(atMostOnceKeywords); @@ -499,7 +500,8 @@ public class RelayNetworkStatusVoteImpl extends NetworkStatusImpl private Integer[] consensusMethods; public List<Integer> getConsensusMethods() { - return Arrays.asList(this.consensusMethods); + return this.consensusMethods == null ? null : + Arrays.asList(this.consensusMethods); } private long publishedMillis; diff --git a/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java b/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java index 17f59a8..6111b59 100644 --- a/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java +++ b/test/org/torproject/descriptor/impl/RelayNetworkStatusVoteImplTest.java @@ -4,6 +4,7 @@ package org.torproject.descriptor.impl; import org.torproject.descriptor.DescriptorParseException; import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertNull; import static org.junit.Assert.assertTrue; import java.util.ArrayList; @@ -622,10 +623,12 @@ public class RelayNetworkStatusVoteImplTest { "vote-status TheMagicVoteStatus"); } - @Test(expected = DescriptorParseException.class) + @Test() public void testConsensusMethodNoLine() throws DescriptorParseException { - VoteBuilder.createWithConsensusMethodsLine(null); + RelayNetworkStatusVote vote = + VoteBuilder.createWithConsensusMethodsLine(null); + assertNull(vote.getConsensusMethods()); } @Test(expected = DescriptorParseException.class)

1 0

[metrics-lib/master] Stop reporting some lines in certificates as unrecognized.
by karsten＠torproject.org 31 May '16

31 May '16

commit 2cd927286d15b92b1eb2663a4db3ca7dadf70a67 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Fri May 20 11:33:01 2016 +0200 Stop reporting some lines in certificates as unrecognized. --- CHANGELOG.md | 2 ++ src/org/torproject/descriptor/impl/DirectoryKeyCertificateImpl.java | 1 + 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff233ff..e5789c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ * Minor changes - Include a Torperf results line with more than one unrecognized key only once in the unrecognized lines. + - Stop reporting "-----END .*-----" lines in directory key + certificates as unrecognized. # Changes in version 1.1.0 - 2015-12-28 diff --git a/src/org/torproject/descriptor/impl/DirectoryKeyCertificateImpl.java b/src/org/torproject/descriptor/impl/DirectoryKeyCertificateImpl.java index 1039bbd..13baedb 100644 --- a/src/org/torproject/descriptor/impl/DirectoryKeyCertificateImpl.java +++ b/src/org/torproject/descriptor/impl/DirectoryKeyCertificateImpl.java @@ -124,6 +124,7 @@ public class DirectoryKeyCertificateImpl extends DescriptorImpl + "block in directory key certificate."); } nextCrypto = ""; + break; default: if (crypto != null) { crypto.append(line).append("\n");

1 0

[metrics-lib/master] Rename properties in descriptor source factory.
by karsten＠torproject.org 31 May '16

31 May '16

commit 9e11172b932faf128f9d7e27dc547c131cb4cf95 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Fri May 20 11:31:53 2016 +0200 Rename properties in descriptor source factory. --- CHANGELOG.md | 4 +++- src/org/torproject/descriptor/DescriptorSourceFactory.java | 8 ++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d2a246..ff233ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# Changes in version ?.?.? - 2016-??-?? +# Changes in version 1.2.0 - 2016-05-?? * Medium changes - Include the hostname in directory source entries of consensuses @@ -8,6 +8,8 @@ the corresponding values, rather than just the whole line. - In Torperf results, recognize all percentiles of expected bytes read for 0 <= x <= 100 rather than just x = { 10, 20, ..., 90 }. + - Rename properties for overriding default descriptor source + implementation classes. * Minor changes - Include a Torperf results line with more than one unrecognized diff --git a/src/org/torproject/descriptor/DescriptorSourceFactory.java b/src/org/torproject/descriptor/DescriptorSourceFactory.java index 8bab13e..728c3eb 100644 --- a/src/org/torproject/descriptor/DescriptorSourceFactory.java +++ b/src/org/torproject/descriptor/DescriptorSourceFactory.java @@ -16,10 +16,10 @@ public final class DescriptorSourceFactory { "org.torproject.descriptor.impl.DescriptorCollectorImpl"; /* property names */ - public final static String PARSER_PROPERTY = "onionoo.parser"; - public final static String READER_PROPERTY = "onionoo.property"; - public final static String LOADER_PROPERTY = "onionoo.downloader"; - public final static String COLLECTOR_PROPERTY = "onionoo.collector"; + public final static String PARSER_PROPERTY = "descriptor.parser"; + public final static String READER_PROPERTY = "descriptor.reader"; + public final static String LOADER_PROPERTY = "descriptor.downloader"; + public final static String COLLECTOR_PROPERTY = "descriptor.collector"; /** * Create a descriptor parser.

1 0