### Abstract {{ '{#abstract}' }}
These are the official extensions to ADC. This document is based on
the information contained in the ADC wiki and ADC forum - spefications
from there are moved here when they are mature and stable enough.
### Version history {{ '{#version_history}' }}
The latest draft of the next version of this document as well as
intermediate and older versions can be downloaded from ...
#### Version 1.0.9, UNRELEASED {{ '{#version_1_0_9_unreleased}' }}
* Clarified HH field in PING to be an ADC URL
#### Version 1.0.8, 2014-02-11 {{ '{#version_1_0_8}' }}
Fredrik Ullner <[email protected]>
* Improved *NATT* documentation, as according to the original paper.
* Added *ONID* extension to provide online service integration.
* TIGR now specifies the changes done to the file list.
* Added error code *ADCS transfers are required* in STA.
* Added *ASCH* extension for extended searching capability.
* Added *Date* attribute in file list for files and directories.
* Added *Size* attribute in file list for directories.
* Added *Children* attribute in file list for directories.
* Added downloaded progress report for uploaders in GET.
* Added *RDEX* for extended redirecting capabilities.
#### Version 1.0.7, 2012-11-22 {{ '{#version_1_0_7}' }}
Fredrik Ullner <[email protected]>
* Added application and version separation in INF
* TIGR should now correctly reference SCH and RES
#### Version 1.0.6, 2010-09-29 {{ '{#version_1_0_6}' }}
Fredrik Ullner <[email protected]>
* Added *KEYP* extension for providing certificate substitution protection in ADCS.
* Added note to signal DFAV.
* Added *SUDP* extension for encryption of UDP traffic.
* Added *TYPE* extension for chat state notifications.
* Added *FEED* extension for RSS feeds.
* Added *SEGA* extension for grouping of file extensions in SCH.
* Added failover hub addresses to the hub’s INF.
* Added free slots to the client’s INF.
* Added *ADCS* extension for encryption in ADC.
#### Version 1.0.5, 2010-09-16 {{ '{#version_1_0_5}' }}
Fredrik Ullner <[email protected]>
* Added locale field to INF.
* Modified user parameter *line* in UCMD to handle multiple inputs.
* Added hidden in enumeration of CT field in INF.
* Added error code Invalid feature in STA.
#### Version 1.0.4, 2010-06-29 {{ '{#version_1_0_4}' }}
Fredrik Ullner <[email protected]>
* Added magnet link extension to UCMD.
* Added NAT traversal extension *NATT*.
* Added referral field to STA.
* Added upload queue field to STA.
* Added partial file sharing extension *PFSR*.
#### Version 1.0.3, 2010-05-26 {{ '{#version_1_0_3}' }}
Fredrik Ullner <[email protected]>
* Removed optional keywords from UCMD.
* Added *BLOM* extension for bloom filters.
#### Version 1.0.2, 2010-04-04 {{ '{#version_1_0_2}' }}
Fredrik Ullner <[email protected]>
* Added *UCMD* extension for user commands.
#### Version 1.0.1, 2009-08-04 {{ '{#version_1_0_1}' }}
Fredrik Ullner <[email protected]>
* Added timestamp field to MSG.
* Added *DFAV* extension for distributing hub addresses.
#### Version 1.0, 2008-05-02 {{ '{#version_1_0}' }}
Jacek Sieka <[email protected]>
* Initial release created from original ADC 1.0 text.
* Added *PING* extension for hub pingers.
### Extensions {{ '{#extensions}' }}
#### TIGR - Tiger tree hash support {{ '{#tigr_tiger_tree_hash_support}' }}
##### General {{ '{#general}' }}
This extension adds Tiger tree hash support to the base protocol. It is
intended to be used both for identifying files and for purposes such as
CID generation and password negotiation
##### TIGR for shared files {{ '{#tigr_for_shared_files}' }}
All files shared by TIGR supporting clients must have been hashed using
Merkle Hash trees, as defined by
<http://web.archive.org/web/20080316033726/http://www.open-content.net/specs/draft-jchapweske-thex-02.html>.
The Tiger algorithm, as specified by
<http://www.cs.technion.ac.il/~biham/Reports/Tiger/>, functions as the
hash algorithm. A base segment size of 1024 bytes must be used when
generating the tree, but clients may then discard parts of the tree as
long as at least 7 levels are kept or a block granularity of 64 KiB is
achieved.
Generally, the root of the tree (TTH) serves to identify a file
uniquely. Searches use it and it must be present in the file list.
Further, the root of the file list must also be available and
discoverable via GFI. A client may also request the rest of the tree
using the normal client-client transfer procedure. The root must be
encoded using base32 encoding when converted to text.
In the file list, each File element carries an additional attribute
"TTH" containing the base32-encoded value of the Tiger tree root.
In the GET/GFI type, the full tree may be accessed using the "tthl"
type.
"tthl" transfers send the largest set of leaves available) as a binary
stream of leaf data, right-to-left, with no spacing in between them.
<start\_pos> must be set to 0 and <bytes> to -1 when
requesting the data. <bytes> must contain the total binary size of
the leaf stream in SND; by dividing this length by the individual hash
length, the number of leaves, and thus the leaf level, can be deducted.
The received leaves can then be used to reconstruct the entire tree, and
the resulting root must match the root of the file (this verifies the
integrity of the tree itself). Identifier must be a TTH root value from
the "TTH/" root.
In the GET/GFI namespace, files are identified by
"TTH/<base32-encoded tree root>".
In SCH and RES, the following attributes are added:
| | |
| -- | -------------------------------------------------------------------------------------------------------------------------------- |
| TR | Tiger tree Hash root, encoded with base32. |
| TD | Tree depth, index of the highest level of tree data available, root-only = 0, first level (2 leaves) = 1, second level = 2, etc… |
The following changes are done to the file list XML schema:
A new type is defined with an appropriate attribute:
<xs:simpleType name="tthType">
<xs:restriction base="xs:string">
<xs:pattern value="[A-Za-z2-7]{39}' }} " />
</xs:restriction>
</xs:simpleType>
<xs:attribute name="TTH" type="tthType" />
The attribute is then referenced in the File element:
<xs:attribute ref="TTH" use="required" />
#### BZIP - File list compressed with bzip2 {{ '{#bzip_file_list_compressed_with_bzip2}' }}
This extension adds a special file "files.xml.bz2" in the unnamed root
of the share which contains "files.xml" compressed with bzip2 1.0.3+
(www.bzip.org).
#### ZLIB - Compressed communication {{ '{#zlib_compressed_communication}' }}
There are two variants of zlib support, FULL and GET, and only one
should be used on a each communications channel set up.
##### ZLIB-FULL {{ '{#zlib_full}' }}
If, during SUP negotiation, a peer sends "ZLIF" in its support string,
it must accept two additional commands, ZON and ZOF. Upon reception of
ZON the peer must start decompressing the incoming stream of data with
zlib before interpreting it, and stop doing so after ZOF is received (in
the compressed stream). The compressing end must partially flush the
zlib buffer after each chunk of data to allow for decompression by the
peer.
##### ZLIB-GET {{ '{#zlib_get}' }}
The alternative is to send "ZLIG" to indicate that zlib is supported for
binary transfers using the GET command, but not otherwise. A flag "ZL1"
is added to the to the SND command to indicate that the data will come
compressed, and the client receiving requests it by adding the same flag
to GET (the sending client may ignore a request for a compressed
transfer, but may also use it even when not requested by the receiver).
The <bytes> parameter of the GET and SND commands is to be
interpreted as the number of uncompressed bytes to be transferred.
#### PING - Pinger extension {{ '{#ping_pinger_extension}' }}
This extension can be supported by both clients and hubs, and when
present, if hub supports it, it must send additional information to the
client ( otherwise normal base client).
It’s purpose is to send to hublist pingers additional information about
the hub that otherwise it would be impossible to get as a normal user
(eg. minimum share, maximum user count, etc).
##### INF {{ '{#inf}' }}
Contexts : F
When the client supporting the PING extension connects, the hub must
send its normal INF along with the following added fields ( none
mandatory, if not present, it means hub has no restrictions in that
matter, or non existent):
| Code | Type | Description |
| ---- | ------- | ----------------------------------------------------- |
| HH | url | Hub Host address (ADC/ADCS URL address form) |
| WS | url | Hub Website |
| NE | string | Hub Network |
| OW | string | Hub Owner name |
| UC | integer | Current User count |
| SS | integer | Total share size |
| SF | integer | Total files shared |
| MS | integer | Minimum share required to enter hub ( bytes ) |
| XS | integer | Maximum share for entering hub ( bytes ) |
| ML | integer | Minimum slots required to enter hub |
| XL | integer | Maximum slots for entering hub |
| MU | integer | Minimum hubs connected where clients can be users |
| MR | integer | Minimum hubs connected where client can be registered |
| MO | integer | Minimum hubs connected where client can be operators |
| XU | integer | Maximum hubs connected where clients can be users |
| XR | integer | Maximum hubs connected where client can be registered |
| XO | integer | Maximum hubs connected where client can be operators |
| MC | integer | Maximum possible clients ( users ) who can connect |
| UP | integer | Hub uptime (seconds) |
| NI | string | Hub name (from BASE) |
| DE | string | Hub description (from BASE) |
| VE | string | Hub software version (from BASE) |
The hub must continue to send the user list as for a normal user (move
to NORMAL state). The pinger may decide to go through or disconnect (eg.
if it doesn’t require additional information about the users).
##### Example {{ '{#example}' }}
-pinger- HSUP ADBASE ADPING AD..
-hub- ISUP ADBASE ADPING AD..
-hub- ISID ..
-hub- IINF NIhubname DEcurrent\stopic VE.. HHadc://example.org:555 WShttp://example.org/ OWmyname UC2231 SS.. SF.. MS0 ML0 MC5000
- (pinger may disconnect)
##### Hub - Hublist communication {{ '{#hub_hublist_communication}' }}
The same extension goes for hub- hublist communication. This way, the
hub takes the role of the client and the hublist of the server.
The hublist may send INF about itself with NI field which would become
hublist name and WS hublist web address.
###### Example {{ '{#example_2}' }}
-hub- HSUP ADBASE ADPING AD..
-hublist- ISUP ADBASE ADPING AD..
-hublist- IINF NIhublist_name WShublist_address
-hub- HINF NIhubname DEcurrent\stopic VE.. HHexample.org:555 WShttp://example.org/ OWmyname UC2231 SS.. SF.. MS0 ML0 MC5000
-( disconnect )
#### TS - Timestamp in MSG {{ '{#ts_timestamp_in_msg}' }}
Timestamp of the moment when the message was sent, expressed in seconds
since the Unix Epoch (January 1 1970 00:00:00 GMT).
#### DFAV - Distributed Favorites {{ '{#dfav_distributed_favorites}' }}
The idea behind this extension is to generate a public hublist from the
users favorite hublist. Implementations should separate between public
and private hubs in the favorite hublist of an user, in order not to
distribute private hubs where one can not connect to anyway.
Signal DFAV in SUP and the INF’s SU field.
##### GFA {{ '{#gfa}' }}
GFA
Contexts: T, C
Asks all users within the same hub with the correct feature to send all
publicly available hubs, in their favorite hub list to the requesting
client.
##### RFA {{ '{#rfa}' }}
RFA
Contexts: C
Response of a client.
| | |
| -- | ----------------------------------------------------------------------------- |
| HA | Hub address |
| LG | Last succesfull login time (number of seconds since the epoch (1970), (UTC) ) |
All INF fields from BASE are inherited. All INF fields from PING
extension are inherited.
#### UCMD - User commands {{ '{#ucmd_user_commands}' }}
CMD name
Contexts: F
States: NORMAL
User commands are used to send hub-specific commands to the client which
provide useful shortcuts for the user. These commands contain strings
which must be sent back to the hub and keyword substitutions in the
strings. Each user command has a display name, a string to be sent to
the hub, and one or more categories where it may appear. The strings
passed to the hub must first be passed through a dictionary replacement
that replaces all keywords in the string and then through the equivalent
of the C standard function "strftime", with the current time.
Name uniquely (per hub) identifies a particular user command. The name
may contain "/" to indicate a logical structure on the viewing client,
where each "/" introduces a new submenu level. Other than name, the
command also has a number of flags that further detail what to do with
it.
| | |
| -- | ------------------------------------------------------------------------------------------------------------------------------- |
| RM | 1 = Remove Command |
| CT | Message Category, 1 = Hub command, client parameters only, 2 = User list command, client and user parameters, 4 = Search result command, client, user and file parameters, 8 = File list command, client, user and file parameters. Multiple types are specified by adding the numbers together. |
| TT | The full text to be sent to hub, including FOURCC, parameters and keywords. |
| CO | 1 = Constrained, when sending this command on multiple users (for example in search results), constrain it to once per CID only |
| SP | 1 = Insert separator instead of command name (name must still be present to uniquely identify the command). |
##### Keywords {{ '{#keywords}' }}
Keywords are specified using "%\[keyword\]". Unknown keywords must be
replaced by the empty string. Additionally, all %-substitutions of the C
function "strftime" must be supported.
The following tables specify the keywords that must be supported.
Client parameters
| | |
| ------ | -------------------------------------------------------------------- |
| myCID | Client CID |
| mySID | ClientSID |
| myXX | One for each flag on that particular hub; for example, myI4 and myNI |
User parameters
| | |
| --------- | ------------------------------------------------------------------- |
| userCID | User CID |
| userSID | User SID |
| userXX | One for each flag on the user sent; for example, userI4 and userNI |
| line:info | Prompts the user for input where *info* is the displayed text description for the user input. *info* can be used for multiple values (combobox etc), and should be structured as "general info/default selection/value0/value1/…/valueN" . The general info can be viewed as the caption of the user input dialog. Default selection is an integer k which signifies the default value to be used. Note that N >= k >= 0 and N >= 1. Note that values are 0-index based. Values are separated with a forward slash (*/*). If a forward slash is part of a value, it should be escaped by using an additional forward slash (*//*). |
File parameters
| | |
| ------ | -------------------------------------------------------------------------------- |
| fileXX | One for each flag contained within a search result or file list entry (see RES) |
| fileMN | Specify magnet link. [Magnet links](http://en.wikipedia.org/wiki/Magnet_link) are used to reference files across networks and applications. Clients may ignore parameters it does not understand, but are free to pass on the parameters to other programs. |
Hub parameters
| | |
| ------ | ------------------------------------------------------------------- |
| hubXX | One for each flag of the hub; for example, hubNI and hubVE |
##### Example {{ '{#example_3}' }}
ICMD ADCH++/Hub\smanagement/Register\snick TTHMSG\s+regnick\s%\[userNI\]\s%\[line:Password\s(leave\sempty\sto\sun-reg)\]\s%\[line:Level\s(facultative;\sdefaults\sto\syour\sown\slevel\sminus\sone)\]\n CT2
ICMD ADCH++/Hub\smanagement/Reload\sbans TTHMSG\s+loadbans\n CT3
ICMD ADCH++/Hub\smanagement/Reload\sscripts TTHMSG\s+reload\n CT3
ICMD ADCH++/Info TTHMSG\s+info\s%\[userNI\]\n CT2
ICMD ADCH++/Info TTHMSG\s+info\n CT1
#### BLOM - Bloom filter {{ '{#blom_bloom_filter}' }}
Bloom filters allow the hub to filter certain searches using bitmap that
represents the hashes of the files in the users share. BLOM is an
extension that allows hub software to create a map (bloom filter) of the
shared files on the hub, but with minimal effort, e.g. the hub doesn’t
keep a list of files, but a filter that never produces false negatives
but only possible false positives. This can potentially save bandwidth
and effort on the client side. When the user updates the share, the
client must send an INF containing the flag SF. The hub may at any time
request that the client sends an updated version of its bloom filter by
sending a GET command to the client. The client will then respond using
SND and send the bloom filter binary data.
##### Legend {{ '{#legend}' }}
| | |
| - | --------------------------------------------------- |
| b | Number of bits used for file hashes |
| n | Number of files in the user’s share |
| m | Size of the bloom filter in bits |
| k | Number of sub-hashes constructed from the file hash |
| h | Number of bits to use for each sub-hash |
| p | Propability of a false positive |
The hub chooses k, h and m.
##### Restrictions {{ '{#restrictions}' }}
| |
| --------------- |
| k \* h < = b |
| h < = 64 |
| 2^h > m |
| m mod 64 == 0 |
##### Probability {{ '{#probability}' }}
| | |
| ------------------------------------------------ | --------------- |
| p == (1 - (1 - 1 / m)^(k \* n))^k | False positives |
| p == 0 | False negatives |
##### Protocol changes {{ '{#protocol_changes}' }}
Signal BLOM in SUP.
For the SND type, adds H as message type.
For the GET type, adds I as message type.
For the GET type, adds "blom" as type.
For the GET type, "/" shall be used as namespace.
For the GET type, 0 (zero) shall be used as start position.
For the GET type, m / 8 shall be used as byte amount.
Updates GET with the following flags;
| | |
| -- | --------------------------------- |
| BK | Specify *k*. |
| BH | Specify *h*. |
##### Algorithm {{ '{#algorithm}' }}
The client constructs the bloom filter by creating a bit array of m bits
set to 0 (zero). For each file it then sets to "1" k positions
constructed from the file hash. Seeing the file hash as a stream of bits
(starting from the lowest bit of the first byte, ending at the highest
bit of the last byte), the client should use h bits starting at the
first bit of the first byte to create an integer and apply modulo m to
get the position in the bit array, then redo the process k times
advancing the starting position by h each time.
Once the hub has received the bloom filter bit array, for each search
command it processes, if it contains a hash search term, it can skip
broadcasting the search to a particular client if at least one of the k
bits in that clients bit array is "0", calculating positions as the
client does when setting bits to "1". The hub has to evaluate the filter
for each client that it has a bloom filter for, for each search.
##### Probability calculations {{ '{#probability_calculations}' }}
p = (1 - (1 - 1 / m)^(k \* n))^k, thus p becomes smaller as m grows
and larger as n grows. Larger m means more bits to transfer but also
fewer false positives. The optimum value for k given m and n is (m / n)
\* ln 2. The largest k supported by a hash of a certain size is b / h,
so if the hub wants the smallest p possible, it should choose the
smallest possible h which gives the largest k, and then calculate m = k
\* n/ln 2, checking that the resulting m < 2^h^. 2^h^ should much be
larger than m (at least 3-4 times), because of how the modulo operator
works. Also, with m grows the required bandwidth to transfer the bloom
filter, so the hub may wish to cap m. In that case, it should still
choose k according to m / n \* ln 2, but send an h as big as possible to
alleviate biasing problems.
##### Sample implementations {{ '{#sample_implementations}' }}
###### Tiger {{ '{#tiger}' }}
For TTH roots, b is 192 and a reasonable value for h is 24, giving a
maximum k = 8 which means that m = 8 \* n / ln 2 ≈ 11.5 \* n. The
required bandwidth then becomes 11.5 \* n / 8 bytes, so approximately
1.44 bytes per file in the users share. For 20000 files, m should then
be 230016 (taking into account the modulo 64 requirement), giving a p =
0.004, in other words \~99.6% of all searches that don’t match a users
share would not be sent, saving valuable upload bandwidth for the hub.
The client calculates i valid positions, if x is an array of bytes
containing the hash of the file, on a little-endian machine, by doing
pos = x\[0+i\*h/8\] | (x\[1+i\*h/8\] << 8) | (x\[2+i\*h/8\]
<< 16) for i = \[0;k). This is of course a special case where h %
8 = 0, the actual algorithm has to take into consideration values for h
where the integer crosses byte boundaries.
For test vectors, see the [ADC wiki talk
page](http://www.adcportal.com/wiki/index.php/Talk:BLOM).
#### NATT - NAT traversal {{ '{#natt_nat_traversal}' }}
NAT traversal allow two passive clients to connect to each other. This
specification is based on the TCP hole punching algorithm described in
[^1].
If a client does not support TCP4 or TCP6, it will send an RCM to the
client it is trying to connect to. If the other client also doesn’t
support TCP4 (or TCP6 correspondingly), NAT traversal may instead be
used. Signal NATT in the INF’s SU field.
Do note that the hub must forward I4 or I6 for respective clients' INF.
An endpoint is the tuple of IP and port. The "private endpoint port"
refers to the outbound port to the connected hub, as seen by the client.
Each client must listen for incoming connections on this port. Note that
this protocol extension uses only this port for the TCP hole punching,
the use of the "public endpoint port" as specified in is not supported.
##### BASE RCM updates {{ '{#base_rcm_updates}' }}
When receiving an RCM and the client does not support TCP4 or TCP6, and
if NAT-T is supported in the remote client, a NAT command should be sent
repeating the protocol and token. The port shall be the private endpoint
port to the connected hub.
##### NAT {{ '{#nat}' }}
NAT protocol separator port separator token
Contexts: T
States: NORMAL
Upon receiving this, try and connect to the specified port. An RNT
command should be sent repeating the protocol and token. The port shall
be the private endpoint. Upon receiving this, try and connect to the
specified port.
##### RNT {{ '{#rnt}' }}
RNT protocol separator port separator token
Contexts: T
States: NORMAL
Upon receiving this, try and connect to the specified port.
##### Example {{ '{#example_4}' }}
Client A is connected to hub A with the private endpoint 1000 and client
B is connected to hub A with the private endpoint 2000. Client A has the
SID AAAA and client B has the SID BBBB.
Client A: DRCM AAAA BBBB ADC/1.0 foobar
Client B: DNAT BBBB AAAA ADC/1.0 2000 foobar
<Client A connects to client B’s IP address and port 2000>
Client A: DRNT AAAA BBBB ADC/1.0 1000 foobar
<Client B connects to client A’s IP address and port 1000>
#### RF - Referrer notification {{ '{#rf_referrer_notification}' }}
Extends the RF field of the INF to STA, allowing a client to notify
clients and hubs upon SUP-negotiation from where the C-C or C-H
originated from.
| | |
| -- | --------------------------------- |
| RF | URL of referrer |
##### Example {{ '{#example_5}' }}
CSUP ADBASE (…)
CSTA 000 referrer RFadc://example.com:1234
#### QP - Upload queue notification {{ '{#qp_upload_queue_notification}' }}
This extension’s purpose is creating a queue on a client, when multiple
other clients want to download from it, but they have no slots.
Currently, when a slot is being freed, the first connecting client gets
it. Other clients that don’t have the luck of getting in time to attempt
to download, have to wait again. The client who creates a queue must
have a ticket number for each connecting client, which must be kept
internally , and a difference between current connecting client’s queue
number and the currently uploading client’s be provided to the
connecting client, so that the clients are being deserved in the order
they originally connected. The client could have a ticket incrementing
starting from 1 for each session. Connecting clients must use the same
token as they used when originally connected.
| | |
| -- | --------------------------------------------------------------------- |
| QP | Queue number, representing how many others are in front in the queue. |
##### Example {{ '{#example_6}' }}
The following example will notify that the client’s slots are full and
that there are three uploads in the queue.
CSTA 253 No\sslots\savailable QP3
#### PFSR - Partial file sharing {{ '{#pfsr_partial_file_sharing}' }}
Partial File Sharing allows sharing of files which are available in
user’s download queue or in finished downloads list. As a result of
this, new files will be spread much faster over whole network.
When client receives search request (SCH), it looks into shared list to
see whether requested hash is available between shared files. If it’s
found, everything is processed as normally. In other case, it looks into
download queue (then, into finished downloads list) and receives a list
of available chunks for requested hash. It mustn’t take every chunk, but
only that ones which are fully downloaded and has already been verified
(e.g. against TTH leaves).
The feature should be signalled in SUP as PFSR.
##### PSR {{ '{#psr}' }}
PSR
Contexts: F, U
States: NORMAL
Information about downloaded and verified chunks is sent to requester
with this command. When the requester is active command is sent over UDP
(with U type) else it is sent over hub (with D type).
| | |
| -- | ---------------------------------------------------------------------------------------------------------------------------- |
| U4 | UDP IPv4 port or 0 if we don’t want receive a response. If UDP port is not zero (it must be when we are passive user), a PSR receiver must respond us with PSR including his available (and verified) chunks. The client must also set UDP port to zero to avoid infinite PSR sending. |
| U6 | Same as U4 but with IPv6 port. |
| TR | File hash |
| PC | Count of downloaded (and verified) chunks the user has. |
| PI | Comma separated list of start and end index of chunks the user has. If a user has a continous block of chunks, the intermittent start and end indexes may be omitted. For example, if a user has chunk 0 and 4 of total 5 chunks, then PI is "0,1,4,5". If the user has chunk 0, 1 and 4, then PI may be "0,1,1,2,4,5" or "0,2,4,5". |
#### LC - Locale specification {{ '{#lc_locale_specification}' }}
This extension’s purpose is to notify the hub which user locale the
client is using as well as the default locale for the hub. This allows
hubs to customize text sent to clients, depending on language,
left-to-right or right-to-left and more. If the hub does not directly
support the client’s locale, it should attempt to fall back to the same
language group (e.g. hub supports en-US but not en-AU, so falls back to
en-US), and if this is not available, then fall back to the hub’s own
locale.
[BCP47](http://tools.ietf.org/html/bcp47) should be used as reference
for locale structure.
| | |
| -- | ---------------------------- |
| LC | User locale |
Note that the standard suggest that the language should be in lowercase
and the country in upper case. Note that the country code may be more
than two characters. Additionally, dash (*-*) and underscore (*\_*) are
acceptable seperators.
#### Hidden status for client type {{ '{#hidden_status_for_client_type}' }}
This extension will add to the CT field enumeration in the INF to denote
a user as "hidden". Other clients shall as appropriate not display the
user in user lists etc.
| | |
| -- | --------------- |
| CT | 64=Hidden |
Full updated and comparable text;
| | |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CT | Client (user) type, 1=bot, 2=registered user, 4=operator, 8=super user, 16=hub owner, 32=hub (used when the hub sends an INF about itself), 64=Hidden. Multiple types are specified by adding the numbers together. |
#### "Invalid feature" error code {{ '{#invalid_feature_error_code}' }}
This extension will add "Invalid feature" as error code in STA. Invalid
features are features the hub or client deem inappropriate or simply not
welcome. The error code should not be used for features the hub or
client does not know of.
| | |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 48 | Invalid feature. Flag "FC" is the FOURCC of the invalid feature(s). If multiple features are invalid, use comma between the features (i.e. FCQWER,ASDF,ZXCV). |
#### KEYP - Certificate substitution protection in conjunction with ADCS {{ '{#keyp_certificate_substitution_protection_in_conjunction_with_adcs}' }}
This extension adds a simple, but secure way to protect against
man-in-the-middle attacks against ADC when wrapped with TLS (1.0 or
later). It does not require setting up a CA or signing keys, but that is
still possible if desired.
The extension introduces a keyprint parameter to the ADCS URI. The
keyprint parameter is a hash of the server certificate.
The extension also requires clients to publish their own certificates'
keyprint in the KP field in the INF. Assuming one trusts the hub enough
not to maliciously change the keyprints en route (a reasonable
assumption given the hub’s existing position of trust), and given that
the connection to the hub has been similarly authenticated (either as
above or via a directly downloaded trusted certificate), client-client
connections are also protected against attempted man-in-the-middle
attacks - without messing around with having to get everyone’s
certificates signed in advance.
The keyprint parameter consists of a hash name, followed by a forward
slash (*/*), followed by the Base32-encoded cyrptographic hash of the
certificate.
The hash used shall be SHA256. Other extensions may add other hashes,
given sufficient security contemplation.
INF field;
| | |
| -- | -------------------------------------------------------------------- |
| KP | The client’s own certificate keyprint. |
##### Keyprint replacement behaviour {{ '{#keyprint_replacement_behaviour}' }}
If a client receives a KP field in an FINF broadcast via a hub it is
connected to using ADCS and a trusted key as above (or otherwise), it
should be regarded as the valid and correct keyprint for that client’s
IP/port/hub combination, replacing any earlier keyprint for that
IP/port/hub combination.
##### Keyprint verification {{ '{#keyprint_verification}' }}
When initiating a TLS handshake with a remote host where the keyprint is
known, the client can verify that a man-in-the-middle attack is not
occurring by checking if the hash given in the keyprint exactly matches
that of the certificate presented during the handshake by the remote
host.
Suppose the client is aware of a remote host’s keyprint and is in the
process of connecting to that host. A certificate substitution attack is
in place if the hub presents itself with a certificate that does not
match and where the certificate is not the root of the valid signature
chain covering the certificate. If the client detects such an attack,
the client should abort the connection and notify the user with a
message stating, for example, "Crypto error: Detected attempted
man-in-the-middle attack, aborting". (This error quite possibly
represents a real attempted attack that has been foiled; we may try
auto-reconnecting but we should NEVER ignore it, or it will succeed. We
may wish to avoid stating the keyprint of the certificate that was
actually received.)
Optionally, when receiving a TLS handshake, if the client knows what the
remote host’s keyprint ought to be, the client could also verify this.
However, note that only the initiating side needs to check this for the
man-in-the-middle protection to be valid; specifically the hub doesn’t
need to remember, or even understand, clients' keyprints.
##### Security Considerations {{ '{#security_considerations}' }}
###### General {{ '{#general_2}' }}
The certificates, including the name fields, are sent in the clear
during the initial handshake. Therefore it is recommended to avoid
identifying marks in the certificates CommonName fields (for example)
that would clearly single them out as being TLS keys used by ADCS:, and
the CID field most definitely should not appear. Quite possibly no name
fields should appear, or they should be blank.
###### Client-Hub {{ '{#client_hub}' }}
The keyprint in the ADCS URI prevents a clandestine man-in-the-middle
(certificate substitution) attack on the TLS session with the hub, if
and only if the kp parameter hasn’t been modified by an attacker.
Suggested countermeasures against this include the following;
- Even if otherwise unprotected, an attacker would likely only have a
maximum of one opportunity to make the substitution (by changing the
kp parameter when the URL is first sent to the user); if it’s
changed later, it will be detected. ("Casual first-use" security, as
often used in SSH.)
- Checking the fingerprint or transferring the hub URL out-of-band
(for example by telephone, or in person) could reveal or thwart
man-in-the-middle attacks; something’s wrong if you don’t have the
same URL as the hub operator gives out. (PGP-style "sneakernet"
security.)
- We would be protected if the URL were in a file signed by some
secure means by a party we have already decided we trust not to
change the URLs maliciously. Encryption would not be necessary, only
a signature to ensure no untrusted party has modified the KP fields.
(A signed hublist, possibly.)
Finally, we would be protected were the hublist/URL retrieved from an
https: site signed by a CA we trust not to issue signatures for any
domain to someone who doesn’t own that domain, and the owner of that
domain trusted not to modify the KP fields. (SSL-style security.)
###### Client-Client {{ '{#client_client}' }}
We are, in particular, trusting the hub not to maliciously modify the KP
fields sent by the clients through their INF broadcasts. However;
- The hub would gain nothing from swapping the keyprints of its users,
as it would not gain anything from mounting a man-in-the-middle
attack on its own users that it does not already have the ability to
do, as it’s the hub; and
- If the client do not trust the hub enough not to maliciously modify
the data, why is the client choosing to connect to the hub and
transmit the client’s IP address through the hub?
- It could be detected by cross-checking with other clients/hubs, as
connecting through a malicious hub would clearly show to have a
different keyprint to any other hub; therefore any hub doing this
would obviously be quickly removed from hublists.
##### Example {{ '{#example_7}' }}
adcs://example.com:1234/?kp=SHA256/G3PJC4F4MQ5KOXGE2MPYJW5EW63IC6M7RN7OS663JLLWN2M5I6FQ
#### SUDP - Encrypting UDP traffic {{ '{#sudp_encrypting_udp_traffic}' }}
This is an extension that allows UDP traffic to be encrypted.
While assymetric encryption may be optimal in sense of security, a
symmetric cipher will protect perfectly against outside adversaries
given the hub-client connections is also running ADCS. New is that
senders now create a random IV for their "request command" (e.g.
searches) and send it along the "response command" (e.g. search result).
Signal SUDP in SUP and in the INF’s SU field.
If a client signal support for SUDP in an ADCS hub, it may extend
commands that will generate a response (e.g. SCH) with a KY-field as the
encryption key. Clients shall only include the flag in ADCS hubs.
| | |
| -- | ----------------------------------------------------------------------- |
| KY | 16 byte encryption key in BASE32. 128 bit AES encryption shall be used. |
For example, a SCH command will result in 29 Bytes of overhead
("<separator>KY"+26 Bytes Base32 encoded key).
A client that has a response for the command can now encrypt the
response message by prepending 16 bytes of random data and afterwards
encrypting it with AES/CBC/PKCS5Padding (Cipher/Blockmode/Padding) using
16 zero bytes as IV for CBC.
In above scenario, the response would be a RES command.
##### Decryption notes {{ '{#decryption_notes}' }}
In the case of searching, the searching client in return for decryption
first has to guess which commands it receives are encrypted and which
are not. It can do so for example by simply trying decryption with all
currently active keys. If a key is wrong or the message was not
encrypted, padding will fail and decryption is unsuccessful!
Client may otherwise verify if the message is a U-type message, followed
by a known command (and a space). If that is not the case, the client
takes the most recent key and decrypts. If that succeed, the message is
valid.
There is a potential chance that decryption succeed with what is a bad
key. If that is the case, the client should verify that the data is not
garbled.
Note that in a normal circumstance, the client will most likely be using
relatively few active keys.
#### TYPE - Typing notification {{ '{#type_typing_notification}' }}
This extension adds a typing similar to Jabber’s ["Chat state
notifications"](http://www.xmpp.org/extensions/xep-0085.html).
Signal TYPE in SUP and the INF’s SU field.
##### TPN {{ '{#tpn}' }}
TPN code
Contexts: F, T
States: NORMAL
Command should be sent to the Reply-To user (PM field in MSG, if
present). All TPN messages are sent when the event occur.
Code values:
| | | | |
| -- | --------- | ---------------------------------------------------------------------------------- | --------------- |
| 00 | Gone | Closed tab, minimized window, etc | Should be sent. |
| 01 | Inactive | Changed tab, window became unfocused (but not closed or minimized), etc | Should be sent. |
| 02 | Paused | Paused typing. | Should be sent. |
| 10 | Active | Now in this tab, reading message and is actively participating in the chat session | Must be sent. |
| 11 | Composing | Currently typing a message | Must be sent. |
#### FEED - RSS feeds {{ '{#feed_rss_feeds}' }}
The extension adds [RSS feed](http://en.wikipedia.org/wiki/RSS) support.
Signal FEED in SUP and the INF’s SU field.
##### RSS {{ '{#rss}' }}
RSS url
Context: F, T
States: NORMAL
url is the URL to the feed.
Additional fields:
| | |
| -- | ------------------------------------------------------- |
| CR | Name of the author. |
| TI | Name of post. |
| DE | Content summary of post. |
| LI | Direct link to post |
| FN | Feed name |
| FN | Feed description |
| DT | Time of publish. Specified in seconds since UNIX epoch. |
| RM | 1 = Remove feed from aggregator. |
##### Examples {{ '{#examples}' }}
Publish a new feed called *Example_feed* and with a description
*description_of_feed*:
RSS <http://example.com/rss> FNExample_feed FNdescription_of_feed
Remove a feed:
RSS <http://example.com/rss> RM1
Publish a new post *New_post* from *John_Doe*:
RSS <http://example.com/rss> TINew_post DEdescription_of_post LIhttp://example.com/entries/new_post DT1253628000 CRJohn_Doe
#### SEGA - Grouping of file extensions in SCH {{ '{#sega_grouping_of_file_extensions_in_sch}' }}
In BASE, clients add EX fields to SCH to denote which extension files
should have. This can lead to a situation where the large bulk of
extensions are of similar "type", e.g. audio files or documents. This
extension intend to add a field GR which groups multiple extensions. In
addition, the field RX shall be used for group-exclusion; if all
extensions in a group but two are desired, field RX will be used to
exclude those group items.
Signal SEGA in the INF’s SU field for support of this extension.
Field GR values, where multiple groups are specified by adding the
numbers together:
| | | |
| -- | ---------- | ---------------------------------------------------------------------------------------------------- |
| 1 | Audio | APE, FLAC, M4A, MID, MP3, MPC, OGG, RA, WAV, WMA |
| 2 | Compressed | 7Z, ACE, ARJ, BZ2, GZ, LHA, LZH, RAR, TAR, TZ, Z, ZIP |
| 4 | Document | DOC, DOCX, HTM, HTML, NFO, ODF, ODP, ODS, ODT, PDF, PPT, PPTX, RTF, TXT, XLS, XLSX, XML, XPS |
| 8 | Executable | APP, BAT, CMD, COM, DLL, EXE, JAR, MSI, PS1, VBS, WSF |
| 16 | Picture | BMP, CDR, EPS, GIF, ICO, IMG, JPEG, JPG, PNG, PS, PSD, SFW, TGA, TIF, WEBP |
| 32 | Video | 3GP, ASF, ASX, AVI, DIVX, FLV, MKV, MOV, MP4, MPEG, MPG, OGM, PXP, QT, RM, RMVB, SWF, VOB, WEBM, WMV |
Field RX:
| | |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| RX | Extensions in a group that are not desired. E.g., "GR1 RXMP3 RXWAV" would include all extensions in the *audio* group except *MP3* or *WAV*. |
#### FO - Failover hub addresses {{ '{#fo_failover_hub_addresses}' }}
If a hub goes down, the client’s only option is to keep re-trying the
last known hub address. This extension will add a list of failover hub
addresses, field FO, that the client can try to connect to, if the main
hub address fail.
Clients should decide the frequency of connection attempts (for the main
hub as well as the failover addresses). The client should try connecting
in the specified order. The client may decide what to do after the
FO-list is exhausted, but recommended is to try to connect to the main
hub and continue with the list as before.
The client should display an appropriate message to the user that it has
connected to a failover address.
This extension should be implemented, at a minimum, for favourite hubs.
If clients have any concerns about where a hub may redirect users to, or
about storing the extra state information, then it may avoid
implementing this for non-favourite hubs.
Field FO in the hub’s INF:
| | |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FO | Failover hub addresses. Specify well formed ADC or ADCS URI addresses, with multiple addresses separated with a comma. Example; FOadc://example.com:1234,adc://example.net:1234 |
#### FS - Free slots in client {{ '{#fs_free_slots_in_client}' }}
This is an extension that will broadcast the amount of free slots the
client has available.
Field FS in the client’s INF:
| | |
| -- | ---------------------- |
| FS | Free slots available. |
#### ADCS - Symmetrical Encryption in ADC {{ '{#adcs_symmetrical_encryption_in_adc}' }}
ADCS is an extension that has the goal of adding the TLS/SSL layer just
over the TCP layer and beneath the application layer (where ADC runs).
This way, the ADC protocol remains unchanged while the connections are
encrypted. The connecting party performs a TLS handshake immediately
after the TCP connection is established. The ADC handshake is performed
and once the TLS connection is established the ADC handshake proceeds as
usual.
Encrypted ADC connections can be established using a TLS tunnel, both
for hub and for client connections. Certificates can be used to
authenticate both hub and user, for example by making the hub the root
CA, and only allow clients signed by the hub to connect. Ephemeral keys
should be use to ensure forward secrecy when possible. A future
extension or revision of this extension will provide ways to handle
certificate based logins, who creates which certificates and who signs
what, and all that is not specified in this revision.
##### Client-Hub encryption {{ '{#client_hub_encryption}' }}
TLS client-hub connections can be initiated either by negotiating the
feature "ADCS" on connection or by using the protocol adcs:// when
initiating the connection.
##### Client-Client encryption {{ '{#client_client_encryption}' }}
TLS client-client connections can be established either by negotiating
the feature "ADCS" on connection or by specifying "ADCS/1.0" in the CTM
protocol field. Clients supporting encrypted connections must indicate
this in the INF SU field with "ADCS".
#### Application and version separation in INF {{ '{#application_and_version_separation_in_inf}' }}
This extension adds the parameter *AP* to the INF to signal application.
The current parameter in BASE, VE, will be used for version signalling.
Example:
BINF BBBB APDCPLUSPLUS VE0.782
#### ONID - Online identification {{ '{#onid_online_identification}' }}
The purpose of the OID and OIR commands is to allow users to exchange
information about their accounts on various online services. The OID
name has been intentionally chosen to be similar to OpenID, although its
spread is broader.
New commands are preferrable here over new INF fields to avoid clogging
up its 2-letter identifiers. They also allow for more flexibility:
multiple profiles of the same type (OIR only); multiple identification
parameters.
The OID command is similar to INF, guaranteeing up-to-date information,
whereas OIR follows a request/response scheme. OIR parties are therefore
not required to keep their OIR information up-to-date.
Parties supporting OID commands MUST advertise the ONID (ONline
IDentification) support in the SU field of their INF.
Parameters of the OID and OIR commands:
- Unnamed parameter in first position to designate the service this
command is referring to. Known services are listed in the "Known
ONID services" (ADC-ONIDServices.txt) document; they are matched
case-insensitively. Implementers willing to use an unlisted service
SHOULD let ADC managers know about it.
- Optional named parameters whose meanings depend on the service in
question.
OID and OIR commands support all contexts (hub-client, client-client).
They are allowed in client-client contexts were users to want to avoid
their OID/OIR information travelling through hubs. Both clients and hubs
MAY provide each other with OID/OIR information.
##### OID {{ '{#oid}' }}
OID service
Any party that has sent OID information about itself SHOULD keep it
up-to-date.
OID parties MAY provide no information, usually indicating a refusal or
inability to communicate it.
Hubs that advertise ONID support MUST dispatch OID information they have
received from clients to new clients logging in, similary to INF
information.
Clients MAY send OID commands to other clients on hubs that do not
advertise ONID support.
##### OIR {{ '{#oir}' }}
OIR service
The requesting party MUST send an OIR command with a service parameter
only (no optional parameter). The responding party MAY answer with an
OIR command containing that same service parameter, and relevant
optional parameters.
The responding party MAY send multiple OIR commands in response to one
request.
The responding party MAY provide no information, usually indicating a
refusal or inability to communicate it.
Any party MAY at any time send an OIR response without any prior
request.
##### Examples {{ '{#examples_2}' }}
| Command | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| BOID BBBB LoL SUtest SEkr | A notification of League of Legends service with the summoner name "test" in the region "Korea". |
| BOID BBBB LoL SUtest2 | An updated notification of the League of Legends service with the new summoner name "test2". |
| BOIR BBBB Google <[email protected]> | A notification of the Google service with the e-mail "[email protected]". |
| BOIR BBBB mslive <[email protected]> | A notification of the Microsoft Live service with the e-mail "[email protected]". |
| BOIR BBBB mslive | A request for notifications of the Microsoft Live service. |
| DOIR CCCC BBBB mslive <[email protected]> | A response for the notification request from BBBB. |
#### "ADCS transfers are required" error code {{ '{#adcs_transfers_are_required_error_code}' }}
This extension will add "ADCS transfers are required" as error code in
STA. A client that has chosen to only allow encrypted transfers (with
ADCS) should send this when a user without ADCS support tries to
initiate a connection (via CTM/RCM etc).
| | |
| -- | -------------------------------------------------------------------------------------- |
| 62 | ADCS transfers are required. Flag "TO" is the token in the transfer request. |
#### ASCH - Extended searching capability {{ '{#asch_extended_searching_capability}' }}
This extension will increase searching capability in BASE. The extension
also imply that searching in partial file lists are now easier.
Signal ASCH in the INF’s SU field.
The SCH command is extended to request a response (STA) indicating how
many search results were sent. This will allow clients to indicate that
all search results have been received (and can aptly indicate as such to
the user). STA severity 0 and code 00 should be used.
Additional SCH fields:
| | |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MT | Matching options. Only applies to search terms (AD) and not excluded terms (EX). |
| PP | Indicating whether the responding party should send the parent path of the matching item. For files the result should be for the containing files and for directories the result is for the parent directory. The responder should check that only one result is sent for each directory. This is useful when searching in a partial list, so the requester can then download the partial list from a correct path and locate the matching items in the directory by itself (less search results to send). |
| OT | Older than. Newest possible (absolute) time for a responded item. Time specified is seconds since the Unix epoch. |
| NT | Newer than. Oldest possible (absolute) time for a responded item. Time specified is seconds since the Unix epoch. |
| MR | Maximum number of wanted results (implementations should be conservative in which message type). The responder may also choose to send less results if the requested count isn’t reasonable. |
| PA | Path in the share where to search from (relative to the unnamed root). This only makes sense for certain message types. |
| RE | Require a STA reply. This only makes sense for certain message types. |
MT field:
| | |
| - | -------------------------------------------------------------------------------------- |
| 1 | Match full path (partial match). |
| 2 | Match file/directory name only (partial match). |
| 3 | Match file/directory name only (exact match). |
PP field:
| | |
| - | -------------------------------------------------------------------------------------- |
| 1 | Send parent path. |
RE field:
| | |
| - | -------------------------------------------------------------------------------------- |
| 1 | Require a reply. |
Additional RES fields:
| | |
| -- | ------------------------------------------------------------------------------------- |
| FI | Number of files in a directory (recursive, directory search results only). |
| FO | Numbers of folders in a directory (recursive, directory search results only). |
| DA | Modified date of a file or directory. Time specified is seconds since the Unix epoch. |
Additional STA fields:
| | |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FC | The FCC of the search command (e.g. BSCH, DSCH). |
| TO | Search token. |
| RC | Number of results sent. The client receiving the search should still send the STA with a 0 here, in the event that there were not hits to the aformentioned search. |
#### *Date* attribute in file list for files and directories {{ '{#emphasis_date_emphasis_attribute_in_file_list_for_files_and_directories}' }}
This extension adds a *Date* attribute to files and directories in a
file list. The attribute is the last modified date of the file or
directory. Time specified is seconds since the Unix epoch.
Implementations should be conservative when it includes the Date
attribute. Only including the attribute in partial file lists can
decrease overall network load requirements.
The following changes are done to the file list XML schema:
A new attribute is defined:
<xs:attribute name="Date" type="xs:unsignedLong" />
The attribute is then referenced in the File and Directory element:
<xs:attribute ref="Date" use="optional" />
#### *Size* attribute in file list for directories {{ '{#emphasis_size_emphasis_attribute_in_file_list_for_directories}' }}
This extension adds a *Size* attribute to directories in a file list.
The attribute is the size of the directory as indicated in a RES.
Implementations should be conservative when it includes the Size
attribute.
This attribute only makes sense in partial file lists (as it can be
calculated in full lists).
The following change is done to the file list XML schema:
The Size attribute from BASE is referenced in the Directory element:
<xs:attribute ref="Size" use="optional" />
#### *Children* attribute in file list for directories {{ '{#emphasis_children_emphasis_attribute_in_file_list_for_directories}' }}
This extension adds a *Children* attribute to directories in a file
list. The attribute indicates whether there are additional
sub-directories.
Value *1* indicate that there are children.
This attribute only makes sense in partial file lists.
The following changes are done to the file list XML schema:
A new attribute is defined:
<xs:attribute name="Children" type="zeroOne" />
The attribute is then referenced in the Directory element:
<xs:attribute ref="Children" use="optional" />
#### Downloaded progress report for uploaders in GET {{ '{#downloaded_progress_report_for_uploaders_in_get}' }}
The info in the current GET command does not permit displaying relative
upload progress for the uploading party (for the whole file).
To address this, this extension will add an additional field to the GET
command for current downloaded (and verified) bytes before the request
has been sent. While still not entirely accurate with this information,
the uploader can see how much of the file the requesting party actually
has instead of either assuming that the requester has the file up to the
start position of the request or being forced to only show the progress
of the currently requested part of the file. There is potentially a
slight delay in the reporting of this info in scenarios where more than
one segment of a file is simultaneously requested (by the downloader)
and the uploader still lacks information about how many other sources
the file is being downloaded from.
| | |
| -- | --------------------------------- |
| DB | Downloaded (and verified) bytes. |
#### RDEX - Redirects Extended {{ '{#rdex_redirects_extended}' }}
The goal of this extension is to enhance the redirect capabilities
provided by BASE by adding support for two new redirect operations and a
way for hubs and clients to communicate accepted redirect protocols. It
also attempts to make the concept of redirects more unambiguous and less
implementation defined. The two new types of redirects added are a
multiple choice redirect and so-called permanent redirect as outlined
below. These new redirect types are not necessarily mutually exclusive.
##### Redirect Security {{ '{#redirect_security}' }}
Hubs should always aim to include as much information pertaining to a
redirect as possible using other fields defined in BASE. Clients may,
for example, rely on the availability of such information to check the
origin of a redirect before making irreversible decisions, such as
accepting a redirect as permanent as defined below.
Clients should not attempt to connect to an unreachable or otherwise
invalid destination resources indefinitely or in otherwise abusive
manner when responding to redirects. Whether clients respond to
redirects using default user information or the same information as used
on the hub that initiated the redirect is implementation defined,
however, in the case that the same information is used careful
consideration should be taken when it comes to automatically sending
sensitive information such as passwords to other hubs especially if it
provides less security to the user than the original hub.
Both clients and hubs should also take note that the TL field, as
defined by BASE, should only impact the current hub and its connection
(if re-established) thus it should not be relied on to trigger a delayed
response to a redirect.
##### Accepted Redirect Protocols {{ '{#accepted_redirect_protocols}' }}
Support for this extension is indicated by the presence of an RP field
in the INF, which defines the accepted redirect protocols for the hub or
a client as a bitmask using any combination of following values.
Additional compatible values may be defined by other extensions.
| Protocol | URI Syntax | Flag |
| ------------------------------------------------------- | -------------------------------- | ---- |
| User action (exclusive) | any supported, as defined below | 0 |
| ADC (BASE) | adc://adress:port | 1 |
| [ADCS Extension](#_adcs_symmetrical_encryption_in_adc) | adcs://address:port | 2 |
| [NeoModus Direct Connect](http://nmdc.sf.net) | dchub://address\[:port\] | 4 |
Hubs should treat the absence of the RP field in clients INF as the
equivalent of RP with the value of one, thus implying support for BASE.
If the ADCS feature is included in the clients feature list this may
also be amended to include ADCS. If a client does not define an RP field
the hub may choose to omit the RDEX syntax from redirects, although this
extension retains full backwards compatibility with BASE. If a hub
defines an RP field for itself it should prevent its users from
redirecting others to protocols it did not define, including redirects
to destinations without an explicit protocol handler. Hubs should always
aim to use fully qualified resource identifiers for all redirects,
regardless of whether an RP field is defined or not, to avoid ambiguous
destinations due to implementation defined default handling.
Clients should refrain from removing support of a previously signalled
redirect protocol from their RP field. It is up to the hub to decide a
corresponding course of action should the client do so. Additionally a
special case is defined for clients as an RP field with the value of
zero to indicate that the client may not react to redirects as defined
by BASE or this extension at all or may do so only as a result of user
action. As such clients defining a non-zero RP field should follow
redirects to accepted protocols automatically and conversely any
attempts to redirect clients that define RP as zero should result in
normal disconnection as per BASE.
##### Multiple Choice Redirect {{ '{#multiple_choice_redirect}' }}
Multiple choice redirect is defined as a redirect where instead of a
single destination resource a set of resource identifiers is provided.
The methodology that is used to select the final destination resource
for a multiple choice redirect is implementation defined. However, only
one final destination resource may be chosen. For example a particular
implementation may prefer one protocol over another, encrypted
connection over an unencrypted one or even simply choose one at random.
This type of redirect is signalled by the presence of an additional RX
field in the QUI as defined for redirects by BASE. The value of the RX
field is a comma separated list of resource identifiers to use in the
redirect. The RD field should be defined for maximum compatibility and
clients should add its value to the list of identifiers defined in RX
when selecting the final destination resource.
##### Permanent Redirect {{ '{#permanent_redirect}' }}
Permanent redirect is defined as a redirect with reference updating. In
the case of a permanent redirect, if and only if a successful connection
is made to the destination resource, the connecting party will then
update all relevant references of the original resource to the
destination resource. Examples of such references may be hublist records
for pingers or favorite entries for clients.
This type of redirect is signalled by the presence of an additional PT
field in the QUI, as defined for redirects by BASE, with the value of
one. Upon receiving such redirect clients will proceed to update
references as outlined above provided the conditions are met.
##### Examples {{ '{#examples_3}' }}
Multiple Choice Redirect (BASE compliant)
| Example | Description |
| -------------------------------------------------------------------------------------------------- | --------------------------------- |
| IQUI BBBB IDAAAA RDadc://example.com:1001 RXadcs://example.com:1002,adc://example.org:1020 | Here user BBBB is presented with a choice between three destinations Two on example.com and one on example.org. Old and non-supporting clients will be redirected to adc://example.com:1001. User AAAA is the originator for this redirect. |
Multiple Choice Redirect (RDEX only, not compatible with old clients thus not recommended)
| Example | Description |
| -------------------------------------------------------------------------------------------------- | --------------------------------- |
| IQUI BBBB IDAAAA RXadc://example.com:1001,adcs://example.com:1002,adc://example.org:1020 | For clients supporting RDEX this is the same as sending the first example. Old and non-supporting clients will be disconnected and they might reconnect to the original hub after an implementation defined time. |
Permanent Redirect
| Example | Description |
| -------------------------------------------------------------------------------------------------- | --------------------------------- |
| IQUI BBBB IDAAAA MSWe’re\smoving! RDadc://example.com:1001 PT1 | Here user BBBB will be redirected to adc://example.com:1001 with the message of "We’re moving!" and AAAA as the originator. BBBB should (see section Redirect Security) connect directly to adc://example.com:1001 in the future. |
Permanent Multiple Choice Redirect
| Example | Description |
| -------------------------------------------------------------------------------------------------- | --------------------------------- |
| IQUI BBBB IDAAAA MSWe\shave\sADCS\snow! RDadc://example.com:1001 RXadcs://example.com:1002 PT1 TL0 | Here user BBBB is redirected permanently with a choice between ADC and ADCS URI, if and only if either of the URI’s matches the URI of the current hub connection and the matching URI is chosen BBBB will reconnect immediately. Sending a redirect like this to all connected clients (once) can be used to attempt to migrate them to ADCS instance of a hub. |
[^1]: B. Ford and P. Srisuresh and and D. Kegel. "Peer-to-Peer
Communication Across Network Address Translators". In USENIX
Technical Conference 2005 - pages 179–192. Online version:
<http://www.brynosaurus.com/pub/net/p2pnat/>