Package org.torproject.descriptor

Interface RelayNetworkStatusVote

All Superinterfaces:

Descriptor, Serializable

public interface RelayNetworkStatusVote
extends Descriptor

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 (RelayNetworkStatusConsensus).

Since:

1.0.0

Method Summary

Modifier and Type	Method	Description
boolean	containsStatusEntry(String fingerprint)	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 getStatusEntries().containsKey(fingerprint).
String	getAddress()	Return the authority's primary IPv4 address in dotted-quad format, or null if the descriptor does not contain an address.
String	getBandwidthFileDigestSha256Base64()	Return the SHA256 digest of the bandwidth file, encoded as 43 base64 characters without padding characters, or null if the authority producing this vote is not configured with a bandwidth file or does not include the SHA256 digest of the configured bandwidth file in its vote.
SortedMap<String,String>	getBandwidthFileHeaders()	Return the headers from the bandwidth file used to generate this vote, or null if the authority producing this vote is not configured with a bandwidth file or does not include the headers of the configured bandwidth file in its vote.
List<Integer>	getConsensusMethods()	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.
SortedMap<String,Integer>	getConsensusParams()	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.
String	getContactLine()	Return the contact information for this authority, which may contain non-ASCII characters, or null if no contact information is included in the descriptor.
String	getDigestSha1Hex()	Return the SHA-1 digest of this vote, encoded as 40 lower-case hexadecimal characters that is used to reference this vote from a consensus.
String	getDirIdentityKey()	Return the authority's identity key in PEM format.
int	getDirKeyCertificateVersion()	Return the version of the directory key certificate used by this authority, which must be 3 or higher.
String	getDirKeyCertification()	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.
String	getDirKeyCrosscert()	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.
long	getDirKeyExpiresMillis()	Return the time in milliseconds since the epoch after which the authority's signing key is no longer valid.
long	getDirKeyPublishedMillis()	Return the time in milliseconds since the epoch when the authority's signing key and corresponding key certificate were generated.
int	getDirport()	Return the TCP port where this authority accepts directory-related HTTP connections, or 0 if the authority does not accept such connections.
String	getDirSigningKey()	Return the authority's signing key in PEM format.
long	getDistSeconds()	Return the number of seconds that the directory authorities will allow to collect signatures from the other authorities when producing the next consensus.
int	getEnoughMtbfInfo()	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.
long	getFastBandwidth()	Return the minimum bandwidth that this authority requires for assigning the Fast flag, or -1 if the authority doesn't report this value.
long	getFreshUntilMillis()	Return the time in milliseconds since the epoch until which the consensus is supposed to be the freshest that is available.
long	getGuardBandwidthExcludingExits()	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.
long	getGuardBandwidthIncludingExits()	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.
long	getGuardTk()	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.
double	getGuardWfu()	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.
String	getHostname()	Return the authority's hostname.
String	getIdentity()	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.
int	getIgnoringAdvertisedBws()	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.
SortedSet<String>	getKnownFlags()	Return known relay flags by this authority.
String	getLegacyDirKey()	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.
int	getNetworkStatusVersion()	Return the document format version of this descriptor which is 3 or higher.
String	getNickname()	Return the authority's nickname consisting of 1 to 19 alphanumeric characters.
int	getOrport()	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.
List<String>	getPackageLines()	Return a list of software packages and their versions together with a URL and one or more digests in the format PackageName Version URL DIGESTS that are known by this directory authority, or null if this descriptor does not contain package information.
long	getPublishedMillis()	Return the time in milliseconds since the epoch when this descriptor was published.
SortedMap<String,SortedSet<Long>>	getRecommendedClientProtocols()	Return the version numbers of all protocols that clients should support, or null if the vote does not contain an opinion about protocol versions.
List<String>	getRecommendedClientVersions()	Return recommended Tor versions for client usage, or null if the authority does not recommend client versions.
SortedMap<String,SortedSet<Long>>	getRecommendedRelayProtocols()	Return the version numbers of all protocols that relays should support, or null if the vote does not contain an opinion about protocol versions.
List<String>	getRecommendedServerVersions()	Return recommended Tor versions for server usage, or null if the authority does not recommend server versions.
SortedMap<String,SortedSet<Long>>	getRequiredClientProtocols()	Return the version numbers of all protocols that clients must support, or null if the vote does not contain an opinion about protocol versions.
SortedMap<String,SortedSet<Long>>	getRequiredRelayProtocols()	Return the version numbers of all protocols that relays must support, or null if the vote does not contain an opinion about protocol versions.
List<String>	getSharedRandCommitLines()	Return all currently known directory authority commit lines for the shared randomness protocol in the original format as they are contained in this vote, or null if this vote does not contain any such line.
int	getSharedRandCurrentNumReveals()	Return the number of commits used to generate the latest shared random value, or -1 if this vote does not contain the latest shared random value.
String	getSharedRandCurrentValue()	Return the latest shared random value, encoded in base64, or null if this vote does not contain the latest shared random value.
int	getSharedRandPreviousNumReveals()	Return the number of commits used to generate the second-to-last shared random value, or -1 if this vote does not contain a second-to-last shared random value.
String	getSharedRandPreviousValue()	Return the second-to-last shared random value, encoded in base64, or null if this vote does not contain a second-to-last shared random value.
List<DirectorySignature>	getSignatures()	Return a list of signatures contained in this vote, which is typically a single signature made by the authority but which may also be more than one signature made with different keys or algorithms.
long	getStableMtbf()	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.
long	getStableUptime()	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.
SortedMap<String,NetworkStatusEntry>	getStatusEntries()	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.
NetworkStatusEntry	getStatusEntry(String fingerprint)	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 getStatusEntries().get(fingerprint).
long	getValidAfterMillis()	Return the time in milliseconds since the epoch at which the consensus is supposed to become valid.
long	getValidUntilMillis()	Return the time in milliseconds since the epoch until which the consensus is supposed to be valid.
long	getVoteSeconds()	Return the number of seconds that the directory authorities will allow to collect votes from the other authorities when producing the next consensus.
boolean	isSharedRandParticipate()	Return whether this directory authority supports and can participate in the shared random protocol.

