Interface ServerDescriptor

  • All Superinterfaces:
    Descriptor, java.io.Serializable
    All Known Subinterfaces:
    BridgeServerDescriptor, RelayServerDescriptor

    public interface ServerDescriptor
    extends 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 (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.

    Since:
    1.0.0
    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.String getAddress()
      Get the server's primary IPv4 address in dotted-quad format.
      boolean getAllowSingleHopExits()
      Get whether this server allows single-hop circuits to make exit connections.
      int getBandwidthBurst()
      Get the burst bandwidth in bytes per second that the server is willing to sustain in very short intervals.
      int getBandwidthObserved()
      Get 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()
      Get the average bandwidth in bytes per second that the server is willing to sustain over long periods.
      java.lang.String getBridgeDistributionRequest()
      Get the method how a bridge requests to be distributed by BridgeDB, or null if no such request is contained in the descriptor.
      boolean getCachesExtraInfo()
      Return whether this server is a directory cache that provides extra-info descriptors.
      java.util.List<java.lang.Integer> getCircuitProtocolVersions()
      Get the list of circuit protocol versions that this server supports.
      java.lang.String getContact()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Deprecated.
      Replaced with isHiddenServiceDir(), because Tor has never supported versions in the hidden-service-dir descriptor line.
      java.lang.String getIdentityEd25519()
      Get the Ed25519 certificate in PEM format, or null if the descriptor doesn't contain one.
      java.lang.String getIpv6DefaultPolicy()
      Get 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()
      Get 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()
      Get 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()
      Get the server's nickname consisting of 1 to 19 alphanumeric characters.
      java.lang.String getNtorOnionKey()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get the TCP port where this server accepts TLS connections for the main OR protocol, or 0 if the server does not accept such connections.
      long getOverloadGeneralTimestamp()
      Get the timestamp of when the server was detected in an overloaded state
      int getOverloadGeneralVersion()
      Get the version number in the overload-general line.
      java.lang.String getPlatform()
      Get 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()
      Get the version numbers of all protocols supported by this server, or null if this descriptor does not specify supported protocol versions.
      long getPublishedMillis()
      Get the time in milliseconds since the epoch when this descriptor and the corresponding extra-info descriptor were generated.
      BandwidthHistory getReadHistory()
      Get 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()
      Get 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()
      Get 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()
      Get 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()
      Get the TCP port where this server accepts SOCKS connections, which is deprecated in the Tor Protocol and should always be 0.
      boolean getTunnelledDirServer()
      Get whether the server accepts "tunneled" directory requests using a BEGIN_DIR cell over the server's OR port.
      java.lang.Long getUptime()
      Get 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()
      Get the enhanced DNS logic value for the server.
      BandwidthHistory getWriteHistory()
      Get 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()
      Get whether the server was hibernating when this descriptor was published and should not be used to build circuits.
      boolean isHiddenServiceDir()
      Return whether this server stores and serves hidden service descriptors.
    • Method Detail

      • getDigestSha1Hex

        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.
        Since:
        1.7.0
      • getDigestSha256Base64

        java.lang.String getDigestSha256Base64()
        Get 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.
        Returns:
        descriptor digest
        Since:
        1.7.0
      • getNickname

        java.lang.String getNickname()
        Get the server's nickname consisting of 1 to 19 alphanumeric characters.
        Returns:
        nickname
        Since:
        1.0.0
      • getAddress

        java.lang.String getAddress()
        Get the server's primary IPv4 address in dotted-quad format.
        Returns:
        IPv4 address
        Since:
        1.0.0
      • getOrPort

        int getOrPort()
        Get the TCP port where this server accepts TLS connections for the main OR protocol, or 0 if the server does not accept such connections.
        Returns:
        TCP OR port
        Since:
        1.0.0
      • getSocksPort

        int getSocksPort()
        Get the TCP port where this server accepts SOCKS connections, which is deprecated in the Tor Protocol and should always be 0.
        Returns:
        socks port
        Since:
        1.0.0
      • getDirPort

        int getDirPort()
        Get the TCP port where this server accepts directory-related HTTP connections, or 0 if the server does not accept such connections.
        Returns:
        TCP directory port
        Since:
        1.0.0
      • getOrAddresses

        java.util.List<java.lang.String> getOrAddresses()
        Get 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.
        Returns:
        OR addresses
        Since:
        1.0.0
      • getBandwidthRate

        int getBandwidthRate()
        Get the average bandwidth in bytes per second that the server is willing to sustain over long periods.
        Returns:
        bandwidth rate
        Since:
        1.0.0
      • getBandwidthBurst

        int getBandwidthBurst()
        Get the burst bandwidth in bytes per second that the server is willing to sustain in very short intervals.
        Returns:
        burst bandwidth limit
        Since:
        1.0.0
      • getBandwidthObserved

        int getBandwidthObserved()
        Get 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).
        Returns:
        observed bandwidth
        Since:
        1.0.0
      • getPlatform

        java.lang.String getPlatform()
        Get 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.
        Returns:
        human-readable Tor and OS version
        Since:
        1.0.0
      • getOverloadGeneralTimestamp

        long getOverloadGeneralTimestamp()
        Get the timestamp of when the server was detected in an overloaded state

        Because this is a binary state, if the line is present, we consider that it was hit at the very least once somewhere between the provided timestamp and the "published" timestamp of the document which is when the document was generated.

        Returns:
        timestamp
        Since:
        2.19.0
      • getOverloadGeneralVersion

        int getOverloadGeneralVersion()
        Get the version number in the overload-general line.
        Returns:
        version
        Since:
        2.19.0
      • getProtocols

        java.util.SortedMap<java.lang.String,​java.util.SortedSet<java.lang.Long>> getProtocols()
        Get the version numbers of all protocols supported by this server, or null if this descriptor does not specify supported protocol versions.
        Returns:
        supported protocols version numbers
        Since:
        1.6.0
      • getPublishedMillis

        long getPublishedMillis()
        Get the time in milliseconds since the epoch when this descriptor and the corresponding extra-info descriptor were generated.
        Returns:
        time since the descriptors were generated
        Since:
        1.0.0
      • getFingerprint

        java.lang.String getFingerprint()
        Get 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.
        Returns:
        SHA-1 public identity key digest
        Since:
        1.0.0
      • isHibernating

        boolean isHibernating()
        Get whether the server was hibernating when this descriptor was published and should not be used to build circuits.
        Returns:
        hibernating flag
        Since:
        1.0.0
      • getUptime

        java.lang.Long getUptime()
        Get 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.
        Returns:
        seconds since the server process was started
        Since:
        1.0.0
      • getOnionKey

        java.lang.String getOnionKey()
        Get 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).
        Returns:
        RSA-1024 public key in PEM format
        Since:
        1.0.0
      • getSigningKey

        java.lang.String getSigningKey()
        Get 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).
        Returns:
        RSA-1024 public key in PEM format
        Since:
        1.0.0
      • getExitPolicyLines

        java.util.List<java.lang.String> getExitPolicyLines()
        Get 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.
        Returns:
        exit policy
        Since:
        1.0.0
      • getRouterSignature

        java.lang.String getRouterSignature()
        Get 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).
        Returns:
        RSA-1024 signature
        Since:
        1.0.0
      • getContact

        java.lang.String getContact()
        Get the contact information for this server, which may contain non-ASCII characters, or null if no contact information is included in the descriptor.
        Returns:
        contact information
        Since:
        1.0.0
      • getBridgeDistributionRequest

        java.lang.String getBridgeDistributionRequest()
        Get the method how a bridge requests to be distributed by BridgeDB, or null if no such request is contained in the descriptor.
        Returns:
        bridge distribution method
        Since:
        2.11.0
      • getFamilyEntries

        java.util.List<java.lang.String> getFamilyEntries()
        Get 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.
        Returns:
        family line
        Since:
        1.0.0
      • getReadHistory

        BandwidthHistory getReadHistory()
        Get 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.
        Returns:
        history of read bytes
        Since:
        1.0.0
      • getWriteHistory

        BandwidthHistory getWriteHistory()
        Get 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.
        Returns:
        history of written bytes
        Since:
        1.0.0
      • getUsesEnhancedDnsLogic

        boolean getUsesEnhancedDnsLogic()
        Get the enhanced DNS logic value for the server. Returns 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.
        Returns:
        enhanced DNS logic boolean flag
        Since:
        1.0.0
      • getCachesExtraInfo

        boolean getCachesExtraInfo()
        Return whether this server is a directory cache that provides extra-info descriptors.
        Since:
        1.0.0
      • getExtraInfoDigestSha1Hex

        java.lang.String getExtraInfoDigestSha1Hex()
        Get 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.
        Returns:
        SHA-1 digest
        Since:
        1.7.0
      • getExtraInfoDigestSha256Base64

        java.lang.String getExtraInfoDigestSha256Base64()
        Get 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.
        Returns:
        SHA-256 digest
        Since:
        1.7.0
      • getHiddenServiceDirVersions

        @Deprecated
        java.util.List<java.lang.Integer> getHiddenServiceDirVersions()
        Deprecated.
        Replaced with isHiddenServiceDir(), because Tor has never supported versions in the hidden-service-dir descriptor line.
        Get 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.
        Returns:
        list of version numbers
        Since:
        1.0.0
      • isHiddenServiceDir

        boolean isHiddenServiceDir()
        Return whether this server stores and serves hidden service descriptors.
        Since:
        2.3.0
      • getLinkProtocolVersions

        java.util.List<java.lang.Integer> getLinkProtocolVersions()
        Return the list of link protocol versions that this server supports.
        Since:
        1.0.0
      • getCircuitProtocolVersions

        java.util.List<java.lang.Integer> getCircuitProtocolVersions()
        Get the list of circuit protocol versions that this server supports.
        Returns:
        list of protocol versions
        Since:
        1.0.0
      • getAllowSingleHopExits

        boolean getAllowSingleHopExits()
        Get whether this server allows single-hop circuits to make exit connections.
        Returns:
        single-hop allowed flag
        Since:
        1.0.0
      • getIpv6DefaultPolicy

        java.lang.String getIpv6DefaultPolicy()
        Get 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.
        Returns:
        default policy
        Since:
        1.0.0
      • getIpv6PortList

        java.lang.String getIpv6PortList()
        Get 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.
        Returns:
        IPv6 exit-policy
        Since:
        1.0.0
      • getNtorOnionKey

        java.lang.String getNtorOnionKey()
        Get 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.
        Returns:
        curve25519 public key
      • getIdentityEd25519

        java.lang.String getIdentityEd25519()
        Get the Ed25519 certificate in PEM format, or null if the descriptor doesn't contain one.
        Returns:
        Ed25519 certificate
        Since:
        1.1.0
      • getMasterKeyEd25519

        java.lang.String getMasterKeyEd25519()
        Get 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.
        Returns:
        Ed25519 master key
        Since:
        1.1.0
      • getRouterSignatureEd25519

        java.lang.String getRouterSignatureEd25519()
        Get 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".
        Returns:
        Ed25519 signature
        Since:
        1.1.0
      • getOnionKeyCrosscert

        java.lang.String getOnionKeyCrosscert()
        Get 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.
        Returns:
        RSA-1024 signature
        Since:
        1.1.0
      • getNtorOnionKeyCrosscert

        java.lang.String getNtorOnionKeyCrosscert()
        Get 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.
        Returns:
        Ed25519 signature
        Since:
        1.1.0
      • getNtorOnionKeyCrosscertSign

        int getNtorOnionKeyCrosscertSign()
        Get 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.
        Returns:
        sign of the Ed25519 public
        Since:
        1.1.0
      • getTunnelledDirServer

        boolean getTunnelledDirServer()
        Get whether the server accepts "tunneled" directory requests using a BEGIN_DIR cell over the server's OR port.
        Returns:
        "tunneled" directory requests flag
        Since:
        1.3.0