public interface ServerDescriptor extends 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
(Microdescriptor
), the directory authorities included
cryptographic digests of server descriptors in network statuses
(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
(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.
Modifier and Type | Method and Description |
---|---|
java.lang.String |
getAddress()
Return the server's primary IPv4 address in dotted-quad format.
|
boolean |
getAllowSingleHopExits()
Return whether this server allows single-hop circuits to make exit
connections.
|
int |
getBandwidthBurst()
Return the burst bandwidth in bytes per second that the server is
willing to sustain in very short intervals.
|
int |
getBandwidthObserved()
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 0.0.8 or older).
|
int |
getBandwidthRate()
Return the average bandwidth in bytes per second that the server is
willing to sustain over long periods.
|
boolean |
getCachesExtraInfo()
Return whether this server is a directory cache that provides
extra-info descriptors.
|
java.util.List<java.lang.Integer> |
getCircuitProtocolVersions()
Return the list of circuit protocol versions that this server
supports.
|
java.lang.String |
getContact()
Return the contact information for this server, which may contain
non-ASCII characters, or null if no contact information is included
in the descriptor.
|
java.lang.String |
getDigestSha1Hex()
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.
|
java.lang.String |
getDigestSha256Base64()
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.
|
int |
getDirPort()
Return the TCP port where this server accepts directory-related HTTP
connections, or 0 if the server does not accept such connections.
|
java.util.List<java.lang.String> |
getExitPolicyLines()
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.
|
java.lang.String |
getExtraInfoDigestSha1Hex()
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.
|
java.lang.String |
getExtraInfoDigestSha256Base64()
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.
|
java.util.List<java.lang.String> |
getFamilyEntries()
Return nicknames, $-prefixed identity fingerprints, or tuples of the
format
$fingerprint=nickname or $fingerprint~nickname
of servers contained in this server's family, or null if the
descriptor does not contain a family line. |
java.lang.String |
getFingerprint()
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.
|
java.util.List<java.lang.Integer> |
getHiddenServiceDirVersions()
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.
|
java.lang.String |
getIdentityEd25519()
Return the Ed25519 certificate in PEM format, or null if the
descriptor doesn't contain one.
|
java.lang.String |
getIpv6DefaultPolicy()
Return the default policy,
"accept" or "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. |
java.lang.String |
getIpv6PortList()
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.
|
java.util.List<java.lang.Integer> |
getLinkProtocolVersions()
Return the list of link protocol versions that this server
supports.
|
java.lang.String |
getMasterKeyEd25519()
Return the Ed25519 master key, encoded as 43 base64 characters
without padding characters, which was either 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. |
java.lang.String |
getNickname()
Return the server's nickname consisting of 1 to 19 alphanumeric
characters.
|
java.lang.String |
getNtorOnionKey()
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.
|
java.lang.String |
getNtorOnionKeyCrosscert()
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.
|
int |
getNtorOnionKeyCrosscertSign()
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.
|
java.lang.String |
getOnionKey()
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).
|
java.lang.String |
getOnionKeyCrosscert()
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.
|
java.util.List<java.lang.String> |
getOrAddresses()
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.
|
int |
getOrPort()
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.
|
java.lang.String |
getPlatform()
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
"Tor $version on $system" ,
or null if this descriptor does not contain a platform line. |
java.util.SortedMap<java.lang.String,java.util.SortedSet<java.lang.Long>> |
getProtocols()
Return the version numbers of all protocols supported by this server, or
null if this descriptor does not specify supported protocol versions.
|
long |
getPublishedMillis()
Return the time in milliseconds since the epoch when this descriptor
and the corresponding extra-info descriptor were generated.
|
BandwidthHistory |
getReadHistory()
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
(
ExtraInfoDescriptor.getReadHistory() ), not in their server
descriptors. |
java.lang.String |
getRouterSignature()
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).
|
java.lang.String |
getRouterSignatureEd25519()
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
"router-sig-ed25519" string, prefixed with
the string "Tor router descriptor signature v1" . |
java.lang.String |
getSigningKey()
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).
|
int |
getSocksPort()
Return the TCP port where this server accepts SOCKS connections,
which is deprecated in the Tor Protocol and should always be 0.
|
boolean |
getTunnelledDirServer()
Return whether the server accepts "tunneled" directory requests using
a BEGIN_DIR cell over the server's OR port.
|
java.lang.Long |
getUptime()
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.
|
boolean |
getUsesEnhancedDnsLogic()
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; current Tor versions should be presumed to have the evdns
backend.
|
BandwidthHistory |
getWriteHistory()
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
(
ExtraInfoDescriptor.getWriteHistory() ), not in their server
descriptors. |
boolean |
isHibernating()
Return whether the server was hibernating when this descriptor was
published and should not be used to build circuits.
|
getAnnotations, getDescriptorFile, getRawDescriptorBytes, getRawDescriptorLength, getUnrecognizedLines
java.lang.String getDigestSha1Hex()
java.lang.String getDigestSha256Base64()
java.lang.String getNickname()
java.lang.String getAddress()
int getOrPort()
int getSocksPort()
int getDirPort()
java.util.List<java.lang.String> getOrAddresses()
int getBandwidthRate()
int getBandwidthBurst()
int getBandwidthObserved()
java.lang.String getPlatform()
"Tor $version on $system"
,
or null if this descriptor does not contain a platform line.java.util.SortedMap<java.lang.String,java.util.SortedSet<java.lang.Long>> getProtocols()
long getPublishedMillis()
java.lang.String getFingerprint()
boolean isHibernating()
java.lang.Long getUptime()
java.lang.String getOnionKey()
java.lang.String getSigningKey()
java.util.List<java.lang.String> getExitPolicyLines()
java.lang.String getRouterSignature()
java.lang.String getContact()
java.util.List<java.lang.String> getFamilyEntries()
$fingerprint=nickname
or $fingerprint~nickname
of servers contained in this server's family, or null if the
descriptor does not contain a family line.BandwidthHistory getReadHistory()
ExtraInfoDescriptor.getReadHistory()
), not in their server
descriptors.BandwidthHistory getWriteHistory()
ExtraInfoDescriptor.getWriteHistory()
), not in their server
descriptors.boolean getUsesEnhancedDnsLogic()
boolean getCachesExtraInfo()
java.lang.String getExtraInfoDigestSha1Hex()
java.lang.String getExtraInfoDigestSha256Base64()
java.util.List<java.lang.Integer> getHiddenServiceDirVersions()
java.util.List<java.lang.Integer> getLinkProtocolVersions()
java.util.List<java.lang.Integer> getCircuitProtocolVersions()
boolean getAllowSingleHopExits()
java.lang.String getIpv6DefaultPolicy()
"accept"
or "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.java.lang.String getIpv6PortList()
java.lang.String getNtorOnionKey()
java.lang.String getIdentityEd25519()
java.lang.String getMasterKeyEd25519()
"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.java.lang.String getRouterSignatureEd25519()
"router-sig-ed25519"
string, prefixed with
the string "Tor router descriptor signature v1"
.java.lang.String getOnionKeyCrosscert()
java.lang.String getNtorOnionKeyCrosscert()
int getNtorOnionKeyCrosscertSign()
boolean getTunnelledDirServer()