Methods inherited from interface org.torproject.descriptor.Descriptor

getAnnotations, getDescriptorFile, getRawDescriptorBytes, getRawDescriptorLength, getUnrecognizedLines

Method Details

getNetworkStatusVersion

int getNetworkStatusVersion()

Return the document format version of this descriptor which is 3 or higher.

Since:

1.0.0

getConsensusMethods

List<Integer> getConsensusMethods()

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

getPublishedMillis

long getPublishedMillis()

Return the time in milliseconds since the epoch when this descriptor was published.

Since:

1.0.0

getValidAfterMillis

long getValidAfterMillis()

Return the time in milliseconds since the epoch at which the consensus is supposed to become valid.

Since:

1.0.0

getFreshUntilMillis

long getFreshUntilMillis()

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

getValidUntilMillis

long getValidUntilMillis()

Return the time in milliseconds since the epoch until which the consensus is supposed to be valid.

Since:

1.0.0

getVoteSeconds

long getVoteSeconds()

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

getDistSeconds

long getDistSeconds()

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

getRecommendedServerVersions

List<String> getRecommendedServerVersions()

Return recommended Tor versions for server usage, or null if the authority does not recommend server versions.

Since:

1.0.0

getRecommendedClientVersions

List<String> getRecommendedClientVersions()

Return recommended Tor versions for client usage, or null if the authority does not recommend client versions.

Since:

1.0.0

getRecommendedClientProtocols

SortedMap<String,SortedSet<Long>> getRecommendedClientProtocols()

Return the version numbers of all protocols that clients should support, or null if the vote does not contain an opinion about protocol versions.

Since:

1.6.0

getRecommendedRelayProtocols

SortedMap<String,SortedSet<Long>> getRecommendedRelayProtocols()

Return the version numbers of all protocols that relays should support, or null if the vote does not contain an opinion about protocol versions.

Since:

1.6.0

getRequiredClientProtocols

SortedMap<String,SortedSet<Long>> getRequiredClientProtocols()

Return the version numbers of all protocols that clients must support, or null if the vote does not contain an opinion about protocol versions.

Since:

1.6.0

getRequiredRelayProtocols

SortedMap<String,SortedSet<Long>> getRequiredRelayProtocols()

Return the version numbers of all protocols that relays must support, or null if the vote does not contain an opinion about protocol versions.

Since:

1.6.0

getPackageLines

List<String> getPackageLines()

Return a list of software packages and their versions together with a URL and one or more digests in the format PackageName Version URL DIGESTS that are known by this directory authority, or null if this descriptor does not contain package information.

Since:

1.3.0

getKnownFlags

SortedSet<String> getKnownFlags()

Return known relay flags by this authority.

Since:

1.0.0

getStableUptime

long getStableUptime()

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

getStableMtbf

long getStableMtbf()

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.

Since:

1.0.0

getFastBandwidth

long getFastBandwidth()

Return the minimum bandwidth that this authority requires for assigning the Fast flag, or -1 if the authority doesn't report this value.

Since:

1.0.0

getGuardWfu

double getGuardWfu()

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

getGuardTk

long getGuardTk()

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

getGuardBandwidthIncludingExits

