Protocols/OSCAR/Services/Rendezvous: Difference between revisions

From NINA Wiki
Jump to navigation Jump to search
No edit summary
 
(8 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{Protocols/OSCAR}}


X
== ICBM ==


=== IM ===
=== Datatype: ICBM__IM_RENDEZVOUS ===
X
 
There are three different types of rendezvous messages - propose, cancel, and accept.
 
==== PROPOSE ====
 
This is the message that a client sends to the server to propose a rendezvous with another client. The tag values to be used in the TLV are the ones specified in RENDEZVOUS_TLV_TAGS. Proposals typically specify either a RENDEZVOUS__CHANNEL or a RENDEZVOUS_IP_ADDR/PORT pair. If neither is specified, the systems which are rendezvousing must know out-of-band how to connect to each other (e.g., a server IP_ADDR compiled into a third party client).
 
If specifying RENDEZVOUS_IP_ADDR, the client may also specify PROPOSER_IP_ADDR which is the IP address that it identifies itself by, as found by a call to get_local_host. If PROPOSER_IP_ADDR is used, VERIFIED_IP_ADDR is added by the server before sending the RENDEZVOUS_PROPOSAL_TO_CLIENT.
 
VERIFIED_IP_ADDR may not be specified by the client in RENDEZVOUS_PROPOSAL_TOHOST. Likewise, if DOWNLOAD_URL is specified and the service UUID matches a well known service, the server may add VERIFIED_DOWNLOAD_URL. The client may not specify VERIFIED_DOWNLOAD_URL itself.
 
Additionally, the client can send any tags specific to a given service as long as the tag values fall outside the reserved range defined above.
 
NOTE: Reserved tag values MUST be at the beginning of the TLV. The server will stop parsing the TLV as soon as it encounters the first non-reserved tag.
 
==== CANCEL ====
 
This message is sent by the sender of a RENDEZVOUS_PROPOSAL_TOCLIENT in order to indicate a desire to cancel the rendezvous. Note that due to timing issues, the cancel may arrive at the other client after the other client has acted on the rendezvous proposal.
 
In other words, cancel is an advisory message only. The sender should take other precautions to prevent a rendezvous attempt from succeeding (e.g., shut down any systems which are listening, etc.).
 
==== ACCEPT ====
 
This message is sent by the recipient of a PROPOSE in order to indicate that it has completed the rendezvous. It may contain modifications to the original PROPOSE TLVs indicating different levels of feature support (e.g., version negotiation).
 