long getGuardBandwidthIncludingExits()

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.

Since:

1.0.0

getGuardBandwidthExcludingExits

long getGuardBandwidthExcludingExits()

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.

Since:

1.0.0

getEnoughMtbfInfo

int getEnoughMtbfInfo()

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.

Since:

1.0.0

getIgnoringAdvertisedBws

int getIgnoringAdvertisedBws()

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.

Since:

1.1.0

getConsensusParams

SortedMap<String,Integer> getConsensusParams()

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

getNickname

String getNickname()

Return the authority's nickname consisting of 1 to 19 alphanumeric characters.

Since:

1.0.0

getIdentity

String getIdentity()

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

getHostname

String getHostname()

Return the authority's hostname.

Since:

1.2.0

getAddress

String getAddress()

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

getDirport

int getDirport()

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

getOrport

int getOrport()

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

getContactLine

String getContactLine()

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

isSharedRandParticipate

boolean isSharedRandParticipate()

Return whether this directory authority supports and can participate in the shared random protocol.

Since:

1.6.0

getSharedRandCommitLines

List<String> getSharedRandCommitLines()

Return all currently known directory authority commit lines for the shared randomness protocol in the original format as they are contained in this vote, or null if this vote does not contain any such line.

 "shared-rand-commit" SP Version SP AlgName SP Identity SP Commit
     [SP Reveal] NL
 

Since:

1.6.0

getSharedRandPreviousNumReveals

int getSharedRandPreviousNumReveals()

Return the number of commits used to generate the second-to-last shared random value, or -1 if this vote does not contain a second-to-last shared random value.

Since:

1.6.0

getSharedRandPreviousValue

String getSharedRandPreviousValue()

Return the second-to-last shared random value, encoded in base64, or null if this vote does not contain a second-to-last shared random value.

Since:

1.6.0

getSharedRandCurrentNumReveals

int getSharedRandCurrentNumReveals()

Return the number of commits used to generate the latest shared random value, or -1 if this vote does not contain the latest shared random value.

Since:

1.6.0

getSharedRandCurrentValue

String getSharedRandCurrentValue()

Return the latest shared random value, encoded in base64, or null if this vote does not contain the latest shared random value.

Since:

1.6.0

getBandwidthFileHeaders

SortedMap<String,String> getBandwidthFileHeaders()

Return the headers from the bandwidth file used to generate this vote, or null if the authority producing this vote is not configured with a bandwidth file or does not include the headers of the configured bandwidth file in its vote.

Since:

2.11.0

getBandwidthFileDigestSha256Base64

String getBandwidthFileDigestSha256Base64()

Return the SHA256 digest of the bandwidth file, encoded as 43 base64 characters without padding characters, or null if the authority producing this vote is not configured with a bandwidth file or does not include the SHA256 digest of the configured bandwidth file in its vote.

Since:

2.11.0

getDirKeyCertificateVersion

int getDirKeyCertificateVersion()

Return the version of the directory key certificate used by this authority, which must be 3 or higher.

Since:

1.0.0

getLegacyDirKey

String getLegacyDirKey()

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

getDirIdentityKey

String getDirIdentityKey()

Return the authority's identity key in PEM format.

Since:

1.2.0

getDirKeyPublishedMillis

long getDirKeyPublishedMillis()

Return the time in milliseconds since the epoch when the authority's signing key and corresponding key certificate were generated.

Since:

1.0.0

getDirKeyExpiresMillis

long getDirKeyExpiresMillis()

Return the time in milliseconds since the epoch after which the authority's signing key is no longer valid.

Since:

1.0.0

getDirSigningKey

String getDirSigningKey()

Return the authority's signing key in PEM format.

Since:

1.2.0

getDirKeyCrosscert

String getDirKeyCrosscert()

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

getDirKeyCertification

String getDirKeyCertification()

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

getStatusEntries

SortedMap<String,NetworkStatusEntry> getStatusEntries()

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

containsStatusEntry

boolean containsStatusEntry(String fingerprint)

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 getStatusEntries().containsKey(fingerprint).

Since:

1.0.0

getStatusEntry

NetworkStatusEntry getStatusEntry(String fingerprint)

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 getStatusEntries().get(fingerprint).

Since:

1.0.0

getSignatures

List<DirectorySignature> getSignatures()

Return a list of signatures contained in this vote, which is typically a single signature made by the authority but which may also be more than one signature made with different keys or algorithms.

Since:

1.3.0

getDigestSha1Hex

String getDigestSha1Hex()

Return the SHA-1 digest of this vote, encoded as 40 lower-case hexadecimal characters that is used to reference this vote from a consensus.

Since:

1.7.0