{| class="wikitable"
! Name
! Type
! Notes
|-
| type
| uint16 (word)
| ''[Class: [[Protocols/OSCAR/Services/Rendezvous#Class:_ICBM_RENDEZVOUS_MESSAGE|ICBM__RENDEZVOUS_MESSAGE]]]'' What kind of rendezvous message is this
|-
| cookie
| [[Protocols/OSCAR/Foodgroups/ICBM#Datatype:_Cookie|ICBM Cookie]]
| Opaque data generated by conversation initiator and used to link up the conversation and errors
|-
| service
| [[Protocols/OSCAR/UUIDs|UUID]]
| Identifies type of data message being exchanged
|-
| params
| Rest of SNAC array of [[Protocols/OSCAR/TLV|TLV]]
| ''[Class: [[Protocols/OSCAR/Services/Rendezvous#TLV_Class:_ICBM_RENDEZVOUS_TAGS|ICBM__RENDEZVOUS_TAGS]]]'' Message data and parameters
|}
 
=== Class: ICBM__RENDEZVOUS_MESSAGE ===
 
This is a type of rendezvous/data message.
 
{| class="wikitable"
! Name
! Value
! Notes
|-
| RENDEZVOUS_MESSAGE_PROPOSE
| 0x00
| Propose a rendezvous
|-
| RENDEZVOUS_MESSAGE_CANCEL
| 0x01
| Cancel a proposal you generated
|-
| RENDEZVOUS_MESSAGE_ACCEPT
| 0x02
| Accept a proposal someone else generated
|-
| RENDEZVOUS_MESSAGE_NAK
| 0x03
| NOT CURRENTLY DOCUMENTED
|}
 
=== Class: ICBM__RENDEZVOUS_CANCEL_REASONS ===
 
These are the reasons a proposal is cancelled.
 
{| class="wikitable"
! Name
! Value
! Notes
|-
| RENDEZVOUS_CANCEL_REASONS_UNKNOWN
| 0x00
| Reason not specified
|-
| RENDEZVOUS_CANCEL_REASONS_USER_CANCEL
| 0x01
| Recipient user declined
|-
| RENDEZVOUS_CANCEL_REASONS_TIMEOUT
| 0x02
| Timeout
|-
| RENDEZVOUS_CANCEL_REASONS_ACCEPTED_ELSEWHERE
| 0x03
| Proposal was accepted by a different instance of the user
|}
 
=== Class: ICBM__RENDEZVOUS_NAK ===
 
Sent in ICBM__CLIENT_ERR errorInfo field
 
{| class="wikitable"
! Name
! Value
! Notes
|-
| RENDEZVOUS_NAK_PROPOSAL_UNSUPPORTED
| 0x00
| Proposal UUID not supported
|-
| RENDEZVOUS_NAK_PROPOSAL_DENIED
| 0x01
| Not authorized, or user declined
|-
| RENDEZVOUS_NAK_PROPOSAL_IGNORED
| 0x02
| DO NOT USE; 'ignores' should no-op
|-
| RENDEZVOUS_NAK_BUSTED_PARAMETERS
| 0x03
| Proposal malformed
|-
| RENDEZVOUS_NAK_PROPOSAL_TIMED_OUT
| 0x04
| Attempt to act on proposal (e.g. connect) timed out
|-
| RENDEZVOUS_NAK_ONLINE_BUT_NOT_AVAILABLE
| 0x05
| Recipient away or busy
|-
| RENDEZVOUS_NAK_INSUFFICIENT_RESOURCES
| 0x06
| Recipient had internal error
|-
| RENDEZVOUS_NAK_RATELIMITED
| 0x07
| Recipient was ratelimited
|-
| RENDEZVOUS_NAK_NO_DATA
| 0x08
| Recipient had nothing to send
|-
| RENDEZVOUS_NAK_NO_VERSION_MISMATCH
| 0x09
| Incompatible versions
|-
| SECURITY_MISMATCH
| 0x0A
| Incompatible security settings
|-
| SERVICE_SPECIFIC_REASON
| 0x0F
| Service-specific reject defined by client
|}
 
=== TLV Class: ICBM__RENDEZVOUS_TAGS ===
 
These are the tags inside the DATA TLV of the RENDEZVOUS channel in ICBM.
 
{| class="wikitable"
! Name
! Tag
! Type
! Notes
|-
| RENDEZVOUS_TLV_TAGS_RENDEZVOUS_CHANNEL
| 0x0001
| uint16 (word)
| ICBM channel on which the rendezvous is to occur
|-
| RENDEZVOUS_TLV_TAGS_RENDEZVOUS_IP_ADDR
| 0x0002
| uint32 (dword)
| IP address proposed for the rendezvous
|-
| RENDEZVOUS_TLV_TAGS_REQUESTER_IP_ADDR
| 0x0003
| uint32 (dword)
| IP address of the proposing client
|-
| RENDEZVOUS_TLV_TAGS_VERIFIED_IP_ADDR
| 0x0004
| uint32 (dword)
| IP address of the proposing client as seen by server; NOTE - this TLV may only be added by the server
|-
| RENDEZVOUS_TLV_TAGS_PORT
| 0x0005
| uint16 (word)
| Port value of the client for rendezvous
|-
| RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL
| 0x0006
| string
| URL for downloading software to support the service
|-
| RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL2
| 0x0007
| string
| NOT CURRENTLY DOCUMENTED
|-
| RENDEZVOUS_TLV_TAGS_VERIFIED_DOWNLOAD_URL
| 0x0008
| string
| Same as DOWNLOAD_URL, but added by server if the service is well known; Note - this TLV may only be added by the server
|-
| RENDEZVOUS_TLV_TAGS_SEQUENCE_NUM
| 0x000A
| uint16 (word)
| Identifies which proposal this is in the rendezvous conversation; the initial proposal has sequence_num 1; NOTE - this tag is required in *all* rendezvous *proposal* payloads and may only occur in proposal payloads; each proposal applying to a given rendezvous cookie increments the sequence_num by one
|-
| RENDEZVOUS_TLV_TAGS_CANCEL_REASON
| 0x000B
| uint16 (word)
| ''[Class: [[Protocols/OSCAR/Services/Rendezvous#Class:_ICBM_RENDEZVOUS_CANCEL_REASONS|ICBM__RENDEZVOUS_CANCEL_REASONS]]]'' Reason for cancelling a rendezvous; this tag must be present in all RENDEZVOUS_CANCEL payloads.
|-
| RENDEZVOUS_TLV_TAGS_INVITATION
| 0x000C
| string
| Text inviting the other player to join
|-
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_CHARSET
| 0x000D
| string
| Charset used by the data
|-
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_LANG
| 0x000E
| string
| Language used by the data
|-
| RENDEZVOUS_TLV_TAGS_REQUEST_HOST_CHECK
| 0x000F
| empty
| Requests that the server check caps for recipient
|-
| RENDEZVOUS_TLV_TAGS_USE_ARS
| 0x0010
| empty
| Requests that the Rendezvous Server be used as a transport for the data
|-
| RENDEZVOUS_TLV_TAGS_REQUEST_SECURE
| 0x0011
| empty
| Requests that SSL be used for the connection
|-
| RENDEZVOUS_TLV_TAGS_MAX_PROTOCOL_VERSION
| 0x0012
| uint16 (word)
| Maximum application protocol version supported
|-
| RENDEZVOUS_TLV_TAGS_MIN_PROTOCOL_VERSION
| 0x0013
| uint16 (word)
| Minimum application protocol version supported
|-
| RENDEZVOUS_TLV_TAGS_COUNTER_REASON
| 0x0014
| uint16 (word)
| Reason for a counter proposal
|-
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_TYPE
| 0x0015
| string
| Content-type used by the data
|-
| RENDEZVOUS_TLV_TAGS_IP_ADDR_XOR
| 0x0016
| uint32 (dword)
| Contains IP_ADDR ^ 0xFFFFFFFF - Used with recent clients to ensure that the IP_ADDR tlv is not tampered with or modified by a NAT since some NATs will change the IP_ADDR tlv when the proposal is sent
|-
| RENDEZVOUS_TLV_TAGS_PORT_XOR
| 0x0017
| uint16 (word)
| PORT ^ 0xFFFF - Used with recent clients to ensure that the PORT tlv is not tampered with or modified by a NAT since some NATs will change the PORT tlv when the proposal is sent
|-
| RENDEZVOUS_TLV_TAGS_ADDR_LIST
| 0x0018
| Array of string08
| List of "IP port" pairs to try
|-
| RENDEZVOUS_TLV_TAGS_SESSION_ID
| 0x0019
| string
| Identifier for session
|-
| RENDEZVOUS_TLV_TAGS_ROLLOVER_ID
| 0x001A
| string
| Identifier of session to rollover
|-
| RENDEZVOUS_TLV_TAGS_SERVICE_DATA
| 0x2711
| blob
| Service specific data
|}
 
[[Category:Stub]]
[[Category:AOL]]
[[Category:AIM]]
[[Category:Protocols/OSCAR]]
[[Category:Protocols/OSCAR/Services]]
[[Category:Work_In_Progress]]

Latest revision as of 03:32, 5 October 2023

OSCAR Protocol
Introduction • Terms • Clients
Basic
Datatypes • FLAP • SNAC • TLV
UUIDs • Errors • Tool IDs
Host Interaction
Rate Limits • Migration • Messages
Other Services
ADMIN • ADVERT • ALERT
BART • BOS • BUCP • CHAT
CHAT_NAV
Tutorials
Sign On • BART • Rendezvous
ICBM • Locate • Buddies
Foodgroups
OSERVICE (0x0001)
LOCATE (0x0002)
BUDDY (0x0003)
ICBM (0x0004)
ADVERT (0x0005)
INVITE (0x0006)
ADMIN (0x0007)
POPUP (0x0008)
PD (0x0009)
USER_LOOKUP (0x000A)
STATS (0x000B)
TRANSLATE (0x000C)
CHAT_NAV (0x000D)
CHAT (0x000E)
ODIR (0x000F)
BART (0x0010)
FEEDBAG (0x0013)
ICQ (0x0015)
BUCP (0x0017)
ALERT (0x0018)
PLUGIN (0x0022)
UNNAMED_FG_24 (0x0024)
MDIR (0x0025)
ARS (0x044A)


ICBM

Datatype: ICBM__IM_RENDEZVOUS

There are three different types of rendezvous messages - propose, cancel, and accept.

PROPOSE

This is the message that a client sends to the server to propose a rendezvous with another client. The tag values to be used in the TLV are the ones specified in RENDEZVOUS_TLV_TAGS. Proposals typically specify either a RENDEZVOUS__CHANNEL or a RENDEZVOUS_IP_ADDR/PORT pair. If neither is specified, the systems which are rendezvousing must know out-of-band how to connect to each other (e.g., a server IP_ADDR compiled into a third party client).

If specifying RENDEZVOUS_IP_ADDR, the client may also specify PROPOSER_IP_ADDR which is the IP address that it identifies itself by, as found by a call to get_local_host. If PROPOSER_IP_ADDR is used, VERIFIED_IP_ADDR is added by the server before sending the RENDEZVOUS_PROPOSAL_TO_CLIENT.

VERIFIED_IP_ADDR may not be specified by the client in RENDEZVOUS_PROPOSAL_TOHOST. Likewise, if DOWNLOAD_URL is specified and the service UUID matches a well known service, the server may add VERIFIED_DOWNLOAD_URL. The client may not specify VERIFIED_DOWNLOAD_URL itself.

Additionally, the client can send any tags specific to a given service as long as the tag values fall outside the reserved range defined above.

NOTE: Reserved tag values MUST be at the beginning of the TLV. The server will stop parsing the TLV as soon as it encounters the first non-reserved tag.

CANCEL

This message is sent by the sender of a RENDEZVOUS_PROPOSAL_TOCLIENT in order to indicate a desire to cancel the rendezvous. Note that due to timing issues, the cancel may arrive at the other client after the other client has acted on the rendezvous proposal.

In other words, cancel is an advisory message only. The sender should take other precautions to prevent a rendezvous attempt from succeeding (e.g., shut down any systems which are listening, etc.).

ACCEPT

This message is sent by the recipient of a PROPOSE in order to indicate that it has completed the rendezvous. It may contain modifications to the original PROPOSE TLVs indicating different levels of feature support (e.g., version negotiation).

Name Type Notes
type uint16 (word) [Class: ICBM__RENDEZVOUS_MESSAGE] What kind of rendezvous message is this
cookie ICBM Cookie Opaque data generated by conversation initiator and used to link up the conversation and errors
service UUID Identifies type of data message being exchanged
params Rest of SNAC array of TLV [Class: ICBM__RENDEZVOUS_TAGS] Message data and parameters

Class: ICBM__RENDEZVOUS_MESSAGE

This is a type of rendezvous/data message.

Name Value Notes
RENDEZVOUS_MESSAGE_PROPOSE 0x00 Propose a rendezvous
RENDEZVOUS_MESSAGE_CANCEL 0x01 Cancel a proposal you generated
RENDEZVOUS_MESSAGE_ACCEPT 0x02 Accept a proposal someone else generated
RENDEZVOUS_MESSAGE_NAK 0x03 NOT CURRENTLY DOCUMENTED

Class: ICBM__RENDEZVOUS_CANCEL_REASONS

These are the reasons a proposal is cancelled.

Name Value Notes
RENDEZVOUS_CANCEL_REASONS_UNKNOWN 0x00 Reason not specified
RENDEZVOUS_CANCEL_REASONS_USER_CANCEL 0x01 Recipient user declined
RENDEZVOUS_CANCEL_REASONS_TIMEOUT 0x02 Timeout
RENDEZVOUS_CANCEL_REASONS_ACCEPTED_ELSEWHERE 0x03 Proposal was accepted by a different instance of the user

Class: ICBM__RENDEZVOUS_NAK

Sent in ICBM__CLIENT_ERR errorInfo field

Name Value Notes
RENDEZVOUS_NAK_PROPOSAL_UNSUPPORTED 0x00 Proposal UUID not supported
RENDEZVOUS_NAK_PROPOSAL_DENIED 0x01 Not authorized, or user declined
RENDEZVOUS_NAK_PROPOSAL_IGNORED 0x02 DO NOT USE; 'ignores' should no-op
RENDEZVOUS_NAK_BUSTED_PARAMETERS 0x03 Proposal malformed
RENDEZVOUS_NAK_PROPOSAL_TIMED_OUT 0x04 Attempt to act on proposal (e.g. connect) timed out
RENDEZVOUS_NAK_ONLINE_BUT_NOT_AVAILABLE 0x05 Recipient away or busy
RENDEZVOUS_NAK_INSUFFICIENT_RESOURCES 0x06 Recipient had internal error
RENDEZVOUS_NAK_RATELIMITED 0x07 Recipient was ratelimited
RENDEZVOUS_NAK_NO_DATA 0x08 Recipient had nothing to send
RENDEZVOUS_NAK_NO_VERSION_MISMATCH 0x09 Incompatible versions
SECURITY_MISMATCH 0x0A Incompatible security settings
SERVICE_SPECIFIC_REASON 0x0F Service-specific reject defined by client

TLV Class: ICBM__RENDEZVOUS_TAGS

These are the tags inside the DATA TLV of the RENDEZVOUS channel in ICBM.

Name Tag Type Notes
RENDEZVOUS_TLV_TAGS_RENDEZVOUS_CHANNEL 0x0001 uint16 (word) ICBM channel on which the rendezvous is to occur
RENDEZVOUS_TLV_TAGS_RENDEZVOUS_IP_ADDR 0x0002 uint32 (dword) IP address proposed for the rendezvous
RENDEZVOUS_TLV_TAGS_REQUESTER_IP_ADDR 0x0003 uint32 (dword) IP address of the proposing client
RENDEZVOUS_TLV_TAGS_VERIFIED_IP_ADDR 0x0004 uint32 (dword) IP address of the proposing client as seen by server; NOTE - this TLV may only be added by the server
RENDEZVOUS_TLV_TAGS_PORT 0x0005 uint16 (word) Port value of the client for rendezvous
RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL 0x0006 string URL for downloading software to support the service
RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL2 0x0007 string NOT CURRENTLY DOCUMENTED
RENDEZVOUS_TLV_TAGS_VERIFIED_DOWNLOAD_URL 0x0008 string Same as DOWNLOAD_URL, but added by server if the service is well known; Note - this TLV may only be added by the server
RENDEZVOUS_TLV_TAGS_SEQUENCE_NUM 0x000A uint16 (word) Identifies which proposal this is in the rendezvous conversation; the initial proposal has sequence_num 1; NOTE - this tag is required in *all* rendezvous *proposal* payloads and may only occur in proposal payloads; each proposal applying to a given rendezvous cookie increments the sequence_num by one
RENDEZVOUS_TLV_TAGS_CANCEL_REASON 0x000B uint16 (word) [Class: ICBM__RENDEZVOUS_CANCEL_REASONS] Reason for cancelling a rendezvous; this tag must be present in all RENDEZVOUS_CANCEL payloads.
RENDEZVOUS_TLV_TAGS_INVITATION 0x000C string Text inviting the other player to join
RENDEZVOUS_TLV_TAGS_INVITE_MIME_CHARSET 0x000D string Charset used by the data
RENDEZVOUS_TLV_TAGS_INVITE_MIME_LANG 0x000E string Language used by the data
RENDEZVOUS_TLV_TAGS_REQUEST_HOST_CHECK 0x000F empty Requests that the server check caps for recipient
RENDEZVOUS_TLV_TAGS_USE_ARS 0x0010 empty Requests that the Rendezvous Server be used as a transport for the data
RENDEZVOUS_TLV_TAGS_REQUEST_SECURE 0x0011 empty Requests that SSL be used for the connection
RENDEZVOUS_TLV_TAGS_MAX_PROTOCOL_VERSION 0x0012 uint16 (word) Maximum application protocol version supported
RENDEZVOUS_TLV_TAGS_MIN_PROTOCOL_VERSION 0x0013 uint16 (word) Minimum application protocol version supported
RENDEZVOUS_TLV_TAGS_COUNTER_REASON 0x0014 uint16 (word) Reason for a counter proposal
RENDEZVOUS_TLV_TAGS_INVITE_MIME_TYPE 0x0015 string Content-type used by the data
RENDEZVOUS_TLV_TAGS_IP_ADDR_XOR 0x0016 uint32 (dword) Contains IP_ADDR ^ 0xFFFFFFFF - Used with recent clients to ensure that the IP_ADDR tlv is not tampered with or modified by a NAT since some NATs will change the IP_ADDR tlv when the proposal is sent
RENDEZVOUS_TLV_TAGS_PORT_XOR 0x0017 uint16 (word) PORT ^ 0xFFFF - Used with recent clients to ensure that the PORT tlv is not tampered with or modified by a NAT since some NATs will change the PORT tlv when the proposal is sent
RENDEZVOUS_TLV_TAGS_ADDR_LIST 0x0018 Array of string08 List of "IP port" pairs to try
RENDEZVOUS_TLV_TAGS_SESSION_ID 0x0019 string Identifier for session
RENDEZVOUS_TLV_TAGS_ROLLOVER_ID 0x001A string Identifier of session to rollover
RENDEZVOUS_TLV_TAGS_SERVICE_DATA 0x2711 blob Service specific data
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/OSCAR/Services/Rendezvous&oldid=8642"